Tcl API Reference

Revision History
Date Ver. Changes
05/08/2018 1.0 Initial release.
05/23/2018 1.1 • Added code examples for logging level usage in URC::LOG.
• Minor corrections.
05/25/2018 1.2 Added section: “Module Termination”
06/08/2018 1.3 Changed Permitted Values for eventType
in ::URC::UI::Handler::onSlider
07/31/2018 1.4 Added reference for ::URC::UI::List::Highlight
11/14/2018 1.5 • Updated parameters for ::URC::Conn functions.
• Added ::URC::LOG::IsEnabled.
• Added ::URC::Settings::Get::DictParameters
12/10/2018 1.6 Added ::URC::Settings::Get::DeviceName
04/08/2019 1.7 • Added ::URC::Settings::Get::DevicePort
• Added ::URC::Settings::Get::BaseStationIP
• Added ::URC::Settings::Get::BaseStationMAC
• Minor corrections.
06/24/2019 1.8 • Updated parameters for ::URC::Conn::WakeOnLan

1
 Table of Contents

Introduction ........................................................................................... 7
Overview ................................................................................................ 8
Terminology Used In This Guide ............................................................ 9
Project Setup ........................................................................................ 10
Importing a Package .............................................................................................................10
Sourcing Files ........................................................................................................................10

URC Settings ......................................................................................... 11

::URC::Settings::Get::DeviceName ........................................................................................11
::URC::Settings::Get::DeviceAddress .....................................................................................11
::URC::Settings::Get::DevicePort ...........................................................................................11
::URC::Settings::Get::UIType .................................................................................................12
::URC::Settings::Get::ZoneNum.............................................................................................12
::URC::Settings::Get::ModuleVersion....................................................................................12
::URC::Settings::Get::Parameters ..........................................................................................13
::URC::Settings::Get::DictParameters ...................................................................................13
::URC::Settings::Get::BaseStationIP ......................................................................................13
::URC::Settings::Get::BaseStationMAC..................................................................................14

Event Handlers ..................................................................................... 15

Module Termination ............................................................................ 16
::URC::Destruct::Register ......................................................................................................16

Package URC::Conn .............................................................................. 17

Namespace ::URC::Conn .......................................................................................................18
Event Handlers .............................................................................................................................. 18
::onData.................................................................................................................................................................. 18
::onClose................................................................................................................................................................. 18
Procedures .................................................................................................................................... 18
::URC::Conn::ConnectTCP ...................................................................................................................................... 18

2
 ::URC::Conn::ConnectUDP ..................................................................................................................................... 19
::URC::Conn::ListenUDP ......................................................................................................................................... 19
::URC::Conn::Send.................................................................................................................................................. 20
::URC::Conn::Close ................................................................................................................................................. 20
::URC::Conn::WakeOnLan ...................................................................................................................................... 21
::URC::Conn::Wrap................................................................................................................................................. 21

Package URC::Debug ............................................................................ 22

Namespace ::URC::Debug .....................................................................................................23
Procedures .................................................................................................................................... 23
::URC::Debug::Try .................................................................................................................................................. 23
::URC::Debug::Catch .............................................................................................................................................. 23
::URC::Debug::Wrap............................................................................................................................................... 23

Package URC::IO ................................................................................... 25

The common and temp Directories .......................................................................................26
Namespace ::URC::IO ............................................................................................................27
Procedures .................................................................................................................................... 27
::URC::IO::Read ...................................................................................................................................................... 27
::URC::IO::Write ..................................................................................................................................................... 27
::URC::IO::Append .................................................................................................................................................. 27
::URC::IO::Delete .................................................................................................................................................... 28
::URC::IO::Exists...................................................................................................................................................... 28
::URC::IO::MkDir..................................................................................................................................................... 28

Package URC::IPC ................................................................................. 30

Namespace ::URC::IPC ..........................................................................................................31
Procedures .................................................................................................................................... 31
::URC::IPC::GetID.................................................................................................................................................... 31
::URC::IPC::SendTo::System ................................................................................................................................... 31
::URC::IPC::SendTo::Client ..................................................................................................................................... 31
::URC::IPC::SendTo::Clients.................................................................................................................................... 32
::URC::IPC::Query::System ..................................................................................................................................... 32
::URC::IPC::Query::Client ....................................................................................................................................... 32

Package URC::LOG ................................................................................ 33

Logging Levels Explained .......................................................................................................34

3
 Namespace ::URC::LOG .........................................................................................................35
Procedures .................................................................................................................................... 35
::URC::LOG::Critical ................................................................................................................................................ 35
::URC::LOG::Error ................................................................................................................................................... 35
::URC::LOG::Support .............................................................................................................................................. 35
::URC::LOG::Warning ............................................................................................................................................. 36
::URC::LOG::Info ..................................................................................................................................................... 36
::URC::LOG::Debug ................................................................................................................................................. 36
::URC::LOG::Trace .................................................................................................................................................. 36
::URC::LOG::Wrap .................................................................................................................................................. 37
::URC::LOG::Enable ................................................................................................................................................ 37
::URC::LOG::IsEnabled............................................................................................................................................ 38

Package URC::Macro ............................................................................ 39

Namespace ::URC::Macro::Event ..........................................................................................40
Procedures .................................................................................................................................... 40
::URC::Macro::Event::GetEventsDict ..................................................................................................................... 40
::URC::Macro::Event::Execute ............................................................................................................................... 40
Namespace ::URC::Macro::Commands .................................................................................41
Event Handlers .............................................................................................................................. 41
::onReceiveOneWay............................................................................................................................................... 41
::onReceiveTwoWay .............................................................................................................................................. 41
Procedures .................................................................................................................................... 41
::URC::Macro::Command::Wrap............................................................................................................................ 41

Package URC::RS232............................................................................. 43
Namespace ::URC::RS232 ......................................................................................................44
Event Handlers .............................................................................................................................. 44
::onData.................................................................................................................................................................. 44
::onClose................................................................................................................................................................. 44
Procedures .................................................................................................................................... 44
::URC::RS232::Connect .......................................................................................................................................... 44
::URC::RS232::Send ................................................................................................................................................ 44
::URC::RS232::Close ............................................................................................................................................... 45
::URC::RS232::Wrap ............................................................................................................................................... 45

4
Package URC::Timer ............................................................................. 46
Namespace ::URC::Timer ......................................................................................................47
Event Handlers .............................................................................................................................. 47
::onTimer ................................................................................................................................................................ 47
Procedures .................................................................................................................................... 47
::URC::Timer::Start ................................................................................................................................................. 47
::URC::Timer::Clear ................................................................................................................................................ 47
::URC::Timer::GetRate ........................................................................................................................................... 48
::URC::Timer::Wrap ................................................................................................................................................ 48

Package URC::UI ................................................................................... 49

