Introduction
This document lists the most common methods that are used in functions
in the Jargon Writer Script Editor. There are many methods that can be
applied to individual containers and components, including:
-
getting the current value of a component such as a textfield,
textarea or combo box
-
assigning the displayed value in a component such as a textfield,
textarea, textpane or image
-
selecting ("checking") or unselecting a checkbox
-
assigning or changing an object's title
-
adding or selecting a specific value in a combobox
In addition, several powerful system methods
can be applied to the global "sys" object:
-
executing CIO commands received from a host procedure
-
display a modal message box
-
display a modal warning box
-
exit the application and Jargon Reader (system exit)
For running procedures on a remote server, a set of Remote
Procedure Call (rpc) methods are provided:
-
assigning the URL, middleware values, and the name of the
program and/or procedure to be run
-
assigning name/value pairs for any desired input parameters
-
executing the remote procedure call
For obtaining any kind of response from a remote server,
a set of general-purpose HTTP methods are provided:
assigning the URL for the HTTP request
assigning name/value pairs for any desired input parameters
assign the name of a function to be run when the response
is received from the remote server
sending the request URL and POST name/value pair data to
the remote server
accessing the response data (when received) and its size
in bytes
Selecting a Method
Methods can be selected from a listbox in the Script
Editor for each type of component. When a container or component is selected
in the target tree on the left side of the Script Editor, an alphabetical
list of its available methods will be shown in the "Target method"
listbox below the tree. Each method's name, parameters and return value
are listed.
The available methods are defined in a file specified
by the "MethodList" value in the Jargon Writer system\preferences.ini file.
To shut off the feature, comment out this entry by placing a "#" character
at the start of the line containing "MethodList=". The default entry is:
MethodList=./system/jsimethods.xml
Method Return Values
If the method returns a value, the object type will be
listed in the "Return type" column. An entry of "void" means that
no value is returned. Common return types are "string" (also called "java.lang.String"),
"int" and "boolean". Methods with return values are used in rpc methods
to populate host parameters with the current contents of objects such as
textfields, and may also be used as nested methods to populate the parameters
of other client methods (these can be nested multiple levels if needed).
Method Parameters
Many methods have one or more parameters that
are one of the basic object types: "string" ("java.lang.String"), "int"
or "boolean". In general, methods which require parameters that are more
complex objects cannot be used unless there is another method which can
be specified as a subtask to populate the parameter with that kind of object
value.
-
An "int" parameter can only contain positive or negative
integers, such as -2, -1, 0, 1, 2, ... 9999 ...
etc. (do not enter commas within the integer). Note: negative values are
not meaningful in most integer parameters.
-
A "boolean" parameter can only have the lowercase
value "true" or "false" (do not enter the quotation marks).
-
A "string" parameter can have any zero or more characters.
 User
