GUI

Displaying a gui

The gui module

This module exposes the gui function

The gui function is used to present the queued gui layout.

gui() returns Promise and therefore an await should be used to allow the gui to run.

MAST

gui_text("Hello, World")
await gui()

Example

To insert a blank part of the layout just call gui_blank::

gui_blank()

Proving a count will allow inserting multiple blanks::

gui_blank(4)

One use of blanks it to help center an element but also adding space::

gui_blank()
gui_icon(...)
gui_blank()

gui(buttons=None, timeout=None)

present the gui that has been queued up

Parameters:

Name	Type	Description	Default
buttons	dict	description. Defaults to None.	None
timeout	promise	A promise that ends the gui. Typically a timeout. Defaults to None.	None

Returns:

Name	Type	Description
Promise		The promise for the gui, promise is done when a button is selected

gui_properties_change(var, label)

create an on change on the client GUI for a property

Parameters:

Name	Type	Description	Default
var	str	The variable to watch	required
label	str or label	The label to run	required

Layout related

This module exposes the gui_blank function

The gui_blank function is used to insert a black space in a layout. Blanks are useful to add space.

Example

To insert a blank part of the layout just call gui_blank::

gui_blank()

Proving a count will allow inserting multiple blanks::

gui_blank(4)

One use of blanks it to help center an element but also adding space::

gui_blank()
gui_icon(...)
gui_blank()

gui_blank(count=1, style=None)

adds an empty column to the current gui ow

Parameters:

Name	Type	Description	Default
style	_type_	Style. Defaults to None.	None

Returns:

Type	Description
	layout object: The Layout object created

gui_hole(count=1, style=None)

adds an empty column that is used by the next item

Parameters:

Name	Type	Description	Default
count	int	The number of columns to use	1
style	_type_	Style. Defaults to None.	None

Returns:

Type	Description
	layout object: The Layout object created

gui_row(style=None)

queue a gui row

Parameters:

Name	Type	Description	Default
style	str	Style. Defaults to None.	None

Returns:

Type	Description
	layout object: The Layout object created

PageSubSection

is_message_for(event)

Used by MessageTrigger i.e. gui_message to know if message is for this object

Parameters:

Name	Type	Description	Default
event	EVENT	the engine event	required

Returns:

Name	Type	Description
bool		if the gui_message MessageTrigger should be True

gui_region(style=None)

Create a new gui section that uses the area specified in the style

Parameters:

Name	Type	Description	Default
style	style	Style. Defaults to None.	None

Returns:

Type	Description
	layout object: The Layout object created

gui_section(style=None)

Create a new gui section that uses the area specified in the style

Parameters:

Name	Type	Description	Default
style	style	Style. Defaults to None.	None

Returns:

Type	Description
	layout object: The Layout object created

gui_sub_section(style=None)

Create a new gui section that uses the area specified in the style

Parameters:

Name	Type	Description	Default
style	style	Style. Defaults to None.	None

Returns:

Type	Description
	layout object: The Layout object created

Responding to gui interactions

gui_message(layout_item, label=None)

Trigger to watch when the specified layout element has a message

Parameters:

Name	Type	Description	Default
layout_item	layout object	The object to watch	required

Returns:

Name	Type	Description
trigger		A trigger watches something and runs something when the trigger is reached

gui_message_callback(layout_item, cb)

Trigger to watch when the specified layout element has a message

Parameters:

Name	Type	Description	Default
layout_item	layout object	The object to watch	required

Returns:

Name	Type	Description
trigger		A trigger watches something and runs something when the trigger is reached

Gui control formatting

GUI Controls

gui_button(props, style=None, data=None, on_press=None, is_sub_task=False)

Add a gui button

Parameters:

Name	Type	Description	Default
props	str	Properties. Usually just the text on the button	required
style	str	Style. Defaults to None. End each style with a semicolon, e.g. color:red;	None
data	object	The data to pass to the button's label	None
on_press	(label, callable, Promise)	Handle a button press, label is jumped to, callable is called, Promise has results set	None
is_sub_task	bool	Set to True if the button is only responding to the button. Use False only if the whole gui will be changed via await gui(). Default is False for backwards-compatibility.	False

Valid Styles