Namespace ::URC::UI::Set .....................................................................................................50
Procedures .................................................................................................................................... 50
::URC::UI::Set::Text ................................................................................................................................................ 50
::URC::UI::Set::Visible............................................................................................................................................. 50
::URC::UI::Set::Image ............................................................................................................................................. 50
::URC::UI::Set::State ............................................................................................................................................... 51
::URC::UI::Set::Size ................................................................................................................................................. 51

Namespace ::URC::UI::Set::Image .........................................................................................53

Procedures .................................................................................................................................... 53
::URC::UI::Set::Image::BtnNormal ......................................................................................................................... 53
::URC::UI::Set::Image::BtnPressed......................................................................................................................... 53
::URC::UI::Set::Image::BarBackground .................................................................................................................. 54
Namespace ::URC::UI::Set::Text ............................................................................................55
Procedures .................................................................................................................................... 55
::URC::UI::Set::Text::Offset .................................................................................................................................... 55
::URC::UI::Set::Text::HorzAlign .............................................................................................................................. 55
::URC::UI::Set:VertAlign ......................................................................................................................................... 55
Namespace ::URC::UI::Set::Bar .............................................................................................57
Procedures .................................................................................................................................... 57
::URC::UI::Set::Bar::Progress.................................................................................................................................. 57
Namespace ::URC::UI::Display ..............................................................................................58
Procedures .................................................................................................................................... 58
::URC::UI::Display::Page ......................................................................................................................................... 58

5
 ::URC::UI::Display::Notification.............................................................................................................................. 58
::URC::UI::Display::Keyboard ................................................................................................................................. 58
Namespace ::URC::UI::List ....................................................................................................60
Procedures .................................................................................................................................... 60
::URC::UI::List::Add ................................................................................................................................................ 60
::URC::UI::List::Print ............................................................................................................................................... 60
::URC::UI::List::Clear............................................................................................................................................... 61
::URC::UI::List::SetItem .......................................................................................................................................... 61
::URC::UI::List::Highlight ........................................................................................................................................ 61
Namespace ::URC::UI::Hardkey.............................................................................................62
Constants ...................................................................................................................................... 62
Procedures .................................................................................................................................... 63
::URC::UI::Hardkey::Redirect ................................................................................................................................. 63
::URC::UI::Hardkey::Simulate................................................................................................................................. 63
Namespace ::URC::UI::Handler .............................................................................................64
Event Handlers .............................................................................................................................. 64
::onButton .............................................................................................................................................................. 64
::onMultiStateButton ............................................................................................................................................. 64
::onHardButtonPress ............................................................................................................................................. 64
::onHardButtonRelease ......................................................................................................................................... 64
::onSlider ................................................................................................................................................................ 65
::onKeyboardOk ..................................................................................................................................................... 65
::onKeyboardCancel ............................................................................................................................................... 65
::onList.................................................................................................................................................................... 65
::onGesture ............................................................................................................................................................ 66
::onOrientation ...................................................................................................................................................... 66
Procedures .................................................................................................................................... 66
::URC::UI::Handler::Wrap ...................................................................................................................................... 66

6
Introduction
The URC Tcl API was created to facilitate the development of two-way modules compatible with the URC platform.
With version 2.0 of the API, we have completely rebuilt things from the ground up. The goal of this major revision
was to provide a more organized, cohesive and well-documented development interface than what was previously
offered. The entire API is written in the Tcl programming language. There are many educational resources and
references for Tcl online. If you are a beginner with the language, a good start would be familiarizing yourself with
the following websites:

Tcler’s Wiki - https://wiki.tcl.tk/

Tcl Syntax and Semantics guide - http://tmml.sourceforge.net/doc/tcl/Tcl.html
Tcl Reference Manual - http://tmml.sourceforge.net/doc/tcl/
Tcl Command Index - http://tmml.sourceforge.net/doc/tcl/category-index.html

7
Overview
In an effort to increase modularity, the API has been divided into several distinct Tcl packages, each with their own
focused set of capabilities. They are as follows:

URC::Conn For managing all network-based connections between a module and the device(s) it is
controlling.
URC::Debug For handling debugging procedures.
URC::IO For handling file I/O operations.
URC::IPC Acronym for Interprocess Communication. Facilitates communication between the
“system” and “client” scripts of a module.
URC::LOG For in-depth management of logging output. Supports nine hierarchical levels of logging for
precision troubleshooting.
URC::Macro For handling all URC macro integration functionality.
URC::RS232 For handling all RS-232 connectivity.
URC::Timer For creating and managing general purpose timers.
URC::UI For manipulation of a URC device's user interface.

The code for each URC API package is contained within one or more Tcl namespaces inside that package. These
namespaces will all fall under the parent ::URC namespace. For example, the Conn package contains a single
namespace named ::URC::Conn. This namespace contains all of the procedures and variables belonging to the
Conn package. The much larger ::URC::UI package on the other hand, is broken up into several namespaces
(i.e. URC::UI::Set::Text, URC::UI::Set::Image, etc.), each with their own special subset of UI-related
functionality.

8
Terminology Used In This Guide
Module Two-Way Module
Base station A URC base station. The main controller on which a two-way module is
executed.
Client script Any Tcl script(s) loaded upon the launch of a module on a user interface.
System script Any Tcl script(s) loaded upon base station startup/reboot.
URC API Any URC code that is exposed to the developer for use.
URC Framework Any URC code that interfaces with the URC API, but not with the developer.
URC programming software Any URC editor software that supports two-way modules (i.e. Accelerator,
Flex, etc.)
Installer Any person who installs and configures URC systems, including the two-way
modules contained within.
End user The person that will be using the two-way module.

9
Project Setup
Importing a Package

To load URC packages (and any other Tcl packages) for use in your module, add the following command to the
beginning of the master system script and master client script:

source [file dirname [info script]]/URC_API.tcl

Next, call the procedure ::URC::LoadPackages to load the packages that you want to use:

::URC::LoadPackages {pkgName pkgVersion} {pkgName pkgVersion} …etc

Example)

::URC::LoadPackages {URC::LOG 1} {URC::Conn 1} {http} {json}

Note the integer placed next to the API package name when loading it. This is to specify the major version of the
package that we require. It is important to include this for API packages to ensure your module continues to work
properly if a new major API release is made in the future. All API packages that are used must belong to the same
major revision to ensure compatibility.

Sourcing Files

To easily source Tcl files that are part of your project, call the procedure:

::URC::SourceFiles tclFilename tclFilename tclFilename …etc.

Example)

::URC::SourceFiles projectMain.tcl commands.tcl data.tcl

10
URC Settings
There are several variables containing some of the configuration settings made in the URC programming software
that get passed into a module upon it’s execution. You may need to access these variables to obtain their values
for use in your module’s code. You can use the “getter” procedures in the ::URC::Settings::Get
namespace to retrieve them.

