Client Methods

Client Methods
Version 3.2

General Components Global Objects

Introduction

Selecting a Method

Method Return Values

Method Parameters

Documentation Format

Containers

Generic Container

Frame

Panel

Tabpanel

Tab

Cardpanel

Card

Generic Component

Button

Checkbox

Combobox

Hyperlink

Image

Label

Menubar

Menu

Menu Item

Passwordfield

Progressbar

Table

Textarea

Textfield

Textpane

Tree

System Methods
     General
     Fonts
     Timer
     Message Boxes
     Managing Apps

Host Call Methods

HTTP Methods

RPC Methods

FTP Methods

Preferences Methods

Barcode Scanner Methods

Serial Port Methods

Infrared (IR) Port Methods

File System Methods

Signature Capture Methods

Video Capture Methods

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

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

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.

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 (not supported on PalmOS)

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 (not supported on PalmOS)

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.

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

Enable or Disable a Button
This method enables or disables a button.

Method: SetEnabled(boolean bEnabled)

Return: void

Param0: (bEnabled) "true" to enable, "false" to disable

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

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 data, int nIndex)

Return: void

Param0: (data) 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, the data string is 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

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 text)

Return: void

Param0: (text) 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: Images are NOT supported in Jargon Reader for Palm OS. All other Jargon Reader versions for Windows and PocketPC devices support images, including all standard GIF and JPG formats.

Method: SetImageData(binary ImageData, int SizeInBytes, boolean ResizeLayout)

Return: void

Param0: (ImageData) The binary image data. This may commonly be obtained either from the http receive buffer or from a local database cursor column value.

Param1: (SizeInBytes) The integer size (in bytes) of the image data.

Param2: (ResizeLayout) When this param is true and the image size (width and height) is different than the amount of space currently allocated in that container, then the layout routine is invoked and all components are repositioned to accommodate the new image. If the param is false then the image is displayed in the space currently allocated and may not show the entire image (if the image is larger) or may leave white space to the right and bottom of the image (if the image is smaller).

Example of displaying image received from http request:
image0.SetImageData(http.GetResponseData(), http.GetResponseSize(), true)
Example of displaying image read from a local database via ODBC/SQL
sqlstr = "SELECT * FROM PRODIMAGE WHERE PRODID = " + tProdID.GetText();
cur = db.cursor(sqlstr, Database.dynaset);
cur.next();
prodimage.SetImageData(cur.IMAGEDATA, cur.SIZE, true);

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.CreateFont 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

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.

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 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", "^");
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 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

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.

Clear All Row Selections
This method deselects all selected table rows and clear the row selection highlighting.

Method: ClearRowSelection()

Return: void

Params: none

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

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

Repaint
This method forces a repaint of the table so that new values will be made visible immediately.

Method: Repaint()

Return: void

Params: none

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.

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) or a combobox (type 2). 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.

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", "^");

Textarea

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).

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.

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 Current Value
This method gets the string value of the current contents of a textarea.

Method: GetText()

Return: string

Params: none

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.CreateFont method, or an integer to specify the default system font: 0=normal, 1=boldface.

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

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.

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

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.

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 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

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.

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.

Textfield

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.

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.

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

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.CreateFont method, or an integer to specify the default system font: 0=normal, 1=boldface.

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

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.

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 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

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.

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.

Textpane

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).

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.CreateFont method, or an integer to specify the default system font: 0=normal, 1=boldface.

Tree

Note: available on Windows platforms only.

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

Enable or Disable a Tree
This method enables or disables a tree.

Method: SetEnabled(boolean bEnabled)

Return: void

Param0: (bEnabled) "true" to enable, "false" to disable

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
System Exit (end session)
This method does a "system 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" or "Exit" button, for example.

Method: Exit()

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 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"

Process CIO Instructions
This method executes one or more CIO (Component Instruction Object) instructions received from a host procedure.

Method: ProcessInstructions(String resultSet)

Return: void

Param0: (resultSet) A character string containing valid CIO command instructions. This will most commonly be the contents of the http response buffer, when used with the http send/response methods.

Example: sys.ProcessInstructions(http.GetResponseData())
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
Create Font
This method creates a handle to a "font object" with 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 CreateFont() is good for the entire Reader session, and is used by the SetFontID method of various text components such as textfields and textareas.
Method: CreateFont(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.CreateFont("Courier", 12, false, false);
     frame0.SetVisible(true);
     textarea0.SetFontID(nFontID);
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.

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 such as older PalmOS-based devices.

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.

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 calback 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.

Method: SendRequest()

Return: void

Params: none

SendRequest (for SSL)
This method sends the URL request to the remote server and specify whether SSL encryption is to be used or not.

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

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

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.

Method: Tokenize( [string delimiter] )

Return: int

Param0: (delimiter) An OPTIONAL character string used to separate strings in the http buffer. Default is a newline character (dec 10).

Example:
var nCount = http.Tokenize(';');
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 save 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: void

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: void

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);

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

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 PalmOS and 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" (note: PalmOS does not support XON/XOFF)

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.

Method: Send(String data)

Return: void

Param0: (data) the string of data to be sent to the port

Example:
ser.Send("Hello world");
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.

Method: Send(String data)

Return: void

Param0: (data) the string of data to be sent to the port

Example:
irda.Send("Hello world");
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.

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; }
Open
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 ("\\").

Method: Open(String pathName)

Return: boolean (true if successful, false if file was not opened)

Param0: (pathName) a character string that is the pathname of the file to open

Example:
var OpenedOK = jsifile.Open('\\My Documents\\My File.txt');
Write
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.

Method: Write(String data)

Return: boolean (true if successful, false if write failed)

Param0: (data) a character string that is the data to write to the file

Example:
var WroteOK = jsifile.Write(textarea0.GetText());
Close
This method closes the output file that was previously opened.

Method: Close()

Return: void

Params: none

Example:
jsifile.Close();
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 ("\\").

Method: Delete(String pathName)

Return: boolean (true if successful, false if file was not deleted)

Param0: (pathName) a character string that is the pathname of the file to delete

Example:
var OK = jsifile.Delete('\\My Documents\\My File.txt');
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');

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. This object is supported on all platforms except PalmOS devices.

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.

new
This method creates a new instance of the signature capture object.
Method: new signature()

Return: handle to signature window

Params: none
   // Example:

   var SigCap = 0;

   function CreateSig() {

      SigCap = new signature(); //Create an instance of the signature capture object.

   }
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.
   // Example:
   var filename = "SigForOrdNum123456.bmp";
   SigCap.SetFileName(filename);
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. Clear will clear the image entry area. Cancel will close the window without saving an image.
Method: Show()

Return: void

Params: none
   // Example:
   SigCap.Show();

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).

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); //Create video window inside panel.
   }
Connect
This method connects a video window to an input video source.
Method: Connect(int deviceNum)

Return: boolean (success or failure)

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 (success or failure)

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();

Up to Top Return to Help Index