|
Introduction
This document lists each
of the "jsi" include files that can be used by Progress procedures to send
various commands to a client application (app). There are commands available
for a wide variety of purposes, including:
- creating a new container or
component object and assigning its constraints and attributes (properties)
- assigning or changing the displayed
value in a component such as a textfield, textarea or table cell
- selecting ("checking") or unselecting
a radio button or checkbox
- making a container or component
visible or hidden
- making a component enabled or
disabled for receiving user input and focus
- assigning or changing a component's
tooltip (floating help message)
- assigning or changing an object's
title, caption or image
- adding or selecting a specific
value in a combobox or listbox
- adding or changing the value
of a table row or individual cell
- bringing a specific panel to
the "top" in a cardpanel or tabpanel
- inserting, removing, expanding,
collapsing, selecting and setting attributes on nodes in a tree
In addition, two powerful utility
methods
allow a host procedure to make use of all methods and tasklists available
in a client app:
- invoke any client method on
any object in the client app
- invoke any existing tasklist
in a client app
Finally, several methods are
available to start and end a "state-aware" session, which dedicates
a Progress Webspeed agent or AppServer process to one client and maintains
its "state" (value of working variables, temp-tables, etc.) between interactions
with that client. Related methods are used to start, commit, undo and retry
transactions
within a state-aware session.
These include files are referenced
using the normal Progress "include file reference" syntax, with
enclosing brace characters containing the name of the include file and
zero or more name/value pairs for any required arguments.
For example, to display the
value of the database field "customer.name" in a client textfield whose
object name is "tName", an include file reference with two arguments is
used:
{jsi/textfield/settext.i &name='tName' &val=customer.name
}
Another example disables a button
whose object name is "bDelete" so that it cannot be clicked or receive
focus:
{jsi/component/setenabled.i &name='bDelete' &b='false'
}
If the value used for a parameter
is a variable name, database field name, temp-table field
name or a Progress function (string, substring, etc.) then it is
not quoted, like the customer.name value in the first example.
When a literal value is
used for a parameter, it must be enclosed in single quotes, like
the 'false' value in the second example. If the literal value contains
embedded
spaces, such as a multi-word message, then there should also be a set
of double quotes outside the single quotes. This example will send
an error message in a warning box when no customer record is available:
{jsi/msgbox/warning.i &component='fMain'
&msg="'No customer record was found.'" }
Note that the message box example
could also use a variable, which can allow more streamlined coding. For
example:
define variable vMsg as character.
find customer where customer.cust-num = tCustNum exclusive-lock
no-wait no-error.
if not available customer then do:
if locked customer
then vMsg = "That customer record
is locked.".
else vMsg = "No such customer record
was found.".
{jsi/msgbox/warning.i &component='fMain'
&msg=vMsg }
end.
else
{jsi/textfield/settext.i &name='tName' &val=customer.name
}
Most include files have at least
one required argument, the "object name" which names
a container or component object to which the method will be applied. These
names are case-sensitive, meaning that upper and lower case must
exactly match the name used in Jargon Writer for this object. This means
that 'TName' and 'tName' cannot be used interchangeably to reference
the same client object. This rule is different than the syntax used in
the Progress language itself, and can be the cause of numerous errors if
not carefully followed.
Utility Methods
jsi/invoke.i
This method is used to invoke
any valid client method on any object within the currently executing app.
The methods that can be invoked are the same ones used when adding tasks
in the Jargon Writer Task Editor
Window. This powerful method allows a host procedure full access to
any client method for which a specific "convenience" include file has not
already been defined in the jsi library. However, the syntax of these commands
requires more knowledge of the required parameters of a method, which can
be seen in the API help documents.
- &object - The internal
name used in the client app for the object on which a method will be invoked.
- &method - The name
of the method to be invoked on the object.
- &typelist - A delimiter-separated
list of data types for required parameters of the method. Data types are
specified as: boolean, int or String. (These are Java and C++ data types,
not Progress data types. Use upper/lower case as shown).
- &vallist - A delimiter-separated
list of values for each parameter. Note that values cannot contain the
delimiter character.
- &delim - The delimiter
used to separate entries in the typelist and vallist parameters. The default
is a comma.
jsi/invoketasklist.i
This method is used to instruct
the client to execute an existing tasklist in a specific app. The tasklist
can contain any valid list of tasks, and is executed just as if it were
linked to a client event which had just taken place.
- &appname - The name
of the client app (without the ".xml" suffix) in which a tasklist is to
be invoked.
- &tasklistname - The
internal name of the tasklist to be invoked in the app.
State-Aware Methods
jsi/state/start.i
This method is used to start
a state-aware WebSpeed session and lock an agent to this client.
- &timeout - The number
of minutes to wait before ending a state-aware session which has had no
activity from its client during that time. Default is 5 minutes.
jsi/state/end.i
This method is used to explicitly
end
a state-aware WebSpeed session and free the agent to handle other
clients.
jsi/tran/start.i
This method is used to explicitly
start
a
Web transaction within a state-aware session.
jsi/tran/commit.i
This method is used to explicitly
commit
a Web transaction within a state-aware session.
jsi/tran/undo.i
This method is used to explicitly
undo
a Web transaction within a state-aware session.
jsi/tran/retry.i
This method is used to explicitly
retry
a Web transaction within a state-aware session.
Container Methods
These methods are used with
various container objects (frames, panels, cardpanels, tabpanels). There
are both generic container methods which can be used with any container
type, and other methods that are specific to a particular container type.
Generic Container
These methods can be used
on any container object (frame, panel, cardpanel, tabpanel).
jsi/container/displaydefaultvalues.i
This method is used to reset
the contents of all components of the specified container by displaying
the default (initial) value of each component.
&name - The internal
name used in the client app for this object.
jsi/container/setenabled.i
This method is used to enable
or disable all components of the specified container. This method must
be used on the smallest containing object (like a panel or a tab of a tabpanel).
You cannot use it on an entire tabpanel or cardpanel container object.
(Well, strictly speaking, you could, but it wouldn't do what you
wanted).
&name - The internal
name used in the client app for this object.
&b - A boolean (logical)
value: 'true' to enable, 'false' to disable.
jsi/container/validate.i
This method is used to force
Jargon Reader to repaint the screen so that a newly added container or
component will be made visible immediately. This should always be done
after adding a new object with a host method and after the container has
been made visible.
&name - The internal
name used in the client app for the new container or the container which
contains the new component.
Frame
jsi/frame/add.i
This method is used to add
a new frame to a client app.
- &name - The internal
name used in the client app for this object.
- &title - The title
to display in the bar at the top of the frame.
- &systemexit - Exit
the entire application when the frame is closed (true) or simply hide the
frame (false).
jsi/frame/pack.i
This method is used to dynamically
size a frame as large as necessary to "pack" around its components. This
is the normal method used to size a frame and is done after adding it.
&name - The internal
name used in the client app for this object.
jsi/frame/setmessage.i
This method is used to display
a message in the system message area at the bottom of the frame.
&name - The internal
name used in the client app for this object.
&val - A character
string to be displayed as a message. Example: " 'Process completed' ".
jsi/frame/settitle.i
This method is used to assign
a frame's title (displayed in the top border of the frame).
- &name - The internal
name used in the client app for this object.
- &val - A character
string to be displayed as the frame title. Example: " 'My Title' ".
jsi/frame/setvisible.i
This method is used to make
a frame visible or invisible (hidden).
&name - The internal
name used in the client app for this object.
&val - A boolean
(logical) value: 'true' to make visible, 'false' to hide.
Panel
jsi/panel/add.i
This method is used to add
a panel dynamically within the client app.
Card panel
jsi/cardpanel/add.i
This method is used to add
a card panel (a container that contains one or more overlayable panels,
like a tabpanel but without the tabs).
jsi/cardpanel/show.i
This method is used to change
the panel within the card panel that is currently displayed.
- &name - The internal
name used in the client app for the cardpanel.
- &card - The internal
name of the panel within this cardpanel that should be displayed ("on top").
Tabpanel
jsi/tabpanel/add.i
This method is used to add
a tabpanel container, which will be able to contain one or more panels.
A tabpanel is similar to a card panel, except that the panels in a tabpanel
have "tabs" along one edge which allow the user to directly change which
panel is displayed ("on top") at any given time. Users cannot do this with
card panels.
jsi/tabpanel/settab.i
This method is used to change
the panel that is currently displayed within the tabpanel.
- &name - The internal
name used in the client app for the tabpanel.
- &tab - The internal
name of a panel within the tabpanel that is to be displayed ("on top").
Component Methods
These methods are used with
various component objects (objects which are not containers). There are
both generic component methods which can be used with any component type,
and other methods that are specific to a particular component type.
Generic Component
These methods can be used
on any component object.
jsi/component/setenabled.i
This method is used to enable
or disable a component.
- &name - The internal
name used in the client app for this object.
- &b - A boolean (logical)
value: 'true' to make visible, 'false' to hide. This parameter is optional.
If not used, the default is 'true' (make the component visible).
Button
jsi/button/add.i
This method is used to add
a button within a container in the currently executing client app.
- &name - The internal
name used in the client app for this object.
- &val - A character
string to be displayed as the caption (label) of this object.
Buttongroup
jsi/buttongroup/add.i
This method is used to assign
two or more button, checkbox and/or radio button objects to a button group.
- &name - The name
of the button group (this is an abstract object, not a visual object)
- &blist - A comma-separated
list of internal object names for the buttons to be put into a common button
group.
Checkbox
jsi/checkbox/add.i
This method is used to add
a checkbox within a container in the currently executing client app.
- &name - The internal
name used in the client app for this object.
- &val - A character
string to be displayed as the caption (label) of this object.
Combo Box
jsi/combobox/add.i
This method is used to add
a combobox within a container in the currently executing client app.
- &name - The internal
name used in the client app for this object.
- &columns - The width
of the comboxbox in average characters.
- &images - Will entries
in the combox contain images (true) or not (false)?
- &editable - Is the
combobox editable (true) or not (false)? (Can you enter a new value?)
- &celleditor - Is
the combobox being added as a column in a table (true) or not (false)?
- &coltitle - Column
title when used as a column in a table.
- &coleditable - Is
value editable (true) or not (false) when used as a column in a table?
- &colwidth - Width
in pixels to override default column width when used in a table.
- common Constraint
Arguments
- common Attribute
Arguments
jsi/combobox/additem.i
This method is used to add
one or more values to the combobox choices. Values are always added at
the bottom of the list of choices.
- &name - The internal
name used in the client app for this object.
- &val - A comma-separated
list of one or more character strings to be displayed as choices in the
list. A choice cannot contain commas.
jsi/combobox/addlist.i
This method is used to add
one or more values to the combobox choices, using a specified delimiter.
Values are always added at the bottom of the list of choices.
- &name - The internal
name used in the client app for this object.
- &list - A delimiter-separated
list of one or more character strings to be displayed as choices in the
list. A choice cannot contain the delimiter character.
- &delim - The delimiter
character to be used to separate values of combobox choices. If choice values
might contain a comma character, a recommended delimiter value is the caret
symbol (^).
jsi/combobox/removeallitems.i
This method is used to remove
all choices from (clear) a combobox.
- &name - The internal
name used in the client app for this object.
jsi/combobox/setdefaultselection.i
This method is used to set
the default selection choice for a combobox. This choice will be displayed
when the combobox is first created and whenever a "set defaults" method
is invoked on it or its container.
- &name - The internal
name used in the client app for this object.
- &val - A character
string that must exactly match one of the current choices in the combo
box (case-sensitive).
jsi/combobox/setselectedindex.i
This method is used to set
the currently selected item to the n'th item in the list, starting with
0 as the top item.
- &name - The internal
name used in the client app for this object.
- &val - An integer
value from 0 to (n - 1), where n is the number of current choices in the
combobox.
jsi/combobox/setselecteditem.i
This method is used to set
the currently selected item by specifying the value of one of the choices.
- &name - The internal
name used in the client app for this object.
- &val - A character
string that must exactly match one of the current choices in the combo
box (case-sensitive).
Label
jsi/label/add.i
This method is used to add
a label within a container in the currently executing client app.
- &name - The internal
name used in the client app for this object.
- &val - A character
string that is the label text to be displayed.
List Box
jsi/listbox/add.i
This method is used to add
a listbox within a container in the currently executing client app.
jsi/listbox/additem.i
This method is used to add
one or more values to the listbox choices, using commas to separate multiple
values. Values are always added at the bottom of the list of choices.
- &name - The internal
name used in the client app for this object.
- &val - A comma-separated
list of one or more character strings to be displayed as choices in the
list. A choice cannot contain commas.
jsi/listbox/addlist.i
This method is used to add
one or more values to the listbox choices, using a specified delimiter.
Values are always added at the bottom of the list of choices.
- &name - The internal
name used in the client app for this object.
- &list - A delimiter-separated
list of one or more character strings to be displayed as choices in the
list. A choice cannot contain the delimiter character.
- &delim - The delimiter
character to be used to separate values of listbox choices. If choice values
might contain a comma character, a recommended delimiter value is the caret
symbol (^).
jsi/listbox/removeallitems.i
This method is used to remove
all choices from (clear) a listbox.
- &name - The internal
name used in the client app for this object.
jsi/listbox/setdefaultselection.i
This method is used to set
the default selected item by specifying the value of one of the choices.
- &name - The internal
name used in the client app for this object.
- &val - A character
string that must exactly match one of the current choices in the listbox
(case-sensitive).
jsi/listbox/setselectedindex.i
This method is used to set
the currently selected item to the n'th item in the list, starting with
0 as the top item.
- &name - The internal
name used in the client app for this object.
- &val - An integer
value from 0 to (n - 1), where n is the number of current choices in the
listbox.
jsi/listbox/setselecteditem.i
This method is used to set
the currently selected item by specifying the value of one of the choices.
- &name - The internal
name used in the client app for this object.
- &val - A character
string that must exactly match one of the current choices in the listbox
(case-sensitive).
Menubar
jsi/menubar/add.i
This method is used to add
a menubar within a container in the currently executing client app.
jsi/menubar/addmenu.i
This method is used to add
a menu to a menubar, or to add a submenu to a menu, in the currently executing
client app.
- &name - The internal
name used in the client app for this menu.
- &caption - The text
displayed for the menu, on the menubar.
- &image - An optional
image filename to be displayed to the left of the caption.
- &mnemonic - Letter
or number used with ALT key to select a menu from the keyboard.
- common Constraint
Arguments
- common Attribute
Arguments
jsi/menubar/addmenuitem.i
This method is used to add
a menu choice within a menu or submenu in the currently executing client
app.
- &name - The internal
name used in the client app for this menu choice.
- &caption - The text
displayed for the menu choice, in the drop-down menu or submenu.
- &image - An optional
image filename to be displayed to the left of the caption.
- &mnemonic - Letter
or number used to select a menu choice from the keyboard.
- common Constraint
Arguments
- common Attribute
Arguments
jsi/menubar/addseparator.i
This method is used to add
a separator after the last menu item of the named menu in the currently
executing client app. This is used with the above two methods to add menu
items, submenus and separators in sequential order to a menu of a menubar.
&name
- The internal name used in the client app for menu item after which to
add a separator line.
Message Box
jsi/msgbox/message.i
This method is used to display
an informational message to the user, in a modal dialog box with an OK
button.
- &component - The
name of the frame that should receive focus after the user clicks the OK
button.
- &msg - A character
string for a one-line message to be displayed in the message box. Cannot
contain the comma (",") character.
jsi/msgbox/warning.i
This method is used to display
an error or warning message to the user, in a modal dialog box with an
OK button.
- &component - The
name of the frame that should receive focus after the user clicks the OK
button.
&msg - A character
string for a one-line message to be displayed in the message box. Cannot
contain the comma (",") character.
jsi/msgbox/msgbox.i
This method is used to display
an informational message to the user, in a modal dialog box with an OK
button.
- &msg - A character
string for a one-line message to be displayed in the message box. May contain
commas.
jsi/msgbox/warnbox.i
This method is used to display
an error or warning message to the user, in a modal dialog box with an
OK button.
- &msg - A character
string for a one-line message to be displayed in the message box. May contain
commas.
Radio Button
jsi/radiobutton/add.i
This method is used to add
a radio button within a container in the currently executing client app.
- &name - The internal
name used in the client app for this object.
- &label - The character
string displayed as the label or caption on the button.
- &icon - The filename
of an image file (JPEG or GIF) to display when the radio button is in its
normal state. If you provide an image filename here, you should also provide
one for "&selected" so that the user can see a different image when
they click the radio button to "bullet" it or not. Note that these images
will replace the default images of a circle (with a bullet displayed
when selected).
- &pressicon - Filename
of image to display when the button is pressed.
- &selected - Filename
of image to display when the button is selected.
- &rollover - Filename
of image to display when the mouse passes over the button.
- &rollselect - Filename
of image to display when the mouse passes over the button and the button
is selected.
- &disabled - Filename
of image to display when the button is disabled.
- &dselect - Filename
of image to display when the button is disabled and selected.
- &mnemonic - Letter
or number used with ALT key to select button from keyboard.
- &halign - Horizontal
alignment of text and image within button. See Alignment
Arguments.
- &valign - Vertical
alignment of text and image within button. See Alignment
Arguments.
- &htextpos -
Horizontal alignment of text relative to the image. See Alignment
Arguments.
- &vtextpos - Vertical
alignment of text relative to the image. See Alignment
Arguments.
- common Constraint
Arguments
- common Attribute
Arguments
jsi/radiobutton/group.i
NOT IMPLEMENTED - DO
NOT USE
(This method was used to
assign two or more radio button objects to a button group).
- &name - The internal
name used in the client app for this object.
- &val - A character
string to be displayed as the caption (label) of this object.
Table
jsi/table/add.i
This method is used to add
a table within a container in the currently executing client app. To add
columns to a newly added table, use jsi/textfield/add.i
and jsi/combobox/add.i to add textfield or combobox
components.
- &name - The internal
name used in the client app for this object.
- &nrows - An integer
value for the initial number of rows in the table.
- &visiblerows - An
integer value for the number of rows to be displayed in the window for
the table. The table will have a vertical scrollbar if this value is less
than the total number of rows in the table (initially "nrows").
- &visiblecols - An
integer value for the number of columns to be displayed in the window for
the table. The table will have a horizontal scrollbar if this value is
less than the total number of columns in the table.
- &selectrow - Are
rows selectable by the user (true) or not (false)?
- &selectcol - Are
columns selectable by the user (true) or not (false)?
- common Constraint
Arguments
- common Attribute
Arguments
jsi/table/additem.i
This method is used to add one or more
values to the list of choices in the combobox cell editors in one table column.
Values are always added at the bottom of the list of choices. The column number
containing the comboboxes must be specified (note that column numbers start
at zero, not one).
- &name - The internal
name used in the client app for this table object.
- &ncol - An integer
column number of the table column containing the combobox, starting with 0 (zero)
for the leftmost column.
- &val - The value
to be added to the comboboxes in this column.
jsi/table/collabel.i
This method is used to set
the title of a column in a table
- &name - The
internal name used in the client app for this object.
- &ncol - The
column number for the title, starting with 0 (zero) for the leftmost column.
- &val - The character
string to be used as a column title (cannot be stacked at this time).
jsi/table/constrain.i
This method is used to change
the Constraint Arguments for an existing table
jsi/table/removeallitems.i
This method is used to remove
all rows from a table.
- &name - The internal
name used in the client app for this object.
jsi/table/setrowtext.i
This method is used to add
or change the contents of all cells in one row of a table. If the specified
row number does not exist, it will be added. If no row number is specified,
a new row is added at the end of the table. The value must be a comma-separated
list of column values for every column of the row. Each column value must
be a string of the appropriate data type as defined in the client table
column properties.
- &name - The internal
name used in the client app for this object.
- &nrow - An optional
integer row number of the cell to be added or changed, starting with 0
(zero) for the top row.
- &val - A list of
column values, separated by commas or other optional delimiter character.
- &delim - An optional
single character to be used instead of the comma character to delimit values.
jsi/table/setselectedrow.i
This method is used to set
the "selected" row in a table
- &name - The
internal name used in the client app for this object.
- &nrow - The
row number to be set to the selected state, starting with 0 (zero) for
the top row.
jsi/table/settext.i
This method is used to assign
or change the contents of one cell in a table. Both the row and column
numbers must be specified (both start at zero, not one).
- &name - The internal
name used in the client app for this object.
- &nrow - An integer
row number of the cell to be added or changed, starting with 0 (zero) for
the top row.
- &ncol - An integer
column number of the cell to be changed, starting with 0 (zero) for the
leftmost column.
- &val - The value
to be displayed in this cell.
Textarea
jsi/textarea/add.i
This method is used to add
a text area within a container in the currently executing client app.
- &name - The internal
name used in the client app for this object.
- &val - The character
string to be displayed within the text area. This value may contain line
feed characters, which will override the automatic word wrap feature of
the text area, to allow user-controlled text placement (as with a name/address
display).
Textfield
jsi/textfield/add.i
This method is used to add
a textfield within a container in the currently executing client app.
- &name - The internal
name used in the client app for this object.
- &val - The value
to be displayed in the textfield. All values will be automatically converted
to strings before being sent to the client, so you may use database fields
that are dates, integers, decimals, etc.
Textpane
jsi/textpane/add.i
This method is used to add
a textpane within a container in the currently executing client app.
- &name - The internal
name used in the client app for this object.
- &columns - The length
of the textpane in "average characters" (default is 40).
- &rows - The height
of the textpane in rows (default is 1).
- &vsbpolicy - Vertical
scrollbar policy. The arguments can be specified as symbolic precompiler
names or as integer values:
{&VSB-AS-NEEDED} or 20
{&VSB-NEVER} or 21
{&VSB-ALWAYS} or 22
- &hsbpolicy - Horizontal
scrollbar policy.The arguments can be specified as symbolic precompiler
names or as integer values:
{&HSB-AS-NEEDED} or 30
{&HSB-NEVER} or 31
{&HSB-ALWAYS} or 32
- &linewrap - Automatic
line wrap at word boundaries (true) or not (false).
- common Constraint
Arguments
- common Attribute
Arguments
jsi/textpane/settext.i
This method is used to display
a value within a textpane.
- &name - The internal
name used in the client app for this object.
- &val - The character
string to be displayed within the textpane. This value may contain line
feed characters, which will override the automatic word wrap feature of
the textpane, to allow user-controlled text placement (as with a name/address
display).
Toolbar
jsi/toolbar/add.i
This method is used to add
a toolbar within a container in the currently executing client app. To
add buttons and separators to the toolbar, use "jsi/button/add.i".
Tree
jsi/tree/addnode.i
This method is used to add
a node to a tree, either under the tree "root" node itself, or under any
other node in the tree.
- &name - The internal
name used in the client app for the tree.
- &parentnode - The
internal name of an existing node in the specified tree under which the
new node is to be added as a child node. This parent node may or may not
already contain other child nodes. If it does, the new node will become
a sibiling of the existing child nodes. Any node automatically becomes
a parent node when one or more child nodes are added under it. There is
no special attribute which distinguishes parent nodes from ordinary "leaf"
nodes, only the fact that they contain at least one child node.
- &node - The internal
name to assign to the new child node. (Must be unique within the client
app).
- &text - The text
to display as the caption for the new node. (Cannot be blank).
- &userdata - (Optional)
An arbitrary character string that can be used to store any application-specific
value for the new node. For example, if a tree is used as a program menu,
the userdata might contain the name of the xml app to run when the node
is selected.
- &tooltip - (Optional)
A character string containing a one-line help message used as the tooltip
for the new node.
- &imageindex - (Optional)
An integer value which selects the icon to be displayed for the new node
in the tree. Selection is from a comma-separated list of icon filenames
in the tree's root node "imageList" attribute. An index of zero (0) will
select the first (leftmost) image filename in the list, one (1) selects
the next image filename entry, etc. If the list contains 5 image filename
entries, any index value of 5 or higher will not select any image, since
0-4 select the five valid choices.
- &nodeindex - (Optional)
An integer value which specifies where to insert the new node. A value
of -1 will add the new node as the last (bottom) child node for the specified
parent node. A value of 0 or more will insert it before an existing child
node of the parent node in that location, where 0 is the top existing node,
1 is the next node, etc.
jsi/tree/collapsenode.i
This method is used to collapse
a parent node that is currently expanded to show its child nodes, so that
the child nodes are no longer displayed. After being collapsed, this node
will show a "+" sign to its left, indicating that it contains one or more
child nodes that are not currently visible.
- &name - The internal
name used in the client app for the tree.
- &node - The internal
name of the parent node which is to be collapsed.
jsi/tree/expandnode.i
This method is used to expand
a collapsed parent node so that its immediate child nodes will be displayed.
Note that the expansion is not recursive, meaning that "grandchild" nodes
are not expanded (nodes under any child node that has its own child nodes).
- &name - The internal
name used in the client app for the tree.
- &node - The internal
name of the parent node which is to be expanded.
jsi/tree/removechildren.i
This method is used to remove
all child nodes under the specified parent node. This removal is recursive,
so "grandchild" nodes and lower levels of nodes will also be removed.
- &name - The internal
name used in the client app for the tree.
- &node - The internal
name of the parent node whose child nodes are to be removed.
jsi/tree/removenode.i
This method is used to remove
the specified node. This removal is recursive, so any child nodes and their
children will also be removed.
- &name - The internal
name used in the client app for the tree.
- &node - The internal
name of the node which is to be removed.
jsi/tree/selectnode.i
This method is used to select
the specified node. This will cause the specified node entry in the tree
to become highlighted and will also fire the TreeSelection event.
- &name - The internal
name used in the client app for the tree.
- &node - The internal
name of the node which is to be selected.
jsi/tree/setnodedata.i
This method is used to set
the value of the "userdata" attribute in the specified node.
- &name - The internal
name used in the client app for the tree.
- &node - The internal
name of the node whose userdata attribute is to be set.
- &val - A character
string that will become the value of the userdata attribute for the specified
node.
jsi/tree/setnodeimage.i
This method is used to set
the value of the "imageIndex" attribute in the specified node.
- &name - The internal
name used in the client app for the tree.
- &node - The internal
name of the node whose imageIndex attribute is to be set.
- &val - An integer
value that will become the value of the imageIndex attribute for the specified
node. This value selects the icon image filename to be displayed for this
node. Selection is from a comma-separated list of icon filenames in the
tree's root node "imageList" attribute. An index of zero (0) will select
the first (leftmost) image filename in the list, one (1) selects the next
image filename entry, etc. If the list contains 5 image filename entries,
any index value of 5 or higher will not select any image, since 0-4 select
the five valid choices.
jsi/tree/setnodetext.i
This method is used to set
the value of the "text" attribute in the specified node.
- &name - The internal
name used in the client app for the tree.
- &node - The internal
name of the node whose text attribute is to be set.
- &val - A character
string that will become the value of the text attribute for the specified
node. This is displayed as the caption for this node.
jsi/tree/setnodetip.i
This method is used to set
the value of the "tooltip Text" attribute in the specified node.
- &name - The internal
name used in the client app for the tree.
- &node - The internal
name of the node whose tooltip text attribute is to be set.
- &val - A character
string that will become the value of the tooltip attribute for the specified
node. This one-line help message will be displayed as the floating tooltip
for this node.
Constraint Arguments
These arguments are part
of a nested include file that is used in most "jsi/XXX/add.i" methods to
assign required and optional constraints when dynamically creating a new
object. They are documented once here, to avoid repetition. For more information
on these constraint properties, see the GridBag
Layout Manager document and the Layout
Tab in the Properties Tabpanel of the Design Window, in the Getting
Started with Jargon Writer document.
-
&container
- The object name of the container (frame or any type of panel) for the
object being added. This is a required argument.
- &gridx - The horizontal
grid position (column) of the left edge of an object. Integer value, starting
with 0 for the leftmost column, 1 for the next column to the right, and
so on. The default value is 0 (zero).
- &gridy - The vertical
grid position (row) of the top edge of an object. Integer value, with 0
being the top row. The default value is 0 (zero).
- &gridw - Number of
cells wide. Default is 1.
- &gridh - Number of
cells high. Default is 1.
- &fill - Method used
by an object to grow to the boundaries of its cell. The arguments can be
specified as symbolic precompiler names or as integer values (default is
"None"):
{&FILL-NONE} or 0
{&FILL-BOTH} or 1
{&FILL-HORIZONTAL} or 2
{&FILL-VERTICAL} or 3
- &anchor - The edge
or corner of a cell to which an object is attached when it is smaller than
its cell. The arguments can be specified as symbolic precompiler names
or as integer values (default is "SOUTHWEST"):
{&ANCHOR-CENTER} or 10
{&ANCHOR-NORTH} or 11
{&ANCHOR-NORTHEAST} or 12
{&ANCHOR-EAST} or 13
{&ANCHOR-SOUTHEAST} or 14
{&ANCHOR-SOUTH} or 15
{&ANCHOR-SOUTHWEST} or 16
{&ANCHOR-WEST} or 17
{&ANCHOR-NORTHWEST} or 18
- &ipadx - Integer
value for number of pixels to add to the horizontal size (width) of an
object. Default is zero.
- &ipady - Integer
value for number of pixels to add to the vertical size (height) of an object.
Default is zero.
- &top - Integer value
for number of pixels to inset the top edge of an object from the top edge
of its cell. Default is zero.
- &left - Integer value
for number of pixels to inset the left edge of an object from the left
edge of its cell. Default is zero.
- &bottom - Integer
value for number of pixels to inset the bottom edge of an object from the
bottom edge of its cell. Default is zero.
- &right - Integer
value for number of pixels to inset the right edge of an object from the
right edge of its cell. Default is zero.
- &width - Width of
the object in pixels. If used as an override of default size, must also
use height.
- &height - Height
of the object in pixels. Use with width to override default object size.
- &weightx - Weighting
value for horizontal object resizing. Decimal value of up to 2 decimal
places, with a default of zero (no resizing).
- &weighty - Weighting
value for vertical object resizing, with values like weightx.
Attribute Arguments
These arguments are part
of a nested include file that is used in many "jsi/XXX/add.i" methods to
assign various optional properties when dynamically creating a new object.
They are documented once here, to avoid repetition. For more information
on these attribute properties, see the GridBag
Layout Manager document and the Layout
Panel in the Properties Tabpanel of the Design Window, in the Getting
Started with Jargon Writer document. Not all arguments are meaningful for
all component types
- &bwidth - Border
width in pixels
- &btitle - Border
title
- &bimage - The filename
of an image used for an image border (&border value 6, below)
- &barray - An array
of values used by certain objects, such as a list of members of a button
group.
- &tooltip - One-line
help message displayed when mouse pointer pauses over an object.
- &visible - Initial
state of object - visible (true) or hidden (false)
- &enabled - Initial
state of object - Enabled for focus/input (true) or disabled (false)
- &border - Type of
border for panels and other objects that can have borders. Values are
1 - empty border (default)
2 - line border
3 - raised 3D border
4 - lowered 3D border
5 - etched border
6 - image border (uses image specified by &bimage argument)
Alignment Arguments
Several of the "add.i" methods
(for button, checkbox, radiobutton and label) use the same set of arguments
(parameters) to specify the alignment for the component's text caption
and image (if any). They are discussed here to avoid duplication within
each method.
The "halign" and "valign"
arguments control the placement of the combined text and image content
within the component's boundaries. This only becomes apparent if the component
(button, checkbox, radiobutton or label) is declared with a fixed size
in pixels which is larger than the size of its contents, so that there
is "room" to move the contents within the boundaries. If default sizing
is used, the boundaries of the component will be only large enough to hold
the contents and these arguments will have no visual effect.
The "htextpos" and
"vtextpos" arguments control the placement of the text caption relative
to the image. If the component does not have an image, these arguments
have no visual effect. Note that checkboxes and radio buttons already have
default images, whereas buttons and labels do not. If both values are centered,
the caption will overlay the image. This may make the caption hard
to read, depending on the hue and intensity of the image's colors.
Although Jargon Writer uses
compass directions like North and SouthEast for the "Alignment" and "Text
Align" options (for ease of use), these are actually translated into vertical
and horizontal alignment parameters, to match the argument syntax of the
underlying components. In host methods, the underlying vertical and horizontal
values must be specified directly. This was done to help keep the client
deployment products as small and efficient as possible.
To see alignment behavior
in Jargon Writer, create a button with a fixed size of 200 by 200 pixels,
and with both a text caption and an image file. Experiment with the
"Align Text" and "Alignment" parameters to see how the contents move as
these values are changed. You can also try this with a checkbox, a radio
button, and a label.
The values of the "halign"
and "htextpos" horizontal alignment arguments can be specified as
either integer values or as symbolic precompiler names:
For center alignment, use '0' or {&ALIGN-CENTER}
For left alignment, use '2' or {&ALIGN-LEFT}
For right alignment, use '4' or {&ALIGN-RIGHT}
Similarly, the "valign"
and "vtextpos" vertical alignment arguments are specified as:
For center alignment: '0' or {&ALIGN-CENTER}
For top alignment: '1' or {&ALIGN-TOP}
For bottom alignment: '3' or {&ALIGN-BOTTOM}
If these arguments are not specified,
the default values will align the text and image in the center of the component,
with text to the right of the image (East).
For example, to add a button
with a text caption above an image (North) and with both the image and
text located near the center of the right edge of the button boundary (East),
you would specify the arguments as:
{jsi/button/add.i
&name='buttonExample'
&label='Button Caption'
&icon='button_image.gif'
<other button arguments would go here>
&halign={&ALIGN-RIGHT}
&valign={&ALIGN-CENTER}
&htextpos={&ALIGN-CENTER}
&vtextpos={&ALIGN-TOP}
}
Note that to do the same thing
in Jargon Writer, the button's Properties Panel would have:
horizontalTextPosition = CENTER
verticalTextPosition = TOP
horizontalAlignment = RIGHT
verticalAlignment = CENTER
|