area: Format as top, left, bottom, right. Just numbers indicates percentage of the section or page to cover. Can also use px (pixels) or em (1em = height of text font). Can combine different units, e.g. 5+5px, 3em, 100-10em, 50px; is a valid area. color: The color of the text background-color: The background color of the button padding: A gap inside the element (makes the button smaller, but the background still is there.) margin: The gap outside the element (makes the button smaller). col-width: The width of the button justify: Where the text is placed inside the button. left, center, or right font: The font to use. Overrides the font in prefernces.json

Returns:

Type	Description
	layout object: The Layout object created

gui_checkbox(msg, style=None, var=None, data=None)

Draw a checkbox

Parameters:

Name	Type	Description	Default
props	str		required
style	style	Style. Defaults to None.	None
var	str	Variable name to set the value to. Defaults to None.	None
data	object	data to pass the handler. Defaults to None.	None

Returns:

Type	Description
	layout object: The Layout object created

gui_cinematic_auto(client_id)

Will automatically track the consoles assigned ship

??? Note: The tracked ship needs to have excitement values player ships automatically have that set

Parameters:

Name	Type	Description	Default
client_id	id	the console's client ID	required

gui_content(content, style=None, var=None)

Place a python code widget e.g. list box using the layout system

Parameters:

Name	Type	Description	Default
content	widget	A gui widget code in python	required
style	str	Style. Defaults to None.	None
var	str	The variable to set the widget's value to. Defaults to None.	None

Returns:

Type	Description
	layout object: The layout object

gui_drop_down(props, style=None, var=None, data=None)

Draw a gui drop down list

Parameters:

Name	Type	Description	Default
props	str		required
style	style	Style. Defaults to None.	None
var	str	Variable name to set the selection to. Defaults to None.	None
data	object	data to pass the handler. Defaults to None.	None

Returns:

Type	Description
	layout object: The Layout object created

gui_face(face, style=None)

queue a gui face element

Parameters:

Name	Type	Description	Default
face	str	description	required
style	str	Style. Defaults to None.	None

Returns:

Type	Description
	layout object: The Layout object created

gui_icon(props, style=None)

queue a gui icon element

Parameters:

Name	Type	Description	Default
props	str	description	required
style	str	Style. Defaults to None.	None

Returns:

Type	Description
	layout object: The Layout object created

gui_icon_button(props, style=None)

queue a gui icon element

Parameters:

Name	Type	Description	Default
props	str	description	required
style	str	Style. Defaults to None.	None

Returns:

Type	Description
	layout object: The Layout object created

gui_input(props, style=None, var=None, data=None)

Draw a text type in

Parameters:

Name	Type	Description	Default
props	str	hi, low etc.	required
style	style	Style. Defaults to None.	None
var	str	Variable name to set the selection to. Defaults to None.	None
data	object	data to pass the handler. Defaults to None.	None

Returns:

Type	Description
	layout object: The Layout object created

gui_image(props, style=None, fit=0)

queue a gui image element that draw based on the fit argument. Default is stretch

Parameters:

Name	Type	Description	Default
props	str	description	required
style	str	Style. Defaults to None.	None
fit	int	The type of fill,	0

Returns:

Type	Description
	layout object: The Layout object created

gui_image_absolute(props, style=None)

queue a gui image element that draw the absolute pixels dimensions

Parameters:

Name	Type	Description	Default
props	str	description	required
style	str	Style. Defaults to None.	None

Returns:

Type	Description
	layout object: The Layout object created

gui_image_add_atlas(key, image, left=None, top=None, right=None, bottom=None)

The image atlas allows a key name to be used to assign to a set of image properties. This key can be used instead of image properties in any command that expect image properties.

The image file passed will be used to search for the file. It will first check the mission directory followed by data/graphics folder. In the future this could be modified to account for mods, e.g. a common media folders. The image atlas takes care of supplying the correct path for the engine to use.

By specifying the rect (left,top, right, bottom) the image key can reference a part of an image.

Add a key to reference a full image

MAST / python

gui_image_add_atlas("test", "media/LegendaryMissions/operator")

Add a key to reference a full image

MAST / python

gui_image_add_atlas("test2", "media/LegendaryMissions/operator", 645,570, 950,820)

Once the atlas is added the key can be used anywhere images can be used.

MAST / python

gui_image("test")

MAST / python

# Text area also use the image atlas for images
gui_text_area("![](image://test2?scale=0.5&fill=center)")

Parameters:

Name	Type	Description	Default
key	str	the key to define in the image atlas	required
image	str	The file of the image. This can also be a image property string do not include the extension. Only PNG files are valid.	required
left	float	The pixel location of the left. Defaults to None.	None
top	float	The pixel location of the top. Defaults to None.	None
right	float	The pixel location of the right. Defaults to None.	None
bottom	float	The pixel location of the bottom. Defaults to None.	None

Returns:

Name	Type	Description
ImageStales		The image Atlas object. This is a low level object typically used by the system

gui_image_keep_aspect_ratio(props, style=None)

queue a gui image element that draw keeping the same aspect ratio, left top justified

Parameters:

Name	Type	Description	Default
props	str	description	required
style	str	Style. Defaults to None.	None

Returns:

Type	Description
	layout object: The Layout object created

gui_image_keep_aspect_ratio_center(props, style=None)

queue a gui image element that keeps the aspect ratio and centers when there is extra

Parameters:

Name	Type	Description	Default
props	str	description	required
style	str	Style. Defaults to None.	None

Returns:

Type	Description
	layout object: The Layout object created

gui_image_stretch(props, style=None)

queue a gui image element that stretches to fit

Parameters:

Name	Type	Description	Default
props	str	description	required
style	str	Style. Defaults to None.	None

Returns:

Type	Description
	layout object: The Layout object created

gui_radio(msg, style=None, var=None, data=None, vertical=False)

Draw a radio button list

Parameters:

Name	Type	Description	Default
props	str	List of buttons to use	required
style	style	Style. Defaults to None.	None
var	str	Variable name to set the selection to. Defaults to None.	None
data	object	data to pass the handler. Defaults to None.	None
vertical	bool	Layout vertical if True, default False means horizontal	False

Returns:

Type	Description
	layout object: The Layout object created

gui_vradio(msg, style=None, var=None, data=None)

Draw a vertical radio button list

Parameters:

Name	Type	Description	Default
props	str	List of buttons to use	required
style	style	Style. Defaults to None.	None
var	str	Variable name to set the selection to. Defaults to None.	None
data	object	data to pass the handler. Defaults to None.	None

Returns:

Type	Description
	layout object: The Layout object created

gui_ship(props, style=None)

renders a 3d image of the ship

Parameters:

Name	Type	Description	Default
props	str	The ship key	required
style	str	Style. Defaults to None.	None

Returns:

Type	Description
	layout object: The Layout object created

gui_int_slider(msg, style=None, var=None, data=None)

Draw an integer slider control

Parameters:

Name	Type	Description	Default
props	str	hi, low etc.	required
style	style	Style. Defaults to None.	None
var	str	Variable name to set the selection to. Defaults to None.	None
data	object	data to pass the handler. Defaults to None.	None

Returns:

Type	Description
	layout object: The Layout object created

gui_slider(msg, style=None, var=None, data=None, is_int=False)

Draw a slider control

Parameters:

Name	Type	Description	Default
props	str	hi, low etc.	required
style	style	Style. Defaults to None.	None
var	str	Variable name to set the selection to. Defaults to None.	None
data	object	data to pass the handler. Defaults to None.	None
is_int	bool	Use only integers values	False

Returns:

Type	Description
	layout object: The Layout object created

gui_text(props, style=None)

Add a gui text object

valid properties text color font

props (str): property string style (style, optional): The style

gui_text_area(props, style=None)

Add a gui text object

valid properties text color font

props (str): property string style (style, optional): The style

List boxes

gui_list_box(items, style, item_template=None, title_template=None, section_style=None, title_section_style=None, select=False, multi=False, carousel=False, collapsible=False, read_only=False)

Build a LayoutListBox gui element

Parameters:

Name	Type	Description	Default
items		A list of the items that should be included	required
style	str	Custom style attributes	required
item_template	list(str | LayoutListBoxHeader)	A list of strings, or, if a header is desired, then that item should be a LayoutListBoxHeader object	None
title_template	str | callable	if a callable, will call the function to build the title. If a string, then title_template will be used as the title of the listbox	None
section_style	str	Style attributes for each section	None
title_section_style	str	Style attributes for the title	None
select	boolean	If true, item(s) within the listbox can be selected.	False
multi	boolean	If true, multiple items can be selected. Ignored if select is None	False
carousel	boolean	If true, will use the carousel styling, e.g. the ship type selection menu	False
collapsible	boolean	If true, clicking on a header will collapse everything until the next header	False
read_only	boolean	Can the items be modified	False

