gui: Main ChimeraX graphical user interface¶

The principal class that tool writers will use from this module is MainToolWindow, which is either instantiated directly, or subclassed and instantiated to create the tool’s main window. Additional windows are created by calling that instance’s MainToolWindow.create_child_window() method.

Rarely, methods are used from the UI class to get keystrokes typed to the main graphics window, or to execute code in a thread-safe manner. The UI instance is accessed as session.ui.

class ChildToolWindow(tool_instance, title, **kw)¶

Bases: ToolWindow

Supported API. Child (i.e. additional) tool window

Only created through use of MainToolWindow.create_child_window() method.

class DefineSelectorDialog(session, *args, **kw)¶: Bases: QDialog

class InitWindowSizeOption(*args, session=None, **kw)¶

Bases: Option

set_multiple()¶: Supported API . Indicate that the items the option covers have multiple different values

property value¶: Supported API. Get/set the option’s value; when set it should NOT invoke the callback

class LabelHeightDialog(session, *args, **kw)¶: Bases: QDialog

class MainToolWindow(tool_instance, **kw)¶

Bases: ToolWindow

Supported API. Class used to generate tool’s main UI window.

The window’s ui_area attribute is the parent to all the tool’s widgets for this window. Call manage() once the widgets are set up to show the tool window in the main interface.

Parameters:: tool_instance – a ToolInstance instance The tool creating this window.

create_child_window(title, *, window_class=None, **kw)¶

Supported API . Make additional tool window

Parameters:

title (str) – Text shown in the window’s title bar.
window_class (ChildToolWindow) – Class to instantiate to create the child window. Only needed if you want to override methods/attributes in order to change behavior.
kw – Keywords to pass on to the tool window’s constructor

class MainWindow(ui, session)¶

Bases: QMainWindow, PlainTextLog

add_menu_entry(menu_names, entry_name, callback, *, tool_tip=None, insertion_point=None, shortcut=None)¶

Supported API . Add a main menu entry. Adding entries to the Select menu should normally be done via the add_select_submenu method instead. For details, see the doc string for that method.

Menus that are needed but that don’t already exist (including top-level ones) will be created. The menu names (and entry name) can contain appropriate keyboard navigation markup. Callback function takes no arguments. This method cannot be used to add entries to menus that are updated dynamically, such as Tools.

If ‘insertion_point is specified, then the entry will be inserted before it. ‘insertion_point’ can be a QAction, a string (menu item text with navigation markup removed) an integer indicating a particular separator (top to bottom, numbering starting at 1), or False indicating that the entry should be placed at the top of the menu.

add_menu_selector(menu, label, selector_text=None, *, insertion_point=None)¶: Supported API . Add an item to the given menu (which was probably obtained with the add_select_submenu method) which will make a selection using the given selector text (which should just be the text of the selector, not a full command) while honoring the current selection mode set in the Select menu. If ‘selector_text’ is not given, it defaults to be the same as ‘label’. The label can have keyboard navigation markup. If ‘insertion_point’ is specified, then the item will be inserted before it. ‘insertion_point’ can be a QAction, a string (menu item text with navigation markup removed) or an integer indicating a particular separator (top to bottom, numbering starting at 1).

add_select_submenu(parent_menu_names, submenu_name, *, append=True)¶

Supported API . Add a submenu (or get it if it already exists). Any parent menus will be created as needed. Menu names can contain keyboard navigation markup (the ‘&’ character). ‘parent_menu_names’ should not contain the Select menu itself. If ‘append’ is True then the menu will be appended at the end of any existing items, otherwise it will be alphabetized into them.

The caller is responsible for filling out the menu with entries, separators, etc. Any further submenus should again use this call. Entry or menu callbacks that actually make selections should use the select_by_mode(selector_text) method to make the selection, which will run the command appropriate to the current selection mode of the Select menu.

The convenience method add_menu_selector, which takes a menu, a label, and an optional selector text (defaulting to the label) can be used to easily add items to the menu.

add_settings_option(category, option)¶: Experimental API . For bundles that need/want to present their settings with the core ChimeraX settings rather than present their own settings UI

changeEvent(self, a0: QEvent | None)¶: Experimental API .

enable_stereo(stereo=True)¶: Experimental API . Switching to a sequential stereo OpenGL context seems to require replacing the graphics window with a stereo compatible window on Windows 10 with Qt 5.9.

log(*args, **kw)¶

Supported API . Log a message.

Parameters:

level (LOG_XXX constant from Log base class) – How important the message is (e.g., error, warning, info)
msg (text) – Message to log

Return type:

True if the routine displayed/handled the log message, False otherwise.

property main_view¶: Return the widget that contains the graphics area

select_by_mode(selector_text)¶: Supported API . Select based on the selector ‘selector_text’ but honoring the current selection mode chosen in the Select menu. Typically used by callbacks off the Selection menu

status(msg, color, secondary)¶

Supported API . Show a status message.

Parameters:

msg (plain (non-HTML) text) – The message to display
color (text or (r,g,b) tuple, r/g/b in range 0-1) – Color to display text in. If log cannot understand color text string, use CanvasText instead.
secondary (boolean) – Whether to show the status in the secondary status area. If the log doesn’t support a secondary status area it should either drop the status or combine it with the last known primary status message.

Returns:

True if the routine displayed/handled the status, False otherwise.
This method is not abstract because a log is free to totally
ignore/drop status messages.
Note that this method may be called from a thread (due to the
use of timers to get proper time delays) and that therefore
special window toolkit handling may be necessary to get your
code executed in the main thread (*e.g., session.ui.thread_safe()).*

class SelContactsDialog(session, *args, **kw)¶: Bases: QDialog

class SelSeqDialog(session, *args, **kw)¶: Bases: QDialog

class SelZoneDialog(session, *args, **kw)¶: Bases: QDialog

class ToolSideOption(*args, values=None, **kw)¶: Bases: EnumOption

class ToolWindow(tool_instance, title, *, close_destroys=True, hide_title_bar=False, statusbar=False)¶

Bases: StatusLogger

Supported API. An area that a tool can populate with widgets.

This class is not used directly. Instead, a tool makes its main window by instantiating the MainToolWindow class (or a subclass thereof), and any subwindows by calling that class’s create_child_window() method.

