Functions
GUIModule scrError	GetMsg ()
	Get a human-readable description for a screen API error code.
GUIModule scrError	GetMsgCount ()
	Get the total number of recognized screen API error codes.
GUIModule	api_e (meta, api_func,...)
	Call a screen API function with error handling and optional error code suppression.
	returns (excluding the error code)
	Call a screen API function without metadata, forwarding all arguments.
GUIModule	api (...)
	Call a screen API function without metadata, forwarding all arguments.
GUIModule	RunHooks (hook_name,...)
	Execute hook functions registered across user and machine screen modules.
GUIModule	GetInstanceCount ()
	Get the number of active Mach4 instances.
GUIModule	IsScreenLoaded ()
	Check whether the MachGUI screen has finished loading.
GUIModule	GetCleanedLabel (object_name)
	Get the cleaned label text of a screen control, with newlines replaced by spaces.
GUIModule	ConvertToLegalVariableName (name)
	Convert an arbitrary string to a legal Lua variable name.
GUIModule	GetObjectNameCore (object_name)
	Extract the base name of a screen control by removing any trailing index suffix.
GUIModule	GetObjectPasswordLevelAsValue (object_name)
	Get the password protection level of a screen object as a numeric value.
GUIModule	GetObjectPasswordLevel (object_name)
	Get the password protection level string for a screen object.
GUIModule	SetObjectPasswordLevel (object_name, level)
	Set the password protection level for a screen object.
SpecificScreenModule	SwitchSpecialMode (curr_mode, prev_mode,...)
SpecificScreenModule	SwitchSpecialMode (curr_mode, prev_mode, ctrl_name,...)
GUIModule	ScreenToggleButtonCall (handler, ctrl_name, event_source,...)
SpecificScreenModule	HandleActionButton1 (direction, amount,...)
SpecificScreenModule	HandleActionButton1 (direction, amount, ctrl_name,...)
GUIModule	ScreenButtonCall (handler, ctrl_name, event_source, ctrl_type,...)
ThisScreenModule	ModifyAxisDROPosition_Screen (dro_new_value, AxisID,...)
GUIModule	ScreenDROModify (handler, new_value, ctrl_name, event_source,...)
GUIModule	MachButtonCall (mach_func_name, control_name, event_source, ctrl_type,...)
GUIModule	ScreenTabEnter (...)
	Handle the enter event for a notebook tab, with password protection support.
GUIModule	ScreenTabExit (...)
	Handle the exit event for a notebook tab.
GUIModule	ScreenPageChanging (...)
	Notify the screen module that a notebook page is about to change.
GUIModule	ScreenPageChanged (...)
	Notify the screen module that a notebook page change has completed.
GUIModule	IsObject (name)
	Determine whether a screen control name refers to a base or indexed control.
GUIModule	DoesHaveProperty (name, datatype)
	Check whether a screen control has a specified property.
GUIModule	SetHidden (name, dummy_unused, make_hidden)
	Set the hidden state of a screen control using a position-based workaround.
GUIModule	GetHidden (name, dummy_unused)
	Get the hidden state of a screen control.
GUIModule	ShowGroupInnards (group_name, show)
	Show or hide all child controls within a group screen object.
GUIModule	FormatDRO (name, enabled)
	Set the visual format of a DRO control to indicate enabled or read-only state.
GUIModule	orig_SetObject (name, datatype, val, force)
	Set a property value on a screen control and all its indexed variants (original implementation).
GUIModule	ObjectCacheClear ()
	Clear the object property cache.
GUIModule ObjectCache	FindObjects ()
	Find and cache all screen controls matching a given base name.
GUIModule	SetObject (name, property, val, force)
	Intelligently set a property value on a screen control and all its indexed variants.
GUIModule	GetObject (name, datatype)
	Get a property value from a named screen control.
GUIModule	GetDropDownSelectedIndex (name)
	Get the currently selected index and value of a drop-down screen control.
GUIModule	SetDropDownSelectedIndex (name, idx)
	Set the selected item of a drop-down control by zero-based index.
GUIModule	GetMMToggleButtonWidthPixel (name)
	Determine the standard pixel-width bucket for an MM toggle button.
GUIModule	SetMMToggleButton (name, value)
	Set the visual state of an MM toggle button by updating its image property.
GUIModule	GetMMToggleButton (name)
	Get the current toggle state of an MM toggle button by reading its image property.
GUIModule	SetAxisObject (name, datatype, val, axis)
	Set a property of axis-associated screen controls, respecting axis enabled state.
GUIModule	SetLED (name, val)
	Set the value of an LED screen control.
GUIModule	GetLED (name)
	Get the current value of an LED screen control.
GUIModule	SetLabelLED (name, color, val)
	Set the background color of a label or button control to indicate an LED state.
GUIModule	SetButtonLED (name, val, color)
	Set the LED state of a button control using color and value.
GUIModule	SetDRO (name, val)
	Set the value of a DRO screen control.
GUIModule	GetDRO (name)
	Get the current numeric value of a DRO screen control.
GUIModule	StartScrollDRO (name, val, minimum, maximum)
	Activate the scroll DRO mechanism.
GUIModule	StartScrollDRO ()
	Activate the scroll DRO mechanism.
GUIModule	StopScrollDRO (name)
	Deactivate the scroll DRO mechanism.
GUIModule	StopScrollDRO ()
	Deactivate the scroll DRO mechanism.
GUIModule	UpdateScrollDRO ()
	Update the scroll DRO state machine, advancing or resetting the scrolling DRO value.
GUIModule	PlusMinusDRO (name, val, startscrolling, minimum, maximum)
	Increment or decrement a DRO value by a specified amount, with optional scroll activation.
GUIModule	DoFunctionName (Name)
	Execute a named Mach screen function on the current instance.
GUIModule	DoFunctionNameInst (inst, Name)
	Execute a named Mach screen function on a specific instance.
GUIModule	DoFunctionCode (NumberCode)
	Execute a Mach screen function by its numeric function code.
GUIModule ScreenObject	Associate (btn_name)
	Create a new ScreenObject instance associated with a screen control.
GUIModule ScreenObject	UpdatePosition ()
	Read and cache the current position and size of this screen object from the screen.
GUIModule ScreenObject	UpdateState ()
	Update this object's internal state based on detectable conditions.
GUIModule ScreenObject	GetState ()
	Get the internal active state of this screen object.
GUIModule ScreenObject	SetState ()
	Set the internal active state of this screen object.
GUIModule ScreenObject	UpdateScreen ()
	Apply this ScreenObject's position and visibility to the live screen.
GUIModule AxisButton	Associate (btn_name, axis_id)
	Create a new AxisButton associated with a screen button and an axis.
GUIModule StackableCollection	new (constraints,...)
	Create a new StackableCollection from layout constraints and an ordered list of ScreenObjects.
GUIModule StackableCollection	Log (...)
	Log a formatted message for this StackableCollection if debugging is enabled.
GUIModule StackableCollection	FitsHereP ()
	Check whether a screen object fits at the current stacking position.
GUIModule StackableCollection	NextPosition ()
	Advance the current stacking position to the next location where an object can be placed.
GUIModule StackableCollection	Stack ()
	Reposition all items in the collection, hiding inactive or non-fitting objects.
GUIModule	AncestorPath (obj_name)
	Build a slash-separated ancestor path string for a screen object.
GUIModule LayoutObjects	new (grid_objects)
	Create a new LayoutObjects instance from a grid configuration table.
GUIModule LayoutObjects	AddToRow (row_id)
	Add a screen control to a specific row in the layout.
GUIModule LayoutObjects	Layout ()
	Arrange all rows of screen objects into a column-based grid layout.
GUIModule LayoutObjects	Hidden (value)
	Set the hidden state of a named row in the layout.
GUIModule LayoutObjects	HideRow ()
	Mark a row in the layout as hidden.
GUIModule LayoutObjects	ShowRow ()
	Mark a row in the layout as visible.
	filter_fn (...)
	Default filter function that accepts all screen objects.
GUIModule	WalkScreenObjectsDFS (obj_name, parent_first, filter_fn)
	Create a coroutine-based iterator for depth-first traversal of screen objects.
GUIModule	GetListOfChildren (Parent, AllowedTypes, NotAllowedTypes, NotAllowedNames)
	Get a flat list of screen controls under a given parent, with optional type filtering.
	MatchInTable (value, options)
	Check whether a value exists in a table of options.
GUIModule	BuildScreenTable (parent)
	Recursively build a table representing the screen object hierarchy.
GUIModule	GetWholeScreenTable ()
	Get the full screen object hierarchy table, building it if necessary.
GUIModule	TranslateObject (obj)
	Translate the label of a single screen object using the wxWidgets translation system.
GUIModule	TranslateGroup (obj)
	Translate all label text in a group and its eligible children.
GUIModule Notebooks	Get ()
	Retrieve a notebook object by name from the Notebooks collection.
GUIModule Notebook	new ()
	Create a new Notebook object and build its tab mapping.
GUIModule Notebook	GetCurrentTab ()
	Get the currently active tab of this notebook.