::URC::Settings is NOT a package and should therefore not be included when ::URC::LoadPackages is called.

The getter procedures are as follows:

::URC::Settings::Get::DeviceName
::URC::Settings::Get::DeviceName

Description
Retrieves the name given to the module by the installer in the URC programming software.

Parameters
N/A

Return
The module’s device name.

::URC::Settings::Get::DeviceAddress
::URC::Settings::Get::DeviceAddress

Description
Retrieves the address set for the module in the URC programming software.

Parameters
N/A

Return
The address of the device being controlled by the module.

::URC::Settings::Get::DevicePort
::URC::Settings::Get::DevicePort

Description
Retrieves the device port set for the module in the URC programming software.

Parameters
N/A

Return

11
The port number.

::URC::Settings::Get::UIType
::URC::Settings::Get::UIType

Description
Retrieves the current UI device type.

Parameters
N/A

Return
The current UI type. [Possible Values: remote, phone, tablet, legacy]

Notes
For client script only.

::URC::Settings::Get::ZoneNum
::URC::Settings::Get::ZoneNum

Description
Retrieves the current UI's zone number. Used for "Muti-Zone" and "Dynamic Interface + Core" device types.

Parameters
N/A

Return
The UI’s zone number.

Notes
For client script only.

::URC::Settings::Get::ModuleVersion
::URC::Settings::Get::ModuleVersion

Description
Retrieves the TCL Module’s current version number.

Parameters
N/A

Return
The modules version number. ; -1 if not applicable.

12
::URC::Settings::Get::Parameters
::URC::Settings::Get::Parameters

Description
Retrieves either the System Parameters or the Module (Client) Parameters for the system and client scripts
respectively.

Parameters
N/A

Return
The system or client parameters.

::URC::Settings::Get::DictParameters
::URC::Settings::Get::DictParameters {delimiter =}

Description
Parses the available parameters line-by-line using the provided delimiter to separate the parameter key and value
for each line. Each key-value pair is then added to the dictionary that is returned by the function.

By default, a parameter in the format:

PARAM1=This is my first parameter
PARAM2=New parameter on a new line

Would return the dictionary:

{PARAM1 “This is my first parameter” PARAM2 “New parameter on a new line”)

Parameters
delimiter Optional parameter to specify the character used as a delimiter for parameters. Default value is
“=”.

Return
A TCL dictionary of the system or client parameters key-value pairs.

::URC::Settings::Get::BaseStationIP
::URC::Settings::Get::BaseStationIP

Description
Retrieves the IP address of the URC base station.

Parameters
N/A

Return

13
The IP address in the format XXX.XXX.XXX.XXX

::URC::Settings::Get::BaseStationMAC
::URC::Settings::Get::BaseStationMAC

Description
Retrieves the MAC address of the URC base station.

Parameters
N/A

Return
The MAC address in the format AABBCCDDEEFF

14
Event Handlers
Throughout the packages of this API, you will come across special procedures located under the category of “Event
Handlers”. These procedures are special in that rather than being called by the developer, they are called by the
API, with the expectation that they have been implemented by the developer.

For example, in the event of data being received by a module on an open TCP connection, the URC API will call
the ::onData procedure. It is the module developer’s responsibility to implement the ::onData procedure, so
that the appropriate actions can be taken upon receiving the data.

Due to event handling requiring calls to procedures located in developer code, each event handler, by necessity,
has been given a default name in the global namespace (i.e. ::onData, ::onReceiveTwoWay, etc.).
However, in an effort to give developers full control over the naming scheme of their own procedures, a
“wrapping” procedure has been provided in each package that contains event handlers. This allows the default
name to be wrapped with a custom name. So a developer could, for example, include the event handlers within
various namespaces throughout their code by wrapping the defaults with the fully qualified procedure names
(i.e. ::myNamespace::onData, ::myOtherNamespace::onReceiveTwoWay, etc.).

If using the Wrap procedure, it should only be called one time (per URC package).

15
Module Termination
There are certain tasks that a module may need to carry out upon its termination. Whether it be an instance of
the module on a client interface (client script) or the core of the module itself (system script), having a well-
planned exit will ensure that a module is gracefully terminated without any unexpected results. Some examples of
things you may need your module to do upon termination include having the system script send any queued
commands to a device, or having an instance of the client script notify the system script that it is terminating.

The URC API handles this by providing the Register procedure in the URC::Destruct namespace. This
allows you to “register” procedures that you’d like to have executed upon termination, so that the API can execute
them when that time comes. Simply call this procedure for each of your own procedures that you’d like to add to
the termination process.

::URC::Destruct is NOT a package and should therefore not be included when ::URC::LoadPackages is called.

::URC::Destruct::Register
::URC::Destruct::Register onCloseProc

Description
Appends a new procedure to the list of procedures called by the URC API when the TCL instance is terminating.

Parameters
onCloseProc The procedure to call when the TCL instance is terminating.

Return
N/A

Notes
Can be called in both the system script and client script.
The order in which the procedures are registered will be the order in which they are executed.

16
Package URC::Conn

17
Namespace ::URC::Conn
Contains all code to manage network-based connections between a module and the device(s) it is controlling.

Event Handlers
::onData
::onData name data {ip}

Description
This procedure will be called by the URC API when data is received on a connection.

Parameters
name The name of the connection on which data was received.
data The data received.
{ip} The IP address that the incoming data is coming from. Must be present if using any listening UDP
connections.

Notes
When dealing with listening UDP connections, the ip parameter must be present due to the possibility of two or
more devices with different IP addresses using the same port number to send data.

::onClose
::onClose name

Description
This procedure will be called by the URC API when a connection is closed unexpectedly. It will not be called when
the connection is closed manually using the Close procedure located within this namespace.

Parameters
name The name of the connection that was closed.

Procedures
::URC::Conn::ConnectTCP
::URC::Conn::ConnectTCP -encoding “” –translation “binary” –buffering “none”
–buffersize “” –eofchar “” -- name host port
Description
Establishes a TCP connection with a host device.

Parameters
name A unique, human-friendly name to assign to the connection for easy reference
host The host device's IP address

18
 port The port on the host device used for the connection
-encoding The encoding that the host device will be using to communicate. The encoding name
must be chosen from the list of encodings returned by the Tcl command [encoding
names]. When specified, this will cause incoming characters to be converted to Unicode
and outgoing characters to be converted to the specified encoding.
-translation End of line translation for input/output data. [Permitted Values: auto; binary; cr; crlf; lf]
-buffering The sockets buffering method. [Permitted Values: full; line; none]
-buffersize The size of the input/output buffer.
-eofchar The sockets end of file marker.

Return
Returns a Tcl error if connection attempt fails. (Any call to this procedure must be wrapped by an exception
handler in order to capture the return value.)

::URC::Conn::ConnectUDP
::URC::Conn::ConnectUDP -encoding “” –translation “binary” –buffering “none”
–buffersize “” –eofchar “” -- name host port

