Widget class

The Widget class allows you to create components for a graphical user interface. More...

The D3PLOT JavaScript API provides many class constants, properties and methods. For Arup to be able to extend and enhance the API in the future any constant, property or method names beginning with a lowercase or uppercase letter are reserved.
If you need to add your own properties or methods to one of the existing classes then to avoid any potential future conflict you should ensure that the name begins with either an underscore (_) or a dollar sign ($) or the name is prefixed with your own unique identifier.
For example if company 'ABC' need to add a property called 'example' then to avoid any potential future conflict use one of:

Class functions

Member functions

Widget constants

Name Description
Widget.BUTTON Button widget
Widget.CHECKBOX Checkbox widget
Widget.COMBOBOX Combobox widget
Widget.LABEL Label widget
Widget.LISTBOX Listbox widget
Widget.RADIOBUTTON Radiobutton widget
Widget.SLIDER Slider widget
Widget.TEXTBOX Text input widget
Widget.TREE Tree widget

Constants for Colour

Name Description
Widget.BLACK Colour black
Widget.BLUE Colour blue
Widget.COLOUR_CONTRAST A contrasting colour in the 3 user interface themes (Green, Purple, and Blue in the Dark, Light, and Classic themes respectively). Blue in the legacy theme.
Widget.COLOUR_CONTRAST_2 Another contrasting colour in the 3 user interface themes (Yellow, Red, and Red in the Dark, Light, and Classic themes respectively). Red in the legacy theme.
Widget.COLOUR_INVERSE Inverse colour in the 3 user interface themes (Black or white depending on theme). Black in the legacy theme.
Widget.COLOUR_LABEL Label text colour in the 3 user interface themes (Black or white depending on theme). Black in the legacy theme.
Widget.COLOUR_LATENT Latent colour in the 3 user interface themes (Different shade of Cyan in every theme). Light Cyan in the legacy theme.
Widget.COLOUR_NEUTRAL Neutral colour in the 3 user interface themes (Different shade of grey in every theme). Light grey in the legacy theme.
Widget.COLOUR_SAFE Safe colour in the 3 user interface themes (Different shade of green in every theme). Dark green in the legacy theme.
Widget.COLOUR_TITLE Title colour in the 3 user interface themes (Different shade of grey in every theme). Dark blue in the legacy theme.
Widget.COLOUR_WARNING Warning colour in the 3 user interface themes (Different shade of red in every theme). Dark red in the legacy theme.
Widget.CYAN Colour cyan
Widget.DARKBLUE Colour dark blue
Widget.DARKGREEN Colour dark green
Widget.DARKGREY Colour dark grey
Widget.DARKGREY_NEUTRAL Only valid in the function 'Line'. Used to keep the 3D effect in the legacy theme and not in the other themes. Neutral colour in the 3 user interface themes (Different shade of grey in every theme). Dark grey in the legacy theme
Widget.DARKRED Colour dark red
Widget.DEFAULT Default colour for widgets
Widget.GREEN Colour green
Widget.GREY Colour grey
Widget.LIGHTGREY Colour light grey
Widget.LIGHTGREY_NEUTRAL Only valid in the function 'Line'. Used to keep the 3D effect in the legacy theme and not in the other themes. Neutral colour in the 3 user interface themes (Different shade of grey in every theme). Light grey in the legacy theme
Widget.MAGENTA Colour magenta
Widget.ORANGE Colour orange
Widget.RED Colour red
Widget.WHITE Colour white
Widget.YELLOW Colour yellow

Constants for Image RGB format

Name Description
Widget.RGB24 24 bits for RGB data in widget images
Widget.RGB8 8 bits for RGB data in widget images

Constants for Justification

Name Description
Widget.BOTTOM Bottom justification
Widget.CENTRE Centre (horizontal) justification
Widget.LEFT Left justification
Widget.MIDDLE Middle (vertical) justification
Widget.RIGHT Right justification
Widget.SCALE Image will be scaled to fit widget
Widget.TOP Top justification

Constants for Orientation

Name Description
Widget.HORIZONTAL Horizontal orientation (for sliders)
Widget.VERTICAL Vertical orientation (for sliders)

Constants for Selection

Name Description
Widget.SELECT_ENHANCED Multiple WidgetItems in a ListBox or tree Widget can be selected. When the user selects a WidgetItem the selection is cleared and the new WidgetItem selected. However, if the user presses the Ctrl key when clicking on a WidgetItem, the clicked WidgetItem gets toggled and all other WidgetItems are left untouched. If the user presses the Shift key while clicking on a WidgetItem, all WidgetItems between the last selected WidgetItem and the clicked WidgetItem are selected or unselected, depending on the state of the clicked WidgetItem.
Widget.SELECT_MULTIPLE Multiple WidgetItems in a ListBox Widget can be selected. When the user selects a WidgetItem, the selection status of that WidgetItem is toggled and the other WidgetItems are left alone.
Not valid for tree widgets. Widget.SELECT_ENHANCED will be used.
Widget.SELECT_NONE No WidgetItem in a ListBox or tree Widget can be selected
Widget.SELECT_SINGLE A single WidgetItem in a ListBox or tree Widget can be selected. When the user selects a WidgetItem, any already-selected WidgetItem becomes unselected, and the user cannot unselect the selected WidgetItem by clicking on it.

Constants for Tree relations

Name Description
Widget.AFTER Add a WidgetItem after the existing WidgetItem for a tree widget.
Widget.BEFORE Add a WidgetItem before the existing WidgetItem for a tree widget.
Widget.CHILD Add a WidgetItem as a child of the existing WidgetItem for a tree widget.

Constants for Tree/listbox scrolling

Name Description
Widget.SCROLL_BOTTOM Scroll tree or listbox widget to bottom.
Widget.SCROLL_DOWN Scroll tree or listbox widget down one.
Widget.SCROLL_PAGE_DOWN Scroll tree or listbox widget down one page.
Widget.SCROLL_PAGE_UP Scroll tree or listbox widget up one page.
Widget.SCROLL_TOP Scroll tree or listbox widget to top.
Widget.SCROLL_UP Scroll tree or listbox widget up one.

