  NAME
    studio - Tcl Bean method invocation package for Java Studio.
  SYNOPSIS
    studio::port portType varName ?options?
    studio::bind varName script
  DESCRIPTION
  COMMANDS
    studio::port portType varName ?options?
      -portname name
      -transfer messageType
        In ports:
        Out ports:
        Twoway ports:
      -location locStr
      -description descStr
    studio::bind varName ?script?
  TRANSFER TYPES
    doubleToBasic (Out)
    floatToBasic (Out)
    integerToBasic (Out)
    longToBasic (Out)
    booleanToBasic (Out)
    stringToBasic (Out)
    basicTo<suffix> (In)
    numberTo<suffix> (In)
    trigger (In)
    object (In or Out)
    dynamic (In or Out)
  LOCATION OPTIONS
  TRACES
  EXAMPLE
  SEE ALSO
  KEYWORDS

### NAME

studio - Tcl Bean method invocation package for Java Studio.

### SYNOPSIS

studio::port portType varName ?options?
studio::bind varName script

### DESCRIPTION

The studio package provides an interface to access Java Studio functionality 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 uses "ports" to graphically represent Java Bean events. Ports send events, called "messages", to another port that has been "wired" together in the Java Studio Design Environment. The Tcl Bean is a Java Bean built for Java Studio, and uses the studio package to create ports and generate messages.

Three types of ports can be created in Java Studio. "Out ports" are responsible for sending messages to other components. "In ports" receive the messages and perform actions defined by the component creator or user. "Twoway ports" combine the functionality of In ports and Out ports. In the rest of this document, the term "In port" refers to any port that can receive messages; that is, both a Twoway port and an In port. Similarly, "Out port" refers to both Twoway ports and Out ports.

The Tcl Bean binds the sending and receiving of messages to Java Studio ports via the Tcl trace facility. Every port created with the studio package has a Tcl variable, varName, associated with it. Traces are placed on varName that evaluate scripts or send messages whenever the variable's value is set. See the section on TRACES for more detail.

### COMMANDS

studio::port portType varName ?options?
  Create a Java Studio port of type portType to be accessed by the variable varName. PortType must be one of the following values: in, out or twoway. Out ports automatically send a message whenever varName is written. The value of the message sent is the value of varName. In ports do not implicitly respond to the message they receive like Out ports. They must be bound to a Tcl script using the studio::bind command. The value of the message received by an In port is stored in varName.

  A Twoway port has the combined functionality of an In and Out port. The varName argument must be a Tcl list containing two variable names: {inVarName outVarName}. InVarName accesses the In port, and outVarName accesses the Out port. A message will be sent out the port whenever outVarName is written. To bind the Twoway port to a script, pass inVarName as the varName argument to the studio::bind command.

  One or more of the following options may be set to override the default settings:

  -portname name
    Specify the name of the port that appears as the label for the port in the Design Window. For In and Out ports the default portname is identical to the varName. For Twoway ports the default value is the first variable name in the varName list.

  -transfer messageType
    Specify the messageType of message to send or accept. The default option is dynamic for any portType. See the section on TRANSFER TYPES for more detail on the semantics each type. The valid messageTypes for each port are as followed:

    In ports:
      basicToDouble, basicToFloat, basicToInteger, basicToLong, basicToString, basicToBoolean, numberToDouble, numberToFloat, numberToInteger, numberToLong, dynamic, object, or trigger.

    Out ports:
      doubleToBasic, floatToBasic, integerToBasic, longToBasic, stringToBasic, booleanToBasic, dynamic, object or trigger.

    Twoway ports:
      The messageType must be a Tcl list of two elements: {inMessageType outMessageType}. InMessageType takes any In port options, and outMessageType takes any Out port options.

  -location locStr
    Specify the location of the port on the icon representing the Java Studio Bean. The default location for an In port is west, an Out port is east and a Twoway port is north. See the section on LOCATION OPTIONS for a list of valid locations.

  -description descStr
    Specify an internal description of the Java Studio port. If two or more ports have identical parts, this option distinguishes the ports without altering their appearance or behavior.

  A port created by the Tcl Bean is uniquely identified by the sum of all its parts: portType, varName, portname, transfer, location and description. As long as one of the parts is different, one port can be distinguished from another. In some situations, it is desirable to have two or more ports with identical behavior and appearance. The description option allows the ports to remain unique. The value of description does not affect the behavior or appearance of the port. If the user attempts to create a port that is identical to an existing port, an error is generated and the port is not created.

