Client Methods
Version 3.3.42


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
    Do Layout
    This method recalculates the component sizes of a frame's contents. It should be used on all previously rendered frames after changing the system default font. This method does not set a frame visible, use table.SetVisible(true) to do that.
    • Method: DoLayout()
    • Return: void
    • Params: none
    Get Component Name That Has Focus
    This method gets the name of the component that currently has focus in a frame.
    • Method: GetFocusComponentName()
    • Return: String
    • Params: none
    Move/Resize Frame
    This method is used to position a frame with its upper lefthand corner at a specific X/Y pixel location, and to resize a frame to a specific width and height, measured in pixels. This method is supported on 32-bit Windows platforms only (ReaderWIN.exe).
    • Method: MoveWindow(int nXPos, int nYPos, int nWidth, int nHeight)
    • Return: void
    • Param0: (nXPos) The "X" (horizontal) pixel position of the upper lefthand corner of the frame. On an 800x600 resolution display, this value can be 0-799.
    • Param1: (nYPos) The "Y" (vertical) pixel position of the upper lefthand corner of the frame. On an 800x600 resolution display, this value can be 0-599.
    • Param2: (nWidth) The "X" (horizontal) pixel width of the frame. On an 800x600 resolution display, this value can be 0-799.
    • Param3: (nHeight) The "Y" (vertical) pixel height of the frame. On an 800x600 resolution display, this value can be 0-599.
    Repaint a Frame
    This method forces a repaint of a frame's contents. Does not redraw table contents, use table.Repaint() to do that.
    • Method: Repaint()
    • Return: void
    • Params: none
    Display a Status Message
    This method displays a one-line message in a frame's status panel (at the bottom of the frame).
    • Method: SetMessage(string message)
    • Return: void
    • Param0: (message) A one-line message string to be displayed.
    Display a Timed Status Message
    This method displays a one-line message, for a specified time interval, in a frame's status panel (at the bottom of the frame).
    • Method: SetTimedMessage(string message, int milliseconds)
    • Return: void
    • Param0: (message) A one-line message string to be displayed.
    • Param1: (milliseconds) The number of milliseconds the message will be displayed before being hidden. For example, a value of 2000 specifies a message that will be displayed for 2 seconds.
    Change a Frame Title
    This method dynamically changes the title displayed in a frame's title bar.
    • Method: SetTitle(string title)
    • Return: void
    • Param0: (title) The character string to display (left-justified) in the frame's title bar (at the top).


    Panel

    Get Handle to Panel
    This method gets a handle to this panel. (Used with "video" global object methods).
    • Method: GetHandle()
    • Return: handle (similar to an int)
    • Params: none

    Get Pixel Height of Panel
    This method gets the pixel height of this panel. (Used with "video" global object methods).
    • Method: GetHeight()
    • Return: int
    • Params: none

    Get Pixel Width of Panel
    This method gets the pixel width of this panel. (Used with "video" global object methods).
    • Method: GetWidth()
    • Return: int
    • Params: none
    Set Tooltip Text
    This method sets the tooltip text for a panel.
    • Method: SetToolTipText(string Tooltip)
    • Return: void
    • Param0: (Tooltip) A character string that will become the value of the tooltip attribute for the specified component. This one-line help message will be displayed as the floating tooltip for this component.


    Tab Panel


    Get Number of Selected Tab in a Tab Panel
    This method gets the number of the tab that is currently displayed within the tab panel. Tabs are numbered from zero (0) to (n-1) for a tabpanel with (n) tabs. Since users can bring up different tabs by clicking on them, this provides a way to see which tab is currently visible ("on top").
    • Method: GetTabIndex()
    • Return: int
    • Params: none


    Get Name of Selected Tab in a Tab Panel
    This method gets the Object Name of the tab that is currently displayed within the tab panel. Since users can bring up different tabs by clicking on them, this provides a way to see which tab is currently visible ("on top").

    • Method: GetSelectedPanelName()
    • Return: string
    • Params: none
    Repaint
    This method forces a repaint of the tabpanel so that new values will be made visible immediately.
    • Method: Repaint()
    • Return: void
    • Params: none
    Display a Tab in a Tab Panel by Name
    This method changes the tab that is currently displayed within the tab panel by specifying a tab name.
    • Method: SetTab(string tabName)
    • Return: void
    • Param0: (tabName) The internal name of the tab within this tabpanel that should be brought to the top so that its contents are displayed.
    Display a Tab in a Tab Panel by Number
    This method changes the tab that is currently displayed within the tab panel by specifying a tab number (starting from zero).
    • Method: SetTabIndex(int tabNumber)
    • Return: void
    • Param0: (tabNumber) The number (leftmost tab is zero) of the tab within this tabpanel that should be brought to the top so that its contents are displayed.


    Tab

    Set Tooltip Text
    This method sets the tooltip text for a tab in a tabpanel.
    • Method: SetToolTipText(string Tooltip)
    • Return: void
    • Param0: (Tooltip) A character string that will become the value of the tooltip attribute for the specified component. This one-line help message will be displayed as the floating tooltip for this component.


    Card Panel


    Get Number of Current Card in a Card Panel
    This method gets the number of the card that is currently displayed within a card panel. Cards are numbered from zero (0) to (n-1) for a cardpanel with (n) cards. This provides a way to determine which card is currently visible ("on top").
    • Method: GetCardIndex()
    • Return: int
    • Params: none


    Get Name of Current Card in a Card Panel
    This method gets the Object Name of the card that is currently displayed within the card panel. This provides a way to determine which card is currently visible ("on top").

    • Method: GetSelectedPanelName()
    • Return: string
    • Params: none
    Repaint
    This method forces a repaint of the cardpanel so that new values will be made visible immediately.
    • Method: Repaint()
    • Return: void
    • Params: none
    Display a Card in a Card Panel by Name
    This method changes the card that is currently displayed within the card panel by specifying a card name.
    • Method: SetCard(string cardName)
    • Return: void
    • Param0: (cardName) The internal name of the card within this cardpanel that should be brought to the top so that its contents are displayed.
    Display a Card in a Card Panel by Number
    This method changes the card that is currently displayed within the card panel by specifying a card number (starting from zero).
    • Method: SetCardIndex(int cardNumber)
    • Return: void
    • Param0: (cardNumber) The number (leftmost card is zero) of the card within this cardpanel that should be brought to the top so that its contents are displayed.


    Card

    Set Tooltip Text
    This method sets the tooltip text for a card in a cardpanel.
    • Method: SetToolTipText(string Tooltip)
    • Return: void
    • Param0: (Tooltip) A character string that will become the value of the tooltip attribute for the specified component. This one-line help message will be displayed as the floating tooltip for this component.


    Component Methods
    These methods are used with various component objects (objects that are not containers). There are both generic component methods that can be used with any component type, and other methods that are specific to a particular component type.
     

    Generic Component
    These methods can be used on any component object unless otherwise specified.

    Enable or Disable a Component
    This method can be used to enable or disable the following components: Button, Checkbox, Combobox, Datefield, Hyperlink, Passwordfield, Table, Textarea, Textfield, and Tree. Note that the Table and Hyperlink components will not change color when disabled, but they will not respond to any user interaction until re-enabled.
    • Method: SetEnabled(boolean bEnabled)
    • Return: void
    • Param0: (bEnabled) "true" to enable, "false" to disable
    View or Hide a Component and its Contents
    This method makes a component visible or hidden (hidden).
    • Method: SetVisible(boolean bVisible)
    • Return: void
    • Param0: (bVisible) "true" to make visible, "false" to hide
    Set Tooltip Text of a Component
    This method sets the tooltip text for a specified component. May be used on all components except label, frame and menubar/menu/menuitem.
    • Method: SetToolTipText(string Tooltip)
    • Return: void
    • Param0: (Tooltip) A character string that will become the value of the tooltip attribute for the specified component. This one-line help message will be displayed as the floating tooltip for this component.

    Button

    Get Button Caption (as Character String)
    This method gets the character value of the current caption (label) of a button as a "string" data type.
    • Method: GetText()
    • Return: string
    • Params: none
    Set Button Caption
    This method assigns a caption (label) to a button. The new value will not be displayed until the button's frame is redrawn using the "frame.SetVisible(true)" method.
    • Method: SetText(string text)
    • Return: void
    • Param0: (text) A character string to be assigned as the button caption.

    Checkbox

    Select or Unselect a Checkbox
    These methods are used to select (check) or unselect (clear) a checkbox.
    • Method: SetSelected(boolean b)
    • Return: void
    • Param0: (b) "true" to select, "false" to unselect
    Get Current Selected Status of a Checkbox
    This method gets the current state of a checkbox (selected or unselected).
    • Method: IsSelected()
    • Return: boolean (true if selected, false if not selected)
    • Params: none
    Combobox
    Get Selected Index
    This method gets the index (starting at zero) of the currently selected item in a combo box.
    • Method: GetSelectedIndex()
    • Return: int
    • Params: none
    Get Selected Value
    Either of these methods can be used to get the string value of the currently selected item in a combo box.
    • Method: GetCurrentValue()
    •     or: GetSelectedString()
    • Return: string
    • Params: none
    Get Delimited List of Choices
    This method returns a delimited string of all the available choices in the combobox dropdown list.
    • Method: GetStringsList( string delimiter )
    • Return: string
    • Param0: (delimiter) A character or string used to separate choices in the list.
    Insert or Append List Item(s)
    This method adds one or more choices to the selection list. New list items can be appended to the end (bottom) of the list of choices or inserted at a specified location in the list.
    • Method: InsertString(string valueString, int nIndex)
    • Return: void
    • Param0: (valueString) A character string to be added as a selection choice. A choice cannot contain a comma. To add multiple choices, separate the string values with commas (ex: "First Choice,Second Choice").
    • Param1: (nIndex) Insertion position in list, from 0 to (n-1) for a list of 'n' choices. If value is -1, choices are appended to the end of the list.
    Remove All List Items
    This method removes all choices from the selection list (clear the combobox).
    • Method: RemoveAllItems()
    • Return: void
    • Params:  none
    Remove a Choice from Selection List
    This method removes the specified value from the list of choices, if it exists in the list.
    • Method: RemoveString(string valueString)
    • Return: boolean (true if choice was removed, false if not)
    • Param0: (valueString) A case-sensitive character string that must exactly match one of the current choices in the selection list.
    Select List Item by Number
    This method sets the currently selected item to the n'th choice in the selection list. The selections are numbered starting with zero, so valid parameter values are 0,1,2,3 ... (n-1) for a list with n selections.
    • Method: SetSelectedIndex(int nIndex)
    • Return: void
    • Param0: (nIndex) An integer value from 0 to (n - 1), where n is the number of current choices in the combobox.
    Select List Item by Value
    This method sets the currently selected item by specifying the value of one of the choices.
    • Method: SetSelectedItem(string valueString)
    • Return: void
    • Param0: (valueString) A case-sensitive character string that must exactly match one of the current choices in the selection list.
    Hyperlink
    Display Text
    This method assigns a display value to a hyperlink. The new value will be immediately displayed if the hyperlink is currently visible. Note that the SetText method will not resize the component if the specified string is longer than the initial size of the component.
    • Method: SetText(string text)
    • Return: void
    • Param0: (text) A character string to be assigned as the hyperlink's display value.
    Change User Data
    This method assigns a user data value to a hyperlink.
    • Method: SetUserData(string text)
    • Return: void
    • Param0: (text) A character string to be assigned as the hyperlink's user data value.
    Get Current Value (as Character String)
    This method gets the character value of the current contents of a hyperlink's display value as a "string" data type.
    • Method: GetText()
    • Return: string
    • Params: none
    Get Current User Data (as Character String)
    This method gets the character value of the current contents of a hyperlink's user data as a "string" data type.
    • Method: GetUserData()
    • Return: string
    • Params: none
    Image
    Assign an Image Value
    This method displays an image by assigning a binary data value to an image component. The image may be specified as resizable or it can be truncated as need to fit into the declared image component size.
    NOTE: All Jargon Reader versions for Windows and PocketPC devices support any image type that Windows supports, including standard BMP, GIF and JPG formats.
    • 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.GetFont method, or an integer to specify the default system font: 0=normal, 1=boldface.

    Progressbar

    Increment Value
    This method increments the current number of displayed increments in the progress bar by one. Each increment in the progress bar displays a small solid colored rectangular shape. Increments beyond the current maximum have no effect.
    • Method: IncrementValue()
    • Return: void
    • Params: none
    Set Maximum
    This method assigns the number of increments in the progress bar. Each increment in the progress bar displays a small solid colored rectangular shape.
    • Method: SetMaximum(int nMaxVal)
    • Return: void
    • Param0: (nMaxVal) An integer value, such as 10 or 20. The wider the progress bar, the larger this value should probably be.
    Set Value
    This method assigns the current number of displayed increments in the progress bar. Each increment in the progress bar displays a small solid colored rectangular shape. Assign zero (0) to display an empty progress bar. Display the maximum value to display a "full" progress bar.
    • Method: SetValue(int nValue)
    • Return: void
    • Param0: (nValue) An integer value, from zero (0) to the current maximum value.

    Table

    Index of Table Methods
    ClearRowSelectionClear all row selections
    GetCellDataGet data from one table cell
    GetRowCountGet the number of populated table rows
    GetRowTextGet row values as a delimited list
    GetSelectedColumnGet selected column number
    GetSelectedRowGet selected row number
    InsertRowInsert a new row at a specified location
    RemoveAllItemsRemove all rows
    RemoveRowRemove a row from a table
    RepaintRefresh the table display
    ResetAllColorsReset all table colors to the defaults
    SetCellColorsSet FG/BG colors for one table cell
    SetCellDataAssign a value to one table cell
    SetCellEditorListAssign values to a combobox table cell
    SetCellEditorTypeSet cell editor type
    SetCellFontIDSet cell font ID
    SetColumnHeadingAssign a column label
    SetRowColorsSet FG/BG colors for all cells in a row
    SetRowTextAssign values to a row of table cells
    SetRowVisiblePosition row within viewable area of table
    SetSelectedRowSet selected row number
    Clear All Row Selections
    This method deselects all selected table rows and clears the row selection highlighting.
    • Method: ClearRowSelection()
    • Return: void
    • Params: none
    Get Data from One Table Cell
    This method gets the current value in one table cell (a specified row and column).
    • Method: GetCellData(int nRow, int nCol)
    • Return: string
    • Param0: (nRow) An integer row number in which to assign the cell value, starting with 0 (zero) for the top row.
    • Param1: (nCol) An integer column number in which to assign the cell value, starting with 0 (zero) for the leftmost column.
    Get the Number of Populated Table Rows
    This method gets an integer that is the number of populated table rows in the table. The value returned is the last populated row number plus one. Note that this may include embedded empty rows that occur before the last populated row.
    • Method: GetRowCount()
    • Return: int
    • Params: none
    Get Row Values as a Delimited List
    This method returns a delimited list of all the column values in the specified table row.
    • Method: GetRowText(int nRow, string delimiter)
    • Return: string
    • Param0: (nRow) An integer row number, starting with 0 (zero) for the top row.
    • Param1: (delimiter) A character or string used to separate values in the list.
    Get Selected Column Number
    This method gets an integer that is the column number of the most recently selected column in the table (note that the leftmost column in a table is column zero).
    • Method: GetSelectedColumn()
    • Return: int
    • Params: none
    Get Selected Row Number
    This method gets an integer that is the row number of the most recently selected row in the table (note that the top row in a table is row zero).
    • Method: GetSelectedRow()
    • Return: int
    • Params: none
    Insert a New Row at a Specified Location
    This method inserts a new row at the specified row location in the table.
    • Method: InsertRow(int nRow)
    • Return: boolean (true if row was inserted, false if not)
    • Param1: (nRow) An integer row number before which a new row is to be inserted into the table. Specify 0 (zero) to insert a new row at the top of the table. Specify 1 (one) to insert after the top row, etc.
    Remove All Rows
    This method removes all rows from a table and clears the row selection highlighting. It also repositions the visible cells so that the first visible column of row 0 is in the upper left-hand corner.
    • Method: RemoveAllItems()
    • Return: void
    • Params: none
    Remove a Row From a Table
    This method removes the specified row from the table.
    • Method: RemoveRow(int nRow)
    • Return: boolean (true if row was removed, false if not)
    • Param1: (nRow) An integer row number to be removed from the table, starting with 0 (zero) for the top row.
    Refresh the Table Display
    This method forces a redisplay of the table so that new values will be made visible immediately.
    • Method: Repaint()
    • Return: void
    • Params: none
    Reset All Table Colors to the Defaults
    This method resets the foreground (FG) and background (BG) colors on all rows in the table to the default initial color scheme.
    • Method: ResetAllColors()
    • Return: void
    • Params: none
    Set FG/BG Colors for One Table Cell
    This method sets the foreground (FG) and background (BG) colors for one cell in the table. Colors are specified by standard Red/Green/Blue integer values, ranging from 0 to 255 each, where "0,0,0" is black and "255,255,255" is white.
    • Method: SetCellColors(int nRow, int nCol, int FG_Red, int FG_Green, int FG_Blue, int BG_Red, int BG_Green, int BG_Blue)
    • Return: void
    • Param0: (nRow) An integer row number in which to assign the specified colors, starting with 0 (zero) for the top row.
    • Param1: (nCol) An integer column number in which to assign the specified colors, starting with 0 (zero) for the leftmost column.
    • Param2: (FG_Red) The foreground red value (0-255).
    • Param3: (FG_Green) The foreground green value (0-255).
    • Param4: (FG_Blue) The foreground blue value (0-255).
    • Param5: (BG_Red) The background red value (0-255).
    • Param6: (BG_Green) The background green value (0-255).
    • Param7: (BG_Blue) The background blue value (0-255).
    Assign a Value to One Table Cell
    This method assigns or changes the contents of one cell in a table. Both the row and column numbers must be specified, and both are numbered starting with zero (not one).
    • Method: SetCellData(int nRow, int nCol, string cellText)
    • Return: void
    • Param0: (nRow) An integer row number in which to assign the cell value, starting with 0 (zero) for the top row.
    • Param1: (nCol) An integer column number in which to assign the cell value, starting with 0 (zero) for the leftmost column.
    • Param2: (cellText) A character string to be assigned as a cell value.
    Assign Values to a Combobox Table Cell
    This method assigns choices to one table cell that has an editor type of combobox (2). The choices are delimited by a specified delimiter (which allows commas in the choice values if the delimiter is not a comma, for instance).
    • Method: SetCellEditorList(int nRow, int nCol, string choiceList, string delimiter)
    • Return: void
    • Param0: (nRow) An integer row number in which to assign the specified combobox choices, starting with 0 (zero) for the top row.
    • Param1: (nCol) An integer column number in which to assign the specified combobox choices, starting with 0 (zero) for the leftmost column.
    • Param2: (choiceList) A delimiter-separated string of combobox values.
    • Param3: (delimiter) A character string used to separate values in the choiceList.
    • Example: table0.SetCellEditorList(0, 0, "first choice^second choice", "^");

    Set Cell Editor Type
    This method assigns an editor type to one table cell. The editor type can be a textfield (type 0 or 1), a combobox (type 2) or a checkbox (type 3). This method is normally used only for editable table columns.
    • Method: SetCellEditorType(int nRow, int nCol, int nEditorType)
    • Return: void
    • Param0: (nRow) An integer row number in which to assign the specified editor type, starting with 0 (zero) for the top row.
    • Param1: (nCol) An integer column number in which to assign the specified editor type, starting with 0 (zero) for the leftmost column.
    • Param2: (nEditorType) An editor type. Supported values are: 0 or 1 = textfield, 2 = combobox, 3 = checkbox.
    Set Cell Font ID
    This method assigns a font ID for display of a cell value. This method can be used with text or hyperlink cell values.
    • Method: SetCellFontID(int nRow, int nCol, int FontID)
    • Return: void
    • Param0: (nRow) An integer row number in which to assign the specified font, starting with 0 (zero) for the top row.
    • Param1: (nCol) An integer column number in which to assign the specified font, starting with 0 (zero) for the leftmost column.
    • Param2: (FontID) A valid font ID. Supported values are: 0=normal, 1=boldface.
    Assign a Column Label
    This method assigns or changes the contents of one column label in a table. Column numbers are specified starting with zero (not one).
    • Method: SetColumnHeading(int nCol, string headingText)
    • Return: void
    • Param0: (nCol) An integer column number for which to assign the column header, starting with 0 (zero) for the leftmost column.
    • Param1: (headingText) A character string to be assigned as a column header value.
    Set FG/BG Colors for All Cells in a Row
    This method sets the foreground (FG) and background (BG) colors for all cells in a specified row of a table. Colors are specified by standard Red/Green/Blue integer values, ranging from 0 to 255 each, where "0,0,0" is black and "255,255,255" is white.
    • Method: SetRowColors(int nRow, int FG_Red, int FG_Green, int FG_Blue, int BG_Red, int BG_Green, int BG_Blue)
    • Return: void
    • Param0: (nRow) An integer row number in which to assign the specified colors, starting with 0 (zero) for the top row.
    • Param1: (FG_Red) The foreground red value (0-255).
    • Param2: (FG_Green) The foreground green value (0-255).
    • Param3: (FG_Blue) The foreground blue value (0-255).
    • Param4: (BG_Red) The background red value (0-255).
    • Param5: (BG_Green) The background green value (0-255).
    • Param6: (BG_Blue) The background blue value (0-255).
    Assign Values to a Row of Table Cells
    This method assigns or changes the contents of all the cells in one row of a table. The row number must be specified, and is numbered starting with zero (not one).
    • Method: SetRowText(int nRow, string rowData, string delimiter)
    • Return: void
    • Param0: (nRow) An integer row number in which to assign the cell values, starting with 0 (zero) for the top row.
    • Param1: (rowData) A delimiter-separated string of cell values.
    • Param2: (delimiter) A character string used to separate values in the rowData.
    • Example: table0.SetRowText(0, "hello, cell 0^hello, cell 1", "^");

    Position Row within Viewable Area of Table
    This method scrolls the table up or down so that the specified row is at the top, center or bottom of the viewable area of the table.
    • Method: SetRowVisible(int nRow, int nPos)
    • Return: void
    • Param0: (nRow) An integer row number to be positioned, starting with zero for the first row in the table.
    • Param1: (nPos) Where to position the column: 0=top 1=center 2=bottom
    Set Selected Row Number
    This method selects a row in the table.
    • Method: SetSelectedRow(int nRow)
    • Return: void
    • Param1: (nRow) An integer row number to be selected, starting with 0 (zero) for the top row.
    Textarea
    Index of Textarea Methods
    AppendAppend text
    GetCursorPositionGet cursor position
    GetSelectedTextGet selected text
    GetSelectionPositionGet selection position
    GetTextGet current value
    GetWindowPositionGet window position
    InsertTextInsert text
    ReplaceSelectedTextReplace selected text
    SetCursorPositionSet cursor position
    SetFocusSet focus on textarea
    SetFontIDSet font ID
    SetSelectedTextSet selected text
    SetTextDisplay text
    SetWindowPositionSet window position
    Append Text
    This method appends a string value to an existing value in a textarea. The new value will be immediately displayed if the textarea is currently visible.
    • Method: Append(string text)
    • Return: void
    • Param0: (text) A character string to be appended to an existing textarea value.
    Get Cursor Position
    This method gets the byte offset of the current location of the insertion cursor. If there is no current location, returns -1.
    • Method: GetCursorPosition()
    • Return: int
    • Params: none
    Get Selected Text
    This method gets the currently selected string from the textarea. If no characters are selected, returns an empty string ('').
    • Method: GetSelectedText()
    • Return: string
    • Params: none
    Get Selection Position
    This method gets the byte offset of the first character of the currently selected string within the textarea. If no string is selected, returns the position of the insertion cursor if any, otherwise -1.
    • Method: GetSelectionPosition()
    • Return: int
    • Params: none
    Get Current Value
    This method gets the string value of the current contents of a textarea.
    • Method: GetText()
    • Return: string
    • Params: none
    Get Window Position
    This method gets the byte offset of the first character in the currently displayed top line of the textarea window.
    • Method: GetWindowPosition()
    • Return: int
    • Params: none
    Insert Text
    This method inserts the specified text at (before) the character at the specified byte offset. The textarea is not repositioned (the current top line stays at the top). If nByteOffset is negative, it prepends the text to the textarea value. If nByteOffset is greater than the length of the textarea contents, it appends the text to the textarea value.
    • Method: InsertText(string text, int nByteOffset)
    • Return: void
    • Param0: (text) A character string to be inserted at a specified offset within an existing textarea value.
    • Param1: (nByteOffset) Byte offset of specified character within the textarea.
    Replace Selected Text
    This method replaces the currently selected string in the textarea with the specified new text. If no string is selected, this method behaves like InsertText if the insertion cursor has a current position. The textarea is not repositioned (the current top line stays at the top).
    • Method: ReplaceSelectedText(string text)
    • Return: void
    • Param0: (text) A character string to replace selected text in a textarea value.
    Set Cursor Position
    This method sets the current location of the insertion cursor to the left of the character at the specified byte offset. If nByteOffset is negative, it sets the location at offset zero. If nByteOffset is greater than length of the textarea contents, it sets the location after the last character in the textarea.
    • Method: SetCursorPosition(int nByteOffset)
    • Return: void
    • Param0: (nByteOffset) Byte offset of specified character within the textarea.
    Set Focus on Textarea
    This method sets "focus" on a textarea, so that entered data will go into the specified textarea.
    • Method: SetFocus()
    • Return: void
    • Params: none
    Set Font ID
    This method assigns a font ID for display of the component value.
    • Method: SetFontID(int FontID)
    • Return: void
    • Param0: (FontID) A valid font ID, either an object handle created by the sys.GetFont method, or an integer to specify the default system font: 0=normal, 1=boldface.
    Set Selected Text
    This method selects (and highlights) the number of characters specified by nLength, starting with the character at nByteOffset. If nLength is zero, the insertion cursor will be positioned at the specified offset but no characters will be selected. If nByteOffset is negative or greater than the length of the textarea contents, the insertion cursor may be repositioned but no characters will be selected.
    • Method: SetSelectedText(int nByteOffset, int nLength)
    • Return: void
    • Param0: (nByteOffset) Byte offset of first character to be selected.
    • Param1: (nLength) The number of characters to be selected.
    Display Text
    This method assigns a value to a textarea. The new value will be immediately displayed if the textarea is currently visible.
    • Method: SetText(string text)
    • Return: void
    • Param0: (text) A character string to be assigned as a textarea value. This value may contain line feed characters, which will override the automatic word wrap feature of the textarea, to allow user-controlled text placement (as with a name/address display).
    Set Window Position
    This method positions the text line containing the character at the specified nByteOffset to the specified windowLocation in the textarea window: 0=top 1=middle 2=bottom.
    • Method: SetWindowPosition(int nByteOffset, int nWindowLocation)
    • Return: void
    • Param0: (nByteOffset) Byte offset of specified character within the textarea.
    • Param1: (nWindowLocation) Where to display the line containing the specified character within the textarea viewing area:0=top 1=middle 2=bottom. This behavior is not strictly observed when referencing the first or last few lines of the textarea contents, or if the contents have fewer lines than the textarea window allows.
    Textfield
    Index of Textfield Methods
    GetCursorPositionGet cursor position
    GetSelectedTextGet selected text
    GetSelectionPositionGet selection position
    GetTextGet current value
    InsertTextInsert text
    ReplaceSelectedTextReplace selected text
    SetCursorPositionSet cursor position
    SetFocusSet focus on textarea
    SetFontIDSet font ID
    SetSelectedTextSet selected text
    SetTextDisplay text
    Get Cursor Position
    This method gets the byte offset of the current location of the insertion cursor. If there is no current location, returns -1.
    • Method: GetCursorPosition()
    • Return: int
    • Params: none
    Get Selected Text
    This method gets the currently selected string from the textfield. If no characters are selected, returns an empty string ('').
    • Method: GetSelectedText()
    • Return: string
    • Params: none
    Get Selection Position
    This method gets the byte offset of the first character of the currently selected string within the textfield. If no string is selected, returns the position of the insertion cursor if any, otherwise -1.
    • Method: GetSelectionPosition()
    • Return: int
    • Params: none
    Get Current Value (as Character String)
    This method gets the character value of the current contents of a textfield as a "string" data type.
    • Method: GetText()
    • Return: string
    • Params: none
    Insert Text
    This method inserts the specified text at (before) the character at the specified byte offset. If nByteOffset is negative, it prepends the text to the textfield value. If nByteOffset is greater than the length of the textfield contents, it appends the text to the textfield value.
    • Method: InsertText(string text, int nByteOffset)
    • Return: void
    • Param0: (text) A character string to be inserted at a specified offset within an existing textfield value.
    • Param1: (nByteOffset) Byte offset of specified character within the textfield.
    Replace Selected Text
    This method replaces the currently selected string in the textfield with the specified new text. If no string is selected, this method behaves like InsertText if the insertion cursor has a current position.
    • Method: ReplaceSelectedText(string text)
    • Return: void
    • Param0: (text) A character string to replace selected text in a textarea value.
    Set Cursor Position
    This method sets the current location of the insertion cursor to the left of the character at the specified byte offset. If nByteOffset is negative, it sets the location at offset zero. If nByteOffset is greater than length of the textfield contents, it sets the location after the last character in the textfield.
    • Method: SetCursorPosition(int nByteOffset)
    • Return: void
    • Param0: (nByteOffset) Byte offset of specified character within the textfield.
    Set Focus on Textfield
    This method sets "focus" on a textfield, so that entered data will go into the specified textfield.
    • Method: SetFocus()
    • Return: void
    • Params: none
    Set Font ID
    This method assigns a font ID for display of the component value.
    • Method: SetFontID(int FontID)
    • Return: void
    • Param0: (FontID) A valid font ID, either an object handle created by the sys.GetFont method, or an integer to specify the default system font: 0=normal, 1=boldface.
    Set Selected Text
    This method selects (and highlights) the number of characters specified by nLength, starting with the character at nByteOffset. If nLength is zero, the insertion cursor will be positioned at the specified offset but no characters will be selected. If nByteOffset is negative or greater than the length of the textfield contents, the insertion cursor may be repositioned but no characters will be selected.
    • Method: SetSelectedText(int nByteOffset, int nLength)
    • Return: void
    • Param0: (nByteOffset) Byte offset of first character to be selected.
    • Param1: (nLength) The number of characters to be selected.
    Display Text
    This method assigns a value to a textfield. The new value will be immediately displayed if the textfield is currently visible.
    • Method: SetText(string text)
    • Return: void
    • Param0: (text) A character string to be assigned as the textfield value.
    Textpane
    Index of Textpane Methods
    AppendAppend text
    GetTextGet current value
    SetFontIDSet font ID
    SetTextDisplay text
    Append Text
    This method appends a string value to an existing value in a textpane. The new value will be immediately displayed if the textpane is currently visible.
    • Method: Append(string text)
    • Return: void
    • Param0: (text) A character string to be appended to an existing textarea value.
    Get Current Value
    This method gets the string value of the current contents of a textpane.
    • Method: GetText()
    • Return: string
    • Params: none
    Set Font ID
    This method assigns a font ID for display of the component value.
    • Method: SetFontID(int FontID)
    • Return: void
    • Param0: (FontID) A valid font ID, either an object handle created by the sys.GetFont method, or an integer to specify the default system font: 0=normal, 1=boldface.
    Display Text
    This method assigns a value to a textpane. The new value will be immediately displayed if the textpane is currently visible.
    • Method: SetText(string text)
    • Return: void
    • Param0: (text) A character string to be assigned as a textpane value. This value may contain line feed characters, which will override the automatic word wrap feature of the textpane, to allow user-controlled text placement (as with a name/address display).


    Tree

    Index of Tree Methods
    CollapseNodeCollapse a node
    ExpandNodeExpand a node
    GetLastCheckedNodeIDGets the node ID for the last node that was checked/unchecked.
    GetNodeIDCheckedGets the checked state of a node
    GetNodeImageIndexGet image index of a node
    GetNodeTextGet text of a node
    GetNodeTooltipGet tooltip of a node
    GetNodeUserDataGet user data of a node
    GetSelectedNodeNameGet name of currently selected node
    GetSelectedNodeUserDataGet user data of currently selected node
    InsertNodeInsert a node
    RemoveChildNodesRemove child nodes of a node
    RemoveNodeRemove a node
    RepaintRepaint a tree
    SetNodeIDCheckedSets the checked state of a node
    SetNodeImageIndexSet image index of a node
    SetNodeTextSet text of a node
    SetNodeTooltipSet tooltip of a node
    SetNodeUserDataSet user data of a node
    SetSelectedNodeSelect a Node
    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 Last Checked NodeID
    This method gets the node ID for the last node that was checked/unchecked.
    • Method: GetLastCheckedNodeID()
    • Return: int
    • Params: none
    Get Checked State Of A Node
    This method Gets the checked state of a node.
    • Method: GetNodeIDChecked(int nodeID)
    • Return: boolean (true if tree node is checked, false if unchecked)
    • Param0: (nodeID) The integer nodeID of a tree node.
    Get Image Index of a Node
    This method gets the integer value that specifies the image filename for a specified node.
    • Method: GetNodeImageIndex(string nodeName)
    • Return: int
    • Param0: (nodeName) The internal name of a tree node.
    Get Text of a Node
    This method gets the string value of the displayed text for a specified node.
    • Method: GetNodeText(string nodeName)
    • Return: string
    • Param0: (nodeName) The internal name of a tree node.
    Get Tooltip of a Node
    This method gets the string value of the tooltip for a specified node.
    • Method: GetNodeTooltip(string nodeName)
    • Return: string
    • Param0: (nodeName) The internal name of a tree node.
    Get User Data of a Node
    This method gets the string value of the "user data" attribute for a specified node.
    • Method: GetNodeUserData(string nodeName)
    • Return: string
    • Param0: (nodeName) The internal name of a tree node.
    Get Name of Currently Selected Node
    This method gets the string value that is the internal name of the currently selected node.
    • Method: GetSelectedNodeName()
    • Return: string
    • Params: none
    Get User Data of Currently Selected Node
    This method gets the string value of the "user data" attribute of the currently selected node.
    • Method: GetSelectedNodeUserData()
    • Return: string
    • Params: none
    Insert a Node
    This method adds a node to a tree, either under the tree "root" node itself, or under any other node in the tree.
    • Method: InsertNode(string parentNodeName, string nodeName, string nodeText, string nodeuserData, string nodeTooltip, int nImageIndex, int nNodeIndex)
    • Return: void
    • Param0: (parentNodeName) The internal name of an existing node in the target tree under which the new node is to be added as a child node. This parent node may or may not already contain other child nodes. If it does, the new node will become a sibiling of the existing child nodes. Any node automatically becomes a parent node when one or more child nodes are added under it. There is no special attribute which distinguishes parent nodes from ordinary "leaf" nodes, only the fact that they contain at least one child node.
    • Param1: (nodeName) The internal name to assign to the new child node. (Must be unique within the client app).
    • Param2: (nodeText) The text to display as the caption for the new node. (Cannot be blank).
    • Param3: (nodeUserData) (Optional) An arbitrary character string that can be used to store any application-specific value for the new node. For example, if a tree is used as a program menu, the userdata might contain the name of the xml app to run when the node is selected.
    • Param4: (nodeTooltip) (Optional) A character string containing a one-line help message used as the tooltip for the new node
    • Param5: (nImageIndex) (Optional) An integer value which selects the icon to be displayed for the new node in the tree. Selection is from a comma-separated list of icon filenames in the tree's root node "imageList" attribute. An index of zero (0) will select the first (leftmost) image filename in the list, one (1) selects the next image filename entry, etc. If the list contains 5 image filename entries, any index value of 5 or higher will not select any image, since 0-4 select the five valid choices.
    • Param6: (nNodeIndex) (Optional) An integer value which specifies where to insert the new node. A value of -1 will add the new node as the last (bottom) child node for the specified parent node. A value of 0 or more will insert it before an existing child node of the parent node in that location, where 0 is the top existing node, 1 is the next node, etc.
    Remove Child Nodes of a Node
    This method removes all child nodes under the specified parent node. This removal is recursive, so "grandchild" nodes and lower levels of nodes will also be removed.
    • Method: RemoveChildNodes(string nodeName)
    • Return: void
    • Param0: (nodeName) The internal name of a tree node.
    Remove a Node
    This method removes the specified node. This removal is recursive, so any child nodes and their children will also be removed.
    • Method: RemoveNode(string nodeName)
    • Return: void
    • Param0: (nodeName) The internal name of a tree node.
    Repaint a Tree
    This method repaints the target tree. If the text or image index of any nodes have been changed, this will redisplay the new text and images.
    • Method: Repaint()
    • Return: void
    • Params: none
    Set NodeID Checked Status
    This method sets the checked state of a node for a specified nodeID.
    • Method: SetNodeIDChecked(int nodeID, boolean bState)
    • Return: void
    • Param0: (nodeID) The internal integer nodeID of a tree node.
    • Param1: (bState) Set status to: checked (true) or unchecked (false).
    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
    Index of General System Methods
    ExitEnd app and return to startup screen
    GetDeviceUniqueIDGet Mobile Device ID
    GetEventSourceNameGets name of component where latest event occured
    GetExecutablePathGets path of Jargon Reader engine.
    GetOpenFileNameGet Open File Name
    GetProductNameGets name of current Jargon Reader engine.
    GetSaveFileNameGet Save File Name
    GetTickCountGet Milliseconds Since Last Reboot
    LoadArrowCursorSets cursor to normal "arrow" pointer
    LoadWaitCursorSets cursor to normal "busy" pointer
    OSExecRun Operating System Executable
    PlaySoundPlays an audio file (".WAV" file, etc.)
    ProcessInstructionsExecute CIO cmds from host procedure
    QuitEnd Jargon Reader session completely
    Set Interrupt CharSet interrupt char that fires ActionEvent
    ShowDocumentShow Web Document in Default Browser
    Exit (end application session)
    This method does an "application exit", which ends the current session and returns to the Jargon Reader initial ApplicationMenu program. It can be the last statement in a function that is associated with a "Logout" button, for example.
    • Method: Exit()
    • Return: void
    • Params: none
    Get Mobile Device ID
    This method gets the 40-character unique device ID of a mobile device running WM5 or later.
    • Method: GetDeviceUniqueID()
    • Return: string
    • 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 Executable Path
    This method gets the path where the Jargon Reader executable file (e.g. ReaderPPO5.exe, ReaderWIN.exe, etc.) is located.
    • Method: GetExecutablePath()
    • 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 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 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"
    Get Milliseconds Since Last Reboot
    This method gets the number of milliseconds since the device was last rebooted.
    • Method: GetTickCount()
    • Return: string
    • Params: none
    Load Arrow Cursor
    This method sets the cursor image to the normal "arrow" pointer.
    • Method: LoadArrowCursor()
    • Return: void
    • Params: none
    Load Wait Cursor
    This method sets the cursor image to the normal "busy" pointer. On PocketPC devices, the wait cursor is the standard multi-colored PPC "circle". On desktop and laptop PCs, it is the standard Windows hourglass.
    • Method: LoadWaitCursor()
    • Return: void
    • Params: none
    Run Operating System Executable
    This method runs an executable Windows program or built-in command. The pathname is specified as it would be in the Windows "Run" window. This object is supported on 32-bit Windows platforms only (ReaderWIN.exe).
    • Method: OSExec(string pathName)
    • Return: void
    • Param0: (pathName) The full or relative pathname of an executable file or other supported Windows command.
      Examples:
      sys.OSExec('regedit') to edit the Registry (a frequent Windows activity).
      sys.OSExec('notepad readme.txt') to open NotePad to view a readme file.
    Play Sound File
    This method plays an audio (sound) file such as a ".WAV" audio file.
    • Method: PlaySound(string filename)
    • Return: void
    • Param0: (filename) The local pathname of a sound file to be played, such as "C:\jargonsoft\data\hello.wav".
    Process CIO Instructions
    This method executes one or more CIO (Component Instruction Object) instructions received from a host procedure.
    • 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())

    Quit (terminate Reader)
    This method completely ends the Jargon Reader program and closes any open frames. It can be the last statement in a function that is associated with a "End" button, for example.
    • Method: Quit()
    • Return: void
    • Params: none
    Set Interrupt Char
    This method fires an ActionEvent when the specified character is entered. (This was added to compensate for the stupid design of the MC5040 keyboard).
    • Method: SetInterruptChar(string Char)
    • Return: void
    • Param0: (Char) Any single ASCII character.
    Show Web Document
    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 or mobile device using the default web browser defined in the Windows registry. A new browser window will be opened each time this method is executed. (Note: some document types cannot be displayed on Windows Mobile devices)
    • Method: ShowDocument(string url)
    • Return: void
    • Param0: (url) The remote URL or local pathname of the document to be displayed in the browser, such as "http://www.jargonsoft.com/index.html" or "C:\jargonsoft\doc\index.html".

    System Methods: Fonts
    Get Font
    This method gets a handle to a "font object" with the specified font face, point size, and optional bold and underline styles. The last two parameters are optional and may not work for all fonts. The handle returned from GetFont() is good for the entire Reader session, and is used by the SetFontID method of various text components such as textfields and textareas. Note: this method was previously named "CreateFont()", which is still supported but should not be used in new development.
    • Method: GetFont(String facename, int size [, boolean bBold [, boolean bUnderline]])
    • Return: object handle
    • Param0: (facename) A character string for the name of a font face, as it appears in ControlPanel-->Fonts.
    • Param1: (size) An integer font point size, such as 10, 12, 15, etc. Some fonts only offer certain point sizes while others are scaleable.
    • Param2: (bBold) A boolean value: true to display in boldface, false for regular face. Some fonts are designed to be bold and will be bold regardless of the bBold param.
    • Param3: (bUnderline) A boolean value: true to underline, false for no underline. If this optional parameter is specified, the bBold parameter must also be specified.
    • Example:
           var nFontID = sys.GetFont("Courier", 12, false, false);
           frame0.SetVisible(true);
           textarea0.SetFontID(nFontID);
      
    Set Default Font
    This method sets the default system font with the specified font face and point size. This system font is used for all text displayed in components, such as labels, table column headings, checkbox captions, contents of textfields, textareas and textpanes, etc. The default is MS Sans Serif 9.

    After changing the default font, the app must do a frame.DoLayout() to recalculate the component sizes on any frames that have been visible in the current or previously cached session. All frames that have never been rendered before in the current or previously cached sessions will be rendered using the new default font. Note that SetVisible and Repaint only use the existing cached font sizes.

    • Method: SetDefaultFont(String facename, int size)
    • Return: object handle
    • Param0: (facename) A character string for the name of a font face, as it appears in ControlPanel-->Fonts.
    • Param1: (size) An integer font point size, such as 10, 12, 15, etc. Some fonts only offer certain point sizes while others are scaleable.
    • Example:
           frame0.SetVisible(true);
           . . . // other stuff happens
           sys.SetDefaultFont("MS Sans Serif", 10);
           frame0.DoLayout(); // recalculate font sizes in currently visible frame
      

    System Methods: Timer
    Set Timer Callback
    This method assigns a function to be executed in a specified app after a timer has been started and has run for a specified number of milliseconds. After each execution, the timer is reset and this process will repeat until the timer is stopped. Note that during the execution of the specified function, any user interface events will be blocked, so you should not set the timer interval to a value that is too brief or the user may not be able to click a button that runs a function to stop it (unless the timer will eventually be stopped automatically by the program).
    • Method: SetTimerProc(int milliseconds, string appName, string functionName)
    • Return: void
    • Param0: (milliseconds) The number of milliseconds the timer will wait before firing. For example, a value of 5000 specifies a timer that fires every 5 seconds.
    • Param1: (appName) A character string for the name of the client xml application that contains the function to be run, without the ".xml" suffix.
    • Param2: (functionName) A character string for the name of the function within the app to be run when the specified timer period has elapsed.
    • Examples:
      sys.SetTimerProc(5000, thisApp, "RefreshHostData");

    Start Timer
    This method starts the timer. The SetTimerProc method should be run first to specify a callback procedure before using this method.
    • Method: StartTimer()
    • Return: void
    • Params: none
    Stop Timer
    This method stops the timer.
    • Method: StopTimer()
    • Return: void
    • Params: none

    System Methods: Message Boxes
    Message Box
    This method displays an informational message to the user, in a modal dialog box with an OK button.
    • Method: MessageBox(string msg)
    • Return: void
    • Param0: (msg) A character string for a multi-line message to be displayed in the message box. Use the newline escape sequence ('\n') to split lines.
    Warning Box
    This method displays an error or warning message to the user, in a modal dialog box with an OK button. Similar to "message box" except that the warning box uses a different icon image.
    • Method: WarningBox(string msg)
    • Return: void
    • Param0: (msg) A character string for a multi-line message to be displayed in the warning box. Use the newline escape sequence ('\n') to split lines.
    Dialog Box
    This method displays a message to the user in a modal dialog box with a choice of certain button combinations. It returns a string containing the label of the selected button (e.g. "OK", "Cancel" etc.).
    • Method: DialogBox(string title, string prompt, string iconCode, string buttonList, string defaultButton)
    • Return: string
    • Param0: (title) A character string for an (optional) title to be displayed in the frame header of the dialog box. Can be the empty string ("").
    • Param1: (prompt) A character string for a multi-line message to be displayed in the dialog box. Use the newline escape sequence ('\n') to split lines. Messages will also auto-wrap if needed.
    • Param2: (iconCode) A one-character code for the image to be displayed in the dialog box to the left of the prompt message. Codes can be in upper or lower case. Valid codes are:
           I/i - info    - information symbol
           Q/q - query   - question mark
           W/w - warning - exclamation mark
           E/e - error   - error symbol (circled X)
    • Param3: (buttonList) A character string containing a comma-separated list of the button labels to be displayed in the dialog box. Only the following sets of button lists are supported:
      "OK", "OK,Cancel", "Retry,Cancel", "Yes,No", "Yes,No,Cancel"
    • Param4: (defaultButton) A character string for the label of the button that is the default (will be auto-selected if Enter key or spacebar is pressed). If this value is not in the buttonList value, the first button will be the default.
    • Example:
           sys.DialogBox("Dialog Demo", "To Be\nOr Not To Be?",
                         "Q", "Yes,No", "Yes")

    System Methods: Managing Apps
    Get Installed App List
    This method gets a comma-separated list of the names of the currently installed (cached) xml application files.
    • Method: GetInstalledAppList()
    • Return: string
    • Params: none
    Load App Configuration
    This method installs (caches) the configuration (".ini" file) data for an xml application file. If successful, it returns the value of the AppName parameter.
    • Method: LoadAppConfig(string configData)
    • Return: string
    • Param0: (configData) A character string containing multiple lines of "name=value" preference parameters, with lines separated by newlines. Typically this data will be obtained from the http request buffer after a request for a ".ini" file. Example of a typical ".ini" file:
      AppRootDir=http://www.jargonsoft.com/V3/xml/demo32
      AppName=menu
      HostURL=http://www.jargonsoft.com
      Script=scripts/wsisa.dll/WService=sports2000
    Open App
    This method opens a cached client xml application file into working memory, and optionally runs its initial function.

    If a configuration (".ini" file) has been previously received and loaded with the "sys.LoadAppConfig" method, then its preferences are used for the app, otherwise the new app will "inherit" the AppRootURL, HostURL and Script values of the invoking app, and only the AppName will be different.

    If not already cached, the xml file to be opened will first be downloaded from the AppRootDir (as specified above) and cached on the local device.

    An optional second boolean parameter controls whether the init tasklist of the new app will be run. The default is 'true' to run it. Since the script engine won't recognize the newly opened app until the process that opened it ends, a new callback method "sys.SetOpenCallback" has been implemented to return control to a specified app/function after an app has been opened. This callback can be used whether or not the app's initial function is also run, and if so the callback function will be run after the opened app's initial function completes.

    • Method: OpenApp(string appName [, boolean runInit])
    • Return: void
    • Param0: (appName) The name of the client xml application to be opened, without the ".xml" suffix.
    • Param1: (runInit) An OPTIONAL boolean value. Use "true" (the default) to run the initial function of the app after opening it, or "false" to only open the app without running any of its functions. Normally the initial function makes a frame visible, so this essentially determines whether control passes to the new app, on platforms where only one frame at a time can be visible. If so, no callback routine is required, although one can be used if desired. If no frame in the opened app is made visible, a callback routine should be set before running the OpenApp method if further processing steps are to be done.
    SetOpenCallback
    This method assigns a function to be executed in a specified app after an app has been opened. If the opened app runs its init function, this callback function will be run after the init function is completed. The specified function may be in the app being opened, the calling app, or some third app. If the app or function name is an empty string, then the execution thread ends and no other action is taken until the user interacts with whatever frame is visible.

    After the specified callback function has run following the opening of an app, both the appName and functionName parameters are cleared, so they will not be used on the next app open unless this method is run again. You may also explicitly clear the callback parameters at any time with sys.SetOpenCallback('',''), however this is usually not necessary.

    • Method: SetOpenCallback(string appName, string functionName)
    • Return: void
    • Param0: (appName) A character string for the name of the client xml application that contains the function to be run, without the ".xml" suffix.
    • Param1: (functionName) A character string for the name of the function within the app to be run after completing the opening of another app.
    • Examples:
      sys.SetOpenCallback(thisApp, "AfterOpening");
      sys.SetOpenCallback("", ""); // to clear the callback

    Update App
    This method updates the specified xml application file by replacing the current cached copy with a new copy from the server. A new copy of the xml file will be downloaded from the specified AppRootDir, then cached and opened.
    • Method: UpdateApp(string appName [, boolean runInit])
    • Return: void
    • Param0: (appName) The name of the client xml application to be updated, without the ".xml" suffix.
    • Param1: (runInit) An OPTIONAL boolean value. Use "true" (the default) to run the initial function of the app after updating it, or "false" to only update the app without running any of its functions. Normally the initial function makes a frame visible, so this essentially determines whether control passes to the new app, on platforms where only one frame at a time can be visible. If so, no callback routine is required, although one can be used if desired. If no frame in the updated app is made visible, a callback routine should be set before running the UpdateApp method if further processing steps are to be done.
    Save App
    This method saves the contents of the specified xml application from working memory to the local device cache. This is done automatically when an app is closed, however this method allows it to be done programatically, on an event such as a user button press, or every 'n' seconds when a system timer event fires.
    • Method: SaveApp(string appName)
    • Return: void
    • Param0: (appName) The name of the client xml application to be saved, without the ".xml" suffix.
    Close App
    This method closes the specified xml application file by removing it from working memory. It will still remain in the local device cache, but its objects and methods will no longer be accessible from script functions. If a frame from this app is rendered it will be closed, and if it is the only currently visible frame, this method will also call the init() function of the Jargon Reader ApplicationMenu startup routine. This method may be used to conserve memory on resource-limited platforms.
    • Method: CloseApp(string appName)
    • Return: void
    • Param0: (appName) The name of the client xml application to be closed, without the ".xml" suffix.
    Delete App
    This method deletes the specified xml application file from the local cache.
    • Method: DeleteApp(string appName)
    • Return: void
    • Param0: (appName) The name of the client xml application to be deleted from the cache, without the ".xml" suffix.
    Test If App Is Configured
    This method tests whether the "configuration preferences" for the specified xml client application file have been installed. These preferences can be installed by loading an ".ini" file or by directly opening the app and thereby inheriting the calling app's preferences. The minimum set of required configuration preferences are "AppRootDir", "AppName", "HostURL" and "Script".
    • Method: IsAppConfigured(string appName)
    • Return: boolean (true if configuration is loaded, false if not)
    • Param0: (appName) The name of the client xml application to be tested, without the ".xml" suffix.
    Test If App Is Cached
    This method tests whether the specified xml client application file has been cached (installed) on the local device. An app can be cached by the OpenApp or UpdateApp methods.
    • Method: IsAppCached(string appName)
    • Return: boolean (true if the app is cached, false if not)
    • Param0: (appName) The name of the client xml application to be tested, without the ".xml" suffix.
    Test If App Is Open
    This method tests whether the specified xml client application file has been opened (loaded from cache into working memory) during the current execution session. An app can be opened by the OpenApp or UpdateApp methods. If an app is open, its objects and methods can be accessed from script functions, but it may or may not have any visible frames.
    • Method: IsAppOpen(string appName)
    • Return: boolean (true if the app is open, false if not)
    • Param0: (appName) The name of the client xml application to be tested, without the ".xml" suffix.
    Host Call Methods

    There are three global system objects and related methods that can be used to send a request to a remote server and to process the data that it sends back to the client in response.

    • The "http" object is the preferred choice for doing all server requests. It MUST be used when SSL encryption is required, or when the server response may be data other than CIO command sets, such as image data, textual data, XML data from a "Web service", etc. When data from an http request is received, NO automatic processing is done. Instead, when the receiving of data is complete, a script function is executed, that was previously registered with the "http.SetNotifyProc" method (see below).

    • The "rpc" object can be used when running a business procedure on a remote host that is known to return Component Instruction Object ("CIO") command sets in standard Jargon Software format. These CIO commands are the output from the "jsi" host methods. When data from an rpc request is received, the response buffer contents are automatically parsed and executed as CIO commands.This object has been replaced by the "http" object and while it will continue to be supported, developers should begin using http instead.

    • The "ftp" object can be used to send a binary file to a remote host, or to retrieve a binary file from a remote host.

    HTTP Methods
    These methods are used with the global "http" (HyperText Transmission Protocol) object to prepare and send a URL and optional POST data to a remote server. The URL may specify a host procedure, a text file, an image file, or any other valid URL object that the remote web server can handle.
    HTTP Methods
    Index of HTTP Methods
    AddParamAdd a name/value input parameter to the http request
    DownloadFileDownload a file in binary mode
    FreeTokensReset all values set by Tokenize method
    GetErrorCodeGet error code for HTTP request/response failure
    GetResponseDataGet the actual data of server response
    GetResponseSizeGet byte size of server response
    GetSuccessGet success or failure status of response from server
    GetTokenGets the string value of a delimited token in response buffer
    SendRequestSend a URL request to server (no encryption)
    SetNotifyProcAssign callback function to run after server response is received.
    SetRequestBufferSizeSet the HTTP request buffer size directly.
    SetShowErrorsDisplay default error messages in http requests/responses.
    SetStopButtonVisibleView or hide the http "Stop" button.
    SetTimeoutSet the HTTP timeout in seconds.
    SetURLCreate the base URL request string
    TokenizeTokenize http response into string array, split by specified delimiter
    UploadFileUpload a file in binary mode
    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.
    Download File
    This method downloads a file in binary mode from the specified host URL to the specified local pathname.
    • Method: DownloadFile(string hostURL, string localPathname)
    • Return: boolean (true if successful, false if download failed)
    • Param0: (hostURL) A character string for the URL of a file on a server.
    • Param1: (localPathname) A character string for the pathname where the downloaded file will be saved.
    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
    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;
        }
    
    GetResponseData
    This method gets the actual data received from the remote server.
    • Method: GetResponseData()
    • Return: String
    • Params: none
    GetResponseSize
    This method gets the size in bytes of the data received from the remote server.
    • Method: GetResponseSize()
    • Return: int
    • Params: none
    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
    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);
      }

    SendRequest
    This method sends the URL request to the remote server and specifies whether SSL encryption is to be used or not. (The default is false if the parameter is omitted).
    • Method: SendRequest(boolean UseSSL)
    • Return: void
    • Param1: (UseSSL) A boolean value: true to use SSL encryption, false if not
    SetNotifyProc
    This method assigns a callback function to be executed when the server response has been completely received. Both an appname and a function name that exists in that app must be specified, or both can be set to empty strings.

    Once assigned, these values remain in effect for every http request until they are changed or cleared. If no app/function names are assigned via this method in the current app before an http.SendRequest executes, then any values that may have been set in a previous app will be used. In particular, the default ApplicationMenu.xml startup menu app that is hardwired into Jargon Reader does the following when loading an app ".ini" file:

      http.SetNotifyProc(thisApp, "NotifyConfigRecvd");

    The callback values can be reset by assigning empty strings, e.g.

      http.SetNotifyProc('', '');

    If the values are empty (blank), then no callback is done, and the response data will simply sit in the response buffer and no other action is taken. This would allow, for example, the http.GetResponseData() method to be used at some later time within the script without doing so immediately upon receipt of the data.

    Note: to emulate "rpc" functionality, simply use SetNotifyProc to run a function that contains the single statement:
    "sys.ProcessInstructions(http.GetResponseData())".

    • Method: SetNotifyProc(string appName, string functionName)
    • Return: void
    • Param0: (appName) A character string for the name of the client xml application that contains the function to be run, without the ".xml" suffix.
    • Param1: (functionName) A character string for the name of the function within the app to be run.
    SetRequestBufferSize
    This method sets the HTTP request buffer size directly.
    • Method: SetRequestBufferSize(int nBytes)
    • Return: void
    • Param0: (nBytes) The default request buffer size is 50K and grows as needed. This method sets the buffer size directly and will succeed or fail immediately, instead of possibly failing partway through request processing if the device runs out of memory.
    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
    SetStopButtonVisible
    This method views or hides the "Stop" button. This button is displayed on the status line at the bottom of the screen during http requests. This method can be used to prevent a user from manually halting an http request. If the method is not used, the default is 'true' (view the stop button) which is consistent with previous versions. If the method is set to false, the button is not displayed, and so the user has no way to cancel the request manually. Once set to false, the button will not be visible for all subsequent HTTP operations, until it is set back to true.
    • Method: SetStopButtonVisible(boolean ShowButton)
    • Return: void
    • Param1: (ShowButton) A boolean value: true to show http "Stop" button, false to hide it
    SetTimeout
    This method sets the HTTP timeout in seconds.
    • Method: SetTimeout(int nSeconds)
    • Return: void
    • Param0: (nSeconds) Number of seconds to wait before timing out an HTTP request.
    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.
    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(';');

    Upload File
    This method uploads a file in binary mode from the specified local pathname, by specifying a host URL that runs a PHP procedure that will save the uploaded file in some host folder.
    • Method: UploadFile(string HostURL, string LocalPathname)
    • Return: boolean (true if successful, false if upload failed)
    • Param0: (HostURL) A character string for a host PHP script with various parameters.
    • Param1: (localPathname) A character string for the local pathname of the file to be uploaded.
       Notes:
       1. The HostURL must include a "ProcName" parameter that specifies the function name
          to be run within the specified PHP script that will save the uploaded file.
       2. Additional parameters can be added to the URL string as "GET" parameters, such as a
          parameter to specify the desired host folder in which to save the uploaded file.
          e.g. "http://localhost/FFM/jsi_sync.php?ProcName=UploadFile&HostDir=/uploads"
    


    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:
      1. These methods currently support ONLY Binary transfer mode, not text.
      2. Due to a bug in PocketPC2002, only anonymous logins work on that platform.
        Other logins work correctly in WinCE and PocketPC2003.
      3. You can use forward slashes in directory names (even for Windows systems). If you wish to use backslashes for the local directory name, you must double them to escape them from the script engine, which uses backslash as an escape character.

    Get
    This method gets a binary file from a remote server and saves it into a specified directory on the client system.
    • Method: Get(string Hostname, string Userid, string Password, string RemoteDir, string LocalDir, string Filename, boolean bPassive)
    • Return: boolean (true if file transfer was successful, false if unsuccessful)
    • Param0: (Hostname) A character string for the remote hostname or IP address.
    • Param1: (Userid) A character string for the ftp login userid on the remote server.
    • Param2: (Password) A character string for the ftp login password on the remote server.
    • Param3: (RemoteDir) A character string for the remote directory (relative to the ftp root folder) from which to get the file.
    • Param4: (LocalDir) A character string for the local directory in which to save the file.
    • Param5: (Filename) A character string for the filename to get from the specified folder.
    • Param6: (bPassive) Use ftp passive mode if this value is true. Default is false.
    • Example:
      ftp.Get("www.abc.com", "tom", "my_pw", "/images", "c:\\images", "test.bmp", true);

    Put
    This method sends a binary file from a specified directory on the client system to a remote server and saves it into a specified directory on the remote system.
    • Method: Put(string Hostname, string Userid, string Password, string RemoteDir, string LocalDir, string Filename, boolean bPassive)
    • Return: boolean (true if file transfer was successful, false if unsuccessful)
    • Param0: (Hostname) A character string for the remote hostname or IP address.
    • Param1: (Userid) A character string for the ftp login userid on the remote server.
    • Param2: (Password) A character string for the ftp login password on the remote server.
    • Param3: (RemoteDir) A character string for the remote directory (relative to the ftp root folder) in which to save the file.
    • Param4: (LocalDir) A character string for the local directory from which to get the file.
    • Param5: (Filename) A character string for the filename to send from the specified folder.
    • Param6: (bPassive) Use ftp passive mode if this value is true. Default is false.
    • Example:
      ftp.Put("www.abc.com", "tom", "my_pw", "/images", "c:\\images", "test.bmp", false);

    SetShowErrors
    This method controls whether Jargon Reader will automatically display system messages for 'no file' errors in ftp Get requests. If this method is not used, the default is 'true' (which is consistent with previous versions). If SetShowErrors is set to false, all ftp error messages will still display except for the error when attempting to download a file that is not there. This allows an application to try to get an optional file without necessarily showing error messages to the user, instead the ftp.Get method will simply have a false return value that the application can test for further action.
    • Method: SetShowErrors(boolean ShowErrors)
    • Return: void
    • Param1: (ShowErrors) A boolean value: true to show all ftp error messages, false to suppress 'no file' error messages
    Preferences Methods

    These methods are used with the global "preference" object to get the values of named preference properties of a specified app. Each app has its own separate set of these preference properties that were loaded from a startup "ini" file, "inherited" from the app that opened the current app, or dynamically created by an app during an execution session, using the SetProperty method below.

    An example of a preference is "UserGroup=sales", where "UserGroup" is the preference name and "sales" is the preference value (i.e. a name/value pair).

    Each preference is a case-sensitive property of the "preference" object, specified by its app name and preference name, and has get/set methods to obtain or assign its value.

    Preferences can be a useful way to pass values between apps without using GUI components such as textfields that consume more system resources. Also, establishing a standard naming convention for using preferences for inter-application communication can improve encapsulation and reduce undesirable dependencies such as one app needing to know any details about another app's internal structure.

    GetPreference
    This method gets the string value of a specified preference property for the current app. If the specified property is not found for the current app, an error message will be displayed and no value will be returned.
    • Method: GetPreference(string preferenceName)
    • Return: string
    • Param0: (preferenceName) A case-sensitive character string for a preference property, such as "HostURL" or "Script".
    • Example:
      function MakeURL(program, procedure) {
         var HostURL = preference.GetPreference("HostURL");
         var Script  = preference.GetPreference("Script");
         rpc.SetURL(HostURL + "/" + Script + "/" + program);
         rpc.AddNameValuePair( "ProcName", procedure);
      }

    GetProperty
    This method gets the string value of any preference property of any app that is open. The optional third parameter indicates if the preference is required (true) or optional (false). The default is "true". If the third parameter is "false" and the preference is not found, the method returns an empty string and does not display any error message. If the third parameter is "true" or not specified, and the specified property is not found, an error message will be displayed and no value will be returned.
    • Method: GetProperty(string appName, string propName [, boolean bReturnErr])
    • Return: string
    • Param0: (appName) A character string for the name of the client xml application that contains the specified preference property, without the ".xml" suffix.
    • Param1: (propName) A case-sensitive character string for a preference property of that app.
    • Param2: (bReturnErr) An OPTIONAL boolean value. Use "true" (the default) to display an error if the specified property is not found, or "false" if the method should return an empty string and no error.
    • Example:
      var UID = preference.GetProperty('login', 'UserGroup', true);

    SetProperty
    This method assigns a string value to any preference property of any app that is open. The specified preference may be an existing one that was loaded from the startup "ini" file, such as "HostURL" or "Script", or that was previously created by this method. If the specified property does not already exist as a preference of the specified app, it will be created.
    • Method: SetProperty(string appName, string propName, string propValue)
    • Return: boolean (true if property value was set, false if not)
    • Param0: (appName) A character string for the name of the client xml application that contains the specified preference property, without the ".xml" suffix.
    • Param1: (propName) A case-sensitive character string for a preference property of that app.
    • Param2: (propValue) A character string for the value to assign to the specified property.
    • Example:
      ran_ok = preference.SetProperty('login', 'UserGroup', 'sales');

    Barcode Scanner Methods
    These methods are used with the global "symbol" and "psc" objects to enable/disable certain Symbol and PSC Falcon barcode scanners, primarily those found in WindowsCE based Symbol and PSC handheld devices. (Most other barcode scanners work like inline PC wedge scanners, placing the scan results into whichever text component currently has focus in a window). When a scan is done, a function is run that was previously registered with SetScanProc. This function can obtain and display scan results in a textfield or other component. A frame method is also available to determine which component currently has focus.

    To conserve battery life in the handheld device, enable the scanner only when on an input frame where such scanning will be done and disable it when leaving that frame, because enabling the scanner causes a power drain.

    OpenScanner
    This method enables the use of the barcode scanner.
    • Method: OpenScanner()
    • Return: void
    • Params: none
    CloseScanner
    This method disables the use of the barcode scanner.
    • Method: CloseScanner()
    • Return: void
    • Params: none
    Set Scan Process
    This method sets the name of a script function that will be run upon successful completion of a barcode scan.
    • Method: SetScanProc(String appName, String functionName)
    • Return: void
    • Param0: (appName) A character string for the name of the client application that contains the function to be run, without the ".xml" suffix.
    • Param1: (functionName) A character string for the name of the function within the app to be run.
    Get Scanned Data
    This method returns the data from the last successful scan.
    • Method: GetScannedData()
    • Return: String
    • Params: none
    Serial Port Methods
    These methods are used with the global "ser" object to use serial ports (COM1, COM2, etc) to communicate with printers, mag stripe readers, and other input/output peripherals.
    Open
    This method opens the specified serial port with the specified data communication parameters. A typical set of values for the serial port on a PDA is port=0 baud=19200 data=8 stop=1 parity=none flowctrl=none
    • Method: Open(int port, int baud, int dataBits, int stopBits, String parity, String flowControl)
    • Return: void
    • Param0: (port) 0 = COM1, 1 = COM2, 2 = COM3, etc.
    • Param1: (baud) Standard values should work (4800, 9600, 19200, etc)
    • Param2: (dataBits) 5, 6, 7, or 8
    • Param3: (stopBits) 1 or 2
    • Param4: (parity) "none" or "even"
    • Param5: (flowControl) "none" or "hardware"
    • Example:
      ser.Open(0, 19200, 8, 1, "none", "none");

    Set Receive Callback Procedure
    This method runs a specified function in a specified app when a specified data string is received from the currently open serial port. This method can be used with mag card readers and other serial devices that can send data to a serial port that contains a known termination string such as a newline or carriage return or other string.
    • Method: SetReceiveProc(string appName, string functionName, string triggerData)
    • Return: void
    • Param0: (appName) A character string for the name of the client xml application that contains the function to be run, without the ".xml" suffix.
    • Param1: (functionName) A character string for the name of the function within the app to be run when the triggerData string is received.
    • Param2: (triggerData) A string of one or more characters that will be received via the currently open serial port by some external action, such as swiping a mag card. When received, this data will fire an event that runs the specified function.
    • Example:
      ser.SetReceiveProc("cardswipe", "ProcessMagStripeData", "\n");

    Receive
    This method receives data from the currently open serial port. Note, this method may return more than the requested number of bytes if there are more available in the buffer. It may return less than the requested number of bytes (possibly zero) if the timeout expires before receiving the requested number of bytes.
    • Method: Receive(int timeout, int bytes)
    • Return: string
    • Param0: (timeout) number of seconds to wait
    • Param1: (bytes) number of bytes to wait for
    • Example:
      data = ser.Receive(2, 500);

    Send
    This method sends data to the currently open serial port.
    • 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.

    In version 3.3.36, major changes have been made to the jsifile methods for reading and writing files. These changes were made because of severe memory management problems in the Windows Mobile operating system. For backward compatibility, the older methods will still work, if they are not used at the same time as the new methods. Both are documented below.

    Example:
    
      function CopyFile(readfilename, writefilename) {
        var hrfile;
        var hwfile;
        var line;
        // open for reading - file must exist.
        hrfile = jsifile.Open(readfilename, 0);
        if (hrfile < 0) return false;
        // open for writing - file will be created or replaced.
        hwfile = jsifile.Open(writefilename, 1);
        if (hwfile < 0) {
          jsifile.Close(hrfile);
          return false;
        }
        while (jsifile.Readline(hrfile)) {
          line = jsifile.GetLineData(hrfile);
          jsifile.Write(hwfile, line + "\r\n");
        }
        // close both files
        jsifile.Close(hrfile);
        jsifile.Close(hwfile);
        return true;
      } // end of function CopyFile
    
    
    Index of File System Methods
    AppendAppend data to an opened file.
    Close (old)Close a writeable file opened by the old Open method
    Close (new)Closes the output file with the specified file handle
    CopyCopy file from old pathname to new pathname
    DeleteDelete the specified file
    ExistsTest if a file already exists
    GetLineDataGets value of latest line read by jsifile.Readline
    GetSizeGet the byte count of specified file
    Open (old)Open a new file for output
    Open (new)Open an existing file for input or a new file for output
    ReadRead Entire File
    ReadlineReads one line from an opened input file
    RenameRename and/or move the specified file
    UUEncodeConverts binary data to a string of 7-bit characters
    UUDecodereturns binary data that was encoded by UUEncode method
    GetUUDecodedLenReturns byte length of UUEncoded binary data
    Write (old)Write data to an output file
    Write (new)Write data to an output file
    Append (old)
    This method appends data to an output file. The data is a string value of any (reasonable) size. It may contain newlines and other nonprintable characters. The file must first be opened with the jsifile.Open method before using this method.
    • Method: Append(String data)
    • Return: boolean (true if successful, false if append failed)
    • Param0: (data) a character string that is the data to append to the file
    • Example:
      var AppendedOK = jsifile.Append(textarea0.GetText());

    Close (old)
    This method closes a writeable file that was opened using the old Open method. (V3.3.36) This method will now only work when there is just one file open.
    • Method: Close()
    • Return: void
    • Params: none
    • Example:
      jsifile.Close();

    Close (new)
    This method closes the output file that was previously opened.
    • Method: Close(int fileHandle)
    • Return: void
    • Param0: (fileHandle) a file handle (returned by jsifile.Open)
    • Example:
      jsifile.Close(fh);

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

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

    Exists
    This method tests if a file with the specified name already exists.
    • Method: Exists(String pathName)
    • Return: boolean (true if file exists, false if file does not exist)
    • Param0: (pathName) a character string that is the filename to test
    • Example:
      if (jsifile.Exists('\\My Documents\\My File.txt')) {
        sys.MessageBox("The file already exists.");
        return;
      }

    Get Line Data (new)
    This method gets the value of the latest line read by jsifile.Readline.
    • Method: GetLineData(int fileHandle)
    • Return: String (text of latest line read)
    • Param0: (fileHandle) a file handle (returned by jsifile.Open)
    • Example:
      var lineData = jsifile.GetLineData(fh);

    Get Size
    This method gets the byte count of a file with the specified name.
    • Method: GetSize(String pathName)
    • Return: int (size of file in bytes)
    • Param0: (pathName) a character string that is the filename of a text or binary file
    • Example:
      var fileSize = jsifile.GetSize('\\My Documents\\My File.txt'))

    Open (old)
    This method opens a new file for output. If a file with the same name already exists, it will be overwritten. You can use "Exists" to test for this before using "Open". Any specified directories (folders) must already exist, this method will NOT create them. Note that for Windows filenames, the path separator character "\" must be escaped ("\\"). (V3.3.36) This method will now only work if no file is already open via the new open methods.
    • 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');

    Open (new)
    This method opens an existing file for input or a new file for output. If an output file with the same name already exists, it will be overwritten. You can use "Exists" to test for this before using "Open". Any specified directories (folders) must already exist, this method will NOT create them. Note that for Windows filenames, the path separator character "\" must be escaped ("\\").
    • Method: Open(String pathName, int accessMode)
    • Return: int (a file handle or a negative value if the open failed)
    • Param0: (pathName) a character string that is the pathname of the file to open
    • Param1: (accessMode) 0 opens for reading a line at a time, 1 opens for writing
    • Example:
      var fileHandle = jsifile.Open('\\My Documents\\My File.txt', 0);

    Read Entire File
    This method opens an existing file, reads the contents, closes the file, and returns the contents as a text or binary result value. This Read method was designed to do the open/close operations automatically. So, you do NOT explicitly open or close a file when reading it with this method, you just read it.

    (Updated for V3.3.36) On Windows Mobile devices, there are memory management problems in the operating system. So, repeated use of this method with very large files (over 1MB) will frequently cause an "out of memory" blue screen of death. For this reason, you should consider using the new jsifile methods to open a file for input, read it a line at a time in a loop, and then close it when the last line has been read.

    • Method: Read(String pathName, boolean bText)
    • Return: filedata (String or binary contents of file)
    • Param0: (pathName) a character string that is the pathname of the file to read
    • Param1: (bText) If true, return a text string. If false, return the binary data of the file. (On desktop systems this value may not make a difference, but on Windows CE platforms text handling requires a Unicode conversion.)
    • Example:
      var myTextData = jsifile.Read('\\My Documents\\My File.txt', true);
      var myImageData = jsifile.Read('\\My Documents\\Signature.bmp', false);

    Read Line (new)
    This method reads one line from an input file into a system input buffer. The file must first be opened with jsifile.Open(pathname, 0) before using this method.
    • Method: Readline(int fileHandle)
    • Return: boolean (true if a line was read, false if at end-of-file)
    • Param0: (fileHandle) a file handle (returned by jsifile.Open)
    • Example:
      var gotLine = jsifile.Readline(fh);

    Rename/Move
    This method renames and/or moves the specified file, which may include a full or relative path. If the new path is different than the old path, this also moves the specified file to the new location. If the file or path does not exist, no action is taken and no warning is displayed. Note that for Windows filenames, the path separator character "\" must be escaped ("\\").
    • Method: Rename(String oldPathName, String newPathName)
    • Return: boolean (true if successful, false if file was not renamed/moved)
    • Param0: (oldPathName) a character string that is the pathname of the file to be renamed
    • Param1: (newPathName) a character string that is the new pathname of the file. It may be a new filename with the same path, a new path with the same filename, or both can be new. Note that if only a filename is specified without any path, the original file will be moved into the current working directory and given the specified new filename.
    • Examples:
      var OK = jsifile.Rename('/Temp/oldFile.txt', '/Temp/newFile.txt');
      var OK = jsifile.Rename('/Temp/oldFile.txt', '/Backup/oldFile.txt');

    UUEncode
    This method takes binary data and returns a string value of printable, 7-bit characters. This could be used, for example, as a way to send an image as a parameter value of an http request. The data would then be UUDecoded after being received by the host procedure. Note that UUEncode is NOT an encryption method. For more information, see the Wikipedia article at http://en.wikipedia.org/wiki/Uuencode.
    • Method: UUEncode(binary data)
    • Return: String
    • Param0: (bindata) a set of binary data (such as an image) to be UUencoded.
    • Example:
      var charData = jsifile.UUEncode(imageData);

    UUDecode
    This method takes data that was previously UUEncoded and produces the exact set of binary data that was originally given to the UUEncode method.
    • Method: UUDecode(String UUEncodedData)
    • Return: binary data
    • Param0: (UUEncodedData) a character string of UUEncoded data.
    • Example:
      var imageData = jsifile.UUDecode(charData);

    GetUUDecodedLen
    This method takes data that was previously UUEncoded and returns the length of the binary data in bytes. This is used, for example, for the image.SetImageData() method in which image size is a required parameter.
    • Method: GetUUDecodedLen(String UUEncodedData)
    • Return: int
    • Param0: (UUEncodedData) a character string of UUEncoded data.
    • Example:
      var imageLength = jsifile.GetUUDecodedLen(charData); image0.SetImageData(imageData, imageLength, true);

    Write (old)
    This method writes data to an output file. The data is a string value of any (reasonable) size. It may contain newlines and other nonprintable characters. The file must first be opened with the old jsifile.Open() method before using this method. (V3.3.36) This method will now only work when there is just one file open.
    • 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());

    Write (new)
    This method writes data to an output file. The data is a string value of any (reasonable) size. It may contain newlines and other nonprintable characters. The file must first be opened with the new jsifile.Open(pathname, 1) method before using this method.
    • Method: Write(int fileHandle, String data)
    • Return: boolean (true if successful, false if write failed)
    • Param0: (fileHandle) a file handle (returned by jsifile.Open)
    • Param1: (data) a character string that is the data to write to the file
    • Example:
      var WroteOK = jsifile.Write(fh, textarea0.GetText());

    Signature Capture Methods
    These methods are used with the global "signature" object to open a window where a signature can be entered and captured to a local BMP image file. Signatures may be entered on (1) a touch screen on a mobile device or tablet PC, using a stylus, (2) a Windows PC or laptop using a mouse, or (3) an external signature capture device (such as "Topaz" products) connected to a Windows PC, using the device's pen. This object is supported on all platforms.

    All methods except the "new" method are used with the handle of a specific instance of this object. Handles may be stored in integer script variables that are initialized to zero. Test for a valid handle by checking for a non-zero value.

    Here is a complete example of signature capture on a Windows PC, laptop or tablet, using all the necessary methods.

       function CaptureSignature(pOrdNum) {
         var SigCap = new signature();               // Create an instance of the signature capture object.
         var filename = 'SigOrd' + pOrdNum + '.bmp'; // assumes "pOrdNum" has current order number
         SigCap.SetFileName(filename);               // specify the filename where the sig will be saved
         SigCap.SetBounds(5, 5, 200, 150);           // specify the window location and size
         SigCap.Show();                              // open the window for capture
       }

    Here is a complete example of signature capture on a Windows mobile handheld device, using all the necessary methods. Note that the SetBounds method is not used on handhelds.

       function CaptureSignature(pOrdNum) {
         var SigCap = new signature();               // Create an instance of the signature capture object
         var filename = 'SigOrd' + pOrdNum + '.bmp'; // assumes "pOrdNum" has current order number
         SigCap.SetFileName(filename);               // specify the filename where the sig will be saved
         SigCap.Show();                              // open the window for capture
       }

    Here is a complete example of signature capture on a Topaz device, using all the necessary methods.

       function CaptureSignature(pOrdNum) {
         var SigCap = new signature();               // Create an instance of the signature capture object
         var filename = 'SigOrd' + pOrdNum + '.bmp'; // assumes "pOrdNum" has current order number
         SigCap.SetFileName(filename);               // specify the filename where the sig will be saved
         SigCap.SetDeviceType("topaz");              // set the external device type to "topaz"
         SigCap.SetDeviceResolution(2000, 600);      // set the topaz device window to 2000x600 pixels
         SigCap.SetDisplayResolution(500, 150);      // set the PC display window to 500x150 pixels
         SigCap.Show();
       }

    new
    This method creates a new instance of the signature capture object.
    • Method: new signature()
    • Return: handle to signature window
    • Params: none
    Move/Resize Signature Capture Window
    This method is used to position the "signature capture" window with its upper lefthand corner at a specific X/Y pixel location, and to set its size to a specific width and height, measured in pixels. Note that SetBounds must be called before the Show method, otherwise it will have no effect. This method is supported on 32-bit Windows platforms only (ReaderWIN.exe).
    • Method: SetBounds(int nXPos, int nYPos, int nWidth, int nHeight)
    • Return: void
    • Param0: (nXPos) The "X" (horizontal) pixel position of the upper lefthand corner of the window. On an 800x600 resolution display, this value can be 0-799.
    • Param1: (nYPos) The "Y" (vertical) pixel position of the upper lefthand corner of the window. On an 800x600 resolution display, this value can be 0-599.
    • Param2: (nWidth) The "X" (horizontal) pixel width of the window. On an 800x600 resolution display, this value can be 0-799.
    • Param3: (nHeight) The "Y" (vertical) pixel height of the window. On an 800x600 resolution display, this value can be 0-599.
    Set Device Type
    This method specifies the device type of an external signature capture peripheral device. Currently, the only device name that is supported is "topaz". This method is only used with an external signature capture device.

    If this method is used to specify a device, but the device is not connected to the PC, an error message is displayed and the mouse can be used instead to draw in the PC window. If the device is found, then the mouse input will be blocked and the device must be used. Either way, the same signature window is displayed. It just gets input from either the mouse or the external device.

    • Method: SetDeviceType(string type)
    • Return: void
    • Param0: (type) The name of the device.
    Set Device Resolution
    This method specifies the number of horizontal and vertical cells on the device pad. For topaz devices, values of 2000x600 are recommended. This method is only used with an external signature capture device.
    • Method: SetDeviceResolution(int nWidth, int nHeight)
    • Return: void
    • Param0: (nWidth) The number of horizontal cells in the device window.
    • Param1: (nHeight) The number of vertical cells in the device window.
    Set Display Resolution
    This method specifies the resolution of the display signature area on the PC display screen (not the signature pad). Using the same aspect ratio as the signature pad is recommended. For example, if the device uses 2000x600, the display could use 500x150. This method is only required for use with an external signature capture device. But you can use SetDisplayResolution if you want to set the size of the signature area to a specific pixel width and height. Doing this will also set the pixel size of the bitmap file.
    • Method: SetDisplayResolution(int nWidth, int nHeight)
    • Return: void
    • Param0: (nWidth) The number of horizontal cells in the display window.
    • Param1: (nHeight) The number of vertical cells in the display window.
    Set File Name
    This method specifies a local pathname where a signature can be captured as a BMP image file.
    • Method: SetFileName(string filename)
    • Return: void
    • Param0: (filename) The local pathname of an image file where the signature image is to be captured. Should have a ".bmp" suffix. Can be a relative or absolute pathname.
    Show
    This method opens a special "signature capture" window where a signature can be entered and saved. The window contains an entry area which captures mouse or stylus motions as line drawings within an image area, and three buttons (Accept, Clear, and Cancel). If Accept is selected, the entered image is captured to the previously specified filename and the window is closed. If nothing has been entered in the signature window, an error message will be displayed and the save will NOT be done. Clear will clear the image entry area. Cancel will close the window without saving an image.
    • Method: Show()
    • Return: void
    • Params: none
    Video Capture Methods
    These methods are used with the global "video" object to interface with a video camera via a special third-party DLL file. The video can be displayed within a panel container, and individual snapshots can be captured to local JPG image files. This object is supported on 32-bit Windows platforms only (ReaderWIN.exe).

    All methods except the "new" method are used with the handle of a specific instance of this object. Handles may be stored in integer script variables that are initialized to zero. Test for a valid handle by checking for a non-zero value.

    Requires installation of the CapturePRO3.dll (from Pegasus Imaging Corp). Copy the DLL to a directory of your choice, then open a command (DOS) window in this directory and enter "regsvr32 CapturePRO3.dll".

    The documentation for Version 3.2 of Pegasus CapturePRO(TM) says:

    CapturePRO interfaces with any video capture device that supports USB, FireWire, WDM, or native DirectShow including legacy Video For Windows devices. CapturePRO contains managed .NET, COM and VCL components (CapturePRO and TwainPRO) that perform image and video acquisition from video capture devices. CapturePRO is designed to connect to any video capture device that supplies a DirectShow (WDM) device driver. Most capture devices currently on the market (video capture cards, PC cameras, etc.) supply this type of driver. In addition, legacy Video for Windows devices are typically available via a DirectShow WDM / VfW translation driver.

    new
    This method creates a new video window inside a panel. The panel should have large X/Y padding values (e.g. iPadX="320" iPadY="240").
    • Method: new video(handle panelHandle, int 0, int 0, int width, int height)
    • Return: handle to video window
    • Param0: (panelHandle) handle of the panel that will contain the video.
    • Param1: (left) left pixel offset of video within panel - set to zero (0)
    • Param2: (top) top pixel offset of video within panel - set to zero (0)
    • Param3: (width) pixel width of the panel that will contain the video.
    • Param4: (height) pixel height of the panel that will contain the video.
    • Example:
           var VidCam = 0;
           function CreateVideo() {
             var handle  = panel0.GetHandle(); //New panel method.
             var nWidth  = panel0.GetWidth();  //New panel method.
             var nHeight = panel0.GetHeight(); //New panel method.
             VidCam = new video(handle, 0, 0, nWidth, nHeight);
             // Creates video window inside panel.
           }

    Connect
    This method connects a video window to an input video source.
    • Method: Connect(int deviceNum)
    • Return: boolean (true if connection was successful, false if not)
    • Param0: (deviceNum) device number of the video input source (starts at 0).
    • Example:
           bSuccess = VidCam.Connect(0);
           // Connect to the first system video device.

    Preview
    This method displays the video source in the window.
    • Method: Preview()
    • Return: void
    • Params: none
    • Example:
           VidCam.Preview();
           //Turn on the video so it displays in the video window.

    Capture
    This method captures a still image of the current video source to a specified local file, as a JPG image file.
    • Method: Capture(string filename)
    • Return: boolean (true if image capture was successful, false if not)
    • Param0: (filename) The local pathname of an image file where the current video image is to be captured. Should have a ".jpg" suffix. Can be a relative or absolute pathname.
    • Example:
           var filename = "image1.jpg";
           bSuccess = VidCam.Capture(filename);

    Disconnect
    This method disconnects the video source.
    • Method: Disconnect()
    • Return: void
    • Params: none
    •    // Example:
      VidCam.Disconnect();


    Up to Top     Return to Help Index