Tip: Note that some string parameters specify an "object name"
that names a container or component object to which the method will be
applied, such as the name of a tab within a tab panel. 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 'tabone' and 'TabOne' cannot
be used interchangeably to reference the same client object. This rule
is different than the syntax used in many other languages, and can be the
cause of numerous errors if not carefully followed.
Documentation Format
The following format is used for the methods described
in this document:
Method: a method name, followed by an ordered list of any required
parameters (in parentheses)
Return: type of value returned by the method ("void" means none)
Param0: description of the first parameter (if any)
Param1: description of the second parameter (etc.)
Container Methods
These methods are used with various container objects
(frames, panels, cardpanels, tabpanels). There are both generic container
methods that 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).
View or Hide a Container and its Contents
This method makes a container visible or invisible
(hidden).
- Method: SetVisible(boolean bVisible)
- Return: void
- Param0: (bVisible) "true" to make visible, "false" to hide
Frame
Do Layout
This method recalculates the component sizes of a frame's
contents. It should be used on all previously rendered frames after changing
the system default font. This method does not set a frame visible, use
table.SetVisible(true) to do that.
- Method: DoLayout()
- Return: void
- Params: none
Get Component Name That Has Focus
This method gets the name of the component that currently
has focus in a frame.
- Method: GetFocusComponentName()
- Return: String
- Params: none
Move/Resize Frame
This method is used to position a frame with its upper
lefthand corner at a specific X/Y pixel location, and to resize a frame to
a specific width and height, measured in pixels. This method is supported on
32-bit Windows platforms only (ReaderWIN.exe).
- Method: MoveWindow(int nXPos, int nYPos, int nWidth, int nHeight)
- Return: void
- Param0: (nXPos) The "X" (horizontal) pixel position of the upper lefthand
corner of the frame. On an 800x600 resolution display, this value can be
0-799.
- Param1: (nYPos) The "Y" (vertical) pixel position of the upper lefthand
corner of the frame. On an 800x600 resolution display, this value can be
0-599.
- Param2: (nWidth) The "X" (horizontal) pixel width of the frame. On
an 800x600 resolution display, this value can be 0-799.
- Param3: (nHeight) The "Y" (vertical) pixel height of the frame. On
an 800x600 resolution display, this value can be 0-599.
Repaint a Frame
This method forces a repaint of a frame's
contents. Does not redraw table contents, use table.Repaint() to do that.
- Method: Repaint()
- Return: void
- Params: none
Display a Status Message
This method displays a one-line message in
a frame's status panel (at the bottom of the frame).
- Method: SetMessage(string message)
- Return: void
- Param0: (message) A one-line message string to be displayed.
Display a Timed Status Message
This method displays a one-line message, for a specified time
interval, in a frame's status panel (at the bottom of the frame).
- Method: SetTimedMessage(string message, int milliseconds)
- Return: void
- Param0: (message) A one-line message string to be displayed.
- Param1: (milliseconds) The number of milliseconds the message will be
displayed before being hidden. For example, a value of 2000 specifies a message
that will be displayed for 2 seconds.
Change a Frame Title
This method dynamically changes the title displayed
in a frame's title bar.
- Method: SetTitle(string title)
- Return: void
- Param0: (title) The character string to display (left-justified) in
the frame's title bar (at the top).
Panel
Get Handle to Panel
This method gets a handle to this panel.
(Used with "video" global object methods).
- Method: GetHandle()
- Return: handle (similar to an int)
- Params: none
Get Pixel Height of Panel
This method gets the pixel height of this panel.
(Used with "video" global object methods).
- Method: GetHeight()
- Return: int
- Params: none
Get Pixel Width of Panel
This method gets the pixel width of this panel.
(Used with "video" global object methods).
- Method: GetWidth()
- Return: int
- Params: none
Set Tooltip Text
This method sets the tooltip text for a panel.
- Method: SetToolTipText(string Tooltip)
- Return: void
- Param0: (Tooltip) A character string that will become the value
of the tooltip attribute for the specified component. This one-line help message
will be displayed as the floating tooltip for this component.
Tab Panel
Get Number of Selected Tab in a Tab Panel
This method gets the number of the tab
that is currently displayed within the tab panel. Tabs are numbered from
zero (0) to (n-1) for a tabpanel with (n) tabs. Since users can bring
up different tabs by clicking on them, this provides a way to see which
tab is currently visible ("on top").
- Method: GetTabIndex()
- Return: int
- Params: none
Get Name of Selected Tab in a Tab Panel
This method gets the Object Name of the tab
that is currently displayed within the tab panel. Since users can bring
up different tabs by clicking on them, this provides a way to see which
tab is currently visible ("on top").
- Method: GetSelectedPanelName()
- Return: string
- Params: none
Repaint
This method forces a repaint of the tabpanel so
that new values will be made visible immediately.
- Method: Repaint()
- Return: void
- Params: none
Display a Tab in a Tab Panel by Name
This method changes the tab that is currently
displayed within the tab panel by specifying a tab name.
- Method: SetTab(string tabName)
- Return: void
- Param0: (tabName) The internal name of the tab within this tabpanel
that should be brought to the top so that its contents are displayed.
Display a Tab in a Tab Panel by Number
This method changes the tab that is currently
displayed within the tab panel by specifying a tab number (starting from zero).
- Method: SetTabIndex(int tabNumber)
- Return: void
- Param0: (tabNumber) The number (leftmost tab is zero) of the tab within
this tabpanel that should be brought to the top so that its contents are displayed.
Tab
Set Tooltip Text
This method sets the tooltip text for a tab in a tabpanel.
- Method: SetToolTipText(string Tooltip)
- Return: void
- Param0: (Tooltip) A character string that will become the value
of the tooltip attribute for the specified component. This one-line help message
will be displayed as the floating tooltip for this component.
Card Panel
Get Number of Current Card in a Card Panel
This method gets the number of the card
that is currently displayed within a card panel. Cards are numbered from
zero (0) to (n-1) for a cardpanel with (n) cards. This provides a way to determine
which card is currently visible ("on top").
- Method: GetCardIndex()
- Return: int
- Params: none
Get Name of Current Card in a Card Panel
This method gets the Object Name of the card
that is currently displayed within the card panel. This provides a way to determine
which card is currently visible ("on top").
- Method: GetSelectedPanelName()
- Return: string
- Params: none
Repaint
This method forces a repaint of the cardpanel so
that new values will be made visible immediately.
- Method: Repaint()
- Return: void
- Params: none
Display a Card in a Card Panel by Name
This method changes the card that is currently
displayed within the card panel by specifying a card name.
- Method: SetCard(string cardName)
- Return: void
- Param0: (cardName) The internal name of the card within this cardpanel
that should be brought to the top so that its contents are displayed.
Display a Card in a Card Panel by Number
This method changes the card that is currently
displayed within the card panel by specifying a card number (starting from zero).
- Method: SetCardIndex(int cardNumber)
- Return: void
- Param0: (cardNumber) The number (leftmost card is zero) of the card within
this cardpanel that should be brought to the top so that its contents are displayed.
Card
Set Tooltip Text
This method sets the tooltip text for a card in a cardpanel.
- Method: SetToolTipText(string Tooltip)
- Return: void
- Param0: (Tooltip) A character string that will become the value
of the tooltip attribute for the specified component. This one-line help message
will be displayed as the floating tooltip for this component.
Component Methods
These methods are used with various component objects
(objects that are not containers). There are both generic component methods
that 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 unless
otherwise specified.
Enable or Disable a Component
This method can be used to enable or disable the following components:
Button, Checkbox, Combobox, Datefield, Hyperlink, Passwordfield, Table, Textarea,
Textfield, and Tree.
Note that the Table and Hyperlink components will not change color when disabled, but
they will not respond to any user interaction until re-enabled.
- Method: SetEnabled(boolean bEnabled)
- Return: void
- Param0: (bEnabled) "true" to enable, "false" to disable
View or Hide a Component and its Contents
This method makes a component visible or hidden
(hidden).
- Method: SetVisible(boolean bVisible)
- Return: void
- Param0: (bVisible) "true" to make visible, "false" to hide
Set Tooltip Text of a Component
This method sets the tooltip text for a specified
component. May be used on all components except label, frame and menubar/menu/menuitem.
- Method: SetToolTipText(string Tooltip)
- Return: void
- Param0: (Tooltip) A character string that will become the value
of the tooltip attribute for the specified component. This one-line help message
will be displayed as the floating tooltip for this component.
Button
Get Button Caption (as Character String)
This method gets the character value of
the current caption (label) of a button as a "string" data type.
- Method: GetText()
- Return: string
- Params: none
Set Button Caption
This method assigns a caption (label) to a button.
The new value will not be displayed until the button's frame is redrawn
using the "frame.SetVisible(true)" method.
- Method: SetText(string text)
- Return: void
- Param0: (text) A character string to be assigned as the button caption.
Checkbox
Select or Unselect a Checkbox
These methods are used to select (check) or unselect (clear)
a checkbox.
- Method: SetSelected(boolean b)
- Return: void
- Param0: (b) "true" to select, "false" to unselect
Get Current Selected Status of a Checkbox
This method gets the current state of a checkbox
(selected or unselected).
- Method: IsSelected()
- Return: boolean (true if selected, false if not selected)
- Params: none
Combobox
Get Selected Index
This method gets the index (starting at zero) of the
currently selected item in a combo box.
- Method: GetSelectedIndex()
- Return: int
- Params: none
Get Selected Value
Either of these methods can be used to get the string value of
the currently selected item in a combo box.
- Method: GetCurrentValue()
or: GetSelectedString()
- Return: string
- Params: none
Get Delimited List of Choices
This method returns a delimited string of all the available choices
in the combobox dropdown list.
- Method: GetStringsList( string delimiter )
- Return: string
- Param0: (delimiter) A character or string used to separate choices in the list.
Insert or Append List Item(s)
This method adds one or more choices to the
selection list. New list items can be appended to the end (bottom) of the
list of choices or inserted at a specified location in the list.
- Method: InsertString(string valueString, int nIndex)
- Return: void
- Param0: (valueString) A character string to be added as a selection choice.
A choice cannot contain a comma. To add multiple choices, separate the
string values with commas (ex: "First Choice,Second Choice").
- Param1: (nIndex) Insertion position in list, from 0 to (n-1) for a
list of 'n' choices. If value is -1, choices are appended to the
end of the list.
Remove All List Items
This method removes all choices from the selection
list (clear the combobox).
- Method: RemoveAllItems()
- Return: void
- Params: none
Remove a Choice from Selection List
This method removes the specified value from the list of choices,
if it exists in the list.
- Method: RemoveString(string valueString)
- Return: boolean (true if choice was removed, false if not)
- Param0: (valueString) A case-sensitive character string that must exactly
match one of the current choices in the selection list.
Select List Item by Number
This method sets the currently selected item
to the n'th choice in the selection list. The selections are numbered starting
with zero, so valid parameter values are 0,1,2,3 ... (n-1) for a list with
n selections.
- Method: SetSelectedIndex(int nIndex)
- Return: void
- Param0: (nIndex) An integer value from 0 to (n - 1), where n is the
number of current choices in the combobox.
Select List Item by Value
This method sets the currently selected item
by specifying the value of one of the choices.
- Method: SetSelectedItem(string valueString)
- Return: void
- Param0: (valueString) A case-sensitive character string that must exactly
match one of the current choices in the selection list.
Hyperlink
Display Text
This method assigns a display value to a hyperlink.
The new value will be immediately displayed if the hyperlink is currently
visible. Note that the SetText method will not resize the component
if the specified string is longer than the initial size of the component.
- Method: SetText(string text)
- Return: void
- Param0: (text) A character string to be assigned as the hyperlink's display value.
Change User Data
This method assigns a user data value to a hyperlink.
- Method: SetUserData(string text)
- Return: void
- Param0: (text) A character string to be assigned as the hyperlink's user data value.
Get Current Value (as Character String)
This method gets the character value of
the current contents of a hyperlink's display value as a "string" data type.
- Method: GetText()
- Return: string
- Params: none
Get Current User Data (as Character String)
This method gets the character value of
the current contents of a hyperlink's user data as a "string" data type.
- Method: GetUserData()
- Return: string
- Params: none
Image
Assign an Image Value
This method displays an image by assigning
a binary data value to an image component. The image may be specified as
resizable or it can be truncated as need to fit into the declared image
component size.
NOTE: All Jargon Reader versions for Windows and PocketPC
devices support any image type that Windows supports, including standard
BMP, GIF and JPG formats.
Remove an Image Value
This method clears an image by displaying background
color throughout the image component area.
- Method: RemoveImageData()
- Return: void
- Params: none
Label
Set Label Caption
This method assigns a caption to a label.
The new value will not be displayed until the label's frame is redrawn
using the "frame.SetVisible(true)" method.
- Method: SetText(string text)
- Return: void
- Param0: (text) A character string to be assigned as the label caption.
Menubar
No Menubar methods are currently available.
Menu
No Menu methods are currently available.
Menu Item
No Menu Item methods are currently available.
Passwordfield
Display Text
This method assigns a value to a passwordfield.
The new value will be immediately displayed if the passwordfield is currently
visible. However, all characters in the data value are replaced with asterisks
("****") in the displayed value, for security purposes.
- Method: SetText(string text)
- Return: void
- Param0: (text) A character string to be assigned as the passwordfield value.
Get Current Value (as Character String)
This method gets the character value of
the current contents of a passwordfield as a "string" data type.
- Method: GetText()
- Return: string
- Params: none
Set Focus on Passwordfield
This method sets "focus" on a passwordfield, so that entered
data will go into the specified passwordfield.
- Method: SetFocus()
- Return: void
- Params: none
Set Font ID
This method assigns a font ID for display of the component value.
- Method: SetFontID(int FontID)
- Return: void
- Param0: (FontID) A valid font ID, either an object handle created by
the sys.GetFont method, or an integer to specify the default
system font: 0=normal, 1=boldface.
Progressbar
Increment Value
This method increments the current number of displayed increments
in the progress bar by one. Each increment in the progress bar displays a small solid colored
rectangular shape. Increments beyond the current maximum have no effect.
- Method: IncrementValue()
- Return: void
- Params: none
Set Maximum
This method assigns the number of increments in the
progress bar. Each increment in the progress bar displays a small solid colored
rectangular shape.
- Method: SetMaximum(int nMaxVal)
- Return: void
- Param0: (nMaxVal) An integer value, such as 10 or 20. The wider the progress bar,
the larger this value should probably be.
Set Value
This method assigns the current number of displayed increments
in the progress bar. Each increment in the progress bar displays a small solid colored
rectangular shape. Assign zero (0) to display an empty progress bar. Display the
maximum value to display a "full" progress bar.
- Method: SetValue(int nValue)
- Return: void
- Param0: (nValue) An integer value, from zero (0) to the current maximum value.
Table
Index of Table Methods
Clear All Row Selections
This method deselects all selected table rows and
clears the row selection highlighting.
- Method: ClearRowSelection()
- Return: void
- Params: none
Get Data from One Table Cell
This method gets the current value in one table
cell (a specified row and column).
- Method: GetCellData(int nRow, int nCol)
- Return: string
- Param0: (nRow) An integer row number in which to assign the cell value,
starting with 0 (zero) for the top row.
- Param1: (nCol) An integer column number in which to assign the cell
value, starting with 0 (zero) for the leftmost column.
Get the Number of Populated Table Rows
This method gets an integer that is the number of populated
table rows in the table. The value returned is the last populated row number plus one.
Note that this may include embedded empty rows that occur before the last populated row.
- Method: GetRowCount()
- Return: int
- Params: none
Get Row Values as a Delimited List
This method returns a delimited list of all the column values
in the specified table row.
- Method: GetRowText(int nRow, string delimiter)
- Return: string
- Param0: (nRow) An integer row number, starting with 0 (zero) for the top row.
- Param1: (delimiter) A character or string used to separate values in the list.
Get Selected Column Number
This method gets an integer that is the column
number of the most recently selected column in the table (note that the
leftmost column in a table is column zero).
- Method: GetSelectedColumn()
- Return: int
- Params: none
Get Selected Row Number
This method gets an integer that is the row
number of the most recently selected row in the table (note that the
top row in a table is row zero).
- Method: GetSelectedRow()
- Return: int
- Params: none
Insert a New Row at a Specified Location
This method inserts a new row at the specified row location in the table.
- Method: InsertRow(int nRow)
- Return: boolean (true if row was inserted, false if not)
- Param1: (nRow) An integer row number before which a new row is to be inserted into the table.
Specify 0 (zero) to insert a new row at the top of the table.
Specify 1 (one) to insert after the top row, etc.
Remove All Rows
This method removes all rows from a table and clears the row
selection highlighting. It also repositions the visible cells so that the first
visible column of row 0 is in the upper left-hand corner.
- Method: RemoveAllItems()
- Return: void
- Params: none
Remove a Row From a Table
This method removes the specified row from the table.
- Method: RemoveRow(int nRow)
- Return: boolean (true if row was removed, false if not)
- Param1: (nRow) An integer row number to be removed from the table,
starting with 0 (zero) for the top row.
Refresh the Table Display
This method forces a redisplay of the table so
that new values will be made visible immediately.
- Method: Repaint()
- Return: void
- Params: none
Reset All Table Colors to the Defaults
This method resets the foreground (FG) and background (BG) colors
on all rows in the table to the default initial color scheme.
- Method: ResetAllColors()
- Return: void
- Params: none
Set FG/BG Colors for One Table Cell
This method sets the foreground (FG) and background (BG) colors
for one cell in the table. Colors are specified by standard Red/Green/Blue integer
values, ranging from 0 to 255 each, where "0,0,0" is black and "255,255,255" is white.
- Method: SetCellColors(int nRow, int nCol,
int FG_Red, int FG_Green, int FG_Blue,
int BG_Red, int BG_Green, int BG_Blue)
- Return: void
- Param0: (nRow) An integer row number in which to assign the specified colors,
starting with 0 (zero) for the top row.
- Param1: (nCol) An integer column number in which to assign the specified colors,
starting with 0 (zero) for the leftmost column.
- Param2: (FG_Red) The foreground red value (0-255).
- Param3: (FG_Green) The foreground green value (0-255).
- Param4: (FG_Blue) The foreground blue value (0-255).
- Param5: (BG_Red) The background red value (0-255).
- Param6: (BG_Green) The background green value (0-255).
- Param7: (BG_Blue) The background blue value (0-255).
Assign a Value to One Table Cell
This method assigns or changes the contents
of one cell in a table. Both the row and column numbers must be specified,
and both are numbered starting with zero (not one).
- Method: SetCellData(int nRow, int nCol, string cellText)
- Return: void
- Param0: (nRow) An integer row number in which to assign the cell value,
starting with 0 (zero) for the top row.
- Param1: (nCol) An integer column number in which to assign the cell
value, starting with 0 (zero) for the leftmost column.
- Param2: (cellText) A character string to be assigned as a cell value.
Assign Values to a Combobox Table Cell
This method assigns choices to one table cell that has an editor
type of combobox (2). The choices are delimited by a specified delimiter (which allows
commas in the choice values if the delimiter is not a comma, for instance).
- Method: SetCellEditorList(int nRow, int nCol, string choiceList, string delimiter)
- Return: void
- Param0: (nRow) An integer row number in which to assign the specified combobox choices,
starting with 0 (zero) for the top row.
- Param1: (nCol) An integer column number in which to assign the specified combobox choices,
starting with 0 (zero) for the leftmost column.
- Param2: (choiceList) A delimiter-separated string of combobox values.
- Param3: (delimiter) A character string used to separate values in the choiceList.
Example: table0.SetCellEditorList(0, 0, "first choice^second choice", "^");
Set Cell Editor Type
This method assigns an editor type to one table cell. The
editor type can be a textfield (type 0 or 1), a combobox (type 2) or a checkbox (type 3).
This method is normally used only for editable table columns.
- Method: SetCellEditorType(int nRow, int nCol, int nEditorType)
- Return: void
- Param0: (nRow) An integer row number in which to assign the specified editor type,
starting with 0 (zero) for the top row.
- Param1: (nCol) An integer column number in which to assign the specified editor type,
starting with 0 (zero) for the leftmost column.
- Param2: (nEditorType) An editor type. Supported values are:
0 or 1 = textfield, 2 = combobox, 3 = checkbox.
Set Cell Font ID
This method assigns a font ID for display of a cell value. This
method can be used with text or hyperlink cell values.
- Method: SetCellFontID(int nRow, int nCol, int FontID)
- Return: void
- Param0: (nRow) An integer row number in which to assign the specified font,
starting with 0 (zero) for the top row.
- Param1: (nCol) An integer column number in which to assign the specified font,
starting with 0 (zero) for the leftmost column.
- Param2: (FontID) A valid font ID. Supported values are: 0=normal, 1=boldface.
Assign a Column Label
This method assigns or changes the contents
of one column label in a table. Column numbers are specified starting
with zero (not one).
- Method: SetColumnHeading(int nCol, string headingText)
- Return: void
- Param0: (nCol) An integer column number for which to assign the column
header, starting with 0 (zero) for the leftmost column.
- Param1: (headingText) A character string to be assigned as a column
header value.
Set FG/BG Colors for All Cells in a Row
This method sets the foreground (FG) and background (BG) colors
for all cells in a specified row of a table. Colors are specified by standard
Red/Green/Blue integer values, ranging from 0 to 255 each,
where "0,0,0" is black and "255,255,255" is white.
- Method: SetRowColors(int nRow,
int FG_Red, int FG_Green, int FG_Blue,
int BG_Red, int BG_Green, int BG_Blue)
- Return: void
- Param0: (nRow) An integer row number in which to assign the specified colors,
starting with 0 (zero) for the top row.
- Param1: (FG_Red) The foreground red value (0-255).
- Param2: (FG_Green) The foreground green value (0-255).
- Param3: (FG_Blue) The foreground blue value (0-255).
- Param4: (BG_Red) The background red value (0-255).
- Param5: (BG_Green) The background green value (0-255).
- Param6: (BG_Blue) The background blue value (0-255).
Assign Values to a Row of Table Cells
This method assigns or changes the contents
of all the cells in one row of a table. The row number must be specified,
and is numbered starting with zero (not one).
- Method: SetRowText(int nRow, string rowData, string delimiter)
- Return: void
- Param0: (nRow) An integer row number in which to assign the cell values,
starting with 0 (zero) for the top row.
- Param1: (rowData) A delimiter-separated string of cell values.
- Param2: (delimiter) A character string used to separate values in the
rowData.
Example: table0.SetRowText(0, "hello, cell 0^hello, cell 1", "^");
Position Row within Viewable Area of Table
This method scrolls the table up or down so
that the specified row is at the top, center or bottom of the viewable
area of the table.
- Method: SetRowVisible(int nRow, int nPos)
- Return: void
- Param0: (nRow) An integer row number to be positioned, starting with zero
for the first row in the table.
- Param1: (nPos) Where to position the column: 0=top 1=center 2=bottom
Set Selected Row Number
This method selects a row in the table.
- Method: SetSelectedRow(int nRow)
- Return: void
- Param1: (nRow) An integer row number to be selected,
starting with 0 (zero) for the top row.
Textarea
Index of Textarea Methods
Append Text
This method appends a string value to an existing
value in a textarea. The new value will be immediately displayed if the
textarea is currently visible.
- Method: Append(string text)
- Return: void
- Param0: (text) A character string to be appended to an existing textarea
value.
Get Cursor Position
This method gets the byte offset of the current location of the insertion cursor. If there
is no current location, returns -1.
- Method: GetCursorPosition()
- Return: int
- Params: none
Get Selected Text
This method gets the currently selected string from the textarea. If no characters are
selected, returns an empty string ('').
- Method: GetSelectedText()
- Return: string
- Params: none
Get Selection Position
This method gets the byte offset of the first character of the currently selected string within
the textarea. If no string is selected, returns the position of the insertion cursor if any, otherwise -1.
- Method: GetSelectionPosition()
- Return: int
- Params: none
Get Current Value
This method gets the string value of the current
contents of a textarea.
- Method: GetText()
- Return: string
- Params: none
Get Window Position
This method gets the byte offset of the first character in the currently displayed
top line of the textarea window.
- Method: GetWindowPosition()
- Return: int
- Params: none
Insert Text
This method inserts the specified text at (before) the character
at the specified byte offset. The textarea is not repositioned (the current top line
stays at the top). If nByteOffset is negative, it prepends the text to the textarea value.
If nByteOffset is greater than the length of the textarea contents, it appends the text
to the textarea value.
- Method: InsertText(string text, int nByteOffset)
- Return: void
- Param0: (text) A character string to be inserted at a specified offset within an existing textarea value.
- Param1: (nByteOffset) Byte offset of specified character within the textarea.
Replace Selected Text
This method replaces the currently selected string in the textarea with the specified
new text. If no string is selected, this method behaves like InsertText if the insertion cursor has a
current position. The textarea is not repositioned (the current top line stays at the top).
- Method: ReplaceSelectedText(string text)
- Return: void
- Param0: (text) A character string to replace selected text in a textarea
value.
Set Cursor Position
This method sets the current location of the insertion cursor to the left of the character
at the specified byte offset. If nByteOffset is negative, it sets the location at offset zero. If nByteOffset
is greater than length of the textarea contents, it sets the location after the last character in the textarea.
- Method: SetCursorPosition(int nByteOffset)
- Return: void
- Param0: (nByteOffset) Byte offset of specified character within the textarea.
Set Focus on Textarea
This method sets "focus" on a textarea, so that entered
data will go into the specified textarea.
- Method: SetFocus()
- Return: void
- Params: none
Set Font ID
This method assigns a font ID for display of the component value.
- Method: SetFontID(int FontID)
- Return: void
- Param0: (FontID) A valid font ID, either an object handle created by
the sys.GetFont method, or an integer to specify the default
system font: 0=normal, 1=boldface.
Set Selected Text
This method selects (and highlights) the number of characters specified by nLength, starting
with the character at nByteOffset. If nLength is zero, the insertion cursor will be positioned at the specified
offset but no characters will be selected. If nByteOffset is negative or greater than the length of the textarea
contents, the insertion cursor may be repositioned but no characters will be selected.
- Method: SetSelectedText(int nByteOffset, int nLength)
- Return: void
- Param0: (nByteOffset) Byte offset of first character to be selected.
- Param1: (nLength) The number of characters to be selected.
Display Text
This method assigns a value to a textarea.
The new value will be immediately displayed if the textarea is currently
visible.
- Method: SetText(string text)
- Return: void
- Param0: (text) A character string to be assigned as a textarea value.
This value may contain line feed characters, which will override the automatic
word wrap feature of the textarea, to allow user-controlled text placement
(as with a name/address display).
Set Window Position
This method positions the text line containing the character at the specified nByteOffset
to the specified windowLocation in the textarea window: 0=top 1=middle 2=bottom.
- Method: SetWindowPosition(int nByteOffset, int nWindowLocation)
- Return: void
- Param0: (nByteOffset) Byte offset of specified character within the textarea.
- Param1: (nWindowLocation) Where to display the line containing the specified character within the textarea
viewing area:0=top 1=middle 2=bottom. This behavior is not strictly observed when referencing the first or last
few lines of the textarea contents, or if the contents have fewer lines than the textarea window allows.
Textfield
Index of Textfield Methods
Get Cursor Position
This method gets the byte offset of the current location of the insertion cursor. If there
is no current location, returns -1.
- Method: GetCursorPosition()
- Return: int
- Params: none
Get Selected Text
This method gets the currently selected string from the textfield. If no characters are
selected, returns an empty string ('').
- Method: GetSelectedText()
- Return: string
- Params: none
Get Selection Position
This method gets the byte offset of the first character of the currently selected string within
the textfield. If no string is selected, returns the position of the insertion cursor if any, otherwise -1.
- Method: GetSelectionPosition()
- Return: int
- Params: none
Get Current Value (as Character String)
This method gets the character value of
the current contents of a textfield as a "string" data type.
- Method: GetText()
- Return: string
- Params: none
Insert Text
This method inserts the specified text at (before) the character
at the specified byte offset. If nByteOffset is negative, it prepends the text to the textfield value.
If nByteOffset is greater than the length of the textfield contents, it appends the text
to the textfield value.
- Method: InsertText(string text, int nByteOffset)
- Return: void
- Param0: (text) A character string to be inserted at a specified offset within an existing textfield value.
- Param1: (nByteOffset) Byte offset of specified character within the textfield.
Replace Selected Text
This method replaces the currently selected string in the textfield with the specified
new text. If no string is selected, this method behaves like InsertText if the insertion cursor has a
current position.
- Method: ReplaceSelectedText(string text)
- Return: void
- Param0: (text) A character string to replace selected text in a textarea
value.
Set Cursor Position
This method sets the current location of the insertion cursor to the left of the character
at the specified byte offset. If nByteOffset is negative, it sets the location at offset zero. If nByteOffset
is greater than length of the textfield contents, it sets the location after the last character in the textfield.
- Method: SetCursorPosition(int nByteOffset)
- Return: void
- Param0: (nByteOffset) Byte offset of specified character within the textfield.
Set Focus on Textfield
This method sets "focus" on a textfield, so that entered
data will go into the specified textfield.
- Method: SetFocus()
- Return: void
- Params: none
Set Font ID
This method assigns a font ID for display of the component value.
- Method: SetFontID(int FontID)
- Return: void
- Param0: (FontID) A valid font ID, either an object handle created by
the sys.GetFont method, or an integer to specify the default
system font: 0=normal, 1=boldface.
Set Selected Text
This method selects (and highlights) the number of characters specified by nLength, starting
with the character at nByteOffset. If nLength is zero, the insertion cursor will be positioned at the specified
offset but no characters will be selected. If nByteOffset is negative or greater than the length of the textfield
contents, the insertion cursor may be repositioned but no characters will be selected.
- Method: SetSelectedText(int nByteOffset, int nLength)
- Return: void
- Param0: (nByteOffset) Byte offset of first character to be selected.
- Param1: (nLength) The number of characters to be selected.
Display Text
This method assigns a value to a textfield.
The new value will be immediately displayed if the textfield is currently
visible.
- Method: SetText(string text)
- Return: void
- Param0: (text) A character string to be assigned as the textfield value.
Textpane
Index of Textpane Methods
Append Text
This method appends a string value to an existing
value in a textpane. The new value will be immediately displayed if the
textpane is currently visible.
- Method: Append(string text)
- Return: void
- Param0: (text) A character string to be appended to an existing textarea
value.
Get Current Value
This method gets the string value of the current
contents of a textpane.
- Method: GetText()
- Return: string
- Params: none
Set Font ID
This method assigns a font ID for display of the component value.
- Method: SetFontID(int FontID)
- Return: void
- Param0: (FontID) A valid font ID, either an object handle created by
the sys.GetFont method, or an integer to specify the default
system font: 0=normal, 1=boldface.
Display Text
This method assigns a value to a textpane.
The new value will be immediately displayed if the textpane is currently
visible.
- Method: SetText(string text)
- Return: void
- Param0: (text) A character string to be assigned as a textpane value.
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).
Tree
Note: available on Windows platforms only.
Index of Tree Methods
Collapse a Node
This method collapses 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.
- Method: CollapseNode(string nodeName)
- Return: void
- Param0: (nodeName) The internal name of a tree node.
Expand a Node
This method expands a collapsed parent node
so that its immediate child nodes will be displayed. Note that the expansion
is not recursive, meaning that this method does not expand "grandchild"
nodes (nodes under any child node that has its own child nodes).
- Method: ExpandNode(string nodeName)
- Return: void
- Param0: (nodeName) The internal name of a tree node.
Get Image Index of a Node
This method gets the integer value that specifies
the image filename for a specified node.
- Method: GetNodeImageIndex(string nodeName)
- Return: int
- Param0: (nodeName) The internal name of a tree node.
Get Text of a Node
This method gets the string value of the displayed
text for a specified node.
- Method: GetNodeText(string nodeName)
- Return: string
- Param0: (nodeName) The internal name of a tree node.
Get Tooltip of a Node
This method gets the string value of the tooltip
for a specified node.
- Method: GetNodeTooltip(string nodeName)
- Return: string
- Param0: (nodeName) The internal name of a tree node.
Get User Data of a Node
This method gets the string value of the "user
data" attribute for a specified node.
- Method: GetNodeUserData(string nodeName)
- Return: string
- Param0: (nodeName) The internal name of a tree node.
Get Name of Currently Selected Node
This method gets the string value that is the
internal name of the currently selected node.
- Method: GetSelectedNodeName()
- Return: string
- Params: none
Get User Data of Currently Selected Node
This method gets the string value of the "user
data" attribute of the currently selected node.
- Method: GetSelectedNodeUserData()
- Return: string
- Params: none
Insert a Node
This method adds a node to a tree, either under
the tree "root" node itself, or under any other node in the tree.
- Method: InsertNode(string parentNodeName, string nodeName, string nodeText,
string nodeuserData, string nodeTooltip, int nImageIndex, int nNodeIndex)
- Return: void
- Param0: (parentNodeName) The internal name of an existing node in the
target 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.
- Param1: (nodeName) The internal name to assign to the new child node.
(Must be unique within the client app).
- Param2: (nodeText) The text to display as the caption for the new node.
(Cannot be blank).
- Param3: (nodeUserData) (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.
- Param4: (nodeTooltip) (Optional) A character string containing a one-line
help message used as the tooltip for the new node
- Param5: (nImageIndex) (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.
- Param6: (nNodeIndex) (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.
Remove Child Nodes of a Node
This method removes all child nodes under the
specified parent node. This removal is recursive, so "grandchild" nodes
and lower levels of nodes will also be removed.
- Method: RemoveChildNodes(string nodeName)
- Return: void
- Param0: (nodeName) The internal name of a tree node.
Remove a Node
This method removes the specified node. This
removal is recursive, so any child nodes and their children will also be
removed.
- Method: RemoveNode(string nodeName)
- Return: void
- Param0: (nodeName) The internal name of a tree node.
Repaint a Tree
This method repaints the target tree. If the
text or image index of any nodes have been changed, this will redisplay
the new text and images.
- Method: Repaint()
- Return: void
- Params: none
Set Image Index of a Node
This method sets the integer value that specifies
the image filename for a specified node.
- Method: SetNodeImageIndex(string nodeName, int nImageIndex)
- Return: void
- Param0: (nodeName) The internal name of a tree node.
- Param1: (nImageIndex) 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.
Set Text of a Node
This method sets the displayed text for a specified
node.
- Method: SetNodeText(string nodeName, string nodeText)
- Return: void
- Param0: (nodeName) The internal name of a tree node.
- Param1: (nodeText) 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.
Set Tooltip of a Node
This method sets the tooltip for a specified
node.
- Method: SetNodeTooltip(string nodeName, string nodeTooltip)
- Return: void
- Param0: (nodeName) The internal name of a tree node.
- Param1: (nodeTooltip) 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.
Set User Data of a Node
This method sets the "user data" attribute
for a specified node.
- Method: SetNodeUserData(string nodeName, string nodeData)
- Return: void
- Param0: (nodeName) The internal name of a tree node.
- Param1: (nodeData) A character string that will become the value of
the "user data" attribute for the specified node.
Select a Node
This method selects the specified node. This
will cause the specified node entry in the tree to become highlighted and
will also fire the TreeSelection event.
- Method: SetSelectedNode(string nodeName)
- Return: void
- Param0: (nodeName) The internal name of a tree node.
Methods for Global Objects
These methods are used with various "global" objects
that are not part of the visible user interface. These non-visual objects and
methods provide system functions, interfaces to ports, peripherals and file systems,
host request and response processing, and startup preferences.
System Methods
These methods are all used with the "sys" object,
which is a system-wide (global) object that is not associated with any
one application or component.
System Methods: General
Exit (end application session)
This method does an "application exit", which ends
the current session and returns to the Jargon Reader initial ApplicationMenu
program. It can be the last statement in a function that is associated with
a "Logout" button, for example.
- Method: Exit()
- Return: void
- Params: none
Quit (terminate Reader)
This method completely ends the Jargon Reader program and closes
any open frames. It can be the last statement in a function that is associated with
a "End" button, for example.
- Method: Quit()
- Return: void
- Params: none
Load Arrow Cursor
This method sets the cursor image to the normal "arrow" pointer.
- Method: LoadArrowCursor()
- Return: void
- Params: none
Load Wait Cursor
This method sets the cursor image to the normal "busy" pointer.
On PocketPC devices, the wait cursor is the standard multi-colored PPC "circle".
On desktop and laptop PCs, it is the standard Windows hourglass.
- Method: LoadWaitCursor()
- Return: void
- Params: none
Get Event Source Name
This method gets the name of the component on
which the most recent event occurred.
- Method: GetEventSourceName()
- Return: string
- Params: none
Get Product Name
This method gets the name of the specific Jargon
Reader engine in which the application is currently being run. Values are in the
form "ReaderXXX", where XXX is an acronym for the platform, as documented in the
product release notes. For example, "ReaderPDA" is the Jargon PDA Emulator,
"ReaderPPC" is the Pocket PC version without Oracle DB support,
"ReaderPPO" is the Pocket PC version with Oracle DB support, etc.
This method may be used to determine whether device-specific logic can be (or
should be) run.
- Method: GetProductName()
- Return: string
- Params: none
Get Executable Path
This method gets the path where the Jargon Reader executable
file (e.g. ReaderWIN.exe) is located.
- Method: GetExecutablePath()
- Return: string
- Params: none
Run Operating System Executable
This method runs an executable Windows program or built-in
command. The pathname is specified as it would be in the Windows "Run" window.
This object is supported on 32-bit Windows platforms only (ReaderWIN.exe).
- Method: OSExec(string pathName)
- Return: void
- Param0: (pathName) The full or relative pathname of an executable file or other
supported Windows command.
Examples:
sys.OSExec('regedit') to edit the Registry (a frequent Windows activity).
sys.OSExec('notepad readme.txt') to open NotePad to view a readme file.
Get Open File Name
This method gets a file name to be opened, using
a standard Windows "Open File" dialog box. The default file types are "XML" and "All",
however the "Files of Type" list choices can be overriden by an optional parameter.
(ReaderWIN only).
- Method: GetOpenFileName(string startInDir [, string filenameFilters])
- Return: string
- Param0: (startInDir) The name of the directory in which the "File Open" window
will start.
- Param1: (nameFilters) This OPTIONAL parameter specifies a list of one or more
file type choices (description and wildcard filename filter) for the "Files of Type"
listbox in the Open window. Choices are in pairs of comma-separated values.
Example: "Text files,*.txt,Doc files,*.doc"
Get Save File Name
This method gets a file name to be saved, using
a standard Windows "Save As" dialog box. The default file types are "XML" and "All",
however the "files of type" list choices can be overriden by an optional parameter.
(ReaderWIN only).
- Method: GetSaveFileName(string startInDir [, String nameFilters] )
- Return: string
- Param0: (startInDir) The name of the directory in which the "Save As" window
will start.
- Param1: (nameFilters) This OPTIONAL parameter specifies a list of one or more
file type choices (description and wildcard filename filter) for the "Files of Type"
listbox in the Open window. Choices are in pairs of comma-separated values.
Example: "Text files,*.txt,Doc files,*.doc"
Play Sound File
This method plays an audio (sound) file such as a ".WAV" audio file.
- Method: PlaySound(string filename)
- Return: void
- Param0: (filename) The local pathname of a sound file to be played,
such as "C:\jargonsoft\data\hello.wav".
Process CIO Instructions
This method executes one or more CIO (Component
Instruction Object) instructions received from a host procedure.
Show Web Document
(Note: implemented on Windows PCs only, using ReaderPDA.exe or ReaderWin.exe).
This method displays a web document such as an HTML web page, a PDF
document file, an image file, or any other valid browser object with a specified
URL, in a web browser on a client PC. The browser is invoked on the client PC
using the default web browser defined in the Windows registry.
A new browser window will be opened each time this method is executed.
- Method: ShowDocument(string url)
- Return: void
- Param0: (url) The remote URL or local pathname of the document to be displayed
in the browser, such as "http://www.jargonsoft.com/index.html"
or "C:\jargonsoft\doc\index.html".
System Methods: Fonts
Get Font
This method gets a handle to a "font object" with the specified
font face, point size, and optional bold and underline styles. The last two
parameters are optional and may not work for all fonts. The handle returned from
GetFont() is good for the entire Reader session, and is used by the SetFontID
method of various text components such as textfields and textareas.
Note: this method was previously named "CreateFont()", which is still supported
but should not be used in new development.
- Method: GetFont(String facename, int size [, boolean bBold [, boolean bUnderline]])
- Return: object handle
- Param0: (facename) A character string for the name of a font face, as it appears
in ControlPanel-->Fonts.
- Param1: (size) An integer font point size, such as 10, 12, 15, etc. Some fonts
only offer certain point sizes while others are scaleable.
- Param2: (bBold) A boolean value: true to display in boldface, false for regular face.
Some fonts are designed to be bold and will be bold regardless of the bBold param.
- Param3: (bUnderline) A boolean value: true to underline, false for no underline. If this
optional parameter is specified, the bBold parameter must also be specified.
Example:
var nFontID = sys.GetFont("Courier", 12, false, false);
frame0.SetVisible(true);
textarea0.SetFontID(nFontID);
Set Default Font
This method sets the default system font with the specified
font face and point size. This system font is used for all text displayed in
components, such as labels, table column headings, checkbox captions, contents of
textfields, textareas and textpanes, etc. The default is MS Sans Serif 9.
After changing the default font, the app must do a frame.DoLayout() to recalculate the
component sizes on any frames that have been visible in the current or previously
cached session. All frames that have never been rendered before in the current or
previously cached sessions will be rendered using the new default font.
Note that SetVisible and Repaint only use the existing cached font sizes.
- Method: SetDefaultFont(String facename, int size)
- Return: object handle
- Param0: (facename) A character string for the name of a font face, as it appears
in ControlPanel-->Fonts.
- Param1: (size) An integer font point size, such as 10, 12, 15, etc. Some fonts
only offer certain point sizes while others are scaleable.
Example:
frame0.SetVisible(true);
. . . // other stuff happens
sys.SetDefaultFont("MS Sans Serif", 10);
frame0.DoLayout(); // recalculate font sizes in currently visible frame
System Methods: Timer
Set Timer Callback
This method assigns a function to be executed in a specified app
after a timer has been started and has run for a specified number of milliseconds.
After each execution, the timer is reset and this process will repeat until the
timer is stopped. Note that during the execution of the specified function, any user
interface events will be blocked, so you should not set the timer interval to a value
that is too brief or the user may not be able to click a button that runs a function
to stop it (unless the timer will eventually be stopped automatically by the program).
- Method: SetTimerProc(int milliseconds, string appName, string functionName)
- Return: void
- Param0: (milliseconds) The number of milliseconds the timer will wait before firing.
For example, a value of 5000 specifies a timer that fires every 5 seconds.
- Param1: (appName) A character string for the name of the client xml
application that contains the function to be run, without the ".xml" suffix.
- Param2: (functionName) A character string for the name of the function
within the app to be run when the specified timer period has elapsed.
Examples:
sys.SetTimerProc(5000, thisApp, "RefreshHostData");
Start Timer
This method starts the timer. The SetTimerProc method should be
run first to specify a callback procedure before using this method.
- Method: StartTimer()
- Return: void
- Params: none
Stop Timer
This method stops the timer.
- Method: StopTimer()
- Return: void
- Params: none
System Methods: Message Boxes
Message Box
This method displays an informational message
to the user, in a modal dialog box with an OK button.
- Method: MessageBox(string msg)
- Return: void
- Param0: (msg) A character string for a multi-line message to be displayed
in the message box. Use the newline escape sequence ('\n') to split lines.
Warning Box
This method displays an error or warning message
to the user, in a modal dialog box with an OK button. Similar to "message
box" except that the warning box uses a different icon image.
- Method: WarningBox(string msg)
- Return: void
- Param0: (msg) A character string for a multi-line message to be displayed
in the warning box. Use the newline escape sequence ('\n') to split lines.
Dialog Box
This method displays a message to the user in a
modal dialog box with a choice of certain button combinations. It returns a
string containing the label of the selected button (e.g. "OK", "Cancel" etc.).
- Method: DialogBox(string title, string prompt,
string iconCode, string buttonList, string defaultButton)
- Return: string
- Param0: (title) A character string for an (optional) title to be displayed
in the frame header of the dialog box. Can be the empty string ("").
- Param1: (prompt) A character string for a multi-line message to be displayed
in the dialog box. Use the newline escape sequence ('\n') to split lines. Messages
will also auto-wrap if needed.
- Param2: (iconCode) A one-character code for the image to be displayed
in the dialog box to the left of the prompt message. Codes can be in upper or lower
case. Valid codes are:
I/i - info - information symbol
Q/q - query - question mark
W/w - warning - exclamation mark
E/e - error - error symbol (circled X)
- Param3: (buttonList) A character string containing a comma-separated list of
the button labels to be displayed in the dialog box. Only the following sets of
button lists are supported:
"OK", "OK,Cancel", "Retry,Cancel", "Yes,No", "Yes,No,Cancel"
- Param4: (defaultButton) A character string for the label of the button
that is the default (will be auto-selected if Enter key or spacebar is pressed).
If this value is not in the buttonList value, the first button will be the default.
Example:
sys.DialogBox("Dialog Demo", "To Be\nOr Not To Be?",
"Q", "Yes,No", "Yes")
System Methods: Managing Apps
Get Installed App List
This method gets a comma-separated list of the
names of the currently installed (cached) xml application files.
- Method: GetInstalledAppList()
- Return: string
- Params: none
Load App Configuration
This method installs (caches) the configuration
(".ini" file) data for an xml application file. If successful, it returns
the value of the AppName parameter.
- Method: LoadAppConfig(string configData)
- Return: string
- Param0: (configData) A character string containing multiple lines
of "name=value" preference parameters, with lines separated by newlines.
Typically this data will be obtained from the http request buffer after a
request for a ".ini" file. Example of a typical ".ini" file:
AppRootDir=http://www.jargonsoft.com/V3/xml/demo32
AppName=menu
HostURL=http://www.jargonsoft.com
Script=scripts/wsisa.dll/WService=sports2000
Open App
This method opens a cached client xml application
file into working memory, and optionally runs its initial function.
If a configuration (".ini" file) has been previously received and loaded
with the "sys.LoadAppConfig" method, then its preferences are used for the app,
otherwise the new app will "inherit" the AppRootURL, HostURL and Script values
of the invoking app, and only the AppName will be different.
If not already cached, the xml file to be opened will first be downloaded
from the AppRootDir (as specified above) and cached on the local device.
An optional second boolean parameter controls whether the init tasklist of
the new app will be run. The default is 'true' to run it. Since the script
engine won't recognize the newly opened app until the process that opened it
ends, a new callback method "sys.SetOpenCallback" has been implemented to
return control to a specified app/function after an app has been opened.
This callback can be used whether or not the app's initial function is also
run, and if so the callback function will be run after the opened app's
initial function completes.
- Method: OpenApp(string appName [, boolean runInit])
- Return: void
- Param0: (appName) The name of the client xml application to be opened,
without the ".xml" suffix.
- Param1: (runInit) An OPTIONAL boolean value. Use "true" (the default) to
run the initial function of the app after opening it, or "false" to only open the
app without running any of its functions. Normally the initial function makes a
frame visible, so this essentially determines whether control passes to the new
app, on platforms where only one frame at a time can be visible. If so, no
callback routine is required, although one can be used if desired. If no frame
in the opened app is made visible, a callback routine should be set before
running the OpenApp method if further processing steps are to be done.
SetOpenCallback
This method assigns a function to be executed in a specified app
after an app has been opened. If the opened app runs its init function, this
callback function will be run after the init function is completed. The specified
function may be in the app being opened, the calling app, or some third app.
If the app or function name is an empty string, then the execution thread ends and no
other action is taken until the user interacts with whatever frame is visible.
After the specified callback function has run following the opening of an
app, both the appName and functionName parameters are cleared, so they will not
be used on the next app open unless this method is run again. You may also explicitly
clear the callback parameters at any time with sys.SetOpenCallback('',''), however
this is usually not necessary.
- Method: SetOpenCallback(string appName, string functionName)
- Return: void
- Param0: (appName) A character string for the name of the client xml
application that contains the function to be run, without the ".xml" suffix.
- Param1: (functionName) A character string for the name of the function
within the app to be run after completing the opening of another app.
Examples:
sys.SetOpenCallback(thisApp, "AfterOpening");
sys.SetOpenCallback("", ""); // to clear the callback
Update App
This method updates the specified xml application file by
replacing the current cached copy with a new copy from the server. A new copy of the
xml file will be downloaded from the specified AppRootDir, then cached and opened.
- Method: UpdateApp(string appName [, boolean runInit])
- Return: void
- Param0: (appName) The name of the client xml application to be updated,
without the ".xml" suffix.
- Param1: (runInit) An OPTIONAL boolean value. Use "true" (the default) to
run the initial function of the app after updating it, or "false" to only update the
app without running any of its functions. Normally the initial function makes a
frame visible, so this essentially determines whether control passes to the new
app, on platforms where only one frame at a time can be visible. If so, no
callback routine is required, although one can be used if desired. If no frame
in the updated app is made visible, a callback routine should be set before
running the UpdateApp method if further processing steps are to be done.
Save App
This method saves the contents of the specified xml application
from working memory to the local device cache. This is done automatically when an app
is closed, however this method allows it to be done programatically, on an event such
as a user button press, or every 'n' seconds when a system timer event fires.
- Method: SaveApp(string appName)
- Return: void
- Param0: (appName) The name of the client xml application to be saved,
without the ".xml" suffix.
Close App
This method closes the specified xml application file
by removing it from working memory. It will still remain in the local device cache,
but its objects and methods will no longer be accessible from script functions.
If a frame from this app is rendered it will be closed, and if it is the only
currently visible frame, this method will also call the init() function of the
Jargon Reader ApplicationMenu startup routine. This method may be used to conserve
memory on resource-limited platforms.
- Method: CloseApp(string appName)
- Return: void
- Param0: (appName) The name of the client xml application to be closed,
without the ".xml" suffix.
Delete App
This method deletes the specified xml application file
from the local cache.
- Method: DeleteApp(string appName)
- Return: void
- Param0: (appName) The name of the client xml application to be deleted
from the cache, without the ".xml" suffix.
Test If App Is Configured
This method tests whether the "configuration preferences"
for the specified xml client application file have been installed. These preferences
can be installed by loading an ".ini" file or by directly opening the app and
thereby inheriting the calling app's preferences. The minimum set of required
configuration preferences are "AppRootDir", "AppName", "HostURL" and "Script".
- Method: IsAppConfigured(string appName)
- Return: boolean (true if configuration is loaded, false if not)
- Param0: (appName) The name of the client xml application to be tested,
without the ".xml" suffix.
Test If App Is Cached
This method tests whether the specified xml client
application file has been cached (installed) on the local device. An app can be
cached by the OpenApp or UpdateApp methods.
- Method: IsAppCached(string appName)
- Return: boolean (true if the app is cached, false if not)
- Param0: (appName) The name of the client xml application to be tested,
without the ".xml" suffix.
Test If App Is Open
This method tests whether the specified xml client
application file has been opened (loaded from cache into working memory) during
the current execution session. An app can be opened by the OpenApp or
UpdateApp methods. If an app is open, its objects and methods can be
accessed from script functions, but it may or may not have any visible
frames.
- Method: IsAppOpen(string appName)
- Return: boolean (true if the app is open, false if not)
- Param0: (appName) The name of the client xml application to be tested,
without the ".xml" suffix.
Host Call Methods
There are three global system objects and related methods
that can be used to send a request to a remote server and to process the data
that it sends back to the client in response.
-
The "http" object is the preferred
choice for doing all server requests. It MUST be used when SSL encryption is
required, or when the server response may be data other than CIO command sets, such
as image data, textual data, XML data from a "Web service", etc. When data from an
http request is received, NO automatic processing is done. Instead, when the
receiving of data is complete, a script function is executed, that was previously
registered with the "http.SetNotifyProc" method (see below).
-
The "rpc" object can be used
when running a business procedure
on a remote host that is known to return Component Instruction Object ("CIO")
command sets in standard Jargon Software format. These CIO commands are
the output from the "jsi" host methods. When data from an rpc request is
received, the response buffer contents are automatically parsed and executed
as CIO commands.This object has been replaced by the "http" object and while
it will continue to be supported, developers should begin using http instead.
-
The "ftp" object can be used to send
a binary file to a remote host, or to retrieve a binary file from a remote host.
HTTP Methods
These methods are used with the global "http" (HyperText
Transmission Protocol) object to prepare and send a URL and optional POST
data to a remote server. The URL may specify a host procedure, a text file,
an image file, or any other valid URL object that the remote web server
can handle.
SetURL
This method creates the URL string that will
be used to access a remote server resource. It includes the "http://<host>"
string, while the rest of the string is application-specific. Specific
formatting of the URL must conform to the host resource being used.
- Method: SetURL(string url)
- Return: void
- Param0: (url) A character string for a URL, starting with "http://"
and ending with the resource to be accessed.
SetStopButtonVisible
This method views or hides the "Stop" button.
This button is displayed on the status line at the bottom of the screen during http requests.
This method can be used to prevent a user from manually halting an http request.
If the method is not used, the default is 'true' (view the stop button) which is consistent
with previous versions.
If the method is set to false, the button is not displayed, and so the user has no way
to cancel the request manually. Once set to false, the button will not be visible for all
subsequent HTTP operations, until it is set back to true.
- Method: SetStopButtonVisible(boolean ShowButton)
- Return: void
- Param1: (ShowButton) A boolean value: true to show http "Stop" button,
false to hide it
SetShowErrors
This method controls whether Jargon Reader will automatically
display system messages for any errors in http requests/responses. If this method
is not used, the default is 'true' (which is consistent with previous versions).
If SetShowErrors is set to false, the script can use the GetErrorCode method to determine
the type of error and display application-specific messages instead of system messages.
- Method: SetShowErrors(boolean ShowErrors)
- Return: void
- Param1: (ShowErrors) A boolean value: true to show system error messages,
false if not
SetNotifyProc
This method assigns a callback function to be executed
when the server response has been completely received. Both an appname and a function
name that exists in that app must be specified, or both can be set to empty strings.
Once assigned, these values remain in effect for every http
request until they are changed or cleared. If no app/function names are assigned via
this method in the current app before an http.SendRequest executes, then any values
that may have been set in a previous app will be used. In particular, the default
ApplicationMenu.xml startup menu app that is hardwired into Jargon Reader does the
following when loading an app ".ini" file:
http.SetNotifyProc(thisApp, "NotifyConfigRecvd");
The callback values can be reset by assigning empty
strings, e.g.
http.SetNotifyProc('', '');
If the values are empty (blank), then no callback is done, and
the response data will
simply sit in the response buffer and no other action is taken. This would allow, for
example, the http.GetResponseData() method to be used at some later time
within the script without doing so immediately upon receipt of the data.
Note: to emulate "rpc" functionality, simply use
SetNotifyProc to run a function that contains the single statement:
"sys.ProcessInstructions(http.GetResponseData())".
- Method: SetNotifyProc(string appName, string functionName)
- Return: void
- Param0: (appName) A character string for the name of the client xml
application that contains the function to be run, without the ".xml" suffix.
- Param1: (functionName) A character string for the name of the function
within the app to be run.
AddParam
This method assigns a name/value pair to be
used as an input parameter for the http request. The "name=value" data
pair will be appended to the URL string assigned by SetURL using standard
CGI/POST syntax.
- Method: AddParam(string name, string value [, string datatype])
- Return: void
- Param0: (name) A character string for the name of an input parameter.
- Param1: (value) A character string for the value of an input parameter.
- Param2: (datatype) An OPTIONAL character string for the data type of
an input parameter. Valid entries are "character", "integer", "decimal",
"date" and "logical". These values may be truncated, e.g. "char", "int",
"dec", "dat", "log". This optional parameter is used only
by the Progress 4GL Source Code Generator to create variables and parsing
routines of the desired data type, and is NOT used at runtime when this
method is executed.
SendRequest
This method sends the URL request to the remote server
(with no encryption).
- Method: SendRequest()
- Return: void
- Params: none
SendRequest (for SSL)
This method sends the URL request to the remote
server and specifies whether SSL encryption is to be used or not.
(The default is false if the parameter is omitted).
- Method: SendRequest(boolean UseSSL)
- Return: void
- Param1: (UseSSL) A boolean value: true to use SSL encryption, false if not
GetSuccess
This method gets the success or failure status
of the response from the remote server. Note that this should be tested before
using the GetResponseSize/Data methods below, as the buffer may contain an error
message of non-zero length, so a response length greater than zero does not ensure
that a valid response was received.
- Method: GetSuccess()
- Return: boolean (true if successful, false if web server returned an error status)
- Params: none
GetErrorCode
This method gets an error code specifying the type of error encountered
during the request or response. Use this method when SetShowErrors is false and GetSuccess
returns "false". Code values are given in the example below.
- Method: GetErrorCode()
- Return: int
- Params: none
Example:
if (! http.GetSuccess()) {
var err = http.GetErrorCode();
var msg = '';
switch (err) {
case 0: msg = 'No Error'; break;
case 1: msg = 'Parse Error'; break;
case 2: msg = 'Host Not Found'; break;
case 3: msg = 'Invalid Socket'; break;
case 4: msg = 'Socket Error'; break;
case 5: msg = 'Invalid Response'; break;
case 6: msg = 'Send Failed'; break;
case 7: msg = 'Receive Error'; break;
case 8: msg = 'User Canceled'; break;
default: msg = 'Unknown Error';
}
sys.WarningBox('HTTP Request Failed\nError Code: '
+ err + ' - ' + msg);
return;
}
GetResponseSize
This method gets the size in bytes of the
data received from the remote server.
- Method: GetResponseSize()
- Return: int
- Params: none
GetResponseData
This method gets the actual data received
from the remote server.
- Method: GetResponseData()
- Return: String
- Params: none
Tokenize
This method tokenizes the data in the http receive
buffer into one or more separate strings, based on the specified delimiter.
It returns an integer that is the number of tokens in the buffer. If no delimiter
is specified, a newline character (decimal 10) is used and carriage returns (decimal 13)
are stripped out of the data. This method and the GetToken method may be used to process
very large received data values, while avoiding the possibility of exceeding size limits
on script variables, etc.
GetToken
This method gets the string value of a token
in the http receive buffer. The http.Tokenize method must have been used first.
It returns a string that is the N'th token in the buffer, based on the delimiter
last specified by the Tokenize method.
- Method: GetToken(int tokenNumber)
- Return: string
- Param0: (tokenNumber) An integer specifying which token to get, starting with zero (0)
for the first token in the buffer. The total number of tokens in the buffer is given by the
return value of the Tokenize method (see above).
Example:
for (i=0; i<nCount; i++) {
var s = http.GetToken(i);
sys.MessageBox('Token ' + i + ' contains value: ' + s);
}
FreeTokens
This method resets the tokenizing values (delimiter etc.) set by
the Tokenize method. It does not affect the contents of the http receive buffer.
- Method: FreeTokens()
- Return: void
- Params: none
RPC Methods
These methods are used with the global "rpc"
(remote procedure call) object to prepare and run a host call to run a
remote procedure on a server.
SetURL
This method creates the URL string that will
be used to run a host procedure. It includes the "http://<host>" string,
any required script string for the middleware, and the name of the remote
program to be run (Progress) or the name of the stored procedure (Oracle).
Specific formatting of the URL must conform to the host middleware being
used. When constructing the hostname portion and script portion, the
"preference.GetPreference(prefName)"
method is useful (see below).
- Method: SetURL(string url)
- Return: void
- Param0: (url) A character string for a URL, starting with "http://"
and ending with the program or stored procedure name to be run.
AddNameValuePair
This method assigns a name/value pair to be
used as an input parameter for the host call.
- Method: AddNameValuePair(string name, string value [, string datatype])
- Return: void
- Param0: (name) A character string for the name of an input parameter.
- Param1: (value) A character string for the value of an input parameter.
- Param2: (datatype) An OPTIONAL character string for the data type of
an input parameter. Valid entries are "character", "integer", "decimal",
"date" and "logical". These values may be truncated, e.g. "char", "int",
"dec", "dat", "log". This optional parameter is used only
by the Progress 4GL Source Code Generator to create variables and parsing
routines of the desired data type, and is NOT used at runtime when this
method is executed.
DisplayURL
This debugging method displays a message box
with the URL value set by the latest call to the SetURL method.
- Method: DisplayURL()
- Return: void
- Params: none
DisplayParams
This debugging method displays a message box
with the CGI parameters (name/value pairs) that were set by the latest
calls to the AddNameValuePair method.
- Method: DisplayParams()
- Return: void
- Params: none
Execute
This method executes (runs) the host call to
the remote server.
- Method: Execute()
- Return: void
- Params: none
FTP Methods
These methods are used with the global "ftp"
object to send a binary file to a remote host, or to retrieve a binary
file from a remote host.
Special Notes:
- These methods currently support ONLY Binary transfer mode, not text.
- Due to a bug in PocketPC2002, only anonymous logins work on that platform.
Other logins work correctly in WinCE and PocketPC2003.
- You can use forward slashes in directory names (even for Windows systems). If you
wish to use backslashes for the local directory name, you must double them to escape
them from the script engine, which uses backslash as an escape character.
Get
This method gets a binary file from a remote
server and saves it into a specified directory on the client system.
- Method: Get(string Hostname, string Userid, string Password, string RemoteDir,
string LocalDir, string Filename, boolean bPassive)
- Return: boolean (true if file transfer was successful, false if unsuccessful)
- Param0: (Hostname) A character string for the remote hostname or IP address.
- Param1: (Userid) A character string for the ftp login userid on the remote server.
- Param2: (Password) A character string for the ftp login password on the remote server.
- Param3: (RemoteDir) A character string for the remote directory (relative to the ftp root
folder) from which to get the file.
- Param4: (LocalDir) A character string for the local directory in which to save the file.
- Param5: (Filename) A character string for the filename to get from the specified folder.
- Param6: (bPassive) Use ftp passive mode if this value is true. Default is false.
Example:
ftp.Get("www.abc.com", "tom", "my_pw", "/images", "c:\\images", "test.bmp", true);
Put
This method sends a binary file from a specified directory on the
client system to a remote server and saves it into a specified directory on the remote system.
- Method: Put(string Hostname, string Userid, string Password, string RemoteDir,
string LocalDir, string Filename, boolean bPassive)
- Return: boolean (true if file transfer was successful, false if unsuccessful)
- Param0: (Hostname) A character string for the remote hostname or IP address.
- Param1: (Userid) A character string for the ftp login userid on the remote server.
- Param2: (Password) A character string for the ftp login password on the remote server.
- Param3: (RemoteDir) A character string for the remote directory (relative to the ftp root folder)
in which to save the file.
- Param4: (LocalDir) A character string for the local directory from which to get the file.
- Param5: (Filename) A character string for the filename to send from the specified folder.
- Param6: (bPassive) Use ftp passive mode if this value is true. Default is false.
Example:
ftp.Put("www.abc.com", "tom", "my_pw", "/images", "c:\\images", "test.bmp", false);
SetShowErrors
This method controls whether Jargon Reader will automatically
display system messages for 'no file' errors in ftp Get requests. If this method
is not used, the default is 'true' (which is consistent with previous versions).
If SetShowErrors is set to false, all ftp error messages will still display except
for the error when attempting to download a file that is not there. This allows an
application to try to get an optional file without necessarily showing error messages
to the user, instead the ftp.Get method will simply have a false return value that
the application can test for further action.
- Method: SetShowErrors(boolean ShowErrors)
- Return: void
- Param1: (ShowErrors) A boolean value: true to show all ftp error messages,
false to suppress 'no file' error messages
Preferences Methods
These methods are used with the global "preference"
object to get the values of named preference properties of a specified app.
Each app has its own separate set of these preference properties that were
loaded from a startup "ini" file, "inherited" from the app that opened the
current app, or dynamically created by an app during an execution session,
using the SetProperty method below.
An example of a preference is "UserGroup=sales",
where "UserGroup" is the
preference name and "sales" is the preference value (i.e. a name/value pair).
Each preference is a case-sensitive property of the "preference" object,
specified by its app name and preference name, and has get/set methods to
obtain or assign its value.
Preferences can be a useful way to pass values between apps
without using
GUI components such as textfields that consume more system resources.
Also, establishing a standard naming convention for using preferences for
inter-application communication can improve encapsulation and reduce
undesirable dependencies such as one app needing to know any details about
another app's internal structure.
GetPreference
This method gets the string value of a specified
preference property for the current app. If the specified property is not found
for the current app, an error message will be displayed and no value will
be returned.
- Method: GetPreference(string preferenceName)
- Return: string
- Param0: (preferenceName) A case-sensitive character string for a preference
property, such as "HostURL" or "Script".
Example:
function MakeURL(program, procedure) {
var HostURL = preference.GetPreference("HostURL");
var Script = preference.GetPreference("Script");
rpc.SetURL(HostURL + "/" + Script + "/" + program);
rpc.AddNameValuePair( "ProcName", procedure);
}
GetProperty
This method gets the string value of any
preference property of any app that is open. The optional third
parameter indicates if the preference is required (true) or optional (false).
The default is "true". If the third parameter is "false" and the preference is not
found, the method returns an empty string and does not display any error message.
If the third parameter is "true" or not specified, and the specified property is not
found, an error message will be displayed and no value will be returned.
- Method: GetProperty(string appName, string propName [, boolean bReturnErr])
- Return: string
- Param0: (appName) A character string for the name of the client xml application
that contains the specified preference property, without the ".xml" suffix.
- Param1: (propName) A case-sensitive character string for a preference property of that app.
- Param2: (bReturnErr) An OPTIONAL boolean value. Use "true" (the default) to
display an error if the specified property is not found, or "false" if the method should
return an empty string and no error.
Example:
var UID = preference.GetProperty('login', 'UserGroup', true);
SetProperty
This method assigns a string value to any
preference property of any app that is open. The specified preference
may be an existing one that was loaded from the startup "ini" file, such
as "HostURL" or "Script", or that was previously created by this method.
If the specified property does not already exist as a preference of the
specified app, it will be created.
- Method: SetProperty(string appName, string propName, string propValue)
- Return: boolean (true if property value was set, false if not)
- Param0: (appName) A character string for the name of the client xml application
that contains the specified preference property, without the ".xml" suffix.
- Param1: (propName) A case-sensitive character string for a preference property of that app.
- Param2: (propValue) A character string for the value to assign to the specified
property.
Example:
ran_ok = preference.SetProperty('login', 'UserGroup', 'sales');
Barcode Scanner Methods
These methods are used with the global "symbol" and "psc"
objects to enable/disable certain Symbol and PSC Falcon barcode scanners, primarily those
found in WindowsCE based Symbol and PSC handheld devices. (Most other
barcode scanners work like inline PC wedge scanners, placing the scan results
into whichever text component currently has focus in a window). When a scan is done,
a function is run that was previously registered with SetScanProc. This function
can obtain and display scan results in a textfield or other component. A frame
method is also available to determine which component currently has focus.
To conserve battery life in the handheld device, enable
the scanner only when on an input frame where such scanning will be done
and disable it when leaving that frame, because enabling the scanner causes
a power drain.
OpenScanner
This method enables the use of the barcode scanner.
- Method: OpenScanner()
- Return: void
- Params: none
CloseScanner
This method disables the use of the barcode scanner.
- Method: CloseScanner()
- Return: void
- Params: none
Set Scan Process
This method sets the name of a script function that will be run upon
successful completion of a barcode scan.
- Method: SetScanProc(String appName, String functionName)
- Return: void
- Param0: (appName) A character string for the name of the client application
that contains the function to be run, without the ".xml" suffix.
- Param1: (functionName) A character string for the name of the function
within the app to be run.
Get Scanned Data
This method returns the data from the last successful scan.
- Method: GetScannedData()
- Return: String
- Params: none
Serial Port Methods
These methods are used with the global "ser" object
to use serial ports (COM1, COM2, etc) to communicate with printers, mag stripe
readers, and other input/output peripherals.
Open
This method opens the specified serial port with the specified data
communication parameters. A typical set of values for the serial port on a PDA is
port=0 baud=19200 data=8 stop=1 parity=none flowctrl=none
- Method: Open(int port, int baud, int dataBits, int stopBits, String parity, String flowControl)
- Return: void
- Param0: (port) 0 = COM1, 1 = COM2, 2 = COM3, etc.
- Param1: (baud) Standard values should work (4800, 9600, 19200, etc)
- Param2: (dataBits) 5, 6, 7, or 8
- Param3: (stopBits) 1 or 2
- Param4: (parity) "none" or "even"
- Param5: (flowControl) "none" or "hardware"
Example:
ser.Open(0, 19200, 8, 1, "none", "none");
Set Receive Callback Procedure
This method runs a specified function in a specified
app when a specified data string is received from the currently open
serial port. This method can be used with mag card readers and other
serial devices that can send data to a serial port that contains a known
termination string such as a newline or carriage return or other string.
- Method: SetReceiveProc(string appName, string functionName, string triggerData)
- Return: void
- Param0: (appName) A character string for the name of the client xml
application that contains the function to be run, without the ".xml" suffix.
- Param1: (functionName) A character string for the name of the function
within the app to be run when the triggerData string is received.
- Param2: (triggerData) A string of one or more characters that will be received
via the currently open serial port by some external action, such as swiping a mag card.
When received, this data will fire an event that runs the specified function.
Example:
ser.SetReceiveProc("cardswipe", "ProcessMagStripeData", "\n");
Receive
This method receives data from the currently open
serial port. Note, this method may return more than the requested
number of bytes if there are more available in the buffer. It may return
less than the requested number of bytes (possibly zero) if the timeout
expires before receiving the requested number of bytes.
- Method: Receive(int timeout, int bytes)
- Return: string
- Param0: (timeout) number of seconds to wait
- Param1: (bytes) number of bytes to wait for
Example:
data = ser.Receive(2, 500);
Send
This method sends data to the currently open serial port.
Close
This method closes the currently open serial port.
- Method: Close()
- Return: void
- Params: none
Example:
ser.Close();
Infrared (IR) Port Methods
These methods are used with the global "irda" object
to use the IR (Infrared) port to communicate with printers, mag stripe readers,
other PDAs, and other input/output peripherals. (Note: IRDA is an acronym for the
Infrared Data Association, a group of device manufacturers that developed a standard
for transmitting data via infrared light waves, which these methods use).
Open
This method opens the IR port.
- Method: Open()
- Return: void
- Params: none
Example:
irda.Open();
Send
This method sends data to the IR port.
Close
This method closes the IR port if it was previously opened.
- Method: Close()
- Return: void
- Params: none
Example:
irda.Close();
File System Methods
These methods are used with the global "jsifile" object
to interface with the native file system of the client device. When specifying
pathnames in Windows, either a single forward slash ('/Temp') or two backslashes
('\\Temp') can be used as path separators.
In version 3.3.36, major changes have been made to the jsifile methods for
reading and writing files. These changes were made because of severe memory management
problems in the Windows Mobile operating system. For backward compatibility, the
older methods will still work, if they are not used at the same time as the new methods.
Both are documented below.
Example:
function CopyFile(readfilename, writefilename) {
var hrfile;
var hwfile;
var line;
// open for reading - file must exist.
hrfile = jsifile.Open(readfilename, 0);
if (hrfile < 0) return false;
// open for writing - file will be created or replaced.
hwfile = jsifile.Open(writefilename, 1);
if (hwfile < 0) {
jsifile.Close(hrfile);
return false;
}
while (jsifile.Readline(hrfile)) {
line = jsifile.GetLineData(hrfile);
jsifile.Write(hwfile, line + "\r\n");
}
// close both files
jsifile.Close(hrfile);
jsifile.Close(hwfile);
return true;
} // end of function CopyFile
Exists
This method tests if a file with the specified name
already exists.
- Method: Exists(String pathName)
- Return: boolean (true if file exists, false if file does not exist)
- Param0: (pathName) a character string that is the filename to test
Example:
if (jsifile.Exists('\\My Documents\\My File.txt')) {
sys.MessageBox("The file already exists.");
return;
}
Get Size
This method gets the byte count of a file with the specified name.
Read Entire File
This method opens an existing file, reads the contents, closes the file, and
returns the contents as a text or binary result value. This Read method was designed to
do the open/close operations automatically. So, you do NOT explicitly open or close a file when
reading it with this method, you just read it.
(Updated for V3.3.36) On Windows Mobile devices, there are memory management problems
in the operating system. So, repeated use of this method with very large files (over 1MB) will
frequently cause an "out of memory" blue screen of death. For this reason, you should consider
using the new jsifile methods to open a file for input, read it a line at a time in a loop, and
then close it when the last line has been read.
- Method: Read(String pathName, boolean bText)
- Return: filedata (String or binary contents of file)
- Param0: (pathName) a character string that is the pathname of the file to read
- Param1: (bText) If true, return a text string. If false, return the binary data of the file.
(On desktop systems this value may not make a difference, but on Windows CE platforms text handling
requires a Unicode conversion.)
Example:
var myTextData = jsifile.Read('\\My Documents\\My File.txt', true);
var myImageData = jsifile.Read('\\My Documents\\Signature.bmp', false);
Open (old)
This method opens a new file for output.
If a file with the same name already exists, it will be overwritten.
You can use "Exists" to test for this before using "Open".
Any specified directories (folders) must already exist, this method will NOT create them.
Note that for Windows filenames, the path separator character "\" must be escaped ("\\").
(V3.3.36) This method will now only work if no file is already open via the new open methods.
Open (new)
This method opens an existing file for input or a new file for output.
If an output file with the same name already exists, it will be overwritten.
You can use "Exists" to test for this before using "Open".
Any specified directories (folders) must already exist, this method will NOT create them.
Note that for Windows filenames, the path separator character "\" must be escaped ("\\").
- Method: Open(String pathName, int accessMode)
- Return: int (a file handle or a negative value if the open failed)
- Param0: (pathName) a character string that is the pathname of the file to open
- Param1: (accessMode) 0 opens for reading a line at a time, 1 opens for writing
Example:
var fh = jsifile.Open('\\My Documents\\My File.txt', 0);
Read Line (new)
This method reads one line from an input file into a system input buffer.
The file must first be opened with jsifile.Open(pathname, 0) before using this method.
Get Line Data (new)
This method gets the value of the latest line read by jsifile.Readline.
Write (old)
This method writes data to an output file. The data is a string value
of any (reasonable) size. It may contain newlines and other nonprintable characters.
The file must first be opened with the jsifile.Open method before using this method.
(V3.3.36) This method will now only work when there is just one file open.
Write (new)
This method writes data to an output file. The data is a string value
of any (reasonable) size. It may contain newlines and other nonprintable characters.
The file must first be opened with jsifile.Open(pathname, 1) before using this method.
- Method: Write(int fileHandle, String data)
- Return: boolean (true if successful, false if write failed)
- Param0: (fileHandle) a file handle (returned by jsifile.Open)
- Param1: (data) a character string that is the data to write to the file
Example:
var WroteOK = jsifile.Write(fh, textarea0.GetText());
Append (old)
This method appends data to an output file. The data is a string value
of any (reasonable) size. It may contain newlines and other nonprintable characters.
The file must first be opened with the jsifile.Open method before using this method.
Close (old)
This method closes a writeable file that was opened using the old Open method.
(V3.3.36) This method will now only work when there is just one file open.
Close (new)
This method closes the output file that was previously opened.
Delete
This method deletes the specified file, which may include a full
or relative path. If the file or path does not exist, no action is taken and no warning
is displayed. Note that for Windows filenames, the path separator character "\" must
be escaped ("\\").
Copy
This method copies the specified file, which may include a full
or relative path. If the file or path does not exist, no action is taken and no warning
is displayed. Note that for Windows filenames, the path separator character "\" must
be escaped ("\\").
- Method: Copy(String oldPathName, String newPathName)
- Return: boolean (true if successful, false if file was not copied)
- Param0: (oldPathName) a character string that is the pathname of the file to be copied
- Param1: (newPathName) a character string that is the pathname of the new copy to be created.
Note that if only a filename is specified without any path, the new file will be created in the
current working directory.
Example:
var OK = jsifile.Copy('/Temp/File1.txt', '/Temp/File1Copy.txt');
Rename/Move
This method renames and/or moves the specified file, which may include a full or
relative path. If the new path is different than the old path, this also moves the specified file to
the new location. If the file or path does not exist, no action is taken and no warning is displayed.
Note that for Windows filenames, the path separator character "\" must be escaped ("\\").
- Method: Rename(String oldPathName, String newPathName)
- Return: boolean (true if successful, false if file was not renamed/moved)
- Param0: (oldPathName) a character string that is the pathname of the file to be renamed
- Param1: (newPathName) a character string that is the new pathname of the file. It may be
a new filename with the same path, a new path with the same filename, or both can be new.
Note that if only a filename is specified without any path, the original file will be moved into the
current working directory and given the specified new filename.
Examples:
var OK = jsifile.Rename('/Temp/oldFile.txt', '/Temp/newFile.txt');
var OK = jsifile.Rename('/Temp/oldFile.txt', '/Backup/oldFile.txt');
UUEncode
This method takes binary data and returns a string value of printable, 7-bit
characters. This could be used, for example, as a way to send an image as a parameter value of
an http request. The data would then be UUDecoded after being received by the host procedure.
Note that UUEncode is NOT an encryption method. For more information, see the Wikipedia article
at http://en.wikipedia.org/wiki/Uuencode.
UUDecode
This method takes data that was previously UUEncoded and produces
the exact set of binary data that was originally given to the UUEncode method.
GetUUDecodedLen
This method takes data that was previously UUEncoded and returns the length
of the binary data in bytes. This is used, for example, for the image.SetImageData() method in
which image size is a required parameter.
- Method: GetUUDecodedLen(String UUEncodedData)
- Return: int
- Param0: (UUEncodedData) a character string of UUEncoded data.
Example:
var imageLength = jsifile.GetUUDecodedLen(charData);
image0.SetImageData(imageData, imageLength, true);
Signature Capture Methods
These methods are used with the global "signature" object
to open a window where a signature can be entered and captured to a local BMP image file.
Signatures may be entered on (1) a touch screen on a mobile device or tablet PC, using a stylus,
(2) a Windows PC or laptop using a mouse, or (3) an external signature capture device (such as
"Topaz" products) connected to a Windows PC, using the device's pen.
This object is supported on all platforms.
All methods except the "new" method are used with the handle
of a specific instance of this object. Handles may be stored in integer script
variables that are initialized to zero. Test for a valid handle by checking
for a non-zero value.
Here is a complete example of signature capture on a Windows PC, laptop or tablet,
using all the necessary methods.
function CaptureSignature(pOrdNum) {
var SigCap = new signature(); // Create an instance of the signature capture object.
var filename = 'SigOrd' + pOrdNum + '.bmp'; // assumes "pOrdNum" has current order number
SigCap.SetFileName(filename); // specify the filename where the sig will be saved
SigCap.SetBounds(5, 5, 200, 150); // specify the window location and size
SigCap.Show(); // open the window for capture
}
Here is a complete example of signature capture on a Windows mobile handheld device,
using all the necessary methods. Note that the SetBounds method is not used on handhelds.
function CaptureSignature(pOrdNum) {
var SigCap = new signature(); // Create an instance of the signature capture object
var filename = 'SigOrd' + pOrdNum + '.bmp'; // assumes "pOrdNum" has current order number
SigCap.SetFileName(filename); // specify the filename where the sig will be saved
SigCap.Show(); // open the window for capture
}
Here is a complete example of signature capture on a Topaz device,
using all the necessary methods.
function CaptureSignature(pOrdNum) {
var SigCap = new signature(); // Create an instance of the signature capture object
var filename = 'SigOrd' + pOrdNum + '.bmp'; // assumes "pOrdNum" has current order number
SigCap.SetFileName(filename); // specify the filename where the sig will be saved
SigCap.SetDeviceType("topaz"); // set the external device type to "topaz"
SigCap.SetDeviceResolution(2000, 600); // set the topaz device window to 2000x600 pixels
SigCap.SetDisplayResolution(500, 150); // set the PC display window to 500x150 pixels
SigCap.Show();
}
new
This method creates a new instance of the signature capture object.
- Method: new signature()
- Return: handle to signature window
- Params: none
Move/Resize Signature Capture Window
This method is used to position the "signature capture" window
with its upper lefthand corner at a specific X/Y pixel location, and to set its size
to a specific width and height, measured in pixels. Note that SetBounds must be called
before the Show method, otherwise it will have no effect. This method is supported on
32-bit Windows platforms only (ReaderWIN.exe).
- Method: SetBounds(int nXPos, int nYPos, int nWidth, int nHeight)
- Return: void
- Param0: (nXPos) The "X" (horizontal) pixel position of the upper lefthand
corner of the window. On an 800x600 resolution display, this value can be
0-799.
- Param1: (nYPos) The "Y" (vertical) pixel position of the upper lefthand
corner of the window. On an 800x600 resolution display, this value can be
0-599.
- Param2: (nWidth) The "X" (horizontal) pixel width of the window. On
an 800x600 resolution display, this value can be 0-799.
- Param3: (nHeight) The "Y" (vertical) pixel height of the window. On
an 800x600 resolution display, this value can be 0-599.
Set Device Type
This method specifies the device type of an external signature
capture peripheral device. Currently, the only device name that is supported is "topaz".
This method is only used with an external signature capture device.
If this method is used to specify a device, but the device is not connected to the PC,
an error message is displayed and the mouse can be used instead to draw in the PC window.
If the device is found, then the mouse input will be blocked and the device must be used.
Either way, the same signature window is displayed. It just gets input from either the mouse
or the external device.
- Method: SetDeviceType(string type)
- Return: void
- Param0: (type) The name of the device.
Set Device Resolution
This method specifies the number of horizontal and vertical cells
on the device pad. For topaz devices, values of 2000x600 are recommended.
This method is only used with an external signature capture device.
- Method: SetDeviceResolution(int nWidth, int nHeight)
- Return: void
- Param0: (nWidth) The number of horizontal cells in the device window.
- Param1: (nHeight) The number of vertical cells in the device window.
Set Display Resolution
This method specifies the resolution of the display signature area on the PC display
screen (not the signature pad). Using the same aspect ratio as the signature pad is recommended.
For example, if the device uses 2000x600, the display could use 500x150.
This method is only required for use with an external signature capture device. But you can use
SetDisplayResolution if you want to set the size of the signature area to a specific pixel width
and height. Doing this will also set the pixel size of the bitmap file.
- Method: SetDisplayResolution(int nWidth, int nHeight)
- Return: void
- Param0: (nWidth) The number of horizontal cells in the display window.
- Param1: (nHeight) The number of vertical cells in the display window.
Set File Name
This method specifies a local pathname where a signature
can be captured as a BMP image file.
- Method: SetFileName(string filename)
- Return: void
- Param0: (filename) The local pathname of an image file where the signature
image is to be captured. Should have a ".bmp" suffix. Can be a relative or
absolute pathname.
Show
This method opens a special "signature capture" window
where a signature can be entered and saved. The window contains an entry area which
captures mouse or stylus motions as line drawings within an image area, and three
buttons (Accept, Clear, and Cancel). If Accept is selected, the entered image is
captured to the previously specified filename and the window is closed. If nothing
has been entered in the signature window, an error message will be displayed and
the save will NOT be done. Clear will clear the image entry area. Cancel will close
the window without saving an image.
- Method: Show()
- Return: void
- Params: none
Video Capture Methods
These methods are used with the global "video"
object to interface with a video camera via a special third-party DLL file.
The video can be displayed within a panel container, and individual snapshots
can be captured to local JPG image files. This object is supported on 32-bit
Windows platforms only (ReaderWIN.exe).
All methods except the "new" method are used with the handle
of a specific instance of this object. Handles may be stored in integer
script variables that are initialized to zero. Test for a valid handle by
checking for a non-zero value.
Requires installation of the CapturePRO3.dll (from Pegasus
Imaging Corp). Copy the DLL to a directory of your choice, then open a
command (DOS) window in this directory and enter "regsvr32
CapturePRO3.dll".
The documentation for Version 3.2 of Pegasus CapturePRO(TM)
says:
CapturePRO interfaces with any video capture device that
supports USB, FireWire, WDM, or native DirectShow including legacy Video For
Windows devices. CapturePRO contains managed .NET, COM and VCL components
(CapturePRO and TwainPRO) that perform image and video acquisition from video
capture devices. CapturePRO is designed to connect to any video capture
device that supplies a DirectShow (WDM) device driver. Most capture devices
currently on the market (video capture cards, PC cameras, etc.) supply this
type of driver. In addition, legacy Video for Windows devices are typically
available via a DirectShow WDM / VfW translation driver.
new
This method creates a new video window inside a panel.
The panel should have large X/Y padding values (e.g. iPadX="320"
iPadY="240").
- Method: new video(handle panelHandle, int 0, int 0, int width, int height)
- Return: handle to video window
- Param0: (panelHandle) handle of the panel that will contain the video.
- Param1: (left) left pixel offset of video within panel - set to zero (0)
- Param2: (top) top pixel offset of video within panel - set to zero (0)
- Param3: (width) pixel width of the panel that will contain the video.
- Param4: (height) pixel height of the panel that will contain the video.
Example:
var VidCam = 0;
function CreateVideo() {
var handle = panel0.GetHandle(); //New panel method.
var nWidth = panel0.GetWidth(); //New panel method.
var nHeight = panel0.GetHeight(); //New panel method.
VidCam = new video(handle, 0, 0, nWidth, nHeight);
// Creates video window inside panel.
}
Connect
This method connects a video window to an input video source.
- Method: Connect(int deviceNum)
- Return: boolean (true if connection was successful, false if not)
- Param0: (deviceNum) device number of the video input source (starts at 0).
Example:
bSuccess = VidCam.Connect(0);
// Connect to the first system video device.
Preview
This method displays the video source in the window.
- Method: Preview()
- Return: void
- Params: none
Example:
VidCam.Preview();
//Turn on the video so it displays in the video window.
Capture
This method captures a still image of the current video
source to a specified local file, as a JPG image file.
- Method: Capture(string filename)
- Return: boolean (true if image capture was successful, false if not)
- Param0: (filename) The local pathname of an image file where the current
video image is to be captured. Should have a ".jpg" suffix. Can be a relative or
absolute pathname.
Example:
var filename = "image1.jpg";
bSuccess = VidCam.Capture(filename);
Disconnect
This method disconnects the video source.
- Method: Disconnect()
- Return: void
- Params: none
// Example:
VidCam.Disconnect();
|
