Module maestro

Returns: str

The parent of the current profile (Maestro, Elements, etc)

@param dismiss_cb is a callable that will be called when another 'Application' panel is displayed and should dismiss the existing panel.

This function does a couple of things. One is that it will dismiss any currently displayed Application panels, secondly it will record the callable dismiss_cb so that if an Application panel is subsequently displayed from either Maestro or another Python script 'dismiss_cb' will be called to hide the current one. In this context an 'Application' panel is one that is expected to be mutually exclusive with other panels, for example one that might be expected to have exclusive control over the Workspace or just to avoid panel clutter as the user changes modeling tasks. These are typically, but not exclusively, accessed from the Applications menu in Maestro.

To de-register the callback, pass in None for dismiss_cb. This is useful when closing the panel, and it will not call the previously recorded dismiss_cb callback.

@param overwrite_prompt is a Boolean. If True, then the prompt will be displayed if the file exists. If False, then no prompt is given and the file is simply overwritten. This only stays in effect for the next call to maestro.command(). After that, whether the command succeeded or not and whether or not entryexport was actually invoked as part of the commands, prompting is re-enabled.

Issues a command from a Python script to be executed by Maestro. See the Maestro Command Reference for available commands.

If the command execution fails, then a MaestroCommand exception is raised.

There are three ways to call this routine:

i) Pass a single string as an argument which simply executes the string as is.

or

ii) Pass a multi-line string (triple quoted) where each line contains a Maestro command which is executed as is.

or

iii) Allow this routine to assemble the arguments into a command string for you. If you choose this option, then the arguments must be in the following order: keyword, operand(s), option(s). See the Maestro Command Reference for details on keywords, operands and options.

Forces an immediate redraw of the main Maestro Workspace. All currently visible objects are redrawn. Unless the Workspace really needs to be redrawn immediately (i.e. while the script is running), the preferred method of redrawing the Workspace is to use redraw_request(). If some atoms have been changed in the main CT then changed_type can be used to indicate the nature of the change to the CT since the last draw. The value should be one of WORKSPACE_CHANGED_* values listed at the top of the file.

Requests the main Maestro Workspace be redrawn. This is the preferred method of redrawing the Workspace. If the Workspace is to be redrawn when the script finishes running, use this command to avoid multiple and unnecessary redrawing of the main Workspace. If some atoms have been changed in the main CT then changed_type can be used to indicate the nature of the change to the CT since the last draw. The value should be one of WORKSPACE_CHANGED_* values listed at the top of the file.

Forces Maestro to update markers for distances, labels, etc. This should be done after atoms are moved in the structure returned by workspace_get().

Forces a redraw of displayed surfaces (mostly for included project entries) to reflect any changes. This should be done after modifying entry surfaces directly, without the use of maestro commands. A separate maestro redraw_request is not needed.

Return a Structure object that contains all the atoms in the Maestro Workspace. Project table properties are not included.

For a description of basic concepts that clarify the relationship between the Workspace and Maestro Projects as well as when and how changes in one affect the other, please see the Basic Concepts section in the python tutorial. The Scripting with Python tutorial is part of the General documentation and can be accessed from within Maestro's Help facility from the Manuals Index.

By default the 'copy' parameter is True and a copy of the structure corresponding to the Maestro Workspace is returned. If you want to actually make changes to the structure in the Workspace then use maestro.workspace_set() to update the Maestro Workspace.

You can also use maestro.workspace_get(copy=False) to get a Structure object that corresponds to the actual Maestro workspace. This was the behavior in versions before the 2008 release but this approach is no longer recommended.

When using copy=False, any change to the Workspace structure by Maestro may render your retrieved Structure instance invalid and further use may cause a core dump. The safest thing to do is assume that your Structure is only valid until the next Maestro command completes.

Also, when using copy=False any call to workspace_set() will render your structure invalid.

Sets the main Workspace connection table to the given Structure object. Structure properties are ignored.

For a description of basic concepts that clarify the relationship between the Workspace and Maestro Projects as well as when and how changes in one affect the other, please see the Basic Concepts section in the python tutorial. The Scripting with Python tutorial is part of the General documentation and can be accessed from within Maestro's Help facility from the Manuals Index.

Setting regenerate_markers to True (default) will force Maestro to update markers for distances, labels, etc. and to apply any changes to the Workspace structure. It should be set to True in most circumstances.

