_{Official ZPE/YASS documentation}zpe.lib.ui

The UI system provides access to ZPE’s native UI toolkit. It allows scripts to create windows (frames), create UI components, and build interactive interfaces in GUI environments.

One of the projects I have been working myself is a home automation program. As such I use ZPE/YASS to do this since it gives more power over many other languages. I use the UIBuilder to make it easy to run these programs. For example I have an option to wake and shutdown my PC. You can find my home automation program on my ZPE Online account.

Objects

ZPEUIBuilder

The UI Builder is used to create new windows. If ZPE is running in a headless environment (or ZPE Native), the UI Builder object cannot be created and will output an error message.

new_frame (string title, number arc) ⇒ object

Creates a new UI frame (window) with the given title and optional rounded-corner radius. The arc value controls how rounded the window corners are.

Note: This method returns the UI Builder object (as implemented), not the frame object.

ZPEFrame

A frame represents a window created using the UI Builder. Frames can contain UI elements (buttons, containers, lists, turtles, etc.) and provide methods for window configuration, element creation, showing/hiding, and responding to the user closing the window.

add (object component) ⇒ object

Adds a UI component to the frame. The provided component must be a UI item. The component is also registered internally so it can be retrieved using get_element_by_id. Returns the frame object.

set_title (string title) ⇒ object

Sets the window title. Returns the frame object.

set_footer_text (string text) ⇒ object

Sets the window footer text (if a footer exists for the current window style). Returns the frame object.

create_turtle () ⇒ object

Creates and returns a ZPETurtle object which draws onto the frame.

set_size (number width, number height) ⇒ null

Sets the frame size in pixels. Note: this method returns null (as implemented), not the frame object.

set_on_close (function func) ⇒ object

Sets a function to run when the user closes the window using the close button. Returns the frame object.

get_element_by_id (string id) ⇒ object

Returns a previously added UI element by its ID.

create_container () ⇒ object

Creates and returns a new container UI object.

create_button (string text[, number arc]) ⇒ object

Creates and returns a new ZPEButton UI object. The arc value controls how rounded the button corners are (defaults to 4 if not provided).

create_list () ⇒ object

Creates and returns a new list UI object.

create_quadratic () ⇒ string

Draws a simple quadratic plot on the frame and returns an empty string. (This is currently a demo/test method.)

alert (string text, string title) ⇒ object

Shows an alert dialog with the given title and text. Returns the frame object.

set_always_on_top (boolean enabled) ⇒ object

Enables or disables the "always on top" window setting. Returns the frame object.

show () ⇒ object

Shows the window. Returns the frame object.

hide () ⇒ object

Hides and disposes of the window. Returns the frame object.

ZPEContainer

A container is a UI element used to group other UI components together. A container can have its own background, layout, size, visibility, and border, and can contain multiple child components.

_construct (number arc) ⇒ object

Constructs the container and optionally sets the corner radius. The arc value controls how rounded the container corners are. Returns the container object.

add (object component) ⇒ object

Adds a UI component to the container. The provided component must be a UI item. Returns the container object.

set_background (object colour) ⇒ object

Sets the background colour of the container. Returns the container object.

set_layout (string layout) ⇒ object

Sets the layout manager for the container. Supported values are: flow, border, and grid. Returns the container object.

set_visible (boolean visible) ⇒ object

Shows or hides the container. Returns the container object.

set_size (number width, number height) ⇒ object

Sets the preferred size of the container in pixels. Returns the container object.

set_border (string colour, number thickness) ⇒ object

Sets a rounded border around the container. The colour should be a hex colour string (for example, #ff8800), and thickness is the border thickness in pixels. Returns the container object.

clear () ⇒ object

Removes all child components from the container. Returns the container object.

ZPEButton

A button UI element. Buttons support attaching event handlers for mouse actions, and support common styling and behaviour options such as text, enabled state, colours, font size, and tooltips.

on (string action, function method) ⇒ object

Registers a function to run when an action occurs on the button. Common actions include: click, double_click, middle_click, right_click, and mouseover. Returns the button object.

set_text (string text) ⇒ object

Sets the button text. Triggers the set_text action. Returns the button object.

set_enabled (boolean enabled) ⇒ object

Enables or disables the button. Returns the button object.

set_foreground (object colour) ⇒ object

Sets the button text (foreground) colour using a Colour object. Returns the button object.

set_background (object colour) ⇒ object

Sets the button background colour using a Colour object. Returns the button object.

set_font_size (number size) ⇒ object

Sets the button font size. Returns the button object.

set_tooltip (string text) ⇒ object

Sets the tooltip text displayed when hovering over the button. Returns the button object.

ZPEList

A list UI element backed by a list model. Lists support adding/removing items, clearing, and reading the currently selected item.

on (string action, function method) ⇒ object

Registers a function to run when an action occurs on the list. Returns the list object.

add_item (string text) ⇒ object

Adds an item to the list. Triggers the add_item action. Returns the list object.

remove_item (number index) ⇒ object

Removes the item at the given index if it exists. Returns the list object.

clear () ⇒ object

Clears all list items. Returns the list object.

get_selected_index () ⇒ string

Returns the selected index as a string. If nothing is selected, returns -1.

get_selected_item () ⇒ string

Returns the selected item text, or an empty string if nothing is selected.

ZPETurtle

A simple turtle graphics object which draws lines onto the frame. The turtle has a position, a direction (angle), and a pen state (up/down). When the pen is down, moving draws a line.

center () ⇒ object

Moves the turtle to the centre of the drawing area without drawing a line. Returns the turtle object.

Note: In the current implementation, this method’s internal name is accidentally set to move, but the exposed native method name is center.

move (number distance) ⇒ object

Moves the turtle forward by distance pixels in the current direction. If the pen is down, a line is drawn from the old position to the new position. Returns the turtle object.

turn (number angle) ⇒ object

Turns the turtle by the given angle in degrees (positive values rotate clockwise). Returns the turtle object.

pen_up () ⇒ object

Lifts the pen so that future movement does not draw. Returns the turtle object.

pen_down () ⇒ object

Lowers the pen so that future movement draws lines. Returns the turtle object.

clear () ⇒ object

Clears the drawing area. Returns the turtle object.

All UI elements (such as ZPEContainer, ZPEButton, and ZPEList) extend the base UI item type. This means they all share the following common methods for managing IDs and removing components from the UI.

UI Item base methods

set_id (string id) ⇒ object

Sets the element ID used to store and retrieve the item inside the frame. Returns the UI item object.

get_id () ⇒ string

Returns the current element ID as a string.

destroy () ⇒ object

Removes the UI component from its parent container and refreshes the UI. Returns the UI item object.