Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
This file describes the application and provides specific settings used by the app engine. Every application must include an app.json file in its directory. The app.json file is a single file written in JSON notation. You must use double quotes to identify object keys and values in your app.json file.
Required: The app.json file must contain the following information:
name
The name of the app. This is how the app engine refers to the app. name must be
64 chars or less, and the first character must be a letter or a digit. The rest
can be letters, digits, underscore, period, comma. We recommend all lowercase,
but that's not required.
jsFiles
The JavaScript file to load when the app starts. You may include multiple
files, they are loaded and run in left-to-right order. It is not necessary to
list language files here.
type
The type of app, which is always foreground.
Also, this information can be included as appropriate:
displayName
This is how the app name is displayed in various places (e.g., the Applications
screen). If this is not included, name is used.
iconFile
Default icon file basename. The phone looks for D70.hello_world_icon.png first,
on a D70, and likewise for other models. The icon can be dynamically set by the
app instead (or in addition), but this file will be used when the app is not
running.
hasIdle
Indicate true if the app supports an idle screen
display mode. If you don't include this, or you indicate false,
the app cannot use the idle screen. The digium.app.idleWindow object is created
based on this.
hidden
Indicate true if the app should not appear in the
Applications screen. If you don't include this, or you indicate false,
the app does appear in the Applications Screen.
{"name": "helloworld", "jsFiles": ["file1.js"], "type": "foreground", "displayName": "Hello, world!", "iconFile" : "hello_world_icon.png", "hidden" : false, "hasIdle": true } |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
The Sangoma Phone API lets you build custom apps for your phones using the popular programming language JavaScript. And the Sangoma Phone App Engine interprets and executes this JavaScript code.
Control the Display on the Phone
The user interface and interaction tools let you control the display on the phone and collect data from the user with menus and forms.
Integrate with Internet Services
You can build AJAX functionality into custom apps to allow your phones to retrieve data from or submit data to the internet (just like programming for a website).
Integrate with Your Business Applications
You can build custom apps that interact with your business applications to improve customer service and productivity.
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
The D-Series Phone API is a JavaScript toolset used to build custom apps.
At its most basic, a custom app is a zip file that contains an app.json file and a JavaScript file.
An app is packaged into a zip file. The zip contains the app.json file, JavaScript file, and additional data (icons, language files, etc.).
A Sangoma Phone uses the zip file to install the app.
Each app requires a JSON file named app.json. The JSON file describes to the Sangoma Phone App Engine what the app is and what its settings are. See the article app.json for details.
The following are the principal phone API modules comprising the toolset:
· Core - Basic building blocks of any Sangoma Phone app. Used for functional programming.
· Classes - Core classes available to every app. Used for functional programming.
· Extended - Libraries to add additional functional methods to a Sangoma Phone app.
· Extended Classes - Additional libraries to add more functional class constructors.
· UI Core (window) - Automatically defined object that enables app display for every app at runtime.
· UI Classes (Widgets) - Basic graphical building blocks (class constructors).
· UI Extended - Additional tools for building user interaction into your app.
· UI Extended Classes - Additional UI class constructors for creating more than basic UI elements.
Links to these modules and their libraries are in the sidebar. See the Getting Started page and the other Guides for general instructions, and the Phone API Demos for annotated sample programs to give you custom app examples.
The phone app programming model is single-threaded, event-driven. Avoid long-running processing loops because they limit the responsiveness of apps, and after a few seconds, they will cause your app to be killed.
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
These core object constructors are available to all apps without requiring any libraries. Objects relating to UI elements are documented in UI Classes (Widgets).
|
Name |
Description |
|
Makes HTTP and similar requests from JavaScript. This object is similar to the standard browser XMLHttpRequest object. |
|
|
Similar to the standard DOMParser. Used to parse an XML string into a DOM document that can be traversed and manipulated in the usual ways (getElementById(), appendChild(), etc). |
|
|
Similar to standard XMLSerializer. Used to convert a DOM document into a valid XML string. |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Similar to the standard DOMParser. Used to parse an XML string into a DOM document that can be traversed and manipulated in the usual ways (getElementById(), appendChild(), etc).
Create a new DOMParser object.
var parser = new DOMParser(); |
|
None |
|
Name |
Description |
|
Parse a string into a standard DOM Document. |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Parse a string into a standard DOM Document.
Basic Example:
var parser = new DOMParser(); var document = parser.parseFromString('<config><test attr="value" /></config>'); |
Parameters
|
Name |
Required |
Type |
Default |
Description |
|
xml |
Yes |
string |
String containing valid XML. |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Makes HTTP and similar requests from JavaScript. This object is similar to the standard browser XMLHttpRequest object.
new NetRequest()
Constructs a new NetRequest Object.
var request = new NetRequest(); |
|
None |
|
Name |
Description |
|
Returns the header field value from the response of which the field name matches header, unless the field name is Set-Cookie or Set-Cookie2. Returns null if either the response has not yet been received or the header doesn't exist in the response. |
|
|
Sets the request method and request URL. This method differs from the standard XMLHttpRequest's open() method by only accepting two parameters (all requests are asynchronous, and the user/password are entered in the request object's user and password properties.) |
|
|
Initiates the request. The optional argument provides the request entity body. The argument is ignored if request method is GET or HEAD. |
|
|
Appends a header to the list of author request headers, or if header is already in the list of author request headers, combines its value with value. |
|
|
Sets a timeout, after which the request will be aborted with a 500 status. |
|
Name |
Description |
|
oncomplete |
Called at the end of the response. This is redundant to onreadystatechange with readyState=4. Basic Example: request.oncomplete = function() { util.debug('request is done'); } |
|
onreadystatechange |
Event handler for readyState. Basic Example: request.onreadystatechange = function () {util.debug(request.readyState); util.debug(request.status); } |
|
password |
Password used in the request, or null if there is no password. Basic Example: request.password = 'secret'; |
|
readyState |
Returns the current state. Basic Example: var currentState = request.readyState; // returns integer such as 200 |
|
responseFile |
If present, along with responseLoc, the response body is placed in the file rather than in responseText. Basic Example: request.responseFile = "text.txt"; |
|
responseLoc |
If present, along with responseFile, the response body is placed in the file rather than in responseText. Basic Example: request.responseLoc = "tmp"; |
|
responseText |
Returns the text response entity body. Basic Example: var response = request.responseText; |
|
status |
Returns the HTTP status code; such as 200 (success), 500 (internal server error), 404 (file not found), etc.. Basic Example: var statusCode = request.status; |
|
user |
Returns the name of the user in the request, or null if there is no username. Sets the user for the request. Basic Example: request.user = "username"; //set username for request request.user; //"username" |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Returns the header field value from the response of which the field name matches header, unless the field name is Set-Cookie or Set-Cookie2. Returns null if either the response has not yet been received or the header doesn't exist in the response.
Basic Example:
var headerValue = request.getResponseHeader(header); |
|
Name |
Required |
Type |
Default |
Description |
|
header |
Yes |
string |
Name of the header as expected from the response. |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Sets the request method and request URL. This method differs from the standard XMLHttpRequest's open() method by only accepting two parameters (all requests are asynchronous, and the user/password are entered in the request object's user and password properties.)
Basic Example:
request.open(method, url); |
|
Name |
Required |
Type |
Default |
Description |
|
url |
Yes |
string |
URL to send the request to. |
|
|
method |
Yes |
string |
HTTP method to use; such as GET or POST. |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Initiates the request. The optional argument provides the request entity body. The argument is ignored if request method is GET or HEAD.
Basic Example:
request.send(); |
|
None |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Appends a header to the list of author request headers, or if header is already in the list of author request headers, combines its value with value.
Basic Example:
request.setRequestHeader(header, value); |
|
Name |
Required |
Type |
Default |
Description |
|
header |
Yes |
string |
Name of the header to set. |
|
|
value |
Yes |
string |
The value to set for the header |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Sets a timeout, after which the request will be aborted with a 500 status.
Basic Example:
request.setTimeout(milliseconds). |
|
Name |
Required |
Type |
Default |
Description |
|
milliseconds |
Yes |
integer |
Integer representing time greater than zero in milliseconds. |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Similar to standard XMLSerializer. Used to convert a DOM document into a valid XML string.
Creates a new XMLSerializer object
var serializer = new XMLSerializer(); |
|
None |
|
Name |
Description |
|
serializeToString |
Serialize a DOM document object to an XML string. Basic Example: var serializer = new XMLSerializer(); var xml = serializer.serializeToString(document); Name Required Type Default Description document Yes DOM document object. |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
These core functions are available to all apps without requiring any libraries. They provide functionality to interact with the application environment, invoke phone functions, etc.
|
Name |
Description |
|
Used to include and evaluate other scripts. Anything exported by a required script is then made available using require. |
|
|
Object used to provide functions, variables, and properties for use by another script. Use require in another script to obtain the exports in the current script. Exports will not work if you set exports = to an object (e.g., {"key" : "value" }). You must set properties of the exports object as can be seen in the example. |
|
|
Handles application launching/hiding, system event listeners, phone functions, and file I/O. |
|
|
Contains methods and properties about the phone's applications. |
|
|
Used to create applications that register event listeners by calling digium.event.observe() and specifying one of the event names as the eventName parameter. Also used to trigger an event with digium.event.fire() and to remove callbacks for an event with digium.event.stopObserving(). |
|
|
Call handling. |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Contains methods and properties about the phone's applications.
|
Name |
Description |
|
Returns the current Image object for the specified app. |
|
|
Returns an object with information about the specified app, as defined in its app.json file. |
|
|
Returns an array containing the names of apps that the system knows about. The names are defined in app.json. |
|
Name |
Description |
|
digium.app.config.xml |
A string containing the XML representing the app's configuration (appconfig) settings from the phone's master configuration xml. These are limited to app-specific settings distributed from the phone's configuration server. Basic Example: digium.app.config.xml; //returns '<appconfig id="test.my_app"><settings /></appconfig>' |
|
digium.app.exitAfterBackground |
An app will start up each time it is placed in the foreground and shut down each time it is placed in the background. This Boolean property sets whether or not the app shuts down (exits) when it goes into the background. The default setting is true; i.e., the app shuts down when it goes into the background. Change the setting to false to make your app run persistently. Basic Example: digium.app.exitAfterBackground = false; //now it won't shut down when backgrounded |
|
digium.app.iconFile |
Get or set the filename of the icon image used for this application. The icon is used in other apps such as the app manager screen and is contained in the app's directory. Basic Example: // Let's assume your app.json file inits your app with the iconFile "myapp_no_msgs.png"; var currentIcon = digium.app.iconFile; // returns "my_app_no_msgs.png"; // Your app then may be running in the background and when it gets a message you want to // update the iconFile to provide an indicator to the Apps screen. // this could be set in some sort of call back function digium.app.iconFile = "my_app_msgs_waiting.png"; // now if you go to the Apps screen (press the Apps button on the D70) you will see the icon has changed. currentIcon = digium.app.iconFile; // returns "my_app_msgs_waiting.png"; If your app is initialized for the first time, digium.app.iconFile is set to the iconFile from the app.json file. If setting the iconFile, the {MODEL}.iconFile naming convention should be used for whichever iconFile you are setting. |
|
digium.app.idleWindowShown |
Boolean flag reflecting whether the the app's idle screen window is currently displayed. |
|
digium.app.inForeground |
Boolean value indicating whether this app is in the foreground. |
|
Get the name of the app as specified in the app's app.json file. |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Returns the current Image object for the specified app.
|
Name |
Required |
Type |
Default |
Description |
|
app_name |
Yes |
string |
Name of the app to act on as defined in its app.json file. |
digium.app.getIcon
digium.app.getIcon('contacts'); |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Returns an object with information about the specified app, as defined in its app.json file.
Basic Example:
var appInfo = digium.app.getInfo(app_name); |
|
Name |
Required |
Type |
Default |
Description |
|
app_name |
Yes |
string |
Name of the app to act on as defined in its app.json file. |
digium.app.getInfo with the return object
digium.app.getInfo('contacts');/* returns: { 'name' : 'contacts', 'displayName' : 'Contacts', 'iconFile' : 'app_contacts.png', 'running' : true 'hidden' : true } */ |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Puts the app in the background, returning the screen to its regular state
(e.g., idle).
Basic Example:
digium.background(); |
When an app is put in the background, unless the digium.app.exitAfterBackground property is set to false, the app will shutdown.
|
None |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Handles application launching/hiding, system event listeners, phone functions, and file I/O.
|
Name |
Description |
|
Puts the app in the background, returning the screen to its regular state (e.g., idle). |
|
|
Brings an app into the foreground. If this is called without any arguments, it brings the current app to the foreground. |
|
|
Reads the contents of a file as utf-8 and returns the contents as a string. The filename is relative to the location that is specified (this is a flat directory). |
|
|
Resets the timeout that causes the phone to hide apps when there's no keyboard input for a while. This keeps the app alive and should be called periodicallly to prevent the app from being timed out. |
|
|
Indicates to the app to reboot itself. |
|
|
This function can be used to change the state of one of the phone's LED lights. |
|
|
Writes the string into a file. The filename is relative to the location that is specified (this is a flat directory). |
|
Name |
Description |
|
digium.phoneModel |
This property is set to a string that represents the model of the phone (D40, D45, D50, D60, D62, D65, D70). |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Used to create applications that register event listeners by calling digium.event.observe() and specifying one of the event names as the eventName parameter. Also used to trigger an event with digium.event.fire() and to remove callbacks for an event with digium.event.stopObserving().
|
Name |
Description |
|
Fire an event of the given eventName and pass your eventData onto any callback that may be observing the event. Note: the list of Digium eventNames cannot be fired except by the system. |
|
|
Set a callback function to be fired when the request eventName fires. |
|
|
Used to remove callbacks for an event. If callback is not passed in (which is a reference to the original observed callback), then all observed events are removed for the specified eventName. |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Fire an event of the given eventName and pass your eventData onto any callback that may be observing the event. Note: the list of Digium eventNames cannot be fired except by the system.
Basic Example:
digium.event.fire(parameters); |
|
Name |
Required |
Type |
Default |
Description |
|
eventName |
Yes |
string |
String that identifies the event type. Event type can either be from this list if you are using digium.event.observe, or from your own list if you're using digium.event.fire to fire your own event. |
|
|
eventData |
Yes |
object |
Object passed to any callbacks listening for this event. eventData can contain a 'callback' property that will be executed when an event named eventName.response (for example, contacts.forwardVM.response) is sent with the same messageId. |
|
|
messageId |
No |
object |
Unique ID for the message. If messageId is not specified one will be generated automatically. |
A full list of system eventNames can be found here
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Set a callback function to be fired when the request eventName fires.
Basic Example:
digium.event.observe(parameters); |
|
Name |
Required |
Type |
Default |
Description |
|
eventName |
Yes |
string |
String that identifies the event type. Event type can either be from this list if you are using digium.event.observe, or from your own list if you're using digium.event.fire to fire your own event. |
|
|
callback |
No |
object |
Called when an event arrives and contains an Object with the following: · callHandle - the string identifying the call. This is only present when the notification is attached to an incoming call. · method - the SIP method type used to deliver the message. INFO, INVITE, or MESSAGE. · eventName - the string identifying the pushed event type · eventData - data associated with the message (from the x-event-data header or the body of an INFO or MESSAGE). If data can be parsed as JSON, the parsed object is used; otherwise, this field contains a string. · messageId - ID string for the event. |
A full list of system eventNames can be found here.
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Used to remove callbacks for an event. If callback is not passed in (which is a reference to the original observed callback), then all observed events are removed for the specified eventName.
Basic Example:
digium.event.stopObserving(parameters); |
|
Name |
Required |
Type |
Default |
Description |
|
eventName |
Yes |
string |
String that identifies the event type. Event type can either be from this list if you are using digium.event.observe, or from your own list if you're using digium.event.fire to fire your own event. |
|
|
callback |
No |
object |
Callback (OPTIONAL) to remove from the event listener. If this parameter is undefined, all callbacks registered to eventNamewill be removed. |
A full list of system eventNames can be found here.
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
App Events
|
digium.app.background |
Called when an application is about to be put in the background. |
|
digium.app.exit |
Called when an application is about to shut down. |
|
digium.app.foreground |
Called when the application is put into the foreground. The application name and any arguments from appconfig will be passed as arguments to the callback. |
|
digium.app.idle_screen_hide |
Called with no arguments when the app idlescreen window is hidden in the GUI. |
|
digium.app.idle_screen_show |
Called with no arguments when the app idlescreen window is displayed by the phone GUI. |
|
digium.app.start |
Called when the app first starts up. |
Phone Events
|
digium.phone.contact_presence |
Called whenever a subscribed user updates his/her presence information. |
|
digium.phone.contact_update |
Called when new contact information is received from the server. The app then rebuilds any data structures based on the result of digium.contacts.getList(). |
|
digium.phone.icon_change |
Called whenever an application changes its icon. Callback will be passed the name of the application in the eventData parameter. |
|
digium.phone.app_install |
Called when an application is installed or reinstalled. Callback will be passed the name of the application in the eventData parameter. |
|
digium.phone.incoming_call |
Called to notify of an incoming phone call. The eventData properties are the same as those given to a handler in the digium.phone api. |
|
digium.phone.mwi |
Called when a Message Waiting Indicator arrives. For example, a voicemail notification. |
|
digium.phone.new_config |
Called when the phone's configuration file has changed. |
|
digium.phone.outgoing_call |
Called to notify of an outgoing phone call. The eventData properties are the same as those given to a handler in the digium.phone api. |
|
digium.phone.play_status |
Called about every second while an audio file is playing, to give status. Also called when playback stops. |
|
digium.phone.server_change |
Called to provide failover status for accounts. |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Brings an app into the foreground. If this is called without any arguments, it brings the current app to the foreground.
Basic Example:
|
|
Note: The app needs to be running for this to do anything.
|
app_name |
No |
string |
|
Name of the app to act on as defined in its app.json file. |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Answers an incoming call.
Basic Example:
digium.phone.answer(parameters); |
If a function is passed in the handler parameter, that function is called with a call status object to notify of state changes to the phone call.
|
Name |
Required |
Type |
Default |
Description |
|
callHandle |
Yes |
string |
Identifier of the call to act on. A call handle can be obtained by observing call events. Information such as this will be passed into the event object. |
|
|
handler |
No |
function |
Handler to register for the call. Executed whenever the call changes state. |
digium.phone.answer with util.debug to print call state
digium.phone.answer({ 'callHandle' : callHandleVar, 'handler' : function (obj) { util.debug(obj.state); //prints the state of the call } }); |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Initiates a call. This function returns a call handle, which is a string identifying the call. It can be used in various other methods such as digium.phone.hangup.
Basic Example:
digium.phone.dial(parameters); |
If a function is passed in the handler parameter, that function is called with a call status object to notify of state changes to the phone call.
|
Name |
Required |
Type |
Default |
Description |
|
number |
Yes |
string |
Number to dial. |
|
|
url |
No |
string |
SIP URL to call (e.g., [email protected]). This can be used instead of a number. Only one of the two are required. |
|
|
headers |
No |
object |
Object with header values to set in the call's INVITE. |
|
|
accountSlot |
No |
integer |
ID for the account. |
|
|
handler |
No |
function |
Handler to register for the call. Executed whenever the call changes state. |
digium.phone.dial with util.debug for state of the call
digium.phone.dial({'number' : 100, 'handler' : function (obj) {util.debug(obj.state); //prints the 'state' of the call } }); |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Call handling.
|
Name |
Description |
|
Answers an incoming call. |
|
|
Initiates a call. This function returns a call handle, which is a string identifying the call. It can be used in various other methods such as digium.phone.hangup(). |
|
|
Hangs up on an ongoing call. |
|
|
Attaches handlers to ongoing-call status changes. Useful if you were unable to attach a handler when the call was created. |
|
|
Ignores (rejects) an incoming call before it is answered. |
|
|
Sends DTMF tones in an ongoing call. |
|
|
Transfers an active call to another extension. This is a blind transfer, meaning the transferor does not talk to the transferee. |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Hangs up on an ongoing call.
Basic Example:
digium.phone.hangup(parameters); |
If a function is passed in the handler parameter, that function is called with a call status object to notify of state changes to the phone call.
|
Name |
Required |
Type |
Default |
Description |
|
callHandle |
Yes |
string |
Identifier of the call to act on. A call handle can be obtained by observing call events. Information such as this will be passed into the event object. |
|
|
handler |
No |
function |
Handler to register for the call. Executed whenever the call changes state. |
digium.phone.hangup with until.debug to print call state
digium.phone.hangup({'callHandle' : callHandleVar, 'handler' : function (obj) {util.debug(obj.callHandle); } }); |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Attaches handlers to ongoing-call status changes. Useful if you were unable to attach a handler when the call was created.
The function passed in the handler parameter is called with a call status object to notify of state changes to the phone call.
|
Name |
Required |
Type |
Default |
Description |
|
handler |
Yes |
function |
Handler to register for the call. Executed whenever the call changes state. |
|
|
callHandle |
Yes |
string |
Identifier of the call to act on. A call handle can be obtained by observing call events. Information such as this will be passed into the event object. |
digium.phone.observeCallEvents with util.debug to print call state
digium.phone.observeCallEvents({'callHandle' : callHandleVar, 'handler' : function (obj) {util.debug(obj.state); } }); |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Ignores (rejects) an incoming call before it is answered.
Basic Example:
digium.ohone.reject(parameters); |
If a function is passed in the handler parameter, that function is called with a call status object to notify of state changes to the phone call.
|
Name |
Required |
Type |
Default |
Description |
|
callHandle |
Yes |
string |
Identifier of the call to act on. A call handle can be obtained by observing call events. Information such as this will be passed into the event object. |
|
|
handler |
No |
function |
Handler to register for the call. Executed whenever the call changes state. |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Sends DTMF tones in an ongoing call.
Basic Example:
digium.phone.sendDTMF(parameters); |
Parameters
|
Name |
Required |
Type |
Default |
Description |
|
digit |
Yes |
string |
Digit 0-9, a letter from A-D, *, or #. |
|
|
duration |
No |
integer |
Length of time in milliseconds to play the tone. |
digium.phone.sendDTMF with a tone to play
digium.phone.sendDTMF({'duration' : 5000, 'digit' : 5 }); |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Transfers an active call to another extension. This is a blind transfer, meaning the transferor does not talk to the transferee.
Basic Example:
digium.phone.transfer(parameters); |
If a function is passed in the handler parameter, that function is called with a call status object to notify of state changes to the phone call.
|
Name |
Required |
Type |
Default |
Description |
|
callHandle |
Yes |
string |
Identifier of the call to act on. A call handle can be obtained by observing call events. Information such as this will be passed into the event object. |
|
|
number |
Yes |
string |
Number to dial. |
|
|
handler |
No |
function |
Handler to register for the call. Executed whenever the call changes state. |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
If a handler is passed to call-related actions, that handler is called whenever the state of the call changes.
The handler is called with one argument, a call status object with the following fields:
·
state - SIP state of the call. One of
"CALLING", "INCOMING", "EARLY",
"CONNECTING", "CONFIRMED", "DISCONNECTING",
"DISCONNCTD".
· accountSlot - Identifier for the line the call is coming in on.
· callHandle - Identifier for the call. This will match the call handle returned by digium.phone.dial, for example.
· remoteInfo - SIP url for the remote end of the call.
· remoteContact - SIP contact header for the remote end of the call.
· lastStatus - Most recent SIP status code associated with the call, or "0".
· lastStatusText - Most recent text associated with status code.
·
mediaStatus - Describes the current audio data flow.
One of "none", "active", "local_hold",
"remote_hold", or "error".
· headers - Object mapping SIP headers to their values.
However, if there's an api-level error (e.g., the callHandle is invalid, you are trying to make a call when there's already an active call, etc.), these are available instead:
· state - Has the value "ERROR".
· callHandle - Identifier for the call.
· errorText - Human readable error message (not for display to end users).
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Reads the contents of a file as utf-8 and returns the contents as a string. The filename is relative to the location that is specified (this is a flat directory).
Basic Example:
digium.readFile(location, file); |
Parameters
|
Name |
Required |
Type |
Default |
Description |
|
location |
Yes |
string |
Read-only location parameters: app The app's own directory (so you can read files
included in the app's zip file). Read and write location parameters: nv Non-volatile storage. Data stored here
survives firmware updates. |
|
|
filename |
Yes |
string |
Name of the file to act on. |
Using digium.readFile / digium.writeFile to store settings.
/* Here are two simple functions for working with JSON / and a JavaScript object to store some settings information. We use the readFile and writeFile method to store a string and use the native JSON JavaScript object to parse and stringify it. */ //settings object passed in, let's assume it looks like {"name" : "Bob", "location" : "USA"}function saveSettings (settings) {var settingsString = JSON.stringify(settings); //write our settings in non-volatile storage so they are preserved. digium.writeFile("nv", "my_app_settings.json", settingsString);} function readSettings () { var settings = {};// we wrap loading this file in a try catch because we are not sure if it exists yet or not. // if it doesn't the app engine will throw an exception halting execution. // this is also why we initialize the settings object above. // If this errors we will return the empty object try { var settingsString = digium.readFile("nv", "my_app_settings.json");settings = JSON.parse(settingsString); } catch (error) { util.debug("my_app_settings.json file does not exist yet");} //return our settings object return settings; } |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Resets the timeout that causes the phone to hide apps when there's no keyboard input for a while. This keeps the app alive and should be called periodicallly to prevent the app from being timed out.
Basic Example:
|
|
If an app is idle for 30 seconds without this function being called, the app will go to the background and the screen will return to idle.
|
None |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Indicates to the app to reboot itself.
Basic Example:
|
|
Note: The digium.app.exit event is fired as the app is about to shutdown. If your app is state dependent, you may need to record some information.
|
None |
digium.restart example
|
|
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
This function can be used to change the state of one of the phone's LED lights.
Basic Example:
digium.setLedState(parameters); |
This function can be used to change the state of one of the phone's LED lights. An app can only control LEDs when it is in the foreground; once it goes into the background, the phone gui will return all LEDs to its default behavior. When an app sets its first LED, all other LEDs will be turned off. The app is then responsible for all LED settings until it is backgrounded. When an app returns to the foreground, it will need to set the LEDs to its desired state again (generally in its onforeground handler).
|
Name |
Required |
Type |
Default |
Description |
|
name |
Yes |
string |
The name of the LED to target. Possible values are as follows: · msg (Voicemail Indicator light) · hdst (headset), spkr (speaker), mute · line[n] (line number [1-6] with n being a number. E.G. line1) · blf[n] (blf line [1-10] with n being a number. E.G. blf1) |
|
|
color |
Yes |
string |
Which color to activate for the LED. Possible choices are green, red and amber. |
|
|
state |
Yes |
string |
Which state the LED should be set as. Possible options are: · on · off · fast (fast blink) · slow (slow blink) |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Writes the string into a file. The filename is relative to the location that is specified (this is a flat directory).
digium.writeFile(location, filename, string); |
If the file exists, it is overwritten with the string. If the file does not exist, it is created.
|
Name |
Required |
Type |
Default |
Description |
|
location |
Yes |
string |
Read-only location parameters: app The app's own directory (so you can read files
included in the app's zip file). Read and write location parameters: nv Non-volatile storage. Data stored here
survives firmware updates. |
|
|
filename |
Yes |
string |
Name of the file to act on. |
|
|
string |
Yes |
string |
String to act on. |
Using digium.readFile / digium.writeFile to store settings.
/* Here are two simple functions for working with JSON / and a JavaScript object to store some settings information. We use the readFile and writeFile method to store a string and use the native JSON JavaScript object to parse and stringify it. */ //settings object passed in, let's assume it looks like {"name" : "Bob", "location" : "USA"}function saveSettings (settings) {var settingsString = JSON.stringify(settings); //write our settings in non-volatile storage so they are preserved. digium.writeFile("nv", "my_app_settings.json", settingsString);} function readSettings () { var settings = {};// we wrap loading this file in a try catch because we are not sure if it exists yet or not. // if it doesn't the app engine will throw an exception halting execution. // this is also why we initialize the settings object above. // If this errors we will return the empty object try { var settingsString = digium.readFile("nv", "my_app_settings.json");settings = JSON.parse(settingsString); } catch (error) { util.debug("my_app_settings.json file does not exist yet");} //return our settings object return settings; } |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Object used to provide functions, variables, and properties for use by another script. Use require in another script to obtain the exports in the current script.
Exports will not work if you set exports = to an object (e.g., {"key" : "value" }). You must set properties of the exports object as can be seen in the example.
Require Extended Library:
exports.test = "test"; |
var example2 = {};example2.init = function () {this.status = 'Status set by example2.init()'; }; example2.getStatus = function () {return this.status; }; example2.setStatus = function (param) {this.status = param; }; example2.init(); exports.getStatus = example2.getStatus.bind(example2); exports.setStatus = example2.setStatus.bind(example2); |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Used to include and evaluate other scripts. Anything exported by a required script is then made available using require.
When require is called, the app engine first checks for the required script in the current directory. If a script with the specified name is not found, it will check the shared lib directory (which contains most predefined modules such as app, util, screen, etc.).
The first time a script is required in an app, it is evaluated and then the exports are returned. If that script is required somewhere else in the same app, a reference to the object created from the first require is returned rather than evaluating the script again.
The following example code includes the util javascript module, which makes all exported util methods then available, including util.isDef, util.forceArray, etc.
var app = require('util');var foo = util.isDef(bar); //foo = false exampleArray = util.forceArray('test'); //exampleArray = ['test'] |
Note: Required JavaScript files are referenced by their filename without the .js extension.
The same script can be required from multiple places in an application, and the file is evaluated the first time. For example, if your app is written in four JavaScript files, you can require a specific one of them in all of them. This allows different parts of an application to share data and methods.
As an example, see the following app, which is split into three scripts: example1.js, example2.js, and example3.js. The following is its app.json file:
{"name": "test", "jsFiles": ["example1.js"], "type": "foreground", } |
1. When the app is started, example1.js requires both example2.js and example3.js (and example3.js, in turn, also references example2.js). When example2.js is evaluated, its init() function assigns a value to the 'status' property of 'Status set by example2.init()'
2. This value is saved to the variable 'foo' in example1.js
3. example2.setStatus() is used to change the value of example2.status to 'Status reset by example1.js'
4. When the 'bar' variable is set to the result of the example3.getStatus() function, you can see that the 'example2' object referenced in both example1.js and example3.js is actually the same object.
var example2 = require('example2');var example3 = require('example3');var foo = example2.getStatus(); //foo = 'Status set by example2.init()' example2.setStatus('Status reset by example1.js');var bar = example3.getStatus(); //bar = 'Status reset by example1.js' |
var example2 = {};example2.init = function () {this.status = 'Status set by example2.init()'; }; example2.getStatus = function () {return this.status; }; example2.setStatus = function (param) {this.status = param; }; example2.init(); exports.getStatus = example2.getStatus.bind(example2); exports.setStatus = example2.setStatus.bind(example2); |
var example2 = require('example2');var example3 = {};example3.getStatus = function () {return example2.getStatus(); }; exports.getStatus = example3.getStatus.bind(example3); |
Parameters
|
Name |
Required |
Type |
Default |
Description |
|
JavaScript module |
Yes |
JavaScript module to include. |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Returns an array containing the names of apps that the system knows about. The names are defined in app.json.
Basic Example:
digium.app.getList(); |
|
None |
digium.app.getList example
var appList = digium.app.getList(); // Example output util.debug(JSON.stringify(appList)); /* outputs something that looks like the following ["appscreen","bootconfig","contacts","parking","phonemenu","queues","status", "techsupport","voicemail","myname.test_app"] */ |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Apps can include these libraries to access additional functionality. Unlike the core functions, they are not available to apps without first requiring a specific library.
|
Name |
Description |
|
Loads and saves standard settings that can be later accessed and used across the application by other modules, screens, etc. Note: the app should always have its init() method called after being included. |
|
|
Contains 'helper' functions useful for development. |
|
|
Object used to send API requests to the PBX. |
|
|
Library that aids in the processing of date strings, appropriate to the cultural differences for the user of the app, for display purposes. |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Takes a parameters object and a required keys array and compares the two. If any keys are missing from the array, then an error is logged and the error screen is shown (app.showErrors).
Basic Example:
var app = require('app');app.init(); app.checkRequired(parameters); |
Parameters
|
Name |
Required |
Type |
Default |
Description |
|
p |
Yes |
object |
This is an object containing key value pairs. |
|
|
required |
Yes |
array |
Array of keys that are checked against the keys of the p object. |
Error screen shown after failing checkRequired
The required parameter ['test'] was not a key in the 'p' object passed in.
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Loads and saves standard settings that can be later accessed and used across the application by other modules, screens, etc. Note: the app should always have its init() method called after being included.
Require Extended Library:
var app = require('app');app.init(); |
|
Name |
Description |
|
Takes a parameters object and a required keys array and compares the two. If any keys are missing from the array, then an error is logged and the error screen is shown (app.showErrors). |
|
|
Returns a reference to the automatically instantiated Auth object that is created when app.init is called. |
|
|
Returns an object that contains this app's various settings including id, settings, and account. These are parsed from the app's XML in the phone configuration's appconfig section. |
|
|
Initializes the app object. Important: this should be done immediately after including the app library for consistent results. |
|
|
Reloads your appconfig and makes a new Auth object. |
|
|
Clears the screen and shows an error popup on the entire screen. Takes an array of error messages so you can show multiple messages at one time. |
|
|
Returns the translated string of the specified language key. |
|
Name |
Description |
|
app.images |
Automatically instantiated Image UI objects when app is required. Basic Example: app.images.softKeys.left; // returns left arrow Image object app.images.softKeys.right; // returns left arrow Image object app.images.softKeys.up; // returns left arrow Image object app.images.softKeys.down; // returns left arrow Image object app.images.softKeys.select; // returns the check mark image app.images.softKeys.cancel; // returns left x cancel image These most likely useful for creating apps with standarized softkeys. See setSoftKeyIcon for setting softKey icons on your widgets. |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Returns a reference to the automatically instantiated Auth object that is created when app.init is called.
Basic Example:
var authObj = app.getAuth(); |
Parameters
|
None |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Returns an object that contains this app's various settings including id, settings, and account. These are parsed from the app's XML in the phone configuration's appconfig section.
Basic Example:
var configData = app.getConfig(); |
|
None |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Initializes the app object. Important: this should be done immediately after including the app library for consistent results.
Basic Example:
app.init([parameters]); |
|
Name |
Required |
Type |
Default |
Description |
|
onError |
No |
function |
Overloads if your application wants to handle error specifically. |
|
|
defaultLangLocale |
No |
string |
Indicates the language file to use if the app does not have a language file for the phone's chosen language. For example, if the chosen language/locale is fr_fr, but the app does not include the file strings.fr_fr.js, then the app uses the default language file as indicated with this parameter. If no value has been defined, the phone tries to use en_us. |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Reloads your appconfig and makes a new Auth object.
Basic Example:
app.refreshConfig(); |
The app library automatically calls this on itself when the event 'digium.phone.new_config' happens. This makes sure your settings and Auth object are always up to date.
|
None |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Returns the translated string of the specified language key.
Basic Example:
var text = app.t(key[, vars, count]); |
|
Name |
Required |
Type |
Default |
Description |
|
key |
Yes |
string |
The language key used to fetch a string. If no string is found for the key, then the key is returned as the string. |
|
|
vars |
No |
array |
An array of variables to use for substitution in your string. For example, if your string is "This %s belongs to %s" and you pass ['Pizza', 'Bob'] for vars, the string returned will be "This Pizza belongs to Bob". |
|
|
count |
No |
integer |
1 |
The integer to use for pluralization. This is used if you provide different forms of your string based on the pluralization. For example, your lang key might define the following ['I have one index', 'I have many indices']. If you pass a value of 1 for vars then the first string will be returned by the translate function, if you pass a value of more than 1, then the second form will be returned. |
Various examples of app.t
/* For the purpose of this example, lets assume we have included a strings-en_us.js file in our package and it looks like this. This covers each combination of ways the translation library can be used. exports.keys = { "T_HELLO_WORLD" : ["Hello World"], "T_MY_NAME_IS" : ['My Name is %s"], "T_DOG" : ["Dog", "Dogs"], "T_PERSON_PPL" : ["I employ %s person", "I employ %s people."], "T_MY_ADDRESS" : ["My address is %s; %s, %s %s"] }; */ app.t("T_HELLO_WORLD"); // returns "Hello World"app.t("T_MY_NAME_IS", ["Ryan"]); // returns "My Name is Ryan"app.t("T_DOG", [], 1); // returns "Dog"app.t("T_DOG", [], 2); // returns "Dogs"app.t("T_PERSON_PPL", [1], 1); // returns "I employ 1 person."app.t("T_PERSON_PPL", [3], 3); // returns "I employ 3 people."app.t("T_MY_ADDRESS". ["12 Brown St.", "San Diego", "CA", "91211"]); // returns "My address is 12 Brown St.; San Diego, CA 91211" |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Sets an image object to display at the top left corner of the softkey. Useful for indicating a hard key that calls the same handler. Suggested image size is 5x5 pixels.
Basic Example:
exampleObj.setSoftkeyIcon(keyNum, icon); |
If you require the app library, you can use Digium's set of softkey icons. These image objects are created when the library is required.
· app.images.softKeys.left (left arrow)
· app.images.softKeys.right (right arrow)
· app.images.softKeys.up (up arrow)
· app.images.softKeys.down (down arrow)
· app.images.softKeys.select (check mark)
· app.images.softKeys.cancel (X)
|
Name |
Required |
Type |
Default |
Description |
|
keyNum |
Yes |
integer |
Softkeys are labeled 1-4. |
|
|
icon |
Yes |
widget |
Instance of a image widget for display. |
setSoftkeyIcon to set icons for the softkeys: Digium up arrow, Digium checkmark, custom icon
testWidget.setSoftkeyIcon(1, app.images.softKeys.up); testWidget.setSoftkeyIcon(2, app.images.softKeys.select); var imgWidget = new Image("app", "smileyface.png", 0, 0, 5, 5);testWidget.setSoftkeyIcon(3, imgWidget); |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Library that aids in the processing of date strings, appropriate to the cultural differences for the user of the app, for display purposes.
Require Extended Library:
var localization_date = require('localization_date'); |
|
Name |
Description |
|
Formats an RFC822 or ISO 8601 date string and displays a localized date based on the phone's preferred locale. For example, take the thirtieth day in the month of April for the year 2013. For the US locale, the phone would display 04/30/2013. If your phone's localization setting were set to the UK and you used this library, your display would read 30/04/2013. |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Formats an RFC822 or ISO 8601 date string and displays a localized date based on the phone's preferred locale.
For example, take the thirtieth day in the month of April for the year 2013. For the US locale, the phone would display 04/30/2013. If your phone's localization setting were set to the UK and you used this library, your display would read 30/04/2013.
Basic Example:
var formattedDate = localization_date.format(parameters); |
Additional display behaviors:
· Current day, returns the time.
· Day previous, returns Yesterday.
· Within the last seven days, returns day of the week (i.e., Monday).
· More than seven days in the past returns a short or long date, in the format associated with the phone's chosen locale.
|
Name |
Required |
Type |
Default |
Description |
|
date |
Yes |
string |
2020-04-30 10:58:01 |
RFC822 or ISO 8601 date string |
|
version |
No |
string |
short |
Format of response string. Can be long or short. Defaults to short. Long includes the time. |
date.format with different versions
var dateString = date.format({'date' : '1985-08-11', 'version' : 'short' }); // sets dateString to '8/11/85' dateString = date.format({'date' : '1985-08-11', 'version' : 'long' }); // sets dateString to '11/8/85 0:00' |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Object used to send API requests to the PBX.
Require Extended Library:
var pbx = require('pbx'); |
|
Name |
Description |
|
Sends an API request and (optionally) handles the response. This may require an authenticated Auth object. · For information regarding the Switchvox Extend API visit http://developers.digium.com/switchvox/. |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Sends an API request and (optionally) handles the response. This may require an authenticated Auth object.
· For information regarding the Switchvox Extend API visit http://developers.digium.com/switchvox/.
Basic Example:
pbx.request(parameters); |
|
Name |
Required |
Type |
Default |
Description |
|
method |
Yes |
string |
Name of the API method to call. |
|
|
parameters |
No |
object |
Javascript Object containing key value pairs of values appriopriate to the API method. Default is empty object. |
|
|
onSuccess |
No |
function |
Function to execute if request returns with a success status. This function will be passed a hash with the format {'result' : queryResultObject, 'method' : 'apiMethod'}. Callback function to call when the request successfully completes. If nothing is passed, the default onSuccess callback writes a success message to the log. |
|
|
onError |
No |
function |
Callback function to call when there is an error making the request. If nothing is passed in, the default onError callback shows a screen that displays the error. |
|
|
loadingText |
No |
string |
Message to display during request execution. If none is provided, the loading screen will not be displayed. If you want to send the requeset to the PBX the phone is configured to as the extension the phone is configured as, then this parameters is not needed. If you want to send the request to another PBX or make it as another user, then you need to pass in an Auth object. |
|
|
auth |
No |
object |
An auth object that contains the account_id, username, password, and server address to authorize pbx requests. If you want to send the request to the PBX the phone is configured to as the extension the phone is configured as, then this parameter is not needed. If you want to send the request to another PBX or make it as another user, then you need to pass in an Auth object. |
pbx.request to print extension info associated with the account
pbx.request({'method' : ' switchvox.users.getMyInfo', 'loadingText' : 'Getting extension info', 'onSuccess' : function (response) {util.debug(response.result.extension.number); } }); |
pbx.request to retrieve a presence option list for specified account
pbx.request({'method' : 'switchvox.users.presence.options.getList', 'parameters' : {'account_id' : "1235" }, 'loadingText' : app.t('STATUSLIST_LOADING'), 'onSuccess' : function (p) { util.debug("We got status options");util.debug(JSON.stringify(p.result.presence_options)); } }); |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Prints the supplied message to the standard output. Use the App Development web page for your phone to view the output from debugging. For debugging objects, use the JSON.stringify function.
Basic Example:
var testString = "Test Test"; util.debug(testString); // "Test Test"; var test = {};util.debug(test); // "[object Object]"; util.debug(JSON.stringify(test)); // "{}" |
|
Name |
Required |
Type |
Default |
Description |
|
message |
Yes |
string |
Message to be displayed. |
|
|
indent |
No |
integer |
0 |
Number of tab stops to indent the message. |
util.debug to print Hello World
util.debug('Hello World'); |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Merges two objects and returns the result. For each key provided, the target object is checked for a corresponding key. If none is found, it will be created with the provided value. Keys in target that are defined will not be overwritten.
Basic Example:
util.defaults(target, object); |
|
Name |
Required |
Type |
Default |
Description |
|
target |
Yes |
object |
The target object to be filled with values. |
|
|
object |
Yes |
object |
The object containing properties to merge into target. |
util.defaults creates an object with properties 'foo' -> 'test', 'bar' -> 999
var target = {'foo' : 'test'};target = util.defaults(target, {'foo' : 'Target already contains property "foo", this property will not be merged', 'bar' : 999 }); |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Contains 'helper' functions useful for development.
Require Extended Library:
var util = require('util'); |
|
Name |
Description |
|
Prints the supplied message to the standard output. Use the App Development web page for your phone to view the output from debugging. For debugging objects, use the JSON.stringify function. |
|
|
Merges two objects and returns the result. For each key provided, the target object is checked for a corresponding key. If none is found, it will be created with the provided value. Keys in target that are defined will not be overwritten. |
|
|
Returns an array. |
|
|
Takes a number of seconds and returns a formatted string representing that amount of time in hours and seconds. There are two possible formats: long and short. |
|
|
Returns true if the supplied variable is defined, false if it is not defined (undefined). |
|
|
Returns true if the supplied variable is undefined, false if it is defined. |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Returns an array.
Basic Example:
var newArray = util.forceArray(value[, key]); |
If called with a single argument of an array, returns the argument forced into an array. Otherwise, returns a new array containing argument.
Also can be called with an object and property name. In this case, it uses object[propertyName] as the target.
If value (or value[key]) is undefined, returns an empty array.
|
Name |
Required |
Type |
Default |
Description |
|
value |
Yes |
Value to be forced into an array. |
||
|
key |
No |
string |
If provided, value[key] is forced into an array. |
util.forceArray returns an array
var param = 'foo'; util.forceArray(param); |
util.forceArray returns an array, takes an object as the first parameter
var param = {'foo' : 'bar'};util.forceArray(param, 'foo'); |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Takes a number of seconds and returns a formatted string representing that amount of time in hours and seconds. There are two possible formats: long and short.
Basic Example:
var timeString = util.formatDuration(parameters); |
long format returns a string showing hours (if greater than 0), minutes (if seconds > 60) and seconds. Time durations are shown as strings (e.g., Hour, Minute) and seconds are not displayed if the number of hours > 0.
short format returns a string showing hours (if greater than 0), minutes (if seconds > 60) and seconds. Time durations are shown as letters (e.g., h for hours) and seconds are not displayed if the number of hours > 0, or if number of minutes > 10.
|
Name |
Required |
Type |
Default |
Description |
|
seconds |
Yes |
integer |
Length of time to be formatted. |
|
|
format |
No |
string |
short |
Format of response string. Can be long or short (default). |
util.formatDuration in all formats
// returns the string '3h, 25m' var short = util.formatDuration({'seconds' : 12345, 'format' : 'short' }); // returns the string '3 hours, 25 minutes' var long = util.formatDuration({'seconds' : 12345, 'format' : 'long' }); |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Returns true if the supplied variable is defined, false if it is not defined (undefined).
Basic Example:
util.isDef(var); |
Note: if the variable you are testing has not been declared in anyway, this will throw an exception. If it has been declared but iniitalized as undefined (e.g., not set in any way), the code will process.
|
Name |
Required |
Type |
Default |
Description |
|
var |
Yes |
variable |
Variable to be checked for definition. |
util.isDef returns true or false
var declaredUndef; var str = 'foo'; var obj = {'test1' : 'abc'};util.isDef(str); // returns true util.isDef(obj.test1); // returns true util.isDef(obj.test2); // returns false util.isDef(declaredUndef); // false util.isDef(nonDeclaredVariable); // throws exception |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Returns true if the supplied variable is undefined, false if it is defined.
Basic Example:
util.isUndef(var);
Note: if the variable you are testing has not been declared in anyway, this will throw an exception. If it has been declared but iniitalized as undefined (e.g,. not set in any way), the code with process.
|
Name |
Required |
Type |
Default |
Description |
|
var |
Yes |
variable |
Variable to be checked for definition. |
util.isUndef returns true or false
var declaredUndef; var str = 'foo'; var obj = {'test1' : 'abc'};util.isUndef(str); // returns false util.isUndef(obj.test1); // returns false util.isUndef(obj.test2); // returns true util.isUndef(declaredUndef); // true util.isUndef(nonDeclaredVariable); // throws exception |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
These object constructors are made available to apps by requiring a library. They provide specific solutions for interacting with the application environment.
|
Name |
Description |
|
Used primarily to interact with the PBX when the phone is used with a server running either Switchvox or the Desk Phone Module for Asterisk (DPMA). The auth object holds the user's account id, extension, password, and the address of the server. |
|
|
Localization_language library's Language constructor that creates an object used for translating strings. After the object is created, it checks the phone's lang/locale settings and attempts to load any localized string files available. For example, if the phone's locale is set to es_mx (Spanish/Mexico), the Language constructor checks the app's directory for a 'strings-es_mx.js' file and attempts to load language keys from this file. For more information about creating localized apps see Building Localized Apps in the Guides section. Additionally, the phone's lang/locale settings can be overridden when creating the Language object by passing a langLocale string to the constructor. |
|
|
Creates a new DOM Document. The document created can be manipulated with javascript's standard DOM methods. |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Used primarily to interact with the PBX when the phone is used with a server running either Switchvox or the Desk Phone Module for Asterisk (DPMA). The auth object holds the user's account id, extension, password, and the address of the server.
Require Extended Library:
var Auth = require('auth').Auth; //access the Auth property which is the Auth constructor. |
Create a new Auth Object.
var authObj = new Auth(parameters); |
|
Name |
Required |
Type |
Default |
Description |
|
account_id |
Yes |
integer |
Unique ID of the account. |
|
|
username |
Yes |
Username that will be used when making requests with the auth object. For pbx requests, this is the account's extension. |
||
|
password |
Yes |
string |
Password to use with requests using the auth object. For requests made with the pbx library, this is the account's web password. |
|
|
appserver |
Yes |
string |
Address to which requests using the auth object will be directed. |
|
|
lang |
Yes |
object |
Language object instance. |
The functionality of this object is included in the app extended library . It is recommended you use the app library if you wish to use this feature.
|
Name |
Description |
Parameters |
Examples |
|
showLoginScreen |
Displays a login screen on which a user can enter a server, extension, and
password. |
None |
auth.showLoginScreen var authObj = require('auth').Auth;var auth = new authObj(); if (!auth.isLoggedIn()) { return auth.showLoginScreen({'callback' : callbackFunction, }); } |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Creates a new DOM Document. The document created can be manipulated with javascript's standard DOM methods.
Require Extended Library:
var Document = require('dom').Document; |
var document = new Document(); |
|
None |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Localization_language library's Language constructor that creates an object used for translating strings. After the object is created, it checks the phone's lang/locale settings and attempts to load any localized string files available. For example, if the phone's locale is set to es_mx (Spanish/Mexico), the Language constructor checks the app's directory for a 'strings-es_mx.js' file and attempts to load language keys from this file. For more information about creating localized apps see Building Localized Apps in the Guides section.
Additionally, the phone's lang/locale settings can be overridden when creating the Language object by passing a langLocale string to the constructor.
Require Extended Library:
var Language = require('localization_language').Language; //the Language constructor is exported in the Language property
var lang = new Language(parameters); |
|
Name |
Required |
Type |
Default |
Description |
|
langLocale |
No |
string |
en_us |
Lang/locale code to use when loading string localization files. The standard format for this string is [lang code]_[locale code] (e.g., es_mx for Spanish/Mexico, en_us for English/US). The lang/locale code corresponds to the last part of a localization file's name (e.g., strings-en_us.js contains the translated strings for English/US). |
|
defaultLangLocale |
No |
string |
en_us |
Indicates the language file to use if the app does not have a language file for the phone's chosen language. For example, if the chosen language/locale is fr_fr, but the app does not include the file strings.fr_fr.js, then the app uses the default language file as indicated with this parameter. If no value has been defined, the phone tries to use en_us. |
The functionality of this object is included in the app extended library . It is recommended you use the app library if you wish to use this feature.
|
Name |
Description |
|
Look up a language key and test it against the currently specificed language. |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Look up a language key and test it against the currently specificed language.
Basic Example:
var string = langObj.translate(parameters); |
|
Name |
Required |
Type |
Default |
Description |
|
key |
Yes |
string |
Key to lookup that was exported in strings file. |
|
|
vars |
No |
array |
[] |
Array of variables for substitution. For each %s found in the language string, these variables are substituted in order starting with index 0. |
|
count |
No |
integer |
1 |
Number of items. Intended for language keys whose value is a pluralized array. |
Language.translate for translation
/* Let's assume we have two string files for our app and they look like the following. [strings-en_us.js] exports.keys = { 'T_MY_APP' : 'My App', 'T_SETTINGS' : 'Settings' 'T_HAVE_DOGS' : ['I have %s dog', 'I have %s dogs'] }; [string-es_mx.js] exports.keys = { 'T_MY_APP' : 'Mi aplicación', 'T_HAVE_DOGS' : ['Tengo un perro', ' Tengo %s perros'] }; /* instantiate Language object set to es_mx (Spanish/Mexico) with a default of en_us (English/USA). If a key is missing from es_mx, the library will try to find it in the default language's strings file. */var langObj = new Language({'langLocale' : 'es_mx', 'defaultLangLocale' : 'en_us'});var str = langObj.translate({'key' : 'T_APP_TITLE'}); // returns "Mi aplicación"var str2 = langObj.translate({'key' : 'T_SETTINGS'}); // returns "Settings" because the key does not exist in the es_mx filevar str3 = langObj.translate({'key' : 'T_HAVE_DOGS', 'count' : 4, 'vars' : ['4']}); //returns Tengo 4 perros |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
These object constructors are available to all apps without requiring any libraries. They create the individual elements that can be displayed on the screen. All of the UI constructors inherit from the Widget base class; it is not possible to construct a Widget object directly.
|
Name |
Description |
|
Methods and properties of the Widget object are used to control basic properties for any UI items. It is not possible to construct a Widget object directly, but all UI classes and onscreen items inherit their basic functionality from this Widget base class. |
|
|
Widget used for drawing text on the screen. |
|
|
Widget that contains other widgets and acts as a container. For example, this widget is useful for showing and hiding many widgets at one time. Groups can have any number of widgets attached to them; e.g., Group widgets, Text widgets, and Input widgets. There are certain Group widgets that are automatically instantiated for an app and must be used for displaying anything. The window property is always accessible to an app and is shown when the app is foregrounded. The property digium.app.idleWindow is instantiated based on the app's app.json manifest. |
|
|
Derived from a group widget. Automatically adds a scrollbar when its widgets overflow the box. |
|
|
Creates a text entry widget that can be used to receive input via the phone's number pad. This widget manages the softkeys themselves; therefore, you are advised not to change them programmatically. |
|
|
Scrolling table with row-wise navigation capabilities. Useful for menus, lists of calls, etc. The user can scroll through a list with the up and down direction keys after it is given focus. List text is black on white background, and the selected/highlighted item is inverted. The width of the selected item highlight is that of the List Object itself and not of the summation of column widths. When referring to columns and rows, indexes always begin at 0. |
|
|
Widget that displays an image file on the screen using a location and filename. |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Widget that contains other widgets and acts as a container. For example, this widget is useful for showing and hiding many widgets at one time. Groups can have any number of widgets attached to them; e.g., Group widgets, Text widgets, and Input widgets.
There are certain Group widgets that are automatically instantiated for an app and must be used for displaying anything. The window property is always accessible to an app and is shown when the app is foregrounded. The property digium.app.idleWindow is instantiated based on the app's app.json manifest.
Constructs a new Group Object. A Group acts as a container for other widgets.
var groupObj = new Group(x, y, width, height); |
|
Name |
Required |
Type |
Default |
Description |
|
x |
Yes |
integer |
x coordinate value for top left corner. |
|
|
y |
Yes |
integer |
y coordinate value for top left corner. |
|
|
width |
Yes |
integer |
Width in pixels. |
|
|
height |
Yes |
integer |
Height in pixels. |
This Class inherits methods and properties from the Widget Base Class. See Widget Base Class for more information about setting your Object's x, y, w, and h properties or adding children to it.
|
Name |
Description |
|
Adds one or more widgets to the group. |
|
|
Removes all child elements from the group or removes all content from the list. |
|
|
Removes one or more widgets from a group. |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Adds one or more widgets to the group.
Basic Example:
exampleObj.add(widget[, widget...]); |
|
Name |
Required |
Type |
Default |
Description |
|
widget |
Yes |
widget |
Widget to act on. |
Using the 'add' method with a variety of widgets
// add a group to the window. var group = new Group(0, 0, window.w, window.h); window.add(group); //add a title to the group group.add(new Text(0, 0, winow.w, Text.LINE_HEIGHT)); //add a scroll to the group slightly smaller due to the text @ top and offset the same. var scroll = new Scroll(0, Text.LINE_HEIGHT, window.w, (window.h - Text.LINE_HEIGHT)); group.add(list); //add a set of images to the list. var img1 = new Image("tmp", "test1.png", 30, 30, 50, 10);var img2 = new Image("tmp", "test2.png", 30, 45, 50, 10)var img3 = new Image("tmp", "test3.png", 30, 60, 50, 10)scroll.add(img1, img2, img3); //support for adding multiple is the same with group and window. |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Removes all child elements from the group or removes all content from the list.
exampleObj.clear(); |
|
None |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Removes one or more widgets from a group.
Basic Example:
exampleObj.remove(widget[, widget...]); |
|
Name |
Required |
Type |
Default |
Description |
|
widget |
Yes |
widget |
Widget to act on. |
Remove widgets from a variety of objects.
window.remove(alertWidget); group.remove(titleWidget); scroll.remove(imgWidget1, imgWidget2); |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Widget that displays an image file on the screen using a location and filename.
For images stored in the app's directory, location should be set to app, and filename should be set to the name of the image file.Construct a new Image Object.
var imgObj = new Image("location", "filename", x, y, w, h); |
|
None |
This Class inherits methods and properties from the Widget Base Class. See Widget Base Class for more information about setting your Object's x, y, w, and h properties or adding children to it.
|
Name |
Description |
|
Reloads the image from disk. This is needed to clear the UI drawing cache. Should only be used if a new image is written over an existing one of the same name that has been used in the current run of the app. |
|
|
Changes the size of the image. If either width or height is set to 0, the image will be scaled to the other width/height, maintaining the aspect ratio. |
Reloads the image from disk. This is needed to clear the UI drawing cache. Should only be used if a new image is written over an existing one of the same name that has been used in the current run of the app.
Basic Example:
imageObj.reload(); |
|
None |
Changes the size of the image. If either width or height is set to 0, the image will be scaled to the other width/height, maintaining the aspect ratio.
Basic Example:
imageObj.resize(width, height); |
|
Name |
Required |
Type |
Default |
Description |
|
height |
Yes |
integer |
Height in pixels. |
|
|
width |
Yes |
integer |
Width in pixels. |
resize an image widget to width of 20 pixels and preserve the previous aspect ratio
var testImage = new Image(0, 0, 40, 100); // image at 0,0 width=40 height = 100 testImage.resize(20, 0); // image at 0,0 width=20 height = 50 |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Creates a text entry widget that can be used to receive input via the phone's number pad. This widget manages the softkeys themselves; therefore, you are advised not to change them programmatically.
Constructs a new text Input Object.
var inputObj = new Input(x, y, widght, height); |
|
Name |
Required |
Type |
Default |
Description |
|
x |
Yes |
integer |
x coordinate value for top left corner. |
|
|
height |
Yes |
integer |
Height in pixels. |
|
|
y |
Yes |
integer |
y coordinate value for top left corner. |
|
|
width |
Yes |
integer |
Width in pixels. |
This Class inherits methods and properties from the Widget Base Class. See Widget Base Class for more information about setting your Object's x, y, w, and h properties or adding children to it.
|
Name |
Description |
|
Sets up a softkey that cycles through a set of modes. Can be any of "normal", "email", "ip", or "numeric". |
|
|
Replaces a range of text from the input widget with another string. |
|
|
Returns the value of the input (same as the value property). |
|
Name |
Description |
|
textColor |
Color of the text. Can be white or black for D40, D50, and D70, or any of the colors specified in the Base Class color properties for the D6X models. |
|
firstUpper |
If set to true, user input for this Input widget will begin cycling with capitalized letters rather than lowercase for the first character. Basic Example: textObj.firstUpper = true; An example use case for this would be input for names or other proper nouns. |
|
mode |
Controls the characters inserted when number keys are pressed on the keypad. Can be normal, email, ip, numeric. |
|
onchange |
Function to be called whenever the contents changes. |
|
position |
Get or set current position of the cursor. Basic Example: var cursorAt = inputObj.position; inputObj.position = 0; //back to the beginning. |
|
value |
Get the current value or set the value of the Input. Basic Example: var currentValue = inputObj.value; inputObj.value = ""; //set the value to a blank string |
Sets up a softkey that cycles through a set of modes. Can be any of "normal", "email", "ip", or "numeric".
Basic Example:
textObj.cycleModes(modesArray);
|
Name |
Required |
Type |
Default |
Description |
|
modes |
Yes |
array |
Array of modes. Can be any of "normal", "email", "ip", or "numeric". |
cycleModes for a softkey that cycles numeric and normal
theInput.cycleModes(['numeric', 'normal']);
Replaces a range of text from the input widget with another string.
Basic Example:
textObj.replace(begin, end, replacement);
Note, this will focus the cursor at the end of the replacement.
|
Name |
Required |
Type |
Default |
Description |
|
begin |
Yes |
integer |
Index to begin replacing. |
|
|
end |
Yes |
integer |
Index to end replacing. |
|
|
replacement |
Yes |
string |
The string to use as the replacement. |
replace bar with foo
var input = new Input(0, 0, 100, Text.LINE_HEIGHT); input.value = 'FooBar'; input.replace(3, 5, 'Foo') return input.toString(); //returns 'FooFoo' |
Returns the value of the input (same as the value property).
Basic Example:
textInput.toString(); //get the value of the Input |
|
Name |
Required |
Type |
Default |
Description |
|
modes |
Yes |
array |
Array of modes. Can be any of "normal", "email", "ip", or "numeric". |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Scrolling table with row-wise navigation capabilities. Useful for menus, lists of calls, etc. The user can scroll through a list with the up and down direction keys after it is given focus.
List text is black on white background, and the selected/highlighted item is inverted. The width of the selected item highlight is that of the List Object itself and not of the summation of column widths.
When referring to columns and rows, indexes always begin at 0.
Constructs a new List Object.
var listObj = new List(x, y, width, height);
|
Name |
Required |
Type |
Default |
Description |
|
x |
Yes |
integer |
x coordinate value for top left corner. |
|
|
y |
Yes |
integer |
y coordinate value for top left corner. |
|
|
width |
Yes |
integer |
Width in pixels. |
|
|
height |
Yes |
integer |
Height in pixels. |
This Class inherits methods and properties from the Widget Base Class. See Widget Base Class for more information about setting your Object's x, y, w, and h properties or adding children to it.
|
Name |
Description |
|
Removes all child elements from the group or removes all content from the list. |
|
|
Retrieves contents of a specific cell in the list. |
|
|
Selects the specified row. |
|
|
Sets the contents of the given cell in the List. |
|
|
Sets the widths of each column in pixels. If the last value is set to 0, it will use all remaining space to fill the list's width. |
|
Name |
Description |
|
Function that takes row and column numbers as parameters and returns the text for a cell. When this property is set, the function is immediately executed. |
|
|
cols |
Number of columns. Columns are numbered from 0, starting on the left. |
|
Callback function called when the selection changes. |
|
|
rowHeight |
Number of pixels high each row should be. Defaults to Text.LINE_HEIGHT in D40, D50, and D70, but defaults to Text.ROW_HEIGHT for D6X models. |
|
rows |
Number of rows the list contains. Rows are numbered from 0, starting at the top of the list. |
|
Returns the currently selected row number or set the row you wish to be selected. |
Function that takes row and column numbers as parameters and returns the text for a cell. When this property is set, the function is immediately executed.
Basic Example:
list.cellFunc = function(r, c) {return ""; } |
Use the cellFunc property for functions that take a row and column as parameters and return the string or image to be displayed at that position. This is more efficient because the list doesn't need to build a large data structure. The cellfunc will be called only for items that are on the screen.
The cellFunc option is recommended for large lists.
List.cellFunc to create a list of employee data
//clear the window and add a header window.clear(); window.add(new Text(0, 0, 100, 100, "Employees")); //add the list object var list = new List(0, 20, window.w, window.h-20); window.add(list); //column widths will be 70, 70, and rest of the visible object list.setColumnWidths(70, 70, 0); //last column will take the up as much space as possible /* This data structure was created to take advantage of the cellFunc function and make filling out our List very easy. Rows will go in order, and are the index of the 'content' array. Each item in the content array is then an array. Each node of the inner array is a set of values which will correspond to the columns. This combination will be used to fill out all of our cells. */ var content = [ ['--Emp.--', '--ID--', '--Country--'], ['Tom', '1231451', 'USA'], ['Ralph', '7567567', 'China'], ['Sam', '890294', 'Canada'], ]; //set cols and rows (rows equal to length of array list.rows = content.length; list.cols = 3; // run over the cellFunc function accessing our content array each row and column at a time. list.cellFunc = function (r, c) { return content[r][c]; };//focus and select the first item in the list (not the header) list.takeFocus(); list.select(1); |
List.cellFunc to create a multiplication table
//Create and add our List object var listObj = new List(0, 20, window.w, (window.h - 20)); window.add(listObj); // we will use this variable in a couple places. It represents how large our grid will be. var num = 10; //programmatically create a widths array which will be passed to setColumnWidths(); var widths = []; while (widths.length < num) {//all the columns are even and will fill the whole screen widths.push(window.w/num); } //set rows and columns listObj.rows = num; listObj.columns = num; //setColumnWidths takes a variable amount of arguments, that is why apply is used here. listObj.setColumnWidths.apply(listObj, widths); //set the cellFunc to return the row multiplied by the column (e.g. row 3, column 4 = 12) listObj.cellFunc = function(r, c) { return r*c; };//focus on the list so we can scroll listObj.takeFocus(); |
Removes all child elements from the group or removes all content from the list.
Basic Example:
exampleObj.clear(); |
|
None |
Retrieves contents of a specific cell in the list.
Basic Example:
var value = listObj.get(row, column); |
rows and columns begin at 0,0.
|
Name |
Required |
Type |
Default |
Description |
|
row |
Yes |
integer |
Row number of the cell. |
|
|
column |
Yes |
integer |
Column number of the cell. |
get the contents of row 1 column 1
list.get(1, 1); |
Callback function called when the selection changes.
Basic Example:
exampleObj.onchange = function() { util.debug('selection change'); }Selects the specified row.
Basic Example:
listObj.select(row);
the first row is row zero.
|
Name |
Required |
Type |
Default |
Description |
|
row |
Yes |
integer |
Row number of the cell. |
select row 14 of a list widget
var list = new List(50, 50, 200, 200); list.setProp('rows', 30) .setProp('cellFunc', function () { return 'This is a row!'; });list.select(14); |
Returns the currently selected row number or set the row you wish to be selected.
Basic Example:
listObj.select(2);
listObj.selected; //returns 2
Note: setting the selected property is the same as using the List.select() method.
Sets the contents of the given cell in the List.
Basic Example:
listObj.set(row, column, content); |
|
Name |
Required |
Type |
Default |
Description |
|
row |
No |
integer |
Row number of the cell. |
|
|
column |
No |
integer |
Column number of the cell. |
|
|
content |
No |
varied |
The contents of the cell. Can be a string, or a widget. |
set the contents of a list widget
var list = new List(50, 50, 200, 200); list.set(0, 0, 'Foo'); list.set(0, 1, 'Bar'); list.set(1, 0, 'Bar'); list.set(1, 1, 'Foo'); |
Sets the widths of each column in pixels. If the last value is set to 0, it will use all remaining space to fill the list's width.
Basic Example:
listObj.setColumnWidths(width[, width...]); |
A List object will not be visible until you perform this method and set the column widths. If not set, column widths default to zero.
|
Name |
Required |
Type |
Default |
Description |
|
width |
Yes |
integer |
Width in pixels. |
setColumnWidth with different column widths, and the last column fits in the remaining space
list.setColumnWidths(35, 100, 0); |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Derived from a group widget. Automatically adds a scrollbar when its widgets overflow the box.
Construct a new Scroll object.
var scrollObj = new Scroll(x, y, width, height); |
|
Name |
Required |
Type |
Default |
Description |
|
y |
Yes |
integer |
y coordinate value for top left corner. |
|
|
x |
Yes |
integer |
x coordinate value for top left corner. |
|
|
width |
Yes |
integer |
Width in pixels. |
|
|
height |
Yes |
integer |
Height in pixels. |
This Class inherits methods and properties from the Widget Base Class. See Widget Base Class for more information about setting your Object's x, y, w, and h properties or adding children to it.
|
Name |
Description |
|
Adds one or more widgets to the group. |
|
|
Removes all child elements from the group or removes all content from the list. |
|
|
Removes one or more widgets from a group. |
|
Name |
Description |
|
yPosition |
Returns the current yPosition of the Scroll object. Note: this is not relative to the placement of the Scroll on the screen in anyway. Also can be used to set the y value of the scroll bar, causing it to scroll. Basic Example: //scroll down the Scroll Widget by 3 a factor of 3 LINE_HEIGHTS. scrollObj.yPosition =(scrollObj.yPosition + (Text.LINE_HEIGHT * 3)); |
Adds one or more widgets to the group.
Basic Example:
exampleObj.add(widget[, widget...]); |
|
Name |
Required |
Type |
Default |
Description |
|
widget |
Yes |
widget |
Widget to act on. |
Using the 'add' method with a variety of widgets
// add a group to the window. var group = new Group(0, 0, window.w, window.h); window.add(group); //add a title to the group group.add(new Text(0, 0, winow.w, Text.LINE_HEIGHT)); //add a scroll to the group sligh |