|
|
Spin is based on a few simple but powerful concepts. You build capsules in Spin by assembling objects called components. You build projects in Spin by grouping together capsules and related files.
The components in Spin are JavaBeans. The JavaBeans component architecture allows you to assemble applications and other programs from individual components. Until now, most software has been handcrafted, one application at a time. This is similar to the way machines were built prior to the industrial revolution. Each machine was built piece-by-piece, usually by hand. Even pieces as simple as nuts and bolts were made one-by-one, so if you lost a single screw, you had to build one to replace it.
The industrial revolution introduced the concept of standard parts, which allowed parts to be manufactured. Nowadays, whether you are building a car or a house, you use standard components whenever possible (e.g., nuts, bolts, fuel pumps, filters, hoses, etc. for an automobile, or nails, 2 by 4 lumber, doors, windows, etc. for a house). Likewise, a computer is built from standard parts, such as processors, disk drives, power supplies, keyboards, and expansion cards, which communicate using standard busses and connectors.
The same revolution is now taking place in software. Component architectures allow applications to be built from standard components. JavaBeans is not the first component architecture, but it is considered by many to be the simplest and most flexible. Other component architectures include CORBA, OpenDoc, and several Microsoft variations on the COM component architecture with names like OLE, ActiveX, OCX, and DNA. Although based on Java, JavaBeans can use any language, including C++ or assembly language. Other components, such as ActiveX and CORBA components, can be used with JavaBeans.
If a JavaBean is written in Java it will have the advantages of Java — in particular portability. If a JavaBean is written in another language, usually the JavaBean vendor will provide versions that run on each supported platform. For example, media libraries such as DirectX and QuickTime for Java are written for specific platforms, so if you use these components then you must ensure that there is a version for them for the platform(s) you are targeting.
Other JavaBeans may have specific hardware requirements. For example, a video input component may be designed to work with a specific kind of video camera, so a capsule built using this component must specify the kind of video camera that is required.
Component architectures allow tools to work together. The standardization of nuts and bolts in the industrial revolution allowed standard wrenches and screwdrivers to be developed. Likewise, Spin can be used with any tool that understands JavaBeans. You can create JavaBeans in any of a number of tools and bring them into Spin, and you can create JavaBeans in Spin and use them in other tools.
Unlike hardware, software can be trivially duplicated, which dramatically affects how software component architectures are used. For example, if you could instantly make a copy of an automobile for free, there would be no need to build new automobiles from the ground up from parts. It would be simpler and faster to duplicate an existing automobile, and then make any desired changes. When using a software component architecture, it is tempting to try to build lots of small universal components, expecting them to be reused. A better strategy is to build a complete solution (like a complete automobile), and design the components to be easily customizable or easily replaced, so that the solution can be customized to any specific need.
The main components in Spin are called actors; you cause actors to do things using behaviors. You group actors, behaviors, and other components together into capsules. To create anything you must have at least one capsule. Actors, behaviors, and capsules are the ABC's of Spin.
Spin comes supplied with a range of components, including actors and behaviors. The capsules you build (out of other components) are themselves components that you can reuse like any actor (in the same capsule or in other capsules). Alternatively, you can acquire components from third parties, you can build components using other authoring tools, or you can build components using standard programming tools (in Java or in other languages).
Continuing with the alphabet, Spin also has data and editors. Data items are variables that you can use to save values and other objects. Data values can be simple values like numbers and strings, or they can be more complex objects, including types that you define yourself.
Editors allow you to change the properties and contents of actors, behaviors, capsules, and data values. You use editors to build your application; they are not normally part of the finished application that the end user sees.
When you start Spin you will see a new project editor. To build anything useful you must create and use capsules. The New Capsule command from the File menu creates a new capsule and opens an editor for it. The default editor for a capsule is called an outline editor, because it shows the actors, behaviors, data, and other capsules inside a capsule as a hierarchical outline. There are other editors for capsules. For example, the layout editor lets you arrange actors in a capsule or a scene. The toybox editor lets you play with a capsule while you build it.
It will be possible to add new editors to Spin, including new capsule editors. For example, we anticipate building a wiring editor that will let you see the connections between actors and behaviors. Eventually, we expect that users will be able to add their own editors to Spin, to further customize Spin to a specific application.
When you build applications using Spin, you typically spend much of your time using one or more capsule editors to build capsules.
Actors in Spin are arbitrary JavaBeans. You can use the JavaBeans that come with Spin, or you can acquire JavaBeans from other sources, such as from the Internet. You can use any JavaBean as an actor in Spin, with no changes. Just remember that if you get JavaBeans from other sources that it is up to you to ensure that they do not contain bugs or malicious code that could crash Spin or possibly even harm your computer.
The Juggler component is an example of a JavaBean. This JavaBean was acquired from the Javasoft division of Sun Microsystems. Because it was acquired from a reputable source, we trust that it does not contain any damaging code.
JavaBeans all have methods that you can use to tell the JavaBean to do something. Many JavaBeans also generate events. Methods and events are described in the following two sections.
All JavaBeans -- and thus all actors in Spin -- have methods that you can invoke. Some methods are commands that tell a component to do something. For example, on the Juggler component there are methods called startJuggling and stopJuggling that tell the juggler to start and stop juggling. These two methods do not take any arguments.
Some methods allow you to inspect and change properties of components. For example, on the Juggler component there are two methods (getAnimationRate and setAnimationRate) that let you inspect and change the value of the AnimationRate property. For properties, Spin hides the individual get and set methods, and simply lets you inspect and change the values of properties.
When you bring an actor into Spin, you can invoke commands and edit properties by pointing at the component and holding down the right mouse button (on the Mac, hold down the command key on the keyboard while clicking the mouse button). Spin creates a menu that lets you edit any property. In the toybox view, you can also invoke any command that does not require any arguments. To invoke commands that take arguments you must use a behavior.
Many JavaBeans also generate events, especially those JavaBeans that are user interface components. Events are often generated when the user does something, such as clicking a mouse button or pressing a key on the keyboard. Or a timer JavaBean can generate an event when a specified amount of time has elapsed.
An event name consists of two parts. The first part is an event class, the second part is a specific event. For example, many components respond to mouse events. For mouse events, the event class is "Mouse" and the specific events are mouseClicked, mousePressed, mouseReleased, mouseEntered, and mouseExited.
Behaviors are used to make actors do things, to communicate with other actors, and to respond to user input. All behaviors have a stimulus and a response. This is similar to animal behaviors; for example, a human responds to a bright light by blinking. In Spin, the stimulus for all behaviors is an event. Different kinds of behaviors differ in how they respond to that stimulus.
There are several kinds of built-in behaviors in Spin, and you can add new behaviors (in several different ways). Built-in behaviors include actions, conditionals, group actions, scripts, timelines, and counters.
You can edit a behavior by selecting the behavior, and then choosing "Edit Selected Object" from the View menu. There are several alternative ways to edit a behavior -- you can select the behavior and then type Control-E on the keyboard (Command-E if you are on a Macintosh). Or you can just double click on the icon for the behavior to edit it. Also, when you select a behavior, a Behavior menu appears in the menu bar. This menu can also be accessed using the right mouse button on the PC (or by command clicking on the Macintosh). The Behavior menu contains an "Edit Behavior" command.
All behaviors are activated by an event. When you edit an event, the first field is "Activate On" -- this field specifies the event that will activate the behavior. To the right of this field is a right-pointing triangle that brings up a hierarchical menu containing all events that can be used to activate this behavior. This menu is divided into two parts. The top part contains three names: "actor", "parent", and "capsule". The bottom part contains the names of all the actors and behaviors in the capsule, plus the capsule itself (since a capsule can generate events).
Behaviors can be conditionally activated by changing the "Activate On" field to "Activate If". This adds a "If=" field to the stimulus. The conditional can be any Java expression that evaluates to true or false. When the activating event occurs, the behavior is only activated if the condition is true.
A single behavior can respond to more than one stimulus. To add additional stimuli, click on the large plus sign to the right of the word "Stimulus". When there is more than one stimulus, you can delete any one stimulus by clicking on the large minus sign to the left of it. If a behavior has multiple stimuli, the behavior is activated if any of the activating events are received.
The counter and timeline behaviors can run for a appreciable amount of time. These behaviors can also be deactivated. You do this by adding an additional stimulus, and changing that stimulus from "Activate On" to "Dectivate On". In addition, deactivation can be conditional.
The aliases "actor", "parent", and "capsule" are Spin features that help make behaviors more reusable. When you add a behavior to a capsule, it is either a child of an actor, a child of another behavior, or a child of the capsule. The name "parent" refers to the component (actor, behavior, or capsule) that is the parent of this behavior. The name "actor" refers to the closest ancestor that is either an actor or a capsule (not another behavior). For example, if an actor has a child that is a group behavior, and the group behavior has a child that is an action behavior, then for the action behavior "parent" refers to the group behavior, and "actor" refers to the actor. The name "capsule" refers to the capsule in which behavior using it resides.
Note that the names "parent", "actor", and "capsule" are just aliases for components that are also in the bottom half of the "Activate On:" menu for a behavior. By using "parent" or "actor" to specify what event invokes a behavior, you make it easier to reuse a behavior in another place, without having to manually change what component generates the event that invokes it.
The "actor" and "capsule" aliases are also found in other menus. For example, in the "Send To:" field of an action behavior.
Actions are the most common kind of behavior in Spin. When an action is activated by an event it responds by invoking a method on an actor. Thus, an action can be considered as a way to translate an event into an invocation of a method.
When you edit an action behavior, you will see three fields. The first field is "Activate On:", which specifies what event activates this behavior. The second field is "Send To:", which specifies what actor to invoke a method on. You can specify any actor in the current capsule, the current capsule itself, or the alias "actor". The third field is "Message:", which specifies the method to invoke on the specified actor. If this method takes any arguments, then additional fields will appear to let you specify these arguments.
If the method to be called takes any arguments, then a "Data:" field will be added. This field specifies the types of the arguments. In Java, it is common to use the same method name more than once, as long as each use takes different numbers or types of arguments. In this case, the "Data:" field will let you choose which method you want to use.
Finally, an additional field will be added for each argument needed. This has a button to its left, which can be pressed to switch between two forms for specifying arguments: "With:" and "With=". The "With:" form allows you to specify a constant value for the argument. The "With=" form allows you to enter an arbitrary Java expression for the argument.
When a conditional IfTest behavior is activated by an event, it evaluates an expression and generates a new event. If the expression is true, then the ifTrue event is generated. If the expression is false, then the ifFalse event is generated. Other behaviors can then be activated based on whether the expression was true or false.
An ActionGroup behavior is a convenient way to group a set of components together to form a single unit. When invoked by an event, an action group generates a new Behavior.activated event. Other behaviors can then be activated by the action group's Behavior.activated event.
A script behavior allows a script of arbitrary Java code to be invoked by an event. This script can call methods on Spin objects, generate events, or do anything else possible in Java.
A timeline behavior is able to modify the properties of actors over time, like a score. This is a very powerful behavior; indeed, popular authoring tools have been built using only the timeline metaphor. Unlike these tools, Spin allows a capsule to contain multiple timelines, and allows a timeline to control any property of an actor.
To use the timeline, you tell it which properties of which actors you want to control. You then "capture" the values of these properties at different times. If the property is numeric, you can "tween" between captured values, so the value changes smoothly over time.
When you are capturing values in the timeline using the toybox, it is important to differentiate between property changes to your capsule's model, and runtime changes. The toybox editor is powerful because it allows you to run your project while you are editing it, but remember that runtime values are not captured by a timeline behavior.
For example, if you have placed a "drag" behavior on an actor, there are two ways to move that actor around in the toybox. You can click on the actor and move it around (runtime changes, using the drag behavior), or you can click on its editing handle and move it around. Only the latter changes will be captured by the timeline behavior.
When activated by an event, a counter behavior starts counting, possibly with a time delay between counts.
When you first start Spin, it opens up an empty project editor. The project editor allows you to keep track of multiple files that are associated with a single project. It contains the menus: File, Edit, Project, and View. Many of these commands have keyboard shortcuts.
New Capsule -- creates a new capsule, and opens a capsule outline editor window for it.
New Project -- creates a new project, and opens a project window for it.
Open -- opens an existing project or capsule.
Close -- closes the current window.
Save -- saves the current project, or prompts for a file name first
if the project has not been saved before.
Save As -- prompts for a file name, and saves the current project.
SQL Connections -- opens a dialog allowing SQL connections to be managed. Only
enabled when the zat.sql beans are loaded.
Quit -- quits Spin, prompting for windows that need saving to be saved.
Cut -- disabled.
Copy -- disabled.
Paste -- disabled.
Delete -- removes the currently selected files from the project.
Preferences... -- opens the preferences dialog, allowing the following preference
tabs and fields that can be modified:
JDKDocsDirectory - allows you to specify a directory (in addition to Spin's docs directory) that the Get Info command uses to find documentation. The Button to the right of the text entry area opens a file dialog that you can use to choose a file within the directory you wish to designate.
Add File -- adds a file to the list of project files.
Remove File(s) -- removes the currently selected files from the project.
Hide/Show Full Path -- hides or shows the full path of the files in the project.
About Spin -- Shows the About Spin dialog. Click in the dialog to make it go away.
The outline editor for a capsule contains the menus: File, Edit, Insert, View, and Outline. Many commands in these menus have keyboard shortcuts. In addition, following Outline is a menu that changes according to the currently selected object. Initially this will be Capsule, but it can change to Actor or Behavior. The contents of this menu are identical to the pop-up menu available from the selected object.
You can drag and drop objects in the outline to reorganize them. Drag an object by dragging its icon onto another object. That object (along with all its children) will then become children of the new object. You can also drag to create a copy of what you are dragging, leaving the original alone. To do this hold down the control key (Windows) or the option key (Mac) while you drag.
The File menu contains the following commands:
New Capsule -- creates a new capsule and opens the capsule editor on it.
New Project -- lets you create a new project, and opens the associated project
window.
Open -- opens an existing capsule. You will use this command to open
the example projects.
Close -- closes the current window.
Save -- saves a capsule.
Save As -- saves the current capsule under a new name.
Save As Archive -- saves the current capsule under a new name with archive format. Archive format can be used identically to the Save As format. The difference is that archive format saves each actor description by separating the class of actor from its properties. This is potentially a safer format to use if you are expecting to be updating your beans a lot because it can get around difficulties encountered when serialization formats used by newer versions of a bean are incompatible with the old format. Any properties not compatible between old and new beans are ignored.
Save As Jar -- writes out a finished capsule into a jar file (Java archive) in a format specific to the type of capsule specified by capsule properties. This can be one of the following:
Save Behavior -- saves the selected behavior you have created. The saved behavior is usually a group behavior that is the root of a tree containing other behaviors and data components. This behavior is saved (as a JavaBean) into the "behaviors" subdirectory of the Spin installation directory.
Run -- precompiles all Java expressions and runs the current capsule,
as if you were running it as a standalone application (or as an
applet in a browser).
Print -- Prints the current outline window contents.
SQL Connections -- opens a dialog allowing SQL connections to be managed. Only
enabled when the zat.sql beans are loaded.
Quit -- quits the Spin application, first asking for windows to be
saved.
The Edit menu contains the Cut, Copy, Paste, Delete, and Preferences commands.
From the outline, Cut and Copy work with text if there is any selected, otherwise the whole outline item is cut or copied. You can copy and paste text and components between Spin windows, but not from or to the other applications (this is a current Java limitation, and will be removed in the future).
The Insert menu allows you to insert components into a capsule.
Capsule -- to insert a capsule as a child inside another capsule
Scene -- to insert a scene (a visual component used to group other
visual components). Note that by default, a capsule is associated
with an implicit scene, but you can add additional scenes to a
capsule.
Behavior -- this contains all the built-in behaviors for Spin.
User Behavior -- contains all the behaviors that were saved using the "Save
Behavior" command (in the File menu).
Data Item -- contains all the built-in data types that you can use in a
capsule.
AWT components -- contains Sun's Abstract Windowing Toolkit widgets, which can
be used as actors, though not all are totally user-friendly.
The final section contains an entry for each package found in files in the "beans" subdirectory when Spin is started. These are the actors you can use in capsules. If you have installed the Standard Beans (and you should have) this section initially contains four entries:
zat.display -- contains a number of useful visual actors.
zat.misc -- contains a number of useful non-visual actors.
zat.html -- contains actors useful to output html-formatted documents.
zat.sql - contains actors useful to connect with and manipulate database
content.
The View menu contains the following commands:
Open Toybox -- opens a toybox editor for this capsule.
Open Layout -- opens a layout editor either for a selected scene, or for
the implicit scene associated with a capsule.
Palettes -- opens separate palette windows, which you can use instead
of the insert menu to insert actors, behaviors, and data items
into a capsule.
Reveal Palettes -- brings the palette windows to the front, so they can be found
after being hidden by other windows.
Edit Selected Object -- used to edit an actor, behavior, capsule, or data object.
Opens the editor for that object. Double-clicking on an object
is usually a short-cut for this command.
Get Object Info - opens an Info window for the selected actor. The Info window
allows you to view Variables, Properties, Methods, and Events
along with the related Javadoc documentation (when available) for that actor.
About Spin -- Shows the About Spin dialog. Click in the dialog to make it
go away.
The Outline menu contains the following commands:
Collapse - collapses the selected outline item if it has children.
Expand - expands the selected outline item if it has children.
Up - moves the selected outline item up one among its siblings.
Down - moves the selected outline item down one among its siblings.
To Top - moves the selected outline item to the top of its siblings.
To Bottom - moves the selected outline item to the bottom of its siblings.
Activation events are those events that activate behaviors. They can be viewed on the left side of the outline to give an idea of the thread of control (i.e., which behaviors are activated) when a particular event occurs.
None - shows no activation event arrows on the left side of the outline.
To/From Selection - shows activation events that activate the selection or are
activated by the selection.
All - shows all activation events.
Action targets are those actors to which methods are sent. They can be viewed on the right side of the outline to give an idea of the thread of control (i.e., which actions send methods to which actors) when an action is activated.
None - shows no action target arrows on the right side of the outline.
To/From Selection - shows action targets that are sent from the selection or sent
to the selection.
All - shows all action targets.
These debugging facilities are presently enabled only when using servlets. Servlets are non-visual and benefit from additional capabilities to debug them.
Enable Debugging - enables debugging for the servlet displayed in the outline,
and opens the debugger window.
Add Breakpoint - adds the selected behavior to the list of breakpoints. Breakpoints
are displayed in the outline by a circle to the left of the associated
behavior.
Remove Breakpoint - removes the selected behavior from the list of breakpoints.
Remove All Breakpoints - clears all active breakpoints.
Add Watch Variable - adds the selected data item to the list of watch variables
and displays it in the debugger window. Each step in execution
of a servlet refreshes all the watch variables in the debugger
window.
Remove Watch Variable - removes the selected data item from the list of watch variables.
Remove All Watch Variables - clears all active watch variables.
The Capsule/Actor/Behavior menu appears in all capsule editors, and reflects the currently selected object when there is a single selection. The menu let's you edit attributes particular to the selection.
Edit Capsule - opens an outline editor for the selected capsule.
Edit Properties - opens the properties editor for the selected capsule:
Edit Behavior - opens the behavior in its own window for editing. If the behavior
is already open its window just comes to the front.
Delete - deletes the behavior from the capsule.
The Actor menu is the same as the pop-up menu available on an actor. It contains the following:
Edit-Custom - opens the custom editor provided by the Javabean for editing
the selected actor. Enabled only when a custom editor is provided.
This is the same editor you get when double-clicking on the actor,
or if no custom editor exists then you get the generic object editor instead.
Edit-Generic - opens the generic object editor which allows every property of the
selected actor to be edited.
Edit Name - allows the name of the selected actor to be edited.
Get Object Info - opens the Object Info window displaying information about the
Actor.
Delete - deletes the actor from the capsule.
Edit Property - displays a sub-menu of all the properties available to the
selected actor. Choosing one allows that property to be individually
edited.
Methods - in Toybox view only - shown at the end of the Actor menu with
parentheses. Choosing one of these methods executes the method
on the selected actor. Only methods that need no parameters are
shown.
The toybox editor is a powerful editor that lets you play with visual components within a capsule while you are constructing it. It also lets you manipulate visual objects visually. Only visual actors can be seen in the toybox view. If an actor does not have a visual component, then you must edit it in the outline view.
Each visual actor in the toybox view has an editing handle attached to its bottom. This editing handle can be hidden using the "Hide/Show Editor" command of the View menu of the toybox editor.
The editing handle consists of three parts. The first part contains icons representing any immediate children of this actor. If an actor has no children, then this part is empty, and is not shown. The second part of the editing handle is the name of the actor. You can edit this name by double clicking on it. The third part of the editing handle is a resize handle that lets you change the size of the actor. This is entirely equivalent to manually setting the "size" property of a component.
The editing handle also allows access to a pop-up menu, which is the same as the Actor menu described above.
You can also press and hold the mouse button in the name part of the editing handle to move the actor around the scene.
The menus in the toybox editor are the same as the menus in the outline editor, except for a few changes in the View menu, and, of course, no Outline menu.
Open Outline -- replaces the "Open Toybox" command.
Arrange -- used to move objects to the front or back of the visual hierarchy. This also changes the order of the objects in the outline view.
Hide/Show Editor -- used to hide the editing handles in the toybox view.
The toybox view lets you simultaneously play with a capsule while you are editing it. Unlike other authoring tools, there is no mode switch to change between edit mode and run mode. When you add a new component to a capsule it is instantly active, with no separate compile and run phases.
When a capsule is running, however, Spin must distinguish between permanent changes to a capsule and those changes that occur only because the capsule is running. For example, if I put a "drag" behavior on an actor, this lets me play with the actor by dragging it around, but I do not want these run-time changes to be made permanent. Instead, if I move the object by dragging its editing handle, then I do want those changes to be permanent.
The toybox view distinguishes between run-time changes (non-permanent) and edit-time changes (permanent) by differentiating between changes that are made by a behavior, and changes that are made directly by the user. For example, changes in an actor's position made by a "drag" behavior are not permanent because they are made by a behavior (even though the drag behavior utilizes user input).
You can drag and drop objects in the toybox to reorganize them. You can only drag child objects of any of the visuals. Drag an object by dragging its icon onto the name tab of another object. That object (along with all its children) will then become children of the new object.
You can also drag to create a copy of what you are dragging, leaving the original alone. To do this hold down the control key (Windows) or the option key (Mac) while you drag.
When testing an application through the toybox view, if an error occurs (usually caused by faulty Java code in a "With=" field of an action behavior, or within a Script), then an error window pops up with the error message. You can double click on the error message to have Spin take you to directly to the code that caused the error.
Spin also has a console window. On Windows this is provided as text output in a DOS window. On the Mac, this is provided in a window opened by MRJ. Some failures report only to the console. These might be problems in the tool itself, within a Javabean that you are using, or simply text output printed to System.out. If you need to report any errors in the operation of Spin, then often you will find messages printed in the console window that can help us to find the problem. Please include these messages if you are filing out a bug report.
To use the console window to help in debugging your application, you can create script behaviors that contain commands such as:
System.out.println("got here");
Then, when your script is activated you will see the "got here"
message output to the console.
Spin has built-in features that enable you to build, test, and debug Java servlets that you can then deploy on your Java-enabled Application Server.
To build a servlet you must first set your capsule type to Java servlet in the capsule properties. Now you can create behaviors that activate based on servlet messages.
The two most frequently used servlet activation messages are:
When you have set up a servlet you can test it using Spin's built-in web server. To do this you must first enable the built-in web server from the Edit->Preferences dialog.
The default port for the server is 90, but this can be changed via the Edit->Preferences command. Access the servlet from any web browser using the URL http://localhost:90. A web page appears describing the request parameters, and listing all the servlets currently open in Spin. If your servlet has a file name, then that name is listed. If your servlet has not yet been saved then the name of its capsule is listed. You can test a GET request by following the named link, or a POST request by filling out parameters for the servlet as name/value pairs.
Note that the built-in web server will also resolve URLs that it cannot identify as servlets. It indirects these through a URL or directory that you can change from the preferences. This location is a good place to keep html source or images that you servlets need to operate.
A single-step debugger is provided to allow you to trace through and view variables in your servlet as it is executing. The debugger presently only works with servlets, but will be augmentated in time. To use the debugger choose Enable Debugging from the Outline menu prior to executing your servlet via a browser.
Spin allows quite a bit of flexibility in how components are arranged in the hierarchy shown in the outline view. In particular, a behavior does not necessarily need to be a child of an actor it is affecting. The outline hierarchy is used for the following:
A Javabean is a Java class or object that defines specific properties, methods and events that control it. Defining capsule properties is the means by which new Javabeans can be created from your capsules. Once these capsule properties are defined, you can save your capsule as a jar, which precompiles it in a form that allows it to be used as a Javabean component.
You can create new properties which are seen as Javabean properties when your capsule is saved to a jar file. To do this, you just need to name them, and specify their bindings. The names you use should not already be used by the type of capsule you have created, otherwise there can be unpredictable results. From the Capsule properties dialog, select the Properties tag, and name each method by using the Add button. Once a property has been added, select it and click the Set Binding button to define how the property is to be resolved. The Set Binding dialog allows you to choose a data item, or a property from an actor to be used for the chosen property.
When used as a Javabean your capsule will have set and get methods for every property you define. In addition, whenever one of your defined properties is set (i.e. its set method is called) the event WhenCapsule.propertySet is generated by your capsule. This event can be used to take internal action when a property is changed.
You can name new methods so that your capsule, when saved as a bean, can respond to them. To do this choose Add... from the Methods tab panel in the Capsule Properties dialog. You are presented with a dialog for entering your method specification. Name the method by entering a name in the Activate On: field. If your method has no arguments then close this dialog. You are done. If you wish to add arguments to your method, then click the +Argument button. In the Arg: field, name your argument. The argument names must be different for each argument of a single method. These names are used when you write an action to respond to a method call from within your capsule. In the Type: field choose a type from the menu. Presently Spin allows only a restricted set of argument types. Add more, or remove arguments as desired.
To respond to a method call from within your capsule you must activate on the method from within a behavior. The events are generated by the capsule itself in the category Capsule, which lists all of your methods. Any expressions or scripted Java within the behavior may use the named arguments of the method directly. The With= popup menu for an action behavior shows those arguments of an activating method when the types are appropriate.
You can send a capsule method from within the capsule that declares it through the use of an action behavior or a script.
Events can be generated by a capsule when saved as a bean. Events are used by a Javabean to signal changes or other things to the user of the bean. Events are defined from the Events tab panel in the Capsule Properties dialog. The editing interface is the same as for methods. You get to name your events, and define their parameters. Defining an event will generate the appropriate listener code, and event objects with your Javabean.
For example, consider an event named Done, with a parameter named When. Code generated when the capsule is saved as a jar will include addDoneListener(DoneListener), and removeDoneListener(DoneListener) along with a DoneEvent class with a getWhen method.
Defining an event is useless unless you cause the event to be sent. To send an event from your capsule you must send it through the use of an Action behavior. The action must send to the capsule a method named the same as your event. Arguments must also be entered if your event requires them. Sending this method will generate your event and send it to listeners of the event.
Note that since events and methods use a similar mechanism, you should use event and method names that are different. Event methods are not made available to users of your capsule Javabean.
Capsule embedding is mostly useful for creating visual objects that require duplication, or for dynamic loading.
Within Spin an individual object cannot be duplicated. However, it is possible to duplicate an object by placing it within a capsule because capsules contain support for duplication, termed cloning. The cloning example shipped with Spin shows how this facility can be used: it embeds a capsule containing a ball within another capsule. The ball bounces whenever its capsule is cloned.
A capsule when embedded within another has its visuals displayed within the containing capsule, which is why the ball in the example shows at all. Notice that if you edit the Scene of the topmost capsule that you never see the ball in the editor. Graphic editors do not presently cross the bounds of capsules contained or otherwise.
A capsule is duplicated by sending it the message makeClone from a behavior.
When a capsule is cloned the new clone will generate the event WhenCapsule.isNewClone. Note that only the new capsule will receive this event. It can use it do to any special setup required when it is created. The capsule originally sent the makeClone message generates the event WhenCapsule.cloned.
Cloning specifically is a run-time only feature of Spin. Cloning doesn't work from the Toybox view, and makeClone generates an error from the toybox if you try it.
A capsule, once it has been saved as a jar file can be dynamically loaded by another capsule. In order to do this, you should insert a placeholder capsule that has no contents into the capsule that wishes to do the loading. When you send the message loadFromURL to the placeholder capsule, it will be replaced by a new capsule loaded from the URL specified. The URL most be fully qualified. A capsule when loaded has its visual components incorporated into those of the parent capsule.
A Scene is a built-in actor that is a subclass of java.awt.Container. Specifically it is a lightweight container component that has the following attributes:
Scenes support the following specific messages:
Scenes support the following specific properties:
Scenes generate the following events:
getComponent1() and getComponent2() messages on the generated event return the components that collided.
If more than two components collide at once, then several Collision.hit messages are generated to accomodate all the collisions between
every pair of colliding components.
The Frame component differs slightly in usage compared to other
components. In particular a Frame cannot be embedded in another
component, but is designed to contain components, and be displayed
as a window in its own right. You can experiment with Frame from
the outline editor. Setting a Frame's Visible property to true
will actually make the Frame appear as a window on the screen even though
in this mode it cannot be used at all. If you use a Frame, then
one of the things you will probably want to do is have it not
be visible within your capsule, and add a behavior to make it
visible when the capsule is started. Always use the Layout editor
on a Frame to edit its contents. You will probably also want to
detect when a frame is closed. Events generated by a frame allow
you to do this, along with a number of other things. Frame is
not well-integrated into the Spin environment, and is really provided
for advanced users.
The Spin Tutorial walks you through several Spin projects, step-by-step.
Spin is designed to work seamlessly with components (JavaBeans) developed by other tools. Thus, to keep Spin as seamless as possible, we have kept our terminology as compatible as possible to that used by JavaBeans and by existing components as much as possible. This glossary covers both terms that Spin uses from JavaBeans and terminology that is uniquely Spin's.
Under construction.