Accessing User Interface Controls from Code

After you have declared a canvas that contains all the desired controls, you should now add behavior to the panel. The panel's code can access the controls declared in the canvas and modify their properties (such as the text of a Text Output). In addition, you can connect a method responding to user actions and dynamically modifying the contents of UI controls.

Connecting Control Events to Code

Canvas controls have events that allow you to execute code when the user makes certain actions, such as clicking the control, hovering the mouse over it, etc. Events are used by connecting a function in the panel's code to that event - this function will be executed when the event occurs.

In order to connect a code function to a control event, you add an attribute to the control's element in the canvas declaration. The attribute's name is the event you want to connect a function to, and the value of the attribute is the name of the function that will be connected.

For example, let's take a simple canvas with only a Text Output control in it:

<canvas> <textoutput id="myTextOutput" /> </canvas>

Now, we connect a function called "onClick" to the Text Output's click event. First, connect the function in the canvas declaration by adding an attribute:

<canvas> <textoutput id="myTextOutput" click="onClick" /> </canvas>

Then, write the function in the panel's code:

function onClick() { //The Text Output has been clicked. Show a message box. sidebar.MsgBox("The myTextOutput control was clicked.", "Message", 0); }

Now, whenever the Text Output is clicked by the user, our onClick function will be executed and will display a message box.

Manipulating Controls from Code

There are many occasions where you will want to manipulate controls from the panel's code, whether it is to modify the text of a Text Output or add rows to a List Output when the panel fetches new data, or to hide a control when it is not needed, and so forth.

In order to access a certain control from the panel's code, we use the GetControl("controlId") function. Remember of course to replace "controlId" with the desired control's id (the same one you assigned the control in the canvas declaration).

The GetControl function returns an object which has many functions of its own that can be used to modify the control's behavior. Each control has various functions which are documented in detail in the Object Reference section.

For a simple example for accessing a control from the panel's code, let's have a look at a panel whose canvas contains only one List Output with the id of "myList". The canvas declaration follows:

<canvas> <listoutput id="myList" /> </canvas>

Now, let's say we want to add a row to our list somewhere in our script. To do that, we use the List Output's AddRow function. Then, we have to put text in that row using the SetText function, otherwise the row won't show up. So to add a row to our list, all we have to do is:

GetControl("myList").AddRow().SetText("A new row has been added!");

For a complete list of the functions, see the Object Reference section.