Returns a structure of the included entry with properties. Raises RuntimeError if no entries are included or if more than one entry is included. Returned Structure is a copy of the included entry.

Returns a list of structure objects with properties for included entries. Will return an empty list if no entries are included. Returned structures are copies of the entry structures. If there are scratch entries in the Workspace, they will be returned last in the list.

Return a set of entry ids for all structures in the workspace (including scratch entry)

Returns: set of str

Set of entry ids

This returns whether a function has already been registered with a callback.

Parameters:

• callback_type (str) - What callback you're checking, these are the keys to the _callbacks dict.
• func (A function) - The function you're checked to see if it's registered

Returns: bool

Is the function registered already?

Register a function to be called when the Workspace is redrawn.
This is intended to support drawing of additional 3D graphics.

The Workspace is redrawn whenever a part of the drawing area is
exposed or resized, or when Maestro changes the contents of the
Workspace (different structures, markers, text, surfaces, etc.)

func: This argument is the client-supplied function to call.

A common way to do this is to have one function for creating the
graphical objects you wish to draw and another to do the actual drawing

Example:

 Calls from within Maestro would be like:

 pythonrun workspace_graphics_sphere_centroid.create_centroid
 pythonrun workspace_graphics_sphere_centroid.add

 where workspace_graphics_sphere_centroid is a .py file containing
 these two functions.  The first one creates the object, the second one
 registers the drawing function by telling the maestro module about itself:

 maestro.workspace_draw_function_add(my_draw_func)

 To remove it have an additional function in your .py, something like
 remove() which tells the maestro module to remove the named function
 from the list of callback functions:

 maestro.workspace_draw_function_remove(my_draw_func)

Remove the named function so it is no longer called when the Workspace is redrawn.

Removing a non-existent function will cause an error.

For an example see the docstring for workspace_draw_function_add()

Register a function to be called when the Workspace contents are changed in some way. The function registered should expect to receive a single string parameter - one of the following values which indicates what has changed for the workspace structure. You should check against the module-level constants that are provided. These start with WORKSPACE_CHANGED_. See top of module for more details.

This feature will usually be used in conjunction with a workspace drawing callback but it can be used for anytime a Python script needs to know that the contents of the workspace have changed.

Note that the state of the Project table is not defined during this callback if the callback was triggered by the inclusion or exclusion of an entry from the project. In other words you can't reliably check on the inclusion state of an entry during this callback. Also you shouldn't issue Maestro commands from the callback.

Remove the named function so it is no longer called when the Workspace is changed

Removing a non-existent function will cause an error.

Add points which will be rotated around the rotation_center as the user rotates the Workspace using the mouse.

Parameters:

• rotation_center (List of 3 floats) - The coordinates of the center of rotation.
• points - Coordinates that should be rotated around the center. @type points; List of 3-item lists.
• changed_cb (callable) - Function to be called as points are rotated. It will be called with a single argument: A list of new coordinates for all points: [[x0,y0,z0], [x1,y1,z1], ...]
• removed_cb (callable) - Function to be called when the rotation mode was exited.

Add points which will be translated as the user translates the Workspace
using the mouse.

@param points: Model coordinates that should be translated, in the form:
  [ [x0, y0, z0], [x1, y1, z1], [x2, y2, z2], ... ]
@type points; List of 3-item lists.

@param changed_cb: Function to be called as points are translated. It will
    be called with a single argument: A list of new coordinates for all
    points:
    [[x0,y0,z0], [x1,y1,z1], ...]
@type changed_cb: callable

@param removed_cb: Function to be called when the translation mode is
    exited.
@type removed_cb: callable

Register a function to be called when a job is available to be incorporated. The function should expect to be called with two parameters. The first is the job ID (a string). The second is a Boolean which indicates if this is just a test of whether the Python script is prepared to handle the incorporation of the job. If this parameter is true, then the callback should only test whether it has the ability to incorporate the job, but not to do the actual job incorporation. This is done to support a feature that allows maestro to get user approval to incorporate jobs even though they are not being monitored. If the second parameter is false, then the callback should attempt to incorporate the job, if it can.

If the function is either prepared to handle the incorporation or is actually going to handle it then it should return maestro.WILL_HANDLE_JOB. If it is not able to handle it at this time then it should return maestro.NOT_INCORPORATABLE. If it is not going to handle the incorporation it should return maestro.NOT_MY_JOB

Remove the named function so it is no longer called when the a job is available to be incorporated