Description
Establishes a “sending only” UDP connection with a host device.

Parameters
name A unique, human-friendly name to assign to the connection for easy reference
host The host device's IP address
port The port on the host device used for the connection
-encoding The encoding that the host device will be using to communicate. The encoding name must
be chosen from the list of encodings returned by the Tcl command [encoding names].
When specified, this will cause incoming characters to be converted to Unicode and
outgoing characters to be converted to the specified encoding.
-translation End of line translation for input/output data. [Permitted Values: auto; binary; cr; crlf; lf]
-buffering The sockets buffering method. [Permitted Values: full; line; none]
-buffersize The size of the input/output buffer.
-eofchar The sockets end of file marker.

Return
Returns a Tcl error if connection attempt fails. (Any call to this procedure must be wrapped by an exception
handler in order to capture the return value.)

Notes
Can be used independently or complemented by URC::Conn::ListenUDP for full two-way UDP functionality.

::URC::Conn::ListenUDP
::URC::Conn::ListenUDP -encoding “” –translation “binary” –buffering “none” –
buffersize “” –eofchar “” -- name port

Description
Opens a “receiving only” UDP socket on the base station.

19
Parameters
name A unique, human-friendly name to assign to the connection for easy reference
port The port on the URC base station that the remote device(s) will be sending data to.
-encoding The encoding that the host device will be using to communicate. The encoding name must
be chosen from the list of encodings returned by the Tcl command [encoding names].
When specified, this will cause incoming characters to be converted to Unicode and
outgoing characters to be converted to the specified encoding.
-translation End of line translation for input/output data. [Permitted Values: auto; binary; cr; crlf; lf]
-buffering The sockets buffering method. [Permitted Values: full; line; none]
-buffersize The size of the input/output buffer.
-eofchar The sockets end of file marker.

Return
N/A

Notes
Can be used independently or complemented by URC::Conn::ConnectUDP for full two-way UDP
functionality. This procedure can only be called once per port number since two separate sockets cannot listen for
data coming from the same port number.

::URC::Conn::Send
::URC::Conn::Send name data {newLine 0}

Description
Sends data across a connection.

Parameters
sock A unique, human-friendly name to assign to the connection for easy reference
data The host device's IP address
{newLine} When set to 0 (default), the puts command that writes data to the socket will include the -
nonewline option. When set to 1, it will not.

Return
N/A

::URC::Conn::Close
::URC::Conn::Close name

Description
Closes a socket connection.

Parameters
name The name of the connection to close

Return

20
N/A

::URC::Conn::WakeOnLan
::URC::Conn::WakeOnLan -ip “BROADCAST” -port 40000 -- mac

Description
Broadcast a Wake-On-Lan "magic packet" over the network to wake up a device.

Parameters
mac The MAC address of the device to be woken up, with a semi-colon delimiting each octet.
(i.e. FF:FF:FF:FF:FF:FF)
-ip The IP to send the magic packet to. If not set, the broadcast IP will be extracted and used.
-port The port to send the magic packet on.

Return
N/A

::URC::Conn::Wrap
::URC::Conn::Wrap -onClose "::onClose" -onData "::onData"

Description
Wraps event-handling procedures called by the API with user-defined procedure names.

Parameters
-onClose Wraps the ::onClose function
-onData Wraps the ::onData function

Return
N/A

21
Package URC::Debug

22
Namespace ::URC::Debug
Contains code to facilitate debugging.

Procedures
::URC::Debug::Try
::URC::Debug::Try args

Description
Wrapper for the Tcl try function. Outputs the Error and Options natively.

Parameters
args List of arguments.
args[0] The script to try to evaluate
args[1-2] The words "on" and "error"
args[3] Script to evaluate on error

Return
Will return an error if one is encountered in the on error script.

::URC::Debug::Catch
::URC::Debug::Catch script

Description
Wrapper for catch that outputs a nicely formatted log of the error info generated by a caught exception.

Parameters
script The name of the procedure or the literal code to evaluate

Return
The return code of the script evaluation. [Possible Values: 0 (ok), 1 (error), 2 (return), 3 (break), 4 (continue)]

::URC::Debug::Wrap
::URC::Debug::Wrap -try "NA" -catch "NA"

Description
Wraps event-handling procedures called by the API with user-defined procedure names.

Parameters
-try Wrapper for ::URC::Debug::Try
-catch Wrapper for ::URC::Debug::Catch

23
Return
N/A

24
Package URC::IO

25
The common and temp Directories
Common and temp are the two directories on the URC base station that you’ll be dealing with when using the
procedures in the IO package. You will specify which one of these directories to read from/write to, etc. by using
the flags –common and –temp. The intended usage of these directories is as follows:

Directory Purpose
common For data that needs to persist after a base station resets or is re-downloaded to.
temp For data that needs to persist after a base station reset but NOT after a re-download.

26
Namespace ::URC::IO
Contains all code to handle I/O operations for TCL Modules.

Procedures
::URC::IO::Read
::URC::IO::Read -common -temp -- fileName

Description
Reads a file from one of a select group of directories on the URC base station.

Parameters
fileName The name of the file to read
-common Flag to specify the common directory
-temp Flag to specify the temporary directory

Return
The file data if the file exists; An error if the file does not exist

::URC::IO::Write
::URC::IO::Write -common -temp -- fileName data

Description
Writes a file to one of a select group of directories on the URC base station. If the file does not exist, it will be
created. Any pre-existing file will be overwritten.

Parameters
fileName The name of the file to write to
data Data to write to the file
-common Flag to specify the common directory
-temp Flag to specify the temporary directory

Notes
If subdirectories are created, they would be specified as part of the file name (i.e.
subDirectory1/subDirectory2/fileName). The subdirectories must already exist.

::URC::IO::Append
::URC::IO::Append -common -temp -- fileName data

Description

27
Writes to a file located within one of a select group of directories on the URC base station. If the file does not exist,
it will be created. Any pre-existing file will be appended to.

Parameters
fileName The name of the file to write to
data Data to write to the file
-common Flag to specify the common directory
-temp Flag to specify the temporary directory

Notes
If subdirectories are created, they would be specified as part of the file name (i.e.
subDirectory1/subDirectory2/fileName). The subdirectories must already exist.

::URC::IO::Delete
::URC::IO::Delete -common -temp -- fileName

Description
Deletes a file or subdirectory located within one of a select group of directories on the URC base station. If deleting
a subdirectory, all of the subdirectory's content will also be deleted.

Parameters
fileName The name of the file/directory to delete
-common Flag to specify the common directory
-temp Flag to specify the temporary directory

Return
N/A

::URC::IO::Exists
::URC::IO::Exists -common -temp -- fileName

Description
Function to determine if a file or directory exists in one of the supported parent directories.