GUIModule Notebook	IsOnCurrentPage ()
	Determine whether this notebook is on the currently visible screen page.
GUIModule Notebook	GetTabInfoFromLabel ()
	Get notebook tab information by searching for a matching label.
GUIModule Notebooks	BuildMapping ()
	Build the index-to-name mapping for all notebooks in the screen.
GUIModule	StartScreenLoadedCheck ()
	Start the timer that polls for screen load completion.
GUIModule	GetMachStateEnabledControls ()
	Get a cached list of screen controls that have Mach-state-dependent enabled properties.
GUIModule	GetAllControls ()
	Get a cached list of all screen controls.
GUIModule	RefreshStateEnabledControls ()
	Refresh all screen controls that have Mach-state-dependent enabled states.
GUIModule	RefreshControl (obj_name)
	Force a single screen control to redraw by toggling its Enabled state.
GUIModule	RefreshAllControls (ctrl_type)
	Refresh all screen controls, optionally filtered by control type.

Function Documentation

◆ AddToRow()

GUIModule LayoutObjects AddToRow ( row_id )

Add a screen control to a specific row in the layout.

Adds the given object name to the ordered list of objects for the specified row_id in the ObjectsInRows table. If ObjectsInRows does not yet exist it is initialized. If the specified row does not yet exist, it is created with Hidden set to false. Multiple calls with the same row_id append objects to that row in order.

Parameters

obj_name	(string) The screen control name to add to the row
row_id	(number) The row index to add the object to

Note: Documentation generated by AI on 2026-03-03

◆ AncestorPath()

GUIModule AncestorPath ( obj_name )

Build a slash-separated ancestor path string for a screen object.

Recursively walks up the screen object hierarchy using scr.GetCtrlParent() to construct a path string from the root down to the specified object. Useful for identifying objects in error messages when the screen editor path is needed. Returns an empty string if obj_name is nil. Returns an error-prefixed string if the screen API returns an error. The base case is when an object is its own parent (root).

Parameters

obj_name (string|nil) The screen control name to build the path for

Returns: (string) Slash-separated ancestor path (e.g., "Main/Group1/MyButton"), or empty string if nil

Note: Documentation generated by AI on 2026-03-03

◆ api()

GUIModule api ( ... )

Call a screen API function without metadata, forwarding all arguments.

Convenience wrapper around GUIModule.api_e() that passes nil as the metadata argument. Use this when no error codes need to be ignored or suppressed.

Parameters

...	(any) The screen API function name followed by its arguments, forwarded directly to GUIModule.api_e()

Returns: (any) Whatever values the underlying screen API function returns (excluding the error code)

See also: GUIModule.api_e() for the full implementation with metadata support

Note: Documentation generated by AI on 2026-03-03

◆ api_e()

GUIModule api_e	(	meta	,
		api_func	,
			... )

Call a screen API function with error handling and optional error code suppression.

Looks up the named function in the scr API table and invokes it via w.pcall() with the provided arguments. Raises a Lua error via WrapperModule.Error() if the function name is not found or if Lua itself raises an error during the call. Checks the last return value for a Mach screen error code (scr.SERROR_NOERROR); if an error is returned and is not in the meta.Ignore list, raises a Lua error with a descriptive message. On success, strips w.pcall()'s status flag and the trailing error code from the return values and returns only the meaningful results.

Parameters

meta	(table\|nil) Behavioral metadata table. Supports key 'Ignore' (array of scr error codes to suppress)
api_func	(string) The name of the screen API function to call (looked up in the scr table)
...	(any) Arguments to pass to the screen API function

Returns: (any) The return values from the screen API function, excluding the trailing error code

-- Call with no return value
h.api_e(nil, "SetProperty", obj_name, "Left", "300")
 
-- Call with a single return value
local left = tonumber(h.api_e(nil, "GetProperty", obj_name, "Left"))
 
-- Ignore a specific error code
h.api_e({Ignore = {scr.SERROR_PROPERTY_NOT_FOUND}}, "SetProperty", obj_name, "CoolBorderColor", "(53,53,53,128)")

Warning: Raises a Lua error via WrapperModule.Error() if the API function is not found, if Lua raises an error, or if an unignored screen error code is returned

See also: GUIModule.api() for a simpler wrapper without metadata

Note: Documentation generated by AI on 2026-03-03

◆ Associate() [1/2]

GUIModule ScreenObject Associate ( btn_name )

Create a new ScreenObject instance associated with a screen control.

Constructs a new ScreenObject by setting its metatable, storing the control name, and reading the current position from the screen via UpdatePosition(). Also calls UpdateState() to initialize the active state. Raises a Lua error if the control cannot be found in the screen. The IsDebugging flag is initialized from w.IsDebugging().

Parameters

btn_name (string) The screen control name (or base name) to associate with this object

Returns: (table) A new ScreenObject instance with position and state initialized

Warning: Raises a Lua error via w.Error() if the screen control cannot be found

See also: GUIModule.ScreenObject:UpdatePosition() for initial position loading; GUIModule.ScreenObject:UpdateState() for initial state detection

Note: Documentation generated by AI on 2026-03-03

◆ Associate() [2/2]

GUIModule AxisButton Associate	(	btn_name	,
		axis_id	)

Create a new AxisButton associated with a screen button and an axis.

Creates a new AxisButton instance by calling GUIModule.ScreenObject.Associate() for the given button name and then applying the AxisButton metatable. Sets the internal type label to 'AxisBtn' and stores the axis_id. Calls UpdateState() to initialize the active state based on whether the associated axis is currently enabled.

Parameters

btn_name	(string) The screen control name of the button to associate
axis_id	(number) The axis index to bind to this button (mc.X_AXIS, mc.Y_AXIS, etc.; use -1 for no axis)

Returns: (table) A new AxisButton instance with axis state initialized

See also: GUIModule.AxisButton:UpdateState() for axis enable/disable logic

Note: Documentation generated by AI on 2026-03-03

◆ BuildMapping()

GUIModule Notebooks BuildMapping ( )

Build the index-to-name mapping for all notebooks in the screen.

Walks the entire screen object hierarchy to find all notebook controls (scr.CTYPE_NOTEBOOK) and builds a GUIModule.Notebook object for each one. Also builds a page list (h.screen_page_list) mapping page control names to their zero-based indices. The resulting notebook objects are stored in the GUIModule.Notebooks table keyed by notebook control name. This function is called automatically when the screen finishes loading.

Note: Uses GUIModule.WalkScreenObjectsDFS() internally, which relies on coroutines

See also: GUIModule.Notebook:new() for individual notebook object construction

Note: Documentation generated by AI on 2026-03-03

◆ BuildScreenTable()

GUIModule BuildScreenTable ( parent )

Recursively build a table representing the screen object hierarchy.

Starting from the given parent control (or the screen root if nil), enumerates all child controls using scr.EnumCtrlChildren() and builds a nested table structure. Each entry contains the parent name, control name, control type, and a children sub-table. Children with their own children are recursively processed.

Parameters

parent (string|nil) The name of the parent screen control to start from. If nil, uses scr.GetScreenName()

Returns: (table|nil) Nested array of control info tables, or nil on error. Each entry has keys: 'parent' (string), 'name' (string), 'type' (number), 'children' (table); (boolean) Success flag - true if the table was built successfully; (string) Status message describing the result

Note: Documentation generated by AI on 2026-03-03

◆ ConvertToLegalVariableName()

GUIModule ConvertToLegalVariableName ( name )

Convert an arbitrary string to a legal Lua variable name.

Replaces all characters that are not alphanumeric or underscores with underscores, and prepends a leading underscore. This is used to generate meaningful but syntactically valid Lua identifiers from arbitrary screen object labels or names.

Parameters

name	(string) The string to convert into a legal Lua variable name

Returns: (string) A legal Lua variable name derived from the input string

Note: Documentation generated by AI on 2026-03-03

References name().

◆ DoesHaveProperty()

GUIModule DoesHaveProperty	(	name	,
		datatype	)

Check whether a screen control has a specified property.

Attempts to resolve the control name by checking both the exact name and the "(1)" indexed variant. Then calls scr.IsProperty() to test for the given property name. Returns true only if the screen API returns scr.SERROR_NOERROR and confirms the property exists.

Parameters

name	(string) The screen control name to check
datatype	(string) The property name to test for (e.g., "Label", "Value", "Hidden")

Returns: (boolean) True if the control has the specified property, false otherwise

Note: Documentation generated by AI on 2026-03-03

References name().

◆ DoFunctionCode()

GUIModule DoFunctionCode ( NumberCode )

Execute a Mach screen function by its numeric function code.

Calls scr.DoFunctionCodeInst() with the current Mach instance and the provided function code. If the call returns an error, reports it via w.FunctionError().

Parameters

NumberCode (string|number) The numeric function code to execute via the screen API

Note: Documentation generated by AI on 2026-03-03

◆ DoFunctionName()

GUIModule DoFunctionName ( Name )

Execute a named Mach screen function on the current instance.