studio::bind varName ?script?
  The studio::bind command is used to associate a Tcl script with the reception of a message by a Java Studio In port. The varName argument is the Tcl variable assigned to one or more ports. When a message is received by a port, varName is set to the value of the message and the script is evaluated in the interpreter associated with the Tcl Bean. See the TRACES section for more detail on how messages are generated.

  If the script argument is not passed, the command returns the existing script bound to varName, or an empty string if no script is bound. If the studio::bind command is called with the script argument, and varName is already bound to another script, the new script replaces the old script.

### TRANSFER TYPES

All messages are sent and received as Java Objects. When a user connects two ports, Java Studio must determine if the data type of the message sent is accepted by the receiving port. The messageType for an Out port specifies an ordered list of data types that can be sent, based on the original data type of the message. The messageType for an In port specifies an ordered list of data types that can be received, and how to convert the message to a single data type. If a common data type is found between an In port and Out port, a connection is made. Below is a description of each messageType, and what portType it may be used with:

  doubleToBasic (Out)
    Converts a Double to the first match of the following options: Double, Float, Integer, Long or String.

  floatToBasic (Out)
    Converts a Float to the first match of the following options: Float, Double, Integer, Long or String.

  integerToBasic (Out)
    Converts an Integer to the first match of the following options: Integer, Long, Float, Double or String.

  longToBasic (Out)
    Converts a Long to the first match of the following options: Long, Integer, Float, Double or String.

  booleanToBasic (Out)
    Converts a Boolean to the first match of the following options: Boolean, String, Integer, Long, Float, Double or String

  stringToBasic (Out)
    Converts a String to the first match of the following options: String, Integer, Long, Float or Double.

  basicTo<suffix> (In)
    Converts a Double, Float, Integer, Long or String to the suffix type. Valid suffix types are: Double, Float, Integer, Long, String or Boolean. A Boolean object is only accepted if the suffix is Boolean.

  numberTo<suffix> (In)
    Converts a Double, Float, Integer or Long to the suffix type. Valid suffix types are: Double, Float, Integer or Long.

  trigger (In)
    Receive a VJTriggerObject, Object or String. The trigger object is used to simply cause an event to occur.

  object (In or Out)
    Send or receive a Java Object without any conversion.

  dynamic (In or Out)
    All of the previous options specify the data type at design time. This option does not specify a data type and defers the validation process to runtime. Connections to this type are always accepted during design time and leave the conversion up to the Java Bean implementation.

### LOCATION OPTIONS

The valid location options are: anywhere, north, northLeft, northCenter, northRight, south, southLeft, southCenter, southRight, west, westTop, westCenter, westBottom, east, eastTop, eastCenter, or eastBottom.

The anywhere option places ports in the least populated side, which may change as ports with sides specified are added to the component. Currently, this behavior is not documented by Java Studio, and may change in the future.

### TRACES

Putting a trace on a variable causes a Tcl command to be evaluated whenever a variable is read, written or unset. Ports created by the Tcl Bean use the Tcl trace command to control the flow of messages through ports. Out ports create a trace on varName automatically when the port is created. When the Out port's varName is set, a message is generated with the new value of this variable. If two or more Out ports use the same varName, then a message is sent to every port associated with varName. When an In port is created, no traces are automatically put on varName. Rather, traces are placed on the port explicitly by using the studio::bind command.

Note: You can also set variable traces on ports using the Tcl trace command. The studio::bind command is just a simplier interface. To learn more about the trace command, see the Tcl documentation.

### EXAMPLE

    # Create an In port called foo.  Notice that all of the options are
    # unnecessary because they are identical to the defaults.

    studio::port in foo \
    	-location west \
    	-transfer dynamic \
    	-portname foo

    # Create a Twoway port called twoWayPort.  Here all of the options are
    # necessary because they override the defaults.

    studio::port twoway {inBar outBar} \
    	-location northRight \
    	-transfer {basicToString stringToBasic} \
    	-portname twoWayPort

    # Create the binding of the In port (foo) to the Out port (outBar).
    # In this example, the varName for the Out port is set with the
    # String representation of any Java object that is sent to the
    # In port.

    studio::bind foo {
        global inBar
        set inBar [$foo toString]
    }

    # Create a similar binding on the In port of the Twoway port.

    studio::bind inBar {
        global outBar
        set outBar ${inBar}PlusMoreData
    }

### SEE ALSO

studio::custom, java

### KEYWORDS

studio, ports, trace, Java Beans, Java Studio

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