ogscript Object

In ogScript,use the ogscriptobject to access a libraryof general-purpose functions. To call a general-purpose function,use:

ogscript.function name(parameters);

For example:

ogscript.debug ('This is a message');

The following tablelists the functionsof the ogscriptobject. Detailed descriptions appearafter the table. If you are reading this document on-screen, click a functionname in the table to view its description.

 

Function

Parameters

Returns

Description

addRemoteTrigger

String [Trigger]

String [Function]

Returns an object that contains one function named close. When executed, closeremoves the function.

Allows remote execution of a script inside of a CustomPanel through the RossTalk GPI command.

Function can be removed by calling

closeon the object returned.

appendXML

String [Container ID] String [XML snippet]

N/A

Adds a section of OGLML code to the panel identified by the Container ID parameter. The OGLML is added during runtime and does not affect the .grid file.

Valid only in <abs/> containers.

asyncExec

function

N/A

Executes a function outside of the UI current thread.

asyncFTP

post

port

username

password

destPath

destName

binary

sourceFilePath

callback

N/A

Sends a file to an FTP server.

asyncFTPGet

host

port

username

password

srcPath

srcName

binary

destFilePath or null

callback

N/A

Retrieves a file from FTP server.

asyncPost

String [URL]

String [HTTP Post Data]

Function [Callback Function]

Boolean [include response]

N/A

Send an asynchronous post to the given URL.

cancelTimer

Timer ID

N/A

Cancel, stop and clean-up, a timer with the given ID.

copyByteArray

src

offset

length

byte array

Creates a full or partial copy of a byte array.

createByteArray

length

an empty byte array

Creates an empty byte array of a specified size.

createFileInput

String [File path]