Calls scr.DoFunctionNameInst() with the current Mach instance and the provided function name. If the call returns an error, reports it via w.FunctionError().

Parameters

Name	(string) The name of the screen function to execute

Note: Documentation generated by AI on 2026-03-03

◆ DoFunctionNameInst()

GUIModule DoFunctionNameInst	(	inst	,
		Name	)

Execute a named Mach screen function on a specific instance.

Calls scr.DoFunctionNameInst() with the provided instance handle and function name. If the call returns an error, reports it via w.FunctionError(). If inst is not a number, falls back to mc.mcGetInstance().

Parameters

inst	(number) The Mach4 instance handle. If not provided, uses current instance
Name	(string) The name of the screen function to execute

Note: Documentation generated by AI on 2026-03-03

◆ filter_fn()

filter_fn ( ... )

Default filter function that accepts all screen objects.

This is the default filter function assigned inside GUIModule._WalkDFS() when no filter_fn is provided by the caller. It unconditionally returns true for every control name passed to it, causing all screen objects to be included in the traversal.

Parameters

...	(any) The screen control name (and any additional arguments passed by the walker)

Returns: (boolean) Always returns true

Note: This function is created as a local closure inside GUIModule._WalkDFS() and is not directly callable from outside; Documentation generated by AI on 2026-03-03

Referenced by WalkScreenObjectsDFS().

◆ FindObjects()

GUIModule ObjectCache FindObjects ( )

Find and cache all screen controls matching a given base name.

Looks up the specified base name in the object cache. If found and non-empty, returns the cached result immediately. Otherwise, searches for all matching controls by checking the exact name (index 0) and indexed variants (name(1) through name(30)). For each found control, stores its name, control type, is_numeric flag, property cache table, lookup count, and write count. Results are stored in both self.cache (by base name) and self.direct (by exact control name) for fast lookup.

Parameters

name	(string) The base screen control name to search for

Returns: (table) Array of cache entry tables, each with fields: name (string), ctrl_type (number), is_numeric (boolean), props (table), lookup_count (number), write_count (number)

Note: Documentation generated by AI on 2026-03-03

◆ FitsHereP()

GUIModule StackableCollection FitsHereP ( )

Check whether a screen object fits at the current stacking position.

Tests whether placing scr_obj at self.current.top and self.current.left would keep the object's bottom and right edges within the configured maximum height and width limits of the container (accounting for bottom and right padding).

Parameters

scr_obj (table) A ScreenObject instance with Height and Width fields

Returns: (boolean) True if the object fits at the current position, false otherwise

See also: GUIModule.StackableCollection:NextPosition() for advancing to the next position

Note: Documentation generated by AI on 2026-03-03

◆ FormatDRO()

GUIModule FormatDRO	(	name	,
		enabled	)

Set the visual format of a DRO control to indicate enabled or read-only state.

Updates the "Editor", "Fg Color", and "Bg Color" properties of the named DRO screen control to visually distinguish between an editable and a read-only state. When enabled, sets a keypad editor with a blue-grey background. When disabled, sets read-only mode with a muted foreground and dark background.

Parameters

name	(string) The screen control name of the DRO to format
enabled	(boolean) True to format as editable (keypad, colored), false to format as read-only (grey)

Note: Documentation generated by AI on 2026-03-03

References name().

◆ Get()

GUIModule Notebooks Get ( )

Retrieve a notebook object by name from the Notebooks collection.

Looks up a previously built GUIModule.Notebook object by its control name. Raises a Lua error if the name is nil or if no notebook with that name has been mapped.

Parameters

nb_name (string) The screen control name of the notebook to retrieve

Returns: (table) The GUIModule.Notebook object associated with nb_name

Warning: Raises a Lua error via w.Error() if nb_name is nil or the notebook is not found

See also: GUIModule.Notebooks:BuildMapping() which must be called before this function

Note: Documentation generated by AI on 2026-03-03

◆ GetAllControls()

GUIModule GetAllControls ( )

Get a cached list of all screen controls.

Returns the full list of screen controls, building and caching the list on first call via GUIModule.GetListOfChildren(). Subsequent calls return the cached result without querying the screen API again.

Returns: (table) Array of control info tables, each with keys: 'Control' (string), 'Parent' (string), 'Type' (number)

Note: Documentation generated by AI on 2026-03-03

◆ GetCleanedLabel()

GUIModule GetCleanedLabel ( object_name )

Get the cleaned label text of a screen control, with newlines replaced by spaces.

Checks whether the named screen object has a "Label" property. If it does, retrieves the label text and replaces both literal "\n" escape sequences and actual newline characters with spaces. Returns an empty string if the object has no "Label" property.

Parameters

object_name (string) The screen control name to retrieve the label from

Returns: (string) The label text with newline characters replaced by spaces, or an empty string if no label exists

Note: Documentation generated by AI on 2026-03-03

◆ GetCurrentTab()

GUIModule Notebook GetCurrentTab ( )

Get the currently active tab of this notebook.

Queries the screen API for the "Current Tab" property of the notebook control and returns the corresponding tab info table. Raises an error if the property cannot be read or does not return a valid numeric index. Returns nil if the tab index is -1 (notebook not visible or no current tab).

Returns: (table|nil) Tab info table with keys: 'name' (string), 'label' (string), 'index' (number), or nil if no current tab

Warning: Raises a Lua error via w.Error() if the screen API returns nil or a non-numeric value

Note: Documentation generated by AI on 2026-03-03

◆ GetDRO()

GUIModule GetDRO ( name )

Get the current numeric value of a DRO screen control.

Retrieves the "Value" property of the named DRO control. If the base name is a valid screen control, reads it directly; otherwise reads from the "(1)" indexed variant. Returns the value converted to a number via tonumber().

Parameters

name	(string) The screen control name of the DRO to read

Returns: (number|nil) The current numeric value of the DRO, or nil if conversion fails

Note: Documentation generated by AI on 2026-03-03

References name().

◆ GetDropDownSelectedIndex()

GUIModule GetDropDownSelectedIndex ( name )

Get the currently selected index and value of a drop-down screen control.

Reads the "Strings" property of the named drop-down control, splits it by "|" to get the list of options, and compares each option against the current "Value" property. Returns the zero-based index of the matching option and its string value. Returns -1 as the index if no match is found.

Parameters

name	(string) The screen control name of the drop-down to query

Returns: (number) The zero-based index of the currently selected option, or -1 if not found; (string) The current value string of the drop-down control

See also: GUIModule.SetDropDownSelectedIndex() for setting the selected option by index

Note: Documentation generated by AI on 2026-03-03

References name().

◆ GetHidden()

GUIModule GetHidden	(	name	,
		dummy_unused	)

Get the hidden state of a screen control.

Returns the hidden state of the named screen control as "1" (hidden) or "0" (visible). For toolpath controls (scr.CTYPE_TOOLPATH), uses the standard "Hidden" property directly. For all other controls, computes the hidden state by checking if the "Left" property value is >= 10000 (the threshold used by GUIModule.SetHidden()) OR if the "Hidden" property is "1". Returns "0" if the Left value cannot be converted to a number. Reports an error via w.FunctionError() if the control type cannot be retrieved.

Parameters

name	(string) The screen control name to query
dummy_unused	(any) Unused parameter; present for API symmetry with scr.GetProperty()

Returns: (string) "1" if the control is hidden, "0" if visible; (number) The screen API return code (scr.SERROR_NOERROR on success)

See also: GUIModule.SetHidden() for the corresponding setter

Note: Documentation generated by AI on 2026-03-03

References name().

◆ GetInstanceCount()

GUIModule GetInstanceCount ( )

Get the number of active Mach4 instances.

Wraps scr.GetInstanceCount() to return the current number of running Mach4 instances available to the screen.

Returns: (number) The number of active Mach4 instances

Note: Documentation generated by AI on 2026-03-03

◆ GetLED()

GUIModule GetLED ( name )

Get the current value of an LED screen control.

Reads the "Value" property of the named LED control and returns it as a number. If the base name is a valid screen control, reads it directly; otherwise reads from the "(1)" indexed variant.

Parameters

name	(string) The screen control name of the LED to read

Returns: (number|nil) The current numeric value of the LED control, or nil if not found

Note: Documentation generated by AI on 2026-03-03

References name().

◆ GetListOfChildren()

GUIModule GetListOfChildren	(	Parent	,
		AllowedTypes	,
		NotAllowedTypes	,
		NotAllowedNames	)

Get a flat list of screen controls under a given parent, with optional type filtering.

Retrieves the full screen hierarchy table and extracts all controls under the specified parent. If parent is nil or the screen root, the entire screen is searched. Otherwise, recursively scans the hierarchy to locate the parent's subtree before filtering. Supports filtering by allowed types, excluded types, and excluded names.

Parameters

Parent	(string\|nil) The name of the parent control to search under. If nil, searches the entire screen
AllowedTypes	(table\|nil) Array of scr.CTYPE_* values to include. If nil, all types are included
NotAllowedTypes	(table\|nil) Array of scr.CTYPE_* values to exclude
NotAllowedNames	(table\|nil) Array of base control names to exclude