Constants for User interface categories

Name Description
Widget.CATEGORY_APPLY Apply buttons
Widget.CATEGORY_BUTTON_BOX A button box panel that contains other widgets
Widget.CATEGORY_CANCEL Buttons which cancel the current operation
Widget.CATEGORY_DATA_ENTRY_HEADER Header for data entry cells, e.g. PRIMER create panels
Widget.CATEGORY_DISMISS Buttons to close or dismiss panels
Widget.CATEGORY_ENTITY Entity types in T/HIS
Widget.CATEGORY_GENERIC A generic button that isn't a special category
Widget.CATEGORY_GENERIC_2 An alternative to the generic category that has a complementary colour
Widget.CATEGORY_HELP Help buttons
Widget.CATEGORY_KEYWORD A PRIMER keyword button
Widget.CATEGORY_LABEL A text label
Widget.CATEGORY_LABEL_BOX Text label with a border
Widget.CATEGORY_LABEL_POPUP Text label with a popup that blends into the background
Widget.CATEGORY_MENU_BOX A menu box
Widget.CATEGORY_MESSAGE For displaying a temporary warning message
Widget.CATEGORY_OPERATE Operate buttons in T/HIS
Widget.CATEGORY_POPUP_BOX A popup box that can contain buttons and plain text
Widget.CATEGORY_SAFE_ACTION Buttons (usually green) to indicate a safe action
Widget.CATEGORY_SEL_ALL Select all
Widget.CATEGORY_TAB Tab
Widget.CATEGORY_TABLE_HEADER Table (column) header
Widget.CATEGORY_TABLE_ROW Table row
Widget.CATEGORY_TEXT_BOX A text box
Widget.CATEGORY_TICKBOX A tick box
Widget.CATEGORY_TITLE Title text
Widget.CATEGORY_TOGGLE Buttons that can be toggled, e.g. On/Off
Widget.CATEGORY_TOOL Buttons within the tools area
Widget.CATEGORY_UNDO Buttons which undo the last operation
Widget.CATEGORY_UNSEL_ALL Unselect/deslect all
Widget.CATEGORY_UPDATE Update buttons which update the screen but leave the panel open
Widget.CATEGORY_WARNING_ACTION Buttons (usually red) to indicate a dangerous action
Widget.NO_CATEGORY No styling is applied. Widget colour controlled by foreground/background properties and is the same in all themes

Widget properties