Returns: The LayoutListBox layout object

gui_list_box_header(label, collapse=False, indent=0, selectable=False, data=None)

Created a gui_list_box_header element

Parameters:

Name	Type	Description	Default
label	str	The label text	required
collapse	bool	Default the collapsed state. Defaults to False.	False
indent	int	The indention level e.g. for a tree like structure	0
selectable	bool	If the header is also selectable	False
collapse_pixel_size	int	The size in pixels for the hit area (only used if selectable)	required
select_first	bool	If the select area is before the collapse click area (only used if selectable)	required
data	any	Optional additional data	None

Returns:

Name	Type	Description
LayoutListBoxHeader		description

gui_list_box_is_header(item)

Created a gui_list_box_header element

Parameters:

Name	Type	Description	Default
label	str	The label text	required
collapse	bool	Default the collapsed state. Defaults to False.	required

Returns:

Name	Type	Description
_type_		description

gui_listbox_items_convert_headers(items)

Converts a list of strings into a list of objects that allow a listbox to collapse if a header is clicked To make a header, prefix the name with >>. Example usage:

item = [">>Header","Item1","Item2",">>Another Header","Another Item 1","Another Item 2"]
ret = gm_convert_listbox_items(item)
gui_list_box(items=ret, style="", select=True, collapsible=True)

Args: items (list(str)): A list of strings Returns: (list(str|LayoutListBoxHeader)): A list of LayoutListBoxHeader (for the headers) and strings (for the items)

Cosmos consoles

gui_activate_console(console)

set the console name for the client

Parameters:

Name	Type	Description	Default
console	str	The console name	required

gui_console(console, is_jump=False)

Activates a console using the default set of widgets

Parameters:

Name	Type	Description	Default
console	str	The console name	required

gui_console_clients(path, for_ships=None)

gets a set of IDs for matching consoles

Parameters:

Name	Type	Description	Default
console	str	The console name	required

Console tabs:

The console tab system allows for creating a page tabbing system that allows the user to switch between pages quickly.

Tabs are defined with a //gui/tab label. This label defines what happens when that tab is press.

Example:

# Allow the debug tab to be shown
# at the top level
gui_tab_add_top("debug")

//gui/tab/debug
    jump show_debug_page

//gui/tab/brain
    jump show_brain_page

=== show_debug_page
    # Set the return page
    gui_tab_back(CONSOLE_SELECT)
    # Add the brain as a tab of the debug page
    gui_tab_enable("brain")
    # Set the back button to the last selected standard console
    # Rest of code to show page

=== show_brain_page
    # Set the back button to the last selected standard console
    gui_tab_back("debug")
    # Rest of code to show page

gui_tab_activate(tab_name)

Sets the back tab (left most) tab for the console tabs. This is general called automatically by //gui/tab and //console labels

Parameters:

Name	Type	Description	Default
tab_name	str	The path of a //gui/tab	required

gui_tab_add_top(tab_name)

Specify a tab by default to shown when the page is shown for standard consoles.

Parameters:

Name	Type	Description	Default
tab_name	str	A comma separated list of paths of a //gui//tab e.g. helm,weapons	required

gui_tab_back(tab_name)

Sets the back tab (left most) tab for the console tabs. The back tag is set by //gui/tab and //console labels This allows overriding

Parameters:

Name	Type	Description	Default
tab_name	str	The path of a //gui/tab	required

gui_tab_clear_top()

Specify a tab by default to shown when the page is shown for standard consoles.

Parameters:

Name	Type	Description	Default
tab_name	str	A comma separated list of paths of a //gui//tab e.g. helm,weapons	required

gui_tab_enable(tab_name)

Enable a tab on the console tabs

Parameters:

Name	Type	Description	Default
tab_name	str	A comma separated list of paths of a //gui//tab e.g. helm,weapons	required

gui_tab_get_active()

returns the active tab

Parameters:

Name	Type	Description	Default
tab_name	str	The path of a //gui/tab	required

gui_tab_is_top(tab_name)

Specify a tab by default to shown when the page is shown for standard consoles.

Parameters:

Name	Type	Description	Default
tab_name	str	A comma separated list of paths of a //gui//tab e.g. helm,weapons	required

gui_tab_remove_top(tab_name)

Specify a tab by default to shown when the page is shown for standard consoles.

Parameters:

