Menus and controls

Discover an action

from gvu import Session

session = Session.attach()
items = session.menus()
roots = [item.path[0] for item in items if len(item.path) == 1]
results = session.model("G1:").menus("Results")

menus() returns a flat catalog whose path tuples encode the hierarchy:

• The default roots are GaussView, File, Edit, Tools, Builder, View, Calculate, Results, Windows and Help.

• Services and nested menus are included.

• menus("Results") restricts discovery to one root.

• menus("Apple") explicitly accesses the operating-system menu.

Availability belongs to the active molecule/dialog context. Use model.menus(...) or model.invoke(...) to select that model first. Recent files, available groups, window titles and some command states are dynamic; inspect again after the context changes.

Interpret menu state

Field	Meaning
path	Exact tuple of menu and submenu names
enabled	Whether the item and its ancestors permit invocation
native_enabled	The item’s own native enabled flag
checked	True or False for recognized choices; None for an unmarked ordinary command
kind	action, submenu, toggle or radio
submenu	Whether the entry contains child commands
shortcut	Native Shortcut metadata, when exposed
mark	Native selection-mark character, when exposed

A Shortcut preserves the native character, modifier bit mask, glyph and virtual-key code. Its fields can be absent; the API does not invent a key binding. The menu reference lists command paths grouped by root.

Invoke and set state

item = session.action("Results", "Vibrations...")
if item.enabled:
    session.invoke(*item.path)

session.set_menu("View", "Labels", checked=True)

• action resolves one exact current entry.

• invoke requires an enabled leaf. Unavailable, ambiguous and submenu-only paths raise ActionUnavailable.

• set_menu reads the existing state, changes it only when necessary and verifies the result.

• To change a radio choice, select another item. Clearing the selected choice directly is unsupported.

Opening a native command may modify a structure, save files or launch a calculation. Menu enumeration alone does not execute those leaf commands. No example here submits a calculation.

Dialogs and native controls

After opening a command, select its dialog with session.dialog(title). controls() returns native Control descriptors, including their tree path, originating dialog, role, label, enabled state, value, supported actions and writable attributes.

dialog = session.dialog("Dialog title from the current application")
controls = dialog.controls()
buttons = [control for control in controls
           if control.role == "AXButton" and control.enabled is not False]

Pass a discovered descriptor to dialog.perform(control, "AXPress"), or to dialog.set_value(control, value) when AXValue is writable. The library resolves the descriptor again and rejects changed or disabled targets and unsupported operations. An enabled state of None means the native interface does not expose that flag.

Many GaussView Qt widgets appear only as an AXUnknown region. Use the rendered-interface helpers where native controls are unavailable:

• dialog.labels() reads text through OCR.

• click(label) clicks a label.

• check(label, enabled=True) sets a checkbox.

• fill(x, y, value) enters a value at dialog-relative coordinates measured in display points.

• choose(label) selects a choice.

• key(name) sends a key.

An OCR label does not establish a widget’s type, enabled state or current value. Duplicate labels are rejected rather than resolved arbitrarily.

Settings

preferences = session.settings()
pages = preferences.pages()
preferences.cancel()

• settings() discovers the application settings command.

• pages() lists 17 preference categories.

• page(name) requires a content change after selection and raises ActionUnavailable when that change cannot be verified. Selecting an already displayed page can also fail this check.

• apply() selects Ok and verifies closure.

• cancel() closes the dialog without applying changes.

Opening, category discovery, native-control inspection and closure were tested. Rendered page navigation failed verification. Individual settings fields and applying changed values remain unverified. Read the coverage record before automating preference changes.

Right-click menus

Model right-click menus share many menu-bar commands; scripts can use the indexed paths through model.invoke(...). This does not prove that the two menus are identical. Plot context menus use Plot.data, image and properties helpers. Arbitrary context-menu trees are not part of the menu-bar catalog.