Returns: (table) Flat array of control info tables, each with keys: 'Control' (string), 'Parent' (string), 'Type' (number)

Note: Documentation generated by AI on 2026-03-03

◆ GetMachStateEnabledControls()

GUIModule GetMachStateEnabledControls ( )

Get a cached list of screen controls that have Mach-state-dependent enabled properties.

Walks the entire screen object tree and collects controls that have either "Enabled States" or "Enable With Machine" properties set to a non-zero value. The resulting list is cached in GUIModule._MachStateEnabledControls so that subsequent calls do not re-walk the screen tree.

Returns: (table) Array of control name strings for controls with state-dependent enabled properties

See also: GUIModule.RefreshStateEnabledControls() for usage of this list

Note: Documentation generated by AI on 2026-03-03

◆ GetMMToggleButton()

GUIModule GetMMToggleButton ( name )

Get the current toggle state of an MM toggle button by reading its image property.

Reads the "Image" property of the named toggle button and compares it against the expected "on" image filename for the button's pixel width. Returns true if the button is in the on state, false otherwise.

Parameters

name	(string) The screen control name of the MM toggle button

Returns: (boolean) True if the button is in the on state, false if in the off state

See also: GUIModule.SetMMToggleButton() for setting the toggle state; GUIModule.GetMMToggleButtonWidthPixel() for pixel width detection

Note: Documentation generated by AI on 2026-03-03

References name().

◆ GetMMToggleButtonWidthPixel()

GUIModule GetMMToggleButtonWidthPixel ( name )

Determine the standard pixel-width bucket for an MM toggle button.

Reads the "Width" property of the named button and maps it to the nearest standard image width: 65, 75, 85, or 95 pixels. This value is used to select the correct on/off image filename for the toggle button.

Parameters

name	(string) The screen control name of the MM toggle button

Returns: (number) The pixel width bucket: 65, 75, 85, or 95

See also: GUIModule.SetMMToggleButton() for usage of the returned pixel width

Note: Documentation generated by AI on 2026-03-03

References name().

◆ GetMsg()

GUIModule scrError GetMsg ( )

Get a human-readable description for a screen API error code.

Looks up the provided error code in the GUIModule.scrError.ErrorCodes table. If the code is not recognized, returns a string indicating the unrecognized code. Otherwise, returns a formatted string combining the description, the symbolic name, and the numeric code.

Parameters

errorcode (number) The screen API error code to look up

Returns: (string) A formatted error message string, or an "Unrecognized" notice if the code is unknown

Note: Documentation generated by AI on 2026-03-03

◆ GetMsgCount()

GUIModule scrError GetMsgCount ( )

Get the total number of recognized screen API error codes.

Counts the entries in the GUIModule.scrError.ErrorCodes table using GUIModule.GetTableCount() and returns the result.

Returns: (number) The count of recognized scr error codes in the ErrorCodes table

Note: Documentation generated by AI on 2026-03-03

◆ GetObject()

GUIModule GetObject	(	name	,
		datatype	)

Get a property value from a named screen control.

Retrieves the specified property from the screen control with the given name. If a control named "name(1)" exists, reads from that indexed variant; otherwise reads directly from the base name. Uses the custom GUIModule.GetHidden() function when the "Hidden" property is requested. Reports an error via w.FunctionError() if the screen API returns a non-zero error code, but still returns whatever value was retrieved.

Parameters

name	(string) The screen control name (or base name) to read from
datatype	(string) The property name to retrieve (e.g., "Value", "Label", "Hidden")

Returns: (string) The property value returned by the screen API

Note: Documentation generated by AI on 2026-03-03

References name().

◆ GetObjectNameCore()

GUIModule GetObjectNameCore ( object_name )

Extract the base name of a screen control by removing any trailing index suffix.

Searches for the last opening parenthesis in the name string and returns everything before it (minus the trailing parenthesis). If no parenthesis is found, the full string is returned unchanged. For example, "MyButton(2)" returns "MyButton".

Parameters

object_name (string) The full screen control name, possibly with an index suffix such as "(1)"

Returns: (string) The base control name with any trailing index parentheses removed

Note: Documentation generated by AI on 2026-03-03

◆ GetObjectPasswordLevel()

GUIModule GetObjectPasswordLevel ( object_name )

Get the password protection level string for a screen object.

Reads the password level for the specified screen object from the Mach4 profile under the "MachMotionPasswords" section. The object name is first normalized by stripping any index suffix via GUIModule.GetObjectNameCore(). Returns "Unprotected" if no entry exists for the object.

Parameters

object_name (string) The screen control name to query the password level for

Returns: (string) The password level string (e.g., "Level1", "Unprotected")

Note: Documentation generated by AI on 2026-03-03

◆ GetObjectPasswordLevelAsValue()

GUIModule GetObjectPasswordLevelAsValue ( object_name )

Get the password protection level of a screen object as a numeric value.

Retrieves the password level string via GUIModule.GetObjectPasswordLevel() and converts it to a numeric value. "Unprotected" returns 0; all other levels return the numeric digit found at the end of the level string (e.g., "Level1" returns 1).

Parameters

object_name (string) The screen control name to query

Returns: (number) The numeric password level; 0 means unprotected, 1-9 indicates a protection level

Note: Documentation generated by AI on 2026-03-03

◆ GetState()

HeightControllers GetState ( )

Get the internal active state of this screen object.

Get the current state of the height controller as a string.

Returns: (boolean) The current active state - true if active, false if inactive

Note: Documentation generated by AI on 2026-03-03

Base class stub that returns an empty string. Subclasses such as NeuronTHC may override this method to return a meaningful state string describing the current operating mode or process sequence of the controller.

Returns: (string) Empty string in the base class implementation

Note: Documentation generated by AI on 2026-03-03

◆ GetTabInfoFromLabel()

GUIModule Notebook GetTabInfoFromLabel ( )

Get notebook tab information by searching for a matching label.

Iterates through all tabs in the notebook looking for one whose label matches the provided string. Raises an error if no tab with the given label is found.

Parameters

label (string) The label text of the tab to find

Returns: (table) Tab info table with keys: 'name' (string), 'label' (string), 'index' (number)

Warning: Raises a Lua error via w.Error() if no tab with the specified label exists

Note: Documentation generated by AI on 2026-03-03

◆ GetWholeScreenTable()

GUIModule GetWholeScreenTable ( )

Get the full screen object hierarchy table, building it if necessary.

Returns the cached screen table (h.screen_table). If the cache is empty or nil, calls GUIModule.BuildScreenTable() to construct it. The table is stored in h.screen_table for subsequent calls.

Returns: (table) Nested table representing the full screen object hierarchy

See also: GUIModule.BuildScreenTable() for the construction logic

Note: Documentation generated by AI on 2026-03-03

◆ HandleActionButton1() [1/2]

SpecificScreenModule HandleActionButton1	(	direction	,
		amount	,
		ctrl_name	,
			... )

◆ HandleActionButton1() [2/2]

SpecificScreenModule HandleActionButton1	(	direction	,
		amount	,
			... )

◆ Hidden()

GUIModule LayoutObjects Hidden ( value )

Set the hidden state of a named row in the layout.

Searches ObjectsInRows for a row whose "Name" key matches the provided name and sets its "Hidden" key to the specified value. Only the first matching row is updated. Has no effect if no row with the given name is found.

Parameters

name	(string) The name identifier of the row to update
value	(boolean) The hidden state to assign - true to hide, false to show

Note: Documentation generated by AI on 2026-03-03

◆ HideRow()

GUIModule LayoutObjects HideRow ( )

Mark a row in the layout as hidden.

Sets the Hidden flag of the specified row to true in the ObjectsInRows table. If ObjectsInRows or the specified row does not exist, it is initialized before setting the visibility. The row will be hidden during the next call to Layout().

Parameters

row_id (number) The index of the row to hide

Note: Documentation generated by AI on 2026-03-03

◆ IsObject()

GUIModule IsObject ( name )

Determine whether a screen control name refers to a base or indexed control.

-------------------— Screen Controls ----------------------—

Checks whether the given name exists as a plain control or as an indexed control (name(1)). Returns false if the plain name is a control (meaning no index suffix needed), true if the "(1)" variant exists (meaning the name is a base for indexed controls), or nil if neither form is found.

Parameters

name	(string\|any) The screen control name to test; non-strings are converted via tostring()

Returns: (boolean|nil) false if name is a plain control, true if name(1) exists, nil if not found; (boolean) true if the control was found in any form, false otherwise; (string) Status message describing the result

Note: Documentation generated by AI on 2026-03-03

References name().

◆ IsOnCurrentPage()

GUIModule Notebook IsOnCurrentPage ( )

Determine whether this notebook is on the currently visible screen page.

Compares the notebook's associated page index against the currently active screen page. If the notebook has no associated page (page_index == -1), it is considered always visible.

Returns: (boolean) True if the notebook is visible on the current page, false otherwise

Note: Documentation generated by AI on 2026-03-03

◆ IsScreenLoaded()