The window’s ui_area attribute is the parent to all the tool’s widgets for this window. Call manage() once the widgets are set up to show the tool window in the main interface.

The close_destroys keyword controls whether closing this window destroys it or hides it. If it destroys it and this is the main window, all the child windows will also be destroyed.

The statusbar keyword controls whether the tool will display status messages via an in-window statusbar, or via the main ChimeraX statusbar. In either case, the status() method can be used to issue status messages. It accepts the exact same arguments/keywords as the status() method in the Logger class. The resulting QStatusBar widget (or None if statusbar was False) will be available from the ToolWindow’s “statusbar” in case you need to add widgets to it or otherwise customize it.

cleanup()¶

Supported API . Perform tool-specific cleanup

Override this method to perform additional actions needed when the window is destroyed

confirm_close()¶

Supported API . Confirm that window can be closed.

Override this if the window contains important data that may be lost if inadvertently closed. Return False to keep the window open

destroy()¶

Supported API . Called to destroy the window (from non-UI code)

Destroying a tool’s main window will also destroy all its child windows.

fill_context_menu(menu, x, y)¶

Supported API . Add items to this tool window’s context menu, whose downclick occurred at position (x,y)

Override to add items to any context menu popped up over this window.

Note that you need to specify the ‘parent’ argument of the QAction constructor (as ‘menu’) to avoid having the action automatically destroyed and removed from the menu when this method returns.

manage(placement=None, fixed_size=False, allowed_areas=<DockWidgetArea.LeftDockWidgetArea|RightDockWidgetArea: 3>, initially_hidden=False)¶

Supported API . Show this tool window in the interface

Tool will be docked into main window on the side indicated by placement (which should be a value from placements or ‘side’ or None, or another tool window). If placement is “side”, then the user-preferred side will be used. If placement is None, the tool will be detached from the main window. If placement is another tool window, then those tools will be tabbed together.

If fixed_size is True then the vertical size of the panel will equal the requested size, otherwise the panel could be vertically larger or smaller than its layout requires.

The tool window will be allowed to dock in the allowed_areas, the value of which is a bitmask formed from Qt’s Qt.DockWidgetAreas flags.

The tool will be displayed unless ‘initially_hidden’ is True. This flag is needed because setting tool.shown to False after manage() will otherwise briefly show the tool.

placements = ['side', 'right', 'left', 'top', 'bottom']¶: Experimental API . Where the window can be placed in the main interface; ‘side’ is either left or right, depending on user preference

property shown¶: Whether this window is hidden or shown

shown_changed(shown)¶

Supported API . Perform actions when window hidden/shown

Override to perform any actions you want done when the window is hidden (shown = False) or shown (shown = True)

shrink_to_fit()¶: Supported API . Resize the window to take up the minimum size needed by its contents. Typically used after hiding widgets.

status(*args, **kw)¶: Supported API . Show a status message for the tool.

property title¶: Supported API. Get/change window title.

class UI(session, *, color_scheme=None)¶

Bases: QApplication

Main ChimeraX user interface

The only methods that tools might directly use are:

register(/deregister)_for_keystrokes: For the rare tool that might want to get keystrokes that are typed when focus is in the main graphics window
thread_safe: To execute a function in a thread-safe manner

deregister_for_keystrokes(sink, notfound_okay=False)¶: Experimental API . ‘undo’ of register_for_keystrokes(). Use the same argument.

dismiss_context_menu()¶: Experimental API . Clicks on the graphics QWindow don’t dismiss context menus in Qt 6.4. This call works around that problem allowing graphics clicks to dismiss any context menus shown with UI.post_context_menu().

forward_keystroke(event)¶

Experimental API . forward keystroke from graphics window to most recent caller of ‘register_for_keystrokes’

up/down arrow keystrokes are not forwarded and instead promote/demote the graphics window selection

register_for_keystrokes(sink)¶: Experimental API . ‘sink’ is interested in receiving keystrokes from the main graphics window. That object’s ‘forwarded_keystroke’ method will be called with the keystroke event as the argument.

set_fatal_error_log_file(file)¶: Experimental API . Profile open file object for writing fatal error messages.

thread_safe(func, *args, **kw)¶: Supported API . Call function ‘func’ in a thread-safe manner

window_image()¶: Experimental API . Tests on macOS 10.14.5 show that QWidget.grab() gives a correct QPixmap even for undisplayed or iconified windows, except not for html widgets (e.g. Log, or file history) which come out blank. Hidden windows also may render an image at the wrong size with a new layout (e.g. Model Panel).

Widgets for choosing models, etc.¶

class ItemListWidget(*, autoselect='default', selection_mode='extended', balloon_help=None, **kw)¶

Bases: ItemsGenerator, ItemsUpdater, QListWidget

destroy(self, destroyWindow: bool = True, destroySubWindows: bool = True)¶: Experimental API .

mod_key_info()¶

Experimental API . Qt swaps control/meta on Mac, so centralize that knowledge here. The possible “key_functions” are: alt, control, command, and shift

Returns the Qt modifier bit (e.g. Qt.KeyboardModifier.AltModifier) and name of the actual key

class ItemMenuButton(*, autoselect='default', balloon_help=None, no_value_button_text='No item chosen', no_value_menu_text=None, special_items=[], autoselect_single_item=None, **kw)¶

Bases: ItemsGenerator, ItemsUpdater, MenuButton

destroy(self, destroyWindow: bool = True, destroySubWindows: bool = True)¶: Experimental API .

class MenuButton(**kw)¶: Bases: QPushButton

class ModelListWidget(session, **kw)¶

Bases: ItemListWidget

Maintain a list of models

Keep list up to date as models are opened and closed while keeping the selected item(s) the same

‘autoselect’ controls what happens when nothing would be selected. The possible values (which are class variables) are:

AUTOSELECT_ALL: all items are selected

AUTOSELECT_SINGLE: if there is only one item in the list, it will be selected

AUTOSELECT_NONE: select nothing

AUTOSELECT_FIRST: the first item in the list will be selected

AUTOSELECT_FIRST_DISPLAYED: select the first item whose ‘display’ attribute is True; if there is none, then the first item