Name Type Description
active logical If widget is active (true) or disabled (false)
arrows boolean Whether arrows will be shown for a slider (default is true). Slider Widgets only.
background constant Widget background colour. Can be: Widget.BLACK, Widget.WHITE, Widget.RED, Widget.GREEN, Widget.BLUE, Widget.CYAN, Widget.MAGENTA, Widget.YELLOW, Widget.DARKRED, Widget.DARKGREEN, Widget.DARKBLUE, Widget.GREY, Widget.DARKGREY, Widget.LIGHTGREY, Widget.ORANGE, Widget.DEFAULT, Widget.COLOUR_NEUTRAL, Widget.COLOUR_CONTRAST, Widget.COLOUR_CONTRAST_2, Widget.COLOUR_WARNING, Widget.COLOUR_SAFE, Widget.COLOUR_TITLE, Widget.COLOUR_INVERSE, Widget.DARKGREY_NEUTRAL, Widget.LIGHTGREY_NEUTRAL Widget.COLOUR_LATENT, Note, background colours in the Window.THEME_DARK, Window.THEME_LIGHT, and Window.THEME_CLASSIC themes will be determined by the category of the widget not the background colour. To override this behaviour and use this background colour first set the widget category to Widget.NO_CATEGORY.
bottom integer Widget bottom coordinate
category constant The button category which determines the button's appearance when using the new user interface, see Window.Theme()
currentItem WidgetItem object The current WidgetItem for a tree Widget. The current WidgetItem in a tree is shown with a dashed border.
fontSize integer Widget font size in points. Currently only supports the following sizes: 6, 7, 8, 10, 12, 14, 18, 24. Can be used only with Widget.LABEL and Widget.BUTTON. Both LATIN1 and UTF-8 encoding is supported on Windows but Linux only supports LATIN1 encoding at the moment.
foreground constant Widget foreground colour. Can be: Widget.BLACK, Widget.WHITE, Widget.RED, Widget.GREEN, Widget.BLUE, Widget.CYAN, Widget.MAGENTA, Widget.YELLOW, Widget.DARKRED, Widget.DARKGREEN, Widget.DARKBLUE, Widget.GREY, Widget.DARKGREY, Widget.LIGHTGREY, Widget.ORANGE, Widget.DEFAULT, Widget.COLOUR_NEUTRAL, Widget.COLOUR_CONTRAST, Widget.COLOUR_CONTRAST_2, Widget.COLOUR_WARNING, Widget.COLOUR_SAFE, Widget.COLOUR_TITLE, Widget.COLOUR_LABEL, Widget.COLOUR_INVERSE, Widget.DARKGREY_NEUTRAL, Widget.LIGHTGREY_NEUTRAL Widget.COLOUR_LATENT, Note, foreground colours in the Window.THEME_DARK, Window.THEME_LIGHT, and Window.THEME_CLASSIC themes will be determined by the category of the widget not the foreground colour. To override this behaviour and use this foreground colour first set the widget category to Widget.NO_CATEGORY.
hover string Widget hover text
imageHeight (read only) integer Height of widget image (pixels)
imageWidth (read only) integer Width of widget image (pixels)
justify constant Widget justification. Can be: Widget.LEFT, Widget.RIGHT or Widget.CENTRE (default).
left integer Widget left coordinate
lineWidth integer Width of lines when drawing graphics (initially 1; values 1-100 allowed).
macroTag string Tag to use for this widget when recording a macro. If empty then the text property value will be used.
maximum integer The maximum value allowed for a slider (default is 100). Slider Widgets only.
minimum integer The minimum value allowed for a slider (default is 0). Slider Widgets only.
monospace boolean true if the widget uses a monospace font instead of a proportional width font (default). Label and button Widgets only.
onChange function Function to call when the text in a TEXTBOX widget, the selection in a COMBOBOX widget or the value of a SLIDER is changed. The Widget object is accessible in the function using the 'this' keyword (see the example below for more details of how to define the function and how to use the 'this' keyword).
To unset the function set the property to null.
Note that this function is called when the user actually types something into the textbox, selects an item in the combobox or moves the slider, NOT when the Widget.text or Widget.value property changes.
onClick function Function to call when a BUTTON, CHECKBOX, COMBOBOX, LABEL, RADIOBUTTON or TREE widget is clicked. The Widget object is accessible in the function using the 'this' keyword (see the example below for more details of how to define the function and how to use the 'this' keyword).
To unset the function set the property to null.
Note that this function is called when the user actually clicks on the button, NOT when the Widget.pushed property changes. For the COMBOBOX widget the function is called before the list of items is mapped.
onPopup function Function to call when a BUTTON, LABEL, TEXTBOX or TREE widget is right clicked to map a popup. The Widget object is accessible in the function using the 'this' keyword. The PopupWindow can then be found by using the popupWindow property of the Widget.
The function is called before the popup is mapped so you can change the widgets in the popup as required.
onTimer function Function to call for a widget when timerDelay ms have elapsed after setting this. Additionally if timerRepeat is set this function will be called repetitively, every timerDelay ms. The Widget object is accessible in the function using the 'this' keyword.
To unset the function set the property to null.
Note that as soon as this property is set the timer starts!
orientation constant The orientation of a slider. Can be: Widget.VERTICAL or Widget.HORIZONTAL (default). Slider Widgets only.
popupDirection constant How PopupWindow will be mapped relative to this widget. Can be Widget.LEFT, Widget.RIGHT, Widget.TOP or Widget.BOTTOM (default). For tree widgets this will be ignored as the popup is always shown on the WidgetItem that is right clicked.
popupSymbol logical TRUE (default) if a symbol will be shown for a PopupWindow.
popupWindow PopupWindow object PopupWindow for this Widget. Only available for Button, Label and Textbox Widgets. To remove a PopupWindow from a Widget set to null.
pushed logical If widget is pushed (true) or not (false). This only affects Widget.BUTTON with the Widget.toggle property set, and Widget.CHECKBOX widgets.
right integer Widget right coordinate
select constant Selection method for ListBox and tree Widgets. Can be: Widget.SELECT_NONE, Widget.SELECT_SINGLE or Widget.SELECT_MULTIPLE or Widget.SELECT_ENHANCED (default).
selectedItem WidgetItem object WidgetItem that is currently selected for a ComboBox or Radiobutton, Widget. If null no WidgetItem is selected.
For a ListBox Widget this property contains the last WidgetItem that was (de)selected. To get a list of all of the selected WidgetItems use WidgetItems() to return all of the WidgetItems and inspect the WidgetItem selected property.
shown (read only) boolean true if the widget is visible. To alter the visibility of a widget use the Show() and Hide() methods.
step integer The step value of a slider (default is 1). Slider Widgets only.
text string Widget text. For a ComboBox Widget this will be the text for the currently selected WidgetItem
textHidden boolean true if the widget text is hidden and replaced by asterisks. This may be used to create textboxes to type passwords in. TextBox Widgets only.
timerDelay integer Delay in ms before the function set for onTimer will be called. The initial value is 1000 (ms). Also see timerRepeat.
timerRepeat logical If the function set for onTimer will be called once (false) or repeatedly (true). The initial value is false. Also see timerDelay.
toggle logical If widget can be toggled (true) or not (false). This only affects Widget.BUTTON widgets.
top integer Widget top coordinate
type (read only) integer Type of the widget. The widget type could be Widget.BUTTON, Widget.CHECKBOX, Widget.COMBOBOX, Widget.LABEL, Widget.LISTBOX, Widget.RADIOBUTTON, Widget.SLIDER, Widget.TEXTBOX or Widget.TREE
value integer The current value of a slider (initially will be the minimum value). Slider Widgets only.
window (read only) Window object The Window that this widget is defined in
xResolution integer X resolution of button when drawing lines, circles, polygons and rectangles (initially 100). X coordinates on the Widget can be from 0 (on the left of the widget) to xResolution (on the right of the widget). Available for Widget.LABEL and Widget.BUTTON Widgets.
yResolution integer Y resolution of button when drawing lines, circles, polygons and rectangles (initially 100). Y coordinates on the Widget can be from 0 (on the top of the widget) to yResolution (on the bottom of the widget). Available for Widget.LABEL and Widget.BUTTON Widgets.

Detailed Description

The Widget class allows you to create Widgets (buttons, textboxes etc) in a Window for a graphical user interface. Callback functions can be declared for widgets to give actions when a button is pressed or the text in a textbox is selected etc. The following example displays various widgets in a window. Several callback methods are used. The exit button allows the user to exit the script but the button is only made active if the checkbox widget is ticked. If the button widgets are pressed feedback is given to the user 

var count = 0;

// Create window
var w = new Window("Test", 0.8, 1.0, 0.5, 0.6);

// Create all of the widgets
var l = new Widget(w, Widget.LABEL,    1, 30, 1, 7, "Text:");
var t = new Widget(w, Widget.TEXTBOX, 31, 80, 1, 7, "Enter text");
var b = new Widget(w, Widget.BUTTON,   1, 30, 8, 14, "Press me");
var b2= new Widget(w, Widget.BUTTON,  31, 61, 8, 14, "Don't press me");
var c = new Widget(w, Widget.CHECKBOX,62, 68, 8, 14);
var l2= new Widget(w, Widget.LABEL,    1, 80, 15, 21, "You haven't pressed the button yet...");
var e = new Widget(w, Widget.BUTTON,   1, 21, 22, 28, "Exit");

