Project and Context Member

Navigation:  Widget Designer > Scripting > Object and Member Notation (dot syntax) >

Project and Context Member

prev main next

Navigation:  Widget Designer > Scripting > Object and Member Notation (dot syntax) >

Project and Context Member

prev main next

Please wait. Due to its content this page might take a while to load...

The previous topic describes members referring to objects like widgets or variables. Besides those, there are two special, superior objects, Project and Context. They provide information and functionality more abstracted than the normal objects.

Those two powerful tools enable you to program highly sophisticated and automated interfaces, they can turn scripting more complex on one hand, but much more flexible and effective on the other hand.

Project member

The Project is the main parent element of the whole Widget Designer. Using this object permits you dynamic access to all child objects like widgets, nodes and global variables.
The main purpose of using the Project object is automating actions that should be performed on many child elements at once. This makes it for example easy to substitute a row of widget IDs with iterating variables to access their members, or to write a script that searches for all widgets with a special type or value.

This is possible because you can use variables instead of explicitly naming an object. One way is to write:

Label1.StartFlash
Label2.StartFlash
etc.
Label10.StartFlash

For this example it would also be possible to use common commands and shorten the script by using a for-loop:

For i = 1 to 10 {

 WDLabelStartFlash(i)

}

 

But you have to keep in mind that the actions or possibilities with commands are limited, whilst member notation permits full access. E.g if you wanted to change the background color of Label 1 to 10 from black as the default value to red. The Label member "BackColor" offers this function, but there is no common command equivalent that can be used here for a for-loop. The Script also disables the transparency option for labels, allowing the background color to be visible.

This is where the Project member comes in handy: It allows you to have flexible access on every object member:

For i = 1 to 10 {

 Project.Label(i).BackColor.SetRGB(255,0,0)
 Project.Label(i).Transparent=False

}

It is also possible to combine this way of scripting with variables. The following script is an alternative for the last one:

for i = 1 to 10{
 var f = Project.Label(i)
 f.BackColor.SetRGB(255,0,0)
 f.Transparent=False
}

 

Lastly, it is possible to combine this with an if-statement as shown in the examples below the table.

The Project member already offers you all available widget types when you set the dot. The widget name (e.g. "Label1") or the ID are used to specify a certain object of which all members are available afterward.

Object

Members

Further Members

Description

Example

Project

.WidgetType

.Variables.Type

 

The Script Assistant offers you a list of all available widget types, nodes and variables that exist in your project.

If you want to access variables, you also have to specify the data type.

Project.Fader

Project.CustomScript

 

Project.Variables.String

Project.Variables.List

 

.WidgetType(ID or name)

.Variables.Type(name)

 

To access the members of a specific object, you have to enter either the ID (for widgets and nodes) or the name of the object.

Project.Fader("Fader15")

Project.CustomScript(3)

 

Project.Variables.String("var_string")

Project.Variables.List("var_list")

 

 

.WidgetMember

.NodeMember

Every object specific member is accessible from the Project object too. All properties can be read or set, all methods can be executed.

If you access a property, you can even use the data type specific members on them.

Project.Fader("Fader15").Value = 128

Project.CustomScript(3).ExecuteClick

Project.Label("Label22").ForeColor.SetRGB(50,0,90)

Project.Node(15).ConnectTarget(12)

 

 

.VariableDataTypeMember

All variables accessed by the Project object have their respective data type member.

Project.Variables.Integer("var_int") = 10

Project.Variables.Boolean("var_bool").ToInteger

Please note that every member returning a value, like string, double, Boolean or list, can have further members respective to their data type. This is explained in this chapter.

Example 1:

Imagine a WD project that is supposed to monitor position values of a theatrical rigging system. Everything is already set up correctly and the height of twenty different flown battens is displayed in twenty different labels, Label1 to Label20. The names of the respective battens are displayed next to height values with Label21 to Label40. The pairing would then look like this:

Batten 1:   20   [Label21] [Label1]

Batten 2:   15   [Label22] [Label2]

Batten 3:   3.5  [Label23] [Label3]

...

 

Maybe you want to check quickly which ones of them are still unused and thus at their maximum height, 20m. With one click, all of those batten name labels should flash and turn green.

You could then use a normal CustomScript button to trigger this action by entering the following script:

for i = 1 to 20 {

 if Project.Label(i).Text = 20 {

         Project.Label(i + 20).ForeColor.SetRGB(0,255,0)

         Project.Label(i + 20).StartFlash

 }

}

This script searches through all labels with ID 1 to 20 for a text value "20" and performs the respective action (set fore color and start flashing) on the label next to the ones where the condition applies (label ID + 20).

Of course this is a very small and simple example, but as the Widget Designer offers you a maximum GUI of 8K x 8K pixels, huge monitoring displays can be arranged, also with BarGraphs, Gauges and other kinds of optical display options.

Finding something special there quickly can become quite difficult, this example provides a simple solution for this problem. The search algorithms can of course be a lot more complex and also include user input, searches can also be automatically timed.

 

Example 2:

Imagine a WD project made for a venue. The venue has several rooms with multiple displays and for each room there is a page in Widget Designer. Each page has widgets, e.g Faders that fade images and videos on those screens. Whenever you enter another room and switch to another page, you like to "reset" i.e. fade down the faders, but not all of them as some Faders influence sound which should stay on until the end of the day. To distinguish those two groups of faders, you could use for example the "Notes" field. Let's say, all faders that should be faded down when you switch a page say "room1", "room2" etc. in the Notes field whilst the Faders for the sound say "audio". With this script, you fade down all "room1" Faders:

for i=1 to 50 {

 if Project.Fader(i).Notes.Contains("room1"){

         Project.Fader(i).FadeDown(2)

 }

}

 

As the Notes field is available for many widgets, it is a very easy and versatile tool to group, address or identify them. Another common application is to "reset" toggle buttons, in the way that all toggle button that are currently in the "Pressed" mode should be clicked (but those in the "Released" mode stay). To achive this , you could replace or add the following command in the above if-statement: WDCustomScriptForceReleased(i)

 

If you name your pages "room1", "room2" etc. you could create a string Variable and use this command in a PageEnter script to write the current page name into the variable, e.g. v_currentpage = Window1.PageName
Now, you can substitute the room string in the above example with the variable and use this script anywhere you like without the need to edit it: in a Custom Script Button (even if it is set to "Fix") or Macro or even the PageLeave script.

for i=1 to 50 {

 if Project.Fader(i).Notes.Contains(v_currentpage){

         Project.Fader(i).FadeDown(2)

 }

}

 

As shown with all these examples, the Project object enables you to use a complete new dimension of dynamic and flexible scripting within the application.

 

Context members

The object "Context" always refers to the context of the script wherein it is run.
For example, if you execute a script by clicking a CustomScript button, the context includes the page and window where the widget is located. In addition, it holds the information with which client it was executed. Imagine your project is displayed in your GUI and at the same time via the Web Server in an external browser. It makes a difference whether you click the button in your GUI, or in the browser, they have two different contexts. If you add faders to the project, each client can have different values for the same fader, because the widget is used in different contexts.
If you are interested in the Web Server and the control of those client differing values, please have a look at the topic Group Values.

However, as said above, the context does not only refer to multiple clients. It is also useful for addressing windows, pages and widgets automatically. Try the following:
Create a project and set up one CustomScript button in Page1. Create another window with Page2 and set up a label.
Open the property dialog of the button and type the following into the "On Press Script" section:
DebugMessage(Context.Name)
Click on the button to execute the script, the Debug Logger will show: Window1/Page1/CustomScript1/ClickScript.
This is the whole context of the executed script, including all parent elements.
Repeat this with the label's On Click Script, and you will get this result: Window2/Page2/Label1/ClickScript.

This should give you a good impression of what a script's context is, it always matters from where it is executed.

Please be aware that scripts must be executed "for real", i.e. for example, a button must be clicked. If you right-click in the script field and choose "Test" or "Test Selected Lines", there is no context! Always execute the script the way it will be by the user afterward.

Here is a list of all available Context members and what they are intended to do, it is recommended to take some time and try them all out. The Debug Logger is a useful tool for this purpose:

Object

Members

Further Members

Description

Context

.Name

 

 

Example:

Debug Message(Context.Name)

Returns the name of the widget, macro, etc. from which the script is executed, including the parent objects.

A CustomScript button executing the example script opens the Debug Logger which shows:

Window1/Page1/CustomScript1/ClickScript

 

.Stack

 

 

Example:

Debug Message(Context.Stack)

Returns a list of all objects (different widgets or macros that call other objects/ macros/ functions) taking part at the chain of executing scripts.

If a CustomScript button executes another Macro which includes the example command, the Debug Logger will open and show:

[["Window1/Page1/CustomScript1/ClickScript","WDMacro Command"]]

 

.Page

.PageMember

e.g. Color1

 

Example:

Context.Page.Name = "new"

Accesses all available page members for the page the object is located on.

A CustomScript button with the example script changes the name of that page it is located on itself to "new".  

 

.WidgetID

 

 

Example:

WDFaderUp(Context.WidgetId,1)

DebugMessage(Context.WidgetId)

Returns the ID of the widget whereof the script is executed as an integer.

If the example script is executed from the CustomScript button with ID 2, the Fader with ID 2 will fade and the Debug Logger will open and display:

2

 

.WidgetName

 

 

Example:

DebugMessage(Context.WidgetName)

Returns the name of the widget whereof the script is executed as a string.

If the example script is executed from the CustomScript button with ID 2, the Debug Logger will open and display:

CustomScript2

 

.WidgetType

 

 

Example:

DebugMessage(Context.WidgetType)

Returns the type of the widget whereof the script is executed as a string.

If the example script is executed from any CustomScript button, the Debug Logger will open and display:

CustomScript

 

.Script

 

 

Example:

DebugMessage(Context.Script)

Returns the type of script field from which it is executed as a string.

The example script would open the Debug Logger and display "ClickScript", "EnterScript" or "LeaveScript" etc.

.Client
(Client Key - optional)

.Groups

.GroupName

e.g. Session

Example:

DebugMessage(Context.Client.Groups.Client)