AUTOSELECT_LAST, AUTOSELECT_LAST_DISPLAYED: analogous to the _FIRST_ values, except the last item instead of the first.

The default is AUTOSELECT_ALL.

‘selection_mode’ controls how items are selected in the list widget. Possible values are: ‘single’, ‘extended’, and ‘multi’ (default ‘extended’) which correspond to QAbstractItemView:: Single/Extended/MultiSelection respectively as per: https://doc.qt.io/qt-5/qabstractitemview.html#SelectionMode-enum

‘balloon_help’ is the balloon help to provide with the list (if any); if none provided then some generic help for the ‘extended’ selection mode is provided if applicable

Do not access or set the value of this widget in trigger handlers that also update the widget. For generic models, those triggers are in session.triggers and are named ADD_MODELS, REMOVE_MODELS, MODEL_ID_CHANGED and MODEL_NAME_CHANGED

class ModelMenuButton(session, *, no_value_button_text='No model chosen', **kw)¶

Bases: ItemMenuButton

Maintain a popup menu of models

Keep menu up to date as models are opened and closed while keeping the selected item(s) the same

‘special_items’ is a list of special additional menu items whose str() reprs will be added to the menu.

‘autoselect’ controls what happens when nothing would be selected. The possible values (which are class variables) are:

AUTOSELECT_SINGLE: if there is only one item in the menu, it will be selected

AUTOSELECT_NONE: select nothing

AUTOSELECT_FIRST: the first item in the menu will be selected

AUTOSELECT_FIRST_DISPLAYED: select the first item whose ‘display’ attribute is True; if there is none, the the first item

AUTOSELECT_LAST, AUTOSELECT_LAST_DISPLAYED: analogous to the _FIRST_ values, except the last item instead of the first.

Special items are ignored for purposes of autoselection. The default is AUTOSELECT_SINGLE.

‘no_value_button_text’ is the text shown on the menu button when no item is selected for whatever reason. In such cases, self.value will be None.

If ‘no_value_menu_text’ is not None, then there will be an additional entry in the menu with that text, and choosing that menu item is treated as setting self.value to None.

‘balloon_help’ is the balloon help to provide with the list (if any).

Do not access or set the value of this widget in trigger handlers that also update the widget. For generic models, those triggers are in session.triggers and are named ADD_MODELS, REMOVE_MODELS, MODEL_ID_CHANGED and MODEL_NAME_CHANGED

Mouse modes¶

mouse_modes: Mouse modes¶

Classes to create mouse modes and assign mouse buttons and modifier keys to specific modes.

class MouseEvent(event=None, modifiers=None, position=None, wheel_value=None)¶

Bases: object

Provides an interface to mouse event coordinates and modifier keys so that mouse modes do not directly depend on details of the window toolkit.

__init__(event=None, modifiers=None, position=None, wheel_value=None)¶: Experimental API .

alt_down()¶: Supported API . Does the mouse event have the alt key down.

ctrl_down()¶: Supported API . Does the mouse event have the shift key down.

position()¶: Supported API . Pair of floating point x,y pixel coordinates relative to upper-left corner of graphics window. These values can be fractional if pointer device gives subpixel resolution.

shift_down()¶: Supported API . Does the mouse event have the shift key down.

wheel_value()¶: Supported API . Number of clicks the mouse wheel was turned, signed float. One click is typically 15 degrees of wheel rotation.

class MouseMode(session)¶

Bases: object

Classes derived from MouseMode implement specific mouse modes providing methods mouse_down(), mouse_up(), mouse_motion(), wheel(), pause() that are called when mouse events occur. Which mouse button and modifier keys are detected by a mode is controlled by a different MauseModes class.

__init__(session)¶: Supported API .

double_click¶: Supported API . Whether the last mouse-down was actually a double_click. Can be used in the mouse-up event handler if different behavior needed after a double click. There is a mouse_double_click method for doing something on a double click (which happens on the second mouse down), so this boolean is only for mouse-up handlers that behave differently after single vs. double clicks.

enable()¶: Supported API . Called when mouse mode is enabled. Override if mode wants to know that it has been bound to a mouse button.

icon_file = None¶: Supported API . Image file name for an icon for this mouse mode to show in the mouse mode GUI panel. The icon file of this name needs to be in the mouse_modes tool icons subdirectory, should be PNG, square, and at least 64 pixels square. It will be rescaled as needed. A none value means no icon will be shown in the gui interface.

last_mouse_position¶: Experimental API . Last mouse position during a mouse drag.

mouse_double_click(event)¶: Supported API . Override this method to handle double clicks. Keep in mind that you will also receive the mouse_down and mouse_up events. If your mouse_up handler needs to behave differently depending on whether it is the second part of a double click, have it check the self.double_click boolean, and make sure to call this base method so that the boolean is set.

mouse_down(event)¶: Supported API . Override this method to handle mouse down events. Derived methods can call this base class method to set mouse_down_position and last_mouse_position and properly handle double clicks.

mouse_down_position¶: Experimental API . Pixel position (x,y) of mouse-down, sometimes useful to detect on mouse-up whether any mouse motion occured. Set to None after mouse up.

mouse_drag(event)¶: Supported API . Override this method to handle mouse drag events.

mouse_motion(event)¶: Supported API . Return the mouse motion in pixels (dx,dy) since the last mouse event.

mouse_up(event)¶: Supported API . Override this method to handle mouse down events. Derived methods can call this base class method to set mouse_down_position and last_mouse_position to None.

move_after_pause()¶: Supported API . Override this method to take action when the mouse moves after a hover. This allows for instance undisplaying a popup help balloon window.

name = 'mode name'¶: Supported API . Name of the mouse mode used with the mousemode command. Should be unique among all mouse modes.

pause(position)¶: Supported API . Override this method to take action when the mouse hovers for a time given by the MouseModes pause interval (default 0.5 seconds).

pixel_size(center=None, min_scene_frac=1e-05)¶: Supported API . Report the pixel size in scene units at the center of rotation. Clamp the value to be at least min_scene_fraction times the width of the displayed models.