Parameters
fileName The name of the file/directory to delete.
-common Flag to specify the common directory
-temp Flag to specify the temporary directory

Return
1 if the file exists; 0 if the file does not exist

::URC::IO::MkDir

28
::URC::IO::MkDir -common -temp -- directoryName

Description
Function to create a subdirectory in one of the supported parent directories.

Parameters
directoryName The name of the directory to create
-common Flag to specify the common directory
-temp Flag to specify the temporary directory

Return
N/A

29
Package URC::IPC

30
Namespace ::URC::IPC
Contains all code to handle Inter Process Communication. This allows the system script and client scripts of a TCL
module to communicate with each other.

Procedures
::URC::IPC::GetID
::URC::IPC::GetID

Description
Returns the current process' id.

Parameters
N/A

Return
The current process' id

::URC::IPC::SendTo::System
::URC::IPC::SendTo::System args

Description
Called by client processes to send data to the system process.

Parameters
args The data to be sent

Return
N/A

::URC::IPC::SendTo::Client
::URC::IPC::SendTo::Client id args

Description
Called by any process to send data to a specific client process.

Parameters
id The id of the process to send the data to
args The data to be sent

Return
31
N/A

::URC::IPC::SendTo::Clients
::URC::IPC::SendTo::Clients args

Description
Called by the system process to send data to all client processes.

Parameters
args The data to be sent

Return
N/A

::URC::IPC::Query::System
::URC::IPC::Query::System args

Description
Called by client processes to query the system process.

Parameters
args The query data to be sent

Return
The data returned by the system script.

::URC::IPC::Query::Client
::URC::IPC::Query::Client id args

Description
Called by any process to query data from a specific client process.

Parameters
id The id of the process to query
args The query data to be sent

Return
The data returned by the client script.

32
Package URC::LOG

33
Logging Levels Explained
URC logging operates on a heirarchical system. There are several different “levels” of logging, all with their own
intended use. Used effectively, they can significantly improve the troubleshooting process, both during
development and after release. These levels are functionally heirarchical in the sense that enabling one will enable
every level above it as well. They are, in order of highest to lowest priority, as follows:

Level Recommended Use

Critical Critical info that is not an actual Tcl error.

Example:
::URC::LOG::Critical “Port number specified is outside valid port range!”
Error Any error that impedes functionality of the module. (not intended for errors that can be handled
gracefully with exceptions)

Example:
::URC::LOG::Error “Cannot complete http request. Client is unauthorized.”
Support Verbose, high-level module status info with the specific intent of aiding tech support agents in
troubleshooting the module after it’s release.

Example:
::URC::LOG::Support “System parameters missing. Check two-way module
settings in URC programming software.”
Warning Identifying a condition that may potentially cause an issue, but is non-critical.

Example:
::URC::LOG::Warning "Target device is running old firmware! Some API
features may not be available."
Info Easily readable, low-level info about the current state of execution.

Example:
::URC::LOG::Info "Received data $data from $ipAddress.”
Debug Raw, low-level info about the current state of execution (i.e. a data structure).

Example:
::URC::LOG::Debug “lightingSystemDict: [dict get $lightingSystemDict]”
Trace For tracking of execution location (i.e. tagging the start and end of a procedure) and outputting
data that would otherwise be ignored at a higher level of debugging (i.e. the counter variable in a
for loop).

Example:
::URC::LOG::Trace “START”

34
Namespace ::URC::LOG
Contains all code for logging Tcl output.

Procedures
::URC::LOG::Critical
::URC::LOG::Critical txt

Description
Prepend LOG output with useful debugging information and a CRITICAL Tag

Parameters
txt The data to be outputted to the LOG

Return
N/A

::URC::LOG::Error
::URC::LOG::Error txt

Description
Prepend LOG output with useful debugging information and an ERROR Tag

Parameters
txt The data to be outputted to the LOG

Return
N/A

::URC::LOG::Support
::URC::LOG::Support txt

Description
Prepend LOG output with useful debugging information and a SUPPORT Tag

Parameters
txt The data to be outputted to the LOG

Return
N/A

35
::URC::LOG::Warning
::URC::LOG::Warning txt

Description
Prepend LOG output with useful debugging information and a WARNING Tag

Parameters
txt The data to be outputted to the LOG

Return
N/A

::URC::LOG::Info
::URC::LOG::Info txt

Description
Prepend LOG output with useful debugging information and an INFO Tag

Parameters
txt The data to be outputted to the LOG

Return
N/A

::URC::LOG::Debug
::URC::LOG::Debug txt

Description
Prepend LOG output with useful debugging information and a DEBUG Tag

Parameters
txt The data to be outputted to the LOG

Return
N/A

::URC::LOG::Trace
::URC::LOG::Trace txt

Description
36
Prepend LOG output with useful debugging information and a TRACE Tag

Parameters
txt The data to be outputted to the LOG

Return
N/A

::URC::LOG::Wrap
::URC::LOG::Wrap -critical -error -support -warning -info -debug -trace

Description
Used to wrap the API Log functions to the function name the developer chooses.

Parameters
-critical Wraps ::URC::LOG::Critical
-error Wraps ::URC::LOG::Error
-support Wraps ::URC::LOG::Support
-warning Wraps ::URC::LOG::Warning
-info Wraps ::URC::LOG::Info
-debug Wraps ::URC::LOG::Debug
-trace Wraps ::URC::LOG::Trace

Return
N/A

Notes
The recommended call for this function will be:
::URC::LOG::Wrap -critical CRITICAL -error ERROR -support SUPPORT -warning
WARNING -info INFO -debug DEBUG -trace TRACE

::URC::LOG::Enable
::URC::LOG::Enable -shell "production" -file "production"

Description
Used to set the current LOG Level.

Parameters
-shell The LOG level for shell logging
-file The LOG level for file logging

Return
N/A

37
Notes
It will be required that the developer call:

::URC::LOG::Enable -shell “production” -file “production“

when building a release version of their module.

It is recommended to only enable shell log during development. File logging should be left set to “production”
unless otherwise instructed or absolutely necessary.

::URC::LOG::IsEnabled
::URC::LOG::Enable lvl

Description
Used to determine if the provided log level is currently enabled or disabled.

Parameters
lvl The log level who’s current state is to be checked [Permitted Values: critical ; error ; support ; warning ;
info ; debug ; trace].

Return
1 if the log level is enabled ; 0 if the log level is disabled

Notes
This function can be used to increase the performance of your module during normal operation while still allowing
you to gather extra logging information when necessary. For example, you may have a system that returns
encrypted feedback that you do not need to parse during normal operation. However, using this function, you can
enable the feedback to be decrypted and outputted only when a specific log level is enabled (such as “debug”).
This avoids slowdowns due to decryption in normal operation but still allows you to see the feedback in a log if
necessary.

38
Package URC::Macro

