Window class

Returns

Window object

Return type

Window

Example

To create a Window 'Example' in the top right half of the screen:

var w = new Window('Example', 0.5, 1.0, 0.5, 1.0);

Details of functions

BottomBorder() [static]

Description

Returns the vertical position of the bottom border (in range 0-1). This can be used to help position windows on the screen.

Returns

real in range 0-1

Return type

Number

Example

To obtain the position of the bottom border:

var b = Window.BottomBorder();

BuildGUIFromString(guistring[string]) [static]

Description

Builds a GUI from a JSON string created by the GUI builder.

Returns

object containing the GUI

Return type

Object

Example

To create a GUI from the string json_string:

var gui = Window.BuildGUIFromString(json_string);

Delete()

Description

Deletes the window from PRIMER and returns any memory/resources used for the window. This function should not normally need to be called. However, in exceptional circumstances if a script recreates windows many times PRIMER may run out of USER objects on Microsoft Windows because of the way PRIMER creates and shows windows. To avoid this problem this method can be used to force PRIMER to return the resources for a window. Do not use the Window object after calling this method.

Returns

No return value

Example

To delete window w:

w.Delete();

EndLoop() [static]

Description

Ends an event loop started by Window.StartLoop()

Returns

No return value

Example

To end a blocking event loop started by Window.StartLoop():

Window.EndLoop();

Error(title[string], error[string], buttons (optional)[constant]) [static]

Description

Show an error message in a window.

Returns

Button pressed

Return type

Number

Example

To show error Critical error!\nAbort? in window with title Error with Yes and No buttons:

var answer = Window.Error("Error", "Critical error!\nAbort?", Window.YES | Window.NO);
if (answer == Window.YES) Exit(); 

GetDirectory(initial (optional)[string]) [static]

Description

Map the directory selector box native to your machine, allowing you to choose a directory. On Unix this will be a Motif selector. Windows will use the standard windows directory selector.

Returns

directory (string), (or null if cancel pressed).

Return type

String

Example

To select a directory:

var dir = Window.GetDirectory();

GetFile(extension (optional)[string], save (optional)[boolean], initial (optional)[string]) [static]

Description

Map a file selector box allowing you to choose a file. See also Window.GetFiles() and Window.GetFilename().

Returns

filename (string), (or null if cancel pressed).

Return type

String

Example

To select a file using extension '.key':

var file = Window.GetFile(".key");

GetFilename(title[string], message[string], extension (optional)[string], initial (optional)[string], save (optional)[boolean]) [static]

Description

Map a window allowing you to input a filename (or select it using a file selector). OK and Cancel buttons are shown. See also Window.GetFile().

Returns

filename (string), (or null if cancel pressed).

Return type

String

Example

To create an file input window with title Choose file and message Choose the file to open and return the filename input:

var filename = Window.GetFilename("Choose file", "Choose the file to open");

GetFiles(extension (optional)[string]) [static]

Description

Map a file selector box allowing you to choose multiple files. See also Window.GetFile() and Window.GetFilename().

Returns

Array of filenames (strings), or null if cancel pressed.

Return type

String

Example

To select multiple files using extension '.key':

var files = Window.GetFiles(".key");

GetGraphicsWindowPosition() [static]

Description

This function returns the current position of the graphics window.

Returns

Array of numbers containing the left, right, bottom and top positions (in the range 0.0 to 1.0)

Return type

Number

Example

To get the current position of the graphics window:

var pos = Window.GetGraphicsWindowPosition();
var l = pos[0];
var r = pos[1];
var b = pos[2];
var t = pos[3];

GetInteger(title[string], message[string], initial (optional)[integer]) [static]

Description

Map a window allowing you to input an integer. OK and Cancel buttons are shown.

Returns

value input (integer), or null if cancel pressed.

Return type

Number

Example

To create an input window with title Input and message Input integer and return the value input:

var value = Window.GetInteger("Input", "Input integer");

GetNumber(title[string], message[string], initial (optional)[real]) [static]

Description

Map a window allowing you to input a number. OK and Cancel buttons are shown.

Returns

value input (real), or null if cancel pressed.

Return type

Number

Example

To create an input window with title Input and message Input number and return the value input:

var value = Window.GetNumber("Input", "Input number");

GetPassword(title[string], message[string]) [static]

Description

Map a window allowing you to input a password. OK and Cancel buttons are shown.
This is identical to Window.GetString except the string is hidden and no initial value can be given.

Returns

value input (string), or null if cancel pressed.

Return type

String

Example

To create an input window with title Input and message Input password and return the value input:

var value = Window.GetPassword("Input", "Input password");

GetString(title[string], message[string], initial (optional)[string]) [static]

Description

Map a window allowing you to input a string. OK and Cancel buttons are shown.

Returns

value input (string), or null if cancel pressed.

Return type

String

Example

To create an input window with title Input and message Input string and return the value input:

var value = Window.GetString("Input", "Input string");

Hide()

Description

Hides (unmaps) the window. Also see the Window onHide property.

Returns

No return value

Example

To hide window w:

w.Hide();

Information(title[string], info[string], buttons (optional)[constant]) [static]

Description

Show information in a window.

Returns

Button pressed

Return type

Number

Example

To show information Information in window with title Example with OK and Cancel buttons:

var answer = Window.Information("Example", "Information", Window.OK | Window.CANCEL);
if (answer == Window.CANCEL) Message("You pressed the Cancel button"); 

MasterResolution() [static]

Description

Returns the resolution of the master programme window in pixels

Returns

Array of numbers containing x and y resolution in pixels

Return type

Number

Example

To get the resolution of the main window:

var res = Window.MasterResolution();

Message(title[string], message[string], buttons (optional)[constant]) [static]