touchpad_four_finger_trans(event)¶: Supported API . Override this method to take action when a four-finger swiping motion is used on a multitouch touchpad. The move parameter is available as event.three_finger_trans and is a tuple of two floats: (delta_x, delta_y) representing the distance moved on the touchpad as a fraction of its width.

touchpad_three_finger_trans(event)¶: Supported API . Override this method to take action when a three-finger swiping motion is used on a multitouch touchpad. The move parameter is available as event.three_finger_trans and is a tuple of two floats: (delta_x, delta_y) representing the distance moved on the touchpad as a fraction of its width.

touchpad_two_finger_scale(event)¶: Supported API . Override this method to take action when a two-finger pinching motion is used on a multitouch touchpad. The scale parameter is available as event.two_finger_scale and is a float, where values larger than 1 indicate fingers moving apart and values less than 1 indicate fingers moving together.

touchpad_two_finger_trans(event)¶: Supported API . Override this method to take action when a two-finger swiping motion is used on a multitouch touchpad. This method should use either event.two_finger_trans (a tuple of two floats delta_x and delta_y) or event.wheel_value (an effective mouse wheel value synthesized from delta_y). delta_x and delta_y are distances expressed as fractions of the total width of the trackpad.

touchpad_two_finger_twist(event)¶: Supported API . Override this method to take action when a two-finger twisting motion is used on a multitouch touchpad. The angle parameter is available as event.two_finger_twist, and is a float representing the rotation angle in degrees.

property uses_wheel¶: Return True if derived class implements the wheel() method.

wheel(event)¶: Supported API . Override this method to handle mouse wheel events.

class MouseModes(session)¶

Bases: object

Keep the list of available mouse modes and also which mode is bound to each mouse button (left, middle, right), or mouse button and modifier key (alt, command, control shift). The mouse modes object for a session is session.ui.mouse_modes

__init__(session)¶: Experimental API .

add_mode(mode)¶: Supported API . Add a MouseMode instance to the list of available modes.

bind_mouse_mode(mouse_button=None, mouse_modifiers=[], mode=None, trackpad_action=None, trackpad_modifiers=[])¶

Experimental API . Bind a MouseMode to a mouse click and/or a multitouch trackpad action with optional modifier keys.

mouse_button is either None or one of (“left”, “middle”, “right”, “wheel”, or “pause”).

trackpad_action is either None or one of (“pinch”, “twist”, “two finger swipe”, “three finger swipe” or “four finger swipe”).

mouse_modifiers and trackpad_modifiers are each a list of 0 or more of (“alt”, “command”, “control” or “shift”).

mode is a MouseMode instance.

bind_standard_mouse_modes(buttons=('left', 'middle', 'right', 'wheel', 'pause'), trackpad=('two finger swipe', 'twist', 'pinch', 'three finger swipe', 'four finger swipe'))¶: Experimental API . Bind the standard mouse modes: left = rotate, ctrl-left = select, middle = translate, right = zoom, wheel = zoom, pause = identify object.

property bindings¶: List of MouseBinding instances.

mode(button='left', modifiers=[], exact=False)¶: Experimental API . Return the MouseMode associated with a specified button and modifiers, or None if no mode is bound.

property modes¶: List of MouseMode instances.

mouse_pause_tracking()¶: Experimental API . Called periodically to check for mouse pause and invoke pause mode. Typically this will be called by the redraw loop and is used to determine when a mouse pause occurs.

remove_binding(button=None, modifiers=[], trackpad_action=None, trackpad_modifiers=[])¶: Experimental API . Unbind the mouse button and modifier key combination. No mode will be associated with this button and modifier.

remove_mode(mode)¶: Experimental API . Remove a MouseMode instance from the list of available modes.

trackpad_mode(action, modifiers=[], exact=False)¶: Experimental API . Return the MouseMode associated with a specific multitouch action and modifiers, or None if no mode is bound.

mod_key_info(key_function)¶

Experimental API . Qt swaps control/meta on Mac, so centralize that knowledge here. The possible “key_functions” are: alt, control, command, and shift

Returns the Qt modifier bit (e.g. Qt.KeyboardModifier.AltModifier) and name of the actual key

Widgets that interoperate with Settings¶

OptionsPanel and CategorizedOptionsPanel are for interfaces that want to present a set of options that aren’t remembered in any way between different sessions. The corresponding Settings classes offer buttons to Save/Reset/Restore the option values to/from a Settings instance (found in chimerax.core.settings).

The Categorized classes organize the presented options into categories, which the user can switch between.

class CategorizedOptionsPanel(parent=None, *, category_sorting=True, option_sorting=True, category_scrolled={}, **kw)¶

Bases: QTabWidget

Supported API. CategorizedOptionsPanel is a container for single-use (not savable) Options sorted by category

add_option(category, option)¶: Supported API . Add option (instance of chimerax.ui.options.Option) to given category

add_tab(category, panel)¶

Supported API . Only used if a tab needs to present a custom interface.

The panel needs to offer a .options() method that returns its options.

class CategorizedSettingsPanel(parent=None, *, category_sorting=True, option_sorting=True, **kw)¶

Bases: SettingsPanelBase

Supported API. CategorizedSettingsPanel is a container for remember-able Options (i.e. Options that have Settings instances (found in chimerax.core.settings) specified via their ‘settings’ constructor arg) and that are presented in categories.

add_option(category, option)¶: Supported API . Add option (instance of chimerax.ui.options.Option) to given category

add_option_group(category, **kw)¶: Experimental API . Returns a container widget and an OptionsPanel; caller is responsible for creating a layout for the container widget and placing the OptionsPanel in it, along with any other desired widgets

add_tab(category, panel)¶: Supported API . Same as CategorizedOptionsPanel.add_tab(…)

class OptionsPanel(parent=None, *, sorting=True, scrolled=True, contents_margins=None, columns=1)¶

Bases: QWidget

Supported API. OptionsPanel is a container for single-use (not savable) Options

add_option(option)¶: Supported API . Add an option (instance of chimerax.ui.options.Option).

class SettingsPanel(parent=None, *, sorting=True, **kw)¶

Bases: SettingsPanelBase

Supported API. SettingsPanel is a container for remember-able Options that work in conjunction with Options that have Settings instances (found in chimerax.core.settings) specified via their ‘settings’ constructor arg.