DebugMessage(Context.Client.Groups.InternalExternal)

DebugMessage(Context.Client.Groups.IpAddress)

DebugMessage(Context.Client.Groups.Session)

This member refers to Group Values, it offers a list of available groups to request or edit the respective key. The optional Client Key parameter can be used to address other clients in the system, apart from the particular client executing the script. The Script Assistant offers you available Client Keys.

A CustomScript button executing the example commands will open the Debug Logger showing the according Client key, Internal or External information, the IP address (or localhost) and the Session Key from the computer / Session it is executed from. It could look as follows:

c21e4700-11aa-22bb-33cc-44dd55ee66ff

Internal

localhost

5e551040-f00f-e99e-d88d-c7b6a55a6b7c

 

Example 2:

DebugMessage(Context.Client("c21e4700-11aa-22bb-33cc-44dd55ee66ff").Groups.InternalExternal)

A CustomScript button executing this command will open the Debug Logger showing the according Internal or External key from the computer with the defined Client Key.

 

Example 3:

If Context.Client.Groups.Session = "5e551040-f00f-e99e-d88d-c7b6a55a6b7c" {WDMacro("Adminmacro")}

A CustomScript button executing this command will execute a macro only if called from the context of the defined Session, not if clicked in other Sessions.

 

Example 4:

Context.Client.Groups.Team = "team_red"

This example shows how to assign a Key to a Custom Group called "Team".

 

 

.Key

 

Example:

DebugMessage(Context.Client.Key)

Returns the Client Key of the indicated client context.

A CustomScript button executing the example command will open the Debug Logger showing the according Client Key, e.g. "c21e4700-11aa-22bb-33cc-44dd55ee66ff".

 

 

.IP

 

Example:

DebugMessage(Context.Client.Ip)

DebugMessage(Context.Client("c21e4700-11aa-22bb-33cc-44dd55ee66ff").Ip)

This member returns the IP address of the indicated client context. With this, you can also retrieve the IP address of every connected client with the Client Key. E.g. the member "Context.ClientKeys" returns a list with the Keys of all connected clients.

A CustomScript button executing the example script will open the Debug Logger which shows for example "localhost" (if it was executed from the local Widget GUI) or "192.168.1.100" for an external client, as well as "192.168.1.102", the IP address corresponding to the entered Client Key.

 

 

.PageName

 

Example:

Context.Client.PageName = "Page2"

This expression can be used to navigate between different pages of the same window. When a Group Value is applied to the window, different clients can access pages independently from each other. Otherwise, the pages are synchronized.

A CustomScript button executing the example script will send the client where it is executed to Page2.

 

.ClientExists
(Client Key)

 

 

Example:

DebugMessage(Context.ClientExists("c21e4700-11aa-22bb-33cc-44dd55ee66ff"))

Returns a Boolean value (False or True) that indicates if a client with the respective Client key is currently connected.

A CustomScript button executing the example script will open the Debug Logger which shows "True" if the session with this Client Key is connected, or "False" if disconnected.

 

.ClientKeys

 

 

Example:

DebugMessage(Context.ClientKeys)

Returns a list containing all Client Keys of currently connected clients.

A CustomScript button executing the example script will open the Debug Logger showing the Client Keys from all open Sessions, for example:

[["c21e4700-11aa-22bb-33cc-44dd55ee66ff","a381490e-9a00-4bd1-ab52-0d835705edb3"]]

 

.Session

.Value(specifier)

 

Example:

Context.Session.Value("name") = "Jonathan"  // stores a new value "name" and sets it to "Jonathan"

Context.Session.Value("country") = "Switzerland"  // stores a new value "country" and sets it to "Switzerland"

DebugMessage(Context.Session.Value("name"))

DebugMessage(Context.Session.Value("country"))

This command can can set or retrieve your own custom value, stored within the WD and responding to the Key in the Session cookie. Please note that you can only store string values!

A CustomScript button executing the example script will open the Debug Logger showing "Jonathan" and "Switzerland", both strings retrieved from the Session where the script was called from.

Please refer to the topic Session and Session Value for further information.

 

 

.Contains
(search expression)

 

Example:

DebugMessage(Context.Session.Contains("Jonathan"))

Returns a Boolean value (False or True) if the indicated expression is stored in the Session.

A CustomScript button executing the example script will open the Debug Logger showing "true" if the Session value was set like in the example before.

 

.Window

.CustomHeader

 

Example:

Context.Window.CustomHeader = "<!DOCTYPE html>

<html>

<style>

.WdWindow{

position: relative;

width: 1200px;

margin: 0 auto;

}

</style>

</html>"

The Custom Header enables you to implement your own HTML5 based design in the Widget Designer interface. The here defined header affects the objects in the specified window.

This example script causes the pages to be located not at the left side of your window but in the middle, assuming that the pages' width is 1200px.

 

 

.PageName

 

Example:

Context.Window.PageName = "Page2"

This expression can be used to navigate between different pages of the same window.

A CustomScript button executing the example script will send the window where it is executed to Page2.

Each member that returns a value can have additional members referring to their data type. The next chapter describes the terms "Session" and "Session Values".