GUIModule IsScreenLoaded ( )

Check whether the MachGUI screen has finished loading.

Wraps scr.IsLoaded() to report whether the screen is fully initialized and ready for interaction.

Returns: (boolean) True if the screen is loaded, false otherwise

Note: Documentation generated by AI on 2026-03-03

◆ Layout()

GUIModule LayoutObjects Layout ( )

Arrange all rows of screen objects into a column-based grid layout.

Iterates through all rows in ObjectsInRows and positions each visible object using the configured padding, column spacing, and within-column spacing. Hidden rows have all their controls set to Hidden="1". Visible rows are stacked vertically; when a row would exceed the Limits.Height, a new column is started. Objects within a row are arranged horizontally with per-object or default spacing. Vertically centers shorter objects within a row relative to the tallest object. Optionally resizes the container control vertically to fit all content. Calls w.FunctionCompleted() on completion.

Note: Requires ObjectsInRows to be populated via AddToRow() before calling; If Padding, Container, Limits, or ResizeContainer are nil, defaults are applied automatically

See also: GUIModule.LayoutObjects:AddToRow() for populating rows before layout

Note: Documentation generated by AI on 2026-03-03

◆ Log()

GUIModule StackableCollection Log ( ... )

Log a formatted message for this StackableCollection if debugging is enabled.

Wraps w.Log() with a standard prefix identifying the collection's container group name. Only outputs the message if self.IsDebugging is true. Accepts a format string and variadic arguments in the same style as string.format().

Parameters

fmt	(string) A format string passed to string.format() with the group name prepended
...	(any) Additional arguments for the format string

Note: Documentation generated by AI on 2026-03-03

◆ MachButtonCall()

GUIModule MachButtonCall	(	mach_func_name	,
		control_name	,
		event_source	,
		ctrl_type	,
			... )

◆ MatchInTable()

MatchInTable	(	value	,
		options	)

Check whether a value exists in a table of options.

Iterates through the options table looking for a value that matches the provided value using equality comparison. Returns false if options is nil or not a table.

Parameters

value	(any) The value to search for
options	(table\|nil) An array of values to search within

Returns: (boolean) True if value was found in options, false otherwise

Note: Documentation generated by AI on 2026-03-03

◆ ModifyAxisDROPosition_Screen()

ThisScreenModule ModifyAxisDROPosition_Screen	(	dro_new_value	,
		AxisID	,
			... )

◆ new() [1/3]

GUIModule Notebook new ( )

Create a new Notebook object and build its tab mapping.

Constructs a new GUIModule.Notebook instance for the given notebook control name. Enumerates all child controls (tabs) of the notebook, skipping hidden tabs, and builds a bidirectional mapping in the 'tabs' table (indexed by both tab index and tab name). Also determines which screen page the notebook resides on by walking up the parent hierarchy to find an ancestor of type scr.CTYPE_PAGE.

Parameters

nb_name (string) The screen control name of the notebook (scr.CTYPE_NOTEBOOK)

Returns: (table) A new Notebook object with fields: 'name', 'tabs', 'page_index', 'page_name'

Warning: Raises a Lua error via w.Error() if any screen API call fails

Note: Tabs with "Hide Tab" property set to "1" are excluded from the mapping; Documentation generated by AI on 2026-03-03

◆ new() [2/3]

GUIModule StackableCollection new	(	constraints	,
			... )

Create a new StackableCollection from layout constraints and an ordered list of ScreenObjects.

Constructs and returns a new StackableCollection instance. Normalizes all constraint fields into lowercase internal forms for consistent access. Requires a ContainerName and Order to be specified; raises an error if either is missing. Supports the following constraint keys:

ContainerName (string): name of the group control containing all items
Limits (table): 'Width' and 'Height' arrays of {min, max}; defaults to group dimensions
ResizeContainer (table): 'Horizontal' and 'Vertical' booleans for resizing the group after stacking
Order (string): one of 'Vertical', 'Horizontal', 'Vertical-then-Horizontal', 'Horizontal-then-Vertical'
Padding (table): 'Top', 'Bottom', 'Left', 'Right' pixel values (defaults: 23, 12, 8, 8)
Between (table): 'Horizontal' and 'Vertical' pixel gaps between items (defaults: 7, 2)
Parameters

constraints (table) Layout constraint configuration table (see details above)

... (any) One or more ScreenObject instances (or subclass instances) to include in the collection

Returns
(table) A new StackableCollection instance ready for use with Stack()

Warning
Raises a Lua error via w.Error() if ContainerName is missing, the container cannot be found, or Order is not specified

See also
GUIModule.StackableCollection:Stack() for the main layout operation

Note
Documentation generated by AI on 2026-03-03

◆ new() [3/3]

GUIModule LayoutObjects new ( grid_objects )

Create a new LayoutObjects instance from a grid configuration table.

Constructs a new LayoutObjects object by copying all key-value pairs from the provided grid_objects configuration table into the new instance. The configuration table supports the following keys:

ContainerName (string): name of the container screen control
Padding (table): 'Top', 'Left', 'Bottom' padding values in pixels
ColumnSpacing (table): 'Vertical' and 'Horizontal' spacing between columns
SpacingWithinColumns (table): 'Vertical' and 'Horizontal' spacing within a column
Container (table): 'Height' of the container
Limits (table): 'Height' maximum height before starting a new column
ResizeContainer (table): 'Vertical' boolean to resize container after layout
Parameters

grid_objects (table) Configuration table defining layout constraints and container info

Returns
(table) A new LayoutObjects instance with all grid_objects fields copied in

Note
Call AddToRow() to populate rows and Layout() to apply positioning

See also
GUIModule.LayoutObjects:AddToRow() for adding objects to rows

GUIModule.LayoutObjects:Layout() for applying the layout

Note
Documentation generated by AI on 2026-03-03

◆ NextPosition()

GUIModule StackableCollection NextPosition ( )

Advance the current stacking position to the next location where an object can be placed.

Updates self.current (with 'top' and 'left' fields) to the next available position for the given screen object based on the collection's configured stacking order. Supports three modes: 1-D vertical, 1-D horizontal, and 2-D (vertical-then-horizontal or horizontal-then-vertical). Returns true if a valid position was found within the group's size limits, false if no more space is available. This function must be called after successfully placing an object to advance past it.

Parameters

scr_obj (table) A ScreenObject instance whose Width and Height are used for position calculations

Returns: (boolean) True if a valid next position exists within the container bounds, false if the container is full

See also: GUIModule.StackableCollection:FitsHereP() for checking whether the current position is valid

Note: Documentation generated by AI on 2026-03-03

◆ ObjectCacheClear()

GUIModule ObjectCacheClear ( )

Clear the object property cache.

Resets GUIModule.ObjectCache.cache to an empty table, invalidating all cached screen object metadata. The next call to SetObject() or ObjectCache:FindObjects() will re-query the screen API for object information.

See also: GUIModule.ObjectCache:FindObjects() for cache population logic

Note: Documentation generated by AI on 2026-03-03

◆ orig_SetObject()

GUIModule orig_SetObject	(	name	,
		datatype	,
		val	,
		force	)

Set a property value on a screen control and all its indexed variants (original implementation).

Original version of SetObject(), retained for reference during active testing of the new cached implementation. Sets the specified property for all controls matching the given base name, including indexed variants (name(1), name(2), ...). For numeric controls (sliders, gauges, DROs) setting the "Value" property, only updates if the difference exceeds 0.0001. For non-numeric properties, only updates if the string value has changed. The "Hidden" property uses GUIModule.SetHidden() and GUIModule.GetHidden() instead of the standard scr API functions. Boolean values are automatically converted to "1"/"0". Reports errors via w.FunctionError().

Parameters

name	(string) The base screen control name to set
datatype	(string) The property name to set (e.g., "Value", "Label", "Hidden", "Enabled")
val	(string\|number\|boolean) The new value; booleans are converted to "1"/"0", others to string
force	(boolean\|nil) If true, sets the property unconditionally without comparing to current value. Defaults to false

Note: This function is superseded by GUIModule.SetObject() and is kept for comparison purposes only

See also: GUIModule.SetObject() for the current cached implementation

Note: Documentation generated by AI on 2026-03-03

References name().

◆ PlusMinusDRO()

GUIModule PlusMinusDRO	(	name	,
		val	,
		startscrolling	,
		minimum	,
		maximum	)

Increment or decrement a DRO value by a specified amount, with optional scroll activation.

Reads the current value of the named DRO, adds the specified delta, and applies optional min/max clamping from the GUIMODULE_SCROLL_DRO table. The new value is written back via the DRO's associated Register, Parameter, or directly to the screen object. If startscrolling is true, activates the scroll DRO mechanism for continuous adjustment. Returns an error if the name is not a string, the value is not a number, or the object cannot be found.

Parameters

name	(string) The screen control name of the DRO to modify
val	(number) The amount to add to the current DRO value (may be negative)
startscrolling	(boolean) If true, activates the scroll DRO for continuous adjustment
minimum	(number\|nil) Optional minimum value clamp. If nil, uses the existing scroll DRO minimum
maximum	(number\|nil) Optional maximum value clamp. If nil, uses the existing scroll DRO maximum

