NAME

studio::custom - Scripting a Java Studio Customizer with the Tcl Bean.

SYNOPSIS

studio::custom getPanel

studio::custom commitScript callbackScript

studio::custom getBeanData

DESCRIPTION

COMMANDS

studio::custom getPanel

studio::custom commitScript callbackScript

studio::custom getBeanData

EXAMPLE

SEE ALSO

KEYWORDS

NAME

SYNOPSIS

DESCRIPTION

The Customizer for all Tcl Beans, default or user defined, consists of two components. The first component in every Tcl Bean Customizer is an interface for loading Tcl scripts from the local file system. The second component in every Tcl Bean Customizer is a Choice Box for selecting from a list of scripts contained in the Tcl Bean jar file. The default Customizer displays the contents of the Tcl script for the Tcl Bean. If the Customizer is defined by the Tcl script, the component that displays the contents of the Tcl script is replaced with the user defined Customizer.

Every time a script is loaded into the Tcl Bean (from the local file system or selecting a built-in script), the Tcl Bean examines the contents of the script. If the script does not begin with #CUSTOM_BEGIN, a default Customizer is constructed and the contents of the file are displayed. Otherwise, the file is considered to contain a user-defined Customizer, and the Tcl Bean parses the file into two separate scripts based on the following file format:

#CUSTOM_BEGIN
<customizerScript>
#CUSTOM_END
<beanScript>

The Customizer is re-initialized by a new interp each time it is displayed. The runtime state of the widget (e.g. text entered into an Entry component) must be preserved so it is not lost when the Customizer is destroyed. All of the Customizer's state, referred to as beanData, is stored in the Tcl Bean. The beanData is also used to define Tcl Bean properties and must be passed from the customizerScript's interp to the beanScript's interp. The commitScript and getBeanData sub commands store, retrieve and pass beanData between interps and the Tcl Bean.

The Customizer initialization phase begins whenever Java Studio requests a new Customizer be displayed. The phase starts by creating a new interp and evaluating the customizerScript. Every customizerScript must perform the following steps to properly initialize the Customizer:

[1]

The Customizer's graphical interface must be defined. Use the studio::custom getPanel command and the java package, to create the interface.

[2]

The customizerScript must register a callbackScript. The callbackScript defines how to preserve the Customizer state and store data needed by the beanScript. The result of evaluating callbackScript is stored in beanData. Use the studio::custom commitScript command to register the callbackScript.

[3]

Retrieve the beanData and restore the state of the Customizer. If the Customizer was previously displayed, then beanData may contain information on the state of the Customizer before it was destroyed. The content of beanData will be reflected in the Customizer. Use the studio::custom getBeanData to retrieve beanData.

The Customizer commit phase starts whenever the Customizer's 'OK' or 'Apply' buttons are pressed. The Customizer commit phase performs the following tasks:

[1]

Evaluate the callbackScript, defined by the command studio::custom commitScript, in the customizerScript's interp. The callbackScript is evaluated at the global scope, and has access to all of the state defined when the customizerScript was evaluated.

[2]

Store the result of evaluating the callbackScript in the Tcl Bean's beanData. At this point, the customizerScript's interp stops running, and the Customizer disappears.

[3]

Create a new interp, and evaluate the beanScript. The beanScript should call the studio::custom getBeanData command to retrieve the data from the Tcl Bean. After this step, the Tcl Bean is initialized according to the beanScript and the beanData.

COMMANDS

studio::custom getPanel

Return the Java object handle for the AWT Panel component contained in the Customizer window. Components packed into this Panel create the Customizer's graphical interface. When the Customizer window is removed, the Panel and all of its sub-components are destroyed. The persistent state of each component must be preserved, to restore the interface the next time the Customizer is displayed. Use the studio::custom commitScript command to preserve the state and the studio::custom getBeanData command to retrieve the state.

studio::custom commitScript callbackScript

Specifies the callbackScript that should be invoked when the Customizer commit phase begins. The return value of callbackScript is stored in the Tcl Bean, and can be retrieved by using the studio::custom getBeanData command. The callbackScript is evaluated in the customScript's interpreter, and is evaluated at the global scope. In general the callbackScript should perform the following steps:

[1]

Extract persistent data from the Customizer's Panel in order to restore the interface to its identical state (e.g. The Text of an Entry component.)

[2]

Gather information needed by the bean script.

[3]

Marshall all of the above data into an ordered Tcl list so the data can be used to re-initialize the Customizer, or be used to set Tcl Bean properties.

[4]

Return the ordered list from step 3.

studio::custom getBeanData

This option returns Customizer data contained in the Tcl Bean. The data consists of the return value of the script that was defined by the callbackScript option. If the Tcl Bean does not have any data stored when this command is called, an empty string is returned. This command should be used in the custom script to retrieve data needed to restore the Customizer to its previous state. The bean script should call this command to retrieve the information from the Customizer.

EXAMPLE

#CUSTOM_BEGIN

# Get the panel to pack the components into.

set customPanel [studio::custom getPanel]

# Get any data that may have been previously set.
# If there is no data, customData is ""

set customData  [studio::custom getBeanData]

# Create two Java AWT components that make the 
# custom interface.

set scriptLabel [java::new {java.awt.Label String} "Script:"]
set scriptArea  [java::new {java.awt.TextArea int int} 10 40]

# If customData is not an empty string, we 
# have defined it to contain a script.  Put
# the script back into the scriptArea.
 
if {$customData != ""} {
    $scriptArea setText $customData
}

# Add the components to the Customizer.

$customPanel {add java.awt.Component} $scriptLabel
$customPanel {add java.awt.Component} $scriptArea

# Define the callback that marshalls data into 
# the Tcl Bean.  The return value of the script
# becomes the return value of calls to 
# studio::custom getBeanData

studio::custom commitScript {
    set data [$scriptArea getText]
    return $data
}
#CUSTOM_END

# Get the data set by the studio::custom callbackScript 
# command.  For this example, the data is a script
# to be evaluated.

set beanData [studio::custom getBeanData]
eval $beanData

SEE ALSO

KEYWORDS

Copyright © 1997-1998 by Sun Microsystems, Inc.
Copyright © 1995-1997 Roger E. Critchlow Jr.