Host Methods for Java
Version 3
Introduction
This document lists each of the Java methods that can be
used by Java servlets to send various commands to a client application (app). These functions are
contained in a set of java class files that can be included by importing the package "jargonsoft/jsi"
with the command:
import jargonsoft.jsi.*;
There are commands available for a wide variety of purposes, including:
-
assigning or changing the displayed value in a component such as a
textfield, textarea or textpane
-
selecting ("checking") or unselecting a checkbox
-
populating or clearing row and cell contents in a table
-
adding or selecting a specific value in a combobox
In addition, a powerful utility procedure allows a host procedure
to indirectly use all scripting capabilities available in a client app, by running
a client-side function that accomplishes the desired action(s).
These functions construct the commands
that are to be sent to the client (known as CIO or Component Instruction Object commands).
They are used like any other Java method. To actually send each command to the client,
create a PrintWriter instance for the response stream.
For example, to display a literal into a client textfield whose object name is "tName":
// Handle the HTTP POST method
public void doPost(HttpServletRequest request, HttpServletResponse response)
throws ServletException, IOException {
// set content type and other response header fields first
response.setContentType("text/html");
// then write the data of the response
PrintWriter out = response.getWriter();
// above is done only once per response
out.println(textfield.setText("tName", "Your Name Here"));
. . . (etc.)
}
Most functions have at least
one required argument, the "object name" which names
a container or component object to which the procedure 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 the same as the syntax
used in Java itself, and can be the cause of numerous errors if not
carefully followed.
Utility Procedures
util.invokeFunction(String appName, String functionName)
This method is used to instruct the client
to execute an existing function in a specific app. The function can contain any valid list
of statements, and is executed just as if it were linked to a client event which had just
taken place. This method may also be called using the alias "util.invokeTaskList"
with the same results.
-
appName - The name of the client app (without the ".xml" suffix) in which a
function is to be invoked. The app must already be open in the client session.
-
functionName - The internal name of the function to be invoked in the app.
Container Procedures
These functions are used with
various container objects (frames, panels). There are both generic container
functions which can be used with any container type, and other functions
that are specific to a particular container type.
Generic Container
These functions can be
used on any container object (frame, panel, cardpanel, tabpanel).
No Generic Container methods are currently available in Version 3.
Frame
frame.setMessage(String name, String msg)
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.
-
msg - A character string to be displayed as a message. Example: "Process completed" .
frame.setTitle(String name, String title)
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.
-
title - A character string to be displayed as the frame title. Example: "My Title".
frame.setVisible(String name, boolean bValue)
This method is used to make a frame visible or invisible (hidden).
-
name - The internal name used in the client app for this object.
-
bValue - A BOOLEAN value: True to make visible, False to hide.
Component Procedures
These functions are used with
various component objects (objects which are not containers). There are
both generic component functions which can be used with any component
type, and other functions that are specific to a particular component
type.
Generic Component
These functions can be used on any component object.
No Generic Component methods are currently available in Version 3.
Button
No Button methods are currently available in Version 3.
Checkbox
checkbox.setSelected (String name, boolean bValue)
This method is used to select (check) or unselect (clear) a checkbox.
-
name - The internal name used in the client app for this object.
-
bValue - A boolean value for the selected state of the checkbox: True for selected,
False for not selected.
Combobox
combobox.addItem(String name, String value)
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.
-
value - A comma-separated list of one or more character strings to be displayed as
choices in the list. A choice cannot contain commas.
combobox.removeAllItems(String name)
This method is used to remove all choices from (clear) a combobox.
-
name - The internal name used in the client app for this object.
combobox.setSelectedIndex(String name, int nValue)
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.
-
nValue - An integer value from 0 to (n - 1), where n is the current number of choices
in the combobox.
combobox.setSelectedItem(String name, String value)
This method is used to set the currently selected item by specifying the exact value of
one of the choices. String must exactly match, including upper/lower case and any trailing spaces.
-
name - The internal name used in the client app for this object.
-
value - A character string that must exactly match one of the current choices in
the combo box (case-sensitive).
Hyperlink
hyperlink.setText(String name, String value)
This method is used to assign the displayed value in a hyperlink.
-
name - The internal name used in the client app for this object.
-
value - The value to be displayed in the hyperlink.
hyperlink.setUserData(String name, String value)
This method is used to assign a value to the (hidden) userdata attribute
in a hyperlink.
-
name - The internal name used in the client app for this object.
-
value - The value to be assigned to the userdata attribute of the hyperlink.
Label
No Label methods are currently available in Version 3.
Message Box
msgbox.message(String msg)
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 message to be displayed in the message box.
May contain newline characters (VBLF). Cannot contain the comma (",") character.
msgbox.warning(String msg)
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 message to be displayed in the message box.
May contain newline characters (VBLF). Cannot contain the comma (",") character.
Passwordfield
textfield.setText(String name, String value)
This method is used to display a value within a passwordfield. It uses the same
method as for textfields. However, the actual characters will not be shown (except on PalmOS),
instead they will be displayed as asterisks to keep the value secret.
-
name - The internal name used in the client app for this object.
-
value - The value to be displayed in the passwordfield.
Table
table.removeAllItems(name)
This method is used to
remove all rows from a table component in a client app.
-
name - The internal name used in the client app for this object.
table.setText (String name, int nRow, int nCol, String value)
This method is used to assign or change the contents
of one cell in a table. This method may also be called using the alias "table.setCellData"
with the same results.
-
name - The internal name used in the client app for this object.
-
nRow - An integer row number of the specified cell, starting with 0 (zero)
for the top row.
-
nCol - An integer column number of the specified cell, starting with 0 (zero)
for the leftmost column.
-
value - The string value to be displayed in this cell.
table.setRowText (String name, int nRow, String value, String delimiter)
This method is used to
assign or change the contents of all cells in one row in a table. This method is more
efficient than using table.setText to set each cell in the row separately.
-
name - The internal name used in the client app for this object.
-
nRow - An integer row number, starting with 0 (zero) for the top row.
-
value - A set of string values, delimited by the specified delimiter character(s), that
will be displayed in the cells (columns) of the specified row.
-
delimiter - The string delimiter used to separate cell values in the "value" parameter.
Be careful to use a delimiter that will not be part of any data values. A caret (^) symbol
is often a good choice.
Textarea
textarea.setText(String name, String value)
This method is used to display text within a text area.
-
name - The internal name used in the client app for this object.
-
value - 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
textfield.setText(String name, String value)
This method is used to display a value within a textfield.
-
name - The internal name used in the client app for this object.
-
value - The value to be displayed in the textfield.
Textpane
textpane.setText(String name, String value)
This method is used to display a value within a textpane.
- name - The internal name used in the client app for this object.
-
value - 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).
Up to Top
Return to Help Index