Returns: (nil) Returns nil on error; (boolean) Success flag - false on error; (string) Status message from w.FunctionError() on error

Note: Documentation generated by AI on 2026-03-03

References name().

◆ RefreshAllControls()

GUIModule RefreshAllControls ( ctrl_type )

Refresh all screen controls, optionally filtered by control type.

Iterates through all screen controls and forces each one to redraw by toggling its Enabled state. This is a workaround for controls that do not properly reflect their state after Mach state changes, particularly when modal dialogs are involved. After refreshing controls, executes the "RefreshAllControls" hook. Performance metrics (control count and elapsed time) are logged on completion.

Parameters

ctrl_type (number|nil) Optional control type filter (e.g., scr.CTYPE_BUTTON). If nil, all controls are refreshed

Note: Documentation generated by AI on 2026-03-03

◆ RefreshControl()

GUIModule RefreshControl ( obj_name )

Force a single screen control to redraw by toggling its Enabled state.

Reads the current Enabled state of the control, temporarily sets it to the opposite value, then restores the original value. This causes the MachGUI renderer to redraw the control, correcting any visual state inconsistencies that may occur when Mach changes states while a modal dialog is open.

Parameters

obj_name (string) The name of the screen control to refresh

Note: Documentation generated by AI on 2026-03-03

◆ RefreshStateEnabledControls()

GUIModule RefreshStateEnabledControls ( )

Refresh all screen controls that have Mach-state-dependent enabled states.

Retrieves the cached list of controls that have "Enabled States" or "Enable With Machine" properties set, then toggles each control's Enabled state to force a redraw. This is a targeted workaround for controls that fail to render correctly when a modal dialog is open during a Mach state change. Executes the "RefreshStateEnabledControls" hook after refreshing. Performance metrics are logged.

Note: This function is less expensive than GUIModule.RefreshAllControls() as it only processes controls with state-dependent enabled properties

See also: GUIModule.RefreshAllControls() for refreshing all controls regardless of type; GUIModule.GetMachStateEnabledControls() for the list of affected controls

Note: Documentation generated by AI on 2026-03-03

◆ returns()

returns ( excluding the error code )

Call a screen API function without metadata, forwarding all arguments.

Convenience wrapper around GUIModule.api_e() that passes nil as the metadata argument. Use this when no error codes need to be ignored or suppressed.

Parameters

...	(any) The screen API function name followed by its arguments, forwarded directly to GUIModule.api_e()

◆ RunHooks()

GUIModule RunHooks	(	hook_name	,
			... )

Execute hook functions registered across user and machine screen modules.

Searches for and executes hook functions in a fixed priority order, from most specific to most general: user[hook_name], user["User"..hook_name], m.screen["Machine"..hook_name], m.screen[hook_name], m["Machine"..hook_name]. Each hook is called via w.pcall() for protected execution. A hook returning (false, b, c) with b == false signals a fatal error and stops further processing. A hook returning (false, b, c) with b ~= false signals successful completion and stops further processing. If all hooks run without stopping, returns true.

Parameters

hook_name	(string) The base name of the hook to search for and execute
...	(any) Additional arguments passed through to each hook function

Returns: (boolean) Result flag from the hook - false if a hook handled the event, true if processing should continue; (boolean) Secondary result flag - false on fatal error, true if processing should continue; (string) Status message from w.FunctionCompleted() or w.FunctionError()

Note: Documentation generated by AI on 2026-03-03

◆ ScreenButtonCall()

GUIModule ScreenButtonCall	(	handler	,
		ctrl_name	,
		event_source	,
		ctrl_type	,
			... )

◆ ScreenDROModify()

GUIModule ScreenDROModify	(	handler	,
		new_value	,
		ctrl_name	,
		event_source	,
			... )

◆ ScreenPageChanged()

GUIModule ScreenPageChanged ( ... )

Notify the screen module that a notebook page change has completed.

If m.screen.ScreenPageChanged is defined, constructs a notebook info table with the notebook name, the new tab's label, the previous tab index, and the current tab index, then invokes m.screen.ScreenPageChanged via w.ProtectedMsg(). Has no effect if the handler is not defined.

Parameters

...	(any) Variadic parameters from MachGUI: notebook name, unused, old tab index, new tab index

Note: Documentation generated by AI on 2026-03-03

◆ ScreenPageChanging()

GUIModule ScreenPageChanging ( ... )

Notify the screen module that a notebook page is about to change.

If m.screen.CommonScreenPageChanged is defined, constructs a notebook info table with the notebook name, the future tab's label, the current tab index, and the future tab index, then invokes the handler via w.ProtectedMsg(). Returns the handler's result, or true if no handler is defined (allowing the page change to proceed).

Parameters

...	(any) Variadic parameters from MachGUI: notebook name, unused, current tab index, future tab index

Returns: (boolean) True to allow the page change, or whatever the handler returns to allow or deny

Note: Documentation generated by AI on 2026-03-03

◆ ScreenTabEnter()

GUIModule ScreenTabEnter ( ... )

Handle the enter event for a notebook tab, with password protection support.

Called when the user switches to a tab. Reads the tab name and parent notebook from the variadic parameters, then executes the main logic inside a protected message handler. Waits until the screen is fully loaded before proceeding. Checks the tab's password protection level and, if protected, invokes w.PasswordProtection(); on failure, restores the previous tab and returns an error. Logs the tab change, updates the current tab number, and if m.screen.CommonScreenTabEnter is defined, constructs a tab info table and calls the handler.

Parameters

...	(any) Variadic parameters from MachGUI: the first value is the tab control name

Note: Documentation generated by AI on 2026-03-03

◆ ScreenTabExit()

GUIModule ScreenTabExit ( ... )

Handle the exit event for a notebook tab.

Called when the user leaves a tab. Reads the tab name and parent notebook from the variadic parameters, retrieves the cleaned label for logging, and caches the current tab index if not already cached. Logs the exit event. If m.screen.CommonScreenTabExit is defined, constructs a tab info table (name, label, index, parent) and invokes the handler via w.ProtectedMsg().

Parameters

...	(any) Variadic parameters from MachGUI: the first value is the tab control name

Note: Documentation generated by AI on 2026-03-03

◆ ScreenToggleButtonCall()

GUIModule ScreenToggleButtonCall	(	handler	,
		ctrl_name	,
		event_source	,
			... )

◆ SetAxisObject()

GUIModule SetAxisObject	(	name	,
		datatype	,
		val	,
		axis	)

Set a property of axis-associated screen controls, respecting axis enabled state.

Iterates through all indexed variants of the named control (name(1), name(2), ...) and sets the specified property. For properties that relate to visibility or enablement ("Enabled", "Fg Color", "Hidden", "Left"), the actual value applied depends on whether the given axis is enabled in the current selected instance. Disabled axes force controls to appear disabled, grey, hidden, or moved off-screen respectively. Other properties are not modified.

Parameters

name	(string) The base screen control name to set
datatype	(string) The property name to set (e.g., "Enabled", "Fg Color", "Hidden", "Left")
val	(string\|number) The value to apply when the axis is enabled
axis	(number) The axis index used to check enabled state (mc.X_AXIS, mc.Y_AXIS, etc.)

Note: Documentation generated by AI on 2026-03-03

References name().

◆ SetButtonLED()

GUIModule SetButtonLED	(	name	,
		val	,
		color	)

Set the LED state of a button control using color and value.

Convenience wrapper that calls GUIModule.SetLabelLED() with the color and value arguments reordered to match the button-centric calling convention.

Parameters

name	(string) The screen control name of the button LED to set
val	(boolean\|number) The LED state - true or non-zero for on, false or zero for off
color	(string\|nil) The color name for the LED (e.g., "GREEN", "RED"). Defaults to "GREEN" if nil

See also: GUIModule.SetLabelLED() for the full list of supported color names

Note: Documentation generated by AI on 2026-03-03

References name().

◆ SetDRO()

GUIModule SetDRO	(	name	,
		val	)

Set the value of a DRO screen control.

Sets the "Value" property of all matching DRO screen controls with the given name. Checks the base name first, then iterates through indexed variants (name(1), name(2), ...). Only calls scr.SetProperty() if the current value differs from the new value, minimizing unnecessary screen API calls.

Parameters

name	(string) The screen control name (or base name) of the DRO to set
val	(string\|number) The value to set; converted to string if not already

Note: Documentation generated by AI on 2026-03-03

References name().

◆ SetDropDownSelectedIndex()

GUIModule SetDropDownSelectedIndex	(	name	,
		idx	)

Set the selected item of a drop-down control by zero-based index.

Reads the "Strings" property of the named drop-down control, splits it by "|" to get the list of options, and sets the "Value" property to the string at the specified index. Reports an error via w.FunctionError() if the index is out of range.

Parameters

name	(string) The screen control name of the drop-down to set
idx	(number) The zero-based index of the option to select

Note: Documentation generated by AI on 2026-03-03

References name().