FileInputParser  (like MessageParser but with getSize(), close(), and isClosed()

Access a file as a byte array with the same capabilities as MessageParser to read raw bytes

createFileOutput

String [File path]

Boolean [appendToExistingfile]

FileOutputBuilder, which is same as MessageBuilder with added functions for clear() (overwrite file), close(), getSize(), flush(), and isClosed()

Create a new file or append to an existing file. Instead of saving XML or string data, gives access to write raw bytes (or strings, or shorts, or ints, etc.). Also gives the ability to append to a file. Once open, it does not close the file until the panel is closed or close() is called. This is handy for logging.

createMessageBuilder

N/A

Returns a MessageBuilder object used to build byte arrays (generally for creating network messages).

Creates a message builder, which enables you to construct a message.

createMessageParser

messageBytes

Returns a MessageParser object (generally used to parse the various pieces of messages received over the network).

Creates a message parser, which enables you to parse a message.

debug

String [Message]

N/A

Write a string to the openGear Debug Information View.

fireGPI

String [trigger]

String [state]

Boolean [global]

N/A

Sends Trigger GPI string [trigger] to execute component task lists.

Sends optional [state] data string, which can be read by the script.

When [global]’ value is 'true', applies to all open panels.

When [global] is 'false', applies only to the current active panel.

getAllById

String [Object ID]

Object []

Get all Objects accessible in the current context that have the associated ID.

getAttribute

String [Attribute ID]

Object

Get an attribute registered in the context with the given ID.

getBuild

N/A

DashBoard version number (same value that appears in Help>About DashBoard)

Gets the version of DashBoard running the panel.

getComponentsById

String [Object ID]

Component []

Get all Java Swing components accessible in the current context that have the associated ID.

getCurrentUser

N/A

String

Returns the username of the current DashBoard user.

getIncludeById

String [Include ID]

IncludeReloadableContainer

Returns the first include with the given ID.

getListenerById

ID

getListenerById returns an object representing the listener.

This object has three public methods you can call: start(), stop(), and isStarted().

The return depends on which of the three methods is used:

If the  start() method is used, return is true if the listener started successfully; otherwise false.

If the stop() method is used, return is true if the listener stopped successfully; otherwise false.

If the isStarted() method is used, return is true if the listener is started; otherwise false.

Starts or stops a listener. Can also check whether a listener is started.

getModificationDate

String [File Path]

Returns the time the specified file was last modified, in Unix Epoch time (also known as POSIX time), as a LONG value.

Retrieves the time the specified file was last modified.

getObject

String [Key]

String

Retrieves stored object

getPosition

String [ID]

JAVA point object with point.x and point.y available.

Retrieves the horizontal (x) and vertical (y) position of the object, in pixels.

getPrivateString

String [Lookup ID]

String [Key]

String

Get a string defined in the lookup table with the specified lookup ID.

getScopedAttribute

String [Scope Name]

String [Attribute ID]

Object

Get an attribute in the named scope that has the given ID. Scopes are often internally defined by DashBoard.

getSize

String [ID]

Dimension object with d.width and d.height available

Retrieves the width and height of the specified panel object.

getString

String [Key]

String

Get a string defined in the global lookup table.

getTimerManager

N/A

ContextTimerManager

Get the timer manager for the context to access timers and perform operations on selected timers.

This function includes several methods.

hide

String [ID]

N/A

Hide the popup with the specified ID.

installTimer

String [Timer ID]

Boolean [Repeat]

Long [Delay]

Long [Repeat Rate]

Function [Task]

N/A

Create a timer with the given ID and register it in the ContextTimerManager. Start the timer after the specified delay, repeat the timer if requested at the specified rate. When the timer fires, run the specified ogScript function.

isTimerRunning

String [Timer ID]

Boolean

Report whether or not a timer exists and is in the “running” state.

true — a timer with the given ID exits and is in the “running” state.

false — a timer with the give ID does not exist or is not in the “running” state.

parseXML

String

org.w3c.dom.Document

Parse and return an XML document using the org.w3c.dom.Document API.

putObject

String [Key]

String [Value]

N/A

Defines a stored object.

putPrivateString

String [LookupID]

String [Key]

String [Value]

N/A

Add or replace a string in a private lookup table.

putString

String [key]

String [value]

N/A

Add or replace a string in the global lookup table.

reload

String [ID]

Null, if null is provided as the ID.

Rebuild the UI element with the given ID.

If no ID is provided, rebuilds entire document.

rename

String [ID]

String [Name]

N/A

Modify the text for a tab name, button, or label with the specified ID.

reposition

String [ID]

Integer [x position]

Integer [y position]

N/A

Moves object to specified XY pixel location

repositionByPercent

String [ID]

Integer [percent x]

Integer [percent y]

Boolean [center x]

Boolean [center y]

N/A

Moves object to the specified location, as percentage of the container width or height.

Center x and center y, when true, center the object at the location horizontally (x only), vertically (y only), or both (x and y).

reveal

String [ID]

N/A

Open a popup with the specified ID, or bring the tab with the specified ID to the foreground.

runXPath

String [XPath]

XML Document

or

XML Element

NodeList

Execute the given XPath command on the given Document or Element and return the results as a NodeList.

saveToFile

path data

overwrite

Returns true, if data is written successfully; otherwise false.

Saves data to a file. This function is typically used to save a byte array, string, or XML document to a file.

sendUDPAsBytes

String [Host]

Integer [Port]

 Byte[] [Data]

N/A

Send the given Data bytes to the provided Host/Port through UDP.

sendUDPString

String [Host]

Integer [Port]

String [Data]

N/A

Convert the given Data string to UTF-8 bytes and send them to the provided Host/Port through UDP.

setAnchorPoints

String [ID]

Boolean [top]

Boolean [left]

Boolean [bottom]

Boolean [right]

N/A

Specifies how an object moves if the user interface is resized for different monitor and window sizes. Anchors or releases an object to/from the top, left, bottom, or right sides of its container.

setSize

String [ID]

String [width]

String [height]

N/A

Resizes a panel object to the specified size.

Valid only in <abs/> containers.

setStyle

String [ID]

String [Style]

N/A

Set Style parameters for the component with the given ID if it exists.

setXML

String [ID]

String [new XML Content]

N/A

Dynamically generates UI components through ogscript.

Replaces the contents of an element with a string of XML code.

toBottom

String [ID]

N/A

Displays the object below all others in the same container. Objects are layered. If they overlap, higher layers are drawn over lower layers.

toTop

String [ID]

N/A

Displays the object above all others in the same container. Objects are layered. If they overlap, higher layers are drawn over lower layers.

upload

File [Upload File]

N/A

Open the File Upload dialog with the specified file.