add_option(option)¶: Supported API . Add an option (instance of chimerax.ui.options.Option).

add_option_group(**kw)¶: Experimental API . Returns a container widget and an OptionsPanel; caller is responsible for creating a layout for the container widget and placing the OptionsPanel in it, along with any other desired widgets

class SettingsPanelBase(parent, option_sorting, multicategory, *, category_sorting=None, buttons=True, help_cb=None, **kw)¶: Bases: QWidget

class BooleanOption(name, default, callback, *, balloon=None, attr_name=None, settings=None, auto_set_attr=True, **kw)¶

Bases: Option

Supported API. Option for true/false values

set_multiple()¶: Supported API . Indicate that the items the option covers have multiple different values

property value¶: Supported API. Get/set the option’s value; when set it should NOT invoke the callback

class ColorOption(name, default, callback, *, balloon=None, attr_name=None, settings=None, auto_set_attr=True, **kw)¶

Bases: RGBA8Option

Option for rgba colors

property value¶: Supported API. Get/set the option’s value; when set it should NOT invoke the callback

class EnumBase(name, default, callback, *, balloon=None, attr_name=None, settings=None, auto_set_attr=True, **kw)¶

Bases: Option

set_multiple()¶: Supported API . Indicate that the items the option covers have multiple different values

property value¶: Supported API. Get/set the option’s value; when set it should NOT invoke the callback

class EnumOption(*args, values=None, **kw)¶

Bases: EnumBase

Supported API. Option for enumerated values. The given values will be displayed in the interface and returned by the ‘value’ attribute. If you want to display different text in the interface than the literal value, use the SymbolicEnumOption. You can specify values either by subclassing and overriding the ‘values’ class attribute, or by supplying the ‘values’ keyword to the constructor.

class FileOption(name, default, callback, *, balloon=None, attr_name=None, settings=None, auto_set_attr=True, **kw)¶

Bases: Option

base class for specifying a file

set_multiple()¶: Supported API . Indicate that the items the option covers have multiple different values

property value¶: Supported API. Get/set the option’s value; when set it should NOT invoke the callback

class FloatEnumOption(name, default, callback, *, balloon=None, attr_name=None, settings=None, auto_set_attr=True, **kw)¶

Bases: EnumBase

Supported API. Option for a floating-point number and an enum (as a 2-tuple), for something such as size and units

set_multiple()¶: Supported API . Indicate that the items the option covers have multiple different values

property value¶: Supported API. Get/set the option’s value; when set it should NOT invoke the callback

class FloatOption(name, default, callback, *, balloon=None, attr_name=None, settings=None, auto_set_attr=True, **kw)¶

Bases: NumericOption

Supported API. Option for floating-point values. Constructor takes option min/max keywords to specify lower/upper bound values. Besides being numeric values, those keyords can also be ‘positive’ or ‘negative’ respectively, in which case the allowed value can be arbitrarily close to zero but cannot be equal to zero.

‘decimal_places’ indicates allowable number of digits after the decimal point (default: 3). Values with more digits will be rounded. If the widget provides a means to increment the value (e.g. up/down arrow) then ‘step’ is how much the value will be incremented (default: 10x the smallest value implied by ‘decimal_places’).

if ‘as_slider’ is True, then a slider widget will be used instead of an entry widget. If using a slider, it is recommended to set ‘min’ and ‘max’ values; otherwise the widget will cover a very large numeric range. When using a slider, you can specify ‘continuous_callback’ as True/False (default False) to control whether the option’s callback happens as the slider is dragged, or just when the slider is released.

Supports ‘left_text’ and ‘right_text’ keywords for putting text before and after the entry widget on the right side of the form, or below left/right of the slider if using a slider.

set_multiple()¶: Supported API . Indicate that the items the option covers have multiple different values

show_text(text)¶: Experimental API . So that option can show text such as ‘N/A’ and number ranges

property value¶: Supported API. Get/set the option’s value; when set it should NOT invoke the callback

class FontOption(*args, **kw)¶: Bases: EnumOption

class HostPortOption(name, default, callback, *, balloon=None, attr_name=None, settings=None, auto_set_attr=True, **kw)¶

Bases: StringIntOption

Supported API. Option for a host name or address and a TCP port number (as a 2-tuple)

class InputFileOption(name, default, callback, *, balloon=None, attr_name=None, settings=None, auto_set_attr=True, **kw)¶: Bases: FileOption

class InputFolderOption(name, default, callback, *, balloon=None, attr_name=None, settings=None, auto_set_attr=True, **kw)¶

Bases: Option

Option for specifying an existing folder for input

set_multiple()¶: Supported API . Indicate that the items the option covers have multiple different values

property value¶: Supported API. Get/set the option’s value; when set it should NOT invoke the callback

class IntOption(name, default, callback, *, balloon=None, attr_name=None, settings=None, auto_set_attr=True, **kw)¶

Bases: NumericOption

Supported API. Option for integer values. Constructor takes option min/max keywords to specify lower/upper bound values.

Supports ‘left_text’ and ‘right_text’ keywords for putting text before and after the entry widget on the right side of the form

set_multiple()¶: Supported API . Indicate that the items the option covers have multiple different values

show_text(text)¶: Experimental API . So that option can show text such as ‘N/A’ and number ranges

property value¶: Supported API. Get/set the option’s value; when set it should NOT invoke the callback

class NumericOption(name, default, callback, *, balloon=None, attr_name=None, settings=None, auto_set_attr=True, **kw)¶

Bases: Option

base class for options that display single numbers (e.g. IntOption, FloatOption)

display_for_items(items)¶: Supported API . Use the option’s ‘attr_name’ attribute to survey the given items for their value or values for that attribute and display the value or values in the option. The ‘items’ can be a chimerax.atomic.Collection or a normal Python sequence. If a Collection, the “plural form” of attr_name will be used to check the Collection. Ranges will be shown appropriately.

abstract show_text(text)¶: Experimental API . So that option can show text such as ‘N/A’ and number ranges

class Option(name, default, callback, *, balloon=None, attr_name=None, settings=None, auto_set_attr=True, **kw)¶

Bases: object

Supported API. Base class (and common API) for all options

Set ‘default’ to None if you want values in a settings menu to survive closing a tool.

