# Java Notes

## Contents

glossary | component options | menu options | code generation | misc. |

## Glossary

Tk and java use different names for, well, just about everything. In many cases, the Tk names are used. This section maps the Tk names into their java equivalents.

- Generic terminology
- widget -> component
- geometry -> layout
- Component names
- label -> Label
- entry -> TextField
- text -> TextArea
- button -> Button
- scrollbar -> Scrollbar
- frame -> Panel
- checkbutton -> Checkbox
- radiobutton -> Checkbox
- menubutton -> Choice
- listbox -> List
- canvas -> Canvas
- frame -> panel
- Option names
- command -> action
- pad -> inset

## Java specific component options

Checkbox (radiobutton) Groups
  In java, check-boxes are turned into radio-buttons by associating a check-box group to them. In SpecJava, the `variable` option on the property sheet for radio buttons controls which group the button belongs to. The easyest way to make a group of radio buttons is to create the first one, set its `variable`, and then copy it using shift-drag.
Choice (menubutton) widgets
  The choices are input as a comma-separated list in the `items` option. The label (`text` option) also appears as a choice if specified.

Several options on the component property sheets have special meaning to java. They are:

action
  A valid java statement should be entered here. Typically this is a method invocation, either from a method inherited in the current class, a static method, such as `System.out.println()`, or a method of the `arg` instance variable, such as `arg.foo()`. The local variable `event` of type `Event` is available as an argument, as are all of the user interface objects.
item_name
  This is used as the name of the java instance for this user interface element. If the default value is used, the "#" is changed into a "_". This name will also be a public instance variable in the generated java code.
subclass
  This option is used to specify an alternate class for this user interface element. `Subclass` should be a subclass of the component used. Subclassing to change the behavior by overriding the `action` method will not work, the action option should be used instead. If the `subclass` option is of the form:
  `subclass.method(args)`
  then right after the object is created (of type `subclass`), the `method` method is called with the arguments indicated, permitting subclass specific initialization to occur.

## Accessing the Java additions to the SpecTcl user interface

These java specific functions have been added to the menus:

java
  on the command menu, takes java code (in `$Current(project).java`) generated from the saved user interface specification, currently `$Current(project).jui`, compiles it (with javac) and runs the interface in test mode. If the file `$Current(project).html` exists in the current directory, the user interface will be tested by calling the applet viewer. Otherwise, it will be run as a standalone application.

  The name of the user interface, as indicated on the title bar (e.g. `$Current(project)`), is used as the name of the class.

kill java
  on the command menu, terminates the current test application, if one is running. This only works on systems that support the kill command.
java...
  on the preferences menu, pops up a dialog box to specify the java code generation options of SpecTcl. These are used to control how the user interface is integrated into the rest of the java application (or applet). The preferences contain the following items:
  package (currently "$P(package)")
    The name of the java package this class will belong to. The default is the empty package.
  imports (currently "$P(imports)")
    The name of a package to import. This is mostly used when there is a `$Current(project).include.java` file in use.
  extends (currently "$P(extends)")
    The name of the class that this class will inherit from.
  implements (currently "$P(implements)")
    The name of the interface that the class will implement. This is useful when several different use interface panels need to be used from the same application.
  arg type (currently "$P(arg)")
    Each generated class contains a public instance variable called `arg`. This may be used as a reference to invoke methods from in the action fields of the user interface elements. The type of this variable is defined here. If you choose not to use it, or leave it blank, `Object` is used for the type.
java api
  on the help menu, allows access to the current java documentation. If this menu item is missing, then SpecJava was not installed properly, so the documentation could not be found. The current location is thought to be $doc_dir.
java notes
  This page, from the help menu.

## Generated code

The class generated by SpecTcl (e.g. `$Current(project)`) consists of the following public methods:

public Object[] getWidgets()
  This array contains the user interface element objects and checkbox groups.
public String[] getNames()
  This array contains the string names of the interface elements, as indicated on the `item_name` option of the property sheet. The order corresponds to the ordering in the `getWidgets` method.
public void init()
  This method instantiates the user interface. It will be called automatically if the class is run from a browser or applet viewer. The `super.init` method is called to allow application specific initialization to occur.
public boolean handleEvent(Event event)
  All of the behavior, as entered in the `action` property is dispatched from this method, which is overridden from the component class. For every event for which no action is defined, the `super.handleEvent` method is called, allowing for generic behaviors to be handled by the parent class.
public static void main(String[] args)
  This calls the `init` method, permitting the class to be run as a standalone application.

#### Instance variables and application specifics.

- Each of the user interface components is defined to be a public instance variable, and therefore accessible from within the `action` property.
- The variable `arg` is an application specific slot, whose type is determined from the `arg type` option of the property sheet, to make it easy to invoke methods from unrelated classes in the `action`property.

## Miscellaneous

- If the file `$Current(project).include.java` exists in the current directory, then the code is inserted directly into the generated java code. This technique, however, is discouraged.
- Application specific functionality may be added to SpecTcl by including Tcl commands in the file `$Current(project).rc`.
- Arbitrary strings may be associated with particular widgets, by adding new options to the widget property sheet, and making them available in the generated code as an array of strings, one per widget.

  As an example, suppose automated entry field validation is desired. An new property, called `check` can be added to every entry widget by placing the following code in the file `$Current(project).rc` file in the current directory.

  set P(other_items:entry) check.
  Then that property can be exported into the generated code with the line:
  set P(export) "check"
  where the value can be a list of exported properties. The generated code will have a public method called `check` which returns the array of strings containing the `check` option for every widget. The order of the strings is the same as returned by the `getNames` method of the generated class.

again