- 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
studio - Tcl Bean method invocation package for Java Studio.
studio::port portType varName ?options?
studio::bind varName script
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.
- 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.
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.
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.
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.
# 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
}
studio::custom, java
studio, ports, trace, Java Beans, Java Studio
Copyright © 1997-1998 by Sun Microsystems, Inc.
Copyright © 1995-1997 Roger E. Critchlow Jr.