display_for_items(items)¶: Supported API . Use the option’s ‘attr_name’ attribute to survey the given items for their value or values for that attribute and display the value or values in the option. The ‘items’ can be a chimerax.atomic.Collection or a normal Python sequence. If a Collection, the “plural form” of attr_name will be used to check the Collection.

property enabled¶: Supported API. Enable/disable the option

get_attribute()¶: Supported API . Get the attribute associated with this option (‘attr_name’ in constructor) from the option’s settings attribute

make_callback()¶: Supported API . Called (usually by GUI) to propagate changes back to program

set_attribute()¶: Supported API . Set the attribute associated with this option (‘attr_name’ in constructor) from the option’s settings attribute

abstract set_multiple()¶: Supported API . Indicate that the items the option covers have multiple different values

abstract property value¶: Supported API. Get/set the option’s value; when set it should NOT invoke the callback

values_for_items(items)¶: Supported API . Convenience function to get values for the ‘attr_name’ attribute from the given items. Used by display_for_items() and by subclasses overriding display_for_items().

class OptionalRGBA8PairOption(name, default, callback, *, balloon=None, attr_name=None, settings=None, auto_set_attr=True, **kw)¶

Bases: Option

Like OptionalRGBA8Option, but two checkboxes/colors

Supports ‘initial_colors’ constructor arg (2-tuple of colors) for initializing the color buttons even when the starting value of the option is (None, None) (checkboxes will be unchecked)

set_multiple()¶: Supported API . Indicate that the items the option covers have multiple different values

set_value(value)¶: Experimental API . 2-tuple. Accepts a wide variety of values, not just rgba

property value¶: Supported API. Get/set the option’s value; when set it should NOT invoke the callback

class OptionalRGBAOption(name, default, callback, *, balloon=None, attr_name=None, settings=None, auto_set_attr=True, **kw)¶

Bases: OptionalRGBA8Option

Option for floating-point (0-1) rgba colors, with possibility of None.

Supports ‘initial_color’ constructor arg for initializing the color button even when the starting value of the option is None (checkbox will be unchecked)

property value¶: Supported API. Get/set the option’s value; when set it should NOT invoke the callback

class OptionalRGBAPairOption(name, default, callback, *, balloon=None, attr_name=None, settings=None, auto_set_attr=True, **kw)¶

Bases: OptionalRGBA8PairOption

Like OptionalRGBAOption, but two checkboxes/colors

Supports ‘initial_colors’ constructor arg (2-tuple of colors) for initializing the color buttons even when the starting value of the option is (None, None) (checkboxes will be unchecked)

property value¶: Supported API. Get/set the option’s value; when set it should NOT invoke the callback

class OutputFileOption(name, default, callback, *, balloon=None, attr_name=None, settings=None, auto_set_attr=True, **kw)¶: Bases: FileOption

OutputFolderOption¶: alias of InputFolderOption

class PasswordOption(name, default, callback, *, balloon=None, attr_name=None, settings=None, auto_set_attr=True, **kw)¶

Bases: StringOption

Supported API. Option for entering a password

class PhysicalSizeOption(name, default, callback, *, balloon=None, attr_name=None, settings=None, auto_set_attr=True, **kw)¶: Bases: FloatEnumOption

class RGBA8Option(name, default, callback, *, balloon=None, attr_name=None, settings=None, auto_set_attr=True, **kw)¶

Bases: Option

Option for rgba colors, returns 8-bit (0-255) rgba values

set_multiple()¶: Supported API . Indicate that the items the option covers have multiple different values

set_value(value)¶: Experimental API . Accepts a wide variety of values, not just rgba

property value¶: Supported API. Get/set the option’s value; when set it should NOT invoke the callback

class RGBAOption(name, default, callback, *, balloon=None, attr_name=None, settings=None, auto_set_attr=True, **kw)¶

Bases: RGBA8Option

Option for rgba colors, returns floating-point (0-1) rgba values

property value¶: Supported API. Get/set the option’s value; when set it should NOT invoke the callback

class StringIntOption(name, default, callback, *, balloon=None, attr_name=None, settings=None, auto_set_attr=True, **kw)¶

Bases: Option

Supported API. Option for a string and an int (as a 2-tuple), for something such as host and port

set_multiple()¶: Supported API . Indicate that the items the option covers have multiple different values

property value¶: Supported API. Get/set the option’s value; when set it should NOT invoke the callback

class StringOption(name, default, callback, *, balloon=None, attr_name=None, settings=None, auto_set_attr=True, **kw)¶

Bases: Option

Supported API. Option for text strings

set_multiple()¶: Supported API . Indicate that the items the option covers have multiple different values

property value¶: Supported API. Get/set the option’s value; when set it should NOT invoke the callback

class StringsOption(name, default, callback, *, balloon=None, attr_name=None, settings=None, auto_set_attr=True, **kw)¶

Bases: Option

Supported API. Option for list of plain text strings There is no builtin way for the user to indicate that they are done editing the text, so no callback will occur. If such an indication is needed, another widget would have to provide it.

set_multiple()¶: Supported API . Indicate that the items the option covers have multiple different values

property value¶: Supported API. Get/set the option’s value; when set it should NOT invoke the callback

class SymbolicEnumOption(*args, labels=None, **kw)¶

Bases: EnumOption

Supported API. Option for enumerated values with symbolic names The given values will be returned by the ‘value’ attribute and the corresponding symbolic names will be displayed in the user interface. If your values and symbolic names are the same, just use EnumOption. You can specify values and symbolic names either by subclassing and overriding the ‘values’ and ‘labels’ class attributes, or by supplying the ‘values’ and ‘labels’ keywords to the constructor.

Table widget for Python objects¶

class ItemTable(*, auto_multiline_headers=True, column_control_info=None, allow_user_sorting=True, settings_attr=None, parent=None, session=None, color_column_width=32)¶

Bases: QTableView

Typical usage is to add_column()s, set the ‘data’ attribute, and then launch() (see doc strings for those). If you saved the table’s state (via session_info() call), then provide the ‘session_data’ keyword to the launch() call with the saved state as the value.

Do not do anything Qt related with the ItemTable until launch() has been called, because that’s when the underlying QTableView gets initialized.