◆ SetHidden()

GUIModule SetHidden	(	name	,
		dummy_unused	,
		make_hidden	)

Set the hidden state of a screen control using a position-based workaround.

Implements hide/unhide behavior that works reliably across all control types. For toolpath controls (scr.CTYPE_TOOLPATH), uses the standard "Hidden" property directly. For all other controls, hides by adding 10000 to the "Left" property (moving off-screen) and unhides by subtracting 10000. This workaround is used because the standard "Hidden" property does not behave consistently for all control types in MachGUI. The ObjectCache is updated whenever Left is modified to keep cached values consistent, and the cached "Hidden" value is removed to force recalculation on next read.

Parameters

name	(string) The screen control name to show or hide
dummy_unused	(any) Unused parameter; present for API symmetry with scr.SetProperty()
make_hidden	(string) "1" to hide the control, "0" to show it

Returns: (number) The screen API return code from scr.SetProperty(), or scr.SERROR_NOERROR if no change was needed

See also: GUIModule.GetHidden() for the corresponding getter

Note: Documentation generated by AI on 2026-03-03

References name().

◆ SetLabelLED()

GUIModule SetLabelLED	(	name	,
		color	,
		val	)

Set the background color of a label or button control to indicate an LED state.

Sets the background and foreground colors of all matching screen controls based on the provided color name and boolean/numeric state value. Supports both button controls (scr.CTYPE_BUTTON) and all other control types, each with their own color table per color name. Supported color names include: "GREEN", "RED", "BLUE", "YELLOW", "ORANGE", "GREY", "WHITE", and color scheme variants prefixed with "COLORSCHEME_" (e.g., "COLORSCHEME_GREEN", "COLORSCHEME_MUTED_RED"). Iterates through all indexed variants of the control name.

Parameters

name	(string) The screen control name (or base name) of the LED label or button
color	(string) The color name to use for on/off states. Defaults to "GREEN" if unrecognized
val	(boolean\|number\|nil) State value - true or non-zero sets the on color; false or zero sets the off color

Note: Documentation generated by AI on 2026-03-03

References name().

◆ SetLED()

GUIModule SetLED	(	name	,
		val	)

Set the value of an LED screen control.

Sets the "Value" property of all matching LED screen controls with the given name. Checks the base name first, then iterates through indexed variants (name(1), name(2), ...). Only calls scr.SetProperty() if the current value differs from the new value. Accepts boolean values, converting true to "1" and false to "0" automatically.

Parameters

name	(string) The screen control name (or base name) of the LED to set
val	(boolean\|string\|number) The value to set; booleans are converted to "1"/"0"

Note: Documentation generated by AI on 2026-03-03

References name().

◆ SetMMToggleButton()

GUIModule SetMMToggleButton	(	name	,
		value	)

Set the visual state of an MM toggle button by updating its image property.

Determines the correct on/off image filename based on the button's pixel width and sets the "Image" property of the screen control accordingly. The image filenames follow the pattern "On{px}px.png" and "Off{px}px.png" where {px} is the width bucket.

Parameters

name	(string) The screen control name of the MM toggle button to update
value	(boolean) The desired state - true for on, false for off

Returns: (any) The return value from GUIModule.SetObject()

See also: GUIModule.GetMMToggleButton() for reading the current toggle state; GUIModule.GetMMToggleButtonWidthPixel() for pixel width bucket logic

Note: Documentation generated by AI on 2026-03-03

References name().

◆ SetObject()

GUIModule SetObject	(	name	,
		property	,
		val	,
		force	)

Intelligently set a property value on a screen control and all its indexed variants.

Sets the specified property for all controls matching the given base name, including indexed variants (name(1), name(2), ...). Uses the GUIModule.ObjectCache to minimize unnecessary screen API calls by comparing the new value against the cached or current value. For numeric controls (sliders, gauges, DROs) setting the "Value" property, only updates if the difference exceeds 0.0001. For non-numeric properties, only updates if the value has changed. The "Hidden" property uses GUIModule.SetHidden() and GUIModule.GetHidden() instead of the standard scr.SetProperty()/scr.GetProperty() functions. The "Current Tab" property is always set unconditionally. Boolean values are automatically converted to "1"/"0".

Parameters

name	(string) The base screen control name to set
property	(string) The property name to set (e.g., "Value", "Label", "Hidden", "Enabled")
val	(string\|number\|boolean) The new value; booleans are converted to "1"/"0", others to string
force	(boolean\|nil) If true, sets the property unconditionally without comparing to current value. Defaults to false

Note: Documentation generated by AI on 2026-03-03

References name().

◆ SetObjectPasswordLevel()

GUIModule SetObjectPasswordLevel	(	object_name	,
		level	)

Set the password protection level for a screen object.

Writes the password level string for the specified screen object to the Mach4 profile under the "MachMotionPasswords" section. The object name is first normalized by stripping any index suffix via GUIModule.GetObjectNameCore().

Parameters

object_name	(string) The screen control name to assign a password level to
level	(string) The password level string to assign (e.g., "Level1", "Unprotected")

Note: Documentation generated by AI on 2026-03-03

◆ SetState()

GUIModule ScreenObject SetState ( )

Set the internal active state of this screen object.

Parameters

new_state (boolean) The new active state - true to mark as active, false to mark as inactive

Note: Documentation generated by AI on 2026-03-03

◆ ShowGroupInnards()

GUIModule ShowGroupInnards	(	group_name	,
		show	)

Show or hide all child controls within a group screen object.

If the named control exists in the screen, retrieves all child controls of the group and sets their Hidden property. The show parameter is normalized so that nil, true, 1, or "1" result in showing the children (Hidden="0"), while any other value hides them (Hidden="1"). Has no effect if the group control does not exist.

Parameters

group_name	(string) The screen control name of the group whose children to show or hide
show	(boolean\|number\|string\|nil) Show state - nil/true/1/"1" to show children, anything else to hide them

Note: Documentation generated by AI on 2026-03-03

◆ ShowRow()

GUIModule LayoutObjects ShowRow ( )

Mark a row in the layout as visible.

Sets the Hidden flag of the specified row to false in the ObjectsInRows table. If ObjectsInRows or the specified row does not exist, it is initialized before setting the visibility. The row will be shown during the next call to Layout().

Parameters

row_id (number) The index of the row to show

Note: Documentation generated by AI on 2026-03-03

◆ Stack()

GUIModule StackableCollection Stack ( )

Reposition all items in the collection, hiding inactive or non-fitting objects.

This is the primary method of the StackableCollection class. It performs the following:

Hides all items initially.
For each item, calls UpdateState() to determine if it is active.
Active items are placed at the current stacking position if they fit; otherwise they are hidden.
Inactive or overflow items have their state forced to false and UpdateScreen() is called.
After placing each active item, NextPosition() advances the current position.
Optionally resizes the container group horizontally and/or vertically to fit the placed content, respecting the configured minimum dimensions.
Note
Requires the collection to have been created with StackableCollection.new() and items added

See also
GUIModule.StackableCollection:NextPosition() for position advancement logic

GUIModule.StackableCollection:FitsHereP() for fit detection

Note
Documentation generated by AI on 2026-03-03

◆ StartScreenLoadedCheck()

GUIModule StartScreenLoadedCheck ( )

Start the timer that polls for screen load completion.

Starts the GUIModule.OnLoadedTimer at 100ms intervals. When the screen reports that it is loaded (scr.IsLoaded()), the timer stops and executes the ScreenIsLoadedScript hooks and builds the notebook tab mapping.

Note: This function must be called after the screen begins loading to trigger post-load initialization

See also: GUIModule.Notebooks:BuildMapping() for notebook initialization that occurs on screen load

Note: Documentation generated by AI on 2026-03-03

◆ StartScrollDRO() [1/2]

GUIModule StartScrollDRO ( )

Activate the scroll DRO mechanism.

Sets the GUIMODULE_SCROLL_DRO["Active"] flag to true if it is not already active, enabling continuous DRO value adjustment on subsequent calls to UpdateScrollDRO().

See also: GUIModule.StopScrollDRO() to deactivate scrolling; GUIModule.UpdateScrollDRO() for the scroll state machine

Note: Documentation generated by AI on 2026-03-03

◆ StartScrollDRO() [2/2]

GUIModule StartScrollDRO	(	name	,
		val	,
		minimum	,
		maximum	)

Activate the scroll DRO mechanism.

Sets the GUIMODULE_SCROLL_DRO["Active"] flag to true if it is not already active, enabling continuous DRO value adjustment on subsequent calls to UpdateScrollDRO().

See also: GUIModule.StopScrollDRO() to deactivate scrolling; GUIModule.UpdateScrollDRO() for the scroll state machine

Note: Documentation generated by AI on 2026-03-03

References name().

◆ StopScrollDRO() [1/2]

GUIModule StopScrollDRO ( )

Deactivate the scroll DRO mechanism.

Sets the GUIMODULE_SCROLL_DRO["Active"] flag to false, stopping any ongoing DRO scrolling on the next call to UpdateScrollDRO().

