Introduction

Introduction

Plug-ins are Java-based extensions to DLSim 3's primitive element set. Plug-ins can add considerable functionality to a DLSim 3 circuit, and because they may contain any Java Swing control, they can be highly interactive.

Plug-in design is simplified by a powerful API that takes care of much of the gory detail. This document will show you how to build a rich set of plug-ins with which you can construct interesting and educationally powerful DLSim 3 examples.

We assume you are familiar with Java programming and DLSim 3 operation. (For the latter see the DLSim 3 Users Guide.) Before attempting to write your own plug-ins, we suggest that you familiarize youself with the plug-ins supplied in the DLSim 3 distribution.

Overview

Plug-ins resemble DLSim 3 abstract circuits (e.g. cards and chips) but are capable of much greater functionality and expressiveness since they are written in Java. A plug-in is constructed as an extension to the DLPlugIn class. Plug-ins may have their own customized "view", or use the default "purple box" view. Customized views may have a user-defined polygonal shape and pin configuration. The default view uses the standard pin configuration and is limited to at most displaying a row of numerical LEDs.

Features

Among the other features of the plug-in API are:

Info description
A brief description of the plug-in can be specified, to be included in the menu item for that plug-in.
Pin maps
Pins may be collected into multipin bundles determined by a map array. This map can be altered dynamically.
I/O support
The API provides methods for multibit integer I/O.
LED support
The API provides methods for numerical data display.
Actions
User-defined actions handled by the plug-in object can be added to the plug-in's Action Menu.
Properties
User-defined properties/property values are saved in the XML description of any circuit including the plug-in instance, providing persistent startup state.

Libraries

A plug-in library consists of a set of related plug-ins distributed together in a Java JAR archive. This archive must have one of the following filenames: Plugins.jar, Plugins0.jar, Plugins1.jar, ... Plugins9.jar. Any such archives residing in the same directory as the DLSim 3 archive DLSim3.jar (we'll call it the home directory) will be loaded when DLSim 3 is launched. When one or more plug-in library is loaded the Elements | Add Plug-in menu and toolbar items are activated, permitting elements from the libraries to be added to the circuit board.

Hierarchy

The plug-in menu uses a hierarchical structure that reflects the package directory structure of the plug-in classes. The user describes this structure in a properties file called dlsim.prop, which may either be included in the META-INF subdirectory of the corresponding plugins?.jar archive, or in the home directory. When several such property files exist they are stitched together.

The base plug-in directory is specified in this file, as is the rest of the directory structure. For example, suppose we specify the base plugin directory as plugins, and we include the plug-in whose java package/path is given by plugins.components.Register. The result will be a plug-in entry for Register in a submenu entry for components. Further details of the plug-in environment are given in a the Environment section.

Software Development Kit

To facilitate plug-in development we've distributed a software development kit (SDK) in the form of an Apache "ant" environment. With modifications this should be sufficient to manage plug-in development projects. It is described in detail in the SDK section. The SDK distribution contains all of the examples discussed in this document.

The Rest of This Document

Frequently Asked Questions
To help you get started.

Plug-in Architecture
A description of the document-view architecture used by plug-ins. Details regarding document and custom view design.

API Reference
Constructors and API methods used by plug-in documents and views.

Plug-in Environment
Creating and loading plug-in libraries. Configuring libraries using dlsim.prop.

Software Development Kit
Compiling plug-ins directly, or using the Ant build script supplied by the SDK.

A Plug-in Tutorial
A series of progressive examples that demonstrate the various facets of plug-in writing.