Ross CustomPanel Development Guide
CustomPanels are applications which run within the DashBoard client. These may be served up by a device directly, or created by a user using DashBoard’s PanelBuilder feature, by writing XML code, or a combination of both. CustomPanels may integrate control of multiple connected devices to provide complete solutions to many workflow problems.
Advertisement
Advertisement
CustomPanel Development Guide
OGLML and ogScript
For DashBoard v7.0 (may also apply to later versions)
Thank you for choosing Ross
You've made a great choice. We expect you will be very happy with your purchase of Ross Technology.
Our mission is to:
1. Provide a Superior Customer Experience
• offer the best product quality and support
2. Make Cool Practical Technology
• develop great products that customers love
Ross has become well known for the Ross Video Code of Ethics. It guides our interactions and empowers our employees. I hope you enjoy reading it below.
If anything at all with your Ross experience does not live up to your expectations be sure to reach out to us at [email protected].
David Ross CEO, Ross Video
Ross Video Code of Ethics
Any company is the sum total of the people that make things happen. At Ross, our employees are a special group. Our employees truly care about doing a great job and delivering a high quality customer experience every day. This code of ethics hangs on the wall of all Ross Video locations to guide our behavior:
1. We will always act in our customers’ best interest.
2. We will do our best to understand our customers’ requirements.
3. We will not ship crap.
4. We will be great to work with.
5. We will do something extra for our customers, as an apology, when something big goes wrong and it's our fault.
6. We will keep our promises.
7. We will treat the competition with respect.
8. We will cooperate with and help other friendly companies.
9. We will go above and beyond in times of crisis. If there's no one to authorize the required action in
times of company or customer crisis - do what you know in your heart is right. (You may rent
helicopters if necessary.)
ii • Thank You for Choosing Ross
DashBoard CustomPanel Development Guide
DashBoard CustomPanel Development Guide
• Ross Part Number: 8351DR-007-7.0
• Release Date: November 02, 2015
Copyright
© 2015 Ross Video Limited. Ross®, openGear®, and any related marks are trademarks or registered trademarks of Ross
Video Ltd. All other trademarks are the property of their respective companies. PATENTS ISSUED and PENDING. All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted in any form or by any means, mechanical, photocopying, recording or otherwise, without the prior written permission of Ross Video.
While every precaution has been taken in the preparation of this document, Ross Video assumes no responsibility for errors or omissions. Neither is any liability assumed for damages resulting from the use of the information contained herein.
Patents
Patent numbers US 7,034,886; US 7,508,455; US 7,602,446; US 7,802,802 B2; US 7,834,886; US 7,914,332; US
8,307,284; US 8,407,374 B2; US 8,499,019 B2; US 8,519,949 B2; US 8,743,292 B2; GB 2,419,119 B; GB 2,447,380 B; and other patents pending.
DashBoard CustomPanel Development Guide
Thank You for Choosing Ross • iii
Company Address
Ross Video Limited
8 John Street
Iroquois, Ontario, K0E 1K0
Canada
Ross Video Incorporated
P.O. Box 880
Ogdensburg, New York
USA 13669-0880
General Business Office: (+1) 613 • 652 • 4886
Fax: (+1) 613 • 652 • 4425
Technical Support: (+1) 613 • 652 • 4886
After Hours Emergency: (+1) 613 • 349 • 0006
E-mail (Technical Support): [email protected]
E-mail (General Information): [email protected]
Website: http://www.rossvideo.com
iv • Thank You for Choosing Ross
DashBoard CustomPanel Development Guide
Contents
Introduction 11
DashBoard Data Model 16
DashBoard CustomPanel Development Guide
Contents • v
vi • Contents
OGLML Reference 62
DashBoard CustomPanel Development Guide
ogScript Reference 141
DashBoard CustomPanel Development Guide
Contents • vii
viii • Contents
DashBoard CustomPanel Development Guide
Appendices 206
Reserved MFC and DashBoard Connect (slot 0) OIDs ........................................... 212
DashBoard CustomPanel Development Guide
Contents • ix
x • Contents
DashBoard CustomPanel Development Guide
Introduction
About this Guide
This guide is part of the DashBoard Help Guides.
DashBoard Help Guides include the following volumes:
• DashBoard Help
• CustomPanel Development Guide (this guide)
• User Rights and Management
• NK Plugin Guide
This edition of the guide is written to the features and specifications of DashBoard version 7.0. There are numerous new features in DashBoard 7.0; they are highlighted in this guide with the following symbol:
7.0 Feature
This guide describes the tools available for creating CustomPanel applications within DashBoard.
The following sections are included:
•
DashBoard Data Model (page 16) – An overview of how data and UI elements are stored in
DashBoard.
•
OGLML Reference (page 62) – Describes OpenGear Layout Markup Language, which is an XML
specification for describing how UI elements are presented within the DashBoard client.
•
ogScript Reference (page 141) – Describes ogScript, which is cripting language, based on
JavaScript, for defining advanced behavior of CustomPanel applications
CustomPanel Overview
CustomPanels are applications which run within the DashBoard client. These may be served up by a device directly, or created by a user using DashBoard’s PanelBuilder feature, by writing XML code, or a combination of both. CustomPanels may integrate control of multiple connected devices to provide complete solutions to many workflow problems.
PanelBuilder
PanelBuilder is a DashBoard tool for creating custom interfaces for products from Ross Video, and partner companies, including openGear cards, DashBoard Connect devices, CamBot robotic camera systems, XPression graphics systems, BlackStorm video servers, and Carbonite and Vision Production
Switchers.
PanelBuilder allows users to create custom control interfaces with any combination of openGear control and monitoring parameters from any combination of openGear cards and DashBoard Connect devices.
DashBoard CustomPanel Development Guide
Users can build graphical navigation layouts based on signal flow or equipment location for efficient device and signal monitoring. Custom control panel layouts can provide user, or function specific control windows for specific events or situations that require quick access to various parameters from multiple devices.
Benefits:
• Create custom control panels. By eliminating unused controls, the operator can work with an uncluttered, efficient GUI that's perfect for the task at hand.
• Group various controls together from multiple products. Focus on the production, not how it's being produced.
• Create graphical navigation layouts. Present an overview of your facility with simple status indicators that can be drilled into to get to the details.
With CustomPanels, you can:
• Allow your operators to focus on the production, and not on the equipment being used. This is especially useful when operators are experts in what the production needs to be, but not how it's made such as in a House of Worship, School, or Corporate setting.
• Support a new workflow using existing equipment. For example select, preview and display static graphics using a Ross Video Master Control MC1-MK.
• Create a Network Operations Center view of geographically dispersed production equipment, with system health status aggregating up thru each level so that you can quickly drill down to where the trouble is when faults occur.
• Integrate control of multiple devices into a single, logically laid out control surface. For example, trigger graphics, video servers, and transitions from the same UI.
• Control other vendors' equipment. With over 50 openGear and DashBoard Connect partners, it's quite likely that the equipment you want to control already understands DashBoard. Otherwise, advanced users can take advantage of PanelBuilder's rich and powerful scripting support to communicate with 3rd party equipment via UDP.
CustomPanel Framework
Applications built in DashBoard’s PanelBuilder are referred to as CustomPanels. Application development in DashBoard utilizes a number of complementary technologies to provide user interface applications. These include:
• openGear Protocol (OGP)
• Resource XML files
• openGear Layout Markup Language (OGLML)
• ogScript
• Other control protocols (such as VDCP, RossTalk, etc.)
The openGear ecosystem, in general, consists of Devices (such as openGear Cards, or stand-alone products) and the DashBoard client. Devices communicate via network connection, and in the case of openGear cards CANBus interface.
DashBoard CustomPanel Development Guide
data source data store application client interface
.xml
.ogd
xml file access openGear
Plugin params menus external objects device card card card ogp json
TCP/IP oglml ogScript ogScript api
CANBus
External data source non-ogp device
Figure 1 – DashBoard Application Framework
DashBoard Panel applications consist of a number of elements that the designer uses to create an application. These are:
• Data sources
• Internal data store
• Application
•
Client Interface
Data Sources
Data may be sourced from several sources. These include:
• Physical devices connected via ogp
• XML files (.xml or .ogd)
• OGLML document with embedded parameter XML data
• Other external data sources
DashBoard manages synchronization between xml sources and, via OGP, physical devices. The data is stored in DashBoard’s internal data store. The details of OGP and JSON protocols are available to registered openGear partners, and are detailed in openGear Development Guide Part II - Software
(8200DR-06).
External data sources, not connected via OGP or a DashBoard xml file, must be managed by the user application via ogScript.
DashBoard allows for multiple data sources to be connected to any application. This allows for multiple devices in addition to local parameters and resources to be incorporated into a CustomPanel application.
Datastore
DashBoard maintains an internal data store of information. Using OGP or JSON protocol, DashBoard retrieves information about the descriptor and value of parameters, menus and external objects. Any changes to the Data store from the client or application is transmitted back to the device. Any changes to the Data store from the device are propagated to the Client. Code may be triggered when a parameter changes based upon an ogScript onchange event registered against parameter.
DashBoard CustomPanel Development Guide
Application
The application can be implemented using a variety of tools, depending upon the particular requirements. The application utilizes the data store to access device information. The following tools are available for developing applications:
• openGear plug-in: The basic plug-in automatically generates a user interface based upon the parameters and menus defined in the data store. The plug-in also support for OGP messaging to allow other basic device control.
• OGLML: OGLML is a markup language that may be used to create CustomPanel control layouts within DashBoard, beyond the default control layout provided by the openGear plug-in.
Applications built in OGLML may include customization on location, size and appearance of controls. The controls in an OGLML application manipulate parameters stored in the data store.
• ogScript: ogScript provides a JavaScript engine to extend the capability of OGLML-based applications. ogScript may also be used to access external data sources (either file or networkbased) as well as provide for custom interface to non-OGP devices.
Client Interface
The application is presented within the DashBoard client. DashBoard provides services to display the application, interface with devices and maintain the data store. DashBoard also provides mechanisms for device discovery, logging, alarms and features an interactive GUI, PanelBuilder, for the creation of
CustomPanel applications.
openGear Protocol
openGear Protocol (OGP) is a basic communications protocol between DashBoard and devices. It provides a mechanism to communicate the basic Data Model, manage parameter changes and describe a basic user interface. With OGP, devices can present a rich user interface using a standardized layout.
There are several variants of OGP, the details of which are described in in openGear Development
Guide Part II - Software (8200DR-06), available to registered openGear partners. The knowledge of the details of the protocol mechanics is not required to develop applications within DashBoard; OGP is simply a mechanism which communicates the Data Model between devices and DashBoard.
Resource XML File
The structure of a device’s parameters and menus may be expressed in XML format. This file can be generated in DashBoard from an existing device by right-clicking the device and selecting “Save
Configuration to file”. This will generate a “ .ogd” file containing the XML representation of the device.
A resource XML file is also generated by PanelBuilder, if “External Data Source Panel File” is selected when creating the CustomPanel. This file will be given the extension .xml.
It is also possible to declare resources directly within an OGLML document using the Resource XML syntax.
openGear Layout Markup Language (OGLML)
OGLML is an XML layout language which augments OGP by providing a set of tools to customize the layout and behaviour of a user interface presented in DashBoard. An OGLML document also allows controls from multiple devices to be combined into a single user interface, called CustomPanels.
CustomPanels may be designed interactively using DashBoard’s internal PanelBuilder feature.
PanelBuilder provides a GUI to customize the user interface, and generates an OGLML document.
When a new CustomPanel file is created within DashBoard’s PanelBuilder, an OGLML file with an extension .grid is created.
OGLML is strictly a layout tool for tailoring the presentation of a device’s user interface within
DashBoard. It simply specifies how a devices’ resources are displayed, and relies upon resources in the data store to provide the values for the content. The data store must be backed by a data source, through one of the mechanisms discussed above.
DashBoard CustomPanel Development Guide
ogScript
ogScript is a programming language developed to interact with Dashboard-enabled devices. It uses
JavaScript functions, syntax, and primitive object types. To enable CustomPanel developers to interact with panels and devices, ogScript adds some new global objects to JavaScript. Most JavaScript works in ogScript scripts, although you might run across an occasional item that does not work. ogScript may be embedded into an OGLML document to add additional functionality based on a set of trigger events (for example, when a page loads, when a parameter changes, mouse clicks, etc.). There are a number of api definitions to allow control of DashBoard’s features, access to the data store, and connect to external devices and data sources.
Getting Started
Building a CustomPanel Application
There are several steps in creating a CustomPanel application. The easiest way to get started is to interactively design a layout with DashBoard’s PanelBuilder. The basic steps involved are:
• Define data sources
• Define local parameters
• Add controls to the layout in PanelBuilder
• Edit OGLML file for fine-tuning
• Add ogScript to the CustomPanel for advanced functionality
PanelBuilder is an interactive tool that allows quick and easy layout of control; its output is an OGLML document (with a
.grid extension).
Refer to DashBoard Online Help or the DashBoard_User_Guide (8351DR-004) for detailed instructions on building CustomPanels in PanelBuilder.
DashBoard CustomPanel Development Guide
DashBoard Data Model
In This Chapter
This chapter describes the underlying data model for openGear and DashBoard Connect devices.
The following topics are discussed:
•
DashBoard Data Model (page 16) – The data model, including parameters, constraints and menus
•
Device Data Model
Data Object Hierarchy
DashBoard stores a device’s data representation in an object hierarchy. card statusmenu menu configmenu menugroup
. . .
menu
. . .
params param constraint param config
. . .
value param
(sub-OID) param
(sub-OID)
. . .
struct descriptor
Figure 2 - Data Object Hierarchy in DashBoard
This hierarchy is explicitly exposed in the XML representation. OGP does not explicitly reference the data through the object hierarchy, but individual data elements may be accessed via their OIDs.
DashBoard CustomPanel Development Guide
Device / Card
All information regarding a device is encapsulated within the device object. This is encapsulated with a
<card> tag in the XML representation. Each node in the DashBoard tree is treated as an independent device object. The device object contains a list of parameters and menu-groups.
Each device node in the DashBoard tree has a unique node-id. This node-id is used by DashBoard to reference parameters from multiple devices within the same client interface. The node-id can be determined by selecting the node in the DashBoard tree and selecting “View Connection Information” from the context menu.
Figure 3 - Connection Information
Parameters
The configuration and state of any device can be represented by a list of parameters holding information about the device, including:
• identification: device type and supplier name, software revision, etc.
• status: alarms, voltage, current, temperature, input signal presence and format, etc.
• configuration: user-specified setup parameters (gain, delay, output video format, etc.)
Each parameter is identified with an Object Identifier (OID), and consists of two parts: the descriptor and the value. The descriptor defines the structure of the data, and the value is the content, which is dependent on the descriptor. The descriptor may also specify a constraint, which limits the value to a certain set of valid values.
Object Identifiers (OIDs)
Each parameter is identified by a unique object ID (OID). There are 2 types of OIDs supported: numeric and string. All devices must support numeric OIDs, and may optionally support string OIDs. However, use of meaningful string OIDs is strongly recommended for new designs, as it clarifies code and simplifies the development of CustomPanels. Handling of Numeric and String OID parameters utilize different message types. Devices implementing String OIDs must support both message types.
Numeric OIDs
Numeric OIDs are 2-byte integers, and referenced in this document as a 16-bit hex value, for example:
0x0105. In JSON messaging, numeric OIDs are encoded as strings. For example, the OID 0x0105 is encoded as the string "0x105".
DashBoard CustomPanel Development Guide
DashBoard Data Model • 17
String OIDs
String OIDs allow text-based parameter identifiers, and must follow the following encoding rules:
• Must not contain spaces
• May only contain the following characters: a-z A-Z 0-9 .(dot) _ (underscore)
• Are case sensitive
• There is no set limit to the String OID identifier length; however string OIDs over 255 characters cannot be carried over CAN or TCP/IP binary protocol.
A string OID identifier should not be confused with the parameter name. A string ID is the variable name, the Parameter Name is the display name for the parameter. For example a parameter may have the OID “mle.2.keyer.3.ckey-state” and the parameter name could be “Chroma Key”. Software refers to the value “mle.2.keyer.3.ckey-state”, but the default label on the DashBoard GUI would be “Chroma
Key”.
Descriptors
Parameters are defined using a descriptor containing its name, data type, data length, constraint (set of permitted values) and other information. When DashBoard first contacts a device, it requests the list of parameters for that device, and the descriptor for each parameter. This information is used to create an appropriate user interface for the device and to properly interpret and display parameter values reported by the device.
In JSON messaging, descriptor objects are identified by the naming convention _d_oid.
The descriptor for each parameter contains the following fields:
Field
oid version name data type data size access precision widget constraint
Description
Object Identifier for this Parameter
Version of the descriptor
Parameter name to be displayed in a user interface
Data type (integer, float, string, or array thereof)
Nominal size of the data field
Read/write access indicator
Precision to displayed for printed numbers
Graphical display hint for this parameter
An object specifying the set of permitted values for the parameter
Version
The current version is 2. Permitted versions are 0, 1 and 2. Versions 0 and 1 are identical to version 2, except that widget hints are ignored.
Name
This field provides the parameter name to be displayed in DashBoard. The name does not need to be unique. It may be ignored by some software (e.g. the SNMP agent).
Data Type and Size
Data type indicates the storage type for the parameter value.
DashBoard CustomPanel Development Guide
Access
This field indicates whether the parameter can be modified. This enables the control software to display an appropriate control for read-only values, or to disallow edits. In OGP, the supported values are:
Access
ACCESS_READWRITE
ACCESS_READONLY
Value
0x01
0x00
Description
Parameter may be modified by the control client
Parameter is read-only, and may not be set by the client
Precision
When used with numbers — this field defines the number of digits following the decimal point displayed for printed numbers. It applies mainly to floating point numbers.
When used with string arrays —this field defines the maximum number of bytes reserved for a single element in the array. If it is 0, no limit is set for each element, and the maximum number of bytes in a parameter value is shared arbitrarily amongst all elements in the array.
Constraint
Constraints allow data to be limited to a certain range or certain values.
Widget Hint
The widget hint specifies the type of graphical control that should be used to display this parameter. To ensure backward compatibility with DashBoard 1.0, widget hints are ignored if the version field is less than 2.
Constraints
Constraints are an important part of the parameter descriptor. It specifies a legal range of values which the value of the parameter may take. Certain constraints also impact how the parameter is displayed within DashBoard. Certain widgets require specific constraints, while others may behave in different manners depending upon the constraint applied to the parameter. For array parameters, the same constraint applies to each element of the array.
Constraints are specified through a numeric identifier called ctype. The supported constraint types are:
Constraint Name
NULL_CONSTRAINT
RANGE_CONSTRAINT
CHOICE_CONSTRAINT
ctype
0
1
2
Param Types
All
INT16_PARAM
INT32_PARAM
INT16_ARRAY
INT32_ARRAY
FLOAT_PARAM
FLOAT_ARRAY
INT16_PARAM
INT16_ARRAY
Description
Parameter is unconstrained.
Parameter is bounded by a min-max range. Display min-max range may be different from the value range.
EXTENDED_CHOICE
STRING_CHOICE
RANGE_STEP_CONSTRAINT
3
4
5
INT16_PARAM
INT16_ARRAY
STRING_PARAM
STRING_ARRAY
INT16_PARAM
INT32_PARAM
Parameter must be selected from a set (enumeration) of name-value pairs (up to 255 choices)
Parameter must be selected from a set (enumeration) of name-value pairs (more than 255 choices)
Provides a set of available choices. Parameter may be selected from this set, but arbitrary values are also permitted.
Parameter is bounded by a min-max range. Step size indicates the amount to
DashBoard CustomPanel Development Guide
DashBoard Data Model • 19
Note:
Constraint Name
ALARM_TABLE
EXTERNAL_CONSTRAINT
ctype
10
11
Param Types
INT16_ARRAY
INT32_ARRAY
FLOAT_PARAM
FLOAT_ARRAY
INT16_PARAM
INT32_PARAM
INT16_ARRAY
All
Description
increment/decrement the value each time it is changed.
Each bit in the parameter is a status flag, so param can display 16 or 32 concurrent named error conditions.
Indicates that the constraint is encoded in an external object, rather than encoded within the descriptor.
Constraints are normally embedded within the parameter descriptor however; they may also be encoded separately as external objects (which allow longer choice lists, etc.).
A detailed definition of each constraint type, and rules for encoding each constraint, are provided below.
The constraint is considered to be a
contract for the parameter. DashBoard will not attempt to set a parameter to a value that violates the constraint. Similarly, the device must ensure that the value reported for each parameter complies with the constraint.
Behavior of some control software may be unpredictable if the reported value violates the constraint.
Note
Unconstrained
To leave a parameter unconstrained, use the NULL_CONTRAINT constraint. Any parameter which does not have any other constraint applied must specify the NULL_CONSTRAINT.
Range Constraints
To constrain a numerical parameter to a specific range of values, the RANGE_CONSTRAINT or
RANGE_STEP_CONSTRIANT must be specified. Both constraint types allow a minimum and maximum parameter value (minValue, maxValue). Additionally, an optional display minimum and maximum value (minDisp, maxDisp) may also be specified. This allows the display range to map to normalized parameter range. The value to be displayed is determined by the following linear mapping: 𝑑𝑑𝑑𝑑𝑑𝑑𝑑𝑑𝑑𝑑𝑑𝑑𝑑𝑑𝑑𝑑𝑑𝑑 𝑣𝑣𝑑𝑑𝑑𝑑𝑣𝑣𝑑𝑑 = 𝑚𝑚𝑑𝑑𝑚𝑚𝑚𝑚𝑑𝑑𝑑𝑑𝑑𝑑 +
(𝑣𝑣𝑣𝑣𝑣𝑣𝑣𝑣𝑣𝑣−𝑚𝑚𝑚𝑚𝑚𝑚𝑚𝑚𝑣𝑣𝑣𝑣𝑣𝑣𝑣𝑣)×(𝑚𝑚𝑣𝑣𝑚𝑚𝑚𝑚𝑚𝑚𝑚𝑚𝑚𝑚−𝑚𝑚𝑚𝑚𝑚𝑚𝑚𝑚𝑚𝑚𝑚𝑚𝑚𝑚)
(𝑚𝑚𝑣𝑣𝑚𝑚𝑚𝑚𝑣𝑣𝑣𝑣𝑣𝑣𝑣𝑣−𝑚𝑚𝑚𝑚𝑚𝑚𝑚𝑚𝑣𝑣𝑣𝑣𝑣𝑣𝑣𝑣)
Note that minDisp and maxDisp must be the same data type as the parameter. For example, to display the value of a 12-bit register (0-4095) as a percentage, set
• (minValue, maxValue) = (0, 4095)
• (minDisp, maxDisp) = (0, 100)
The difference between RANGE_CONSTRAINT and RANGE_STEP_CONSTRAINT is the latter also allows a step size to be specified. The step is specified in the same data type as the parameter and is the minimum change increment on the parameter value (not necessarily the display value).
It is strongly recommended that the range (maxValue – minValue) be evenly divisible by the provided step size. Otherwise, when starting from the minimum, the parameter will use values of minValue + n * stepSize and when starting from the maximum, the parameter will use values of maxValue – n * stepSize.
Range constraints applied to an array parameter apply to all members of the array.
DashBoard CustomPanel Development Guide
Choice Constraints
Choice constraints allow a parameter to provide a list of choices. CHOICE_CONSTRAINT and
EXTENDED_CHOICE constraints provide a mechanism to create a set of enumerated values for an
INT16 or INT32 parameter. This allows integer types to be limited to a specific set of valid values, as well as providing a mechanism to provide text choices in the DashBoard UI for these parameters.
STRING_CHOICE constraint provides a set of default values which may be populated in a
STRING_PARAM, however unlike CHOICE_CONSTRAINT and EXTENDED_CHOICE, it does not limit the user to only these values, any arbitrary value may still filled into the string.
Alarms
Assigning an ALARM_TABLE constraint to an integer parameter tells DashBoard to treat the integer as an array of alarms. When alarms are set, they will impact the overall status reporting of the device.
External Constraints
An EXTERNAL_CONSTRAINT is used to indicate that the constraint for this parameter is provided in an external object, rather than embedded within the parameter descriptor.
This constraint simply provides a reference to the external object, encoded as shown in the following table.
Parameter Structure Objects
7.0 Feature
DashBoard version 7 and later allows user defined structures to be defined within parameters, called
structs. Structs are defined by encoding a struct descriptor within the value object of a parameter. This is done by inserting an array of sub-OID descriptors (param objects) into the value field of a parameter.
Structs must have their type set to STRUCT or STRUCT-ARRAY.
A parameter may inherit the struct descriptor from another parameter through use of a STRUCT constraint which specifies a templateoid. The templateoid specifies the OID of a parameter whose descriptor will be inherited, thus eliminating the need to define identical struct descriptor for each instance of a struct parameter.
Parameter References
7.0 Feature
Sub-params within a structure may also be defined as references to other parameters. These behave much like C++ or Java variable references. A parameter reference inherits the referenced parameter’s type, attributes and constraints.
Menus
How a device is displayed in DashBoard is determined by the menu data provided by the device.
DashBoard provides two methods for a device to specify menu layout and structure:
• Default openGear layout
• openGear Layout Markup Language (OGLML)
Default Menu Layout
The default menu layout is designed to make it very simple for devices to display a menu structure.
Each menu comprises a name and a list of object identifiers specifying the parameters to be displayed in the menu. Menus are organized into groups, where each group comprises a name and an array of menus.
Menus are divided into menu groups. The default layout displays only 2 groups:
• Group 0: Status (read-only)
• Group 1: Configuration
DashBoard CustomPanel Development Guide
DashBoard Data Model • 21
Below is an example of the default layout:
Menu Tabs Menu Tabs
Parameters
Menu Group 0 Menu Group 1
Figure 4 - Menu Layout
Each product may define any number of menus and groups; however, the DashBoard control system recognizes two groups in the default UI layout: group 0 = status parameters (read only), and group 1 = configuration parameters. Other menu groups are not displayed in the default UI layout presented by
DashBoard, but may be used in OGLML UI layouts
OGLML Menu Layout
Advanced menu layouts are available with openGear Layout Markup Language (OGLML). OGLML documents can replace an individual menu or the entire device configuration in DashBoard
Customizing Menus Using Display Hints
Overview
The descriptor for each parameter includes a widget hint to allow the device designer to specify the type of control to be used to display the parameter. The hints available depend on the parameter type, the constraint type, and the values in the constraint for each parameter. This allows the designer to customize the menu for each device.
DashBoard 1.0 ignored widget hints and provided a default control based on parameter and constraint type. For backwards compatibility, DashBoard 2.0 (and later) ignores widget hints for parameters with the version field set to 0 or 1, providing the same default behavior as DashBoard 1.0. To use widget hints, it is necessary to set the version field within the parameter to 2.
DashBoard CustomPanel Development Guide
When a read-only parameter provides a widget hint, a read-only version of the parameter’s preferred widget is used. The exceptions are WIDGET_DEFAULT (displays like DashBoard 1.0) and Alarm
Tables (display the alarm). Hints for status menu parameters are overridden for correct display in that space.
Universal Hints
The following widget hints may be used for any parameter type:
Widget Name
WIDGET_DEFAULT
WIDGET_TEXT_DISPLAY
WIDGET_HIDDEN
WIDGET_LABEL
Value Description
0 DashBoard will choose what it thinks is the best widget to use for the parameter type and constraint (makes the parameter work like it does with DashBoard 1.0).
1
2
100 shows a read-only version of the parameter value (uses same widget that is shown when WIDGET_DEFAULT parameter is set to read-only). still uses space on the menu page and shows the label for the parameter but show a blank area on the menu page where the widget would be.
Displays the value of the parameter as a read-only label
Separators, Titles and Layout Hints
The following hints are used with string parameters to provide separators, titles, and extended layout options for menus. Parameters using these widget hints are treated as read only and constant – they do not update live on the screen. Examples of each hint are shown below.
Widget Name
WIDGET_TITLE_LINE
WIDGET_LINE_ONLY
WIDGET_TITLE_ONLY
WIDGET_PAGE_TAB
WIDGET_TITLE_HEADER
Value Description
5 displays the value of the String parameter as a label with all other parameter labels and a line across the content area of the menu page.
6 displays a line across the content area of the menu page with no label on the left.
7
8
10 displays the value of the String parameter as a label with empty space in the content area of the menu page. creates a 3rd-level tab within the menu page. The value of the parameter is used as the tab label. displays a title over the content area of the menu with the value of the parameter used as the header text.
WIDGET_TITLE_LINE (5)
This displays the value of the String parameter as a label aligned with all other parameter labels, and a line across the content area of the menu page. The name of the parameter is ignored.
Figure 5 -
WIDGET_TITLE_LINE hint
.
DashBoard CustomPanel Development Guide
DashBoard Data Model • 23
WIDGET_LINE_ONLY (6)
This displays a line across the content area of the menu page with no label on the left. The name and value of the parameter are ignored.
Figure 6 - WIDGET_LINE_ONLY hint.
WIDGET_TITLE_ONLY (7)
This displays the value of the String parameter as a label with empty space in the content area of the menu page. The name of the parameter is ignored.
Figure 7 - WIDGET_TITLE_ONLY hint
WIDGET_PAGE_TAB (8)
Whenever a new String parameter with a WIDGET_PAGE_TAB hint is found on a menu page, a new
3 rd
-level tab is created inside of that menu page. The label on that tab will be the value of the String parameter. All parameters listed after each WIDGET_PAGE_TAB String parameters (until the next such parameter) are placed on a menu page inside of that 3 rd
-level tab.
Figure 8 - A menu with WIDGET_PAGE_TAB hints.
Note
Whenever WIDGET_PAGE_TAB hints are used on a menu, the first OID in the menu should be for a String parameter with a widget hint defining the first tab’s label.
WIDGET_TITLE_HEADER (10)
Displays a title over the content area of the menu with the value of the parameter used as the header text.
No label is shown on the left and the name of the parameter is ignored.
Figure 9 - WIDGET_TITLE_HEADER hint.
DashBoard CustomPanel Development Guide
Array Layout Hints
By default, all array parameters are displayed horizontally across a menu page. Adjacent OIDs of the same size will format in DashBoard in a tabular format. For example, 3 array parameters with 4 elements each, the layout would appear as:
Figure 10 - Default array layout.
Column headers can be added by adding a read-only INT16_ARRAY parameter to the menu immediately before the other arrays (widget hint WIDGET_ARRAY_HEADER_HORIZONTAL). The parameter is expected to have a choice constraint. The string values of the elements of this parameter provide the column headers. The resulting display is:
Figure 11 - WIDGET_ARRAY_HEADER_HORIZONTAL hint.
Array elements can also be given a vertical layout. Changing the widget hint for the header array to
WIDGET_ARRAY_HEADER_VERTICAL provides the following layout:
Figure 12 - WIDGET_ARRAY_HEADER_VERTICAL hint.
Array layout can be specified by including a read-only INT16_ARRAY parameter as a header, with one of the following widget hints:
Widget Name
WIDGET_ARRAY_HEADER_VERTICAL
Value Description
15 indicates that the associated array parameter and all subsequent parameters should be displayed in a vertical layout
WIDGET_ARRAY_HEADER_HORIZONTAL 16 indicates that the associated array parameter and all subsequent parameters should be displayed in a horizontal layout
Normally sequential array OIDs will be formatted as a single table. If it is desired to break a block of sequential array OIDs into multiple tables, it is necessary to insert a non-array OID, or switch from a horizontal layout hint to a vertical layout hint (or vice versa). If multiple arrays of different size are encoded with different sizes, the layout may be unpredictable.
DashBoard CustomPanel Development Guide
DashBoard Data Model • 25
WIDGET_ARRAY_HEADER_VERTICAL (15)
This hint indicates that the associated array parameter and subsequent parameters should be displayed in a vertical layout. The elements of the parameter will be used as row labels for display. The names of the following arrays are used as column labels. The header should be a read-only INT16_ARRAY parameter with a choice constraint to allow meaningful text labels. The elements of each array are displayed as specified by the widget hint for that array.
The vertical array layout will be applied until another WIDGET_ARRAY_HEADER_VERTICAL starts a new set of vertical columns, a WIDGET_ARRAY_HEADER_HORIZONTAL declares that subsequent arrays should be laid out horizontally, a non-array element in found on the page, or the end of the menu page is reached.
Figure 13 shows an INT16_ARRAY parameter named "Channel", provides a vertical layout and row
labels for 7 array parameters named “Channel Update”, “Source”, “Vertical Channel”, “Delay Array
(ms)”, “Gain (dB)”, “Invert”, and “Destination”.
Figure 13 - INT6_ARRAY vertical layout example.
WIDGET_ARRAY_HEADER_HORIZONTAL (16)
The WIDGET_ARRAY_HEADER_HORIZONTAL is used to create a header over a horizontal array.
It will also will end a block of vertical array elements. Each element in the header parameter will be displayed as a column header.
Figure 14 shows an INT16_ARRAY parameter named "Channel" providing a horizontal layout and
column labels for 7 array parameters named “Horizontal Channel”, “Source”, “Delay Array (ms)”,
“Gain (dB)”, “Invert”, “Destination” and “Transition”.
DashBoard CustomPanel Development Guide
Figure 14 - INT16_ARRAY horizontal layout example.
INT16/INT32 Parameters with Choice Constraints
The following hints apply to INT16, INT16_ARRAY, INT32, and INT32_ARRAY Parameters provided that they use a constraint of type CHOICE or EXTENDED_CHOICE. There are some restrictions for certain hints (checkboxes and toggle buttons are only valid for 2-choice constraints, buttons with and without prompts are only valid for single-choice and 2-choice constraints). If a widget hint is used incorrectly, the combo box will be substituted in place of the chosen widget. Display examples are provided below.
Widget Name
WIDGET_COMBO_BOX
WIDGET_CHECKBOX
WIDGET_RADIO_HORIZONTAL
WIDGET_RADIO_VERTICAL
WIDGET_BUTTON_PROMPT
WIDGET_BUTTON_NO_PROMPT
WIDGET_BUTTON_TOGGLE
WIDGET_FILE_DOWNLOAD
WIDGET_MENU_POPUP
Value Description
7 Displays a dropdown list of selectable options. This is the default widget used for any choice parameter with more than 1 choice provided.
8
9
10
11
12
Displays a checkbox. Checkboxes only apply to parameters with exactly 2 choices. The first choice is considered false or unchecked; the second choice is considered true or checked.
Displays a radio button for each integer value option.
The radio buttons are placed beside each other horizontally on the page.
Displays a radio button for each integer value option.
The radio buttons are placed in a vertical column.
Provides a button with confirmation prompt.
Whenever the button is pressed and confirmed, the parameter value is send to the device.
Provides a button without confirmation prompt.
Whenever the button is pressed, the parameter value is send to the device.
13
18
20
Displays a toggle buttons. This hint applies only to parameters with exactly 2 choices. The first choice is shown when the button is up (not pressed); the second choice is shown when the button is down
(pressed).
Displays a file download widget. This hint requires an external object with an OID matching the value of the parameter.
Each value in the parameter must refer to the menu
ID of an OGP Menu. The choice corresponding to the parameter value has its name used as the value displayed on a button. When the button is pressed, the menu with an OID corresponding to the parameter value is displayed in a popup menu.
DashBoard CustomPanel Development Guide
DashBoard Data Model • 27
Widget Name Value Description
WIDGET_RADIO_TOGGLE_BUTTONS 22 Displays a toggle button for each integer value option. The toggle buttons are placed beside each other horizontally on the page.
WIDGET_TREE 31 Displays a tree control. Tree elements are defined by the elements of the choice constraint. The tree hierarchy is defined by “-” characters at the beginning of the choice. See detailed description below for more information.
WIDGET_TREE_POPUP 32 Displays the tree (same definition as
WIDGET_TREE) in a combo box control. See detailed description below for more information.
WIDGET_COMBO_BOX (7)
Display a dropdown list of selectable options. This is the default widget used for any choice parameter with more than 1 choice provided.
Figure 15 - WIDGET_COMBO hint
WIDGET_CHECKBOX (8)
Displays a checkbox. Checkboxes only apply to integer choice constraints with exactly 2 choices.
The first choice is considered false or unchecked; the second choice is considered true or checked.
Figure 16 - WIDGET_CHECKBOX hint.
WIDGET_RADIO_HORIZONTAL (9)
Displays a radio button for each element in the choice constraint. The radio buttons are placed beside each other horizontally on the page.
Figure 17 - WIDGET_RADIO_HORIZONTAL hint
DashBoard CustomPanel Development Guide
WIDGET_RADIO_VERTICAL (10)
Displays a radio button for each element in the choice constraint. The radio buttons are placed in a column vertically on the page.
Figure 18 - WIDGET_RADIO_VERTICAL hint
WIDGET_BUTTON_NO_PROMPT (12)
This hint can only be used for a parameter having a choice constraint with one or two choices. It displays a button with the name of the first choice as the button label. When the button is pressed, a parameter set request is sent to the device immediately (without user confirmation). If the parameter has only one choice, the value of that choice is sent to the device. If the parameter has two choices, the value of the second choice is sent. The device should normally reset the parameter value to the first choice when it acknowledges the set request.
Figure 19 shows a single-choice parameter named "Factory Defaults" with a hint of
WIDGET_BUTTON_NO_PROMPT and a value of "Reset". There will be no confirmation dialog.
Figure 19 - WIDGET_BUTTON_NO_PROMPT hint.
WIDGET_BUTTON_PROMPT (11)
This hint can only be used for a parameter having a choice constraint with one or two choices. It is the default widget used when only one choice is available. It displays a button with the name of the first choice as the button label. When the button is pressed, a confirmation dialog is displayed before sending anything to the device. The dialog uses the format: “[Button Label] [Parameter Name]?” So a choice called “Reset” with a parameter named “Parameter Values” would display “Reset Parameter Values?” as the prompt. When the button is pressed and confirmed, a parameter set request is sent to the device. If the parameter has only one choice, the value of that choice is sent to the device. If the parameter has two choices, the value of the second choice is sent. The device should normally reset the parameter value to the first choice when it acknowledges the set request. If a two-state button is desired, see
WIDGET_BUTTON_TOGGLE.
Figure 20 shows single-choice parameter named "Factory Defaults" with a hint of
WIDGET_BUTTON_PROMPT and a value of "Reset".
DashBoard CustomPanel Development Guide
DashBoard Data Model • 29
Figure 20 - WIDGET_BUTTON_PROMPT hint
Note
Two choices are necessary for using WIDGET_BUTTON_PROMPT and
WIDGET_BUTTON_NO_PROMPT with array parameters.
WIDGET_BUTTON_TOGGLE (13)
Toggle buttons work exactly the same was a checkbox. The toggle button applies only to integer
constraints with exactly two choices. The name of the first choice is shown when the button is up (not pressed) and the name of the second choice is shown when the button is down (pressed).
Figure 21 shows a two-choice integer parameter named "Bold Toggler" with choice 1 set to "First
Value" and choice 2 set to "Second value" The figure shows the button’s display for both before and after a button toggle.
Figure 21 - WIDGET_BUTTON_TOGGLE hint
WIDGET_FILE_DOWNLOAD (18)
This hint requires that an external object with an OID matching the value of the parameter be available.
For each choice in the parameter’s choice constraint, the choice value represents an external object’s
OID and the value represents the filename to display. When the ‘save’ button is pressed, DashBoard requests the external object with the given OID and save the external object’s bytes to the filename/location defined by the user (default filename is defined in the choice constraint).
DashBoard CustomPanel Development Guide
Figure 22 - WIDGET_FILE_DOWNLOAD hint
WIDGET_MENU_POPUP (20)
This hint requires that an OID Menu with a menu ID matching the value of the parameter be available.
For each choice in the parameter’s choice constraint, the choice value represents a menu’s ID and the choice name represents the label to display on the button. When the button is pressed, DashBoard displays the menu with the given ID as a popup menu.
Figure 23 - WIDGET_MENU_POPUP hint
DashBoard CustomPanel Development Guide
DashBoard Data Model • 31
WIDGET_RADIO_TOGGLE_BUTTONS (22)
Displays a radio toggle button for each integer value option. The radio toggle buttons are placed beside each other horizontally on the page.
Figure 24 - WIDGET_RADIO_TOGGLE_BUTTONS hint
WIDGET_TREE (31)
Displays a tree control. Tree elements are defined by the elements of the choice constraint. The tree hierarchy is defined by “-” characters at the beginning of the choice. When an element in the tree is selected, the parameter value is set to the value of the selected choice. All other expand/collapse changes are local only to the DashBoard on which the change occurred.
“+” indicates that an element should be expanded by default.
Figure 25 - WIDGET_TREE hint
The tree pictured above is defined by the following list of choices:
1. Element 1<i:>
2. +Element 1 - 1<i-u:http://127.0.0.1/icons/small/sound2.png>
3. +Element 1 - 2<i:>
4. +-Element 1 - 2 - 1<i:>
5. +-Element 1 - 2 - 2<i:>
6. +-Element 1 - 2 - 3<i:>
7. Element 2
8. +-Element 2 - 1
9. +-Element 2 - 2
10. +-Element 2 - 2 - 1
11. +-Element 2 - 2 - 2
12. +-Element 2 - 2 - 3
13. +--Bob!
14. Element 3
15. Element 4
DashBoard CustomPanel Development Guide
WIDGET_TREE_POPUP (32)
Displays the tree (same definition as WIDGET_TREE) in a combo box control. This functions the same as WIDGET_TREE, with the difference that only the currently selected item shows by default. When the user clicks on the value, a popup appears, allowing selection to be made.
Figure 26 - WIDGET_TREE_POPUP hint
Hints for Numeric Parameters with Other Constraints
The following hints are for INT16, INT16_ARRAY, INT32, INT32_ARRAY, FLOAT, and
FLOAT_ARRAY parameters and arrays with constraints other than choices. Most hints have specific restrictions. Details for each hint are provided below.
Widget Name
WIDGET_SLIDER_HORIZONTAL
WIDGET_SLIDER_VERTICAL
WIDGET_SPINNER
WIDGET_TEXTBOX
WIDGET_IP_ADDRESS
WIDGET_PROGRESS_BAR
WIDGET_AUDIO_METER
WIDGET_TIMER
WIDGET_COLOR_CHOOSER
Value Description
3 Displays a horizontal slider control. This is the default control for range-bounded integer and floating point parameters when they are not used in an array
4
5
6
14
17
19
21
23
WIDGET_SLIDER_HORIZONTAL_NO_LABEL 24
WIDGET_SLIDER_VERTICAL_NO_LABEL
WIDGET_VERTICAL_FADER
25
26
Displays a vertical slider control. This is the default control for range-bounded integer and floating point array parameters
Displays a spinner (entry field plus up/down arrows). This is the default for unbounded INT16 parameters. This cannot be used for unbounded FLOAT or
INT32 parameters.
Displays a numeric entry field. This is the default for unbounded FLOAT and INT32 parameters.
Displays an IP Address entry field.
Only works with unconstrained INT32 parameters.
Displays a read-only progress bar control.
Displays a read-only audio level meter control with green, yellow, and red markers.
Displays a label that counts down from the parameter value to 0 when double-clicked.
Put a colour chooser as an element in the
UI. Changes made to the colour chooser are instantly sent to the device.
Color values are INT32 values in ARGB format.
Displays a horizontal slider control with no label
Displays a vertical slider control with no label
Displays a vertical slider that looks like a fader bar
DashBoard CustomPanel Development Guide
DashBoard Data Model • 33
Widget Name
WIDGET_TOUCH_WHEEL
WIDGET_HEX_SPINNER
WIDGET_ABSOLUTE_POSITIONER
WIDGET_ABSOLUTE_CROSSHAIR
WIDGET_JOY_STICK
WIDGET_COLOR_CHOOSER_POPUP
WIDGET_GRAPH
Value Description
27 Displays a touch wheel control
28 Displays a spinner (entry field plus up/down arrows). Display the value in
Base 16.
29
30
34
33
256
Provides a 2-axis absolute positioning element. When used as an INT16, the 8
LSBs represent the X coordinate and the 8
MSBs represent the Y coordinate. When used as an INT32, the 16 LSBs represent the X coordinate and the 16 MSBs represent the Y coordinate.
A crosshair in a box can be dragged to the absolute position of the value in 2-D space.
Position a value in 2-D space. When used as an INT16, the 8 LSBs represent the X coordinate and the 8 MSBs represent the
Y coordinate. When used as an INT32, the
16 LSBs represent the X coordinate and the 16 MSBs represent the Y coordinate.
A crosshair that snaps to the center when released makes changes in +/- X, +/- Y relative to the offset from the center.
Position a value in 2-D space. When used as an INT16, the 8 LSBs represent the X coordinate and the 8 MSBs represent the
Y coordinate. When used as an INT32, the
16 LSBs represent the X coordinate and the 16 MSBs represent the Y coordinate.
Displays a joystick and modifies the X, Y values as the joystick is dragged north, south, east, and west of the center.
Display a combo box control showing the
‘current’ colour. On click, show the colour chooser. If “Live” is togged on, update the parameter value immediately. If “Live” is toggled off, update the parameter value when the popup is closed.
Color values are INT32 values in ARGB format.
Displays a plot graph of a parameter’s value over time.
WIDGET_SLIDER_HORIZONTAL (3)
Horizontal sliders are the default widgets used for range-bounded integer and floating point numbers when they are not used in an array. Sliders are not available for unbounded (null constraint) parameters.
Figure 27 shows an integer parameter with a range constraint bounded by (0, 200) and a
WIDGET_SLIDER_HORIZONTAL hint.
Figure 27 - WIDGET_SLIDER_HORIZONTAL hint
DashBoard CustomPanel Development Guide
WIDGET_SLIDER_VERTICAL (4)
Vertical sliders are the default widgets used for range-bounded integer and floating point numbers when they are used in an array. Sliders are not available for unbounded (null constraint) parameters.
The following is an integer parameter with a range constraint bounded by (0, 994) and a
WIDGET_SLIDER_VERTICAL hint.
Figure 28 - WIDGET_SLIDER_VERTICAL hint
WIDGET_SLIDER_HORIZONTAL_NO_LABEL (24)
Figure 29 - WIDGET_SLIDER_HORIZONTAL_NO_LABEL hint
WIDGET_SLIDER_VERTICAL_NO_LABEL (25)
Figure 30 - WIDGET_SLIDER_HORIZONTAL_NO_LABEL hint
WIDGET_VERTICAL_FADER (26)
This hint specifies that the number shall be displayed as a vertical fader bar. The user can adjust the level by dragging the handle of the fader up or down.
DashBoard CustomPanel Development Guide
Figure 31 - WIDGET_VERTICAL_FADER hint
DashBoard Data Model • 35
WIDGET_TOUCH_WHEEL (27)
This hint specifies that the number shall be displayed as a touch wheel (or circular slider). The user grabs the dot on the circle and drags clockwise to increment the value and counter clockwise to decrement it. The touch wheel can be configured to take a specified number of revolutions to go from the minimum value to the maximum value and can also be configured to roll over to the minimum or maximum when the limits of the range are reached.
Figure 32 - WIDGET_TOUCH_WHEEL hint
WIDGET_PROGRESS_BAR (17)
This hint specifies that the number shall be displayed as a horizontal progress bar. For a range-bounded parameter, the progress bar displays the specified range (similar to a slider). For an unbounded parameter, the progress bar displays from 0 to 100%.
Figure 33 - WIDGET_PROGRESS_BAR hint
WIDGET_SPINNER (5)
Spinner widgets provide a compact way to navigate a bounded integer or float parameter. Spinner widgets are the default widgets used for unbounded int16 parameters. The spinner widget cannot be
used with an unbounded floating point or int32 parameter.
Figure 34 - WIDGET_SPINNER hint
Notes
The range of the parameter: abs(max – min) x precision cannot exceed the maximum size of a signed integer for sliders and spinners.
To aid in touch screen environments, clicking and dragging a spinner up/down will increase/decrease its value.
WIDGET_TEXTBOX (6)
This hint specifies that a simple text entry field should be used for a number. The information entered into the text field is forced to conform to the constraints provided by the parameter. This is the default widget used for unbounded floating point parameters.
Figure 35 - WIDGET_TEXTBOX hint
WIDGET_IP_ADDRESS (14)
Displays an IPv4 Address format for a 32-bit integer. Only works with unbounded INT32 parameters.
Figure 36 - WIDGET_IP_ADDRESS hint
DashBoard CustomPanel Development Guide
WIDGET_AUDIO_METER (19)
This hint specifies that the number shall be displayed as a vertical audio meter. The number of red/yellow/green segments is fixed.
Notes
Figure 37 - WIDGET_AUDIO_METER hint
WIDGET_TIMER (21)
This hint applies only to integer parameters with RANGE_STEP_CONSTAINT constraints. The parameter is displayed as a label and counts down if minVal < 0 or up if minVal >= 0. Negative numbers are not displayed. The step size is used to specify the number of ticks-per-second to use and must be a number between 1 and 1000.
When the maximum or minimum values are reached, the timer will stop counting.
To initialize the counter to a specific value but not have it start counting:
• If the minimum value is negative and the parameter value is positive, the timer will display absolute(min) –value but will not count.
• If the minimum value is positive and the parameter value is negative, the timer will display absolute(value) but will not count.
The timer can be reset or synchronized by sending a REPORT_PARAM message with the new parameter value (typically “1”).
Examples:
• min=-600, max=0, step=1 (count from 10:00 to 0:00 showing each second).
• min=0, max=600, step=1 (count from 0:00 to 10:00 showing each second)
• min=0, max=1000,step=1000 (count from 0:00:000 to 0:01:000 showing each millisecond)
Figure 29 shows an INT_32 parameter with a WIDGET_TIMER hint, a precision of 1000, and a value
of 13794088.
Figure 38 - WIDGET_TIMER hint
WIDGET_HEX_SPINNER (28)
Displays a spinner (entry field plus up/down arrows). Display the value in Base 16.
Figure 39 - WIDGET_HEX_SPINNER hint
Due to the lack of unsigned data types in OGP, hex spinners do not function properly in the following circumstances:
- An INT16 parameter with any values in the range of 0x8000 – 0xFFFF
- An INT32 parameter with any values in the range of 0x80000000 – 0xFFFFFFFF
- To allow a spinner to function in the range from 0x0000 – 0xFFFF, it is recommended that an INT32 parameter be used.
DashBoard CustomPanel Development Guide
DashBoard Data Model • 37
WIDGET_ABSOLUTE_POSITIONER (29)
Position a value in 2-D space.
• When used as an INT16, the 8 LSBs represent the X coordinate and the 8 MSBs represent the Y coordinate.
• When used as an INT32, the 16 LSBs represent the X coordinate and the 16 MSBs represent the Y coordinate.
A crosshair in a box is dragged to the absolute position of the value in 2-D space. The ratio of width to height is the ratio of xmax-xmin to ymax-ymin with the assumption that the screen pixels are square.
Values are updated and sent to the device as the crosshair is dragged.
Figure 40 - WIDGET_ABSOLUTE_POSITIONER hint
WIDGET_CROSSHAIR (30)
Position a value in 2-D space.
• When used as an INT16, the 8 LSBs represent the X coordinate and the 8 MSBs represent the Y coordinate.
• When used as an INT32, the 16 LSBs represent the X coordinate and the 16 MSBs represent the Y coordinate.
A crosshair that snaps to the center when released makes changes in +/- X, +/- Y relative to the offset from the center. The ratio of width to height is the ratio of xmax-xmin to ymax-ymin. Values are updated and sent to the device as the crosshair is dragged.
Figure 41 - WIDGET_CROSSHAIR hint
WIDGET_JOY_STICK(34)
Position a value in 2-D space.
• When used as an INT16, the 8 LSBs represent the X coordinate and the 8 MSBs represent the Y coordinate.
• When used as an INT32, the 16 LSBs represent the X coordinate and the 16 MSBs represent the Y coordinate.
Displays a joystick and modifies the X,Y values as the joystick is dragged north, south, east, and west of the center.
DashBoard CustomPanel Development Guide
Figure 42 - WIDGET_JOY_STICK hint
WIDGET_COLOR_CHOOSER(23)
Display a color chooser as an element in the UI. Changes made to the color chooser are immediately sent to the device. Note that the color chooser provides control for Hue, Saturation, Lightness, but color values are INT32 values in ARGB format.
Figure 43 - WIDGET_COLOR_CHOOSER hint
WIDGET_COLOR_CHOOSER_POPUP(33)
Display a combo box control showing the ‘current’ color. On click, show the color chooser.
• If “Live” is togged on, update the parameter value immediately.
• If “Live” is toggled off, update the parameter value when the popup is closed.
Color values are INT32 values in ARGB format.
DashBoard CustomPanel Development Guide
Figure 44 - WIDGET_COLOR_CHOOSER hint
DashBoard Data Model • 39
7.0 Feature
WIDGET_GRAPH (256)
The graph widget provides a plot graph which tracks the value of a numeric parameter over time.
Figure 45 - WIDGET_GRAPH hint
A parameter utilizing a WIDGET_GRAPH widget may also specify additional configuration parameters in the config object of the parameter.
Properties
Property
w.time w.grid w.plotfg w.plotbg w.hidelegend w.hidex w.hidey w.autoadvance
Type
Integer
String
String
String
Boolean
Boolean
Boolean
Booelan
Default Description
Sets the timescale of the plot. If set to 0, the timescale will adapt to display entire change history.
Sets the color of the gridlines
Sets the color of the plot foreground
Sets the color of the plot background true – Legend is not shown false – Legend is shown true – X-axis scale is not shown false – X-axis scale is shown true – Y-axis scale is not shown false – Y-axis scale is shown true – graph will auto-update every 1 second false – graph will only update upon parameter change.
DashBoard CustomPanel Development Guide
Hints for String Parameters
The following widget hints may be used for String parameters (in addition to the separators and layout hints defined above). The last two hints apply only to a String parameter using the reserved objectID
0xFF01.
Widget Name
WIDGET_TEXT_ENTRY
WIDGET_PASSWORD
WIDGET_COMBO_ENTRY
WIDGET_COLORED_DOT
WIDGET_RICH_LABEL
WIDGET_MULTILINE_TEXT_ENTRY
WIDGET_NAME_OVERRIDE_APPEND
Value Description
3 Displays a normal text entry field. This is the default for editable String parameters.
4
11
12
13
14
0
WIDGET_NAME_OVERRIDE_REPLACE 1
Displays an entry field for passwords (text entered in this field is obscured).
Displays an entry field together with a dropdown list of selectable items. This is applicable only with the STRING_CHOICE constraint.
Displays a colored icon. The icon color is specified using a tag in the text string.
Displays a read-only multi-line text field with
HTML formatting.
Displays a multi-line text editor.
Special hint only for objectID 0xFF01 – causes this string to be appended to the displayed product name
Special hint only for objectID 0xFF01 – causes this string to replace the product name to be displayed
WIDGET_TEXT_ENTRY (3)
This is a text entry field used to enter String values. This is the default widget used with editable String parameters. It is very important to correctly set the length of the String with this widget as the length affects the width of the text field. In DashBoard the value is sent to the device when the user hits ‘Enter’ or changes focus to a different control on the screen.
Figure 46 - WIDGET_TEXT_ENTRY hint
WIDGET_PASSWORD (4)
This is a text entry field used to enter passwords. When the device receives a set message for a parameter using this hint, a device could send an empty string back to the device to clear the password field. Text in the password field is sent when it has changed from the value reported from the device and the user hits “Enter” or moves focus to another control.
Figure 47 - WIDGET_PASSWORD hint
DashBoard CustomPanel Development Guide
DashBoard Data Model • 41
WIDGET_COMBO_ENTRY (11)
This displays a text entry field along with a dropdown list. This option is available only for String parameters having a STRING_CHOICE constraint. The user may select an option from the dropdown list, or can type any value in the entry field. The text is sent to the device when a dropdown item is selected, when the user presses “Enter” or moves the focus after typing a value.
Figure 48 - WIDGET_COMBO_ENTRY hint, selecting from the dropdown list
WIDGET_COLORED_DOT (12)
This displays a colored icon. This should not be confused with Alarm parameters which have a similar appearance. The tag specifies the 24-bit RGB color index of the icon in hex, in the format
<#RRGGBB>. If the string does not contain a valid color tag, the icon is drawn but not filled (i.e. background shows through).
Figure 49 - WIDGET_ICON_DISPLAY hint, and value “<#3F3FFF>”
WIDGET_RICH_LABEL (13)
This displays a read-only multi-line text field, and formats the text according to the HTML formatting tags embedded in the text. Total string length including tags is limited to 250 bytes. The display uses html support within the java display object, so the exact appearance of the label may vary depending on operating system and java version.
Figure 50 - WIDGET_RICH_LABEL hint
WIDGET_MULTILINE_TEXT_ENTRY (14)
This displays a multi-line text entry field. The amount of data a user can input into the field is limited by the maximum length specified by the parameter. The size of the field is the same regardless of the maximum number of bytes the user is allowed to enter. If the parameter’s value spans more lines than the number of rows represented by the text field, a vertical scrollbar is shown to allow the user to scroll.
Text will be wrapped to avoid horizontal scrollbars.
DashBoard CustomPanel Development Guide
Figure 51 - WIDGET_MULTILINE_TEXT_ENTRY hint
WIDGET_NAME_OVERRIDE_APPEND (0)
This is a special hint ONLY FOR OID 255.1 (0xFF01). This causes the value of the String parameter with OID 255.1 to be appended to the end of the device name in DashBoard.
Figure 52 shows the result of setting parameter 255.1 to " (XPF)" with a
WIDGET_NAME_OVERRIDE_APPEND hint.
Figure 52 - WIDGET_NAME_OVERRIDE_APPEND hint
WIDGET_NAME_OVERRIDE_REPLACE (1)
This is a special hint ONLY FOR OID 255.1 (0xFF01). This causes the value of the String parameter with OID 255.1 to be displayed as the device name instead of the product name (OID 0x0105) in
DashBoard. This is the only supported method for changing a product name dynamically. Devices should never modify their base product name (OID 0x0105); DashBoard, DataSafe, and User Rights all depend on the base product name remaining fixed. Change of the product name is assumed to mean that the user has physically removed a card, and has replaced it with a different type of card.
Figure 53 shows the result of setting parameter 255.1 to "My Device Name" with a
WIDGET_NAME_OVERRIDE_REPLACE hint.
DashBoard CustomPanel Development Guide
DashBoard Data Model • 43
Figure 53 - WIDGET_NAME_OVERRIDE_REPLACE hint
Hints for STRUCT Types
Struct parameters may utilize the following widget types:
7.0 Feature
WIDGET_TABLE (36)
The table widget displays a line for each element in a STRUCT_ARRAY. Column headings are specified by the name property of each struct element. Each element of the struct is given a column in the table.
Figure 54 - WIDGET_TABLE hint
A parameter using a WIDGET_TABLE widget may also specify additional configuration parameters in the config object of the parameter.
Properties
Property
w.localselection w.scrollselection
Type
Boolean
Boolean
Default
false true
Description
true – edits in the table row do not update backing parameter; changes in the backing parameter do not update the selected row(s). false – backing parameter and table row changes track with each other. true – auto scroll to the selected row false – do not scroll to the selected row
DashBoard CustomPanel Development Guide
Property
w.reorder
Type
Boolean w.rowstyleparam String w.selectionparam String w.rowaccessparam String w.rowheight w.colwidth.n w.colminwidth.n w.hscroll w.alwaysscroll
Number
Number
Number
Boolean
Boolean w.hgrid w.vgrid
Boolean
Boolean
Default
false
none
none
none
automatic
automatic automatic
false false true true
Description
true – allow drag to reorder values false – do not allow drag to reorder values
OID of string array parameter providing style information (background, foreground, font, font size, etc.) for each row.
OID of integer parameter that will be populated with the index of a selected row.
OID of integer array parameter which determines read-only access for each row.
(0 = read-only, 1 = read-write). If not specified, all rows are read-write.
Sets the row height. Specified in pixels
Sets the width of the
n
th index is 0.
column. First column
Sets the minimum width of the
n
th
First column index is 0.
column. true – show horizontal scrollbar false – do not show horizontal scrollbar true – vertical scrollbar always shown false – vertical scrollbar only shown only when required true – display horizontal grid lines false – do not display horizontal grid lines true – display vertical grid lines false – do not display vertical grid lines
Data Types
Data Types
OGP supports a number of parameter data types the supported types summarized in the table below. For
OGP messaging, the OGP Type value is a numerical index to indicate the parameter’s data type. For
JSON messaging, the Data Type Name is used to indicate the parameter type.
Data Type Name OGP type
INT16 2
INT32
FLOAT
STRING
4
6
7
INT16_ARRAY 12
Data Size
(bytes)
2
4
4 variable
2 * len
Description
16-bit signed integer (INT16)
32-bit signed integer (INT32)
32-bit IEEE single-precision floating point number null-terminated UTF-8 string data_size = maximum permitted number of character data bytes array of 16-bit integers data_size = 2 * number of elements
(total length of the array in bytes)
DashBoard CustomPanel Development Guide
DashBoard Data Model • 45
Data Type Name OGP type
INT32_ARRAY 14
Data Size
(bytes)
4 * len
FLOAT_ARRAY
STRING_ARRAY
STRUCT
STRUCT_ARRAY
BINARY_PARAM
16
17 n/a n/a
18
4 * len variable variable variable variable
Description
array of 32-bit integers data_size = 4 * number of elements
(total length of the array in bytes) array of 32-bit floats data_size = 4 * number of elements
(total length of the array in bytes) null-terminated UTF-8 strings precision = maximum string length for any element in the array data_size = maximum number of character data bytes
User-defined data structure. (Dashboard 7.0+)
Array of User-defined data structures. (DashBoard
7.0+) array of binary data of type unknown to DashBoard.
Endianness
All numeric data encoding within OGP is in Big Endian format. Therefore, highest order bytes of multibyte numeric values are transmitted first.
Number Encoding
Signed integer data types are binary encoded 2’s complement numbers. Valid ranges for integer types are:
Response
UINT8
UINT16
INT16
INT32
Min
0
0
-32,768
-2,147,483,648
Max
255
65535
32,767
2,147,483,647
Floating point data types are encoded as 32-bit IEEE (single-precision) floating point numbers. This encoding is broken down as:
• Sign: 1 bit
• Exponent: 8 bits; Range -126 to +127
• Base: 23 bits
• Data size is the number of bytes occupied by the value.
String Encoding
All string data encoding within OGP is in UTF-8 format. Strings are preceded by a length count byte, and are followed by a null terminating byte.
DashBoard CustomPanel Development Guide
External Data Objects
To support more complex interaction with the device than is possible with parameters, DashBoard includes a set of general data objects called External Objects. Each object is identified by a 2-byte objectID (like parameters), and contains a type identifier and object-specific data. External object OIDs can overlap with parameter OIDs. The range of OIDs from 0xFE00 to 0xFFFF is reserved for future use.
External objects include an object type to indicate the type of data they encapsulate. The supported object types are:
objtype Description
1 Constraint
2
3
File
Image
4 OGLML or XML document
Constraint
Parameter constraint information can be taken outside of the parameter descriptor and moved into an external object. This is useful, for example if there is a choice constraint with a large number of options, or a common constraint is to be applied to multiple parameters. The constraint field in the parameter descriptor simply refers to an external object ID.
Any constraint type can be externalized except the external constraint type itself. An external constraint object can be shared by multiple parameters (the external object will be requested only once for all parameters which share the constraint). The object type of the external constraint must be 1, and the object data must be encoded in the same format as used for an embedded constraint.
An external object that is not object type 0x0001 will be treated as a NULL constraint (unconstrained).
Just like constraints declared in the parameter descriptor, external constraints must have the same data type as the referring parameter.
Arbitrary File
Arbitrary binary data can be sent from the device to DashBoard as a file download. These files are requested by supplying an integer parameter with a WIDGET_FILE_DOWNLOAD widget hint and a choice constraint. The numeric value of the parameter must match the OID of an external object containing the file data to download. The string value of the choice constraint is used to supply a file name for the download. To upload the file data back to the device, the data must use the standard openGear file header information defined in the section
Image
Images may be encapsulated within an External Object to be displayed in the device editor (via
OGLML) or to be used to override its icon in DashBoard. The icon may include a status indicator or
DashBoard can overlay a status indicator over the provided icon. Icons can be provided either by a URL or embedded directly in the external object.
Images must be formatted as JPEG, GIF, or PNG. Icons must be 16x16.
OGLML Descriptor or Index XML
DashBoard includes powerful feature for defining the on-screen layout of a device’s configuration page in DashBoard. These configurations are defined in an OGLML Document. These documents can be retrieved from a web server or sent to DashBoard in an external object.
DashBoard CustomPanel Development Guide
DashBoard Data Model • 47
OGLML Documents
Containers
All UI elements must be placed within a container. The container dictates how UI components are laid out within the DashBoard UI. There are several container types which provide different options on component layout. Layout containers may be nested.
By default, PanelBuilder will create a top-level abs container, and all elements (including nested containers) are placed within this top-level container.
Contexts
Contexts define scope within an OGLML document. PanelBuilder creates OGLML documents with a default context named “ opengear”. If multiple devices are linked to an OGLML document, each device has its own separate context. Therefore, elements defined within the context of one device are not visible within another device’s context.
OGLML Document Structure
The basic structure of the OGLML document is as follows:
<?
xml version="1.0" encoding="UTF-8"?>
<abs contexttype="opengear" >
<api>
Global code
</api>
<meta>
Non-UI Tags here
<api>
Global ogScript code
</api>
<params>
Parameter declarations
</params>
<menus>
Menu declarations
</menus>
<widgets>
Widget descriptors
</widgets>
</meta>
<ui container >
<ui elements/ >
<ui element>
Local scope ogScript code
</ui element>
<nested ui container>
<ui element/>
. . .
</nested ui containter>
DashBoard CustomPanel Development Guide
. . .
</ui container>
. . .
</abs>
Details about the individual tags are documented in the section OGLML Reference on page 62.
OGLML URLs
An OGLML URL can be a standard URL or an external object reference. The fragment (“#name”) of the URL can optionally provide the ID of a child element inside of the OGLML document to reference.
An external object reference URL has the form “eo://0x1234” where 0x1234 is the external object ID of the external object containing the OGLML descriptor.
OGLML URL examples:
• http://myhost/mydocument.xml
(include the entire document at the given URL)
• https://10.0.100.1/document.xml#myid
(include the element with id=”myid” from the given URL)
• eo://0xAB12
(load the OGLML descriptor from the external object with ID 0xAB12)
• eo://0xAB12#my-other-id
(load the OGLML descriptor from the external object with ID 0xAB12 and select sub-element with id=”my-other-id”)
OGLML Descriptor Format
The first byte of an OGLML Descriptor defines the type of information to follow.
No OGLML Descriptor (0x00)
This is used when there is no OGLML document referenced by this descriptor.
Field length
desctype 1 (uint8) content 0
Description
0x00
No content is provided in this case
Descriptor provided by external object (0x01)
This is used when the descriptor is contained in an external object.
Field length
desctype 1 (uint8) content 2
(uint16)
Description
0x01
The external object ID of the object containing the OGLML Descriptor
DashBoard CustomPanel Development Guide
DashBoard Data Model • 49
OGLML Document provided by URL (0x02)
The OGLML document is hosted on a web server. The descriptor provides the URL of the OGLML
Document.
Field length
desctype 1 (uint8) urllen url
1 (uint8) urllen
Description
0x02
The length of the URL to follow including the null terminator
The null-terminated URL of the external object. This must begin with
“http://” or “https://”. The content on the webserver can be uncompressed or follow web conventions for zip or deflate compression. file:// URLs may also be used but this should generally only be for development purposes and not actually on a released device.
Descriptor provides the OGLML Document in-line (0x03)
The OGLML File document immediately follows the descriptor type field.
Field length
desctype 1 (uint8) content *
Description
0x03
OGLML XML File Content
Descriptor provides a GZipped OGLML Document in-line (0x04)
The OGLML document is provided immediately following the descriptor type field (document is compressed in GZip format).
Field length
desctype 1 (uint8) content *
Description
0x04
GZipped OGLML XML File Content
Descriptor provides a Deflate OGLML Document in-line (0x05)
The OGLML document is provided immediately following the descriptor type field (document is compressed in Deflate format).
Field length
desctype 1 (uint8) content *
Description
0x05
Deflate OGLML XML File Content
DashBoard CustomPanel Development Guide
Custom Widgets
7.0 Feature
Overview
DashBoard Version 7.0 and later includes support for user-defined controls within a DashBoard editor.
These allow device designers and CustomPanel developers to reuse repeated elements within an
OGLML document. Complex UI behaviour can be coded into the widget, which is hidden from the UI developer.
Custom Widgets allow the designer to design an element consisting of multiple controls, OGLML markup tags and ogScript. This element can then be instantiated multiple times within an OGLML document. Widgets may be defined within an OGLML document or made globally available in
DashBoard.
Widgets allow configuration parameters exposed to tailor the look, feel and behaviour. These configuration parameters are also available through the PanelBuilder GUI, allowing simple customization of the widget.
Widgets are defined by creating a Widget Descriptor, which consists of a section OGLML/ogScript code that defines the controls. Additionally, a configuration block may be defined which creates a configuration page for the widget within PanelBuilder.
Creating Widgets
Widget Descriptor Structure
The widget descriptor has a structure as outlined below:
<widgetdescriptor id ="widget-id" >
<config>
<params>
Configuration parameters here
</params>
<oglml>
Optional OGLML markup for configuration editor
</oglml>
</config>
<oglml>
<meta>
<params>
Private parameter declarations
</params>
<api>
Private ogScript functions
</api>
<meta>
<layout-container>
UI elements
</layout-container>
</oglml>
</widgetdescriptor>
DashBoard CustomPanel Development Guide
DashBoard Data Model • 51
OGLML Block
The OGLML section (encapsulated within an <oglml> tag) contains the OGLML document to create the widget. It may contain
<meta>, <ogscript>, <api> and layout container tags in the same manner as a standard OGLML document. Note that all declarations within the <oglml> section are private to the widget.
Config Block
The config section (encapsulated within a <config> tag) contains OGLML document that creates a configuration page for the widget. The configuration page is displayed within the Edit Component dialog in PanelBuilder. By default, the default openGear layout will be used to present any parameters declared within a <params> tag in the config block:
<widgetdescriptor id ="alarmgrid" >
<config>
<params>
<param access ="1" name ="String 1" oid ="str1" type ="STRING" value ="First" />
<param access ="1" name ="String 2" oid ="str2" type ="STRING" value ="Second" />
<param access ="1" name ="String 3" oid ="str3" type ="STRING" value ="Third" />
<param access ="1" name ="String 4" oid ="str4" type ="STRING" value ="Fourth" />
<param access ="1" name ="String 5" oid ="str5" type ="STRING" value ="Fifth" />
<param access ="1" name ="String 6" oid ="str6" type ="STRING" value ="Sixth" />
</params>
</config>
<oglml>
<simplegrid cols ="3" rows ="2" >
<param height ="40" oid ="str1" widget ="12" width ="200" />
<param height ="40" oid ="str2" widget ="12" width ="200" />
<param height ="40" oid ="str3" widget ="12" width ="200" />
<param height ="40" oid ="str4" widget ="12" width ="200" />
<param height ="40" oid ="str5" widget ="12" width ="200" />
<param height ="40" oid ="str6" widget ="12" width ="200" />
</simplegrid>
</oglml>
</widgetdescriptor>
DashBoard CustomPanel Development Guide
Figure 55 – Widget Configuration (Default Layout)
However, OGLML markup may be added by specifying it within an <oglml> block within the config block.
Note
If an <oglml> block is specified within the <config> section, only parameters included in the <oglml> block will be displayed in the PanelBuilder “Edit Component” dialog.
The following is an example of a widget descriptor incorporating an OGLML configuration markup. In the example, a
<simplegrid> container is used to arrange configuration parameters into a 3x2 grid.
<widgetdescriptor id ="alarmgrid-oglml" >
<config>
<params>
<param access ="1" name ="String 1" oid ="str1" type ="STRING" value ="First" />
<param access ="1" name ="String 2" oid ="str2" type ="STRING" value ="Second" />
<param access ="1" name ="String 3" oid ="str3" type ="STRING" value ="Third" />
<param access ="1" name ="String 4" oid ="str4" type ="STRING" value ="Fourth" />
<param access ="1" name ="String 5" oid ="str5" type ="STRING" value ="Fifth" />
<param access ="1" name ="String 6" oid ="str6" type ="STRING" value ="Sixth" />
</params>
<oglml>
<simplegrid cols ="3" rows ="2" >
<param height ="40" oid ="str1" widget ="12" width ="200" />
<param height ="40" oid ="str2" widget ="12" width ="200" />
<param height ="40" oid ="str3" widget ="12" width ="200" />
<param height ="40" oid ="str4" widget ="12" width ="200" />
<param height ="40" oid ="str5" widget ="12" width ="200" />
<param height ="40" oid ="str6" widget ="12" width ="200" />
</simplegrid>
</oglml>
</widgetdescriptor>
DashBoard CustomPanel Development Guide
DashBoard Data Model • 53
Figure 56 – Widget Configuration (OGLML layout)
If the widget descriptor includes a structtype attribute, PanelBuilder will use this as a filter to only offer the widget for insertion if a struct parameter exists with matching structtype attribute.
Widget Samples
Numeric Keypad
This example creates a reusable control which presents a numeric keypad. The keypad accepts parameters to map it to a specific OID to update, as well as name and a default value.
Figure 57 - Keypad Custom Widget
The widget also defines a custom configuration panel, which is presented within PanelBuilder’s “Edit
Component” dialog.
Figure 58 - Keypad Config Dialog
The widget descriptor to generate this widget is shown below. Comments have been added before various sections of the code to identify their functionality.
DashBoard CustomPanel Development Guide
The config block defines four parameters:
• Ext.Punch.Name – OID whose value the punchpad will manipulate
• Ext.Punch.DisplayName – Name to display in the title bar of the widget
• Ext.Punch.Default – Value to set if the DFLT button is pressed
•
Ext.Punch.DefaultEnabled – Enables/Disables the DFLT button
There is an oglml block within the config section to specify the layout of the configuration parameters in the Edit Component dialog.
This widget implements an ogScript function, addDigit(), to update the param value as the user types in the keypad.
The oglml section lays out the keypad using a table container, and hooks the addDigit() function to the buttonpress handler for each digit button.
<?
xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<widgets>
<widgetdescriptor id="com.rossvideo.widget.punchpad v3" icon="com.rossvideo.punchpad.png" inheritsrc="true" name="Punchpad v3" >
<!--Configuration setion starts here-->
<config>
<!-- Variables that appear in the edit mode for the grid file and that are part of the declaration for the widget -->
<!—Config parameter declarations start here-->
<params>
<param access="1" maxlength="0" name="OID To use" oid="Ext.Punch.Name" type="STRING" value="OID not specified" widget="0" />
<param access="1" maxlength="0" name="OID To use" oid="Ext.Punch.DisplayName" type="STRING" value="name not specified" widget="0" />
<param access="1" constrainttype="INT_NULL" name="Ext.Punch.Default" oid="Ext.Punch.Default" precision="0" strvalue="0" type="INT16" value="0" widget="0" />
<param access="1" constrainttype="INT_CHOICE" name="Default Enabled" oid="Ext.Punch.DefaultEnabled" precision="0" strvalue="On" type="INT16" value="1" widget="8" >
<constraint key="0" >
Off
</constraint>
<constraint key="1" >
On
</constraint>
</param>
</params>
<!-- Definition for the UI that appears in edit mode -->
<!—Config parameter layout starts here-->
<oglml>
<abs height="500" left="0" top="272" width="334" >
DashBoard CustomPanel Development Guide
DashBoard Data Model • 55
<table height="150" left="0" top="0" width="800" >
<tr>
<label anchor="east" fill="none" insets="0,0,0,5" name="OID To Use" weightx="0.0" />
<param anchor="west" element="0" fill="both" oid="Ext.Punch.Name" showlabel="false" weightx="1.0" weighty="1.0" />
</tr>
<tr>
<label anchor="east" fill="none" insets="0,0,0,5" name="Title" weightx="0.0" />
<param anchor="west" element="0" fill="both" oid="Ext.Punch.DisplayName" showlabel="false" weightx="1.0" weighty="1.0" />
</tr>
<tr>
<label anchor="east" fill="none" insets="0,0,0,5" name="Default Value" weightx="0.0" />
<param anchor="west" element="0" fill="both" oid="Ext.Punch.Default" showlabel="false" weightx="1.0"
</tr> weighty="1.0" />
<tr>
<label anchor="east" fill="none" insets="0,0,0,5" name="Default Value Enabled" weightx="0.0" />
<param anchor="west" element="0" fill="both" oid="Ext.Punch.DefaultEnabled" showlabel="false" weightx="1.0" weighty="1.0" />
</tr>
</table>
</abs>
</oglml>
</config>
<!-- Definition for the widget UI itself -->
<oglml>
<!-- Temporary internal variables to the widget -->
<!—Local parameter declarations start here-->
<params>
<param access="1" maxlength="0" name="Punch.Temp.Number" oid="Punch.Temp.Number" type="STRING" value="" widget="0" />
</params>
DashBoard CustomPanel Development Guide
<!-- Global functions for the widget to use -->
<api id="addDigit" name="addDigit" >
function addDigit(digit)
{
var value=params.getValue('Punch.Temp.Number',0);
var i;
if (digit=='-')
{
if (value[0] != '-')
value = '-' + value;
else
value = value.substring(1);
}
else if (digit == '.')
{
// is there a '.' already?
for (i=0;i<value.length;i++)
{
if (value[i]=='.')
return;
}
value +='.';
}
else if (value[0] != '0')
value += digit;
else // first digit is a 0
value = digit;
params.setValue('Punch.Temp.Number',0,value);
}
</api>
<style id="TextStyle" name="TextStyle" value="size:20;font:bold;bg#000000;fg#FFFFFF;" />
<abs height="317" left="641" style="bdr:etched;" top="355" virtualheight="317" virtualwidth="371" width="371" >
<abs left="147" top="174" />
<!—Title bar begins here-->
<label height="23" id="Var.Name" left="25" name="%value['Ext.Punch.DisplayName'][0]%" style="size:16;font:bold;txt-align:west;" top="14" width="105" />
<param expand="true" height="32" oid="Punch.Temp.Number" right="20" showlabel="false" top="10" width="200" />
<!—Table starts here-->
<table bottom="10" left="20" right="20" top="49" >
DashBoard CustomPanel Development Guide
DashBoard Data Model • 57
<!—Table row showing buttons 7, 8, 9, DFLT-->
<tr>
<button buttontype="push" colspan="1" fill="both" height="43" name="7" rowspan="1" style="style:TextStyle;" weightx="1.0" weighty="1.0" width="58" >
<task tasktype="ogscript" >
addDigit('7');
</task>
</button>
<button buttontype="push" colspan="1" fill="both" height="43" name="8" rowspan="1" style="style:TextStyle;" weightx="1.0" weighty="1.0" width="58" >
<task tasktype="ogscript" >
addDigit('8');
</task>
</button>
<button buttontype="push" colspan="1" fill="both" height="43" name="9" rowspan="1" style="style:TextStyle;" weightx="1.0" weighty="1.0" width="58" >
<task tasktype="ogscript" >
addDigit('9');
</task>
</button>
<button buttontype="push" colspan="1" fill="both" height="43" name="DFLT" rowspan="1" style="style:TextStyle;" weightx="1.0" weighty="1.0" width="58" >
<task tasktype="ogscript" >
var enabled = params.getValue('Ext.Punch.DefaultEnabled'
,0);
var value = params.getValue('Ext.Punch.Default',0);
if (enabled == 0)
return;
params.setValue('Punch.Temp.Number', 0, value.toString());
</task>
</button>
</tr>
<!—Table row showing buttons 4, 5, 6, CLR-->
<tr>
<button buttontype="push" colspan="1" fill="both" height="43" name="4" rowspan="1" style="style:TextStyle;" weightx="1.0" weighty="1.0" width="58" >
<task tasktype="ogscript" >
addDigit('4');
</task>
</button>
<button buttontype="push" colspan="1" fill="both" height="43" name="5" rowspan="1" style="style:TextStyle;"
DashBoard CustomPanel Development Guide
weightx="1.0" weighty="1.0" width="58" >
<task tasktype="ogscript" >
addDigit('5');
</task>
</button>
<button buttontype="push" colspan="1" fill="both" height="43" name="6" rowspan="1" style="style:TextStyle;" weightx="1.0" weighty="1.0" width="58" >
<task tasktype="ogscript" >
addDigit('6');
</task>
</button>
<button buttontype="push" colspan="1" fill="both" height="43" name="CLR" rowspan="1" style="style:TextStyle;" weightx="1.0" weighty="1.0" width="58" >
<task asktype="ogscript" >
params.setValue('Punch.Temp.Number', 0, '0');
</task>
</button>
</tr>
<!—Table row showing buttons 1, 2, 3, Enter-->
<tr>
<button buttontype="push" colspan="1" fill="both" height="43" name="1" rowspan="1" style="style:TextStyle;" weightx="1.0" weighty="1.0" width="58" >
<task tasktype="ogscript" >
addDigit('1');
</task>
</button>
<button buttontype="push" colspan="1" fill="both" height="43" name="2" rowspan="1" style="style:TextStyle;" weightx="1.0" weighty="1.0" width="58" >
<task tasktype="ogscript" >
addDigit('2');
</task>
</button>
<button buttontype="push" colspan="1" fill="both" height="43" name="3" rowspan="1" style="style:TextStyle;" weightx="1.0" weighty="1.0" width="58" >
<task tasktype="ogscript" >
addDigit('3');;
</task>
</button>
<button buttontype="push" colspan="1" fill="both" height="43" name="ENTR" rowspan="2" style="style:TextStyle;" weightx="1.0" weighty="1.0" width="58" >
<task tasktype="ogscript" >
params.setValue('%value['Ext.Punch.Name'][0]%
',0, params.getValue('Punch.Temp.Numbe
r',0));
params.setValue('Punch.Temp.Number', 0, '0');
DashBoard CustomPanel Development Guide
DashBoard Data Model • 59
</task>
</button>
</tr>
<!—Table row showing buttons +/- 0-->
<tr>
<button buttontype="push" colspan="1" fill="both" height="43" name="+/-" rowspan="1" style="style:TextStyle;" weightx="1.0" weighty="1.0" width="58" >
<task tasktype="ogscript" >
addDigit('-');
</task>
</button>
<button buttontype="push" colspan="1" fill="both" height="43" name="0" rowspan="1" style="style:TextStyle;" weightx="1.0" weighty="1.0" width="58" >
<task tasktype="ogscript" >
addDigit('0');;
</task>
</button>
<button buttontype="push" colspan="1" fill="both" height="43" name="." rowspan="1" style="style:TextStyle;" weightx="1.0" weighty="1.0" width="58" >
<task tasktype="ogscript" >
addDigit('.');
</task>
</button>
</tr>
</table>
</abs>
</oglml>
</widgetdescriptor>
</widgets>
Descriptor Location
Descriptors may be defined within an OGLML document, stored in an external file, or retrieved directly from a device.
Inline Widget Descriptors
Descriptors are defined within the
<meta> block of an OGLML document. Descriptors may not be nested within other widget descriptors. All widget descriptors must be placed within a <widgets> block within the
<meta> block.
External Widget Descriptor Files
The widget descriptor may be stored in an external file. External widget descriptor files have the extension .widgetdescriptor.
DashBoard searches for widget descriptors in the following locations:
• Within a widgets subfolder within the folder containing the OGLML document.
• Within the widgets folder inside the DashBoard installation directory.
• A file specified by use of the baseurl attribute of a widgetdescriptor tag.
DashBoard CustomPanel Development Guide
Device-served Widget Descriptors
A device may specify a URL to retrieve widgets using reserved OID 0xFF14. This mechanism will retrieve a single file from the specified URL. This is the recommended approach for openGear device developers.
Parameter Mapping
Parameters declared within the config block are visible to the configuration editor and the widget itself.
External ogScript functions may access these parameters via the getConfigParams function of the widget object.
Parameters declared within the oglml block are private to the widget, and not visible to the config block.
Global parameters are visible within the widget when referenced explicitly.
Widgets also support relative parameters. When a relative parameter is referenced, its name is concatenated to the string specified in the baseOID attribute of the widget instance.
Parameters within a widget are interpreted as relative if one of the following conditions is met:
• the OID begins with a "."
• the parameter has the attribute relative set to true.
• the parameter reference explicitly specifies the baseOID by explicitly prefixing %baseoid% to the
OID of the parameter.
A parameter may force reference to a local parameter by prepending %widget% to the OID of the referenced parameter.
Example
The widgetdescriptor keyer references the parameters .clip and .gain. Global parameters are created called keyer1.clip, keyer1.gain, keyer2.clip and keyer2.gain. The widgets then may be instantiated as:
<widget id ="key1" widgetid ="keyer" baseoid ="keyer1" />
<widget id ="key2" widgetid ="keyer" baseoid ="keyer2" />
The key1 widget’s parameters
.clip and .gain are concatenated with the baseoid keyer1 thus mapping them to the global parameters keyer1.clip, and keyer1.gain. In a similar manner, key2 widget’s parameters map to the global parameters keyer2.clip, and keyer2.gain.
The baseoid attribute may be queried and modified dynamically through the ogScript getBaseOID and setBaseOID member functions of the widget object.
DashBoard CustomPanel Development Guide
DashBoard Data Model • 61
OGLML Reference
In This Chapter
This chapter describes the OGLML tags.
The following topics are discussed:
•
•
•
Layout/Container Tags (page 72)
•
•
•
Device Resource Declarations (page 113)
•
Device Resource Tags (page 125)
•
General Attributes
An OGLML document consists of a series of (nested) tags, described in detail in the following sections. Each tag can take optional attributes. The following chart lists attributes that can be used with all tags.
Note that there are also tag-specific attributes; these are discussed in the Tags section.
Syntax
<component attribute="value" attribute="value" ... >
General Attributes
Attribute
containertype scroll
Values
bottom inset etched raised lowered tabpage
Restrictions
Should not be used with
“browser” tag.
Description
Adjust the border and shading of the component. See the Examples below.
Indicates that the component created by the tag should be enclosed in a scrollable container. If the display is too small to display the component,
DashBoard CustomPanel Development Guide
Attribute
contexttype objectid objecttype id width height style
Values
true false horizontal vertical always
Restrictions
Nesting within another “scrolls” element is not recommended
Scrolling for the
“menu” tag will always be true.
Description
horizontal or vertical scrollbars are added.
Provides both horizontal and vertical scrollbars
Provides no scrollbars
Provides only horizontal scrolling
Provides only vertical scrolling
Forces horizontal and vertical scrollbars to always be visible. opengear
…
node-id of the source of parameters within container. The
objectid is passed onto child elements and containers.
Type of device when communicating wit han openGear of DashBoard connect device.
Used to uniquely identify/reference an element in the OGLML file.
String
Must be unique within all OGLML files displayed by a device.
IDs must only use A-Z, a-z, 0-9,
“-“, and “_” characters.
Positive integer Required for browser tags
Positive integer Required for
style hints
browser tags
If a parameter already provides style hints as part of its constraint, style hints should not be overridden with this style tag
– results are unpredictable.
Specifies the preferred with (in pixels) for a component. May be ignored by
DashBoard depending on the component.
Specifies the preferred height (in pixels) for a component. May be ignored by
DashBoard depending on the component. openGear Style Hints are used to specify the background color, foreground color, icon, and border for certain
components. Refer to Style Hints .
DashBoard CustomPanel Development Guide
OGLML Reference • 63
Examples
The following image illustrates the available containertype values:
Figure 59 – containertype examples
Style Hints
openGear Style Hints
openGear Style Hints provide something similar to an inline style CSS attribute in HTML. For certain components, they can be used to specify a background color, foreground color, border, and icon. The hints can be provided inside OGLML tags or via parameter choice constraint values.
Note
Syntax
To specify a style hint inside an OGLML tag, the style attribute is used:
<component style="style-hint;style-hint;...;" component attributes>
To specify a style hint within a parameter choice constraint, the style tag is inserted at the end of the constraint value, enclosed in angle brackets (< >). In order to represent the angle brackets in the OGLML document, they must use standard XML escape sequences ( < >).
Specifying hints within the constraint value allows different styles to be applied to each choice.
<constraint key="key">value<style-tag;style-tag;...
></constraint>
Style hints may be specified in
either the OGLML style attribute or within the constraint value, but not both.
For clarity, this document will provide examples using the OGLML style attribute only, however the style hints may be utilized within constraints unless specifically mentioned.
Style Hint Reference
The following style hints are supported:
Tag
bdr#color-value bg#color-value
Description
Sets the component background color.
Sets the component border style.
Sets the component border color.
Sets the component background color.
Sets the alignment of a background image.
DashBoard CustomPanel Development Guide
Tag
di:none di-eo:external-oid di-u:image-URL
hi:none hi-eo:external-oid hi-u: image-URL i:none i-eo:external-oid i-u: image-URL
Description
Controls how a background image is sized.
Sets a container background to image located at a specified URL.
Removes a component drag icon.
Sets a component drag icon to image encapsulated in an external OID.
Sets a component drag icon to image located at a specified URL.
Style modifier when button value is false.
Sets the component foreground color.
Sets the font type.
Sets the table gridline color.
Removes a component hover icon.
Sets a component hover icon to image encapsulated in an external OID.
Sets a component hover icon to image located at a specified URL.
Removes a component icon.
Sets a component icon to image encapsulated in an external OID.
Sets a component icon to image located at a specified URL.
Sets insets around the label of a button.
Sets the text outline color.
Sets the text font size.
Applies style hints defined within a
style tag.
Style modifier when button value is true.
Sets a tooltip for a label or button.
Sets the alignment of text.
style Style Hint
User styles may be created within an OGLML document to allow standardized formatting to be
applied to multiple components. Styles are defined using the style
be referenced by a component as part of its style attribute. Additional style hints may be included in the same style attribute string. If the style string explicitly specifies a hint which contradicts a hint in the predfined style, the explicitly added hint shall supersede.
Style Hint
style:style-id
Values
String
Restrictions
The style with the provided ID must be defined in an
OGLML document at a higher scope than where it is referenced.
Description
Apply the style hints of the style defined
in a different set of style hints. See style tag documentation for more information.
DashBoard CustomPanel Development Guide
OGLML Reference • 65
Examples
The following example applies button style hints as defined in the predefined style
CommandButtonStyle. Note that the “Stop” button has an additional hint applied
( size:big), and overrides the background color (bg#ff0000).
<style id ="ButtonStyle" value ="bg#808000;bdr:etched;" />
<button name ="Start" style ="style:ButtonStyle;" />
<button name ="Stop" style ="style:ButtonStyle;size:big;bg#ff0000;" />
<button name ="Reset" style ="style:ButtonStyle;" />
Figure 60 - Style Tag Example
Component Color
The foreground, background and border colors of components may be specified. It is often a good idea to override the background and foreground as a pair to avoid the possibility of the background and foreground being the same (or similar) colors in the UI.
Style Hint
#color-value or bg#color-value fg#color-value bdr#color-value o#color-value grid#color-value
Values
#RRGGBB or
#color-constant or
#RRGGBBAA
Restrictions
#RRGGBB or
#color-constant or
#RRGGBBAA
#RRGGBB or
#color-constant or
#RRGGBBAA
#RRGGBB or
#color-constant or
#RRGGBBAA
#RRGGBB or
#color-constant or
#RRGGBBAA
Applies to table container only.
Description
Set the background color of the component.
Colors may be specified as RGB, RGBA
or one of the pre-defined color constants . R, G, B and A are specified
as 2-digit hex values.
Set the foreground color of the component.
Colors may be specified as RGB, RGBA
or one of the pre-defined color constants . R, G, B and A are specified
as 2-digit hex values.
Create a line border around the component with the specified color.
Colors may be specified as RGB, RGBA
or one of the pre-defined color constants . R, G, B and A are specified
as 2-digit hex values.
Create an outline around the text within a component with the specified color.
Colors may be specified as RGB, RGBA
or one of the pre-defined color constants . R, G, B and A are specified
as 2-digit hex values.
Specifies the color of the gridlines for a
Colors may be specified as RGB, RGBA
or one of the pre-defined color constants . R, G, B and A are specified
as 2-digit hex values.
DashBoard CustomPanel Development Guide
Example
The following style tag creates a label using the predefined background #panelbg and the foreground (text) in orange.
<label name ="Label" style ="bg#panelbg;fg#FFC000;" />
Predefined Colors
DashBoard defines the following color constants, which make up the standard color scheme.
These colors are used in the standard controls within DashBoard, but may be applied to the background, foreground or border color style tag of any component. Custom color constants may be defined within an OGLML document using the color tag.
Color Constant
#control
#dark
#foreground
#listbg
#listfg
#panelfg
#panelbg
#readonlybg
#readonlyfg
#selectbg
#selectfg
#tabbg
#tabfg
#textbg
#textfg
#transparent
#user-defined-color
Description
The background color of a basic control or panel.
The dark panel background color used in the default DashBoard display.
The foreground color of a basic control or button.
The default background color of a combo box control.
The default foreground color of a combo box control.
The proper foreground color to use on a panel.
The standard panel background color used in the default DashBoard display.
The default background color of a read-only text box.
The default foreground color of a read-only text box.
The default background color for a selected toggle button.
The default foreground color for a selected toggle button.
The default background color of a selected tab.
The default foreground color of a selected tab.
The default background color of a read/write text box.
The default foreground color of a read/write text box.
No fill; the element will be transparent.
User defined color. Defined using the color tag.
Examples
The following image illustrates the pre-defined color constants, as rendered in DashBoard 7.
DashBoard CustomPanel Development Guide
Figure 61 - Predefined color constants
OGLML Reference • 67
Border Styles
The style of a component border may be specified with the bdr hint. If the border hint is not specified, a simple line will be drawn for the control border.
Note:
The containertype attribute , if specified for a component, will override the bdr
style hint.
Style Hint
bdr:border-style bdr#color-value grid#color-value
Values
none etched shadow
Restrictions Description
Removes the border from the component.
Create an etched border around the component.
Creates a drop shadow under the component.
Sets border color; see Component Color Section .
Sets grid color in a table; see Component Color Section .
Examples
The following image illustrates the border style hint:
Figure 62 - Border style
Text/Font Styles
The following style hints modify the rendering of text in a component.
Style Hint
size:font-size font:font-type
Values
Integer size smaller small
normal
big bigger biggest
default
bold mono
Restrictions Description
Set the font size for the component.
Number specifies a font size in points
(1/72”).
smaller corresponds to 2/3 normal size.
biggest corresponds to 4x normal size.
See examples below.
Set the control font to the default font, a bold font, or a mono-spaced font.
DashBoard CustomPanel Development Guide
Style Hint Values
txt-align:alignment center north northeast east southeast south southwest west northwest fg#color-value
Restrictions Description
Controls the position of text within a button or label control.
Sets text foreground color; see Component Color Section .
o#color-value
Sets text outline color; see Component Color Section .
Examples
The following image illustrates the size style
Figure 63 - size style attribute
The following image illustrates the font style:
Figure 64 - font style attribute
Note
Icon Styles
Icon styles may be applied to label and button components. DashBoard allows separate icons to be defined for the default icon, the icon when a mouse hovers over the control, and the icon when the control is dragged (if dragging is enabled on the component).
Icon Styles have no effect on buttons with the flat attribute.
Style Hint
i-eo:external-oid i-u: image-URL i:none di-eo:external-oid di-u:image-URL di:none
Values Restrictions
External OID External OID specified must be type 0x03.
Description
Set the icon for the component (applies to labels and buttons).
URL String
Full qualified URL to PNG, GIF or
JPG image.
External OID External OID specified must be type 0x03.
URL String
Full qualified URL to PNG, GIF or
JPG image.
Set the icon for the component. (applies to labels and buttons)
Remove the icon for the component.
Set the drag icon for the component
(only applies if “dragvalue” attribute is used).
Set the drag icon for the component
(only applies if “dragvalue” attribute is used)
Remove the drag icon for the component.
DashBoard CustomPanel Development Guide
OGLML Reference • 69
Style Hint
hi-eo:external-oid hi-u: image-URL hi:none
Values Restrictions
External OID External OID specified must be type 0x03.
Description
Set the hover icon for the component
(applies to buttons)
URL String Full qualified URL to PNG, GIF or
JPG image.
Set the hover icon for the component
(applies to buttons)
Remove the hover icon for the component.
Example
<button buttontype ="push" style ="i-u:http://myserver/RossLogo.jpg;hi-u:http://my-server/DashBoardLogo.jpg;" />
Figure 65 – Background and Hover Icon
Tooltip Style
Tooltip may be added to components. Balloon help text will be displayed when the mouse hovers over the component.
Style Hint
tt:tool-tip-string
Values
String
Restrictions
May only be applied to label and buttons.
Description
Set the tooltip of the component to the specified String. A “ ;” can be inserted into the string by inserting the escape sequence “ \;”.
Example
<button name ="Tooltip" style ="tt:This is the tooltip text" />
Figure 66 – Tooltip Style
Inset Style
Insets provide a margin from the edge of a component to the text or icon content.
Style Hint
m:top,left,bottom,
right
Values
4 Integers
Restrictions
This hint can only be applied to button widgets.
Description
Sets the margins around the label of the button. The margins are specified in pixels.
DashBoard CustomPanel Development Guide
Background Styles
Background styles allow images to be placed in the background of container components.
Style Hint
b-u:image-url bg-fill:value bg-align:value
Values
URL String
none
both
horizontal vertical fit crop tile paint9
center north northeast east southeast south southwest west northwest
Restrictions
Must be a fully qualified URL.
Description
Set the background image of the component.
Do not scale the image.
Stretch the image to the width/height of the control.
Scale the image to the width of the control (maintain aspect ratio).
Scale the image to the height of the control (maintain aspect ratio).
Scale the image to the largest size that will fit inside of the control (maintain aspect ratio).
Scale the image to fill the control maintaining the aspect ratio. Crop the image to remove the parts that don’t fit.
Tile the image (starting at the upper left) to fill the background of the control.
Divide the image into 9 areas (defined with Background Insets) to define fixed corners, vertically or horizontally stretched sides, and a stretched center.
If the fill is set to anything other than
“both” or “tile”, this controls where the background is positioned in the component.
Button Style Modifiers
All style options can be overridden for toggle and radio buttons, such that the style of the widget is determined by the value of the backing parameter. For toggle buttons, the style can be specified for the true state (button toggled down) and false state (button toggled up). For radio buttons, the style can be specified for each choice for the true state (choice selected) and false state (choice not selected).
DashBoard CustomPanel Development Guide
OGLML Reference • 71
Syntax
<component style ="t:true-style-hint;f:false-style-hint;...;" >
Hint Modifier
t:true-style-hint f:false-style-hint
Values Restrictions
Valid style hint
Valid style hint
Description
Applies the style hint only when the choice is true.
Applies the style hint only when the choice is false.
Examples
The following example creates a toggle button whose color is green when true (toggled down) and red when false (toggled up):
<param oid ="0x7" style ="t:bg#00ff00;f:bg#ff0000;" widget ="13" />
Figure 67 - Toggle Button Style Modifier
The following example changes the font size to big for the selected radio button:
<param oid ="0x6" style ="t:size:big;f:size:normal;" widget ="9" />
Figure 68 – Radio Button Style Modifier
Layout/Container Tags
Container tags define regions of the layout which contain other elements. Containers control how the child elements are presented within DashBoard. Container tags accept attributes which impact the container as a whole, and may also specify additional attributes which may be applied to child elements; these define how the elements are displayed within the container. Containers may be nested.
The following containers are supported:
Tag
Description
Allows elements to be placed in absolute positions
Aligns elements in a horizontal row
Presents child elements in a popup window
Creates a grid of fixed-size rows and columns
Creates a draggable split screen with 2 components.
Creates a tabbed page
Creates a grid of rows and columns
DashBoard CustomPanel Development Guide
abs
Use absolute positioning and sizing for components inside of the abs tag. The sizing and positioning of child components must be specified as attributes of those child components.
Syntax
<abs container attributes >
<component
child component attributes
> </component>
<component
child component attributes
> </component>
. . .
</abs>
Container Attributes
In addition to General Attributes , the following attributes may be specified to the <
abs> tag:
Attribute
virtualwidth virtualheight
Values
Integer
Integer
Restrictions Description
Defines a virtual width and height to use for all coordinates inside of the container. All offsets and dimensions inside of the container are scaled based on current width/height vs. virtualwidth/virtualheight.
When these attributes are used, the UI will scale as the container size changes.
Child Component Attributes
In addition to General Attributes , the following attributes may be specified to child components:
Attribute
left right top bottom width height
Values
Integer
Integer
Integer
Integer
Integer
Integer
Restrictions
Ignored if both
left and right are specified.
Ignored if both
top and bottom are specified.
Description
Defines the distance between the left edge of the abs and the component.
When combined with right it will force the component to fill the available area.
Defines the distance between the right edge of the abs and the control.
When combined with left, it will force the component to fill the available area.
Defines the distance between the top edge of the
abs and the control.
When combined with bottom, it will force the component to fill the available area.
Defines the distance between the bottom edge of the abs and the control.
When combined with
top, it will force the component to fill the available area.
Defines the width of the control. If undefined, the control’s calculated preferred size will be used.
Defines the height of the control. If undefined, the control’s calculated preferred size will be used.
DashBoard CustomPanel Development Guide
OGLML Reference • 73
virtualwidth and virtualheight
If the virtualheight and virtualwidth attributes are not set, components within the abs container will be displayed in their specified size. Resizing the abs container will not scale the child components. If the abs area does not encompass the area required for the specified components, the components will be cropped.
If virtualheight and virtualwidth attributes are set, component size and position within the abs container are scaled according to: 𝑐𝑐𝑐𝑐𝑚𝑚𝑑𝑑𝑐𝑐𝑚𝑚𝑑𝑑𝑚𝑚𝑐𝑐 𝑑𝑑𝑑𝑑𝑑𝑑𝑑𝑑𝑑𝑑𝑑𝑑𝑑𝑑 𝑤𝑤𝑑𝑑𝑑𝑑𝑐𝑐ℎ = 𝑐𝑐𝑐𝑐𝑚𝑚𝑑𝑑𝑐𝑐𝑚𝑚𝑑𝑑𝑚𝑚𝑐𝑐 𝑤𝑤𝑑𝑑𝑑𝑑𝑐𝑐ℎ × � 𝑑𝑑𝑎𝑎𝑑𝑑 𝑤𝑤𝑑𝑑𝑑𝑑𝑐𝑐ℎ 𝑑𝑑𝑎𝑎𝑑𝑑 𝑣𝑣𝑑𝑑𝑣𝑣𝑐𝑐𝑣𝑣𝑑𝑑𝑑𝑑𝑤𝑤𝑑𝑑𝑑𝑑𝑐𝑐ℎ
� 𝑐𝑐𝑐𝑐𝑚𝑚𝑑𝑑𝑐𝑐𝑚𝑚𝑑𝑑𝑚𝑚𝑐𝑐 𝑑𝑑𝑑𝑑𝑑𝑑𝑑𝑑𝑑𝑑𝑑𝑑𝑑𝑑 ℎ𝑑𝑑𝑑𝑑𝑒𝑒ℎ𝑐𝑐 = 𝑐𝑐𝑐𝑐𝑚𝑚𝑑𝑑𝑐𝑐𝑚𝑚𝑑𝑑𝑚𝑚𝑐𝑐 ℎ𝑑𝑑𝑑𝑑𝑒𝑒ℎ𝑐𝑐 × � 𝑑𝑑𝑎𝑎𝑑𝑑 ℎ𝑑𝑑𝑑𝑑𝑒𝑒ℎ𝑐𝑐 𝑑𝑑𝑎𝑎𝑑𝑑 𝑣𝑣𝑑𝑑𝑣𝑣𝑐𝑐𝑣𝑣𝑑𝑑𝑑𝑑ℎ𝑑𝑑𝑑𝑑𝑒𝑒ℎ𝑐𝑐
�
Examples
The following example creates an abs container with 4 buttons placed in a 2x2 grid. The buttons will not scale if the abs is resized (they will be cropped):
<abs left ="16" top ="16" width ="250" height ="250" >
<button left ="5" top ="5" width ="100" height ="100" name ="1" />
<button left ="110" top ="5" width ="100" height ="100" name ="2" />
<button left ="5" top ="110" width ="100" height ="100" name ="3" />
<button left ="110" top ="110" width ="100" height ="100" name ="4" />
</abs>
The following example creates an abs container with 4 buttons placed in a 2x2 grid. The buttons will scale if the abs is resized:
<abs left ="16" top ="16" width ="250" height ="250" virtualwidth ="250" virtualheight ="250" >
<button left ="5" top ="5" width ="100" height ="100" name ="1" />
<button left ="110" top ="5" width ="100" height ="100" name ="2" />
<button left ="5" top ="110" width ="100" height ="100" name ="3" />
<button left ="110" top ="110" width ="100" height ="100" name ="4" />
</abs>
In the following example, the 2x2 grid will be scaled to half its original size. All buttons will appear 50x50 pixels in size:
<abs left ="16" top ="16" width ="125" height ="125" virtualwidth ="250" virtualheight ="250" >
<button left ="5" top ="5" width ="100" height ="100" name ="1" />
<button left ="110" top ="5" width ="100" height ="100" name ="2" />
<button left ="5" top ="110" width ="100" height ="100" name ="3" />
<button left ="110" top ="110" width ="100" height ="100" name ="4" />
</abs>
DashBoard CustomPanel Development Guide
flow
Arrange controls horizontally across the page. Wrap the controls vertically if there is not enough space to show all controls on a single row.
Syntax
<flow container attributes >
<component component attributes > </component>
<component component attributes > </component>
<component component attributes > </component>
. . .
</flow>
Container Attributes
In addition to General Attributes , the following attributes may be specified:
Attribute
anchor
Values
center east west
Restrictions Description
Defines the alignment of the controls
Default values shown in bold.
Child Component Attributes
See General Attributes . There are no additional attributes for child components.
Example
The following example places 6 buttons in a horizontal row, aligned to the left edge of the flow container.
<flow height ="200" left ="16" top ="16" width ="1000" >
<button buttontype ="push" height ="126" name ="1" width ="126" />
<button buttontype ="push" height ="126" name ="2" width ="126" />
<button buttontype ="push" height ="126" name ="3" width ="126" />
<button buttontype ="push" height ="126" name ="4" width ="126" />
<button buttontype ="push" height ="126" name ="5" width ="126" />
<button buttontype ="push" height ="126" name ="6" width ="126" />
</flow>
popup
Creates a button that, when clicked, displays a balloon dialog containing the component. Popup groups may be defined. Only one popup from each group is displayed at a time, however popups from different groups may be displayed simultaneously.
Note:
It is an error to put more than 1 component tag under a popup tag.
Syntax
<popup container attributes >
<component child component attributes > </component>
DashBoard CustomPanel Development Guide
OGLML Reference • 75
</popup>
Container Attributes
In addition to General Attributes , the following attributes may be specified to the <
popup> tag:
Attribute
name group
Values
String
String
Restrictions Description
The name to display on the button to trigger the popup.
The group attribute is used to define different groups that can be open at the same time. If this attribute is not defined, the popup is not a part of any group.
Child Component Attributes
In addition to General Attributes , the following attributes must be specified to child components:
Attribute
width height
Values
Integer
Integer
Restrictions
Required
Required
Description
Width of the container inside the popup
Height of the container inside the popup
Example
The following example creates a popup triggered by a button labelled “Selector”. The popup contains an abs container with 4 buttons placed in a 2x2 grid.
<popup name ="Selector" >
<abs height ="100" width ="100" >
<button left ="0" top ="0" width ="50" height ="50" name ="1" />
<button left ="50" top ="0" width ="50" height ="50" name ="2" />
<button left ="0" top ="50" width ="50" height ="50" name ="3" />
<button left ="50" top ="50" width ="50" height ="50" name ="4" />
</abs>
</popup>
Figure 69 – Popup
DashBoard CustomPanel Development Guide
simplegrid
Creates a grid of fixed-sized cells. All cells in a simplegrid control are of the same size. Child components are laid out left-to-right, top-down and are sized to fill the cell. If more control over
layout is required, the table container should be used instead.
Syntax
<simplegrid container attributes >
<component component attributes > </component>
<component component attributes > </component>
<component component attributes > </component>
. . .
</simplegrid>
Container Attributes
In addition to General Attributes , the following attributes may be specified:
Attribute
rows cols
Values
Integer
Integer
Restrictions Description
Specifies the number of rows in the grid
Specified the number of columns in the grid
Child Component Attributes
See General Attributes . There are no additional attributes for child components.
Example
The following example creates a 2 row x 3 column grid, with buttons 1, 2, 3 on the top row and buttons 4, 5, 6 on the bottom row. Each cell is 100x100 pixels.
<simplegrid left ="16" top ="16" height ="200" width ="300" rows ="2" cols ="3" >
<button buttontype ="push" name ="1" />
<button buttontype ="push" name ="2" />
<button buttontype ="push" name ="3" />
<button buttontype ="push" name ="4" />
<button buttontype ="push" name ="5" />
<button buttontype ="push" name ="6" />
</simplegrid>
DashBoard CustomPanel Development Guide
OGLML Reference • 77
split
Note:
Creates a split screen with exactly two components. The split is either horizontal (with a left component and a right component, separated by a vertical split bar) or vertical (with a top component and a bottom component separated by a horizontal split bar). If only one component is defined under the split tag, the split is removed and the single component is returned.
It is an error to put more than 2 component tags under a split tag.
Syntax
<split container attributes >
<component
child component attributes
> </component>
<component
child component attributes
> </component>
</split>
Container Attributes
In addition to General Attributes , the following attributes may be specified to the <
split> tag:
Attribute
orientation
Values horizontal
vertical
Restrictions Description
The first component will be on the left and the second component will be on the right.
The first component will be on the top and the second component will be on the bottom.
Default values shown in bold.
Child Component Attributes
In addition to General Attributes , the following attributes may be specified to child components:
Attribute
weight minw minh maxw maxh
Values
Double value between +0.0 and 1.0
Restrictions Description
Specifies how much of the screen should be devoted to each side of the split.
If the weight is defined for both components, the split is determined by weight / total weight.
Positive integer
Positive integer
Positive integer
Positive integer
The minimum width of the component in pixels. This is considered a hint and may or may not be honored by DashBoard.
The minimum height of the component in pixels. This is considered a hint and may or may not be honored by DashBoard.
The maximum width of the component in pixels. This is considered a hint and may or may not be honored by DashBoard.
The maximum height of the component in pixels. This is considered a hint and may or may not be honored by DashBoard.
DashBoard CustomPanel Development Guide
Example
The following example creates a split container with a horizontal split:
• Left side contains an abs container with 4 buttons placed in a 2x2 grid.
• Right side contains an abs container with 4 buttons placed in a 2x2 grid.
<split height ="150" width ="300" orientation ="horizontal" >
<abs weight ="0.5" height ="100" width ="100" >
<button left ="5" top ="5" width ="25" height ="25" name ="1" />
<button left ="30" top ="5" width ="25" height ="25" name ="2" />
<button left ="5" top ="30" width ="25" height ="25" name ="3" />
<button left ="30" top ="30" width ="25" height ="25" name ="4" />
</abs>
<abs weight ="0.5" height ="100" width ="100" >
<button left ="5" top ="5" width ="25" height ="25" name ="5" />
<button left ="30" top ="5" width ="25" height ="25" name ="6" />
<button left ="5" top ="30" width ="25" height ="25" name ="7" />
<button left ="30" top ="30" width ="25" height ="25" name ="8" />
</abs>
</split>
tab
Creates a tab component where each child component within the tab tag represents a separate tab page inside of the tab component. Note that the height and width attributes of a tab component include the space occupied by the tab labels, not just the size of child components.
Syntax
<tab container attributes >
<component for tab 1
child component attributes
>
</component>
<component for tab 2
child component attributes
>
</component>
. . .
</tab>
DashBoard CustomPanel Development Guide
OGLML Reference • 79
Container Attributes
In addition to General Attributes , the following attributes may be specified to the <
tab> tag:
Attribute
tabposition tablayout tabheight onchange
Values north
east south west none none scroll
stack
Restrictions
How the tabs are rendered within their quadrant is determined by the look and feel.
Description
Specifies the placement of the tabs.
Integer ogScript String
Tab will not resize below minimum size to render tab label text
Tabs will be hidden and the visible component must be controlled through the “reveal” tag or the OGP
REVEAL_ELEMENT trap.
If there are more tabs than can fit in the horizontal space available, this controls whether there are multiple rows of tabs
(“stack”) or if additional tabs are on the same row and accessible via scrolling
(“scroll”).
Specifies the height of the tab label, in pixels. Note that the width of the tab is determined by the length of the tab label names.
The provided snippet of ogScript is triggered when the selected tab changes.
Current tab index is:
this.getSelectedIndex()
Current tab name is:
this.getTitleAt(this.getSelectedIndex()
)
Default values shown in bold.
Child Component Attributes
In addition to General Attributes , the following attributes may be specified to child components:
Attribute
name selected
Values
String default forced
none
Restrictions
This attribute is used in elements contained within a tab tag.
This attribute is used in elements contained within a tab tag.
Description
Specifies (or overrides) the name to display in the tab for a component. If the component provides its own name (e.g. an OGP Menu), that name will be used in the absence of this attribute. default = this tab will be selected by default when the UI is loaded. forced = this tab will be selected by default when the UI is loaded and, if the
UI is refreshed, this tab will be selected again. none = when the UI is loaded, the first tab in the tab group is selected. If the UI is refreshed, DashBoard should attempt to maintain the current tab selection.
Default values shown in
bold.
DashBoard CustomPanel Development Guide
Example
The following example creates a tab container with three tabs:
• First tab contains an abs container with 4 buttons placed in a 2x2 grid.
• Second tab contains an abs container with 4 buttons placed in a 2x2 grid.
• Third tab contains a single button
<tab width ="250" height ="300" left ="1" tabposition ="north" top ="1" >
<abs height ="300" width ="250" name ="First Tab" >
<button left ="5" top ="5" width ="25" height ="25" name ="1" />
<button left ="30" top ="5" width ="25" height ="25" name ="2" />
<button left ="5" top ="30" width ="25" height ="25" name ="3" />
<button left ="30" top ="30" width ="25" height ="25" name ="4" />
</abs>
<abs height ="250" width ="250" name ="Second Tab" >
<button left ="5" top ="5" width ="25" height ="25" name ="5" />
<button left ="30" top ="5" width ="25" height ="25" name ="6" />
<button left ="5" top ="30" width ="25" height ="25" name ="7" />
<button left ="30" top ="30" width ="25" height ="25" name ="8" />
</abs>
<button name ="Go" />
</tab>
table
A table is a grid of rows and columns. A cell in the table can span any number of rows or columns. Each cell in a table contains a component defined in a child tag. Similar to HTML, each row of cells in a table must be encapsulated in a tr tag. Each element inside of a tr tag defines a
Syntax
<table container attributes >
<tr>
<component child component attributes > </component>
<component child component attributes > </component>
. . .
</tr>
<tr>
<component child component attributes > </component>
<component child component attributes > </component>
. . .
</tr>
. . .
</table>
DashBoard CustomPanel Development Guide
OGLML Reference • 81
Child Tags
Tag
<tr>
<component>
Values
Any valid component tag
Restrictions Description
Encapsulates a row.
Defines the component for a table cell.
Must be a child of a tr tag.
Container Attributes
Child Component Attributes
The following set of attributes controls the layout of cells and components. To control the appearance of the table contents, these additional attributes should be defined in the child tags that define the content of the table cells.
Attribute
fill anchor
Values
none
Horizontal
Vertical both
Restrictions Description
Controls how the component inside of a table cell fills the cell itself.
Uses the component’s natural width and height and floats it inside of the cell.
Uses the component’s natural height but fills the horizontal space.
Uses the component’s natural width but fills the vertical space.
Ignores the component’s natural width and fills the entire cell.
If the fill is set to anything other than both, this controls where the component is attached to the cell. rowspan colspan insets
center north northeast east southeast south southwest west northwest
Positive integer Cells must not collide
Positive integer Cells must not collide
4 positive integers separated by commas. e.g. “5,5,5,5”
The number of rows spanned by a cell.
The number of columns spanned by a cell.
Specifies padding around the component. The 4 numbers represent the top, left, bottom, and right padding.
The insets are specified in pixels.
DashBoard CustomPanel Development Guide
minw minh maxw maxh
Attribute
weightx weighty orientation
Values
Double value between +0.0 and 1.0
Double value between +0.0 and 1.0
horizontal
vertical
Restrictions
Positive integer
Positive integer
Positive integer
Positive integer
Only applies to element tags that return multiple components.
Description
Specifies how to distribute extra horizontal space.
The table calculates the weight of a column to be the maximum
weightx of all the components in a column. If the resulting layout is smaller horizontally than the area it needs to fill, the extra space is distributed to each column in proportion to its weight. A column that has a weight of zero receives no extra space.
If all the weights are zero, all the extra space appears between the grids of the cell and the left and right edges.
Specifies how to distribute extra vertical space.
The table calculates the weight of a row to be the maximum weighty of all the components in a row. If the resulting layout is smaller vertically than the area it needs to fill, the extra space is distributed to each row in proportion to its weight. A row that has a weight of zero receives no extra space.
If all the weights are zero, all the extra space appears between the grids of the cell and the top and bottom edges.
If a tag returns multiple components (e.g. a param tag for an array parameter), this specifies whether the returned components should be in the same row
(horizontal) or in the same column
(vertical).
The minimum width of the component in pixels. This is considered a hint and may or may not be honored by
DashBoard.
The minimum height of the component in pixels. This is considered a hint and may or may not be honored by
DashBoard.
The maximum width of the component in pixels. This is considered a hint and may or may not be honored by
DashBoard.
The maximum height of the component in pixels. This is considered a hint and may or may not be honored by
DashBoard.
DashBoard CustomPanel Development Guide
OGLML Reference • 83
Note:
Attribute
placeholders maxperrow
Values
Positive integer
Default 0
Positive integer
Default -1
Restrictions Description
This tag specifies the minimum number of elements which are expected to be returned by a tag. If a tag returns fewer than the specified number of elements, placeholder elements are created and added to the layout in their place.
A value of
0 means that the tag is ignored if no elements were returned (or the tag is undefined).
A value > 0 defines the maximum number of elements in a row. Additional elements will be placed on the next row.
Default values shown in
bold.
DashBoard uses a Java Swing GridBagLayout internally. For more information about GridBagLayout, please see http://docs.oracle.com/javase/8/docs/api/java/awt/GridBagLayout.html
Example
The following sample utilizes a table to create a numeric keypad.
<table height ="300" left ="16" top ="16" width ="300" >
<tr>
<button buttontype ="push" fill ="both" name ="1" > </button>
<button buttontype ="push" fill ="both" name ="2" > </button>
<button buttontype ="push" fill ="both" name ="3" > </button>
</tr>
<tr>
<button buttontype ="push" fill ="both" name ="4" > </button>
<button buttontype ="push" fill ="both" name ="5" > </button>
<button buttontype ="push" fill ="both" name ="6" > </button>
</tr>
<tr>
<button buttontype ="push" fill ="both" name ="7" > </button>
<button buttontype ="push" fill ="both" name ="8" > </button>
<button buttontype ="push" fill ="both" name ="9" > </button>
</tr>
<tr>
<button buttontype ="push" fill ="both" name ="*" > </button>
<button buttontype ="push" fill ="both" name ="0" > </button>
<button buttontype ="push" fill ="both" name ="#" > </button>
</tr>
</table>
DashBoard CustomPanel Development Guide
Widget Tags
Widget tags are components that can be added to an OGLML page. In contrast with the Container tags described previously, widget tags do not contain other components.
The following tags are provided.
Tag
Description
Brings hidden tab pages to the front
Opens the editor for a specified node in the DashBoard Tree.
Displays a static image
Creates a static text label
Creates a button
Creates a web browser window
Placeholder, used to leave a blank cell in simplegrid, table and flow containers
Allows DashBoard client screen to be locked
Creates an instance of a custom widget
reveal
Creates a button that, when clicked, causes elements within tab pages to become visible in the UI.
When the button is pressed, DashBoard finds all components with the provided target ID(s) and checks to see if they are contained within a tab component or menugroup. If component is found, its tab page is brought to the foreground (made the active tab). If the specified component is buried deep within the UI (e.g. a tab within a tab), the device must supply multiple IDs to ‘reveal’ the desired component and the component’s parents.
Syntax
<reveal name ="button-name", targetid ="element1,element2,..." >
</reveal>
Attributes
In addition to General Attributes , the following attributes may be specified to the <
reveal> tag:
Attribute
name targetid
Values
String list of Strings separated by commas or semicolons.
Restrictions
Each string in the value must refer to the
id of another component.
Description
The name to display on the button.
Specifies the element ids to show.
DashBoard CustomPanel Development Guide
OGLML Reference • 85
Examples
The following example creates a button that reveals the menu with id “Key1Panel”
<reveal name ="Key 1", targetid ="Key1Panel" />
The following example creates a button that reveals the menu “Key1Panel” and the tab
“Key1ChromaTab”.
<reveal name ="Chroma Key 1", targetid ="Key1Panel,Key1ChromaTab" />
ext
Creates a button that, when clicked, causes DashBoard to open an editor tab for a device in the
DashBoard tree view. When the button is pressed, DashBoard searches its tree view for a node with the provided ID. If a node is found and the node contains an editor, its editor is opened and/or brought to the foreground (made the active tab).
If a component is buried deep within the UI (e.g. a tab within a tab), the card can supply multiple
IDs to ‘reveal’ not only the desired component, but also the component’s parents.
Syntax
<ext name =
"
button-name
"
objectid =
"
node-id
"
buttontype ="type"
general attributes
/ >
<ext name =
"
button-name
"
objectid =
"
FileNavigator,file-path,file-
name
"
buttontype ="type" general attributes/ >
Attributes
In addition to General Attributes , the following attributes may be specified to the <
ext> tag:
Attribute
name objectid
Values
String
String buttontype
button
label
Default values shown in bold.
Restrictions
The value must refer to the node
ID an element in
DashBoard’s tree view.
Optional
Description
The name to display on the button.
Specifies the id of the components to show.
DashBoard provides a few shortcuts to reference elements under the device node in the tree or a sibling device in the same frame:
%frame% will be replaced with the frame’s primary identifier.
%device% will be replaced with the device’s primary identifier.
%slot 1 (or 2, or 3, etc.)% will be replaced with the primary identifier of the device in the referenced slot in the same frame.
If the String starts with
“ FileNavigator,” the objectid specifies a path and filename of a resource in the DashBoard file navigator, rather than the tree view.
“button” = display the link as a button
“label” = display the link as a label
DashBoard CustomPanel Development Guide
image
Fetch an image from the provided URL and display it.
Syntax
<image src ="URL-String" attributes > </image>
Attributes
Attribute
src height top bottom width left right
Values
URL String
Integers
Integers
Restrictions
Required. Must be a fully qualified URL.
Description
Set the background image of the component.
It top and bottom are both specified, or
height is specified, the image will be stretched to the height specified.
Otherwise, the image’s native height is used.
It left and right are both specified, or
width is specified, the image will be stretched to the width specified.
Otherwise, the image’s native width is used.
Examples
The following example places an image at its native size:
<image src ="http://whatever.com/logo.jpg" top ="50" left ="50" />
The following example places an image and scales it to 200x100 pixels in size.
<image src =" http://whatever.com/logo.jpg" top ="50" left ="50" height ="100" width ="200" />
label
Display a label. If the name is not defined, the text content of the label is used to provide the content. One or more ogScript tasks can be attached to a label to be fired when the label is clicked.
Syntax
<label name ="label-name" attributes > </label>
Attributes
Tag
name align header
Values
String left right center true
false
Restrictions Description
The text to display in the label.
The horizontal alignment of the text within the label.
Format the label as a header element
(apply a standard header background, foreground, and border).
DashBoard CustomPanel Development Guide
OGLML Reference • 87
Tag
html
Values
true
false
Restrictions Description
The text is actually a snippet of HTML
(you do not need to provide the
<html></html> tags).
Default values shown in bold.
Examples
<label name ="This is a label" />
<label html ="true" name ="This is an <i>HTML</i> label" />
<label header ="true" name ="Label with the header attribute" />
Figure 70 – Label Examples
button
Display a button. One or more ogScript tasks can be attached to a button to be fired when the button is pressed or toggled.
Syntax
<button name ="label-name" attributes > </button>
Attributes
Attribute
name buttontype toggled flat
Values
String
push
toggle checkbox radio true
false
true
false
Restrictions
Required
Description
The text to display in the label.
The type of button to create. Push buttons are stateless. Toggle, checkbox, and radio are all 2-sate “on” and “off”.
The initial state of the button.
Only applicable to
push or toggle
buttontype
Request a ‘flat’ look for the button (or toggle button) in the UI. Note that icons styles may not be applied to flat buttons.
Default values shown in bold.
DashBoard CustomPanel Development Guide
Examples
This example displays a series of simple pushbuttons as illustrated in Figure 71:
<button buttontype ="push" name ="push" top ="25" width ="80" />
<button buttontype ="toggle" name ="toggle" toggled ="true" top ="25" width ="80" />
<button buttontype ="push" flat ="true" left ="400" name ="flat" top ="25" width ="80" />
<button buttontype ="radio" left ="500" name ="radio" top ="25" />
<button buttontype ="checkbox" left ="600" name ="checkbox" top ="25" />
Figure 71 – Button Examples
browser
Embed a web browser component in the page and point it at the specified URL.
Note The browser plug-in is a heavy widget, and should therefore be used sparingly.
Syntax
<browser url ="URL-String" height ="height" width ="width" attributes >
</browser>
Attributes
Attribute
url width height
Values
URL String
Restrictions
Required. Must be a fully qualified URL.
Positive integer Required
Positive integer Required
Description
The URL to use for the provided browser.
The width (in pixels) of the browser
The height (in pixels) of the browser
Notes
This is a native browser component provided by the OS.
• On Windows it will generally be Internet Explorer.
• On Linux it will either be WebKit GTK or XUL Runner.
• The browser is currently disabled on OS X pending a bug fix within the Eclipse platform.
The web sites pointed to by the browser must NOT contain Java Applets.
Not all plug-ins will be available on all browsers. It is recommended that developers test their web pages inside of DashBoard on multiple platforms.
The browser is a heavyweight component and must not be used inside of a scrolling component.
The browser will cause rendering issues if it is clipped by other components.
DashBoard CustomPanel Development Guide
OGLML Reference • 89
Example
<browser url ="http://www.rossvideo.com" height ="400" width ="1200" />
blank
Creates a blank placeholder component. This can be used to fill space where necessary.
Syntax
<blank
attributes
/>
Attributes
Example
<table left ="25" top ="25" width ="400" >
<tr>
<label name ="This" width ="100" />
<label name ="is" width ="100" />
<label name ="a" width ="100" />
<label name ="table" width ="100" />
</tr>
<tr>
<label name ="with" width ="100" />
<blank/>
<label name ="blank" width ="100" />
<label name ="tags" width ="100" />
</tr>
</table>
Figure 72 – Blank Tag Example
lock
Creates a button that, when pressed, will turn on DashBoard’s screen lock. The lock button will display a lock icon by default but this icon can be overridden by a card developer.
Syntax
<lock name ="button-name"
attributes
/>
DashBoard CustomPanel Development Guide
Attributes
Attributes
name
Values
String
Restrictions Description
Text to display on the button. Text will be rendered beside the lock icon.
Example
<lock name ="Lock Screen" left ="25" top ="25" />
Figure 73 – Lock Button
When locked, the DashBoard UI will be darkened, with an unlock widget.
Figure 74 – Lock Screen Widget
widget
Creates an instance of a custom widget. The widget must be defined through a widgetdescriptor tag. Parameters declared within the widgetdescriptor’s config block may be overridden through param tags within a config block.
Syntax
<widget widgetid ="widget-id" baseOID ="base-oid" >
<config>
<params>
<param/>
<param/>
. . .
<params/>
</config>
</widget>
DashBoard CustomPanel Development Guide
OGLML Reference • 91
Attributes
In addition to General Attributes , the following attributes may be specified to the <
widget> tag:
Attributes
widgetid baseOID
Values
String
String
Restrictions
Must match the
id of a declared widgetdescriptor.
Description
Widget identifier.
Specifies the base OID string for relative parameter access. Relative parameter access within the widget will be prefixed with the value of the
baseOID attribute string.
See Also
Examples
The following example displays a custom widget with id alarmgrid:
<widget widgetid ="alarmgrid" top ="100" left ="100" />
The following example displays a custom widget with id alarmgrid, overriding the value of parameter str2 with the value “New String Value”:
<widget left ="100" top ="300" widgetid ="alarmgrid" >
<config>
<params>
<param oid ="str2" value ="New String Value" />
</params>
</config>
</widget>
Non-UI Tags
The following tags do not provide any UI elements themselves. They contribute new parameters, script snippets, constraints, etc. for use elsewhere in the OGLML document.
The following tags are provided.
Tag
Description
Provides a location for global ogScript code.
A convenient parent tag for all non-UI tags. Does not deepen scope.
A container for user-defined widget descriptors.
Defines a custom widget.
DashBoard CustomPanel Development Guide
Tag
Description
Defines constants to be substituted inside of other tag attributes or used in ogScript blocks.
To provide something similar to Cascading Style Sheets (CSS) available in HTML, styles can be defined in a tag and referenced in the style attribute of widget tags.
Defines or overrides a color constant for use within style hints.
Defines an ogScript code snippet to handle an event on a UI element or parameter.
Defines the constraint of a parameter.
The parent container for parameters defined within the OGLML document.
Fires events at regular intervals.
Allows an OGLML page to process network communications using protocols not already available.
Defines a block of ogScript to be run when an event happens in the system.
Defines a block of ogScript to be run when a timer goes off.
Allows an OGLML document to be assembled from several individual
XML files or fragments.
api
Provides a location for global ogScript code. Contents of the api tag are processed by the ogScript compiler directly. Elements within an api tag are scoped where they are declared in the
XML; siblings and children of siblings have visibility to elements declared within the api tag.
The api tag should generally be placed within a <meta> tag for global ogScript code encapsulation. However, ogScript code intended to dynamically generate and modify the XML should be placed in a top-level api tag.
Syntax
<api>
global-scope elements
</api>
Attributes
None.
DashBoard CustomPanel Development Guide
OGLML Reference • 93
meta
This is a convenient parent tag for all non-UI tags. The meta tag does not deepen the scope, therefore children of the meta are considered at the same scope as the meta tag itself, and therefore siblings of other top-level tags.
Syntax
<meta>
non-ui-tags
</meta>
Attributes
None.
widgets
This is a container for user-defined widget descriptors.
Syntax
<widgets>
<widgetdescriptor/>
<widgetdescriptor/>
. . .
</widgets>
Attributes
None.
widgetdescriptor
Defines a custom widget. The widget descriptor contains two blocks denoted by <config> and
<oglml> tags. The config section includes content to render the widget’s configuration page within PanelBuilder’s Edit Component dialog. The oglml block contains the content to create the widget itself.
The widgetdescriptor tag may be contained within a widgets block of an oglml document, in an external file or be served up via URL
Syntax
<widgetdescriptor id ="widget-id" baseurl ="URL-string" structtype ="structtype" >
<config/>
<oglml/>
</widgetdescriptor>
DashBoard CustomPanel Development Guide
Attributes
Attributes
id structtype baseurl
Values
String
String
String
Restrictions Description
Must be unique Widget identifier.
Must be a valid, fully qualified
URL.
Specifies a dependency of the widget upon a global struct parameter with matching
structtype. Currently this type checking is restricted only to
PanelBuilder UI; a custom widget will only be available in PanelBuilder if a parameter exists with matching
structtype.
When specified, the widget descriptor will be fetched from a document specified by the URL, rather than inline.
See Also
Examples
The following creates a custom widget which displays four alarm dots in a 2x2 grid. The strings that sit beside each dot are configurable parameters of the widget.
<widgetdescriptor id ="alarmgrid
">
<config>
<params>
<param access ="1" type ="STRING" oid ="str1" name ="String
1
"/>
<param access ="1" type ="STRING" oid ="str2" name ="String
2
"/>
<param access ="1" type ="STRING" oid ="str3" name ="String
3
"/>
<param access ="1" type ="STRING" oid ="str4" name ="String
4
"/>
</params>
</config>
<oglml>
<simplegrid cols ="2" rows ="2
">
<param oid ="str1" widget ="12" width ="200" height ="40 "/>
<param oid ="str2" widget ="12" width ="200" height ="40
"/>
<param oid ="str3" widget ="12" width ="200" height ="40 "/>
<param oid ="str4" widget ="12" width ="200" height ="40" />
</simplegrid>
</oglml>
</widgetdescriptor>
DashBoard CustomPanel Development Guide
OGLML Reference • 95
The following retrieves a widget descriptor from a web server:
<widgetdescriptor baseurl ="http://mydevice/files/widgets.widgetdescriptor" />
The widget is then displayed with the following:
<widget widgetid ="alarmgrid" top ="100" left ="100" />
The following example displays the widget, overriding the value of parameter str2 with the value “New String Value”:
<widget left ="100" top ="300" widgetid ="alarmgrid" >
<config>
<params>
<param oid ="str2" value ="New String Value" />
</params>
</config>
</widget>
lookup
A lookup defines constants to be substituted inside of other tag attributes or used in ogScript blocks. Lookups contain “entry” tags to define key/value pairs. Constants defined in a parent context can be referenced in a child context. If a key from the parent context is re-defined in a child context, the re-defined value will take precedence in the child’s scope.
Global
lookup tags should usually be placed within an api
Syntax
<lookup id ="id-string" scope ="scope" >
<entry key ="key">value </entry>
<entry key ="key">value </entry>
. . .
</lookup>
Attributes
Attribute
scope
Values
private
public
window
Restrictions
If “private”, the lookup must define the id attribute. id code string true
false
Description
By default, all key/value pairs are added to a general lookup table. The lookup table in any context is the concatenation of all parent lookup tables and sibling lookup tables.
If the scope is set to “private”, the key/value pairs can only be referenced using the lookup table’s ID.
If defined, key/value pairs for this lookup can be referenced in ogScript using
“ogscript.getPrivateString(‘[id]’, ‘[key]’);”
Or substitute inside of other attributes with %const[‘id’][‘key’]%
Must be set true if the lookup value contains executable script.
DashBoard CustomPanel Development Guide
Attribute
multiline
Values
true
false
Default values shown in bold.
Restrictions Description
Must be set true if lookup value contains multi-line strings.
Example
The following tag creates a public lookup
<lookup>
<entry key ="breakfast">Bacon and Eggs </entry>
<entry key ="lunch">BLT </entry>
<entry key ="dinner">Bacon explosion </entry>
<entry key ="snack">Bacon-maple donut </entry>
</lookup>
The following code returns the string BLT. var currentMeal = ogscript.getString('lunch');
The following tag creates a private scope lookup
<lookup id ="family" scope ="private" >
<entry key ="father">Homer Simpson </entry>
<entry key ="son">Bart Simpson </entry>
<entry key ="mother">Marge Bouvier-Simpson </entry>
<entry key ="daughter">Lisa </entry>
<entry key ="baby">Magaggie </entry>
</lookup>
The following code would return the string Homer Simpson. var name = ogscript.getPrivateString('family', 'father');
The following tag creates a block of code lookup:
<lookup code ="true" id ="GlobalScripts" multiline ="true" >
<entry key ="UpdateTimer" >
{ if (params.getValue('Update_Automatically', 0) == 1) ogscript.getTimerManager().getTimer('UpdateTimer').startTimer( false);
} else
{
ogscript.getTimerManager().getTimer('UpdateTimer').stopTime
r(false);
}
</entry>
</lookup>
DashBoard CustomPanel Development Guide
OGLML Reference • 97
The following is an example of instancing the code defined in the above lookup:
<ogscript handles ="onload" > %const['GlobalScripts']['UpdateTimer']% </ogscri pt>
style
To provide something similar to Cascading Style Sheets (CSS) available in HTML, styles can be
defined in a tag and referenced in the style attribute of widget tags.
Syntax
<style id ="style-name" value ="value-string" />
Attributes
Attribute
id value
Values
string string
Restrictions
Must not contain a semicolon
Must not contain any circular references to itself.
Description
The ID to use when referencing the style.
Value contains a style hint string following the same format used in the
style attribute of other tags.
Examples
The following example applies button style hints as defined in the predefined style
CommandButtonStyle. Note that the “Stop” button has an additional hint applied
( size:big), and overrides the background color (bg#ff0000).
<style id ="ButtonStyle" value ="bg#808000;bdr:etched;" />
<button name ="Start" style ="style:ButtonStyle;" />
<button name ="Stop" style ="style:ButtonStyle;size:big;bg#ff0000;" />
<button name ="Reset" style ="style:ButtonStyle;" />
Figure 75 - Style Tag Example
color
Defines or overrides a color constant for use within style hints.
Syntax
<color id ="color-name" value ="color-value" />
DashBoard CustomPanel Development Guide
Attribute
id
Attributes
value
Values
string
Restrictions
#RRGGBB or
#color-constant
or
#RRGGBBAA
Description
The ID to use when referencing the color.
Value contains a style hint string following the same format used in the
Example
The following example defines a color constant ColorBlue and applies it to the background of a button widget.
<color id ="VibrantBlue" value ="#0000FF" />
<button name ="Blue Button" style ="bg#VibrantBlue" />
ogscript
Defines an ogScript code snippet to handle an event on a UI element or parameter.
For more information, see ogScript Reference on page 141 .
Syntax
<ogscript handles=”[event type]”>
Ogscript code
</ogscript>
Attributes
Attribute
use targetid handles
Values
online offline
both string
Restrictions
onchange onmousedown
Multiple “handles” arguments can be supplied separated by commas.
Only supported by tabs and parameters.
Description
Script will only run on a real device
Script will only run on a file-based device
Script will run always
The ID of the UI element to target.
The type of event that triggers the script.
Triggers script when parameter or tab is changed. onmouseup onclick
Triggers script onmouse click down event.
Triggers script on mouse click up event.
Triggers script when element is clicked.
DashBoard CustomPanel Development Guide
OGLML Reference • 99
Attribute
oid element script
Values
onmousemove ondrag ondrop dragvalue onload
Positive integer Must be a defined
OID.
Only applies to
“onchange”
List of array indices separated by commas
All array elements referenced must exist in the parameter value.
Only applies to
“onchange” ogScript
Restrictions
Can also be the text content of the
<ogscript> tag.
Description
Triggers script when mouse moves over component
Triggers script hen the element is dragged
Triggers script when another component is dropped on the component. must specify something to return
(generally a string or a number) when the element is dragged.
Triggered when the panel has finished loading or is reloaded
The OID of the parameter to target.
By default all elements of an array parameter are targeted. This attribute can be used to return a subset of the array. If a list is provided, only the elements at the provided indices are returned (note- you can specify the elements in any order).
This value must be “0” for a non-array parameter.
The script to run when triggered by any of the events listed in “handles”.
Default values shown in bold.
constraint
Defines the constraint of a parameter. The structure of this object depends upon the
constrainttype of the parameter. Range constraints are specified as an attribute of a param tag;
Choice, Alarm Table, and Struct constraints are specified using constraint tags as children to the param object.
Constraints may be defined within a param declaration, or defined globally and referenced by specific parameters.
Syntax
Constraints with inline constraint values:
<constraint constrainttype ="ctype" constraint ="cvalue" id= "constraint-id" />
Constraints defined within a param tag with inline constraint values:
<param constrainttype="ctype" constraint="cvalue"
paramattributes
/>
DashBoard CustomPanel Development Guide
Note
Choice and Alarm Constraints:
<param constrainttype ="ctype"
param-attributes
>
<constraint
key-attributes
>
cvalue
</constraint>
<constraint
key-attributes
>
cvalue
</constraint>
. . .
</param>
Choice and Alarm Constraints defined within a param tag:
<param constrainttype ="ctype"
param-attributes
/>
<constraint
key-attributes
>
cvalue
</constraint>
<constraint
key-attributes
>
cvalue
</constraint>
. . .
</param>
See sections below for examples and syntax for each constraint type.
Constraint Types
Constraint
Constraint Type
INT_NULL
FLOAT_NULL
INT_RANGE
INT_STEP_RANGE
FLOAT_RANGE
FLOAT_STEP_RANG
E
INT_CHOICE
String Choice Constraint STRING_CHOICE
ALARM_TABLE
ID_REFERENCE
STRUCT
Param Type
INT16_PARAM
INT16_ARRAY
INT32_PARAM
INT32_ARRAY
FLOAT_PARAM
FLOAT_ARRAY
INT16_PARAM
INT16_ARRAY
INT32_PARAM
INT32_ARRAY
FLOAT_PARAM
FLOAT_ARRAY
INT16_PARAM
INT16_ARRAY
INT32_PARAM
INT32_ARRAY
STRING_PARAM
STRING_ARRAY
INT16_PARAM
INT32_PARAM
All
STRUCT_PARAM
STRUCT_ARRAY
If no constraint is specified for a parameter, it will be unconstrained by default.
Refer to the appropriate section below for definition of the constraint object for each constraint type.
DashBoard CustomPanel Development Guide
OGLML Reference • 101
constraint (Unconstrained)
Specifies that a parameter is unconstrained. All parameters are considered unconstrained by default if no constraint is applied.
Syntax
<param constrainttype="constraint-type"
attributes
/>
Attributes
Attribute
constrainttype
Values
INT_NULL
FLOAT_NULL
Restrictions
param type:
INT16_PARAM
INT16_ARRAY
INT32_PARAM
INT32_ARRAY
param type:
FLOAT_PARAM
FLOAT_ARRAY
Description
Parameter is unconstrained
Examples
The following constraint specifies an integer to be unconstrained:
<param constrainttype ="INT_NULL" name ="Delay" oid ="0x500" type ="INT16_PARAM" />
constraint (Constraint Reference)
References a globally-defined constraint. A constraint may be specified globally in the <meta> block. These globally-defined constraints may then by referenced by specific parameters.
Syntax
<constraint id= "constraint-id" constrainttype ="constraint-type" >
<param constrainttype ="ID_REFERENCE" constraint ="constraint-id"
attributes
/>
Attributes
Attribute
id constrainttype
Values
String
Any valid
constraint type
Restrictions
Param type must be compatible with the referenced constraint.
Description
Unique identifier for this constraint
See Constraint Types for valid constraint
types.
DashBoard CustomPanel Development Guide
Examples
The following example creates a global constraint VideoFormat. Params 0x501, 0x502 and
0x503 are all constrained using this constraint definition.
<constraint constrainttype ="INT_CHOICE" id ="VideoFormat" >
<constraint key ="0" >
480i-59.94
</constraint>
<constraint key ="1" >
576i-50
</constraint>
<constraint key ="2" >
1080i-29.97
</constraint>
<constraint key ="3" >
1080i-25
</constraint>
<constraint key ="4" >
720p-59.94
</constraint>
<constraint key ="5" >
720p-50
</constraint>
<constraint key ="6" >
1080p-59.94
</constraint>
<constraint key ="7" >
1080p-50
</constraint>
</constraint>
<param constrainttype ="ID_REFERENCE" constraint ="VideoFormat" name ="Vid1" oid ="0x501" type ="INT16_PARAM"/ >
<param constrainttype ="ID_REFERENCE" constraint ="VideoFormat" name ="Vid2" oid ="0x502" type ="INT16_PARAM"/ >
<param constrainttype ="ID_REFERENCE" constraint ="VideoFormat" name ="Vid3" oid ="0x503" type ="INT16_PARAM"/ >
constraint (Range Constraints)
Constrains a numeric parameter type to a specific range. Minimum and maximum values effect the parameter’s valid range. Display minimum and maximum values scale the parameter value to a different range for display purposes. Finally a step value can be set to constrain the minimum step size a value may be changed by.
Syntax
Min / Max Constraint:
<param constraint="min;max;" constrainttype="constraint-type"
attributes
/>
Min / Max Constraint with Display-Min and Display-Max:
<param constraint ="min;max;display-min;display-max;" constrainttype ="constraint-type"
attributes
/>
Min / Max Step Constraint:
<param constraint ="min;max;step" constrainttype ="constraint-
type
"
attributes
/>
Min / Max Step Constraint with Display-Min and Display-Max:
<param constraint ="min;max;display-min;display-max;step" constrainttype ="constraint-type"
attributes
/>
DashBoard CustomPanel Development Guide
OGLML Reference • 103
Attributes
Attribute
constraint
Values
constrainttype INT_RANGE
INT_STEP_RANGE
FLOAT_RANGE
FLOAT_STEP_RANGE
min
Restrictions Description
param type:
INT16_PARAM
INT16_ARRAY
INT32_PARAM
INT32_ARRAY
Type of constraint
param type:
FLOAT_PARAM
FLOAT_ARRAY
Required Minimum value to which a parameter can be set
max
Required
display-min display-max step
Optional; must be used with
display_max.
Optional; must be used with
display_min.
xxx_STEP_RAN
GE constraints only
Minimum value to which a parameter can be set
The displayed value of the parameter when the parameter has a value of
min. The default value is min.
The displayed value of the parameter when the parameter has a value of
max. The default value is max.
Smallest increment a value may be changed by. Spinner widgets will increment a parameter by the step value. Note that the step increment is applied to the parameter value, not the display value.
Examples
The following example constrains a FLOAT_PARAM to [0,100]:
<param constraint ="0.0;100.0;" constrainttype ="FLOAT_RANGE" name ="Delay" oid ="audio.delay" type ="FLOAT_PARAM" />
The following example constrains an integer to [0, 255] mapping it to a display range of [0, 100], and the value increments by steps of 2:
<param constraint ="0;255;0;100;2" constrainttype ="INT_STEP_RANGE" name ="Gain" oid ="key1.gain" type ="INT16_PARAM" />
constraint (Integer Choice Constraints)
Choice constraints provide a list of possible values for a parameter, based upon a text selection.
For integer parameters, the parameter may only be assigned a value specified in the constraint.
Syntax
<param constrainttype= "INT_CHOICE" type= "param-type"
attributes
>
<constraint key=
"choice1-key"
>
choice1-value
</constraint>
<constraint key= "choice2-key" >
choice2-value
</constraint>
. . .
</param>
DashBoard CustomPanel Development Guide
Attributes
Attribute
type key
value
Values
INT16_PARAM
INT32_PARAM
INT16_ARRAY
INT32_ARRAY
Integer
Restrictions
String
Description
Parameter must be integer type.
Examples
The following constraint provides an enumerated choice:
<param constrainttype ="INT_CHOICE" name ="Channel" oid ="0x503" type ="INT16_PARAM" >
<constraint key ="0" >
Channel 01
</constraint>
<constraint key ="1" >
Channel 02
</constraint>
<constraint key ="2" >
Channel 03
</constraint>
<constraint key ="3" >
Channel 04
</constraint>
</param>
constraint (String Choice Constraints)
Choice constraints provide a list of possible values for a parameter, based upon a text selection.
For String parameters, the constraint provides a set of defaults, but the user may arbitrarily enter any other value for the parameter.
Syntax
<param constrainttype=
"STRING_CHOICE" type=
"param-type"
attributes
>
<constraint>
value
</constraint>
<constraint>
value
</constraint>
. . .
</param>
Attributes
Attribute
type
value
Values
STRING_PARAM
STRING_ARRAY
String
Restrictions Description
Parameter must be string type.
Available strings for drop-down widget
Numeric assignment of current enumerated choice.
Text name for the current enumerated choice
DashBoard CustomPanel Development Guide
OGLML Reference • 105
Examples
The following constraint provides five string options for a String parameter.
<param constrainttype ="STRING_CHOICE" name ="Name" oid ="0x504" type ="STRING_PARAM" >
<constraint>
Zeus Test Card
</constraint>
<constraint>
ZTC
</constraint>
<constraint>
Johnny
</constraint>
<constraint>
Matilda
</constraint>
</param>
Figure 76 – String Choice
constraint (Alarm Table)
Alarm constraints map a set of alarms as bitfields into an INT16_PARAM or INT32_PARAM.
Each bit represents an independent alarm which may have a message and severity assigned to it.
Alarm parameters contribute to the device’s overall alarm status in DashBoard; the most severe alarm set will determine the device’s overall reported alarm status.
Syntax
<param constrainttype= "ALARM_TABLE" type= "param-type"
attributes
>
<constraint key=
"bit-number" severity=
"severity"
>
value
</constraint>
<constraint key= "bit-number" severity= "severity" >
value
</constraint>
. . .
</param>
Attributes
Attribute
type key severity value
Values
INT16_PARAM
INT32_PARAM
Integer
Integer
String
Restrictions
INT16: 0..15
INT32: 0..31
Description
Parameter must be integer type.
The bit position for the alarm (0 is LSB).
The severity of the alarm:
0 = OK
1 = WARN
2 = ERROR
Alarm message text
DashBoard CustomPanel Development Guide
Examples
The following constraint creates an alarm table:
<param constrainttype ="ALARM_TABLE" name ="Alarm" oid ="0x504" type ="INT16_PARAM" >
<constraint key ="0" severity ="0" >
Hardware OK
</constraint>
<constraint key ="1" severity ="2" >
Hardware Error
</constraint>
<constraint key ="2" severity ="1" >
Flash Memory
Full
</constraint>
</param>
constraint (Struct Constraints)
Struct Constraints allow a parameter to define a complex structure of multiple parameters. The
Struct Constraint is applied to each parameter that is an instance of a Struct.
Syntax
<param constrainttype ="STRUCT" structtype ="struct-type" templateoid ="template-oid" type ="STRUCT"
param-attributes
>
Attributes
Attribute
type templateoid structtype
Values
String
String
String
Restrictions
Required
Must be unique
Description
Set to "STRUCT"
Specifies a template OID to pre-populate the structure. All parameters, constraints and widgets for the sub-OIDs are copied from the template.
Defines the structure type. Used by
PanelBuilder to type-check custom widgets against defined struct parameters.
Examples
The following code is an example of a struct definition.
<param constrainttype ="STRUCT" name ="Clip Info" oid ="clipInfo" structtype ="playinfo" type ="STRUCT" widget ="36" >
<value>
<subparam name ="Clip Name" suboid ="ClipName" type ="STRING" value ="Test" />
<subparam name ="Director" suboid ="Director" type ="STRING" value ="Test" />
<subparam name ="Date" suboid ="AirDate" type ="STRING" value ="Test" />
<subparam name ="Author" suboid ="Author" type ="STRING" value ="Test" />
</value>
</param>
DashBoard CustomPanel Development Guide
OGLML Reference • 107
The following declaration utilizes the previous example as a template, by specifying the templateoid attribute:
<param constrainttype ="STRUCT" name ="Clip List" oid ="clipList" structtype ="playinfo" templateoid ="clipInfo" type ="STRUCT_ARRAY" widget ="36" >
<value>
<subparam suboid ="ClipName" value ="Winter is Coming" />
<subparam suboid ="Director" value ="Tim Van Patten" />
<subparam suboid ="OriginalAirDate" value ="April 24, 2011" />
<subparam suboid ="Author" value ="David Benoiff & D.B.
Weiss"
/>
</value>
<value>
<subparam suboid ="ClipName" value ="The Kingsroad" />
<subparam suboid ="Director" value ="Brian Kirk" />
<subparam suboid ="OriginalAirDate" value ="April 24, 2011" />
<subparam suboid ="Author" value ="David Benoiff & D.B.
Weiss"
/>
</value>
<value>
<subparam suboid ="ClipName" value ="Lord Snow" />
<subparam suboid ="Director" value ="Brian Kirk" />
<subparam suboid ="OriginalAirDate" value ="May 1, 2011" />
<subparam suboid ="Author" value ="David Benoiff & D.B.
Weiss"
/>
</value>
<value>
<subparam suboid ="ClipName" value ="A Golden Crown" />
<subparam suboid ="Director" value ="Daniel Minahan" />
<subparam suboid ="OriginalAirDate" value ="May 22, 2011" />
<subparam suboid ="Author" value ="David Benioff & D. B.
Weiss"
/>
</value>
</param>
params
The parent container for parameters defined within the OGLML document. This tag may only contain <param> tags.
Syntax
<params>
<param
param-attributes
/>
<param
param-attributes
/>
. . .
</params>
DashBoard CustomPanel Development Guide
Attributes
None.
timer
The timer tag fires events at regular intervals. Timers can operate on their own or linked to other timers. ogScript commands exist to start/stop/reset timers (see ogScript documentation for more details).
Tasks are attached to listener tags to process data received.
Attributes
Attribute
id
Values
String source rate delay pattern start stop autostart
String
Long
Long
String
Long or time in format of
“pattern”
Long or time in format of
“pattern” true
*false
Restrictions
Optional
Optional.
Must be the ID of another timer.
Not applicable if
“source” is set.
Not applicable if
“source” is set.
Default value is true if ‘clock mode’ is used.
Description
The ID used to reference this timer.
Required for ogScript, child timers, or external <timertask/> tags to interact with the timer.
If used, the timer being defined will be a child of the timer with the given ID.
The rate (in milliseconds) at which the timer fires.
The delay (in milliseconds) before the timer initially fires.
The display pattern for the timer’s current time: https://docs.oracle.com/javase/8/docs/ap i/java/text/SimpleDateFormat.html
The start value of the timer. If start > stop, timer counts down.
If start is undefined, the timer is ‘clock mode’
The start value of the timer. If start > stop, timer counts down.
If start is undefined, the timer is ‘clock mode’
Whether or not the timer automatically starts. If it is not automatically started, an ogScript command must be issued to the timer to start it.
DashBoard CustomPanel Development Guide
OGLML Reference • 109
listener
The listener tag allows an OGLML page to process network communications using protocols not already available. It is designed for small and simple protocols only.
The listener tag can work in two different modes: listen for incoming connections (server mode) or establish a connection (client mode). In both cases, the listener tag will listen for incoming data from the remote system.
Tasks are attached to listener tags to process data received.
Attribute
connecthost
Values
String connectport listenport delimitertype delimiter syncword
Integer
Integer newline bytes fixedlen varlen string
Restrictions
Cannot be used if listenport is defined.
Description
The hostname of the remote host to connect to.
Cannot be used if listenport is defined.
Cannot be used if connectport/conn ect host are defined.
Required.
The port to connect to on the remote host.
The local port to listen on for new connections.
May be required depending on value of
delimitertype
Optional
The mechanism used to separate one incoming message from another.
“newline” = read bytes until 0x0A is received
“bytes” = convert value in “delimiter” attribute into a byte array and wait for those bytes.
“fixedlen” = read a fixed number of bytes for each message.
“string” = convert value in “delimeter” into
UTF-8 bytes and wait for those bytes.
“varlen” = convert value in “delimiter” to an integer “n”. The first [n] bytes of the message indicate how many bytes follow.
The data for the delimiter. Changes depending on the value of delimitertype bytes: The bytes in the message delimiter. E.g. to listen for a Carriage
Return/Line Feed combination “0D0A”. fixedlen: The number of bytes in each message.
String: The UTF-8 String to wait for to indicate the end of a message. E.g.
“END” varlne: The number of bytes to read to determine message length. E.g. if your protocol defines a 2-byte length count at the beginning of each message, the value would be “2”.
Defines an array of bytes to read at the start of an incoming message. E.g. for openGear protocol, the sync word would be “BAD2ACE5”
DashBoard CustomPanel Development Guide
Attribute
blockingpause buttontype autostart
Values
true
false toggle
none true false
Restrictions Description
When processing tasks, blockingpause means that all message processing is done in the message RX Thread. This means that if a “pause” task is encountered, all RX of messages will pause too.
If no button is defined, the listener is automatically started. If a button is defined, this allows the user to toggle the listener off/on.
Whether or not the listener should be automatically started.
This is always true if no buttontype has been defined.
Example
<listener autostart="true" delimitertype="newline" listenport="12345">
<task tasktype="ogscript">if (event.isMessageEvent())
{
var rec = event.getBytesAsString().trim();
var response = '';
for (var i = rec.length - 1; i >= 0; i--)
{
response += rec.charAt(i);
}
this.writeString('REVERSE: ' + response + '\n', false);
}
</task>
</listener>
task
Defines a block of ogScript to be run when an event happens in the system. Tasks inside of label tags are fired when the label is clicked. Tasks inside of button tags are fired when the button is pressed. Tasks inside of listener tags are fired whenever a connection is established or whenever data is received.
The text content of the tag contains the actual ogScript to be executed.
Syntax
<component>
<task tasktype ="task-type" >
ogScript-code
</task>
</component>
DashBoard CustomPanel Development Guide
OGLML Reference • 111
Attributes
Tag
tasktype
Values
*ogscript robot vdcp rosstalk ogparamset timercontrol
Restrictions Description
This attribute tells the editor user interface what type of task is contained in the tag body. Manually-edited tasks should simply use ogscript.
timertask
Defines a block of ogScript to be run when a timer goes off. The timer must be in the same scope as the timertask. The text content of the tag contains the actual ogScript to be executed.
Syntax
<container>
<timer id =”timer-id” />
<container>
<container>
<timertask tasktype ="task-type" timerid =”timer-id” >
ogScript Code
</timertask>
</container>
</container>
</container>
Attributes
Tag
tasktype timerid
Values
*ogscript robot vdcp rosstalk ogparamset timercontrol
String
Restrictions Description
This attribute tells the editor user interface what type of task is contained in the tag body. Manually-edited tasks should simply use ogscript.
Must match the
id attribute of a timer tag accessible in this tasks’s scope.
Defines the ID of a timer to fire this timertask. This allows a timer to be defined at the document root but perform actions on elements defined much deeper in the document structure.
DashBoard CustomPanel Development Guide
include
This tag allows an OGLML document to be assembled from several individual XML files or fragments. The tag provides a URL, which is retrieved and then replaces the tag with the contents of the referenced OGLML document.
Attribute
*src
Values
URL for http, https, or “eo”
Restrictions Description
Points to an OGLML document at the given URL.
Documents are refreshed when a card is re-queried (i.e. either card sends an external object change, or
OGP_RESTART, or user clicks
“refresh”). HTTP fetches use if-modifiedsince header and ETag (as defined in
RFC 2616 section 14.25 and 14.19 respectively)
A DashBoard-specific scheme “eo” can be used to fetch content from an
External Object. Examples would be
“eo://1234” or “eo://0x4D2”). If this format is used, DashBoard will look for the OGLML document referenced by the provided external object (contained within an OGLML Descriptor).
See section on OGLML URLs for more information.
Device Resource Declarations
The following tags are used to declare resources. These tags may be used in a stand-alone XML file (such as a .
ogd or .xml file), or may be embedded within an OGLML document (typically within a <meta> block).
Resource XML File
Data store resources may be backed by an XML file. Below is an outline of the XML file structure:
<?
xml version ="1.1" encoding ="UTF-8"?>
<frame>
<card>
<params>
<param/>
<param/>
. . .
</params>
<statusmenu>
<menu>
<param/>
DashBoard CustomPanel Development Guide
OGLML Reference • 113
<param/>
. . .
</menu>
<menu/>
. . .
</statusmenu>
<configmenu>
<menu>
<param/>
<param/>
. . .
</menu>
<menu/>
. . .
</configmenu>
<menugroup>
<menu>
<param/>
<param/>
. . .
</menu>
<menu/>
. . .
</menugroup>
<menugroup/>
. . .
</card>
<card/>
. . .
</frame>
Resources within the <card> block may also be declared within an OGLML document, and should be located within a
<meta> block.
config
Provides a container for extended configuration key-value pairs for elements related to a parameter. Contents are dependent on other constraints, parameter types or widgets.
Syntax
<param>
<config key ="key">value </config>
<config key ="key">value </config>
. . .
</param>
DashBoard CustomPanel Development Guide
Attributes
Attribute
key
value
Values
String
String
Restrictions Description
Configuration parameter name
Configuration parameter value
Example
The following config object sets attributes of a graph widget:
<param oid ="Fader_Bar" right ="5" widget ="256" >
<config key ="w.time" >
5
</config>
<config key ="w.autoadvance" >
true
</config>
<config key ="w.plotbg" >
#dark
</config>
<config key ="w.plotfg" >
#00FF00
</config>
<config key ="w.grid" >
#panelfg
</config>
<config key ="w.hidelegend" >
true
</config>
<config key ="w.hidey" >
false
</config>
<config key ="w.hidex" >
false
</config>
</param>
constraint
Defines the choice constraint for a parameter. For
INT_CHOICE constraints, the integer value is defined with the key attribute and the text to display is the text content of the tag. For
STRING_CHOICE constraints, each constraint tag contains a value to populate a combo-box drop-down.
The parameter must have a constrainttype of INT16_CHOICE, INT32_CHOICE or
STRING_CHOICE.
Syntax
<constraint key= "choice1-key" >
choice1-value
</constraint>
Attributes
Attribute
key
value
Values
Integer
String
Restrictions
Not required for
STRING_CHOICE constraints
Description
Numeric assignment of current enumerated choice.
Text name for the current enumerated choice
DashBoard CustomPanel Development Guide
OGLML Reference • 115
Examples
The following constraint provides an enumerated choice:
<param constrainttype ="INT_CHOICE" name ="Channel" oid ="0x503" type ="INT16_PARAM" >
<constraint key ="0" >
Channel 01
</constraint>
<constraint key ="1" >
Channel 02
</constraint>
<constraint key ="2" >
Channel 03
</constraint>
<constraint key ="3" >
Channel 04
</constraint>
</param>
The following constraint provides a list of selections for a STRING parameter:
<param constrainttype ="STRING_CHOICE" name ="Name" oid ="0x504" type ="STRING" >
<constraint>
Jeremy Clarkson
</constraint>
<constraint>
James May
</constraint>
<constraint>
Richard Hammond
</constraint>
<constraint>
The Stig
</constraint>
</param>
card
Top-level container for a device within an XML or OGD file. Encapsulates a device within a
.frame file. Note this tag should not be used as a container within an OGLML document.
Syntax
<card autosave ="auto-save" online ="true" slot ="slotno" sourceframe ="frame-node-id" sourceframename ="device-name" sourceid ="card-node-id" status ="status-level" statustext ="status-text" version ="2.0" >
Attributes
Attribute
autosave
Values
true
false
online
true
false
Integer
slot sourceframe
String
sourceframename
String
sourceid status
String
0
1
Restrictions
Not required for
PanelBuilder
Description
If true, DashBoard will automatically save contents of the resources specified in the file from data store periodically.
Sets the device’s online status. Normally should be set to true.
Defines the slot-id for the device.
node-id of the frame or device.
Name of the device. This is the top-level name shown in the DashBoard Tree
The original node-id of the virtual device
(used when saved as the offline configuration of a real device)
Status OK
Status WARN
DashBoard CustomPanel Development Guide
Attribute Values
2
String
Restrictions Description
Status ERROR
Status text for the node. statustext version
String
Default values shown in bold.
Not required for
PanelBuilder
Set to 2.0.
Example
The following example defines a device (openGear card) installed in a frame called “Demo
Frame”, slot 10. The device’s node id is “172.16.7.230:5253(Slot10)SPG-8260”.
<card online ="true" slot ="10" sourceframe ="172.16.7.230:5253" sourceframename ="Demo Frame" sourceid ="172.16.7.230:5253<br>Slot 10<br>SPG-8260" status ="0" statustext ="OK" version ="2.0" >
</card>
frame
Top-level container for a frame within a
.frame file. Note this tag should not be used as a container within an OGLML document. Frame files are created by DashBoard.
Syntax
<frame name ="frame-name" sourceid ="node-id" >
<card/>
<card/>
. . .
</frame>
Attributes
Attribute
Name sourceid
Values
String
String
Restrictions Description
Display name of the frame
The original node-id of the virtual device
(used when saved as the offline configuration of a real device)
menu
Defines the controls to place within a menu tab or menu pop-up. <param> tags within the menu block may override the param’s default attributes for display within this menu.
Synax
<menu menuid ="menu-id" menustate ="state" name ="name" staticid ="static-id" >
<param/>
<param/>
. . .
</menu>
DashBoard CustomPanel Development Guide
OGLML Reference • 117
Attributes
Attribute
menuid menustate name staticid
Values
Integer
0
1
2
String
Integer
Restrictions
Required
Required
Description
Numeric ID for the menu. Menu tabs within a menu group are displayed in numeric order, lowest first. This value may be changed to dynamically re-order menus.
Menu is hidden
Menu is displayed, but params are readonly
Menu is displayed and params are read/write (based upon individual parameter access permissions)
Name of the menu. This name will appear in the menu tab.
Unique numeric identifier for this menu.
This value must be only set once and not changed.
Example
The following example creates a menu called “Network Setup”.
<menu menuid ="257" menustate ="2" name ="Network Setup" staticid ="257" >
<param access ="1" name ="Addressing Mode" oid ="0x0x711" />
<param access ="1" name ="IP Address" oid ="0x712" />
<param access ="1" name ="Subnet Mask" oid ="0x713" />
<param access ="1" name ="Default Gateway" oid ="0x714" />
</menu>
menugroup
Defines a menu group. The menugroup is a container for menus. When a menugroup is displayed, child menus are displayed as tabbed elements within the container.
Syntax
<menugroup menuid ="id" name ="menu-group-name" >
<menu/>
<menu/>
. . .
</menugroup>
DashBoard CustomPanel Development Guide
Attributes
Attribute
menuid
Values
Integer
Restrictions
Required
Description
Numeric ID for the menu group. This value must be only set once and not changed.
menuid=0 corresponds to the openGear status menu
menuid=1 corresponds to the openGear configuration menu
Name of the menu group. name
String
Examples
The following example creates a menu group with two menus:
<menugroup menuid ="0" name ="Status" >
<menu menuid ="0" menustate ="2" name ="Status" staticid ="0" >
<param access ="0" name ="Card Status" oid ="0x201" />
<param access ="0" name ="Reference" oid ="0x204" />
</menu>
<menu menuid ="1" menustate ="2" name ="Product Info" staticid ="1" >
<param access ="0" name ="Product" oid ="0x105" />
<param access ="0" name ="Name" oid ="0x107" />
<param access ="0" name ="Supplier" oid ="0x102" />
<param access ="0" name ="Software Rev" oid ="0x10B" />
</menu>
</menugroup>
statusmenu
Defines the Status Menu group for the default openGear menu layout. This tag behaves in the same manner as the < menugroup> tag when the menuid=0.
Syntax
<statusmenu menuid ="id" name ="menu-group-name" >
<menu/>
<menu/>
. . .
</statusmenu>
Attributes
Attribute
menuid name
Values
Integer
String
Restrictions
Optional. Should be set to 0.
Description
Numeric ID for the menu group. This value must be only set once and not changed. Defaults to 0.
Name of the menu group.
DashBoard CustomPanel Development Guide
OGLML Reference • 119
Example
The following example creates a status menu group with two menus:
<statusmenu menuid ="0" name ="Status" >
<menu menuid ="0" menustate ="2" name ="Status" staticid ="0" >
<param access ="0" name ="Card Status" oid ="0x201" />
<param access ="0" name ="Reference" oid ="0x204" />
</menu>
<menu menuid ="1" menustate ="2" name ="Product Info" staticid ="1" >
<param access ="0" name ="Product" oid ="0x105" />
<param access ="0" name ="Name" oid ="0x107" />
<param access ="0" name ="Supplier" oid ="0x102" />
<param access ="0" name ="Software Rev" oid ="0x10B" />
</menu>
</statusmenu>
configmenu
Defines the Config Menu group for the default openGear menu layout. This tag behaves in the same manner as the < menugroup> tag when the menuid=1.
Syntax
<configmenu menuid ="id" name ="menu-group-name" >
<menu/>
<menu/>
. . .
</configmenu>
Attributes
Attribute
menuid name
Values
Integer
String
Restrictions
Optional. Should be set to 1.
Description
Numeric ID for the menu group. This value must be only set once and not changed. Defaults to 1.
Name of the menu group.
Example
The following example creates a status menu group with 2 menus:
<configmenu menuid ="1" name ="Status" >
<menu menuid ="513" menustate ="2" name ="Network Setup" staticid ="257" >
<param access ="1" name ="Addressing Mode" oid ="0xFE11" />
<param access ="1" name ="IP Address" oid ="0x712" />
<param access ="1" name ="Subnet Mask" oid ="0x713" />
<param access ="1" name ="Default Gateway" oid ="0x714" />
</menu>
DashBoard CustomPanel Development Guide
<menu menuid ="514" menustate ="2" name ="Remote Control Setup" staticid ="258" >
<param access ="1" name ="Protocol" oid ="0x411" />
<param access ="1" name ="Baud Rate" oid ="0x412" />
<param access ="1" name ="Parity" oid ="0x413" />
<param access ="1" name ="Stop Bits" oid ="0x414" />
</menu>
</statusmenu>
params
The parent container for parameters defined within the OGLML document. This tag may only contain <param> tags.
Syntax
<params>
<param
param-attributes
/>
<param
param-attributes
/>
. . .
</params>
Attributes
None.
param
Creates a parameter descriptor, which defines the parameter. Declaration of a param descriptor must be located within a <params> block. Constraints for the param may be included as an attribute (for range constraints), or as child tags (for choice constraints).
Syntax
<param oid ="oid" attributes />
<param oid ="oid" attributes >
<constraint / >
<constraint / >
. . .
<config / >
<config / >
. . .
</param>
Attributes
Attribute
oid
Values
String
Restrictions
Required, except for subparams
Description
The OID of the parameter (can be used to override an existing parameter).
DashBoard CustomPanel Development Guide
OGLML Reference • 121
Attribute
suboid access name widget maxlength precision type constraint constrainttype stateless value config
Values
String
0
1
String
Positive integer
Positive integer
Positive integer
INT16
INT16_ARRAY
INT32
INT32_ARRAY
STRING
STRING_ARRAY
FLOAT32
FLOAT32_ARRAY
Restrictions
Required for subparams
Must be a valid widget hint
Applies only to
String/String
Array parameters
STRUCT
STRUCT_ARRAY
BINARY_VALUE
cvalue
ctype
false
true
varies varies
Value type must be compatible with the specified
type.
Description
If the param declaration is a sub-param within a struct, the OID is specified in the suboid attribute.
Parameter is read-only in DashBoard
Parameter is read-write in DashBoard
Parameter Name
Defines the default widget hint for the
param.
The maximum length of any String element in the parameter.
This field defines the number of digits following the decimal point displayed for printed numbers. It applies mainly to floating point numbers.
Param is 16-bit signed integer.
Param is an array of 16-bit signed integer.
Param is 32-bit signed integer.
Param is an array of 32-bit signed integer.
Param is a string.
Param is an array of strings.
Param is a 32-bit (IEEE single) float.
Param is an array of 32-bit (IEEE single) float.
Param is a struct.
Param is an array of struct.
Param is of unknown type.
See constraint tag for more details.
See constraint tag for more details.
Parameters are saved to backing source
Parameters are not saved
Specifies the initial value of the param.
Arrays may be initialized by separating values with "
;".
Provides additional widget configuration parameters. See config tag for details.
Default values shown in bold.
Example
<param access="1" maxlength="0" name="Message" oid="Message" type="STRING" value="Reverse this message" widget="3"/>
DashBoard CustomPanel Development Guide
param (struct)
Compound parameters may be defined through the use of the STRUCT param type. A struct contains a collection of parameters. Structs may not be nested. Struct must have a
constrainttype of STRUCT. Members of the struct are declared through subparam tags within the value tag.
A struct may also use another param as a template to pre-populate the member sub-param declarations. This is done through the templateoid attribute.
Syntax
<param constrainttype ="STRUCT" oid ="oid" type ="STRUCT"
attributes
>
<value>
<subparam suboid ="sub-oid"
sub-param-attributes
/>
<subparam
. . .
suboid ="sub-oid"
sub-param-attributes
/>
</value>
</param>
Attributes
Attribute
oid
Values
String
Restrictions
Required access name widget type structtype templateoid constrainttype value subparam
0
1
String
Positive integer Must be a valid widget hint
STRUCT
String
String
STRUCT
param
May not be a nested struct param
Description
The OID of the parameter (can be used to override an existing parameter).
Parameter is read-only in DashBoard
Parameter is read-write in DashBoard
Parameter Name
Defines the default widget hint for the
param.
Must be set to STRUCT.
Defines the structure type. Specifies a dependency of a widget upon a global struct parameter with matching
structtype. Currently this type checking is restricted only to PanelBuilder UI; a custom widget will only be available in
PanelBuilder if a parameter exists with matching structtype.
Specifies a template struct parameter to pre-populate the subparams.
Must be set to STRUCT
Container for subparam elements.
Member parameters, declared using the same syntax as a param declaration, with the exception that its oid is specified in the attribute suboid.
Default values shown in
bold.
DashBoard CustomPanel Development Guide
OGLML Reference • 123
Example
The following declares a struct parameter.
<param access ="1" constrainttype ="STRUCT" name ="Clip Info" oid ="clipInfo" type ="STRUCT" widget ="36" >
<value>
<subparam name ="Clip Name" suboid ="ClipName" type ="STRING" value ="Test" />
<subparam name ="Director" suboid ="Director" type ="STRING" value ="Test" />
<subparam name ="Air Date" suboid ="AirDate" type ="STRING" value ="Test" />
<subparam name ="Author" suboid ="Author" type ="STRING" value ="Test" />
</value>
</param>
The following declares an array of struct params, using the previous example as its template. Note that any attributes specified explicitly will override the values provided in the template.
<param access ="1" constrainttype ="STRUCT" name ="Clip List" oid ="clipList" templateoid ="clipInfo" type ="STRUCT_ARRAY" widget ="36" >
<value>
<subparam suboid ="ClipName" value ="Winter is Coming" />
<subparam suboid ="Director" value ="Tim Van Patten" />
<subparam suboid ="AirDate" value ="April 24, 2011" />
<subparam suboid ="Author" value ="David Benoiff & D.B.
Weiss" />
</value>
<value>
<subparam suboid ="ClipName" value ="The Kingsroad" />
<subparam suboid ="Director" value ="Brian Kirk" />
<subparam suboid ="AirDate" value ="April 24, 2011" />
<subparam suboid ="Author" value ="David Benoiff & D.B.
Weiss" />
</value>
<value>
<subparam suboid ="ClipName" value ="Lord Snow" />
<subparam suboid ="Director" value ="Brian Kirk" />
<subparam suboid ="AirDate" value ="May 1, 2011" />
<subparam suboid ="Author" value ="David Benoiff & D.B.
Weiss" />
</value>
</param>
DashBoard CustomPanel Development Guide
Device Resource Tags
The following tags use resources provided by the same device that sent the OGLML document to
DashBoard.
The following tags can be used to incorporate standard openGear UI elements into an OGLML document. For example the typical device page is composed of the following tagged resources.
<menugroup mid="1"/>
<summary/>
<param/>
<menu/>
<buttonbar/>
Figure 77 – Device Resource Tags
Note that the tags described in this section add a control to the UI for manipulating the underlying resource. These must be contained within a UI layout container.
Many of the tags are also used to define the underlying resource in the data store. Declarations may be contained within a <meta> block of an OGLML or stand-alone XML file.
menugroup
This tag is used to incorporate a top-level menu group as a single component. This includes all sub-menus and parameters that would appear in a default-layout OGP menu.
Syntax
<menugroup mid ="id" />
DashBoard CustomPanel Development Guide
OGLML Reference • 125
Attributes
Attribute
mid
Values
integer
Restrictions
Must be a defined top-level menu.
Description
menuid of a defined menu.
0 = Status Menu
1 = Configuration Menu
2 = “Extra” Menu
menu
This tag provides a mechanism to display a standard OGP Menu in two different ways:
• Display the entire menu as a single component
• Create a clickable button to display the menu in a balloon dialog (similar to a tool tip).
Syntax
<menu mid ="menu-id" popup ="popup-flag" oglml ="oglml-flag" tabposition ="position"
GeneralAttributes
/>
Attributes
In addition to General Attributes , the following attributes may be specified to the <
menu> tag:
Attribute
mid popup oglml tabposition
Values
integer true
false
true
false north east
south
west
Restrictions
Must be a defined
OID Menu.
name attribute must also be specified.
How the tabs are rendered within their quadrant is determined by the look and feel
(i.e. whether the tabs fill the available space, are positioned to the left, right, or center of the space, etc.)
Description
The static ID of the OID Menu to draw.
A button with the name attribute as its label is the component. When pressed, the menu will appear in a balloon dialog.
See WIDGET_MENU_POPUP widget hint documentation for more information.
The menu is included as a single component.
If the referenced menu has been overridden by an OGLML page, the
OGLML version of the menu will be used.
The standard OGP menu without any
OGLML will be used.
Specifies the placement of the tabs for any 3 rd
-level submenus.
Default values shown in bold.
DashBoard CustomPanel Development Guide
param
Displays a widget to display and manipulate a param. Must be placed within a layout container tag. If the param is an array, multiple widgets are displayed (one for each element).
Syntax
<param oid ="oid" attributes />
<param oid ="oid" attributes >
<constraint / >
<constraint / >
. . .
<config / >
<config / >
. . .
</param>
Attributes
Attribute
showlabel oid
*mid element widget
Values
true
false
String
Restrictions Description
Display the parameter name as a label beside the parameter elements.
String
List of array indices separated by commas
Must be a defined
OID
Must be the static menu ID of a defined OID
Menu.
All array elements referenced must exist in the parameter value.
Positive integer The value must
defined for the parameter’s type
The OID of the parameter to show.
This is used to determine the user rights for a parameter. The menu with the a
staticid matching the specified mid is treated as the parent menu of the parameter when checking read/write rights and whether it is on a status menu or a configuration menu.
If no
mid is defined, the parameter is always rendered as though it is on a configuration menu with full read/write rights.
By default all elements of an array parameter are returned. This attribute can be used to return a subset of the array. If a list is provided, only the elements at the provided indices are returned (note- you can specify the elements in any order).
This value should either be “0” or should not be provided for a non-array parameter.
By default, the widget hint provided by the parameter will be used. This attribute can be used to override the
parameter’s widget hint with another
one.
DashBoard CustomPanel Development Guide
OGLML Reference • 127
Attribute
expand
Values
true
false
Restrictions
Only applies to radio and toggle button parameters.
Description
Return each radio or toggle button created by a choice constraint as a separate element. constrainttype onchange
INT_CHOICE or eo://external-
object-OID ogScript String
Can only be applied to parameters that already use choice constraints.
Allows a device developer to override the choice constraint defined in the OGP
Parameter Descriptor.
The parameter must either contain the available choices in constriant tags inside of the param tag or an external object URL pointing to an external object that contains an integer choice constraint.
The provided snippet of ogScript is triggered when the parameter value changes. A ParamScriptable object named this is created within the context of the onchange to view and manipulate the param. relative true Parameter is interpreted as a relative parameter within a widget. The widget instance’s baseOID will be prefixed to the param OID to create a fully-qualified
OID.
false
Default values shown in bold.
*mid is optional but its use is strongly recommended for User Rights Management support.
constraint
Overrides the choice constraint for a parameter. For INT_CHOICE constraints, the integer value is defined with the key attribute and the text to display is the text content of the tag. For
STRING_CHOICE constraints, each constraint tag contains a value to populate a combo-box drop-down.
The parameter must have a constrainttype of INT16_CHOICE, INT32_CHOICE or
STRING_CHOICE.
Syntax
<constraint key=
"choice1-key"
>
choice1-value
</constraint>
Attributes
Attribute
key
value
Values
Integer
String
Restrictions
Not required for
STRING_CHOIC
E constraints
Description
Numeric assignment of current enumerated choice.
Text name for the current enumerated choice
DashBoard CustomPanel Development Guide
Examples
The following constraint provides an enumerated choice:
<param constrainttype ="INT_CHOICE" name ="Channel" oid ="0x503" type ="INT16_PARAM" >
<constraint key ="0" >
Channel 01
</constraint>
<constraint key ="1" >
Channel 02
</constraint>
<constraint key ="2" >
Channel 03
</constraint>
<constraint key ="3" >
Channel 04
</constraint>
</param>
The following constraint provides a list of selections for a STRING parameter:
<param constrainttype ="STRING_CHOICE" name ="Name" oid ="0x504" type ="STRING" >
<constraint>
Jeremy Clarkson
</constraint>
<constraint>
James May
</constraint>
<constraint>
Richard Hammond
</constraint>
<constraint>
The Stig
</constraint>
</param>
buttonbar
Creates the button bar containing the “Refresh”, “Upload”, “Reboot”, and “Close” buttons.
Normally this appears at the bottom of a Device Tab. Only a single instance of this tag is permitted per OGLML document.
Syntax
<buttonbar />
Attributes
None.
Example
The following displays the button bar:
<buttonbar/>
Figure 78 - <buttonbar/> tag
DashBoard CustomPanel Development Guide
OGLML Reference • 129
editor
Inserts the editor UI of another device node from the DashBoard Tree into the current container.
The editor tag may insert either the full editor UI or a compact summary.
Syntax
<editor objectid ="object-id" template ="template-style" widgetroot ="root-flag" />
Attributes
Attribute
objectid template widgetroot
Values
String summary
Boolean
Restrictions Description
ID of the device node to insert
Inserts a summary panel for the device.
Everything inside of the editor must be kept together. Individual elements cannot be dragged out to other panels.
Example
The following inserts the full UI for device with id
00.0f.9b.00.00.26(Slot 0)MFC-
8310:
<editor objectid ="00.0f.9b.00.00.26<br>Slot
0<br>MFC-8310" widgetroot ="true" />
The following inserts a summary panel for the device:
<editor objectid ="00.0f.9b.00.00.26<br>Slot
0<br>MFC-8310" template ="summary" widgetroot ="true" />
Figure 79 – Summary Editor
DashBoard CustomPanel Development Guide
summary
Creates the standard card status panel with card name, online state, and overall card status.
Syntax
<summary />
Attributes
None.
Example
The following displays the summary panel for a device:
<summary/>
Figure 80 - <summary/> tag
statuscombo
Display a status icon for a single or multiple items from the DashBoard Tree View. When the status icon is clicked, a list of tree nodes is expanded; these nodes can be then clicked to open the editor for that node.
This is largely intended to be created by dragging/dropping items from the DashBoard Tree View or Advanced Tree View into a PanelBuilder CustomPanel document.
A hierarchy of <treeobject/> elements with the same attributes allows you to create combined status items.
Syntax
<statuscombo
attributes
>
<treeElement name ="node-name" objectid ="node-id" />
<treeElement name ="node-name" objectid ="node-id" />
. . .
</statuscombo>
Attributes
Attribute
objectid name
Values
String
String
Restrictions
Must be the node-ID of a node in
DashBoard tree view
Description
The node-id of the element in the tree to display. If the object has children, they are automatically shown under the node.
The display name of the item.
DashBoard CustomPanel Development Guide
OGLML Reference • 131
Example
The node-id of a node in the Tree View may be obtained by right-clicking the node and selecting
“View Connection Settings”.
Figure 81 – Connection Settings
The following code creates a statuscombo with 2 nodes:
<statuscombo grid ="false" left ="448" name ="Favorite Cards" top ="118" >
<treeElement name ="Slot 0: MFC-8322-N" objectid ="10.1.9.36:5253<br>Slot 0<br>MFC-8322-N" />
<treeElement name ="Slot 5: SRA-8602" objectid ="10.1.9.36:5253<br>Slot 5<br>SRA-8602" />
</statuscombo>
The result appears in DashBoard as:
When clicked, it expands as follows:
Figure 82 – statuscombo
Figure 83 – statuscombo expanded
DashBoard CustomPanel Development Guide
If the specified treenode has child nodes, it will appear as follows:
Figure 84 – statuscombo with child nodes
Macro Expansion
DashBoard includes several pre-defined macros which expand into specific useful information.
The following macros are supported:
Macro
Description
Expands to the node-id of the current frame
Expands to the node-id of the current device or card node
Expands to the node-id of the specified slot within the current frame
Expands to a parameter’s value
Expands to a widget’s id
Expands to a lookup value
Expands to a widget’s baseOID
Expands to the full element id hierarchy
Expands to the path of the current CustomPanel
Expands to the DashBoard installation directory
Expands to the id of the current component
Performs a regular expression expansion
DashBoard CustomPanel Development Guide
OGLML Reference • 133
%frame%
Expands to the node-id of the frame within the current context.
Syntax
%frame%
Example
<label name ="frame node-id is %frame%" />
Figure 85 - %frame% macro
%device%
Expands to the node-id of the current device within the current context.
Syntax
%device%
Example
<label name ="device node-id is %device%" />
Figure 86 - %device% macro
%slot%
Expands to the node-id of the specified slot within the frame in the current context.
Syntax
%slot slot-number%
Parameters
Parameter
slot-number
Values
Integer
Restrictions
Must be a valid slot number within the current frame
Description
Slot number of the device whose
node-
id is to be returned.
DashBoard CustomPanel Development Guide
Example
<label name ="slot 2 node-id is %slot 2%" />
Figure 87 - %slot% macro
%value%
Expands to the value of a specified parameter.
Syntax
%value ['param-oid'][element]%
Parameters
Parameter
param-oid
Values
String
Restrictions
element
Integer
Description
The OID of the parameter whose value is returned
The array index to return. For non-array parameters this must be set to 0.
Example
The following displays the value of a parameter:
<label name ="the value of myParam is %value['myParam'][0]%" />
The following example utilizes the %value% macro to allow the value of one parameter to specify which parameter to process. The parameter OIDName specifies the OID of the parameter which is displayed in the line below. Note that when the parameter OIDName is changed, it is necessary to manually reload the elements which display the results ( label1 and label2), as the %value% macro is expanded only when the control is rendered.
<params>
<param name ="OID Name" oid ="OIDName" type ="STRING" value ="testOID2" />
<param name ="test OID1" oid ="testOID1" type ="STRING" value ="Fred" />
<param name ="test OID2" oid ="testOID2" type ="STRING" value ="George" />
</params>
<abs>
<param left ="382" oid ="params.OIDName" widget ="3" width ="243">
<task tasktype ="onchange" >
ogscript.reload ("label1");
ogscript.reload ("label2");
</task>
</param>
DashBoard CustomPanel Development Guide
OGLML Reference • 135
<label id ="label1" left ="382" name ="The value of
%value['OIDName'][0]% is"
/>
<param id ="label2" left ="575" oid ="%value['OIDName'][0]%" widget ="1" />
</abs>
Figure 88 - %value% macro
%widget%
Expands to the id of widget within the current context.
Syntax
%widget%
Example
If used within a widget, the following displays the widget’s ID:
<label name ="the value of myParam is %widget%" />
%const%
Expands to the value of a lookup. The lookup must have a specified id.
Syntax
%const['id']['key']%
Parameters
Parameter
id
Values
String key String
Restrictions
Must be an id defined in a
<lookup> tag
Must be a valid key within the specified lookup.
Description
ID of the lookup tag.
Key within the lookup tag whose value will be returned.
Example
Given the following lookup:
<lookup id ="family" scope ="private" >
<entry key ="father">Homer Simpson </entry>
<entry key ="son">Bart Simpson </entry>
<entry key ="mother">Marge Bouvier-Simpson </entry>
<entry key ="daughter">Lisa </entry>
<entry key ="baby">Maggie </entry>
</lookup>
DashBoard CustomPanel Development Guide
The following code will display the label “The son is Bart Simpson”.
<label "The son is %const['family']['son']%" />
%baseoid%
Expands to the value of the baseOID attribute of the current widget.
Syntax
%baseoid%
Example
If you have a widget with a baseoid of params.audio.channels.1 with parameters for signal presence, EQ, etc., you could attach change handlers to them as follows:
<ogscript handles=”onchange” oid=”%baseoid%.eq” element=”0”> ogscript.debug(‘EQ has changed for %baseoid%:‘ + this.getValue());
</ogscript>
%fully-qualified-id%
Expands to the fully-qualified id of the current context. If the current context is nested within other contexts, the hierarchy is expressed, separated by “ .”. Note that only containers with a specified id are included in the expansion.
Syntax
%fully-qualified-id%
Example
<abs id ="abs1" >
<abs>
<abs id ="abs2" >
<label "The fully qualified ID is %fully-qualifiedid%"/ >
</abs>
</abs>
</abs>
Figure 89 - %fully-qualified-id% macro
DashBoard CustomPanel Development Guide
OGLML Reference • 137
%panel-path%
Expands to the folder path which contains the current OGLML document.
Syntax
%panel-path%
Example
<label name ="panel path is %panel-path%" />
Figure 90 - %panel-path% macro
%app-path%
Expands to the folder path which the current instance of DashBoard is installed.
Syntax
%app-path%
Example
<label name ="DashBoard is installed in %app-path%" />
Figure 91 - %app-path% macro
%id%
Expands to the id of the current context.
Syntax
%id%
Example
<label height="62" left="0" name="Click to see my context's ID" style="txt-align:center;" top="0" width="291">
<task tasktype="ogscript">ogscript.debug('My Context\'s ID is
"%id%"');</task>
</label>
DashBoard CustomPanel Development Guide
%eval[ogscript]%
Evaluates the ogscript and replace the %eval[ogscript]% with the value returned by the script.
Syntax
%eval [ogscript]%
Example
<label height="62" left="0" name="%eval[var text = ''; for (var i = 0; i < 10; i++){text += i + ' ';} text.trim();]%" style="txt-align:center;" top="0" width="291"/>
DashBoard CustomPanel Development Guide
OGLML Reference • 139
ogScript Reference
About ogScript
Ross Video ogScript is a programming language developed by Ross Video to interact with Dashboardenabled devices.
It also enables you to add functionality and logic to custom panels you create in DashBoard.
Ross Video ogScript uses JavaScript functions, syntax, and primitive object types. To enable CustomPanel developers to interact with panels and devices, ogScript adds some new global objects to JavaScript.
Most JavaScript works in ogScript scripts, although you might run across an occasional item that does not work.
For information about ogScript objects and functions, refer to the sections in this guide. For information about JavaScript commands and syntax, search for “JavaScript Reference” on the World Wide Web.
This reference guide contains information about ogScript objects and functions. It includes the following major sections:
•
•
•
ParamScriptable Object on page 199
•
•
•
•
The information about ogScript contained in this reference guide applies to the following DashBoard version or greater:
Version 7.0
To view your current DashBoard version, select About DashBoard from the Help menu in DashBoard.
JavaScript
Ross Video ogScript is a programming language developed by Ross Video to interact with Dashboardenabled devices. It uses JavaScript functions, syntax, and primitive object types. To enable
CustomPanel developers to interact with panels and devices, ogScript adds some new global objects to
JavaScript. Most JavaScript works in ogScript scripts, although you might run across an occasional item that does not work.
For information about ogScript objects and functions, refer to the sections in this guide. For information about JavaScript commands and syntax, search for “JavaScript Reference” on the World Wide Web.
DashBoard CustomPanel Development Guide
Commonly Used Functions
Ross Video recommends that you first learn the following commonly used functions:
Ogscript
•
•
params
•
•
Functions Set in the User Interface
Functions in the following objects are typically set through a user interface:
•
•
•
•
ogscript Object
In ogScript, use the ogscript object to access a library of general-purpose functions. To call a generalpurpose function, use: ogscript.function name(parameters);
For example: ogscript.debug ('This is a message');
The following table lists the functions of the ogscript object. Detailed descriptions appear after the table.
If you are reading this document on-screen, click a function name in the table to view its description.
Function
addRemoteTrigger appendXML asyncExec
Parameters
String [Trigger]
String [Function]
String [Container ID]
String [XML snippet] function
Returns
Returns an object that contains one function named close. When executed, close removes the function.
N/A
N/A
N/A
Description
Allows remote execution of a script inside of a CustomPanel through the
RossTalk GPI command.
Function can be removed by calling
close on the object returned.
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.
Executes a function outside of the
UI current thread.
Sends a file to an FTP server. post port username password
DashBoard CustomPanel Development Guide
Function
createByteArray createFileInput
Parameters
destPath destName binary sourceFilePath callback host port username password srcPath srcName binary destFilePath or null callback
String [URL]
String [HTTP Post Data]
Function [Callback
Function]
Boolean [include response]
Timer ID
Returns
N/A
N/A
N/A byte array src offset length length
String [File path]
String [File path]
Boolean
[appendToExistingfile]
N/A
messageBytes
String [Message]
String [trigger]
String [state]
Boolean [global]
DashBoard CustomPanel Development Guide
Description
Retrieves a file from FTP server.
Send an asynchronous post to the given URL.
Cancel, stop and clean-up, a timer with the given ID.
Creates a full or partial copy of a byte array. an empty byte array
FileInputParser (like
MessageParser but with getSize(), close(), and isClosed()
FileOutputBuilder, which is same as
MessageBuilder with added functions for clear()
(overwrite file), close(), getSize(), flush(), and isClosed()
N/A
Creates an empty byte array of a specified size.
Access a file as a byte array with the same capabilities as
MessageParser to read raw bytes
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.
Creates a message builder, which enables you to construct a message.
Returns a
MessageBuilder object used to build byte arrays
(generally for creating network messages).
Returns a MessageParser object (generally used to parse the various pieces of messages received over the network).
N/A
Creates a message parser, which enables you to parse a message.
Write a string to the openGear
Debug Information View.
Sends Trigger GPI string [trigger] to execute component task lists.
Sends optional [state] data string,
Function
getAllById getAttribute getBuild
Parameters
String [Object ID]
String [Attribute ID]
N/A
String [Object ID]
getIncludeById getListenerById
N/A
String [Include ID]
ID
String [File Path]
String [Key]
String [ID]
String [Lookup ID]
String [Key]
Returns
Object []
Object
Description
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.
Get all Objects accessible in the current context that have the associated ID.
Get an attribute registered in the context with the given ID.
Gets the version of DashBoard running the panel.
DashBoard version number (same value that appears in Help>About
DashBoard)
Component []
String
IncludeReloadableContai ner 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.
Returns the time the specified file was last modified, in Unix Epoch time (also known as
POSIX time), as a LONG value.
String
JAVA point object with point.x and point.y available.
String
Get all Java Swing components accessible in the current context that have the associated ID.
Returns the username of the current DashBoard user.
Returns the first include with the given ID.
Starts or stops a listener. Can also check whether a listener is started.
Retrieves the time the specified file was last modified.
Retrieves stored object
Retrieves the horizontal (x) and vertical (y) position of the object, in pixels.
Get a string defined in the lookup table with the specified lookup ID.
DashBoard CustomPanel Development Guide
Function
Parameters
String [Scope Name]
String [Attribute ID]
String [ID]
String [Key]
N/A
String [ID]
String [Timer ID]
Boolean [Repeat]
Long [Delay]
Long [Repeat Rate]
Function [Task]
String [Timer ID]
String
String [Key]
String [Value]
String [LookupID]
String [Key]
String [Value]
String [key]
String [value]
String [ID]
String [ID]
String [Name]
String [ID]
Integer [x position]
Integer [y position]
String [ID]
Integer [percent x]
Integer [percent y]
DashBoard CustomPanel Development Guide
Returns
Object
Description
Get an attribute in the named scope that has the given ID. Scopes are often internally defined by
DashBoard.
Dimension object with d.width and d.height available
String
Retrieves the width and height of the specified panel object.
ContextTimerManager
N/A
N/A
Get a string defined in the global lookup table.
Get the timer manager for the context to access timers and perform operations on selected timers.
This function includes several methods.
Hide the popup with the specified
ID.
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.
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. org.w3c.dom.Document Parse and return an XML document using the org.w3c.dom.Document
API.
N/A Defines a stored object.
N/A Add or replace a string in a private lookup table.
N/A
Null, if null is provided as the ID.
N/A
N/A
Add or replace a string in the global lookup table.
Rebuild the UI element with the given ID.
If no ID is provided, rebuilds entire document.
Modify the text for a tab name, button, or label with the specified
ID.
Moves object to specified XY pixel location
N/A Moves object to the specified location, as percentage of the container width or height.
Center x and center y, when true,
Function
Parameters
Boolean [center x]
Boolean [center y]
String [ID]
String [XPath]
XML Document or
XML Element path data overwrite
NodeList
Returns true, if data is written successfully; otherwise false.
N/A String [Host]
Integer [Port]
Byte[] [Data]
String [Host]
Integer [Port]
String [Data]
String [ID]
Boolean [top]
Boolean [left]
Boolean [bottom]
Boolean [right]
String [ID]
String [width]
String [height]
String [ID]
String [Style]
N/A
N/A
N/A
N/A
String [ID]
String [new XML Content]
N/A
String [ID]
String [ID]
File [Upload File]
Returns
N/A
N/A
N/A
N/A
Description
center the object at the location horizontally (x only), vertically (y only), or both (x and y).
Open a popup with the specified ID, or bring the tab with the specified ID to the foreground.
Execute the given XPath command on the given Document or Element and return the results as a
NodeList.
Saves data to a file. This function is typically used to save a byte array, string, or XML document to a file.
Send the given Data bytes to the provided Host/Port through UDP.
Convert the given Data string to
UTF-8 bytes and send them to the provided Host/Port through UDP.
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.
Resizes a panel object to the specified size.
Valid only in <abs/> containers.
Set Style parameters for the component with the given ID if it exists.
Dynamically generates UI components through ogscript.
Replaces the contents of an element with a string of XML code.
Displays the object below all others in the same container. Objects are layered. If they overlap, higher layers are drawn over lower layers.
Displays the object above all others in the same container. Objects are layered. If they overlap, higher layers are drawn over lower layers.
Open the File Upload dialog with the specified file.
DashBoard CustomPanel Development Guide
addRemoteTrigger
Allows remote execution of a script inside of a CustomPanel through the RossTalk GPI command. The function can be removed by calling close on the object returned.
Syntax
ogscript.addRemoteTrigger (trigger, function);
Parameters
Parameter
Trigger
Function
Type
String
String
Required
Yes
Yes
Description
String that triggers the specified function to execute.
The function to execute, including its parameters (if any).
Returns
Returns an object that contains one function named
close
. When executed,
close
removes the function.
Example
Coming soon.
appendXML
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.
The appendXML function is supported within the <abs> tag only.
Syntax
ogscript.appendXML (container ID, XML snippet);
Parameters
Parameter
container ID
XML snippet
Type
String
String (XML object)
Required
Yes
Yes
Description
ID of the container to append to. Valid only in <abs/> containers.
XML code to append
Returns
N/A
Example
Coming Soon.
asyncExec
Executes a function outside of the UI current thread.
This is especially useful for operations that take time to complete. You can use
asyncExec
to run such operations while continuing to execute the rest of your tasks.
DashBoard CustomPanel Development Guide
Syntax
ogscript.asyncExec (function);
Parameters
Parameter
function
Type
Function reference
Required
Yes
Returns
N/A
Example
Coming soon.
Description
Reference to the function to be run.
asyncFTP
Sends a file to an FTP server. If a callback is provided,
asyncFTP
calls it when the operation is complete.
Note: As the file is transferred, a progress attribute is updated. You can add an ogscipt handler to monitor changes to the attribute to show progress.
Syntax
ogscript.asyncFTP (host, port, username, password, destPath, destName, binary, sourceFilePath, callback);
Parameters
Parameter
host
Type
String
Required
Yes port username password destPath destName binary sourceFilePath callback
Integer
String
String
String
String
Boolean
String function reference
Yes
Yes
Yes
No
No
Yes
Yes
No
Description
The host name of the destination computer.
The port number to which the data is to be sent.
The username required to log onto the destination computer.
The password required to log onto the destination computer.
The directory path where the data is to be saved on the destination computer.
The name of the destination file.
Can be used to rename the existing file.
If a file with the same name exists in the destination path, that file is overwritten.
Specifies the transfer mode. When true, binary transfer is used.
When false, ASCII transfer is used.
The directory path to the source file. The path can be absolute or relative.
The callback is called when the operation is complete, whether or not the operation is successful.
Returns
N/A
DashBoard CustomPanel Development Guide
Example 1
The following example is a task. It uses variable to populate the parameters of the
asyncFTP
function. It also includes a callback to indicate success or failure of the transfer.
<task tasktype="ogscript">function callback(success, sourceFilePath, exception)
{ if (success)
{
} ogscript.rename('label.bytes', 'SUCCESS!'); else
{
} ogscript.rename('label.bytes', 'FAIL!');
} ogscript.rename('label.bytes', 'TRYING TO SEND FILE'); var host = params.getStrValue('params.host', 0); var port = params.getValue('params.port', 0); var user = params.getStrValue('params.username', 0); var password = params.getStrValue('params.password', 0); var file
= params.getStrValue('params.file', 0); var destPath = params.getStrValue('params.destpath', 0); var destFileNameOverride = null; var isBinary = true; ogscript.asyncFTP(host, port, user, password, destPath, destFileNameOverride, isBinary, file, callback); ogscript.rename('label.bytes', 'Waiting...');
</task>
Example 2
The following is an example of an ogscript handler for monitoring and reporting the progress of the transfer.
<ogscript attribute="com.rossvideo.ftp.event" handles="attributechange"> var progressEvent = event.getNewValue(); if (progressEvent == null)
{
} ogscript.debug('No progress'); else
{
} ogscript.rename('label.bytes',
(progressEvent.getTotalBytesTransferred() / 1024) + 'kb');
</ogscript>
DashBoard CustomPanel Development Guide
asyncFTPGet
Retrieves a file from FTP server.
Syntax
ogscript.asyncFTPGet (host, port, username, password, srcPath, srcName, binary, destFilePath or null, callback);
Parameters
Parameter
host
Type
String
Required
Yes port username password srcPath srcName binary callback
Integer
String
String
String
String
Boolean destFilePath or null String function reference
Yes
Yes
Yes
No
Yes
Yes
No
No
Description
The host name of the source computer, from which the file is to be retrieved
The port number required to access the source computer.
The username required to log onto the source computer.
The password required to log onto the source computer.
The directory path where the source file is located.
The name of the file to be retrieved.
Specifies the transfer mode. When true, binary transfer is used.
When false, ASCII transfer is used.
The directory path where the file is to be saved on the local computer.
If null, the file is saved in the same directory as the panel.
The callback is called when the operation is complete, whether or not the operation is successful.
Returns
N/A
Example
Coming soon.
asyncPost
Send an asynchronous post to the given URL. Call the given function when the post has completed. The data retrieved from the HTTP Post is passed as a string as the first variable in the method.
If the MIME type of the HTTP response is image or binary, the result will be a byte array containing what is fetched.
Syntax
ogscript.asyncPost (URL, HTTP Post Data, Callback Function, Include
Response);
DashBoard CustomPanel Development Guide
Parameters
Parameter
URL
Type
String
HTTP Post Data String
Callback Function Function
Include Response Boolean
Required
Yes
Yes
Yes
No
Description
URL to send a post.
Post to send to the specified URL.
Function to call after the post completes.
If true, result is a JSON Object
{
responseCode = HTTP RESONSE
CODE,
contentType = HTTP MIME TYPE
url = URL Requested
bytes= BYTES RECEIVED
}
Otherwise, it is content fetched over HTTP parsed as though it’s a string (as before).
Returns
N/A
Example
Coming soon.
cancelTimer
Cancel, stop and clean up, a timer with the given ID.
Note: For information about creating a timer function, see installTimer on page 168.
Syntax
ogscript.cancelTimer (Timer ID);
Parameters
Parameter
Timer ID
Type
String
Required
Yes
Description
ID of the timer to stop and clean up.
Returns
N/A
Example
//Stop the timer that was created with installTimer ogscript.cancelTimer('myTimer');
copyByteArray
Creates a full or partial copy of a byte array.
Syntax
ogscript.copyByteArray(src, offset, length)
DashBoard CustomPanel Development Guide
Parameters
Parameter
src offset length
Type
byte array
Integer
Integer
Required
Yes
Yes
Yes
Description
The byte array to be copied.
Index of the first byte to be copied. Use 0 for the start of the array.
The number of bytes to copy.
Tip: To copy the entire array, use src.length.
Returns
byte array
Example 1
In the following example, the contents of a byte array named
srcArray
are copied into a variable named
myCopy. var myCopy=ogscript.copyByteArray (srcArray,0,srcArray.length);
Example 2
In the following example, the 20 bytes of a byte array named
srcArray
, starting at byte
4
, are copied into a variable named myCopy. var myCopy=ogscript.copyByteArray (srcArray,4,20);
createByteArray
Creates an empty byte array of a specified size.
Syntax
ogscript.createByteArray (length);
Parameters
Parameter
length
Type
Integer
Required
Yes
Description
The size of the new array, in bytes.
Returns
An empty byte array.
Example
var myNewByteArray = ogscript.createByteArray (12);
createFileInput
Accesses a file as a byte array with the same capabilities as
MessageParser
, to read raw bytes. See also
createMessageParser on page 154.
Syntax
ogscript.createFileInput (File path);
DashBoard CustomPanel Development Guide
Parameters
Parameter
File path
Type
String
Required
Yes
Description
Path of the file to open (can be relative to the panel)
Returns
FileInputParser (like MessageParser but with getSize(), close(), and isClosed().
Example
Coming Soon.
createFileOutput
Creates a new file or appends 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.
Similar to MessageBuilder (see createMessageBuilder on page 153).
Syntax
ogscript.createFileOutput (File path, appendToExistingfile);
Parameters
Parameter
File path
Type
String appendToExistingfile Boolean
Required
Yes
Yes
Description
File path of the file to be created or appended.
When true, data is appended to existing file.
When false, a new file is created.
Returns
FileOutputBuilder
, which is same as
MessageBuilder
file),
close()
,
getSize()
,
flush()
, and
isClosed()
. with added functions for
clear()
(overwrite
Example
Coming soon.
createMessageBuilder
Creates a message builder, which enables you to construct a message. The message is created as a byte array, can contain multiple data types.
Syntax
ogscript.createMessageBuilder ();
Parameters
N/A
Returns
Returns a MessageBuilder object used to build byte arrays (generally for creating network messages).
DashBoard CustomPanel Development Guide
Example
In the following example, a variable named myMessage is created to contain message content created by a message builder. Then data of various data types are added to the message. The variable messageArray is defined to contain the message content as a byte array.
Tip: You can use the createMessageParser function to parse messages.
var myMessage = ogscript.createMessageBuilder(); myMessage.writeBoolean(true); myMessage.writeByte(255); myMessage.writeByte(255); myMessage.writeShort(65535); myMessage.writeShort(65535); myMessage.writeChar('a'); myMessage.writeInt(65536); myMessage.writeLong(4294967296); myMessage.writeFloat(0.000001); myMessage.writeDouble(0.000002); myMessage.writeString('abcd'); myMessage.writeUTF('Hello World'); //includes 2-byte length count var messageArray = myMessage.toByteArray();
createMessageParser
Creates a message parser, which enables you to parse a message.
Syntax
ogscript.createMessageParser (messageBytes);
Parameters
Parameter
messageBytes
Type
byte array
Required
Yes
Description
The source byte array.
Returns
Returns a MessageParser object (generally used to parse the various pieces of messages received over the network).
Example
In the following example, a variable named messageArray contains several pieces of data of various data types to be extracted by a message parser. A variable named parsedMessage is created to contain the extracted message content. Each element of the array is parsed and sent to the debug utility.
Tip: You can use the createMessageBuilder function to create messages.
var parsedMessage = ogscript.createMessageParser(messageArray); ogscript.debug(parsedMessage.readBoolean()); ogscript.debug(parsedMessage.readByte()); ogscript.debug(parsedMessage.readUnsignedByte()); ogscript.debug(parsedMessage.readShort()); ogscript.debug(parsedMessage.readUnsignedShort()); ogscript.debug(parsedMessage.readChar()); ogscript.debug(parsedMessage.readInt()); ogscript.debug(parsedMessage.readLong()); ogscript.debug(parsedMessage.readFloat()); ogscript.debug(parsedMessage.readDouble()); ogscript.debug(parsedMessage.readString(4)); ogscript.debug(parsedMessage.readUTF());</task>
DashBoard CustomPanel Development Guide
debug
Write a string to the openGear Debug Information view.
The openGear Debug Information view must be open to view debug messages. To open the openGear
Debug Information view, select openGear Debug Information from the Views menu in DashBoard.
Syntax
ogscript.debug (Message);
Parameters
Parameter
Message
Type
String
Required
Yes
Description
Message to display in the openGear
Debug Information View.
Returns
N/A
Example 1
ogscript.debug ('This is a message');
Example 2
var data = params.getValue(0x12,0); ogscript.debug ('Parameter 0x12 (score): ' + data);
Example 3
ogscript.debug ('Parameter 0x12 (score): ' + params.getValue(0x12,0));
fireGPI
Sends a Trigger GPI message to panels. When buttons, labels, and displayed parameters that have a matching GPI Trigger receive the message, their task lists are executed.
Tip: This function can be used for inter-panel communication, by triggering globally.
Syntax
ogscript.fireGPI (Trigger), (State), (Global);
Parameters
Parameter
Trigger
State
Global
Type
String
String
Boolean
Required
Yes
No
Yes
Description
GPI Trigger message.
Sends optional data string, which can be read by the script.
When true, applies to all open panels.
When false, applies only the panel initiating the trigger.
Returns
N/A
DashBoard CustomPanel Development Guide
Example
In this example, the GPI trigger message 'StartClock' and the state data 'ResetClock' are sent to all open panels. ogscript.fireGPI ('StartClock','ResetClock',true);
getAllById
Get all Objects accessible in the current context that have the associated ID.
Syntax
ogscript.getAllById (Object ID);
Parameters
Parameter
Object ID
Type
String
Required
Yes
Description
ID of the objects in the current context to get.
Returns
Object []
Example
Coming soon.
getAttribute
Get an attribute registered in the context with the given ID.
Syntax
ogscript.getAttribute (Attribute ID);
Parameters
Parameter
Attribute ID
Type
String
Required
Yes
Description
ID from which to get a registered in context attribute.
Returns
Object
Example
Coming soon.
getBuild
Returns the DashBoard version number. This is the same version number you see in DashBoard if you click About DashBoard on the Help menu.
Syntax
ogscript.getBuild ();
DashBoard CustomPanel Development Guide
Parameters
N/A
Returns
DashBoard version number, similar to the following:
Version 7.0.0I 2015-06-12 T09:54
getComponentsById
Get all Java Swing components accessible in the current context that have the associated ID.
Syntax
ogscript.getComponentsById (Object ID);
Parameters
Parameter
Object ID
Type
String
Required
Yes
Description
ID from which to get all Java Swing components accessible in the current context.
Returns
Component []
Example
Coming soon.
getCurrentUser
Returns the username of the current DashBoard user.
When a User Rights Management server is present, this function returns the username of the user signed-in to DashBoard.
When no User Rights Management Server is found, this function returns the computer account name.
Syntax
ogscript.getCurrentUser ( );
Parameters
N/A
Returns
String
Example
This example uses the getCurrentUser function to read the user name, and then uses the rename function
to rename a label. For more information about the rename function, see rename on page 173.
The label is defined in the .grid file as follows:
<label height="49" id="Welcome Label" left="136" name="Welcome" style="txt-align:west;" top="275" width="188"/>
DashBoard CustomPanel Development Guide
The script to read the user name and then rename the label is as follows:
//read the login user name var loginName = ogscript.getCurrentUser();
//display the user name in the Welcome label var message = 'Welcome
' + loginName; ogscript.rename('Welcome Label',message);
getIncludeById
Returns the first include with the given ID. The include must have been created using the <include> tag.
Syntax
ogscript.getIncludeById (Include ID);
Parameters
Parameter
Include ID
Type
String
Required
Yes
Description
ID of the include to find.
Returns
IncludeReloadableContainer
Example
Coming soon.
getListenerById
Starts or stops a listener. Can also check whether a listener is started.
Syntax
ogscript.getListenerById (ID);
Parameters
Parameter
ID
Type
String
Required
Yes
Description
ID of the listener.
Returns
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.
Example
var myListener = ogscript.getListenerById (myId); myListener.start
(); myListener.stop (); myListener.isStarted ();
DashBoard CustomPanel Development Guide
getModificationDate
Retrieves the time the specified file was last modified.
Syntax
ogscript.getModificationDate (file path);
Parameters
Parameter
File path
Type
String
Required
Yes
Description
Path to the file.
Returns
Returns the time the specified file was last modified, in Unix Epoch time (also known as POSIX time), as a LONG value.
Example
Coming soon.
getObject
You can create an object and reference it in other parts of the code. Some possible uses include:
• Storing parsed XML data in an object so you don’t have to re-parse it.
• Storing the results of an async HTTP post so you don’t have to re-fetch it.
• Storing connection code so you cna reference it wherever your code needs to establish that connection.
The getObject function works in conjunction with the putObject function. The putObject function defines the object. The getObject function references the object. The scope of a defined object is global, so you can reference it from anywhere in your panel code.
For information about the putObject function, see putObject on page 170.
Syntax
ogscript.getObject(Key);
Parameters
Parameter
Key
Type
String
Required
Yes
Description
The name used to reference what is being stored.
Returns
String.
DashBoard CustomPanel Development Guide
Example
The following example parses and stores data from an XML file in a variable so it can be used globally without the need to re-parse the XML data each time you want to use it.
It defines a function named loadTheXML, which uses the parseXML function to retrieve XML data from a file and load it into a variable named myObject. It then uses the putObject function to copy the data into a variable named myXML. The readTheXML function loads the data into a variable named otherObject. function loadTheXML()
{ var myObject = ogscript.parseXML('file:/c:/mydocument.xml'); ogscript.putObject('myXML',myObject);
} function readTheXML()
{ var otherObject = ogscript.getObject('myXML');
// Do anything you want with the data, now contained in the otherObject variable.
}
getPosition
Retrieves the horizontal (x) and vertical (y) position of a panel object, in pixels.
Syntax
ogscript.getPosition (ID);
Parameters
Parameter
ID
Type
String
Required
Yes
Description
The ID of the panel object.
Returns
JAVA point object containing public variables x and y, populated with values for the horizontal (y) and vertical (y) position of the object, in pixels.
Example
The following example draws a label that can be resized and repositioned. When the user drags the middle of the label, it moves. When the user drags the bottom right corner of the label, the label is resized.
<abs bottom="0" contexttype="opengear" left="0" right="0" top="0">
<meta>
<ogscript handles="onmousedown" targetid="move-label">var size = ogscript.getSize('move-label'); if (event.getX() < size.width - 10 && event.y < size.height - 10)
{ ogscript.putObject('mode', 'move'); ogscript.putObject('position', ogscript.getPosition('movelabel')); ogscript.putObject('offsetX', event.x); ogscript.putObject('offsetY', event.y);
}
DashBoard CustomPanel Development Guide
else
{ ogscript.putObject('mode', 'size');
}
</ogscript>
<ogscript handles="ondrag" targetid="move-label"> if (ogscript.getObject('mode') == 'size')
{ ogscript.setSize('move-label', event.getX(), event.getY());
} else if (ogscript.getObject('mode') == 'move')
{ var origin = ogscript.getObject('position'); var offsetX = ogscript.getObject('offsetX'); var offsetY = ogscript.getObject('offsetY'); ogscript.reposition('move-label', origin.x + event.x - offsetX, origin.y + event.y - offsetY); ogscript.putObject('position', ogscript.getPosition('movelabel'));
}
</ogscript>
</meta>
<label height="116" id="move-label" left="27" style="bdr:etched;bg#FF0000" top="38" width="215"/>
</abs>
getPrivateString
Get a string defined in a private lookup table that matches the specified lookup ID.
Note: Use the getPrivateString function if the lookup table has an ID. If the lookup table has no ID, use
Syntax
ogscript.getPrivateString (Lookup ID, Key);
Parameters
Parameter
Lookup ID
Key
Type
String
String
Required
Yes
Yes
Description
ID of the string to find in the specified lookup table.
Private lookup table in which to find the specified string.
Returns
String
DashBoard CustomPanel Development Guide
Example
This example uses the getPrivateString function to read an IP address stored in a lookup table. The lookup table is defined at the beginning of the .grid file, and can be accessed by any script.
The lookup table definition for this example is as follows:
<lookup id="hosts">
<entry key="XPression.host">10.0.2.210</entry>
<entry key="XPression.port">7788</entry>
</lookup>
The script to read an entry from the lookup table is as follows:
//Get the IP Address associated with entry key XPression.host var host = ogscript.getPrivateString('hosts',' XPression.host ');
getScopedAttribute
Get an attribute in the named scope that has the given ID. Scopes are often internally defined by
DashBoard.
Syntax
ogscript.getScopedAttribute (Scope Name, Attribute ID);
Parameters
Parameter
Scope Name
Attribute ID
Type
String
String
Required
Yes
Yes
Description
Name of the scope in which to get and attribute.
ID of the attribute to get in the named scope.
Returns
Object
Example
Coming soon.
getSize
Retrieves the width and height of the specified panel object, in pixels.
Syntax
ogscript.getSize (ID);
Parameters
Parameter
ID
Type
String
Required
Yes
Description
ID of the panel object.
Returns
Dimension object with d.width and d.height available.
DashBoard CustomPanel Development Guide
Example
The following example draws a label that can be resized and repositioned. When the user drags the middle of the label, it moves. When the user drags the bottom right corner of the label, the label is resized.
<abs bottom="0" contexttype="opengear" left="0" right="0" top="0">
<meta>
<ogscript handles="onmousedown" targetid="move-label">var size = ogscript.getSize('move-label'); if (event.getX() < size.width - 10 && event.y < size.height - 10)
{ ogscript.putObject('mode', 'move'); ogscript.putObject('position', ogscript.getPosition('movelabel')); ogscript.putObject('offsetX', event.x); ogscript.putObject('offsetY', event.y);
} else
{ ogscript.putObject('mode', 'size');
}
</ogscript>
<ogscript handles="ondrag" targetid="move-label"> if (ogscript.getObject('mode') == 'size')
{ ogscript.setSize('move-label', event.getX(), event.getY());
} else if (ogscript.getObject('mode') == 'move')
{ var origin = ogscript.getObject('position'); var offsetX = ogscript.getObject('offsetX'); var offsetY = ogscript.getObject('offsetY'); ogscript.reposition('move-label', origin.x + event.x - offsetX, origin.y + event.y - offsetY); ogscript.putObject('position', ogscript.getPosition('movelabel'));
}
</ogscript>
</meta>
<label height="116" id="move-label" left="27" style="bdr:etched;bg#FF0000" top="38" width="215"/>
</abs>
getString
Get a string defined in the global lookup table.
Note: Use the getString function if the lookup table has no ID. If the lookup table has an ID, use the getPrivateString function. For more information about the getPrivateString function, see
Syntax
ogscript.getString (Key);
DashBoard CustomPanel Development Guide
Parameters
Parameter
Key
Type
String
Required
Yes
Description
Private lookup table from which to get string.
Returns
Object
Example
This example uses the getString function to read an IP address stored in a lookup table. The lookup table definition for this example is as follows:
<lookup>
<entry key="Tom">television</entry>
</lookup>
The script to read an entry from the lookup table is as follows:
//Get the string associated with entry key Tom ogscript.getString('Tom');
getTimerManager
Get the timer manager for the context to access timers and perform operations on selected timers.
Syntax
ogscript.getTimerManager ( );
Parameters
N/A
Methods
The getTimerManager function is an object that has several methods. The following methods can be run on an existing timer. A timer can be created using the installTimer function or using the graphical
editor. For more information about the installTimer function, see installTimer on page 168.
Method
isRunning() startTimer(Boolean reset) stopTimer(Boolean reset) resetTimer() setStart(Long valueInMilliseconds)
Parameter
Required
N/A
Yes true or false
Yes true or false
N/A
Yes
Milliseconds
Description
Checks whether the time is running.
Starts the timer.
If the boolean parameter is set to true, the timer resets to the starting time when the function is performed.
If the boolean parameter is set to false, the function is performed at the timer's current time.
Stops the timer.
If the boolean parameter is set to true, the timer resets to the starting time when the function is performed.
If the boolean parameter is set to false, the function is performed at the timer's current time.
Resets the timer to the start time.
Sets the start time of the timer.
DashBoard CustomPanel Development Guide
Method
setStop(Long valueInMilliseconds) setTime(Long valueInMilliseconds) getStart() getStop() getCurrent() incrementTime(Long difference) setPattern(String dateTimePattern)
Parameter
Required
(Long)
Yes
Milliseconds
(Long)
Yes
Milliseconds
(Long)
N/A
N/A
N/A
Yes
Milliseconds
(Long)
Yes
Time format definition
Description
Sets the stop time of the timer.
Sets the current time of the timer.
Returns the timer’s start time in milliseconds (Long).
Returns the timer’s stop time in milliseconds (Long).
Returns the timer’s current value in milliseconds (Long).
Increments the timer value by the specified number of milliseconds
Sets the time format pattern for displaying time values.
Returns
ContextTimerManager
Example 1 — getTimerManager function using isRunning method
//verify if timer named 'selftimer' is currently running if (ogscript.getTimerManager().getTimer('selftimer').isRunning())
{ ogscript.debug('running = true');
} else
{ ogscript.debug('running = false');
}
Example 2 — getTimerManager function using startTimer method
//Starts a timer named 'selftimer' ogscript.getTimerManager().getTimer('selftimer').startTimer(false);
Example 3 — getTimerManager function using stopTimer method
//Stops a timer named 'selftimer' ogscript.getTimerManager().getTimer('selftimer').stopTimer(false);
Example 4 — getTimerManager function using resetTimer method
//Resets a timer named 'selftimer' to the start time ogscript.getTimerManager().getTimer('selftimer').resetTimer();
Example 5 — getTimerManager function using setStart method
//Set the start time of a timer named 'selftimer' to 30 seconds
(30000ms) ogscript.getTimerManager().getTimer('selftimer').setStart(30000);
DashBoard CustomPanel Development Guide
Example 6 — getTimerManager function using setStop method
//Set the stop time of a timer named 'selftimer' to two minutes
(120000 ms) ogscript.getTimerManager().getTimer('selftimer').setStop(120000);
Example 7 — getTimerManager function using setTime method
//Set the current time of a timer named 'selftimer' to 59 seconds
(59000 ms) ogscript.getTimerManager().getTimer('selftimer').setTime(59000);
Example 8 — getTimerManager function using getStart method
// Get the start time of a timer named 'selftimer' var startTime = ogscript.getTimerManager().getTimer('selftimer').getStart();
Example 9 — getTimerManager function using getStop method
// Get the stop time of a timer named 'selftimer' var stopTime = ogscript.getTimerManager().getTimer('selftimer').getStop();
Example 10 — getTimerManager function using getCurrent method
// Get the current time of a timer named 'selftimer' var currentTime
= ogscript.getTimerManager().getTimer('selftimer').getCurrent();
Example 11 — getTimerManager function using incrementTime method
//increase the current time of a timer named 'selftimer' by 30 seconds ogscript.getTimerManager().getTimer('selftimer').incrementTime(30000
)
;
//decrease the current time of a timer named 'selftimer' by 5 seconds ogscript.getTimerManager().getTimer('selftimer').incrementTime(-
5000)
;
Example 12 — getTimerManager function using setPattern method
letter returns more digits or a variation of the format. For example, when specifying M for month, one
M shows the month number with no leading zero, two Ms adds a leading zero for months 0 to 9, three
Ms shows the three letter month (such as Jan), and four or more Ms shows the full month name (such as
January).
Letter
D
S
G
Y
M
H m s
Date or Time
Component
Day
Hour of the day (0-23)
Minute of the hour
Second of the minute
Millisecond
Era designator
Year
Month of the year
Presentation
Number
Number
Number
Number
Number
Text
Number
Text or number
Examples
189
8
30
55
768
AD
1969; 69
September; Sep; 09
DashBoard CustomPanel Development Guide
Letter
w
W d
F h a z
E k
K
Date or Time
Component
Week of the year
Week of the month
Day of the month
Day of the week in the month
Day of the week
Hour of the day (1-24)
Hour in AM/PM (0-11)
Hour in AM/PM (1-12
AM/PM marker
Time zone
Presentation
Number
Number
Number
Number
Text
Number
Number
Number
Text
General Time Zone
Examples
27
3
12
1
If the day of the week is
Tuesday, 1 would denote the first
Tuesday of the month
Friday; Fri
22
0
10
PM
Pacific Standard Time,
PST,
-0800 Z Time zone RFC 822 time zone
The following code example returns the date and time. An example of the date and time as returned by this example is Sep 30, 2013 2:35:34 PM.
//Sets the display format of a timer named 'simpleclock' to show full date and time ogscript.getTimerManager().getTimer('simpleclock').setPattern('MMM dd, yyyy h:mm:ss a');
hide
Hide the popup associated with the specified ID.
Note: to use the hide function, a popup must already exist. Popups can be created only in the JavaScript source, not in DashBoard.
Syntax
ogscript.hide (Popup ID);
Parameters
Parameter
Popup ID
Type
String
Required
Yes
Description
ID of the popup to hide.
Returns
N/A
Example
This example includes two sections of XML code to be added to the .grid file. The first creates a button that opens a popup. The second creates a button that hides the popup.
//This example creates a button which, when clicked by a user, opens the popup area.
<popup id="popup1" left="20" name="Click here to open the Popup" top="25">
<abs height="300" left="200" style="bdr:etched;" top="200"
DashBoard CustomPanel Development Guide
width="300">
</abs>
</popup>
//This example creates a button which, when clicked by a user, hides the popup.
<button buttontype="push" height="50" left="50" name="Click here to hide the Popup" top="500" width="200">
<task tasktype="ogscript">ogscript.hide('popup1');</task>
</button>
installTimer
Create a timer with the given ID and register it in the ContextTimerManager. Start the timer after the specified delay. If requested, repeat the timer at the specified frequency. When the timer fires, run the specified ogScript function.
Syntax
ogscript.installTimer (Timer ID, Repeat, Delay, Repeat Delay, Task);
Parameters
Parameter
Timer ID
Repeat
Delay
Repeat Delay
Task
Type
String
Boolean
Long
Long
Function
Required
Yes
Yes
Yes
Yes
Yes
Description
ID of the timer to create and register in the
ContextTimerManager. true — repeat the timer using the specified
Delay and Repeat Delay. false — only run the timer once, do not repeat the timer.
Number of milliseconds to wait before starting the timer.
How frequently the associated function runs, in milliseconds. ogScript function to run when the timer fires.
Returns
N/A
Example
This example creates a label named "Time" and a button named "Install Timer". When a user clicks the
"Install Timer" button, an associated task runs a function named myFunction (), which creates a timer.
It also retrieves the time value every 30 seconds, and loads it into a variable named str which is displayed on the "Time" label. The myFunction () function uses the installTimer function to create the timer and set the rate at which the time data is updated.
<label height="80" id="timeLabel" left="43" name="Time" style="txtalign:west" top="26" width="275"/>
<button buttontype="push" height="57" left="48" name="Install Timer" top="133" width="184">
<task tasktype="ogscript">function myFunction()
{ var date = new Date();
DashBoard CustomPanel Development Guide
var str = date.getHours() + ':' + date.getMinutes() + ':' + date.getSeconds(); ogscript.rename('timeLabel', 'Time: ' + str);
}
//create a timer that starts immediately and runs myFunction every
30 seconds (30000 milliseconds) ogscript.installTimer('myTimer', true, 0, 30000, myFunction);
</task>
</button>
isTimerRunning
Report whether or not a timer exists and is in the “running” state.
Syntax
ogscript.isTimerRunning (Timer ID);
Parameters
Parameter
Timer ID
Type
String
Required Description
Yes 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.
Returns
Boolean
Example
//verify if the timer is currently running var runtime = ogscript.isTimerRunning('selftimer');
parseXML
Parse and return an XML document using the org.w3c.dom.Document API. The XML document to parse can be provided in the following ways:
• Piece of well-formatted XML
• URL relative to a CustomPanel
• File URL (file:/c:/…)
• http URL (http://…)
The document is loaded via a blocking call that is run in the DashBoard User Interface thread.
Calls to load documents over a network (for example, using http://) are strongly discouraged and can have undesired impacts on the UI performance.
Syntax
ogscript.parseXML (Document);
Parameters
Parameter
Document
Type
String
Required
Yes
Description
XML document to parse.
DashBoard CustomPanel Development Guide
Returns
XML Document
For more information about returns, refer to the following URL: http://docs.oracle.com/javase/6/docs/api/org/w3c/dom/Document.html
Example
The following example loads an XML file from the web using an asynchronous http request. An XPath expression extracts data from the XML and displays it on a label. function myFunc(pageContent)
{ var xmlPageContent = '<?xml version="1.0" encoding="UTF-
8"?>\n' + pageContent; var document = ogscript.parseXML(xmlPageContent); var nodeList = ogscript.runXPath('/response/sports/sportsItem/leagues/leaguesIt em/teams/teamsItem/name', document); var teamList =
'<html>'; ogscript.debug(nodeList.getLength()); for (var i = 0; i < nodeList.getLength(); i++)
{ teamList = teamList + nodeList.item(i).getTextContent() +
'<br/>';
} ogscript.rename('resultLabel', teamList + '</html>');
} ogscript.asyncPost('http://api.oursports.com/v1/sports/hockey/league
/ teams/?_accept=text%6Axml&apikey=ksjdur7euejru47fkbos85kg', null, myFunc);
putObject
You can create an object and reference it in other parts of the code. Some possible uses include:
• Storing parsed XML data in an object so you don’t have to re-parse it.
• Storing the results of an async HTTP post so you don’t have to re-fetch it.
• Storing connection code so you cna reference it wherever your code needs to establish that connection.
The putObject function works in conjunction with the getObject function. The putObject function defines the object. The getObject function references the object. The scope of a defined object is global, so you can reference it from anywhere in your panel code.
For information about the getObject function, see getObject on page 159.
Syntax
ogscript.putObject(Key, Value);
Parameters
Parameter
Key
Type
String
Required
Yes
Value String Yes
Description
The name of the object in which the data is being stored.
The value to be stored.
DashBoard CustomPanel Development Guide
Returns
N/A.
Example
The following example parses and stores data from an XML file in a variable so it can be used globally without the need to re-parse the XML data each time you want to use it.
It defines a function named loadTheXML, which uses the parseXML function to retrieve XML data from a file and load it into a variable named myObject. It then uses the putObject function to copy the data into a variable named myXML. The readTheXML function loads the data into a variable named otherObject. function loadTheXML()
{ var myObject = ogscript.parseXML('file:/c:/mydocument.xml'); ogscript.putObject('myXML',myObject);
} function readTheXML()
{ var otherObject = ogscript.getObject('myXML');
// Do anything you want with the data, now contained in the otherObject variable.
}
putPrivateString
Add or replace a string in a private lookup table.
Note: Use the putPrivateString function if the lookup table has an ID. If the lookup table has no ID, use
Syntax
ogscript.putPrivateString (Lookup ID, Key, Value);
Parameters
Parameter
Lookup ID
Key
Value
Type
String
String
String
Required
Yes
Yes
Yes
Description
ID of the string to create or replace in the specified lookup table.
Private lookup table in which to create or replace the specified string.
New value for the specified string.
Returns
N/A
Example
This example uses the putPrivateString function to replace a datum in a lookup table. The lookup table definition for this example is as follows:
<lookup id="hosts">
<entry key="XPression.host">10.0.2.210</entry>
<entry key="XPression.port">9999</entry>
</lookup>
DashBoard CustomPanel Development Guide
The script to replace an entry in the lookup table is as follows:
//Replace the port number associated with entry key XPression.host ogscript.putPrivateString('hosts',' XPression.port ', '7788');
putString
Add or replace a string in the global lookup table.
Note: Use the putPrivateString function if the lookup table has no ID. If the lookup table has an ID, use the putPrivateString function. For more information about the putPrivateString function, see
Syntax
ogscript.putString (Lookup ID, Value);
Parameters
Parameter
Lookup ID
Value
Type
String
String
Required
Yes
Yes
Description
ID of the string to create or replace in the global lookup table.
New value for the specified string.
Returns
N/A
Example
This example uses the putString function to replace a datum in a lookup table. The lookup table definition for this example is as follows:
<lookup>
<entry key="Tom">television</entry>
</lookup>
The script to replace an entry in the lookup table is as follows:
//Replace the string associated with entry key Tom ogscript.putString('Tom','telephone');
reload
Rebuild the user interface element with the specified ID. If the ID is for an <include> tag, re-fetch the included document before rebuilding the user interface.
If no ID is provided, rebuilds the entire document.
Syntax
ogscript.reload (User Interface ID);
Parameters
Parameter
User Interface ID
Type
String
Required
Yes
Description
ID of the user interface element to rebuild.
Returns
Null, if null is provided as the ID.
DashBoard CustomPanel Development Guide
Example
In this example, the ogscript.reload function is used to rebuild a drop-down list to show new options.
//create a new array of colours var color = new Array("Red","Green","Blue");
//populate the dropdown color_list with the color array params.replaceIdentifiedConstraint('color_list', params.createIntChoiceConstraint(color));
//reload the dropdown list to view the new options ogscript.reload('color_list');
rename
Modify the text associated with a tab name, label, or button. Use the Component ID to specify the component to rename. Do not use the Object ID (OID).
To view the ID of a component, double-click the component in PanelBuilder to open the Edit
Component dialog box. The ID box displays the ID of the selected component.
ID — use the ID displayed in this box to identify the component to rename.
Figure 2.1 Component ID in the Edit Component dialog box
Syntax
ogscript.rename (Component ID, Name);
Parameters
Parameter
Component ID
Type
String
Required
Yes
Name String Yes
Description
ID of the user interface component to rename.
New text to display on the screen for the specified user interface component.
Returns
N/A
Example 1
// Set the item with ID='Seat 5' to have the text 'Mika Andersen' ogscript.rename ('Seat 5','Mika Andersen');
DashBoard CustomPanel Development Guide
Example 2
// Read the value of a parameter into a variable named data var data
= params.getValue(0x12,0);
// Use the variable named data to make a new ID and set the ID to have the text 'Mika Andersen' ogscript.rename('Seat ' + data,'Mika Andersen');
reposition
Moves a component to an absolute position, defined as an X - Y pixel position.
Alternatively, you can specify a component’s position by percentage of the container’s width and
height. For more information, see repositionByPercent on page 174.
Syntax
ogscript.reposition (ID, x position, y position);
Parameters
Parameter
ID x position y position
Type
String
Integer
Integer
Required
Yes
Yes
Yes
Description
ID of the component you want to reposition
Number of pixels from the left
Number of pixels from the right
Returns
N/A
Example
In this example, the task associated with the “Top Left” button uses the ogscript.reposition function to reposition a label.
<label height="40" id="myLabel" left="160" name="myLabel" style="txt-align:center" top="100" width="160"/>
<button buttontype="push" height="40" left="160" name="Top Left" top="200" width="160">
<task tasktype="ogscript">ogscript.reposition('myLabel', 0, 0);
</task>
</button>
repositionByPercent
Moves a component to an absolute position, defined as a percentage of container width and height.
Syntax
ogscript.repositionByPercent (OID, x percent, y percent, center x, center y);
DashBoard CustomPanel Development Guide
Parameters
Parameter
OID x percent y percent center x center y
Type
String
Integer
Integer
Boolean
Boolean
Required
Yes
Yes
Yes
Yes
Yes
Description
OID of the component you want to reposition
Distance from the left, as a percentage of container width
Distance from the top, as a percentage of container height true — Shows the full width of the object. false — Crops the object if it extends beyond the horizontal boundaries of the container. true — Shows the full height of the object. false — Crops the object if it extends beyond the vertical boundaries of the container.
Returns
N/A
Example
In this example, the task associated with the One Quarter button uses the ogscript.reposition function to reposition a label 25% from the left, and 25% from the top. Centering is set to false in both the x and y axes, so if the label overhangs the edges of the container the overhanging portion is not shown.
<label height="41" id="myLabel" left="160" name="myLabel" style="txt-align:center" top="101" width="160"/>
<button buttontype="push" height="40" left="160" name="One Quarter" top="200" width="159">
<task tasktype="ogscript">ogscript.repositionByPercent('myLabel',
25, 25, false, false);
</task>
</button>
reveal
Open a popup with the specified ID, or bring the tab with the specified ID to the foreground.
This function is especially useful for tab sets that have their placement set to the center, meaning that there are no tabs showing for users to click. Using the reveal function is the only way to display the specified tab.
Syntax
ogscript.reveal (User Interface ID);
Parameters
Parameter
User Interface ID
Type
String
Required
Yes
Description
ID of the popup to open or the tab to bring to the foreground.
Returns
N/A
DashBoard CustomPanel Development Guide
Example
This example includes a definition for a set of tabs with its position set to center, and uses the ogscript.reveal function to select a particular tab to be shown.
Tip: When tab position is set to center, tabposition="none" in the tab set’s XML source code.
<tab height="91" left="580" tabposition="none" top="373" width="221">
<abs id="page1" name="Tab 1"/>
<abs id="page2" name="Tab 2"/>
<abs id="page3" name="Tab 3"/>
</tab>
//Select Tab2 ogscript.reveal('page2');
runXPath
Execute the given XPath command on the given XML Document or XML Element and return the results as a NodeList. ogscript.runXPath (XPath, Document); or ogscript.runXPath (XPath, Element);
Parameters
Parameter
XPath
Document
Element
Type
String
String
Required
Yes
Yes
Yes
Description
The XPath command to execute on the given XML Document or XML Element
XML Document on which to execute the given XPath command.
XML Element on which to execute the given XPath command.
For more information about the required parameters, refer to the following URLs:
• http://docs.oracle.com/javase/6/docs/api/org/w3c/dom/Document.html
• http://docs.oracle.com/javase/6/docs/api/org/w3c/dom/Element.html
• http://docs.oracle.com/javase/6/docs/api/org/w3c/dom/NodeList.html
• http://www.w3schools.com/xpath/
Returns
NodeList
Example
Coming soon.
saveToFile
Saves data to a file. This function is typically used to save a byte array, string, or XML document to a file.
Syntax
ogscript.saveToFile(path, data, overwrite);
DashBoard CustomPanel Development Guide
Parameters
Parameter
path data overwrite
Type
String
String, byte[], or
XML
Required
Yes
Yes
Boolean Yes
Description
The directory path to the destination file.
The data to be saved to file.
When true, existing file of the same name is overwritten.
When false, existing file of the same name is not overwritten.
Returns
Returns true, if data is written successfully; otherwise false.
Example
ogscript.saveToFile('files/my-new-file.txt','This is my data',true);
sendUDPAsBytes
Converts ASCII string data to a byte array, and sends it as bytes to the specified host/port through UDP.
The ASCII data is converted to Hexadecimal bytes, and can consist only of the following characters:
• 0 to 9
• A to F
• Spaces and commas (as delimiters)
Syntax
ogscript.sendUDPAsBytes (Host, Port, Data);
Parameters
Parameter
Host
Port
Data
Type
String
Integer
ASCII string
Required
Yes
Yes
Yes
Description
Host name to send the given data through
UDP.
Port number on the given host to be sent given data through UDP.
Data to be converted to bytes and sent through UDP to the specified host/port.
Returns
N/A
Example
ogscript.sendUDPAsBytes (myComputer, 7788,'7A, 3C, FF');
sendUDPBytes
Send the given data bytes to the specified host/port through UDP.
Syntax
ogscript.sendUDPBytes (Host, Port, Data);
DashBoard CustomPanel Development Guide
Parameters
Parameter
Host
Port
Data
Type
String
Integer
Byte
Required
Yes
Yes
Yes
Description
Host name to send the given Data bytes through UDP.
Port number on the given Host to send given Data byte through UDP.
Data bytes to send through UDP to the given Host and Port.
Returns
N/A
Example
Coming soon.
sendUDPString
Convert a string to UTF-8 bytes and send the bytes to the provided host/port through UDP.
Syntax
ogscript.sendUDPString (Host, Port, Data);
Parameters
Parameter
Host
Port
Data
Type
String
Integer
String
Required
Yes
Yes
Yes
Description
Host name to send the given Data string through UDP.
Port number on the given Host to send given Data string through UDP.
Data string to convert to bytes and send through UDP to the given Host and Port.
Returns
N/A
Example
This example uses the sendUDPString function to send a message to a particular host/port. var host = ogscript.getPrivateString('hosts',' Panel.host '); var port = parseInt(ogscript.getPrivateString('hosts',' Panel.port
')); var message = "Hello, can you hear me?"; ogscript.sendUDPString(host,port,message);
DashBoard CustomPanel Development Guide
setAnchorPoints
Specifies how an object moves if the user interface is resized for different monitor and window sizes.
Anchor points are relative to the container in which they are located (for example, a tab, a split pane, etc.).
The setAnchorPoints function allows you to anchor or release an object to/from the top, left, bottom, or right sides. By setting these values, you can effectively anchor an object to a corner, a side, or the center.
Syntax
ogscript.setAnchorPoints (ID, top, left, bottom, right);
Parameters
Parameter
ID top left bottom right
Type
String
Boolean
Boolean
Boolean
Boolean
Required
Yes
Yes
Yes
Yes
Yes
Description
ID of the object you want to anchor. true — object is anchored to the top false — object is not anchored to the top true — object is anchored to the left false — object is not anchored to the left true — object is anchored to the bottom false — object is not anchored to the bottom true — object is anchored to the right false — object is not anchored to the right
Returns
N/A
Example
The button in this example has a task that anchors an object (with ID 'dialog') to the top left.
<button buttontype="push" name="anchorTopLeft">
<task tasktype="ogscript">ogscript.setAnchorPoints('dialog', true, true, false, false);
</task>
</button>
setSize
Resizes a panel object the to the specified width and height, in pixels. Valid only in <abs/> containers.
Syntax
ogscript.setSize (ID, width, height);
Parameters
Parameter
ID
Type
String
Required
Yes width height
Integer
Integer
Yes
Yes
Description
ID of the panel object to be resized. Valid only in <abs/> containers.
New width of the panel, in pixels.
New height of the panel, in pixels.
DashBoard CustomPanel Development Guide
Returns
N/A
Example
Coming soon.
setStyle
Set Style parameters for the component with the given ID if it exists. Style commands are additive.
They can be added or modified, but not removed.
Tip: To view syntax examples for particular styles, use the PanelBuilder user interface to add the style on the Style tab, and then view the resulting code in the Source tab.
For openGear Style Hints for the available style options, refer to the openGear documentation.
Syntax
ogscript.setStyle (Component ID, Style);
Parameters
Parameter
Component ID
Style
Type
String
String
Required
Yes
Yes
Description
ID of the Component to style with the given Style parameters.
Style parameters with which to style the given Component.
Returns
N/A
Example 1
This example defines the style of a label, and then makes three style changes.
//label definition
<label height="45" id="label1" left="330" name="Change the style of this label" style="txt-align:west;" top="100" width="325"/>
//first change - set the background to red ogscript.setStyle('label1',"bg#FF0000");
//second change - set the text colour to black and text size to big ogscript.setStyle('label1',"fg#000000;size:big");
//third change - modify the text alignment from left to right ogscript.setStyle('label1',"txt-align:east");
Example 2
This example creates a pre-defined style, and applies it to a component. Pre-defined styles can add or replace a component’s style settings, but not remove them.
//create a pre-defined style
<style id="Style1" name="Style1" value="size:Big;bg#6F63FB;bdr:etched;"/>
//Add a predefined Style to a component ogscript.setStyle('label1',"style:Style1")
DashBoard CustomPanel Development Guide
setXML
Dynamically generates UI components through ogscript. Replaces the contents of an element with a string of XML code.
Syntax
ogscript.setXML (ID, new XML content)
Parameters
Parameter
ID
Type
String
Required
Yes new XML content String Yes
Description
ID for the component in which you want to replace XML
The new XML content
Returns
N/A
Example
This example includes a label with text. When the user clicks the label, the associated task uses ogscript.setXml to replace the text.
<abs id="0x4">
<label height="59" id="0x2" left="61" name="This Text Will Be
Replaced" style="txt-align:center" top="40" width="238"/>
</abs>
<button buttontype="push" height="40" id="0x3" left="59" name="replaceText" top="121" width="240">
<task tasktype="ogscript">ogscript.setXml('0x4', '<label height="59" id="0x2" left="61" name="This is the New Text" style="txt-align:center" top="40" width="238"/>');
</task>
</button>
toBottom
Displays the object below all others in the same container. Object display is layered. If objects overlap, higher layers are drawn over lower layers.
Syntax
ogscript.toBottom (ID);
Parameters
Parameter
ID
Type
String
Required
Yes
Description
ID object to be sent to the bottom
Returns
N/A
DashBoard CustomPanel Development Guide
Example
This example includes two labels occupying the same position. LabelOne is defined second in the code, so it appears on top and is therefore visible. Button One runs a task that uses ogscript.toBottom to send
Label One to the bottom of the stack. This makes Label Two visible. Button Two sends Label Two to the bottom.
<abs>
<label height="317" id="labelTwo" left="100" name="Label Two" style="size:Biggest;bg#D92648;txt-align:center;" top="100" width="350"/>
<label height="317" id="labelOne" left="100" name="Label One" style="size:Biggest;bg#selectbg;txt-align:center;" top="100" width="350"/>
<button buttontype="push" height="40" id="oneBottom" left="150" name="Button One" style="bg#selectbg;txt-align:center;" top="450" width="100">
<task tasktype="ogscript">ogscript.toBottom('labelOne');
</task>
</button>
<button buttontype="push" height="40" id="twoBottomn" left="300" name="Button Two" style="bg#D92648;txt-align:center;" top="450" width="100">
<task tasktype="ogscript">ogscript.toBottom('labelTwo');
</task>
</button>
</abs>
toTop
Displays the object above all others in the same container. Object display is layered. If objects overlap, higher layers are drawn over lower layers.
Syntax
ogscript.toTop (ID);
Parameters
Parameter
ID
Type
String
Required
Yes
Description
ID object to be sent to the top
Returns
N/A
Example
This example includes two labels occupying the same position. LabelTwo is defined second in the code, so it appears on top and is therefore visible. Button One runs a task that uses ogscript.toTop to send
Label One to the top of the stack. This makes Label One visible. Button Two sends Label Two to the top.
<abs>
<label height="317" id="labelOne" left="100" name="Label One" style="size:Biggest;bg#selectbg;txt-align:center;" top="100" width="350"/>
<label height="317" id="labelTwo" left="100" name="Label Two"
DashBoard CustomPanel Development Guide
style="size:Biggest;bg#D92648;txt-align:center;" top="100" width="350"/>
<button buttontype="push" height="40" id="oneTop" left="150" name="Button One" style="bg#selectbg;txt-align:center;" top="450" width="100">
<task tasktype="ogscript">ogscript.toTop('labelOne');
</task>
</button>
<button buttontype="push" height="40" id="twoTop" left="300" name="Button Two" style="bg#D92648;txt-align:center;" top="450" width="100">
<task tasktype="ogscript">ogscript.toTop('labelTwo');
</task>
</button>
</abs>
upload
Open the File Upload dialog with the specified file.
Syntax
ogscript.upload (Filename);
Parameters
Parameter
Filename
Type
String
Required
Yes
Description
Name of the file with which to open the
File Upload dialog box.
Returns
N/A
Example
Coming soon.
params Object
In ogScript, use the params object to access functions to interact with openGear Device parameters and constraints. The params object is also used to manipulate parameters stored in the .grid file.
The params object is accessible when a CustomPanel is associated with an openGear device or XML data file (.grid file). Scripts referencing a device must follow beneath the referenced device in the XML hierarchy.
To call an openGear Device function, use: params.function name (parameters);
For example: var data = params.getValue (0x12, 0);
Some params functions return a ParamScriptable object named this, which contains several methods
that enable you to manipulate parameters. For more information, see ParamScriptable Object
on page
DashBoard CustomPanel Development Guide
params Functions
The following table lists the functions of the params object. Detailed descriptions appear after the table.
If you are reading this document on-screen, click a function name in the table to view its description.
Function
Parameters Returns
Source OID
Destination OID
ParamScriptable
[choices]
Source OID
Destination OID
N/A
ParamScriptable multiset object
Description
Creates a copy of the parameter. The duplicate parameter is independent of the base parameter. Changing the value of one does not affect the other.
Creates a choice constraint (which is a set of key/value pairs) for use in toggle buttons, combo box, radio buttons, etc.
The choice constraint you create here can be used to replace a constraint for a parameter.
Creates a copy of the parameter that is linked to the base parameter:
Changing the value of the base parameter also changes the value of the duplicate parameter.
Changing the value of the duplicate parameter does not affect the value of the base parameter.
Replaces multiple parameter values all at once.
String [OID]
Integer [Index]
Object [Value]
JSON parameter definition
OID of parameter to delete
String [OID]
String [OID]
N/A
N/A
The entire array of values within the parameter.
Constraint
Creates a parameter based on a JSON parameter definition.
Deletes the specified parameter.
Retrieves the entire array of values within the parameter.
getElementCount getIdentifiedConstraint
String [OID]
Integer [Context
ID] String [OID]
Integer [Index]
String [ID]
Device status information
ParamScriptable
String
Get the constraint from the parameter with the specified OID.
Checks the status of a device and returns an Integer value indicating that status:
0 - good
- warning
- error
- unknown
Get the information about an element in a parameter with the specified OID.
ParamScriptable
Get the constraint with the specified ID. If the ID is an external object URL, get the constraint defined in the specified external object.
Gets information about an element in the parameter with the specified Object ID.
String [Context
ID]
String [OID]
Integer [Index]
String or Integer
[OID] Integer
[Index]
N/A Removes a parameter element. If the parameter is an array with more than one element, the element at the index location
DashBoard CustomPanel Development Guide
Function
isDeviceOnline isPrivateParamContext
replaceConstraint replaceViewConstraint resetAllValues
Parameters
String [OID]
String [OID]
Integer [Index]
String [OID]
Integer [Index]
String [OID]
N/A
Returns
Boolean
String
String
Online status of the device as Boolean
Boolean
String [OID]
String
[Constraint ID]
String [view
OID] String
[constraint object]
String
[parameter OID]
N/A
N/A
N/A
Description
is removed.
Check whether streaming of parameter values to XPression is enabled.
Get the value of a parameter with the specified OID.
If the parameter is not an array parameter, use an Index of 0. In most cases, enter 0 as the Index.
Get a string representation of an element in a parameter with the specified OID.
Queries a device to determine whether it is online.
Returns true if local OGLML-based parameters are operating disconnected from the real device.
Replace the constraint for the parameter with the specified OID with the constraint with the specified constraint ID.
Replaces the constraint object of a parameter view.
String [OID],
Integer [Access]
OID Object[]
Values
N/A
N/A
Integer [Static
Menu ID],
Integer [Menu
State]
N/A
Boolean [Value] N/A
If the specified parameter is a copy of a base parameter, this function resets the parameter’s values to those of the base parameter.
Set the access level of the parameter with the provided OID.
For an array parameter, replaces the current array with the new array.
Set the menu state of the menu with the specified static menu ID.
String [OID]
Boolean
[true/false]
String [OID],
Integer [Index],
Object [Value]
String [OID],
Integer [index],
Integer [change in value]
String (OID)
N/A
N/A
N/A
N/A true — disconnect parameters defined in the OGLML document from the device. false — re-connect parameters defined in the OGLML document from the device.
Controls whether the parameter streams its values to XPression when XPression streaming is on.
When true, streaming is ON. When false, streaming is OFF.
Set the value of an element in a parameter with the provided OID to the provided value.
Changes the value of a parameter.
If the value is a string, it is replaced. If it is a float or int, the specified value is added to the current value.
Creates an OID object.
DashBoard CustomPanel Development Guide
createCopy
Creates a copy of the parameter. The duplicate parameter is independent of the base parameter.
Changing the value of one does not affect the other.
Syntax
params.createCopy (Source OID, Destination OID);
Parameters
Parameter
Source OID
Destination OID
Type
String
String
Required
Yes
Yes
Description
The OID of the parameter to copy
The OID of the new parameter.
Returns
Returns ParamScriptable. For more information, see ParamScriptable Object on page 199.
Example
Coming soon.
createIntChoiceConstraint
Syntax
params.createIntChoiceConstraint (Choices);
Parameters
Parameter
Choices String
Type Required
Yes
Description
Name of the array variable that contains the choices.
Returns
N/A
Example
Coming soon.
createLinkedCopy
Creates a copy of the parameter that is linked to the base parameter:
• Changing the value of the base parameter also changes the value of the duplicate parameter.
• Changing the value of the duplicate parameter does not affect the value of the base parameter.
Syntax
params.createLinkedCopy (Source OID, Destination OID);
Parameters
Parameter
Source OID
Destination OID
Type
String
String
Required
Yes
Yes
Description
The OID of the parameter to copy
The OID of the new parameter.
DashBoard CustomPanel Development Guide
Returns
Returns ParamScriptable. For more information, see ParamScriptable Object on page 199.
Example
Coming soon.
createMultiSet
Changes the values of multiple parameters at once.
Syntax
params.createMultiSet (OID, Index, Value);
Parameters
Parameter
OID
Index
Type
String
Integer
Required
Yes
Yes
Value Object Yes
Description
Object ID of object of interest.
Array parameter index. If the parameter is not an array parameter, use an Index of 0.
In most cases, enter 0 as the Index.
New value for the OID.
Returns
Multiset object.
Example
In the following example, four parameters named "Value 1" through "Value 4" are created with text values that are displayed on buttons when the example is run. When the user taps the Multi-Set button, the params.createMultiSet function changes the parameter values to those referenced by the function.
<abs contexttype="opengear" gridsize="20" style="">
<meta>
<params>
<param access="1" maxlength="0" name="Value 1" oid="Value_1" stateless="true" type="STRING" value="Original Value 1" widget="100"/>
<param access="1" maxlength="0" name="Value 2" oid="Value_2" stateless="true" type="STRING" value="Original Value 2" widget="100"/>
<param access="1" maxlength="0" name="Value 3" oid="Value_3" stateless="true" type="STRING" value="Original Value 3" widget="100"/>
<param access="1" maxlength="0" name="Value 4" oid="Value_4" stateless="true" type="STRING" value="Original Value 4" widget="100"/>
</params>
</meta>
<param expand="true" height="40" left="20" oid="Value_1" top="20" width="340"/>
<param expand="true" height="40" left="20" oid="Value_2" top="80" width="340"/>
<param expand="true" height="40" left="20" oid="Value_3" top="140" width="340"/>
DashBoard CustomPanel Development Guide
<param expand="true" height="40" left="20" oid="Value_4" top="200" width="340"/>
<button buttontype="push" height="60" left="20" name="Multi-Set" top="260" width="340">
<task tasktype="ogscript"> var multi = params.createMultiSet(); multi.setValue('Value_1', 0, 'Multi-set 1'); multi.setValue('Value_2', 0, 'Multi-set 2'); multi.setValue('Value_3', 0, 'Multi-set 3'); multi.setValue('Value_4', 0, 'Multi-set 4'); multi.execute();
</task>
</button>
</abs>
createParam
Creates a parameter based on a JSON parameter definition.
Syntax
params.createParam (JSON parameter definition);
Parameters
Parameter
JSON parameter definition
Type
String
Required
Yes
Returns
N/A
Example
Coming soon.
deleteParam
Deletes the specified parameter.
Syntax
params.deleteParam (OID);
Parameters
Parameter
OID
Type
String
Required
Yes
Returns
N/A
Example
Coming soon.
Description
JSON definition of the parameter.
Description
OID of parameter to delete
DashBoard CustomPanel Development Guide
getAllValues
Retrieves the entire array of values from a parameter.
Syntax
params.getAllValues (OID);
Parameters
Parameter
OID
Type
String
Required
Yes
Description
The OID of the parameter
Returns
The entire array of values from the parameter.
Example
Coming soon.
getConstraint
Get the constraint from the parameter with the specified Object ID.
Syntax
params.getConstraint (OID);
Parameters
Parameter
OID
Type
String
Required
Yes
Description
Object ID of the object of interest.
Returns
Constraint
Example
Coming soon.
getDeviceStatus
Checks the status of a device and returns an Integer value indicating that status.
Syntax
params.getDeviceStatus (OID);
Parameters
Parameter
OID
Type
String
Required
Yes
Description
OID of the device to be queried.
DashBoard CustomPanel Development Guide
Returns
Device status, as an Integer:
• 0 — good
• 1 — warning
• 2 — error
• 3 — unknown
Example
Coming soon.
getElementCount
Gets the number of elements in a parameter array.
Syntax
params.getElementCount (OID);
Parameters
Parameter
OID
Type
String
Required
Yes
Description
The OID of the parameter.
Returns
The number of elements in the parameter array, as an Integer.
Example
Coming soon.
getIdentifiedConstraint
Get the constraint with the specified ID. If the ID is an external object URL, get the constraint defined in the specified external object.
Syntax
params.getIdentifiedConstraint (ID);
Parameters
Parameter
ID
Type
String
Required
Yes
Description
ID of the constraint of interest.
Returns
String
Example
Coming soon.
DashBoard CustomPanel Development Guide
getParam
Gets information about an element in the parameter with the specified Object ID.
Syntax
params.getParam (Context ID, OID, Index);
Parameters
Parameter
Context ID
Type
String
Required
No
OID
Index
String
Integer
Yes
Yes
Description
The context ID of the component that contains the parameter of interest.
Object ID of the object of interest.
Array parameter index. If the parameter is not an array parameter, use an Index of 0. In most cases, enter 0 as the Index.
Returns
ParamScriptable
Example
Coming soon.
getParam (OID, Index).remove
Removes a parameter element. If the parameter is an array with more than one element, the element at the index location is removed.
Syntax
params.getParam ([oid], [index]).remove();
Parameters
Parameter
OID
Index
Type
String or
Integer
Integer
Required
Yes
Yes
Description
OID can be a string or an integer, depending on how the parameter is defined.
Array parameter index. If the parameter is not an array parameter, use an Index of 0.
Returns
N/A
Example
Coming soon.
DashBoard CustomPanel Development Guide
getStream
Checks whether streaming of parameter values to XPression is enabled for the parameter.
Syntax
params.getStream (OID);
Parameters
Parameter
OID
Type
String
Required
Yes
Description
OID of the parameter
Returns
Boolean, to indicate whether streaming is enabled.
Example
Coming soon.
getValue
Gets the value of a parameter with the specified Object ID.
Syntax
params.getValue (OID, Index);
Parameters
Parameter
OID
Index
Type
String
Integer
Required
Yes
Yes
Description
Object ID of object of interest.
Array parameter index. If the parameter is not an array parameter, use an Index of 0. In most cases, enter 0 as the Index.
Returns
String
Example
var data = params.getValue (0x12,0);
getValueAsString
Gets a string representation of an element in a parameter with the specified Object ID.
Syntax
params.getValueAsString (OID, Index);
DashBoard CustomPanel Development Guide
Parameters
Parameter
OID
Index
Type
String
Integer
Required
Yes
Yes
Description
Object ID of the object of interest.
Array parameter index. If the parameter is not an array parameter, use an Index of 0. In most cases, enter 0 as the Index.
Returns
ParamScriptable
Example
Coming soon.
isDeviceOnline
Queries a device to determine whether it is online.
Syntax
params.isDeviceOnline (OID);
Parameters
Parameter
OID
Type
String
Required
Yes
Returns
Online status of the device.
Example
Coming soon.
Description
OID of device to query.
isPrivateParamContext
Returns true when the local OGLML-based parameters are operating disconnected from a real device.
Changes and values are not sent to or fetched from the device if the parameter is defined in the OGLML document.
Syntax
params.isPrivateParamContext ();
Parameters
N/A
Returns
Boolean
Example
Coming soon.
DashBoard CustomPanel Development Guide
replaceConstraint
Replace the constraint for the parameter with the specified Object ID with the constraint with the specified constraint ID. If the ID is an external object URL, replace the constraint with the constraint specified by the external object.
Syntax
params.replaceConstraint (OID, Constraint ID);
Parameters
Parameter
OID
Type
String
Constraint ID String
Required
Yes
Yes
Description
Object ID of object of interest.
ID of the constraint with which to replace the constraint for the parameter with the specified
Object ID.
Returns
N/A
Example
Coming soon.
replaceViewConstraint
Replaces the constraint object of a parameter view.
Syntax
params.replaceViewConstraint (view OID, constraint object);
Parameters
Parameter
view OID constraint object
Type
String
String
Required
Yes
Yes
Description
OID of the view. constraint object to use.
Returns
N/A
Example
Coming soon.
resetAllValues
If the specified parameter is a copy of a base parameter, this function resets the parameter’s values to those of the base parameter.
Syntax
params.resetAllValues (parameter OID);
DashBoard CustomPanel Development Guide
Parameters
Parameter
parameter OID
Type
String
Required
Yes
Description
The OID of the parameter.
Returns
N/A
Example
Coming soon.
setAccess
Set the access level of the parameter with the specified Object ID.
Syntax
params.setAccess (OID, Access);
Parameters
Parameter
OID
Access
Type
String
Integer
Required
Yes
Yes
Description
Object ID of object of interest.
Access level to set for the specified OID. The available access levels are as follows:
0 — Read Only
1 — Read and Write
Returns
N/A
Example
Coming soon.
setAllValues
For an array parameter, replaces the current array with a new array.
Syntax
params.setAllValues([oid], [array]);
Parameters
Parameter
OID
Array
Type
String
String
Required
Yes
Yes
Description
The OID of the parameter.
The new array.
Returns
N/A
Example
Coming soon.
DashBoard CustomPanel Development Guide
setMenuState
Set the menu state of the menu with the provided static menu ID.
Syntax
params.setMenuState (Static Menu ID, Menu State);
Parameters
Parameter Type
Static Menu ID Integer
Menu State Integer
Required
Yes
Yes
Description
ID of the menu of interest.
Menu state to set for the specified Static Menu
ID. The available menu states are as follows:
0 — Hidden
1 — Disabled
2 — Normal
Returns
N/A
Example
Coming soon.
setPrivateParamContext
Control the context between the parameters defined in the OGLM document and a device. This function has no impact on parameters that are only defined on the device or only defined in the OGLML document.
Syntax
params.setPrivateParamContext (Value);
Parameters
Parameter
Value
Type
Boolean
Required
Yes
Description
The available contexts are as follows: true — disconnect parameters defined in the
OGLML document from the device. false — re-connect parameters defined in the
OGLML document from the device.
Returns
N/A
Example
Coming soon.
DashBoard CustomPanel Development Guide
setStream
Controls whether a parameter streams its values to XPression when XPression streaming is on.
Syntax
params.getStream (OID, true/false);
Parameters
Parameter
OID true/false
Type
String
Boolean
Required
Yes
Yes
Description
OID of the parameter
When true, streaming is ON. When false, streaming is OFF.
Returns
N/A
Example
Coming soon.
setValue
Set the value of a parameter for the provided Object ID.
Syntax
params.setValue (OID, Index, Value);
Parameters
Parameter
OID
Index
Type
String
Integer
Required
Yes
Yes
Value Object Yes
Description
Object ID of object of interest.
Array parameter index. If the parameter is not an array parameter, use an Index of 0. In most cases, enter 0 as the Index.
New value for the OID.
Returns
N/A
Example 1
// Set the parameter to 3: params.setValue (0x12,0,3);
Example2
// Set the value to 3 greater than it was. var data = getValue (0x12,0); params.setValue (0x12,0,data + 3);
DashBoard CustomPanel Development Guide
setValueRelative
Increments or decrements a numeric value by a specified amount.
Syntax
params.setValueRelative (OID, Index, Change in value);
Parameters
Parameter
OID
Type
String or
Integer
Index
Change in
Value
Integer
Integer
Required
Yes
Yes
Yes
Description
The OID of the object of which you want to change the value.
Position of data in the parameter.
Amount by which the value is incremented. To decrement the value, use a negative integer.
Returns
N/A
Example
Coming soon.
toOid
Creates an OID object.
Syntax
params.toOid (OID);
Parameters
Parameter
OID
Type
String
Required
Yes
Description
The value of the new OID object.
Returns
N/A
Example
This example is a function that uses the toOid function to create an OID with the value
'my.special.oid'
, then uses the
getOid
function to return the OID value. function lookForSpecificOid(myParam)
{ var myOID = params.toOid('my.special.oid'); return myParam.getOid()
== myOID;
}
DashBoard CustomPanel Development Guide
ParamScriptable Object
Some params functions return a ParamScriptable object named this, which contains several methods that enable you to manipulate parameters.
In ogScript, use methods of the this object to manipulate parameters. To call a general-purpose function, use: this.method name(parameters);
For example: this.replaceConstraint ("0.0;100.0;0.0;100.0;1");
The following table lists the methods of the ParamScriptable object.
Method
deleteParam
Parameters
N/A
Returns
N/A
Description
Deletes the parameter getConstraint getAllValues getElementCount getIndex getOid getValue getValueAsString getValueAt getName replaceConstraint
N/A
N/A getValueAtAsString Integer [index] setValue
N/A
N/A
N/A
N/A
N/A
Integer [index]
String [value]
N/A
Returns the parameter constraint Gets the parameter constraint
The entire array of values within the parameter.
Retrieves the entire array of values within the parameter.
The number of elements in the parameter array, as an Integer.
Returns the index of the changed element
Gets the number of elements in the parameter array.
Get the index of the changed element
Returns the OID of the changed parameter
Returns the value of the changed element
Gets the OID of the changed parameter
Gets the value of the changed element
Returns a string representation of the changed value
Returns a string representation of the value at the provided index
Returns a string representation of the value at the provided index
N/A
Returns the parameter name
String [onstraint] N/A
Gets a string representation of the changed value
Gets a string representation of the value at the provided index
Gets a string representation of the value at the provided index
Sets the value of the changed element to the provided value.
Gets the parameter name getIndex remove isArrayParameter
N/A
N/A
N/A
Returns the array index of the current element
N/A
Returns true if the parameter is an array element
Replaces the parameter's constraint to the provided value
Gets the array index of the current element
Removes the current array element
Checks whether the parameter is an array element resetAllValues N/A N/A setValueAt getElementCount
Integer [index]
String [value]
N/A
N/A
Returns the number of elements in the array
If the parameter is a copy of a base parameter, this function resets the parameter’s values to those of the base parameter.
Sets the value of element at the provided index to the provided value.
Gets the number of elements in the array
DashBoard CustomPanel Development Guide
rosstalk Object
In ogScript, use the rosstalk object to communicate over the network to other devices that speak
RossTalk protocol. Functions in the rosstalk object are typically set through a user interface.
To call a general-purpose function, use: rosstalk.function name (parameters);
The following table lists the functions of the rosstalk object.
Function
setHost getHost setPort getPort
For example: rosstalk.setHost (Server01); sendAsBytes sendAsBytes sendAsBytesWithResponse String [Host], Int [Port],
String [Bytes as Hex String],
String [responseBytes],
Function [Callback] sendBytes sendBytesWithResponse
Parameters
String [Host]
N/A
Integer [Port]
N/A
String [Host], Int [Port],
String [Bytes as Hex String]
String [Host], Int [Port],
String [Bytes as Hex String],
Function [Callback]
String [Host], Int [Port],
Byte[] [Data to Send],
Function [Callback]
String [Host], Int [Port],
Byte[] [Data to Send], Byte
[responseTerminator]
Function [Callback]
Returns
N/A
String
N/A
Integer
N/A
N/A
Response message provided by the recipient.
N/A
Response message provided by the recipient.
Description
Set a default host to use for
RossTalk commands where no host has been defined.
Get the default host previously defined.
Set a default port to use for
RossTalk commands where no host has been defined.
Get the default port previously defined.
Equivalent of calling: sendAsBytes(host, port, bytes, null);
Convert bytes from string
(where string is formatted as
ASCII representations of bytes e.g.
"FDDFEAAE12F9…") and send them to the provided host at the provided port.
Invoke the callback function when done.
Convert bytes from string
(where string is formatted as
ASCII representations of bytes e.g.
"FDDFEAAE12F9…") and send them to the provided host at the provided port.
Invoke the callback function when done.
The [responseBytes] string, when received from the recipient, indicates the end of the response message.
Send the provided bytes to the provided host at the provided port. Invoke the callback function when done.
Send the provided bytes to the provided host at the provided port. Invoke the callback function when done.
The [responseTerminator] byte, when received from the recipient, indicates the end of
DashBoard CustomPanel Development Guide
Function
sendMessage sendMessage sendMessage sendMessage
Parameters
String [RossTalk Command],
Function [Callback]
N/A
String [Host], Int [Port],
String [RossTalk Command]
String [Host], Int [Port],
String [RossTalk Command]
Function [Callback]
Returns
String [RossTalk Command] N/A
N/A
N/A sendMessageWithResponse String [Host], Int [Port],
String [RossTalk Command],
String [responseTerminator],
Function [Callback]
Response message provided by the recipient.
Description
the response message.
Equivalent of calling: sendMessage (getHost(), getPort(), RossTalk
Command, null);
Equivalent of calling: sendMessage (getHost(), getPort(), RossTalk
Command, Callback);
Equivalent of calling: sendMessage (Host, Port,
RossTalk Command, null);
Send the provided string as
UTF-8 followed by CRLF bytes to the provided host at the provided port. Invoke the callback function when done.
Send the provided string as
UTF-8 followed by CRLF bytes to the provided host at the provided port. Invoke the callback function when done.
The [responseTerminator] string, when received from the recipient, indicates the end of the response message.
robot Object
In ogScript, use the robot object to communicate with CamBot robotic cameras through the CamBot PC
User Interface. Functions in the robot object are typically set through a user interface.
To call a general-purpose function, use: robot.function name (parameters);
For example: robot.setHost (Server01);
The following table lists the functions of the robot object.
Function
setHost
Parameters
String [Host]
Returns
N/A getHost setPort getPort sendCambot
N/A
Integer [Port]
N/A
String [CamBot
Command]
String
N/A
Integer
N/A
Description
Set a default host to use for
CamBot commands where no host has been defined.
Get the default host previously defined.
Set a default port to use for
CamBot commands where no host has been defined.
Get the default port previously defined.
Equivalent of calling: sendCambot (getHost(), getPort(), command, null)
DashBoard CustomPanel Development Guide
Function
sendCambot sendCambot sendCambot
Parameters
String [CamBot
Command] Function
[Callback]
Returns
N/A
String [Host], Int [Port],
String [CamBot
Command]
String [Host], Int [Port],
String [CamBot
Command] Function
[Callback]
N/A
N/A
Description
Equivalent of calling: sendCambot (getHost(), getPort(), CamBot Command,
Callback);
Equivalent of calling: sendCambot (Host, Port,
CamBot Command, null);
Send the provided CamBot command to the provided host at the provided port. Invoke the callback function when done.
Callback function signature:
Function (Boolean success,
String sentData, String receivedData, Exception javaException)
vdcp Object
In ogScript, use the vdcp object to communicate with BlackStorm video servers. Functions in the vdcp object are typically set through a user interface.
To call a general-purpose function, use: vdcp.function name (parameters);
For example: vdcp.setHost (Server01);
Function
setHost getHost setPort getPort activeClip clipDuration
The following table lists the functions of the vdcp object.
Parameters
String [Host]
N/A
Integer [Port]
N/A
String [Host], Int [Port], Int [Channel],
Function [Callback]
String [Host], Int [Port], Int [Channel],
String [ClipID], Function [Callback]
Returns Description
N/A
String
N/A
Set a default host to use for VDCP commands where no host has been defined.
Get the default host previously defined.
Set a default port to use for VDCP commands where no host has been defined.
Integer Get the default port previously defined.
N/A
N/A
Fetch the active clip ID for the provided channel from the server at the provided host/port. Invoke the callback with the active clip ID when done.
Callback function signature:
Function (Boolean success, String sentCommand, String resultString,
Exception javaException)
Fetch the duration [HH:MM:SS:FF] of the clip with the given ID. Invoke the callback with the clip duration when done.
Callback function signature:
DashBoard CustomPanel Development Guide
Function
continuePlay cueClip cueClip fastForward fastForward listClips pause pause play rewind rewind stop stop
Parameters
String [Host], Int [Port], Int [Channel]
String [Host], Int [Port], Int [Channel]
String [Host], Int [Port], Int [Channel],
Function [Callback]
String [Host], Int [Port], Int [Channel]
String [Host], Int [Port], Int [Channel],
Function [Callback]
String [Host], Int [Port], Int [Channel],
Function [Callback]
String [Host], Int [Port], Int [Channel]
String [Host], Int [Port], Int [Channel],
Function [Callback]
String [Host], Int [Port], Int [Channel]
String [Host], Int [Port], Int [Channel]
String [Host], Int [Port], Int [Channel],
Function [Callback]
String [Host], Int [Port], Int [Channel]
String [Host], Int [Port],Int [Channel],
Function [Callback]
N/A
N/A
N/A
N/A
N/A
N/A
N/A
N/A
N/A
N/A
Returns Description
Function (Boolean success, String sentCommand, String resultString,
Exception javaException)
N/A
N/A
N/A
Sends the vdcp continuePlay command.
Sends the vdcp variPlay command.
nkScript Object
In ogScript, use the nkScript object to control NK Router OGLML tags used in Switchboard virtual control panels. Functions in the nkScript object are typically set through a user interface.
The nkScript global object is only accessible in OGLML contexts that have been declared as having the
NK Router context type or are beneath such a context in the OGML document hierarchy.
To call a general-purpose function, use: nkscript.function name (parameters);
For example: nkscript.setHost (Server01);
Function
doSwitch
The following table lists the functions of the nkscript object.
Parameters
N/A
Returns
Boolean doSwitch getActiveDst
Int [Dst],
Int [Src], Long [Levels]
N/A
Boolean
Int
Description
Equivalent of calling: doSwitch(getActiveDst(), getActiveSrc(), getLevelMask());
Do a switch on the active IPS to route the given dst to the given src on the given levels.
Get the active dst number
(0-indexed). Returns -1 if there is no active destination.
DashBoard CustomPanel Development Guide
Function
getActiveDstName getActiveIPS getActiveIPSName getActiveSrc getActiveSrcName getLevelMask isLevelActive isMCFlag isProtected isProtectedByMe isSrcActive isSrcActive isVirtual setActiveDst setActiveIPS setActiveSrc setLevelActive setLevelMask setMCFlag setProtected
Parameters
N/A
N/A
N/A
N/A
N/A
N/A
Int [Level Num]
N/A
N/A
N/A
Int [Src]
Int [Dst],
Int [Src], Long [Levels]
N/A
Int [Dst]
String [Serial]
Int [Src]
Int [Level Num]
Long [Level Mask]
Boolean
Boolean
Returns
String
String
String
Int
String
Long
Boolean
Boolean
Boolean
Boolean
Boolean
Boolean boolean
Boolean boolean
N/A boolean
N/A
Boolean
Boolean
Description
Get the name of the active dst
(from the switchboard configuration).
Returns null if there is no active destination.
Get the serial number of the active IPS
Get the name of the active
IPS
Get the active src number
(0-indexed). Returns -1 if there is no active source.
Get the name of the active src
(from the switchboard configuration).
Returns null if there is no active source. get the current level mask (as a bit field)
Is the current level active.
Equivalent to asking: levelMask & (1 << levelNum)
!= 0;
Is the Machine Control flag set.
Is the active destination protected.
Is the active destination protected by this virtual panel.
Is the given source active on the active destination any level.
Is the given source active on the given destination on the given level mask.
Is virtual routing in use (for switch commands and status requests).
Set the active destination (0indexed).
Set the IPS with the given serial number as the active
IPS to receive commands and send status.
Deactivate any currently active IPS.
Set the active source (0indexed).
Set the given level as active.
Set the complete level mask bitfield.
Set the Machine Control flag to true or false.
Request the router to protect
DashBoard CustomPanel Development Guide
Function
setVirtual verifyConfiguration
Parameters
Boolean
N/A
Returns
Boolean
Boolean
Description
the active destination.
Set virtual routing on/off for switch commands and status requests.
Re-activate the current IPS.
DashBoard CustomPanel Development Guide
Appendices
Appendix A: Widget Hint Definitions
// widget hints for all parameter types
#define WIDGET_DEFAULT 0 // let DashBoard decide
#define WIDGET_TEXT_DISPLAY 1 // display as text, read only
#define WIDGET_HIDDEN 2 // do not display
// widget hints for numeric types with NULL_CONSTRAINT or RANGE_CONSTRAINT
#define WIDGET_SLIDER_HORIZONTAL 3 // slider (RANGE only)
#define WIDGET_SLIDER_VERTICAL 4 // slider (RANGE only)
#define WIDGET_SPINNER 5 // spinner
#define WIDGET_TEXTBOX 6 // numeric entry field
#define WIDGET_PROGRESS_BAR 17 // progress bar (RANGE only)
#define WIDGET_AUDIO_METER 19 // audio meter (RANGE only)
#define WIDGET_MENU_POPUP 20 // popup menu with the ID(INT
ONLY)
#define WIDGET_TIMER 21 // countdown/up timer (RANGE only)
#define WIDGET_SLIDER_H_NO_LABEL 24 // unlabeled slider (RANGE only)
#define WIDGET_SLIDER_V_NO_LABEL 25 // unlabeled slider (RANGE only)
#define WIDGET_VERTICAL_FADER 26 // vertical fader bar (RANGE only)
#define WIDGET_TOUCH_WHEEL 27 // touch wheel (RANGE only)
#define WIDGET_HEX_SPINNER 28 // base 16 spinner (RANGE only)
#define WIDGET_ABSOLUTE_POSITIONER 29 // absolute x,y positioner
#define WIDGET_CROSSHAIR 30 // joystick-like x,y positioner
#define WIDGET_JOY_STICK 34 // joystick x,y positioner
// widget hints for integer types with CHOICE_CONSTRAINT
#define WIDGET_COMBO_BOX 7 // combo box - usually the default
#define WIDGET_CHECKBOX 8 // two choices
#define WIDGET_RADIO_HORIZONTAL 9 // radio buttons
#define WIDGET_RADIO_VERTICAL 10 // radio buttons
#define WIDGET_BUTTON_PROMPT 11 // single choice
#define WIDGET_BUTTON_NO_PROMPT 12 // single choice
#define WIDGET_BUTTON_TOGGLE 13 // two choices
#define WIDGET_FILE_DOWNLOAD 18 // external object OID/filename pairs
#define WIDGET_RADIO_TOGGLE_BUTTONS 22 // display a toggle button for choices
#define WIDGET_TREE 31 // display a tree with choices
#define WIDGET_TREE_POPUP 32 // display a tree in a combo box
DashBoard CustomPanel Development Guide
// widget hints for INT32_PARAM
#define WIDGET_IP_ADDRESS 14 // nnn.nnn.nnn.nnn
#define WIDGET_COLOR_CHOOSER 23 // argb color chooser
#define WIDGET_COLOR_CHOOSER_POPUP 33 // argb color chooser in popup
// widget hints for integer arrays
#define WIDGET_ARRAY_HEADER_VERTICAL 15 // array layout specification
#define WIDGET_ARRAY_HEADER_HORIZONTAL 16 // array layout specification
// widget hints for STRING_PARAM
#define WIDGET_TEXT_ENTRY 3 // normal text entry field
#define WIDGET_PASSWORD 4 // uses password entry field
#define WIDGET_TITLE_LINE 5 // layout hint - read only
#define WIDGET_LINE_ONLY 6 // layout hint - read only
#define WIDGET_TITLE_ONLY 7 // layout hint - read only
#define WIDGET_PAGE_TAB 8 // layout hint - read only
#define WIDGET_LICENSE 9 // RossKeys license adapter
#define WIDGET_TITLE_HEADER 10 // layout hint - read only
#define WIDGET_COMBO_ENTRY 11 // combo box plus entry field
#define WIDGET_ICON_DISPLAY 12 // icon plus text display
#define WIDGET_RICH_LABEL 13 // multi-line display (html format)
#define WIDGET_MULTILINE_TEXT_ENTRY 14 // multi-line text entry (nonhtml)
// widget hints for STRING_PARAM (used with special OID 255.1)
#define WIDGET_NAME_OVERRIDE_APPEND 0
#define WIDGET_NAME_OVERRIDE_REPLACE 1
// deprecated names - here for backward compatibility
#define WIDGET_NONE WIDGET_DEFAULT
#define WIDGET_COMBO WIDGET_COMBO_BOX
#define WIDGET_RADIO WIDGET_RADIO_HORIZONTAL
#define WIDGET_HSLIDER WIDGET_SLIDER_HORIZONTAL
#define WIDGET_VSLIDER WIDGET_SLIDER_VERTICAL
DashBoard CustomPanel Development Guide
Appendix B: Reserved Object IDs
Reserved OIDs
Parameter OIDs in the set 0xFF00 to 0xFFFF are reserved for future protocol messages. Apart from these, there are several other OIDs that have special significance in DashBoard.
Name
SUPPLIER_NAME*
PRODUCT_NAME**
SERIAL_NUMBER
SOFTWARE_REV*+
FPGA_REV+
OPTION_SOFTWARE_REV+
OPTION_FPGA_REV+
SMPTE_STATUS
CURRENT_MILLIS
EDIT_PERMISSION
NAME_OVERRIDE
OID
0x0102
0x0105
0x0106
0x010B
0x010C
0x010D
0x010E
0x0201
0x0205
0x0601
0xFF01
Type
String
String
(32bytes max)
String
String
(20bytes max)
String
String
String
Int16
Int16
Int16
String
Constra int
N/A
N/A
N/A
N/A
N/A
N/A
Function
Name of the card manufacturer or OEM supplier (i.e. who customer should call for support). Reported as a generic card parameter by SNMP.
The product name used to identify the card in DashBoard. This name should not change. For display purposes, an alternate name can be provided via OID
0xFF01.
Reported as a generic card parameter by
SNMP.
Unique serial number.
This value is used by a card to report information about its software load. The value should be meaningful to the people supporting the card.
Reported as a generic card parameter by
SNMP.
This value is used by DashBoard compare software versions when uploading the
Main Board FPGA Type (upload type 1).
This value is used by DashBoard compare software versions when uploading the
Option Board Software Type (upload type
2).
N/A
N/A
N/A
Choice
N/A
This value is used by DashBoard compare software versions when uploading the
Option Board FPGA Type (upload type 3).
Card status to be reported via frame fault
LEDs.
Value of 0 indicates no error.
Non-zero values indicate error state.
Current consumption in milliamps at 12 V.
This may be used by the fan controller to adjust fan speed for high-current cards.
Tells DashBoard that the card is editable.
If this OID is used, parameters on the card will be editable only if the parameter value is 0. If the parameter value is non-zero, the card will display as read-only.
With a widget hint of 0, the value in this
String will be appended to the device name (0x0105) when displayed in the
DashBoard tree and tabs. With a widget hint of 1, the value in this String will be displayed instead of the value in 0x0105 in the DashBoard tree and tabs.
DashBoard CustomPanel Development Guide
Name
CONNECT_VERIFY
UPLOAD_URL
FRAME_ID
BACKWARDS_COMPATIBILE 0xFF05 String
(20bytes max)
RESTORE_SET_DELAY
RESTORE_START
OID
0xFF03
Type
Mixed
0xFF02 String
0xFF04 String
0xFF06 Int16
0xFF07 Int16
DashBoard CustomPanel Development Guide
Constra int
N/A
N/A
N/A
N/A
N/A
N/A
Function
This parameter is used for communicating
DashBoard’s connection handshake and response. See the Connection
Management section for more details.
Alternate file upload target. This overrides the behavior of the DashBoard upload button.
If this value is “disable”, DashBoard will disable the upload button on the device page.
If this value is a valid URL, DashBoard will upload files to this location via HTTP
POST.
Reserved for use by an openGear frame’s
Network Interface Card. If this parameter is provided, its value MUST match the unique ID provided by SLP and manual
SLP attribute queries. If it does not,
DashBoard will close its connection to the frame.
Specifies the lowest software version to maintain OID-compatibility with this software version. If this OID is not supplied, the lowest software version is assumed to be the version specified in the
SOFTWARE_REV OID (0x010B).
The card guarantees that all software versions bounded by the version numbers specified between 0xFF05 and 0x010B can be restored using the same stored set of parameter values.
Specifies the delay to use between each parameter set request during a card restore. The restore set messages will not be sent any faster than the specified delay. This number must be between 0 and 1000 milliseconds.
If this value is not specified, a default of 0 is used. Parameters will be restored as quickly as the card can process the
PARAM_SET commands.
If the value is -1, DataSafe is disabled for this card. Other negative values are not valid at this time and should not be used.
A parameter set request with a value of 1 will be sent to this parameter before the card data is restored (the equivalent of a button press in DashBoard).
If this parameter is provided, its position in the list of OIDs returned by the
OGP_GET_PARAM_OIDS Response defines where the range of saved parameter values should start. No parameters whose OID was returned before this OID will be restored by
DataSafe.
Name
RESTORE_STOP
DATASAFE_NAME
UPLOAD_NAME
DISPLAY_OPTIONS
DEVICE_ICON
DEVICE_INDEX_URL
OGLML_DESCRIPTOR
DEDICATED_CONNECTION
OID
0xFF08
0xFF09
0xFF0A
0xFF0B
0xFF0C
0xFF0D
0xFF0E
0xFF0F
Type
Int16
String
Int16
Int16
ARRAY
Int16
String
String
Binary
Constra int
Function
N/A
N/A
Choice
N/A
N/A
N/A
N/A
A parameter set request with a value of 1 will be sent to this parameter after the card data is restore is complete (the equivalent of a button press in
DashBoard).
If this parameter is provided, its position in the list of OIDs returned by the
OGP_GET_PARAM_OIDS Response defines where the range of saved parameter values should stop. No parameters whose OID was returned after this OID will be restored by DataSafe.
Alternative card name for determining
DataSafe compatibility. See DataSafe section for more details.
Alternative card name for file upload purposes.
See DataSafe section for more details.
Each array element is used to define a different display option.
Element 0 controls display of the card:
0 (Default) = Display the card in the tree view
1 = Hide the card in the tree view
Element 1 controls the display of the slot name before the card name:
0 (Default) = Display the slot name (e.g.
Slot 1: UDC-8225-W)
1 = Hide the slot name (e.g. UDC-8225-
W)
All other array elements are reserved for future use.
Contains an external object ID for an encapsulated icon. See table 3.15 for encoding information.
URL for a DashBoard Connect XML
Definition.
Provides an OGLML URL that describes a layout to use in place of the standard configuration screen in DashBoard.
Allows a card that has its own Ethernet port to communicate directly with
DashBoard, bypassing the CAN bus and
MFC card. This allows traffic offloading from the CAN bus, and also allows messages to be sent to specific
DashBoards rather than all of them.
When connected, DashBoard will use this connection to send all messages to the card. DashBoard will continue to receive updates from both the dedicated OGP connection and the CAN Bus connection.
DashBoard CustomPanel Development Guide
Name OID Type Constra int
Function
DEVICE_IP_ADDRESS
FAN_SPEED_REQUEST
OCCUPIED_SLOTS
0xFF10
0xFF11
0xFF12
UPLOAD_FILE_EXTENSIONS 0xFF13
Int32
Int16
Int16
String
Array
IP_AD
DRESS
N/A
N/A
N/A
UTF-8 String for the hostname
UINT16 for the port
UINT8 for the use
0 = Do not use
1 = Connect when UI is visible
Cards that have their own Ethernet port should use this OID to report their current
IPv4 address.
Used by cards in OG3-FR high power frame to request additional fan cooling.
Card must send OGP_REPORT_PARAM for this OID periodically (not to exceed once per minute). Value of the parameter varies depending on the cooling capabilities of the frame.
Report the number of slots this card occupies.
Value consists of two 8-bit fields, representing the number of additional slots to the left and right.
Value = (left << 8) | (right)
Extensions of file types allowed to be sent to the device. Arrau elements have the format: “[Description]<ext:[extension without dot]>”
Reserved for future use RESERVED
RESERVED
0xFF14 to
0xFFFF
0xFF14 to
0xFFFF
…
…
…
… Reserved for future use
** Required by DashBoard and SNMP.
* Required for SNMP.
+ Version numbers are important for software uploads and DataSafe. Please review section 5-9 for recommended version number encodings.
SMPTE_STATUS, CURRENT_MILLIS, and EDIT_PERMISSION are optional, but to avoid misinterpretation, these OIDs should not be used for other parameters.
DashBoard CustomPanel Development Guide
Reserved MFC and DashBoard Connect (slot 0) OIDs
Parameter OIDs in the range 0xFE00 to 0xFEFF have special significance for the MFC network controller (Slot 0) device. These also apply to any DashBoard Connect devices reporting on slot 0.
Name OID Type
DOOR_STATE
SLOT_NAMES
SLOT_DATA_SAFE
URM_STATE
MASTER_PASSWORD
APPLY_BUTTON
CANCEL_BUTTON
DEVICE_CATEGORY
FRAME_ICON
CONFIG_SLOT
CONFIG_URL
INDEX_URL
0x0709
0x803
0x802
0xFE01
0xFE02
0xFE03
0xFE04
0xFE05
0xFE06
0xFE07
0xFE08
0xFE09
Int16
Int16_Array
Int16_Array
Int16
String
(20-bytes max)
Int16
Int16
String
Int16
Int16
String
String
Constra int
N/A
N/A
N/A
N/A
N/A
Choice
Choice
N/A
N/A
N/A
N/A
N/A
Function
Broadcast by the MFC every 10 seconds to indicate door status. 1= closed and 2= open
Deprecated field, see OID 0xFE0B below.
This array has one element for each slot in the frame. Each element’s value is the OID of a String parameter whose value should be used as the name for the device in the given slot.
This array has one element for each slot in the frame.
0 = DataSafe is enabled for the slot [Element
#]
Default = DataSafe is disabled for slot
[Element #] by the frame
States whether the frame requires a User
Rights Management (URM) -Enabled
DashBoard (or a master password) is required to connect to DashBoard.
0 (Default) = URM is not supported by the frame
1 = URM is disabled/not required
2 = URM is enabled/required
This is the value of the master password required by DashBoard users to connect when the User Rights Management server is not available and the URM State is
“Enabled”
The button DashBoard must press to apply changes to the master password or URM state parameters.
The button DashBoard can press to cancel any changes to the master password or
URM state parameters. After the apply button has been pressed, this button does nothing.
Default: “openGear Devices”
Controls how items are grouped in User
Rights Management and in the DashBoard tree view.
Items sharing the same category are kept together.
Contains an external object ID for an encapsulated icon. See table 3.15 for encoding information.
Default: 0
The slot # for the device to open when the frame is ‘opened’ for configuration.
Default: [none]
If defined and non-empty, the URL of a web page to open when the frame is ‘opened’ for configuration.
URL for a DashBoard Connect XML
Definition.
DashBoard CustomPanel Development Guide
Name
MASTER_PASSWORD
_SAVE
FAN_DOOR_STATUS
OID
0xFE0A
0xFE0B
Type
String
Int16
FAN_AMBIENT_TEMP 0xFE0C Int16
FAN_SPEED_REPORT 0xFE0D Int16
RESERVED 0xFE0E
–
0xFEFF
…
Constra int
N/A
N/A
N/A
N/A
…
Function
Same as 0xFE02 above, but used for internal storage on the MFC controller.
Broadcast by the MFC every 10 seconds to indicate door status.
1= closed
2= open
This replaces legacy OID 0x0709.
Broadcast by the MFC every 10 seconds to report the ambient temperature of inlet air.
0 = fan door is open
Otherwise temperature in degrees Celsius.
Broadcast by the MFC every 10 seconds to report current door fan speed.
0 = minimum speed (or fan door open)
Higher values indicate increasing speed.
Max value depends on DFR frame type.
Reserved for future use
DashBoard CustomPanel Development Guide
Download
Public link updated
The public link to your chat has been updated. You may view and manage your chat links after registration here.
Document public link
Advertisement
Key features
Create custom control panels
Group various controls together from multiple products
Create graphical navigation layouts
Control other vendors' equipment
Integrate control of multiple devices into a single, logically laid out control surface
Frequently asked questions
CustomPanels are applications which run within the DashBoard client. These may be served up by a device directly, or created by a user using DashBoard’s PanelBuilder feature, by writing XML code, or a combination of both. CustomPanels may integrate control of multiple connected devices to provide complete solutions to many workflow problems.
Benefits of using CustomPanels include the ability to create custom control panels, group various controls together from multiple products, create graphical navigation layouts, control other vendors' equipment, and integrate control of multiple devices into a single, logically laid out control surface.
CustomPanels are built using a number of complementary technologies, including openGear Protocol (OGP), Resource XML files, openGear Layout Markup Language (OGLML), ogScript, and other control protocols (such as VDCP, RossTalk, etc.).