// Allow button widget b2 to toggle
b2.toggle = true;
// The exit button is initially inactive
e.active = false;

// Assign the callback functions
b.onClick  = clicked;
b2.onClick = clicked;
c.onClick  = clicked;
t.onChange = changed;
e.onClick  = confirm_exit;

// Show the window and start event loop
w.Show();

////////////////////////////////////////////////////////////////////////////////

function clicked()
{
// If checkbox is clicked then set the state of the exit button
    if (this === c)
    {
        Message("Checkbox clicked");
        e.active = c.pushed;
    }
// If the "Don't press me' button is pressed then change the colour if the button is pressed in.
    else if (this === b2)
    {
        Message("I said don't press!!!");
        if (b2.pushed) b2.background = Widget.WHITE;
        else           b2.background = Widget.DEFAULT;
    }
// If the "Press me" button is pressed then update the text in the label widget
// with how many times the button has been pressed.
    else
    {
        Message("You pressed...");
        count++;
        l2.text = "Button pressed " + count + " times";
    }
}

////////////////////////////////////////////////////////////////////////////////

function changed()
{
// If the user has changed the text in the textbox then give a message in
// the dialogue box
    Message("Text has changed to " + this.text);
}

////////////////////////////////////////////////////////////////////////////////

function confirm_exit()
{
// Map confirm box
    var ret = Window.Question("Confirm exit", "Are you sure you want to quit?");
// If the user has answered yes then exit from the script.
    if (ret == Window.YES) Exit();
}

In version 20 a tree widget was added. A simple tree widget example is shown below. 

Window.Theme(Window.THEME_CURRENT);

let wi, cwi;

// Create a popup window and some widgets
let pw = new PopupWindow();
let pw_l1 = new Widget(pw, Widget.LABEL, 1, 61,  1,  7, "");
let pw_l2 = new Widget(pw, Widget.LABEL, 1, 61,  7, 13, "");
let pw_l3 = new Widget(pw, Widget.LABEL, 1, 61, 13, 19, "");
let pw_l4 = new Widget(pw, Widget.LABEL, 1, 61, 19, 25, "");
let pw_l5 = new Widget(pw, Widget.LABEL, 1, 61, 25, 31, "");
let pw_l6 = new Widget(pw, Widget.LABEL, 1, 61, 31, 37, "");

// Create window
let w = new Window("JavaScript Tree widget test", 0.85, 1.0, 0.75, 1.0);

// Create tree widget
let t = new Widget(w, Widget.TREE, 1, 61, 1, 51, "Suite");

// Add a root node to tree
let env_wi = new WidgetItem(t, "MyItem");

// Add a child to the root node
wi  = new WidgetItem(t, "PRIMER", Widget.CHILD, env_wi);
cwi = new WidgetItem(t, "Prepare", Widget.CHILD, wi);
wi.onMouseOver = wi_onmouseover;
cwi.hover = "Efficient, reliable model setup with support for all of the latest Ansys LS-DYNA features";

wi  = new WidgetItem(t, "Ansys LS-DYNA", Widget.CHILD, env_wi);
cwi = new WidgetItem(t, "Analyse", Widget.CHILD, wi);
wi.onMouseOver = wi_onmouseover;

// Add a sibling node after Ansys LS-DYNA
wi  = new WidgetItem(t, "REPORTER", Widget.AFTER, wi);
cwi = new WidgetItem(t, "Report", Widget.CHILD, wi);
wi.onMouseOver = wi_onmouseover;
cwi.hover = "Automatic report generation for Ansys LS-DYNA simulations";
 
// Add a sibling node before REPORTER
wi  = new WidgetItem(t, "T/HIS", Widget.BEFORE, wi);
cwi = new WidgetItem(t, "Process", Widget.CHILD, wi);
wi.onMouseOver = wi_onmouseover;
cwi.hover = "Plot, manipulate and process XY data from Ansys LS-DYNA";
 
// Alternatively, create WidgetItem without parent and add
let d3plot_wi   = new WidgetItem(null, "D3PLOT");
t.AddWidgetItem(d3plot_wi, Widget.BEFORE, wi);
cwi = new WidgetItem(null, "Visualise");
t.AddWidgetItem(cwi, Widget.CHILD, d3plot_wi);
d3plot_wi.onMouseOver = wi_onmouseover;
cwi.hover = " In-depth 3D visualisation of Ansys LS-DYNA results";

// Expand root node
env_wi.expanded = true;

// Link popup to tree widget
t.popupWindow = pw;

// Assign callbacks
t.onClick = click_tree;
t.onPopup = do_popup;

// Show the widget and start event loop
w.Show();

////////////////////////////////////////////////////////////////////////////////

function do_popup()
{
    pw_l1.text = this.currentItem.text;

    if (this.currentItem.selected) pw_l2.text = "Selected";
    else                           pw_l2.text = "Not selected";

    if (this.currentItem.Parent())
        pw_l3.text = "Parent: " + this.currentItem.Parent().text;
    else
        pw_l3.text = "No parent";

    if (this.currentItem.FirstChild())
        pw_l4.text = "First child: " + this.currentItem.FirstChild().text;
    else
        pw_l4.text = "No children";

    if (this.currentItem.PreviousSibling())
        pw_l5.text = "Previous: " + this.currentItem.PreviousSibling().text;
    else
        pw_l5.text = "No previous";

    if (this.currentItem.NextSibling())
        pw_l6.text = "Next: " + this.currentItem.NextSibling().text;
    else
        pw_l6.text = "No next";
}

////////////////////////////////////////////////////////////////////////////////

function click_tree()
{
    Message("Clicked on "+this.currentItem.text+" in tree");
}

////////////////////////////////////////////////////////////////////////////////

function wi_onmouseover()
{
    Message("Called onMouseOver for WidgetItem "+this.text+" in tree");
}

Graphics (lines, circles, rectangles etc) can be drawn on Widget.LABEL and Widget.BUTTON widgets. If these methods are used the resolution of the widget is 100 units in x and y and the origin is at the top left of the widget. See the documentation below and the WidgetItem and Window classes for more details.