ItemTable provides a selection_changed signal that delivers two lists to the connected function: newly selected items and newly deselected items. To find all currently selected items, use the tables ‘selected’ property.

add_column(title, data_fetch, *, format='%s', data_set=None, display=None, title_display=True, justification='center', balloon=None, font=None, refresh=True, color=None, header_justification=None, icon=None, editable=False, validator=None, sort_func=None, show_tooltips=False, data_color=None, is_html=False)¶

Experimental API . Add a column who’s header text is ‘title’. It is allowable to add a column with the same title multiple times. The duplicative additions will be ignored.

‘data_fetch’ is how to fetch the value to display from a data item. If it’s a string, then it is assumed to be an attribute (or subattribute, e.g. “color.rgba”) of the data item (see set_data()). Otherwise it is a function which, when applied to a data item, returns the value that should be displayed in the corresponding cell (but see ‘format’).

If ‘data_set’ is None, then changing a table value (e.g. checkbutton, color button) will attempt to set the attribute specified by ‘data_fetch’ (if it is an attribute that is, otherwise an error). But you often want to issue a command equivalent instead or need some fancier behavior. For such cases, ‘data_set’ can be specified and can either be a string or a callable. If it’s a string, then that string will have its .format() method called with keyword ‘item’ being the data item and ‘value’ being the value it is being set to, and the result should be a ChimeraX command string. Hint: to get the item’s atom spec into the command string, use the format “{item.atomspec}”. If ‘data_set’ is a callable, it will be called with (item. value) arguments. Note that if ‘data_set’ is a string, then the ‘session’ keyword parameter must be given during table construction.

‘format’ describes how to show that data item’s value. If ‘format’ is COL_FORMAT_BOOLEAN, use a check box. If it is COL_FORMAT_TRANSPARENT_COLOR or COL_FORMAT_OPAQUE_COLOR then use a color button with the appropriate transparency option. Otherwise it should ether be a callable or a text string. If it’s a callable, the callable will be invoked with the value returned by ‘data_fetch’ and should return a textual representation of the value. If it’s a text string, it should be a format string such that (format % data_fetch(data_item)) returns the text to display in the cell.

‘display’ is whether the column should be initially displayed or not. If None, then any user preferences will be used to choose the value, and if there are none then the column will default to being displayed.

‘title_display’ controls whether the title of the column will be displayed as a header.

‘justification’ controls how data items are aligned in the cells. It can be “left”, “right”, “center”, or “decimal”. If “decimal” then a fixed-width font will be employed with right justification. This means you should provide a ‘format’ with a fixed number of decimal places, possibly with trailing spaces to mitigate the right justification.

‘balloon’ is explanatory text that will be shown in a tooltip if the user hovers the mouse over the column header.

‘font’ is the font employed to display column data items, and should be a QFont instance. If not provided, it defaults to a proportional font unless ‘jusification’ is “decimal”, in which case a fixed-width font will be used.

‘refresh’ is whether to refresh the table contents once the column is added. It defaults to True, but if you are adding multiple columns to an existing large table, you might want to set it to False except for the last added column.

‘color’ is the _foreground_ (text) color of the column header. Should be a chimerax.core.Color instance or a value that can be used as the Color constructor first argument.

‘header_justification’ is the text justification of the header text. Same values as ‘justification’ except no “decimal”. Default to the same justification as ‘justification’ (but “right” if ‘justification’ is “decimal”).

If ‘icon’ is specified, it will be shown in place of the column’s title. If should be either a QIcon or QPixmap instance, or a string that can be used as the argument of a chimerax.ui.icons.get_qt_icon() call.

For text cell values to be editable by the user, set ‘editable’ to True. If the text value needs verfication before it is used, supply a function as ‘validator’ that takes the new text value as an argument and returns True if it is valid and False otherwise. Supplying a ‘validator’ value implies that ‘editable’ is True (and therefore ‘editable’ does not need to be specified separately).

If the column should sort on something other than numeric values or alphabetized text, you can supply a ‘sort_func’ function which takes two items as arguments and returns whether the first item is “less than” the second item based on those items’ values in this column.

If ‘show_tooltips’ is True, then hovering over cells in that column will show the cell contents in a tooltip. Useful in cases where cell values might exceed the width of the column.

‘data_color’, if not None, is a function that returns the _foreground_ (text) color of a row entry. The function take the row’s data item as its only argument. The returned value should be a chimerax.core.Color instance or a value that can be used as the Color constructor first argument.

Set ‘is_html’ to True if you need HTML formatting. This uses a QLabel for each cell in the column so is somewhat higher overhead, so only use it when actually needed if possible.

destroy(self, destroyWindow: bool = True, destroySubWindows: bool = True)¶: Experimental API .

scroll_to(datum)¶: Experimental API . Scroll the table to ensure that the given data item is visible

sizeHintForColumn(self, column: int) → int¶: Experimental API .

class NumSortingProxyModel¶

Bases: QSortFilterProxyModel

lessThan(self, left: QModelIndex, right: QModelIndex) → bool¶: Experimental API .

class QCxTableModel(item_table, **kw)¶

Bases: QAbstractTableModel

columnCount(self, parent: QModelIndex = QModelIndex()) → int¶: Experimental API .

data(self, index: QModelIndex, role: int = Qt.DisplayRole) → Any¶: Experimental API .

flags(self, index: QModelIndex) → Qt.ItemFlag¶: Experimental API .

headerData(self, section: int, orientation: Qt.Orientation, role: int = Qt.DisplayRole) → Any¶: Experimental API .

rowCount(self, parent: QModelIndex = QModelIndex()) → int¶: Experimental API .

setData(self, index: QModelIndex, value: Any, role: int = Qt.EditRole) → bool¶: Experimental API .

HTML-based tools/widgets¶

class HtmlToolInstance(session, tool_name, size_hint=None, show_http_in_help=True, log_errors=False)¶

Bases: ToolInstance

Base class for creating a ChimeraX tool using HTML as its main user interface. HtmlToolInstance takes care of creating the ChimeraX tool instance, main window, and HTML widget. Derived classes can also define methods that are called when hyperlinks in the HTML widget are clicked, or when ChimeraX models are added or removed.