Removing a non-existent function will cause an error.

Gets a handle to the currently open project. Note: this is the actual handle to the project and not a copy, so it should never be deleted from within a script. The handle can be operated on by mmproj_* interface routines, but there are higher-level interfaces available to perform many project operations and these are the preferred mechanisms for manipulating the Project Table data from a Python script.

Forces a redraw of the Project Table to reflect any changes. This function may be called at anytime in order to update the Project Table after new properties or entries have been added.

Synchronizes the Workspace with the project according to the users' synchronization preferences. Any changes in the Workspace will be saved in to the project. If the user has 'Automatic' set then this will be done silently. If they have 'Prompt' set then they will be prompted as to whether they want to synchronize. If 'Manual' then no synchronization will be done.

This function returns True if the synchronization took place, False if the user canceled it when prompted.

Give some processor time to Maestro, for it to process pending events.

Parameters:

• wait_for_more_events (bool) - When True, WaitForMoreEvents flag is passed to QCoreApplication::processEvents, thus waiting for events if no pending events are available. This is False by default, i.e. the function returns control immediately.

Returns the jobID of the most recently started job. This may be used with mmjob_* library routines (see the library reference documentation for further details). In practice this is seldom needed as wait_for_job() and get_current_job_status() are the preferred interfaces for controlling jobs running within Maestro.

Returns the status of the last job monitored
The status is one of the following:
          launched
          submitted
          started
          running
          paused
          exited
          unreachable
          stranded
          completed
          incorporated
          None
If we fail to get the job status, we return None

Requests that atom picks are sent to the function callback_func. This must be a callable which expects to take a single integer parameter: the atom number of the picked atom. This atom number is appropriate for the CT handle returned from get_main_ct(). When picks are no longer needed, the script should call stop_picking(). Note: it is possible for a script to have the ability to receive picks if a panel in Maestro is activated for picking (picks can only go to one place at any given time). Scripts which use picking_atom_start() may also want to consider the use of maestro.picking_loss_notify() so they can be aware when the user has moved to another pick mode and their panel is no longer receiving picks from the workspace.

Requests that bond picks are sent to the function callback_func. This must be a callable which expects to take a two integer parameters: the atom numbers around the picked bond. The first atom corresponds to the atom nearest the half-bond picked. These atom numbers are appropriate for the CT handle returned from get_main_ct(). When picks are no longer needed, the script should call picking_stop(). Note: it is possible for a script to have the ability to receive picks if a panel in Maestro is activated for picking (picks can only go to one place at any given time). Scripts which use picking_bond_start() may also want to consider the use of maestro.picking_loss_notify() so they can be aware when the user has moved to another pick mode and their panel is no longer receiving picks from the workspace.

Requests that picks no longer be sent to the callback function specified earlier with picking_atom_start(), picking_bond_start(), or picking_lasso_start(). This should be called whenever a script no longer needs to receive picks and must be called before a Tkinter-based interactive script terminates.

Requests that if atom picks are no longer being sent to the function registered by maestro.picking_atom_start(), maestro.picking_bond_start(), or maestro.picking_lasso_start(), the specifed function will be called. This must be a callable which takes no parameters. This function must re-registed each time you turn on picking via maestro.picking_atom_start(), maestro.picking_bond_start(), or maestro.picking_lasso_start().

Requests that atom picks are sent to the function callback_func.

Parameters:

• help_string - the text to be displayed in Maestro main window status bar, e.g., "Pick atom to delete".
• callback_func - the callable which expects to take an ASL expression, e.g., pick_atom_cb(self, asl). If a single atom is picked, the parameter 'asl' is something like "atom.num 15". If a lasso selection is done, the parameter 'asl' is something like "at.n 5-8,15-18,1". Atom numbers are appropriate for the CT handle returned from get_main_ct(), and they can be extracted by mmasl_parse_input() based on the CT handle and the ASL string. When picks are no longer needed, the script should call picking_stop(). Note: it is possible for a script to have the ability to receive picks if a panel in Maestro is activated for picking (picks can only go to one place at any given time). Scripts which use picking_lasso_start() may also want to consider the use of maestro.picking_loss_notify() so they can be aware when the user has moved to another pick mode and their panel is no longer receiving picks from the workspace.

Register a function that will be called each time a command is processed in Maestro.

This must be a callable which takes a single parameter - the text of the command processed.

Remove the named function so it is no longer called when a command is issued in Maestro

