Custom Script Button

Navigation:  Widget Designer > Widgets > Buttons >

Custom Script Button

prev main next

Navigation:  Widget Designer > Widgets > Buttons >

Custom Script Button

prev main next

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

The CustomScript button allows you to execute one or more commands whenever the button is clicked or activated in a different way. You can set up any button style and any click-able user interaction. Over 1500 commands are available to remote control all important Pandoras Box features as well as Widget Designer interface elements and much more.

wd_widget_button_cs-empty To create a CustomScript button choose "Widgets > Buttons > Custom Script". The mouse cursor changes to a crosshairs icon, indicating the create mode. With a left-click anywhere on the empty main background window you add the selected widget to the current page. Left-click again if you like to add one more. To quit the create mode, you can switch to the run mode with [F8], where you can use all widgets. Most widgets however need to be set up first.

To edit the CustomScript button properties simply right-click it and choose the first menu entry "CustomScript Properties". Alternatively, you can press [Alt + P] whilst the mouse is hovering above it or switch to the edit / move mode with [F9] and double-click on it.
The CustomScript button property dialog opens up.



The property dialog is divided into eight sections additional to the general widget properties on the top: Settings, Button Styles, four different kinds of Scripts, Network Broadcasting and Ui Effects & Animations.

General Widget Settings


A unique name can be entered to identify the widget via the Object and Member Notation. The default name is based on the widget type and ID.


This drop-down offers all available pages to place the widget on.

The CustomScript button's ID may be changed by entering a new one in the text field top left. If you change it, you will be asked if you also want to adapt the name to the new ID.


A short note can be added here. It is not displayed outside the widget but can be set and retrieved with the WidgetID.Note property member.


Uncheck this box to hide the widget.

When the option "Fix" is checked, the CustomScript button will be displayed on every page.


Enter a pixel size for the CustomScript button's size.

X and Y:

Enter the location of the widget (upper left corner) in pixels


Timeout (ms):
The timeout setting can be used to call the click script after a given timeout. The timeout is always restarted upon mouse enter on the control.
This feature is particularly useful for AirScan or touch applications where the user can only position the mouse but not cause a click with the input device.

Mute Click Script:
Set a specific time in milliseconds for a CustomScript click script to be muted (not executed).
This protects a CustomScript button from accidental double clicks.

You may set the button type to be Click or Toggle. The toggle state of the CS button will be kept when the project is saved and loaded.

wd_cs-modesAfter creating a button it is always in the "Released" mode. A button with the Click type has no other status. If you click on it, each time, the "On Press" script is executed. When releasing the mouse click, the button is again into the "Released" mode and the Release Script executed (if defined).

The toggle button has two modes. First it is "Released". When clicking on it, the "On Press" script is executed and the button changes to the "Pressed" mode. The next time it is clicked, the "On Release" script is executed and the button changes to the "Released" mode again.


The modes can be indicated by an image (see below). There are commands that press a button, with or without executing the associated script and with or without changing the mode.

Mouse Capture:
CustomScript buttons allow to capture a mouse left click even when WD GUI is in the background, as well as Mouse Enter and Mouse Leave events. This is useful when WD is used on the same machine as the Pandoras Box Client (e.g. a Server). Please note that the WD interface needs to be minimized for this feature to work!

Interaction (Mouse Click / Release Scripts):

This section is of interest if you like to "click" a CustomScript button without using a mouse device, including node solutions addressing a mouse. It is possible to use the input device directly to execute the "On Press / Release" or "On Mouse Enter / Leave" script. If the device generates more than one input event you can use all of them even if running a Win XP system that is normally restricted to one input event. The following input devices are supported: AirScan, Camera Tracker, iPhone, Kinect, Remote Input, TUIO.
In addition you can also receive inputs from a device that is physically connected and set up on the Pandoras Box Master or even Client system. The Client sends the mouse / touch / etc. inputs to the Master system which sends it through the Widget Designer Device to the Widget Designer interface.

Set up the supported device connection as usual to generate input events.

Last, open the Item Properties of the Custom Script Button that should receive the input data. Enter the script as usual and in the section "Interaction" enable then the check box for the input device, e.g Camera Tracker as shown in the below screenshot. If you like to click the button with data from a PB Master or Client, decide whether the screen (i.e. output resolution) or UV data of a layer is of interest. If you like to filter data from a specific site / layer only, enter the Master's IP address, then the Site (and Device ID) and the filter type. For more info about UV data see the chapter about Layer Picking.

click to enlarge

Web Link URL:

The Web Link section is of special interest when working with the Web Server feature, i.e. clicking the CustomScript button in a web browser. Enter a URL e.g. "" that your browser should call when clicking the button.

But it is also possible to achieve a quick page change with the URL, simply enter a hash tag "#" and the page name. E.g.: #Page2

Button Styles

Enter a label that will be displayed on the button. The text's color can be set via the color field and its font via the according button.

CustomScript buttons can be colored by selecting a tint color, this applies only to the default button images.

Three images can be assigned to the different states of the button (the modes are explained above).
"Release" refers to no click or not toggled.
"Click" is on press or toggled.
"Highlight" can be used to draw a PNG with alpha over either the click or release image.


Click on the "..." button to open a file dialog where you can choose your path and image. If you like to choose an image from the Widget Designer "library", click on the "Res" button. The Resource Manager opens where you can double-click on the image of your choice. You can also save custom images in the Resource Manager to access them faster. The small "x" at the right sets the default image.

For a long time, Custom Script Buttons needed to be rectangular but now they can have any shape you wish. Simply create an according image with transparency and assign it to the Release, Click or Highlight state of the CS button. When you click on a fully transparent area in Run mode, the button does not execute any script. In case you placed another Widget underneath that area, this one will receive that click (however certain drag'n'drop actions to this Widget are not supported).

It is recommended to assign images with the same size to the three states and to reduce the transparent area to the borders of visible pixels.

If you like to work with transparent buttons, it might be faster or more convenient to use Labels (with an on-click-script) instead.


In the Script section you may enter commands to be executed. You can type directly in the text field, the Script Assistant will help you finding the expression you search for. The topic Script Language explains this in more detail.

The scripts for Press, Release, Mouse Enter and Mouse Leave are executed when the Widget Designer button is being used, on the local interface as well as on any web client.

You can put as much text in one of the scripting fields as you like, but for keeping a good overview, using Macros and Functions is recommended for sophisticated scripts
If you are interested in the Web Server feature and some small examples, please read the topics Web Server and Object and Member Notation .

See here a list of all commands.

Network Broadcasting

The NBS (Network Broadcast Service) allows transmitting and updating Faders, Labels and CustomScript buttons across multiple WD Designers instances on the network. To activate this service, please refer to the Remoting Menu!

Enable Send:
To send the CustomScript buttons state (clicked or released) as broadcast into the network, you only have to check "Enable Send".

Enable Receive:
To receive values from other CustomScript buttons, please check "Enable Receive".

Now you have to specify which item should update your CustomScript button:
Enter the IP address of the computer you want to listen to. This could be the local computer (to control the CustomScript button through another CustomScript button on the same Widget Designer) or a different computer in the network. If you do not want to specify the computer but want to listen to all computers in the network, enter "".

As next step specify the CustomScript button you want to take the status from. This could be e.g. "CustomScript1" or "CustomScript2".

Ui Effects & Animations

The topic Effects & Animations explains how to add and apply CSS based effects and animations.