The tool_window instance attribute refers to the MainToolWindow instance for the tool.

The html_view instance attribute refers to the HtmlView instance for managing HTML content and link actions.

To facilitate customizing the HTML view, if the derived class has an attribute CUSTOM_SCHEME and a method handle_scheme(), then the HtmlView instance will be configured to support the custom scheme.

If the HtmlToolInstance has a method update_models(), then it will be called as a handler to model addition and removal events. update_models() should take three arguments: self, trigger_name and trigger_data. trigger_name is a string and trigger_data is a list of models added or removed.

Parameters:

session (a Session instance) – The session in which the tool is created.
tool_name (a string) – The name of the tool being created.
size_hint (a 2-tuple of integers, or ''None'') – The suggested initial widget size in pixels.

delete()¶: Supported API . Delete this HtmlToolInstance.

ChimeraXHtmlView provides a HTML window that understands ChimeraX-specific schemes. It is built on top of HtmlView, which provides scheme support.

class ChimeraXHtmlView(session, parent, *args, schemes=None, interceptor=None, download=None, handlers=None, profile=None, **kw)¶

Bases: HtmlView

HTML window with ChimeraX-specific scheme support.

The schemes are ‘cxcmd’ and ‘help’.

class HtmlView(*args, size_hint=None, schemes=None, interceptor=None, download=None, handlers=None, profile=None, profile_is_private=None, tool_window=None, log_errors=False, **kw)¶

Bases: QWebEngineView

HtmlView is a derived class from Qt.QtWebEngineWidgets.QWebEngineView that simplifies using custom schemes and intercepting navigation requests.

HtmlView may be instantiated just like QWebEngineView, with additional keyword arguments:

Parameters:

size_hint (a QSize compatible value, typically (width, height),) – specifying the preferred initial size for the view. Default None.
interceptor (a callback function taking one argument, an instance) – of QWebEngineUrlRequestInfo, invoked to handle navigation requests. Default None.
schemes (an iterable of custom schemes that will be used in the) – view. If schemes is specified, then interceptor will be called when custom URLs are clicked. Default None.
download (a callback function taking one argument, an instance) – of QWebEngineDownloadItem, invoked when download is requested. Default None.
profile (the QWebEngineProfile to use. If it is given, then) – ‘interceptor’, ‘schemes’, and ‘download’ parameters are ignored because they are assumed to be already set in the profile. Default None.
profile_is_private (True if profile should be deleted when widget is) – closed. Default True if profile is None.
tool_window (if specified, ChimeraX context menu is displayed instead) – of default context menu. Default None.
log_errors (whether to log JavaScript error/warning/info messages) – to ChimeraX console. Default False.

profile¶

Type:: the QWebEngineProfile used

deleteLater()¶: Supported API . Schedule HtmlView instance for deletion at a safe time.

runJavaScript(script, *args)¶

Supported API . Run JavaScript using currently displayed HTML page.

Parameters:

script (a string containing URL to new content.)
args (additional arguments supported by) – Qt.QtWebEngineWidgets.QWebEnginePage.runJavaScript().

setHtml(html, url=None)¶

Supported API . Replace widget content.

Parameters:

html (a string containing new HTML content.)
url (a string containing URL corresponding to content.)

setUrl(url)¶

Supported API . Replace widget content.

Parameters:: url (a string containing URL to new content.)

sizeHint()¶: Supported API . Returns size hint as a :py:class:Qt.QtCore.QSize instance.

chimerax_intercept(request_info, *args, session=None, view=None)¶

Experimental API . Interceptor for ChimeraX-specific schemes

Parameters:

request_info (QWebEngineRequestInfo)
session (a Session instance)
view (a QWebEngineView instance or a function that returns the instance)

create_chimerax_profile(parent, schemes=None, interceptor=None, download=None, handlers=None, storage_name=None)¶

Experimental API . Create QWebEngineProfile with ChimeraX-specific scheme support

See create_profile() for argument types. The interceptor should incorporate the chimerax_intercept() functionality.

create_profile(parent, schemes=None, interceptor=None, download=None, handlers=None, storage_name=None)¶

Experimental API . Create a QWebEngineProfile. The profile provides shared access to the files in the html directory in the chimerax.ui package by rewriting links to /chimerax/ui/html to that directory.

Parameters:

interceptor (a callback function taking one argument, an instance) – of QWebEngineUrlRequestInfo, invoked to handle navigation requests. Default None.
schemes (an iterable of custom schemes that will be used in the) – view. If schemes is specified, then interceptor will be called when custom URLs are clicked. Default None.
download (a callback function taking one argument, an instance) – of QWebEngineDownloadItem, invoked when download is requested. Default None.
handlers (a dictionary of scheme handlers. Default None.)
storage_name (a string giving a unique name for persistent cookie storage.) – if this is None then cookies are only stored in memory.

delete_profile(profile)¶: Experimental API . Cleanup profiles created by create_profile

set_user_agent(profile)¶: Experimental API . Set profile’s user agent

Font-size convenience function¶

The ‘ui’ command¶

ui_autostart(session, do_start, tool_name)¶: Experimental API . Control whether a tool is launched at ChimeraX startup

ui_dockable(session, dockable, tool_name)¶: Experimental API . Control whether a tool’s windows are dockable

ui_favorite(session, make_favorite, tool_name)¶: Experimental API . Control whether a tool is launched at ChimeraX startup

ui_fullscreen(session, show)¶: Experimental API . Show fullscreen (no titlebar) or normal mode.

ui_hide_floating(session, hide_tools)¶: Experimental API . Temporarily show/hide floating tools.

ui_menubar(session, show)¶: Experimental API . Show or hide the top of window menubar.

ui_statusbar(session, show)¶: Experimental API . Show or hide the statusbar.

ui_tool_hide(session, tool_name, _show=True)¶

Experimental API . Hide tool.

Parameters:: tool_name (string)

ui_tool_show(session, tool_name, _show=True)¶

Experimental API . Show a tool, or start one if none is running.

Parameters:: tool_name (string)

ui_windowfill(session, fill)¶: Experimental API . Temporarily show/hide docked tools.

gui: Main ChimeraX graphical user interface¶