Removing a non-existent function will cause an error.

Register a function to be called when the user makes a right-click in the Workspace. Note this will override any normal Maestro right-mouse features such as the built-in right-mouse menu.

This must be a callable which takes three parameters, the x and y positions of the mouse when clicked and the atom number of any atom under the mouse (or an invalid index if there's no atom under the mouse). Use mm.mmct_valid_atom to determine if the index is valid.

Remove the named function so it is no longer called when a right-mouse click is done in Maestro.

Removing a non-existent function will cause an error.

Register a callback to be called when the level of detail in the Maestro Workspace changes. This is typically used for graphical representation like whether to show the bond orders.

The callback function takes no parameters.

Remove the callback so it is no longer called when the level of detail in the Workspace changes.

Removing a non-existent function will cause an error.

Register a function to be called when current project is about to be closed. This must be a callable which takes no parameters. If Python scripts want to cancel Maestro project closing operation, they should call Maestro function mae_project_close_cancel(). This function can be used for anytime a Python script needs to know that current project is about to be closed.

Remove the named function so it is no longer called when current project is about to be closed

Removing a non-existent function will cause an error.

Register a function to be called when current project is about to be renamed. This must be a callable which takes no parameters. This function can be used for anytime a Python script needs to know that current project is about to be renamed.

Remove the named function so it is no longer called when current project is about to be renamed.

Removing a non-existent function will cause an error.

Register a function to be called when current project is updated in some way. This might be because of changes in selection, inclusion or properties. The function must be a callable which takes no parameters.

Remove the named function so it is no longer called when current project is updated.

Removing a non-existent function will cause an error.

Forces to cancel the processing of closing current project. This function may be called at the end of callback function from project_close_callback_add(), if the script doesn't want to close current project. This might cause bad behavior if it's done unconditionally.

Register a function to be called when the bounding box for a fit to
screen operation is being performed. This is intended to take into
account python 3D graphics objects when fitting Maestro Workspace.

The Workspace fit to screen is required whenever new 3D graphics objects
are added, or when Maestro changes the contents of the
Workspace (different structures, markers, text, surfaces, etc.)

func: This argument is the client-supplied function to call.

A common way to do this is to have one function for creating the
graphical objects you wish to draw and another to do the actual drawing

Example:

 Calls from within Maestro would be like:

 pythonrun workspace_graphics_sphere_centroid.create_centroid
 pythonrun workspace_graphics_sphere_centroid.add

 where workspace_graphics_sphere_centroid is a .py file containing
 these two functions.  The first one creates the object, the second one
 registers the bounding box function by telling the maestro module
 about itself:

 maestro.workspace_bounding_box_function_add(my_bounding_box_func)

 To remove it have an additional function in your .py, something like
 remove() which tells the maestro module to remove the named function
 from the list of callback functions:

 maestro.workspace_bounding_box_function_remove(my_bounding_box_func)

Remove the named function so it is no longer called when the Workspace is fit to screen.

Removing a non-existent function will cause an error.

For an example see the docstring for workspace_bounding_box_function_add()

Adds a Python function to be called each time the workspace bounding box callback function is called. The Python function passes the bounding box of Python 3D graphics objects to Maestro.

Adds a Python function to be called each time the mouse rests over an atom in the Workspace. This function should expect to receive a single parameter: the number of the atom which the mouse is currently resting over (or an invalid index if none---see mm.mmct_valid_atom). To remove the callback use hover_callback_remove() but note that this cannot be done from within a the callback function itself - in other words the hover callback cannot self-terminate.

Removes a Python function from the list of functions to be called each time the mouse rests over an atom in the Workspace. This function must have been previously added with hover_callback_add(). Note that this function cannot be called from within the callback_func() itself, as this will cause Maestro to crash.

A python function that adds the given job launch info to the project's annotation. The job name is passed as one of the argument so that we can selectively log job launches if necessary.

Adds a Python function which is called periodically during Maestro's operation (about 20 times a second). When the periodic task is no longer required, it should be removed with periodic_callback_remove(). NOTE: periodic_callback_remove() cannot be called from the callback_func() itself.

Removes a Python function being called periodically during Maestro's operations. This function should have been previously added with periodic_callback_add(). NOTE: periodic_callback_remove() cannot be called from the callback_func() itself.

Returns an ASL expression corresponding to the currently selected atoms in the Workspace. If there are no selected atoms in the workspace then None is returned.

Returns a SMARTS pattern for the currently selected Workspace atoms.

Raises ValueError if no atoms are selected, if selection is not continuous, or if more than 50 atoms are selected.

Returns: str

SMARTS pattern that would match the selected atoms.

Gets the value of the option for the given command. If there is an error such as the command does not exist or the option does not exist, then empty string, "", is returned. Note that this function may return None if fetching the option fails or if there's a buffer overflow.

Gets the names of the items currently associated with the given command. For example if the command is 'set' then the nmaes of all the currently defined sets will be returned.

Gets the name of the currently selelected item associated with the given command. For example if the command is 'set' then it will be the name of the currently selected set. If no items are selected then None will be returned.

Draw text_to_draw string at position x, y, z in the 3D workspace.

This function replaces draw_string, using a graphics text object instead of a workspace drawing callback, but only draws a single line of text.

Parameters:

• text_to_draw (str) - String to render.
• x (float) - X coordinate (Angstroms)
• y (float) - Y coordinate (Angstroms)
• z (float) - Z coordinate (Angstroms)
• font_name (str) - Font to be used (one returned by get_font_names())
• r (float) - Red color component, range is 0.0 to 1.0
• g (float) - Green color component, range is 0.0 to 1.0
• b (float) - Blue color component, range is 0.0 to 1.0
• a (float) - Alpha color component, range is 0.0 to 1.0
• font_size (int) - Font pixel size
• is_bold (bool) - Whether to use bold font
• is_italic (bool) - Whether to use italic font

Returns: int

The handle of a Maestro text array object

Draw text_to_draw string at position x, y, z in the 3D workspace.

This function replaces draw_string, using a graphics text object instead of a workspace drawing callback, and supports multi-line text with embedded newlines.

Parameters:

• text_to_draw (str) - String to render.
• x (float) - X coordinate (Angstroms)
• y (float) - Y coordinate (Angstroms)
• z (float) - Z coordinate (Angstroms)
• font_name (str) - Font to be used (one returned by get_font_names())
• r (float) - Red color component, range is 0.0 to 1.0
• g (float) - Green color component, range is 0.0 to 1.0
• b (float) - Blue color component, range is 0.0 to 1.0
• a (float) - Alpha color component, range is 0.0 to 1.0
• font_size (int) - Font pixel size
• is_bold (bool) - Whether to use bold font
• is_italic (bool) - Whether to use italic font

Returns: int

The handle of a Maestro text2 object

Draw text_to_draw string at position x, y, z in the 3D workspace.

This function would normally only be used in a workspace drawing callback, and is deprecated in favor of create_multiline_text or create_single_line_text.

Parameters:

• text_to_draw (str) - String to render.
• x (float) - X coordinate (Angstroms)
• y (float) - Y coordinate (Angstroms)
• z (float) - Z coordinate (Angstroms)
• font_name (str) - Font to be used (one returned by get_font_names())
• r (float) - Red color component, range is 0.0 to 1.0
• g (float) - Green color component, range is 0.0 to 1.0
• b (float) - Blue color component, range is 0.0 to 1.0
• a (float) - Alpha color component, range is 0.0 to 1.0
• font_size (int) - Font pixel size
• is_bold (bool) - Whether to use bold font
• is_italic (bool) - Whether to use italic font

Draw a string (with optional html tags) at position x,y,z in the
3D workspace. Uses the default font.

@param text_to_draw: string to render.  Can contain some limited
                     html: <sub></sub> and <sup></sup> tags
                     for sub- and super-scripts, respectively.
                     Can also pass a non-formatted string (ie doesn't
                     require you have html tags in it)
@param x: double - X coordinate, Angstrom space
@param y: double - Y coordinate, Angstrom space
@param z: double - Z coordinate, Angstrom space
@param is_transparent: bool - when false will render a box around
                       the text in the background color.
                       When true, no box is rendered, i.e.
                       the background is transparent.
                       Default is true.
@param xoffset: float - X offset in pixels, from bottom left.
                        Default = 0.0.
@param yoffset: float - Y offset in pixels, from bottom left
                        Default = 0.0.
@param adjustments:  Set/list of which adjustments, if any, to apply.
                     Default is None meaning no centerin is done and
                     no offsets are applied.  Values which can
                     be placed into adjustments are:

                     LABEL_CENTER_HORIZONTAL
                     LABEL_CENTER_VERTICAL
                     LABEL_USER_OFFSETS

                     Centering, if any, is applied first.
                     Then user offsets, if any, are applied.

@param mode: LABEL_DRAW draws the label and returns bounding box
             LABEL_BOUNDING_BOX only returns the bounding box
             The default is LABEL_DRAW.

@param use_default_font: bool indicating whether to use the default
             font or let the caller of this routine set the font.
             If the latter, then the caller must use MM_Font.useFont()
             or similar to set the font or the text won't render.

@return:  Bounding box list (indices precede value here only for
          informational purposes - they're not part of the returned
          values):

          0:left, 1:right, 2:bottom, 3:top, 4:near, 5:far

          Or empty list if there was an error

This function would normally only be used in a workspace drawing callback.

Create a 2D atom marker.
@param atom is the atom number
@param r is the red color component, range is 0.0 to 1.0
@param g is the green color component, range is 0.0 to 1.0
@param b is the blue color component, range is 0.0 to 1.0
@param hr is the highlight red color component, range is 0.0 to 1.0
@param hg is the highlight green color component, range is 0.0 to 1.0
@param hb is the highlight blue color component, range is 0.0 to 1.0
@param highlight uses highlight color and line width or not,
       icon will drawn in highlight color
@param icon is one of the GRAPHICS_ICON_* values listed at the top
       of the file.
@param style is a style for atom markers, it's a value of:
    GRAPHICS_ATOM_MARKER_STYLE_STAR
    GRAPHICS_ATOM_MARKER_STYLE_GENERAL
@return The handle of the marker, on error this function returns -1.

Create a 2D atom pair marker.
@param atom1 is the first atom number
@param atom2 is the second atom number
@param r is the red color component, range is 0.0 to 1.0
@param g is the green color component, range is 0.0 to 1.0
@param b is the blue color component, range is 0.0 to 1.0
@param hr is the highlight red color component, range is 0.0 to 1.0
@param hg is the highlight green color component, range is 0.0 to 1.0
@param hb is the highlight blue color component, range is 0.0 to 1.0
@param highlight uses highlight color and line width or not,
       icon and text will drawn in highlight color
@param text draw text if it's not NULL, if it's drawn then icon is hidden
@param icon is one of the GRAPHICS_ICON_* values listed at the top
       of the file.
@return The handle of the marker, on error this function returns -1.

Create a 2D atom triple marker.
@param atom1 is the first atom number
@param atom2 is the second atom number
@param atom3 is the third atom number
@param r is the red color component, range is 0.0 to 1.0
@param g is the green color component, range is 0.0 to 1.0
@param b is the blue color component, range is 0.0 to 1.0
@param hr is the highlight red color component, range is 0.0 to 1.0
@param hg is the highlight green color component, range is 0.0 to 1.0
@param hb is the highlight blue color component, range is 0.0 to 1.0
@param highlight uses highlight color and line width or not,
       icon and text will drawn in highlight color
@param text draw text if it's not NULL, if it's drawn then icon is hidden
@param icon is one of the GRAPHICS_ICON_* values listed at the top
       of the file.
@return The handle of the marker, on error this function returns -1.

Create a 2D atom quad marker.
@param atom1 is the first atom number
@param atom2 is the second atom number
@param atom3 is the third atom number
@param atom4 is the fourth atom number
@param r is the red color component, range is 0.0 to 1.0
@param g is the green color component, range is 0.0 to 1.0
@param b is the blue color component, range is 0.0 to 1.0
@param hr is the highlight red color component, range is 0.0 to 1.0
@param hg is the highlight green color component, range is 0.0 to 1.0
@param hb is the highlight blue color component, range is 0.0 to 1.0
@param highlight uses highlight color and line width or not,
       icon and text will drawn in highlight color
@param text draw text if it's not NULL, if it's drawn then icon is hidden
@param icon is one of the GRAPHICS_ICON_* values listed at the top
       of the file.
@return The handle of the marker, on error this function returns -1.

Returns a path to a temporary directory which is likely to be writeable and will be removed when this Maestro session is finished. This would typically used when temporary files need to be created, for example if file conversion is required as part of a script workflow

Rebuild the scripts menu(includes entries for both Workflows & Knime menus). This will re-read the scriptsx.mnu file from the user and common areas and display the contents in the Scripts menu.

Write entries from the project to a file. The parameters to this
method are:

filename -      the name of the file which to write these entries to. The
                suffix determines the format of the file using the same
                rules as Structure.write()

which_entries - Which entries to write. 'All', 'Included' or 'Selected'

Htreatment -    If not None then hydrogens will be added to the structures
                before they are written to the file using the specified
                H-treatment.
                Allowed treatment names are:
                  All-atom with Osp3/Nsp3-Lp
                  All-atom with No-Lp
                  Csp3 United-atom with S-Lp
                  Csp3 United-atom with No-Lp
                  All-atom with S-Lp
                  C sp2/sp3 United-atom with No-Lp
                  C sp2/sp3, N,O,S United-atom with No-Lp

                The one you almost certainly want is 'All-Atom with No-Lp'


synchronize -   Boolean representing whether to first synchronize the
                Workspace with the project. It is recommended this be done.

append      -   Boolean indicating whether to append to the specified file
                or overwrite.

props       -   Boolean indicating whether CT-level properties should be
                written.

If synchronization was done and the Maestro user had 'Prompt' mode
active then they may choose to cancel the operation. If they cancel
then nothing will be written and this method will return False,
otherwise it returns True

Notifies Maestro that a new Tk toplevel has been created and should be displayed and share event processing with Maestro itself. Note: this is the preferred way to run a Tkinter script from within Maestro and should be called instead of using the Tkinter.MainLoop() function.

Notifies Maestro that a Tk toplevel previously registered via tk_toplevel_add() no longer needs to be displayed or have events passed to it. Note: this function does not actually hide the toplevel widget. The script should call destroy() on the widget after remove_tk_toplevel() in order to hide the widget.

Post the atom selection dialog. The user can make selections in that dialog and the resulting ASL string will be returned as a result of this function. If the user cancels then the empty string will be returned by this function. The description field is displayed in the upper section of the dialog to indicate to the user the purpose of displaying this dialog. The current_asl will be set in the dialog when it is first displayed and the user will be able to edit that in this dialog.

Post a Maestro warning dialog with an OK button. This displays the text specified in 'message' in the same dialog Maestro uses to display warnings/errors, ensuring a consistent look and feel.

Post a Maestro informational dialog with an OK button. This displays the text specified in 'message' in the same dialog Maestro uses for displaying information, ensuring a consistent look and feel.

Post a Maestro question dialog - the same dialog Maestro
uses for displaying questions, ensuring a consistent look and feel.

Arguments are:
  question:  Question text
  button1:   Defaults to OK, but you can pass in what you like
  button2:   Defaults to Cancel, but you can pass in what you like

Returns:
maestro.BUTTON1 or maestro.BUTTON2, depending on which button
was pressed.

Notify the current pick widget that it lost its picking rights. Note that this function will not stop the picking itself.

Return the full path for the specified directory.
If which_directory is valid but it cannot, it raises a StandardError.

@param which_directory specifies the directory to get back.
@param preferences_file_name only applies when PREFERENCES is specified.
       In the PREFERENCES case if preferences_file_name is not specified,
       then just the absolute path to the preferences directory is
       returned.  This is the default.
       If preferences_file_name is specified, then return a string which is
       the preferences dir + directory separator + preferences_file_name.

Valid values for which_directory are defined at the top of this
module and are:

PREFERENCES         - Maestro preferences (for this version of Maestro)
TEMPORARY_DATA      - Temporary data directory
TEMPORARY_PROJECTS  - Directory where temporary (scratch) projects are put

If an invalid which_directory is specified, then a ValueError is thrown.

Returns a list of 16 floats representing the current view matrix. Note that the final column of the matrix is always 0.0 as this doesn't actually include the translation - for that see workspace_get_translation()

Also note that this matrix is returned in OpenGL order meaning it is column major notation.

Returns a list of 16 floats representing the current inverse view matrix. Note that the final column of the matrix is always 0.0 as this doesn't actually include the translation - for that see workspace_get_translation()

Returns a list of 16 floats representing the current inverse view matrix with no center. Note that the final column of the matrix is always 0.0 as this doesn't actually include the translation - for that see workspace_get_translation()

Return a tuple of width, height, scale

width:  width of the Workspace drawing area in pixels
height: height of the Workspace drawing area in pixels
scale:  ratio of window to world space.  The ratio
        is calculated for the width and for the height. The
        the smaller of these is returned (as this is what Maestro uses).

Set the polyhedron style to either LINE or FILL

Parameters:

• polyhedron - A handle to a Maestro polyhedron, returned from create_polyhedron()
• style (Choice, FILL or LINE) - Whether to fill the polyhedron in or to leave it as lines connecting vertices.

Set the coordinates for the given handle. Used for cylinders and cones.

Set the other coordinates for the given handle. Used for cylinders and cones.

Set the picking category for the given handle. pick_category should be a string containing the category to pick (e.g. <script name>_spheres)

Starting picking items in the picking category (e.g. <script name>_spheres)

Sets a command to add to the project-open command script when the project is closed, or when a saved project scene is re-applied. @param name is typically the name of the invoking script @param command is a single Maestro command

Appends the given command to the set of commands to add to the project-open command script when the project is closed or project scene is re-applied. @param name is typically the name of the invoking script @param command is a single Maestro command

Deletes all of the project commands associated with the given name. @param name is typically the name of the invoking script

Returns the maestro top level window from the list of available top level windows in the maestro application. The exact window returned depends on whether docking is enabled or not.

@type w: QWidget
@param w: Widget for which we need to set the docking configuration

@type dockable:  bool
@param dockable: Whether or not this widget is dockable

@type dock_area:  Qt.QFlags
@param dock_area: Area where the widget is to be docked (if
                  it is dockable)

This routine takes the specified widget and configures the
widget docking settings based on Maestro's preferences and
whether the widget itself is dockable.

Raises the Maesto main window to the top of the parent widget's stack This function is used mainly by the python scripts which operates directly in Maestro workspace, so that maestro mainwindow is visible and stays on the top of the widget stack

At present, this function is uncallable. Fix it, define getMaestroTopLevelWindow and remove the first line of the function

Show the Docking Panels window. There can be cases where we've added widgets to this panel, but it isn't visible and we want it to be visible.

Try to send an email.

Parameters:

• from_addr (str) - The From Email address
• to_addr (str) - The address to which we are sending
• server (str) - SMTP server. Only supports SMTP.
• port (int) - Port to which we will attach
• security (str) - What type of security if any. Valid values are: none, starttls, ssltls.
• message (str) - Body of the message to send.
• passwd (str) - Password. If blank, then assumes no login is needed.
• debug (bool

  @return nothing

  ) - If True, debugging is printed.

Access the color associated with a particular job status in the job monitor panel.

Parameters:

• job_status (str

  @return the color associated with this job_status as a hex triplet #XXXXXX

  ) - The job status as used in job records.

Get a list of current job names, job ids and job statuses known to Maestro.

Parameters:

• view_name (str) - Only return jobs matching this 'viewname'
• current_project_only (bool

  @return a tuple consisting of a boolean which will be true for success, false for error, a list of job names, a list of job ids and a list of job statuses.

  ) - If true restrict list to jobs associated with the currently open project

Notify Maestro job monitoring that a job has been started.

Parameters:

• job_id (str) - The job id returned from mmjob when the job was launched

Parameters:

• panel_name - Panel which needs to be docked under tab if there are existing docked panels.

Gets main window instance

Returns: QMainWindow

instance for Maestro's main window

A decorator for ignoring workspace changes.  Note: This will only work to
ignore class-methods and global methods.  Instance-methods will need to
use the context manager IgnoreWorkspaceChanged.

Example:
@maestro.ignore_workspace_changed(MyClass.my_ws_changed):
def my_func():
    #Any WS changes inside this function won't trigger my_ws_changed,
    #even if it's been registered with workspace_changed_function_add

Returns 2D structure QImage for specified entry ID.

Parameters:

• entry_id (str) - Entry ID.
• width (int) - Image width.
• height (int) - Image height.

Returns: QImage or NoneType

2D structure image of the specified entry, or None if the image could not be created.

Returns a row column tooltip for specified entry ID that includes 2D structure image. The row argument is used to generate a tooltip string in case the image could not be created.

Parameters:

• entry_id (str) - Entry ID.
• row - Project table row.
• width (int)

Returns: str

Tooltip expressed as rich text string.

Set a right click handler on a specified pick category. When user right clicks on any graphics object which belongs from given pick category, a python function of a given module is called.

Parameters:

• pick_category (str) - Pick category of graphics objects.
• pymodule (str) - Python module name.
• pyfunc (str) - Python function name.

Utility function for panels that use the Maestro command 'transform scope=local', which works operates on Workspace selection.

See PANEL-8273 for details.

Parameters:

• local_asl (str) - ASL defining the local scope for the transform