Constructor

new Widget(window[Window or PopupWindow], type[constant], left[integer], right[integer], top[integer], bottom[integer], text (optional)[string])

Description

Create a new Widget object.

Arguments

  • window (Window or PopupWindow)

    Window or PopupWindow that widget will be created in

  • type (constant)

    Widget type. Can be Widget.BUTTON, Widget.CHECKBOX, Widget.COMBOBOX, Widget.LABEL, Widget.LISTBOX, Widget.RADIOBUTTON, Widget.SLIDER, Widget.TEXTBOX or Widget.TREE

  • left (integer)

    left coordinate of widget

  • right (integer)

    right coordinate of widget

  • top (integer)

    top coordinate of widget

  • bottom (integer)

    bottom coordinate of widget

  • text (optional) (string)

    Text to show on widget (optional for LABEL, BUTTON, TEXTBOX and TREE, not required for CHECKBOX, COMBOBOX, LISTBOX, RADIOBUTTON and SLIDER). For a TREE widget the text will be used as a macroTag.

    Returns

    Widget object

    Return type

    Widget

    Details of functions

    AddWidgetItem(item[WidgetItem], position (optional)[integer])

    Description

    Adds a WidgetItem to a ComboBox ListBox or Radiobutton Widget. Also see Widget.RemoveAllWidgetItems and Widget.RemoveWidgetItem.

    Arguments

  • item (WidgetItem)

    WidgetItem to add

  • position (optional) (integer)

    Position on Widget to add the WidgetItem. Any existing WidgetItems will be shifted down as required. If omitted the WidgetItem will be added to the end of the existing ones. Note that positions start at 0.

    Returns

    No return value

    Example

    To add WidgetItem wi to widget w: 

    w.AddWidgetItem(wi);

    AddWidgetItem(item[WidgetItem], relationship[constant], relitem[WidgetItem])

    Description

    Adds a WidgetItem to a Tree Widget. Also see Widget.RemoveAllWidgetItems and Widget.RemoveWidgetItem.

    Arguments

  • item (WidgetItem)

    WidgetItem to add

  • relationship (constant)

    What relationship (relative to relitem) to use when adding item to the Widget. Can be:
    Widget.BEFORE,
    Widget.AFTER or
    Widget.CHILD.

  • relitem (WidgetItem)

    Existing WidgetItem to add item relative to. If relationship is Widget.CHILD then relitem can be null and then the WidgetItem will be added to the root node of the tree.

    Returns

    No return value

    Example

    To add WidgetItem wi to tree widget w after existing WidgetItem ewi: 

    w.AddWidgetItem(wi, Widget.AFTER, ewi);

    To add WidgetItem wi to tree widget w as a child of existing WidgetItem ewi: 

    w.AddWidgetItem(wi, Widget.CHILD, ewi);

    Circle(colour[constant], fill[boolean], xc[integer], yc[integer], radius[integer])

    Description

    Draws a circle on the widget. Only possible for Widget.LABEL and Widget.BUTTON widgets. The coordinates are local to the Widget, not the Window. See properties xResolution and yResolution for more details. Note that the widget graphics will only be updated when the widget is redrawn. This is to allow the user to do multiple drawing commands on a widget. To force the widget to be redrawn call Show().

    Arguments

  • colour (constant)

    Colour of circle. See foreground for colours.

  • fill (boolean)

    If circle should be filled or not.

  • xc (integer)

    x coordinate of centre of circle.

  • yc (integer)

    y coordinate of centre of circle.

  • radius (integer)

    radius of circle.

    Returns

    no return value

    Example

    To draw a red filled circle, radius 25, at (50, 50) on widget w: 

    w.Circle(Widget.RED, true, 50, 50, 25);

    Clear()

    Description

    Clears any graphics on the widget. Only possible for Widget.LABEL and Widget.BUTTON widgets. Note that the widget graphics will only be updated when the widget is redrawn. This is to allow the user to do multiple drawing commands on a widget. To force the widget to be redrawn call Show().

    Arguments

    No arguments

    Returns

    no return value

    Example

    To clear any graphics for widget w: 

    w.Clear();

    ClearSelection()

    Description

    Clears selection of any WidgetItems on the widget. Only possible for Widget.COMBOBOX, Widget.LISTBOX, Widget.RADIOBUTTON and Widget.TREE widgets.

    Arguments

    No arguments

    Returns

    no return value

    Example

    To clear selection of any WidgetItems for widget w: 

    w.ClearSelection();

    Cross(colour (optional)[constant])

    Description

    Draws a cross symbol on the widget. Only possible for Widget.LABEL and Widget.BUTTON widgets.

    Arguments

  • colour (optional) (constant)

    Colour of cross symbol. See foreground for colours. If omitted, current foreground colour is used.

    Returns

    no return value

    Example

    To draw a red cross symbol on widget w: 

    w.Cross(Widget.RED);

    CtrlPressed() [static]

    Description

    Check to see if the Ctrl key is pressed

    Arguments

    No arguments

    Returns

    true/false

    Return type

    Boolean

    Example

    To test if someone has the Ctrl key pressed: 

    if (Widget.CtrlPressed()) { ... }

    Delete()

    Description

    Deletes the widget from D3PLOT (removing it from the window it is defined in) and returns any memory/resources used for the widget. This function should not normally need to be called. However, sometimes a script may want to recreate widgets in a window many times and unless the old widgets are deleted D3PLOT will reach the maximum number of widgets for a window (Options.max_widgets). To avoid this problem this method can be used to force D3PLOT to delete and return the resources for a widget. Do not use the Widget object after calling this method.

    Arguments

    No arguments

    Returns

    no return value

    Example

    To delete widget w: 

    w.Delete();

    DirectoryIcon(line_colour[constant], fill_colour[constant])

    Description

    Draws a directory icon on the widget. Only possible for Widget.BUTTON widgets.

    Arguments

  • line_colour (constant)

    Colour of lines of folder (only used in the old UI - in the new UI it will be ignored, a standard icon is always used). See foreground for colours.

  • fill_colour (constant)

    Colour of fill of folder (only used in the old UI - in the new UI it will be ignored, a standard icon is always used). See foreground for colours.

    Returns

    no return value

    Example

    To draw a directory icon on widget btn: 

    btn.DirectoryIcon(Widget.BLACK, Widget.YELLOW);

    DumpImageString(filename[string], format (optional)[constant])

    Description

    Dumps a string representation of an image for a widget to a file in a form that can be used by Widget.ReadImageString(). Only possible for Widget.LABEL and Widget.BUTTON widgets.

    Arguments

  • filename (string)

    Filename to dump string representation to

  • format (optional) (constant)

    Can be Widget.RGB8 or Widget.RGB24. Before version 15 D3PLOT only used 8 bits to store RGB (red, green and blue) colour information for widget images. In version 15 widget images have been changed to use 24 bits to store RGB information (8 bits for red, 8 bits for green and 8 bits for blue). Both formats are supported. If omitted the new Widget.RGB24 format will be used. See Widget.ReadImageString() for more details.

    Returns

    no return value

    Example

    To dump the image data to file 'image_data' for widget w with the old 8 bit RGB representation: 

    w.DumpImageString('image_data', Widget.RGB8);

    To dump the image data to file 'image_data' for widget w with 24 bit RGB representation: 

    w.DumpImageString('image_data', Widget.RGB24);

    Hide()

    Description

    Hides the widget on the screen

    Arguments

    No arguments

    Returns

    No return value

    Example

    To hide widget w 

    w.Hide();

    ItemAt(index[integer])

    Description

    Returns the WidgetItem object used at index in this Widget. See also Widget.TotalItems() and Widget.WidgetItems(). Note that for tree Widgets the items will not be returned in the order that they are displayed in, they will be returned in the order they were added to the tree.

    Arguments

  • index (integer)

    index to return WidgetItem for. Note that indices start at 0.

    Returns

    WidgetItem object.

    Return type

    WidgetItem

    Example

    To loop over the WidgetItems used in Widget w 

    for (i=0; i<w.TotalItems(); i++)
{
    wi = w.ItemAt(i);
}

    Line(colour[constant], x1[integer], y1[integer], x2[integer], y2[integer])

    Description

    Draws a line on the widget. Only possible for Widget.LABEL and Widget.BUTTON widgets. The coordinates are local to the Widget, not the Window. See properties xResolution and yResolution for more details. Note that the widget graphics will only be updated when the widget is redrawn. This is to allow the user to do multiple drawing commands on a widget. To force the widget to be redrawn call Show().

    Arguments

  • colour (constant)

    Colour of line. See foreground for colours.

  • x1 (integer)

    x coordinate of start of line.

  • y1 (integer)

    y coordinate of start of line.

  • x2 (integer)

    x coordinate of end of line.

  • y2 (integer)

    y coordinate of end of line.

    Returns

    no return value

    Example

    To draw a red line from (10, 90) to (90, 10) on widget w: 

    w.Line(Widget.RED, 10, 90, 90, 10);

    MoveWidgetItem(item[WidgetItem], relationship[constant], relitem[WidgetItem or null])

    Description

    Moves an existing WidgetItem in a tree Widget. Also see Widget.RemoveAllWidgetItems and Widget.RemoveWidgetItem.

    Arguments

  • item (WidgetItem)

    WidgetItem to move

  • relationship (constant)

    What relationship (relative to relitem) to use when moving item to the Widget. Can be:
    Widget.BEFORE,
    Widget.AFTER or
    Widget.AFTER.

  • relitem (WidgetItem or null)

    Existing WidgetItem to move item relative to. If relationship is Widget.CHILD then relitem can be null and then the WidgetItem will be moved to the root node of the tree.

    Returns

    No return value

    Example

    To move WidgetItem wi in tree widget w after existing WidgetItem ewi: 

    w.MoveWidgetItem(wi, Widget.AFTER, ewi);

    To move WidgetItem wi in tree widget w as a child of existing WidgetItem ewi: 

    w.MoveWidgetItem(wi, Widget.CHILD, ewi);

    PixelsPerUnit() [static]

    Description

    Returns the number of pixels per unit coordinate. This will vary depending on the monitor D3PLOT is running on.

    Arguments

    No arguments

    Returns

    pixels/unit (real)

    Return type

    Number

    Example

    To return how many pixels there are per unit coordinate: 

    var ppu = Widget.PixelsPerUnit();

    Polygon(colour[constant], fill[boolean], points[array])

    Description

    Draws a polygon on the widget. Only possible for Widget.LABEL and Widget.BUTTON widgets. The coordinates are local to the Widget, not the Window. See properties xResolution and yResolution for more details. Note that the widget graphics will only be updated when the widget is redrawn. This is to allow the user to do multiple drawing commands on a widget. To force the widget to be redrawn call Show(). The number of points (x, y pairs) is limited to 500. Any extra points will be ignored.

    Arguments

  • colour (constant)

    Colour of polygon. See foreground for colours.

  • fill (boolean)

    If polygon should be filled or not.

  • points (array)

    Array of point coordinates

    Returns

    no return value

    Example

    To draw a red filled triangle with corners (20, 20) and (50, 80) and (80, 20) on widget w: 

    var a = new Array(20, 20, 50, 80, 80, 20);
