gui: Main Chimera 2 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, size=None)

Bases: chimera.core.ui.gui.ToolWindow

Child (i.e. additional) tool window

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

class MainToolWindow(tool_instance, size=None)

Bases: chimera.core.ui.gui.ToolWindow

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.

size : 2-tuple of ints, optional

Requested size for the tool window, width by height, in pixels. If not specified, uses the window system default.

create_child_window(title, size=None, window_class=None)

Make additional tool window

Parameters:

title : str

Text shown in the window’s title bar.

size

Same as for MainToolWindow constructor.

window_class : ChildToolWindow subclass, optional

Class to instantiate to create the child window. Only needed if you want to override methods/attributes in order to change behavior. Defaults to ChildToolWindow.

class ToolWindow(tool_instance, title, size)

Bases: object

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.

cleanup()

Perform tool-specific cleanup

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

close_destroys = True

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 destroyedRolls

destroy()

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)

Add items to this tool window’s context menu

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

manage(placement, fixed_size=False)

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 None). If placement is None, the tool will be detached from the main window.

placements = ['right', 'left', 'top', 'bottom']

Where the window is placed in the main interface

shown

Whether this window is hidden or shown

shown_changed(shown)

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)

class UI(session)

Bases: wx.core.App

Main Chimera2 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)

‘undo’ of register_for_keystrokes(). Use the same argument.

forward_keystroke(event)

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

register_for_keystrokes(sink)

‘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.

thread_safe(func, *args, **kw)

Call function ‘func’ in a thread-safe manner