Name	Type	Description	Default
tab_name	str	A comma separated list of paths of a //gui//tab e.g. helm,weapons	required

gui_add_console_type(path, display_name, description, label)

adds a tab definition

Parameters:

Name	Type	Description	Default
id_or_obj	agent	agent id or object	required
console	str	Console name	required
tab_name	str	Tab name	required
label	label	Label to run when tab selected	required

gui_get_console_type(key)

Get the list of consoles defined by @console decorator labels

gui_get_console_type_list()

Get the list of consoles defined by @console decorator labels path is added as a value

gui_get_console_types()

Get the list of consoles defined by @console decorator labels

gui_remove_console_type(path, display_name, label)

adds a tab definition

Parameters:

Name	Type	Description	Default
path	str	Console path	required
display_name	str	Display name	required
label	label	Label to run when tab selected	required

gui_layout_widget(widget)

Places a specific console widget in the a layout section. Placing it at a specific location

Parameters:

Name	Type	Description	Default
widget	str	The gui widget	required

Returns:

Type	Description
	layout element: The layout element

gui_update_widget_list(add_widgets=None, remove_widgets=None)

Set the engine widget list. i.e. controls engine controls

Parameters:

Name	Type	Description	Default
console	str	The console type name	required
widgets	str	The list of widgets	required

gui_update_widgets(add_widgets, remove_widgets)

Set the engine widget list. i.e. controls engine controls

Parameters:

Name	Type	Description	Default
console	str	The console type name	required
widgets	str	The list of widgets	required

gui_widget_list(console, widgets)

Set the engine widget list. i.e. controls engine controls

Parameters:

Name	Type	Description	Default
console	str	The console type name	required
widgets	str	The list of widgets	required

gui_widget_list_clear()

clear the widet list on the client

Update and refreshing the GUI

gui_hide(layout_item)

If the item is visible it will make it hidden

Note

For sections it will recalculate the layout. For individual item or row, it will hide, but not layout. so you may also need to pair this with a gui_represent of a section

Parameters:

Name	Type	Description	Default
layout_item	layout_item		required

gui_rebuild(region)

prepares a section/region to be build a new layout

Parameters:

Name	Type	Description	Default
region	layout_item	a layout/Layout item	required

Returns:

Type	Description
	layout object: The Layout object created

gui_refresh(label)

refresh any gui running the specified label

Parameters:

Name	Type	Description	Default
label	label	A mast label	required

gui_represent(layout_item)

redraw an item

Note

For sections it will recalculate the layout and redraw all items

Parameters:

Name	Type	Description	Default
layout_item	layout_item		required

gui_show(layout_item)

gui show. If the item is hidden it will make it visible again

Note

For sections it will recalculate the layout. For individual item or row, it will hide, but not layout. so you may also need to pair this with a gui_represent of a section

Parameters:

Name	Type	Description	Default
layout_item	layout_item		required

gui_update(tag, props, shared=False, test=None)

Update the properties of a current gui element

Parameters:

Name	Type	Description	Default
tag	str		required
props	str	The new properties to use	required
shared	bool	Update all gui screen if true. Defaults to False.	False
test	dict	Check the variable (key) update if any value is different than the test. Defaults to None.	None

gui_history_back()

Jump back in history

gui_history_clear()

Clears the history for the given page

gui_history_forward()

Jump forward in history

gui_history_jump(to_label, back_name=None, back_label=None, back_data=None)

Jump to a new gui label, but remember how to return to the current state

Parameters:

Name	Type	Description	Default
to_label	label	Where to jump to	required
back_name	str	A name to use if displayed	None
back_label	label	The label to return to defaults to the label active when called	None
back_data	dict	A set of value to set when returning back	None

??? Note: If there is forward history it will be cleared

Returns:

Name	Type	Description
results	PollResults	PollResults of the jump

gui_history_store(back_text, back_label=None)

store the current

Parameters:

Name	Type	Description	Default
label	label	A mast label	required

gui_reroute_clients(label, data=None, exclude=None)

reroute client guis to run the specified label

Parameters:

Name	Type	Description	Default
label	label	Label to jump to	required
exclude	set	set client_id values to exclude. Defaults to None.	None

gui_reroute_server(label, data=None)

reroute server gui to run the specified label

Parameters:

Name	Type	Description	Default
label	label	Label to jump to	required

Windows clipboard

Interacting with client side data