See also: GUIModule.StartScrollDRO() to activate scrolling; GUIModule.UpdateScrollDRO() for the scroll state machine

Note: Documentation generated by AI on 2026-03-03

◆ StopScrollDRO() [2/2]

GUIModule StopScrollDRO ( name )

Deactivate the scroll DRO mechanism.

Sets the GUIMODULE_SCROLL_DRO["Active"] flag to false, stopping any ongoing DRO scrolling on the next call to UpdateScrollDRO().

See also: GUIModule.StartScrollDRO() to activate scrolling; GUIModule.UpdateScrollDRO() for the scroll state machine

Note: Documentation generated by AI on 2026-03-03

References name().

◆ SwitchSpecialMode() [1/2]

SpecificScreenModule SwitchSpecialMode	(	curr_mode	,
		prev_mode	,
		ctrl_name	,
			... )

◆ SwitchSpecialMode() [2/2]

SpecificScreenModule SwitchSpecialMode	(	curr_mode	,
		prev_mode	,
			... )

◆ TranslateGroup()

GUIModule TranslateGroup ( obj )

Translate all label text in a group and its eligible children.

Translates the label of the group object itself, then retrieves all child controls of translatable types (static text, buttons, pages, groups, notebook pages, toggle buttons) and translates their labels using wx.wxGetTranslation().

Parameters

obj	(string) The screen control name of the group to translate

See also: GUIModule.TranslateObject() for translating a single object

Note: Documentation generated by AI on 2026-03-03

◆ TranslateObject()

GUIModule TranslateObject ( obj )

Translate the label of a single screen object using the wxWidgets translation system.

Checks whether the screen object has a "Label" property. If it does, retrieves the current label text, passes it through wx.wxGetTranslation(), and sets the translated result back on the object.

Parameters

obj	(string) The screen control name of the object to translate

Note: Has no effect if the object does not have a "Label" property

See also: GUIModule.TranslateGroup() for translating an entire group of objects

Note: Documentation generated by AI on 2026-03-03

◆ UpdatePosition()

GUIModule ScreenObject UpdatePosition ( )

Read and cache the current position and size of this screen object from the screen.

Queries the screen API for the Top, Left, Height, and Width properties of the associated control and stores the numeric values in the corresponding fields of this object. Raises a Lua error if any property cannot be retrieved.

Warning: Raises a Lua error via w.Error() if any positional property returns nil

Note: Documentation generated by AI on 2026-03-03

◆ UpdateScreen()

GUIModule ScreenObject UpdateScreen ( )

Apply this ScreenObject's position and visibility to the live screen.

Sets the Top and Left properties of the screen control to the values stored in this object. Also sets the Hidden property based on the current state: hidden (1) if state is false, visible (0) if state is true. Logs the update if debugging is enabled.

Note: Object size (Width and Height) is not currently managed by this function

See also: GUIModule.ScreenObject:UpdatePosition() for reading position from the screen; GUIModule.ScreenObject:SetState() for changing the active state

Note: Documentation generated by AI on 2026-03-03

◆ UpdateScrollDRO()

GUIModule UpdateScrollDRO ( )

Update the scroll DRO state machine, advancing or resetting the scrolling DRO value.

Called periodically (e.g., from the PLC script) to manage the scroll DRO behavior. When scrolling is active and was already active, applies a delay before beginning to scroll, then calls PlusMinusDRO() at an accelerating rate based on the total number of scans elapsed. Resets internal counters when scrolling transitions from inactive to active, and clears all state when scrolling transitions from active to inactive.

Note: Relies on the global GUIMODULE_SCROLL_DRO table for all state; should be called each PLC scan

See also: GUIModule.StartScrollDRO() to activate scrolling; GUIModule.StopScrollDRO() to deactivate scrolling; GUIModule.PlusMinusDRO() for the underlying DRO increment function

Note: Documentation generated by AI on 2026-03-03

◆ UpdateState()

GUIModule AxisButton UpdateState ( )

Update this object's internal state based on detectable conditions.

Update the active state of an AxisButton based on whether its associated axis is enabled.

Base implementation for ScreenObject. At this level, there is no way to discern whether the object ought to be active, so the state is unconditionally set to true. Subclasses should override this method to implement condition-specific logic.

Returns: (boolean) Always returns true at this base class level

Note: Subclasses such as AxisButton override this to implement axis-enable detection

See also: GUIModule.AxisButton:UpdateState() for an example subclass override

Note: Documentation generated by AI on 2026-03-03

Queries mc.mcAxisIsEnabled() for the button's axis_id using the currently selected instance. If axis_id is outside the valid axis range (mc.AXIS0 to mc.MC_MAX_AXES), the button is unconditionally set to active. If the API call returns an error, logs the error and returns without changing state. Sets internal state to true if the axis is enabled, false if disabled.

Note: Uses w.GetSelectedInstance() rather than mc.mcGetInstance() for the axis query

See also: GUIModule.AxisButton.Associate() for creating an AxisButton instance

Note: Documentation generated by AI on 2026-03-03

◆ WalkScreenObjectsDFS()

GUIModule WalkScreenObjectsDFS	(	obj_name	,
		parent_first	,
		filter_fn	)

Create a coroutine-based iterator for depth-first traversal of screen objects.

Wraps GUIModule._WalkDFS() in a coroutine, returning an iterator function suitable for use in a generic for loop. Each call to the iterator resumes the coroutine and returns the next screen object name. Raises a Lua error if the coroutine encounters an error during traversal. Iteration stops when all objects have been visited.

Parameters

obj_name	(string\|nil) The root screen object to start traversal from. If nil, uses scr.GetScreenName()
parent_first	(boolean\|nil) If true (default), yield parent before children; if false, yield children first
filter_fn	(function\|nil) Optional function(ctrl_name) returning true to include the object, false to skip it

Returns: (function) An iterator function that returns one screen control name per call, or nil when done

-- Get all screen objects under "root_obj_name"
for obj_name in GUIModule.WalkScreenObjectsDFS('root_obj_name') do
    print(obj_name)
end
 
-- Only return buttons
for obj_name in GUIModule.WalkScreenObjectsDFS('root_obj_name', true,
    function(ctrl)
        return scr.GetCtrlType(ctrl) == scr.CTYPE_BUTTON
    end) do
    print(obj_name)
end

Warning: Raises a Lua error via w.Error() if the coroutine encounters an error during traversal

See also: GUIModule._WalkDFS() for the underlying recursive implementation

Note: Documentation generated by AI on 2026-03-03

References filter_fn().

constraints	(table) Layout constraint configuration table (see details above)
...	(any) One or more ScreenObject instances (or subclass instances) to include in the collection

Functions

Function Documentation

◆ AddToRow()

◆ AncestorPath()

◆ api()

◆ api_e()

◆ Associate() [1/2]

◆ Associate() [2/2]

◆ BuildMapping()

◆ BuildScreenTable()

◆ ConvertToLegalVariableName()

◆ DoesHaveProperty()

◆ DoFunctionCode()

◆ DoFunctionName()

◆ DoFunctionNameInst()

◆ filter_fn()

◆ FindObjects()

◆ FitsHereP()

◆ FormatDRO()

◆ Get()

◆ GetAllControls()

◆ GetCleanedLabel()

◆ GetCurrentTab()

◆ GetDRO()

◆ GetDropDownSelectedIndex()

◆ GetHidden()

◆ GetInstanceCount()

◆ GetLED()

◆ GetListOfChildren()

◆ GetMachStateEnabledControls()

◆ GetMMToggleButton()

◆ GetMMToggleButtonWidthPixel()

◆ GetMsg()

◆ GetMsgCount()

◆ GetObject()

◆ GetObjectNameCore()

◆ GetObjectPasswordLevel()

◆ GetObjectPasswordLevelAsValue()

◆ GetState()

◆ GetTabInfoFromLabel()

◆ GetWholeScreenTable()

◆ HandleActionButton1() [1/2]

◆ HandleActionButton1() [2/2]

◆ Hidden()

◆ HideRow()

◆ IsObject()

◆ IsOnCurrentPage()

◆ IsScreenLoaded()

◆ Layout()

◆ Log()

◆ MachButtonCall()

◆ MatchInTable()

◆ ModifyAxisDROPosition_Screen()

◆ new() [1/3]

◆ new() [2/3]

◆ new() [3/3]

◆ NextPosition()

◆ ObjectCacheClear()

◆ orig_SetObject()

◆ PlusMinusDRO()

◆ RefreshAllControls()

◆ RefreshControl()

◆ RefreshStateEnabledControls()

◆ returns()

◆ RunHooks()

◆ ScreenButtonCall()

◆ ScreenDROModify()

◆ ScreenPageChanged()

◆ ScreenPageChanging()

◆ ScreenTabEnter()

◆ ScreenTabExit()

◆ ScreenToggleButtonCall()

◆ SetAxisObject()

◆ SetButtonLED()

◆ SetDRO()

◆ SetDropDownSelectedIndex()

◆ SetHidden()

◆ SetLabelLED()

◆ SetLED()

◆ SetMMToggleButton()