39
Namespace ::URC::Macro::Event
Contains all code for handling any device events created in the URC programming software.

Procedures
::URC::Macro::Event::GetEventsDict
::URC::Macro::Event::GetEventsDict

Description
Retrieves the Events dict.

Parameters
N/A

Return
The Events dict in the format:

{$eventID1 {ruleid $ruleid param $param zoneID $zoneID} $eventID2 {ruleid

$ruleid param $param zoneID $zoneID } $eventID3 {ruleid $ruleid param $param
zoneID $zoneID}….etc.

…where param is a dict containing the event’s parameters in the format:

{$paramID1 $paramVal1 $paramID2 $paramVal2 $paramID3 $paramVal3....etc.}

::URC::Macro::Event::Execute
::URC::Macro::Event::Execute eventID

Description
Triggers the execution of an event macro by notifying the firmware that the event has occurred.

Parameters
eventID The unique numeric ID of the event.

Return
N/A

40
Namespace ::URC::Macro::Commands
Contains all code for handling incoming commands sent from the firmware.

Event Handlers
::onReceiveOneWay
::onReceiveOneWay data

Description
Called by the URC API when a one-way command is received from the base station firmware.

Parameters
data The one-way data.

Notes
This procedure should only be implemented when processing of a one-way command is needed. A common use
case for this would be if you want the installer of your module to be able to create custom one-way commands. In
the integration guide for the module, you can define a special format to use when creating the command and
then, within this procedure, implement code to process these custom commands into actual commands to send to
the controlled device.

::onReceiveTwoWay
::onReceiveTwoWay data

Description
Called by the URC API when a two-way command/query is received from the base station firmware.

Parameters
data The command/query data in dictionary form:

ruleID $ruleID zoneID $zoneID paramDict {$paramID $paramValue $paramID

$paramValue $paramID $paramValue …..etc.}

Notes
This procedure will have the repsonsibility of processing any two-way query or command that can be added to a
project by an installer in the macro editing section of the URC programming software.

Procedures
::URC::Macro::Command::Wrap

41
::URC::Macro::Command::Wrap -oneway "::onReceiveOneWay" -twoway
"::onReceiveTwoWay"

Description
Wraps event-handling functions called by the API with user-defined function names.

Parameters
-oneway Wraps ::onReceiveOneWay
-twoway Wraps ::onReceiveTwoWay

Return
1

42
Package URC::RS232

43
Namespace ::URC::RS232
Contains code for all RS232 connection related functions and variables.

Event Handlers
::onData
::onData data

Description
This procedure will be called by the URC API when data is received on a connection.

Parameters
data The data received.

::onClose
::onClose

Description
This procedure will be called by the URC API when a connection is closed unexpectedly. It will not be called when
the connection is closed manually using the Close procedure located within this namespace.

Parameters
N/A

Procedures
::URC::RS232::Connect
::URC::Connect

Description
Creates a RS232 connection using the serial settings configured in the URC programming software.

Parameters
N/A

Return
1 if successful connection; 0 if unsuccessful connection

::URC::RS232::Send

44
::URC::RS232::Send data

Description
Sends data to the RS232 socket created in the ::URC::RS232::Connect procedure.

Parameters
data The data to be sent out of the socket

Return
1 if successful; 0 if unsuccessful

::URC::RS232::Close
::URC::RS232::Close

Description
Closes the connection to the RS232 socket.

Parameters
N/A

Return
1 if successful; 0 if unsuccessful

::URC::RS232::Wrap
::URC::RS232::Wrap -onClose "::onClose" -onData "::onData"

Description
Wraps event-handling procedures called by the API with user-defined procedure names.

Parameters
-onClose Wraps the ::onClose function
-onData Wraps the ::onData function

Return
N/A

45
Package URC::Timer

46
Namespace ::URC::Timer
Namespace for all Timer related functions and variables.

Event Handlers
::onTimer
::onTimer id

Description
This procedure will be called by the URC API when a timer triggers.

Parameters
id The unique id for the timer that was triggered.

Procedures
::URC::Timer::Start
::URC::Timer::Start id ms

Description
Starts a new Timer with the id and time that is passed in. If additional args are included, they will be passed onto
the ::onTimer function.

Parameters
id The unique id for the timer (this will be passed into the ::onTimer function)
ms The interval value in milliseconds

Return
N/A

Notes
It is recommended that the IDs chosen for timers be a easily readable name rather than a numeric ID. If a timer is
started with an already active ID, the timer will be cleared and restarted.

::URC::Timer::Clear
::URC::Timer::Clear id

Description
Clears a timer.

Parameters

47
 id The unique id for the timer that should be cleared

Return
1 if the timer is cleared; 0 if the timer does not exist

Notes
N/A

::URC::Timer::GetRate
::URC::Timer::GetRate id

Description
Get the current rate of a timer.

Parameters
id The id of the timer

Return
The rate (in ms) if the timer exists ; -1 if the timer does not exist

::URC::Timer::Wrap
::URC::Timer::Wrap -onTimer

Description
Wraps event-handling procedures called by the API with user-defined procedure names.

Parameters
-onTimer The name of the proc to call when a timer is triggered

Return
N/A

48
Package URC::UI

49
Namespace ::URC::UI::Set
Contains procedures used to set the more general (non-widget-specific) properties of UI widgets.

Procedures
::URC::UI::Set::Text
::URC::UI::Set::Text id text {state -1}

Description
Sets the text of any applicable widget (see Notes).

Parameters
id The ID of the widget to set .
text The text string to apply to the widget. (256-character limit)
{state} Used to set a specific state of a widget (multistate buttons only). Default value is -1 and refers to
the entire widget.

Return
N/A

Notes
For widget types: Text, Image, Button, Multi-state Button

::URC::UI::Set::Visible
::URC::UI::Set::Visible id isVisible

Description
Sets the visibility of any applicable widget (see Notes).

Parameters
id The ID of the widget to set.
isVisible The state of visibility (Boolean). [Permitted Values: 1 = Visible, 0 = Hidden]

Return
N/A

Notes
For widget types: All

::URC::UI::Set::Image
::URC::UI::Set::Image id type uri

50
Description
Sets the image of any applicable widget (see Notes).

Parameters
id The ID of the widget to set.
type The type of the image. [Permitted Values: web, custom, library]
uri The URI of the image resource.

Return
N/A

Notes
For widget types: Image

::URC::UI::Set::State
::URC::UI::Set::State id state

Description
Sets the state of any applicable widget (see Notes).

Parameters
id The ID of the widget to set.
state The state to set the button to. [Permitted Values: 0-254]

Return
N/A

Notes
For widget types: Multi-state Button

::URC::UI::Set::Size
::URC::UI::Set::Size id width height

Description
Sets the size of any applicable widget (see Notes).

Parameters
id The ID of the widget to set.
width The width in pixels.
height The height in pixels.

Return
N/A

51
Notes
For widget types: Text, Image, Button, Multi-state Button

52
Namespace ::URC::UI::Set::Image
Contains procedures used to manipulate an image or the image portion of a containing UI widget (i.e. the knob in a
slider object).

Procedures
::URC::UI::Set::Image::BtnNormal
::URC::UI::Set::Image::BtnNormal id type uri {state -1}

Description
Sets the image on the 'Normal' state of a button.

Parameters
id The ID of the widget to set.
type The type of the image. [Permitted Values: web, custom, library]
uri The URI of the image resource.
{state} Used to set a specific state of a widget (multistate buttons only). Default value is -1 and refers to
the entire widget.

Return
N/A

Notes
For widget types: Button, Multi-state Button

::URC::UI::Set::Image::BtnPressed
::URC::UI::Set::Image::BtnPressed id type uri {state -1}

Description
Sets the image on the 'Pressed' state of a button.

Parameters
id The ID of the widget to set.
type The type of the image. [Permitted Values: web, custom, library]
uri The URI of the image resource.
{state} Used to set a specific state of a widget (multistate buttons only). Default value is -1 and refers to
the entire widget.

Return
N/A

Notes
For widget types: Button, Multi-state Button

53
::URC::UI::Set::Image::BarBackground
::URC::UI::Set::Image::BarBackground id type uri

Description
Sets the Background image of any applicable widget (see Notes).

Parameters
id The ID of the widget to set.
type The type of the image. [Permitted Values: web, custom, library]
uri The URI of the image resource.

Return
N/A

Notes
For widget types: Progress Bar, Scroll Bar, Slider, Slider-Progress Hybrid

54
Namespace ::URC::UI::Set::Text
Contains procedures used to manipulate a text widget or the text portion of a containing widget (i.e. the built-in
text on a button widget).

Procedures
::URC::UI::Set::Text::Offset
::URC::UI::Set::Text::Offset id horzVal vertVal

Description
Sets the vertical and horizontal offset of text on any applicable widget.

Parameters
id The ID of the widget to set.
horzVal The horizontal offset value. [Permitted Values: Any positive or negative integer]
vertVal The vertical offset value. [Permitted Values: Any positive or negative integer]

Return
N/A

Notes
For widget types: Text, Image, Button, Multistate Button

::URC::UI::Set::Text::HorzAlign
::URC::UI::Set::Text::HorzAlign id align

Description
Sets the horizontal alignment of text on any applicable widget.

Parameters
id The ID of the widget to set.
align The horizontal alignment value. [Permitted Values: left, center, right]

Return
N/A

Notes
For widget types: Text, Image, Button, Multistate Button

::URC::UI::Set:VertAlign
::URC::UI::Set:VertAlign id align

55
Description
Sets the vertical alignment of text on any applicable widget.

Parameters
id The ID of the widget to set.
align The vertical alignment value. [Permitted Values: top, middle, bottom]

Return
N/A

Notes
For widget types: Text, Image, Button, Multistate Button

56
Namespace ::URC::UI::Set::Bar
Contains procedures used to manipulate a slider/progress/scroll bar widget.

Procedures
::URC::UI::Set::Bar::Progress
::URC::UI::Set::Bar::Progress id level

Description
Sets the progress or position on any applicable widget.

Parameters
id The ID of the widget to set.
level The value as a percentage. [Permitted Values: Whole integer from 0-100]

Return
N/A

Notes
For widget types: Progress Bar, Scroll Bar, Slider, Slider-Progress Hybrid

57
Namespace ::URC::UI::Display
Contains procedures used to display top-level visual containers that either take up the entire screen (i.e. a page)
and/or steal visual focus entirely (i.e. a pop-up).

Procedures
::URC::UI::Display::Page
::URC::UI::Display::Page pageName

Description
Displays one of the pages contained in the UI.

Parameters
pageName The name of the page to display.

Return
N/A

::URC::UI::Display::Notification
::URC::UI::Display::Notification title message btnText

Description
Displays a basic pop-up notification message window with a title, body and a single button that closes the window
when pressed.

Parameters
title The header text to display at the top of the message window.
message The body of the message. (64-character limit)
btnText The text to display on the button.

Return
N/A

::URC::UI::Display::Keyboard
::URC::UI::Display::Keyboard -text "" -ok "Ok" -cancel "Cancel" -- title

Description
Displays a pop-up keyboard.

Parameters
title The header text to display at the top of the window.

58
 -text The default keyboard text. (Default value is blank)
-ok The text to display on the Ok button. (Default value = "Ok")
-cancel The text to display on the Cancel button. (Default value = "Cancel")

Return
N/A

Notes
The parameters –ok and –cancel apply only to interfaces of type remote.

59
Namespace ::URC::UI::List
Contains all procedures for manipulating a list object.

Procedures
::URC::UI::List::Add
::URC::UI::List::Add -redraw -list0 "" -list1 "" -list2 "" -list3 "" -- id

Description
Loads up a List object with data and (optionally) redraws it.

Parameters
id The id of the List object.
-redraw Flag that redraws the list.
-list0 The list of text items to add to the list at index 0 of the List object.
-list1 The list of text items to add to the list at index 1 of the List object.
-list2 The list of text items to add to the list at index 2 of the List object.
-list3 The list of text items to add to the list at index 3 of the List object.

Return
N/A

Notes
A "List object" can essentially be thought of as a two-dimensional matrix with four columns, where each column is
one of the List object's "member lists". It is important to understand the difference between the indices of a List
object (i.e. its member lists) and the indices of a member list itself. The list data being passed to each parameter is
for populating the indices of a single member list. The position/index of the parameter determines WHICH
member list gets populated with the data. Finally, a "list item" is a set of all member list (column) values for a
single row.

::URC::UI::List::Print
::URC::UI::List::Print id {startIndex 0}

Description
Prints a List object's data to the screen.

Parameters
id The id of the List object.
{startIndex} The index at which to begin printing the list. (Default value = 0)

Return
N/A

60
::URC::UI::List::Clear
::URC::UI::List::Clear id

Description
Clears all of the data in a List object.

Parameters
id The id of the List object.

Return
N/A

::URC::UI::List::SetItem
::URC::UI::List::SetItem id text listIndex listItemIndex

Description
Sets the text of single list item.

Parameters
id The id of the List object.
text The text string to apply to the list item.
listIndex The index of the list.
listItemIndex The index of the list item.

Return
N/A

::URC::UI::List::Highlight
::URC::UI::List::Highlight id highlightIndex

Description
Highlights a single list item.

Parameters
id The id of the List object.
highlightIndex The index of the list item to be highlighted.

Return
N/A

Notes
For UI type REMOTE only.

61
Namespace ::URC::UI::Hardkey
Contains "human-friendly" reference variables for all URC device hardkey numeric values as well as procedures to
control them.

Constants
::URC::UI::Hardkey::MAIN
::URC::UI::Hardkey::VOLUP
::URC::UI::Hardkey::VOLDN
::URC::UI::Hardkey::MUTE
::URC::UI::Hardkey::CHUP
::URC::UI::Hardkey::CHDN
::URC::UI::Hardkey::PREV
::URC::UI::Hardkey::PLAY
::URC::UI::Hardkey::STOP
::URC::UI::Hardkey::PAUSE
::URC::UI::Hardkey::REW
::URC::UI::Hardkey::FF
::URC::UI::Hardkey::SKIPPLUS
::URC::UI::Hardkey::SKIPMINUS
::URC::UI::Hardkey::REC
::URC::UI::Hardkey::GUIDE
::URC::UI::Hardkey::MENU
::URC::UI::Hardkey::INFO
::URC::UI::Hardkey::EXIT
::URC::UI::Hardkey::LEFT
::URC::UI::Hardkey::RIGHT
::URC::UI::Hardkey::UP
::URC::UI::Hardkey::DOWN
::URC::UI::Hardkey::SELECT
::URC::UI::Hardkey::0
::URC::UI::Hardkey::1
::URC::UI::Hardkey::2
::URC::UI::Hardkey::3
::URC::UI::Hardkey::4
::URC::UI::Hardkey::5
::URC::UI::Hardkey::6
::URC::UI::Hardkey::7
::URC::UI::Hardkey::8
::URC::UI::Hardkey::9
::URC::UI::Hardkey::P10
::URC::UI::Hardkey::ENTER
::URC::UI::Hardkey::YELLOW
::URC::UI::Hardkey::BLUE
::URC::UI::Hardkey::RED
::URC::UI::Hardkey::GREEN
::URC::UI::Hardkey::PAGEPREV
::URC::UI::Hardkey::PAGENEXT
::URC::UI::Hardkey::COMMON
::URC::UI::Hardkey::HELP

62
Procedures
::URC::UI::Hardkey::Redirect
::URC::UI::Hardkey::Redirect keyVal {toWhere "tcl"}

Description
Redirects a hard button to Tcl so that its events can be handled in the module, or back to the firmware to be
handled via punch-through (where its events are handled by default).

Parameters
keyVal The decimal value of the hard key to be redirected. [Permitted Values: Any hardkey constants
defined in this namespace.]
{toWhere} Determines where to redirect the hard buttons to. [Permitted Values: tcl (default),
punchthrough]

Return
N/A

::URC::UI::Hardkey::Simulate
::URC::UI::Hardkey::Simulate keyVal {event "pressAndRelease"}

Description
Simulates the press/release of a hard button.

Parameters
keyVal The decimal value of the hard key to be simulated. [Permitted Values: Any hardkey constants
defined in this namespace.]
{event} The type of hard button event to simulate. [Permitted Values: press, release,
pressAndRelease (default)]

Return
N/A

63
Namespace ::URC::UI::Handler
Contains all code associated with the handling of UI events.

Event Handlers
::onButton
::onButton eventType buttonID

Description
Called by the URC API when a (soft) button is pressed.

Parameters
eventType The type of button event [Permitted Values: PRESS, RELEASE]
buttonID The id of the button that produced the event.

::onMultiStateButton
::onMultiStateButton eventType buttonID

Description
Called by the URC API when a multi-state button is pressed.

Parameters
eventType The type of button event [Permitted Values: PRESS, RELEASE]
buttonID The id of the button that produced the event.

::onHardButtonPress
::onHardButtonPress hkeyVal

Description
Called by the URC API when a hard button is pressed.

Parameters
hkeyVal The numeric value of the hard key that was pressed. (See the “Constants” section of this
namespace for reference)

::onHardButtonRelease
::onHardButtonRelease hkeyVal

Description
Called by the URC API when a hard button is released.

64
Parameters
hkeyVal The numeric value of the hard key that was released. (See the “Constants” section of this
namespace for reference)

::onSlider
::onSlider eventType sliderID sliderVal

Description
Called by the URC API when a slider is adjusted.

Parameters
eventType The type of button event [Permitted Values: DRAG, RELEASE]
sliderID The id of the slider that produced the event.
sliderVal The current value of the slider [Permitted Values: 0-100]

::onKeyboardOk
::onKeyboardOk inputString

Description
Called by the URC API when the “Ok” button is pressed on the keyboard pop-up.

Parameters
inputString The entered string of characters at the time the “Ok” button is pressed.

::onKeyboardCancel
::onKeyboardCancel inputString

Description
Called by the URC API when the “Cancel” button is pressed on the keyboard pop-up.

Parameters
N/A

::onList
::onList eventType listID topIndex selectedIndex

Description
Called by the URC API when a list is adjusted/updated.

Parameters
eventType The type of list event [Permitted Values: RELEASE,UPDATE]

65
 listID The id of the list object that produced the event.
topIndex The index of the list item at the top of the visible (on-screen) portion of the list.
(For example, if the visible portion of a list contains list items 11-15, topIndex would be
equal to 11)
selectedIndex The index of the selected list item (relative to the visible portion of the list).
(For example, if the visible portion of a list is 5 items long, then selectedIndex will
always be between 0 and 4, no matter what topIndex is.)

::onGesture
::onGesture gestureID gestureDirection

Description
Called by the URC API when the end user swipes across a gesture area.

Parameters
gestureID The id of the gesture area that produced the event.
gestureDirection The direction of the swipe [Permitted Values: UP,DOWN,LEFT,RIGHT]

::onOrientation
::onOrientation pageName orientation

Description
Called by the URC API when the orientation of a phone or tablet-style interface is changed from landscape to
portrait or vice-versa.

Parameters
pageName The name of the page to be displayed after the orientation is changed.
orientation The page orientation of the interface. [Permitted Values: LANDSCAPE,PORTRAIT]

Procedures
::URC::UI::Handler::Wrap
::URC::UI::Handler::Wrap -btn "::onButton" -multibtn "::onMultiStateButton" -
hardpress "::onHardButtonPress" -hardrelease "::onHardButtonRelease" -slider
"::onSlider" -keyboardOk "::onKeyboardOk" -keyboardCancel
"::onKeyboardCancel" -list "::onList" -gesture "::onGesture" -orientation
"::onOrientation"

Description
Wraps event-handling procedures called by the API with user-defined procedure names.

Parameters
-btn Wraps ::onButton
-multibtn Wraps ::onMultiStateButton

66
 -hardpress Wraps ::onHardButtonPress
-hardrelease Wraps ::onHardButtonRelease
-slider Wraps ::onSlider
-keyboardOk Wraps ::onKeyboardOk
-keyboardCancel Wraps ::onKeyboardCancel
-list Wraps ::onList
-gesture Wraps ::onGesture
-orientation Wraps ::onOrientation

Return
N/A

67