w.Polygon(Widget.RED, true, a);

    Polygon(colour[constant], fill[boolean], x1[integer], y1[integer], x2[integer], y2[integer], ... xn[integer], ... yn[integer])   [deprecated]

    This function is deprecated in version 21.0. It is only provided to keep old scripts working. We strongly advise against using it in new scripts. Support may be removed in future versions.

    Description

    Draws a polygon on the widget. Only possible for Widget.LABEL and Widget.BUTTON widgets. The coordinates are local to the Widget, not the Window. See properties xResolution and yResolution for more details. Note that the widget graphics will only be updated when the widget is redrawn. This is to allow the user to do multiple drawing commands on a widget. To force the widget to be redrawn call Show(). The number of points (x, y pairs) is limited to 500. Any extra points will be ignored.

    Arguments

  • colour (constant)

    Colour of polygon. See foreground for colours.

  • fill (boolean)

    If polygon should be filled or not.

  • x1 (integer)

    x coordinate of point 1.

  • y1 (integer)

    y coordinate of point 1.

  • x2 (integer)

    x coordinate of point 2.

  • y2 (integer)

    y coordinate of point 2.

  • ... xn (integer)

    x coordinate of point n.

  • ... yn (integer)

    y coordinate of point n.

    Returns

    no return value

    Example

    To draw a red filled triangle with corners (20, 20) and (50, 80) and (80, 20) on widget w: 

    w.Polygon(Widget.RED, true, 20, 20, 50, 80, 80, 20);

    ReadImageFile(filename[string], justify (optional)[constant], transparent (optional)[colour value (integer)], tolerance (optional)[integer])

    Description

    Reads an image from a file to show on the widget. Only possible for Widget.LABEL and Widget.BUTTON widgets. The image will be shown on the widget underneath any text. Note that due to the way that colours are used for menus in D3PLOT only a small number of colours are available for Widget images. Black and white images will display without any issues but colour images will be displayed with a reduced set of colours.

    Arguments

  • filename (string)

    Image file (BMP, GIF, JPEG or PNG) to read. To remove an image use null.

  • justify (optional) (constant)

    Widget justification. Can be a bitwise or of Widget.LEFT, Widget.RIGHT or Widget.CENTRE and Widget.TOP, Widget.MIDDLE or Widget.BOTTOM. Additionally Widget.SCALE can be used to scale the image (either reducing or enlarging it) so that it fills the widget. If omitted the default is Widget.CENTRE|Widget.MIDDLE without scaling.

  • transparent (optional) (colour value (integer))

    Transparent colour. Must be a colour returned by Colour.RGB() in D3PLOT. If given then this colour will be replaced by a transparent colour. i.e. the widget background colour will be shown. If omitted or null no transparency will be used.

  • tolerance (optional) (integer)

    Tolerance for transparent colour (0-255).
    Any pixels in the image that have a red, green and blue colour value within tolerance of the transparent colour will be transparent.
    For example if the transparent colour was given as Colour.RGB(255, 0, 0) and tolerance is 0 only pixels which have red value 255 and green value 0 and blue value 0 will be made transparent.
    If tolerance is 4, pixels which have red values between 251 and 255 and green values between 0 and 4 and blue values between 0 and 4 will be made transparent.
    If omitted a value of 8 will be used.

    Returns

    no return value

    Example

    To read image example.png for widget w and place it at the top left: 

    w.ReadImageFile("example.png", Widget.TOP|Widget.LEFT);

    To read image example.png for widget w and place it at the top left, scaling it to fit the widget: 

    w.ReadImageFile("example.png", Widget.TOP|Widget.LEFT|Widget.SCALE);

    To read image example.png for widget w and place it at the top left, replacing red with a transparent colour: 

    w.ReadImageFile("example.png", Widget.TOP|Widget.LEFT, Colour.RGB(255, 0, 0));

    To remove an image from widget w: 

    w.ReadImageFile(null);

    ReadImageString(string[string], justify (optional)[constant], transparent (optional)[colour value (integer)], tolerance (optional)[integer])

    Description

    Reads an image from a JavaScript string previously created by Widget.DumpImageString() to show on the widget. Only possible for Widget.LABEL and Widget.BUTTON widgets. The image will be shown on the widget underneath any text.
    Note, prior to version 15 of D3PLOT only a small number of colours were available for Widget images. In version 14 and earlier the RGB (red, green and blue) information for each pixel in the image was packed into a single byte (8 bits) with 3 bits for red, 3 for green and 2 for blue. Widget.DumpImageString() always returned the string beginning with "RRRGGGBB_RLE" which is this 8 bit format with run length encoding. This is format Widget.RGB8.
    In version 15 support for Widget images was enhanced to give 24bit support for colours. The RGB information for each pixel has 8 bits for red, 8 bits for green and 8 bits for blue. This is format Widget.RGB24.
    From version 15 Widget.DumpImageString() can either return the the old 8 bit format Widget.RGB8 (string beginning with "RRRGGGBB_RLE") or return the the new 24bit format Widget.RGB24 (string beginning with "RGB24_Z").
    ReadImageString supports both formats.

    Arguments

  • string (string)

    String containing the image data previously created by Widget.DumpImageString(). To remove an image use null.

  • justify (optional) (constant)

    Widget justification. Can be a bitwise or of Widget.LEFT, Widget.RIGHT or Widget.CENTRE and Widget.TOP, Widget.MIDDLE or Widget.BOTTOM. Additionally Widget.SCALE can be used to scale the image (either reducing or enlarging it) so that it fills the widget. If omitted the default is Widget.CENTRE|Widget.MIDDLE without scaling.

  • transparent (optional) (colour value (integer))

    Transparent colour. Must be a colour returned by Colour.RGB() in D3PLOT. If given then this colour will be replaced by a transparent colour. i.e. the widget background colour will be shown. If omitted or null no transparency will be used.

  • tolerance (optional) (integer)

    Tolerance for transparent colour (0-255). Only used for the new 24bit format Widget.RGB24 (strings beginning with "RGB24_Z"). Ignored for the old 8 bit format Widget.RGB8 (strings beginning with "RRRGGGBB_RLE").
    Any pixels in the image that have a red, green and blue colour value within tolerance of the transparent colour will be transparent.
    For example if the transparent colour was given as Colour.RGB(255, 0, 0) and tolerance is 0 only pixels which have red value 255 and green value 0 and blue value 0 will be made transparent.
    If tolerance is 4, pixels which have red values between 251 and 255 and green values between 0 and 4 and blue values between 0 and 4 will be made transparent.
    If omitted a value of 8 will be used.

    Returns

    no return value

    Example

    To read image data from string s for widget w and place it at the top left: 

    w.ReadImageString(s, Widget.TOP|Widget.LEFT);

    To read image data from string s for widget w and place it at the top left, scaling it to fit the widget: 

    w.ReadImageString(s, Widget.TOP|Widget.LEFT|Widget.SCALE);

    To read image data from string s for widget w and place it at the top left, replacing red with a transparent colour: 

    w.ReadImageString(s, Widget.TOP|Widget.LEFT, Colour.RGB(255, 0, 0));

    To remove an image from widget w: 

    w.ReadImageString(null);

    Rectangle(colour[constant], fill[boolean], x1[integer], y1[integer], x2[integer], y2[integer])

    Description

    Draws a rectangle on the widget. Only possible for Widget.LABEL and Widget.BUTTON widgets. The coordinates are local to the Widget, not the Window. See properties xResolution and yResolution for more details. Note that the widget graphics will only be updated when the widget is redrawn. This is to allow the user to do multiple drawing commands on a widget. To force the widget to be redrawn call Show().

    Arguments

  • colour (constant)

    Colour of rectangle. See foreground for colours.

  • fill (boolean)

    If rectangle should be filled or not.

  • x1 (integer)

    x coordinate of first corner of rectangle.

  • y1 (integer)

    y coordinate of first corner of rectangle.

  • x2 (integer)

    x coordinate of second (opposite) corner of rectangle.

  • y2 (integer)

    y coordinate of second (opposite) corner of rectangle.

    Returns

    no return value

    Example

    To draw a red filled rectangle with corners (20, 20) and (80, 80) on widget w: 

    w.Rectangle(Widget.RED, true, 20, 20, 80, 80);

    RemoveAllWidgetItems()

    Description

    Removes any WidgetItems from the Widget. Also see Widget.AddWidgetItem and Widget.RemoveWidgetItem.

    Arguments

    No arguments

    Returns

    No return value

    Example

    To remove all WidgetItems from widget w: 

    w.RemoveAllWidgetItems();

    RemoveWidgetItem(item[WidgetItem])

    Description

    Removes a WidgetItem from the Widget. Also see Widget.AddWidgetItem and Widget.RemoveAllWidgetItems.

    Arguments

  • item (WidgetItem)

    WidgetItem to remove

    Returns

    No return value

    Example

    To remove WidgetItem wi from widget w: 

    w.RemoveWidgetItem(wi);

    Scroll(scroll[constant or WidgetItem object])

    Description

    Scrolls a tree or listbox widget

    Arguments

  • scroll (constant or WidgetItem object)

    How to scroll the tree/listbox widget. Can be: Widget.SCROLL_TOP, Widget.SCROLL_BOTTOM, Widget.SCROLL_UP, Widget.SCROLL_DOWN, Widget.SCROLL_PAGE_UP or Widget.SCROLL_PAGE_DOWN in which case the tree/listbox widget will be scrolled by that value or a WidgetItem, in which case the tree/listbox will be scrolled to make the WidgetItem visible, (expanding any branches as necessary to do so for the tree widget).

    Returns

    No return value

    Example

    To scroll tree widget w to the top: 

    w.Scroll(Widget.SCROLL_TOP);

    To scroll listbox widget w so that WidgetItem wi is visible: 

    w.Scroll(wi);

    ShiftPressed() [static]

    Description

    Check to see if the Shift key is pressed

    Arguments

    No arguments

    Returns

    true/false

    Return type

    Boolean

    Example

    To test if someone has the Shift key pressed: 

    if (Widget.ShiftPressed()) { ... }

    Show()

    Description

    Shows the widget on the screen

    Arguments

    No arguments

    Returns

    No return value

    Example

    To show widget w: 

    w.Show();

    Static()

    Description

    Windows have two different regions for Widgets. A 'normal' region which can be scrolled if required (if the window is made smaller scrollbars will be shown which can be used to scroll the contents) and a 'static' region at the top of the Window which is fixed and does not scroll. For an example of a static region in a Window see any of the keyword editing panels. The 'Dismiss', 'Create', 'Reset' etc buttons are in the static region. By default Widgets are put into the normal region of the Window. This method puts the Widget to the static region of the Window.

    Arguments

    No arguments

    Returns

    No return value

    Example

    To put widget w in the static part of the window: 

    w.Static();

    StringLength(text[string], monospace (optional)[boolean], fontSize (optional)[integer]) [static]

    Description

    Returns the length of a string in Widget units. This can be used to find what size a Widget must be to be able to display the string.

    Arguments

  • text (string)

    Text to find the width of

  • monospace (optional) (boolean)

    If true then width will be calculated using a monospace font. If false (default) then the normal proportional width font will be used

  • fontSize (optional) (integer)

    Calculation can be based on a defined font size, at the moment support is added only for font sizes of 6, 7, 8, 10, 12, 14, 18 and 24.

    Returns

    integer

    Return type

    Number

    Example

    To get the width of string 'Example': 

    var len = Widget.StringLength('Example');

    Tick(colour (optional)[constant])

    Description

    Draws a tick symbol on the widget. Only possible for Widget.LABEL and Widget.BUTTON widgets.

    Arguments

  • colour (optional) (constant)

    Colour of tick symbol. See foreground for colours. If omitted, current foreground colour is used.

    Returns

    no return value

    Example

    To draw a red tick symbol on widget w: 

    w.Tick(Widget.RED);

    TotalItems()

    Description

    Returns the number of the WidgetItem objects used in this Widget (or 0 if none used). See also Widget.ItemAt() and Widget.WidgetItems().

    Arguments

    No arguments

    Returns

    integer

    Return type

    Number

    Example

    To return the total number of WidgetItems used for Widget w 

    var total = w.TotalItems();

    WidgetItems()

    Description

    Returns an array of the WidgetItem objects used in this Widget (or null if none used). See also Widget.ItemAt() and Widget.TotalItems().

    Arguments

    No arguments

    Returns

    Array of WidgetItem objects

    Return type

    Array

    Example

    To return WidgetItems used for Widget w 

    var wi = w.WidgetItems();