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

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

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) 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_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

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

gui_add_console_tab(id_or_obj, console, tab_name, 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_remove_console_tab(id_or_obj, console, tab_name)

removes 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

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