Description

Show a message in a window.

Returns

Button pressed

Return type

Number

Example

To show message Press YES or NO in window with title Example with YES and NO buttons:

var answer = Window.Message("Example", "Press YES or NO", Window.YES | Window.NO);
if (answer == Window.NO) Message("You pressed No"); 

MiddleBorder() [static]

Description

Returns the vertical position of the middle border (in range 0-1). The middle border is the border between the tools/keywords window and the docked windows. This can be used to help position windows on the screen.

Returns

real in range 0-1

Return type

Number

Example

To obtain the position of the middle border:

var b = Window.MiddleBorder();

Question(title[string], question[string], buttons (optional)[constant]) [static]

Description

Show a question in a window.

Returns

Button pressed

Return type

Number

Example

To show question Do you want to continue? in window with title Question:

var answer = Window.Question("Question", "Do you want to continue?");
if (answer == Window.NO) Message("You pressed No"); 

Recompute()

Description

Recomputes the positions of widgets in the window. If you have static widgets and 'normal' widgets in a window and you show and/or hide widgets the window needs to be recomputed to refresh the graphics, scroll bars etc. Calling this method will recompute and redraw the window.

Returns

No return value

Example

To recompute window w:

w.Recompute();

Redraw()

Description

Redraws the window. Sometimes if you show, hide or draw graphics on widgets the window needs to be redrawn to refresh the graphics. Calling this method will redraw the window refreshing the graphics.

Returns

No return value

Example

To redraw window w:

w.Redraw();

RightBorder() [static]

Description

Returns the horizontal position of the right border (in range 0-1). This can be used to help position windows on the screen.

Returns

real in range 0-1

Return type

Number

Example

To obtain the position of the right border:

var b = Window.RightBorder();

SetGraphicsWindowPosition(left[real], right[real], bottom[real], top[real]) [static]

Description

This function allows you to move or resize the graphics window.

Returns

No return value

Example

To move/resize the graphics window to be in the top left half of the screen:

Window.SetGraphicsWindowPosition(0.0, 0.5, 0.5, 1.0);

SetGraphicsWindowSize(width[integer], height[integer]) [static]

Description

This function allows you to resize the graphics window.

Returns

No return value

Example

To resize the graphics window to be 400 pixels wide and 300 pixels high:

Window.SetGraphicsWindowSize(400, 300);

Show(modal (optional)[boolean])

Description

Shows (maps) the window and waits for user input.

Returns

No return value

Example

To show window w:

w.Show();

To show window w allowing the user to use other functions in PRIMER:

w.Show(false);

StartLoop() [static]

Description

Starts a blocking event loop in PRIMER. Before version 21 PRIMER would create a blocking event loop when the Window Show method was called (the call to the Window Show method would not return until the window was hidden again). In PRIMER version 21 the logic has been changed so that Window Show maps the window and returns straight away. The window is managed from the main event loop in PRIMER. In most cases this will make no differences to scripts but there may be rare cases where you specifically want the blocking behaviour. An example of this is using a keyout hook script, or if you want to give aprompt/question similarly to Window.Message() where you do not want to return to the main event loop. You want to block until the user has specified the action.
Window.StartLoop() can be used to start a local blocking, event loop. To terminate the event loop and resume execution of the script use Window.EndLoop()
Note that only a single loop can be active in PRIMER at any one time. i.e. they cannot be nested. Window.StartLoop() should be used as sparingly as possible and only used for specific short events (e.g. something like the equivalent of Window.Message() where you really do need to block) as if it is used in one script it will prevent it from being used in another script.

Returns

No return value

Example

To start a blocking event loop:

Window.StartLoop();

Theme(theme (optional)[constant]) [static]

Description

Set or get a user interface theme.

Returns

Integer. When getting the theme one of: Window.USE_OLD_UI_JS, Window.THEME_DARK, Window.THEME_LIGHT, Window.THEME_CLASSIC

Return type

Number

Example

To determine the current theme:

var ui = Window.Theme();
      if(ui == Window.THEME_DARK)
      {
          print("Theme is dark\n");
      }
      else if(ui == Window.THEME_LIGHT)
      {
          print("Theme is light\n");
      }
      else if(ui == Window.THEME_CLASSIC)
      {
          print("Theme is classic\n");
      }
      else
      {
          print("Theme is not set\n");
      }
      

To keep the original (pre v17) appearance of your JavaScript (default):

Window.Theme(Window.USE_OLD_UI_JS);

To use the current user interface theme:

Window.Theme(Window.THEME_CURRENT);

To use the dark user interface theme:

Window.Theme(Window.THEME_DARK);

TopBorder() [static]

Description

Returns the vertical position of the top border (in range 0-1). This can be used to help position windows on the screen. This is no longer used in PRIMER and will always be 1 but is left for backwards compatibility.

Returns

real in range 0-1

Return type

Number

Example

To obtain the position of the top border:

var b = Window.TopBorder();

UpdateGUI() [static]

Description

Force GUI to be updated. This function is not normally needed but if you are doing a computationally expensive operation and want to update the GUI it may be necessary as the GUI update requests are cached until there is spare time to update them. Calling this function forces any outstanding requests to be flushed.

Returns

No return value

Example

To force update of GUI:

Window.UpdateGUI();

Warning(title[string], warning[string], buttons (optional)[constant]) [static]

Description

Show a warning message in a window.

Returns

Button pressed

Return type

Number

Example

To show warning Title is blank\nSet to ID? in window with title Warning with Yes and No buttons:

var answer = Window.Warning("Warning", "Title is blank\nSet to ID?", Window.YES | Window.NO);
if (answer == Window.NO) Message("You pressed No");