  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

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

### SYNOPSIS

studio::custom getPanel
studio::custom commitScript callbackScript
studio::custom getBeanData

### DESCRIPTION

The studio::custom command provides the interface to create a Java Studio Customizer from the Tcl Bean. Java Studio is a graphical development environment for gluing together Java Beans in order to create applets, applications or other compound Java Beans. Java Studio creates a graphical interface, called a Customizer, to manipulate Java Bean properties. Every Tcl Bean contains a default Customizer that displays the contents of the Tcl script. However, the studio::custom command and the java package provide the interface to override the default Customizer and define a Customizer from Tcl.

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 customizerScript and beanScript are distinct scripts evaluated in separate interpreters and share no common data. The Tcl Bean stores a copy of both scripts, and evaluates them when needed. The customizerScript's primary function is to the define the Customizer. Every time Java Studio requests that the Tcl Bean Customizer be displayed, a new interpreter is created and the customizerScript is evaluated. The beanScript's primary function is to initialize the Tcl Bean by creating Java Studio ports and defining the bindings on the ports. Every time the Customizer commit phase begins (described below),the beanScript is evaluated in a new interp. See the studio man page for more information on writing the 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

studio, java

### KEYWORDS

Java Beans, Java Studio, Customizer, studio

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