The EnSight 'ensight.core' module

CEI provides ensight base objects located in the directory $CEI_HOME/ensight{version}/site_preferences/extensions/core. This module is loaded by default (see the __init__.py file for details) as the module ‘ensight.core’. In that directory are the base classes for various operations and many EnSight specific helper classes.

Python stdout/stderr redirection

In EnSight, the Python stdout and stderr systems are redirected into the Command window Python tab by default.  This operation is controls by objects in ensight.core. Specifically, ensight.core.ENS_stdout_instance and ENS_stderr_instance are the wrappers for the Python interpreter output. EnSight 9.0 has added ‘resume()’ and ‘suspend()’ methods which allows output to be redirected to the console instead of the command dialog Python tab. For example:

import ensight.core

ensight.core.ENS_stdout_instance.suspend()

ensight.core.ENS_stderr_instance.suspend()

will disable the redirection of Python text output to the Python tab window.

Core: Extension Base Classes

• core_extension.py, gui_extension.py, menu_extension.py, tool_extension.py → base classes for user defined command language extensions, GUI replacements, menus and tools respectively. More on extensions later...
• userdefinedmenus.py, userdefinedtools.py → mechanisms to display and interact with user defined menus and tools
• enspyqtgui.py → code for handling switches between GUIs.
• extensions → a dictionary of instances of the currently loaded extensions.  The keys of the dict include ‘menu’, ‘tool’, ‘core’, ‘gui’ and each points to a list of instances of object of the class ‘xxxx_extension’s that were created on startup. The keys match the extension “type”s noted below.  There are helper methods to search this dictionary in the core_extension class.

The core_extension

Basic extension of the command language.  All EnSight extensions inherit from this base class. The class provides basic metadata for the objects: Name, description, version, vendor, release date, etc.  It also provides basic support for parent/child hierarchies of extensions (e.g. for dependent extensions or simple display hierarchies). There is a notion that the core object will be called back whenever the EnSight license changes and when the EnSight GUI is considered to be fully up and running. The core of the language translation system is in this base class.  Every extension is given a name in EnSight command language and the system by which it can be called from command language and record its own actions in command language. Finally, there is a hook so that the user can call any extension from the command line and pass parameters to it using the '-E' option and the command language name of the extension.

type = “core”

• _version : version number
• _vendor : who wrote this extension
• _path : path to the file defining this extension
• _name : “name” for purposes of Python/cmdlang namespaces (no spaces, odd chars, etc)
• _text : Display name of the extension
• _desc : ASCII description of the exension
• _namespace : actual cmdlang namespace (e.g. ext: namespace foo)
• _children : list of children of this extension
• _sort : the string to be used when sorting items (e.g. for the purposes of display in a menu list, etc)

• addChild(child) : add a child
• setDesc(text), d = getDesc() : set/get the description for this extension
• setSort(text) : set the menu sorting value for this extension
• cmdExec(string) : called back when cmdlang sees “ext: namespace foo” String will be “foo”
• cmdRecord(string) : call to record command language “ext: _namespace string”
• licenseChanged(): called whenever the EnSight license changes
• setVendor(v) : sets the name of the vendor
• setReleaseDate(d) : sets the release date (string) of the extension
• setText(t), t=getText() : set/get the human visible name of this extension
• setName(n), n=getName() : set/get the (local) python namespace of this extension
• getTranslationNamespace() : get the fully qualified namespace of this extension (prepends any parent namespaces)
• getTranslationStrings() : get a list of strings that will need to be translated in the above namespace.  The core implementation includes the _text, _desc, and _tooltip strings.
• Note: actual translation support is only available in the guibase_extension subclasses as it uses Qt
• cmdLine(param=None) : If this extension is invoked from the command line (-E option), this method will be called.
• cmdExec(string) : if this extension is invoked from command language, this methods will be called with the extended command string.
• cmdRecord(string,ispython=0) : call this method to record an operation into command language.  The 'string' will be recorded with the proper namespace and on execution of the script, cmdExec() will be called with the original string.  Note: if the string is actually valid Python and need not be routed back via cmdExec(), setting ispython to 1 will cause the string to be output into command language as raw python with no connection to this extension.
• finalize(stage) : the finalize() method is designed to be called at various steps during EnSight startup.  At present, it is only called once.  If stage==0, the EnSight GUI has been fully instantiated.

The guibase_extension (core_extension)

Command language + common GUI elements.  This class includes some basic help features. The programmer can set a URL (external website) or HTML text as the help for this extension and can check for the existence of help as well as display it (possibly in a web browser).

type = “guibase”

• setInMenus(v) : Set the state of dynamic menu visiblity.  This works by returning None in getWidget() calls.
• getInMenus() : True if this extension should show up in any dynamic menus.
• setTooltip(text) : the text for the tooltip
• setIcon(”pathname”) : filename for the icon, can be a resource reference (e.g. “:/ensight/...”)
• getWidget(w,parent) : get the display widget for a specific object.  Generally, this is a QPushButton, QTreeWidgetItem, QMenu or QAction depending on the subclass and the context.  The first two are common with tool_extensions and the latter are used by menu_extensions. 
• setWaitCursor(onoff) : Enable/disable a "wait" cursor for the current window/context.
• setHelpHTML(string): set help text in the Qt HTML subset that is displayed in a window by doHelpDialog()
• setHelpURL(string): specify a URL that will be opened in a web browser by doHelpDialog()
• getHelpURL():
• getHelpHTML():
• hasHelpDialog(): returns true if either the URL or HTML help strings has been set.
• getHelpDialog(parent=ensight.qtparent()): returns a subclass of a modal QDialog widget if the HTML string has been set (it allows the extension a change to embed images, etc in the content).
• doHelpDialog(parent=ensight.qtparent()): will display the HTML text in a modal dialog or will open the URL in an external webbrowser (note: CEI_WEBBROWSER can be used to select the browser). It returns 0 on failure or if the user clicked to "cancel" the dialog.
• translate(s) : will translate the passed string (Python string or QString) into the current EnSight language, returning a QString object.  Note: the string must have previously be returned by getTranslationStrings(), and the translated Qt .ts file must have been compiled and placed in the appropriate CEI installation translation folder. 

Drag and drop support

The guibase_extension supports drag and drop operations.  There are a number of methods that must be overridden to make this work. When an extension wants to start a drag, it calls self.dragStart(widget,'str') or self.dragStart(widget,[ensobjlist]).  This will cause the target to have a string or a list of ensight objects potentially dropped on it. If the drag was dropped on one or more EnSight objects, self.dragHandler(str,objlist,executeflag) will be called on the extension.  This asks the extension if it is ok to apply the information in 'str' onto the objectlist.  The method should return True if the operation is allowed or False if it is not.  If executeflag is True, the operation should actually be performed by the extension.  The default implementation of guibase_extension.dragHandler() will interpret the string as a dictionary and call obj.setattrs(dict,record=1) on all of the objects in the object list.  It also filters the drop based on matches in the attribute keys in the source dictionary and the target objects.

There are a host of additional utilities for working with EnSight drag and drop object lists and other MIME types in the file guibase_extension.py.  The user is encouraged to explore the source for details.

• dropDecode(obj) parse an ENSOBJ QMimeData object into actual object references.
• classifyURLbyMIME(url) given a drop event object, find the file types and detailed information (e.g. 'movie', 'EVO') for any URLs in the drop object.
• classifyFilebyMIME(filename) same as above, but for a filename
• dragEnterEvent() : decide if we can open a specific file type in the URLs of a drag enter event
• dropEvent() : actually open the file(s) in the URLs of a drop event
• ...

The gui_extension (guibase_extension)

A full user-defined GUI

type = “gui”

• setSplash(pathname) : pathname to an SVG file to use as the splash screen
• doActivate(onoff) : called to enable/disable this GUI must be overridden, returns False on failure.
• doErrorMessage(message,style) : called when EnSight throws an error or needs a Yes/No question, must be overridden. 
• style=0 : warning dialog, return 1 to accept, 0 to disallow
  style=1 : error dialog, do not block (return value ignored)
  style=2 : error dialog, block until user presses ok (return value ignored)
  style=3 : status string
• doGuiEvent(message,targetlist) : called when there is a GUI event, must be overridden.
• setMainWidget(w) : if the GUI creates a main window widget, the GUI should register it using this method
• getMainWidget(): return the registered GUI widget
• getStartup():
• showStartup():
• getSplashSVG():
• getGUIMenu(parent): build a Qt menu that allows your user to change to other GUI interfaces
• updateMRUMenu(parent): if your application wants to use the EnSight MRU, pass a QMenu parent and when your GUI is activated, calling updateMRUMenu() will cause your MRU menu to be properly populated.  Note: loading of an MRU entry causes a gui_event() message which you can handle or allow the core to load.
• doInfoMan(name): this is a request by EnSight to display part of the EnSight help system.  The default is to dispatch such requests through: ensight.int_help(name) which brings up the PDF viewer for the associated page.

Note: cmdExec/ has been overridden to include “activate_gui” message

Useful module functions:

• ensight.core.gui_extension.gui_activate(name)
• gui=ensight.core.gui_extension.current_active_gui()
• ensight.core.gui_extension.error_message(msg,what) - This function is used to send an error message off to the active GUI. The core sends the call to the doErrorMessage() method on the currently active gui_extension subclass. The default doErrorMessage() method prints to stderr. ‘msg’ is a string to display and ‘what’ can be 0 (warning dialog, return 1 to accept, 0 to disallow), 1 (a non-blocking error dialog), 2 (a blocking error dialog), 3 (a “status” message string).
• ensight.core.gui_extension.gui_event(msg,targets) - This function is used to send an event off to the active GUI. The core sends the call to the doGuiEvent() method on the currently active gui_extension subclass. The default doGuiEvent() method does nothing. 
• gui=ensight.core.gui_extension.current_gui_mainwidget()
• ensight.core.gui_extension.info_man(what)
• ensight.core.gui_extension.gui_about()

Currently defined gui_event() messages include:

• “edit tool TOOLNAME” - TOOLNAME can be one of: “cursor”, ”plane”, ”line”,”box”, ”select_tool”, ”cylinder”, “sphere”, ”cone”, ”revolution”. If the GUI can edit such a tool, it should display the dialog for it.
• “edit object”, target_object - A request to “edit” the attributes of the target object(s).
• “open window WINDOWNAME" - WINDOWNAME and be one of: "views_manager", "cei_info”, "texture_editor" - a request to open a specific EnSight window.
• “open mru {num}” - a request to open the Nth item in the MRU list.
• “traceback ‘saasdsd’” - do not try to handle this internal event. It is used by the error handling console extension.

If desired, a gui_extension subclass can allow EnSight to try to handle the event by calling: ensight.int_message(message,targetlist) in the doGuiEvent() method. The subclass doGuiEvent() method gives the gui a chance to filter the events before EnSight sees them.

Note: cmdExec/ has been overridden to include “activate_gui”

The tool_extension (guibase_extension)

Base class for an EnSight user-defined tool.  A user-defined tool typically displays a top-level widget that the user can interact with. The widget can be modal or non-modal.

type = “tool”

• run() : override to do what this menu should do when selected.
• getWidget(parent, btn=0) : this method returns a QPushButton or QTreeWidgetItem subclass that will cause 'run()' to be called if the item is clicked. if btn is 1, it will return the QPushButton subclass.

The panel_extension (guibase_extension)

Base class for an EnSight user-defined panel.  A panel controls a widget that can be docked into the EnSight GUI. It's status will be remembered and EnSight will try to re-open them at startup. Generally this will be a non-modal panel that reflects some status of the session and allows for unique interaction. Panels can allow a single GUI instance or multiple instances of the GUI.

type = “panel”

• run() : Generally, this method should not be overridden.  If 
• setMultiple(b) : enable/disable the display of multiple instances of the GUI
• multiple() : get the 'setMultiple()' status
• setIsTool(b): if true, the panel will also be registered as a tool_extension.
• setWindowTitle(s): The title of the window that should wrapper the panel contents
•  createInstance(parent): This method must be overridden.  It is called when a new instance of the panel should be created.  'parent' is the widget that will serve as the parent of the panel UI.  The GUI is asked to provide a top-level parent of the panel.  Generally, this is a dockwidget, but it could be any potential widget (e.g. group, etc). This method must not call show() as that will be done external to this method.

The menu_extension (guibase_extension)

Base class for an EnSight popup menu.

type = “menu”

• setSeparator(T/F) : set to true if this menu is a separator
• setMode(mode) : mode for this menu to be displayed in. Concatenated from: ‘Part’,’Annot’,’Plot’,’VPort’,’Frame’,’All’
• setPartType(type) : part types for which this menu is to be displayed. Concatenated from: ‘All’,’Model’,’ClipPlane’,’Contour’,’DiscreteParticle’,’Frame’,’IsoSurface’,’ParticleTrace’,’Profile’,’VectorArrow’,’ElevatedSurface’,’DevelopedSurface’,’ModelExtract’,’ModelCut’,’ModelBoundary’,’IsoVolume’,’BuiltUp’,’TensorGlyph’,’FxVortexCore’,’FxShock’,’FxSepAtt’,’MaterialInterface’,’Point’,’AxiSymmetric’,’ ModelMerge’,’Mult’
• validFilter(self,emode,ptype) : return 1 if this menu should be shown. By default, it filters by mode and parttype as noted above, however for general filtering, override this method.
• run() : override to do what this menu should do when selected.
• _info : the dictionary of values resulting from the mousedown that triggered this menu

Note: the _info attribute is set to the “context” of the operation that started the menu operation. It is a dictionary. Some fields are pre-defined, depending on the EnSight RMB context.

The pre-defined _info fields are:

Common to all modes

• ‘pick’: the click target
• ‘pos’: the (x,y,z) tuple of the click in data space
• ‘target’: list of ensight object references that are the action target (list can be empty)
• ‘mousepos’: (x,y) position tuple in the graphics window of the mouse down (normalized coords). -1,-1 if there is no position or one is not in the window.

pick: CVF_CURSOR_TOOL

pick: CVF_LINE_TOOL

• ‘item’: The part of the line clicked: CVF_EVENT_LOCAT_MID, CVF_EVENT_LOCAT_END2, CVF_EVENT_LOCAT_END1, CVF_EVENT_LOCAT_XAXIS, CVF_EVENT_LOCAT_YAXIS, CVF_EVENT_LOCAT_ZAXIS

pick: CVF_PLANE_TOOL

• ‘item’: The part of the line clicked: CVF_EVENT_LOCAT_MID, CVF_EVENT_LOCAT_UPPER_RIGHT, CVF_EVENT_LOCAT_LOWER_LEFT, CVF_EVENT_LOCAT_LOWER_RIGHT, CVF_EVENT_LOCAT_UPPER_LEFT, CVF_EVENT_LOCAT_XAXIS, CVF_EVENT_LOCAT_YAXIS, CVF_EVENT_LOCAT_ZAXIS

pick: CVF_CYLINDER_TOOL

• ‘item’: The part of the line clicked: CVF_EVENT_LOCAT_MID, CVF_EVENT_LOCAT_END2, CVF_EVENT_LOCAT_END1, CVF_EVENT_LOCAT_XAXIS, CVF_EVENT_LOCAT_YAXIS, CVF_EVENT_LOCAT_ZAXIS, CVF_EVENT_LOCAT_RADIUS

pick: CVF_CONE_TOOL

• ‘item’: The part of the line clicked: CVF_EVENT_LOCAT_MID, CVF_EVENT_LOCAT_END2, CVF_EVENT_LOCAT_END1, CVF_EVENT_LOCAT_XAXIS, CVF_EVENT_LOCAT_YAXIS, CVF_EVENT_LOCAT_ZAXIS, CVF_EVENT_LOCAT_RADIUS

pick: CVF_SPHERE_TOOL

• ‘item’: The part of the line clicked: CVF_EVENT_LOCAT_MID, CVF_EVENT_LOCAT_END2, CVF_EVENT_LOCAT_END1, CVF_EVENT_LOCAT_XAXIS, CVF_EVENT_LOCAT_YAXIS, CVF_EVENT_LOCAT_ZAXIS

pick: CVF_REVO_TOOL

• ‘item’: The part of the line clicked: CVF_EVENT_LOCAT_MID, CVF_EVENT_LOCAT_END2, CVF_EVENT_LOCAT_END1, CVF_EVENT_LOCAT_XAXIS, CVF_EVENT_LOCAT_YAXIS, CVF_EVENT_LOCAT_ZAXIS

pick: CVF_POLYLINE

• ‘item’: The spline number clicked on
• ‘point’: The index into the spline knot points

pick: CVF_LEGEND

• ‘item’: The palette id
• ‘component’: The palette id component (for vectors)

pick: CVF_ANNOT

• ‘item’: The annotation id (the target object has the type implicitly)

pick: CVF_PART

• ‘item’: The part id

pick: CVF_VIEWPORT

• ‘item’: The viewport id

pick: CVF_PLOTTER

• ‘curve’: The curve number clicked on
• ‘value’: The (f,x) value at the clicked point
• ‘point’: the hit point: CVF_EVENT_LOCAT_MID, CVF_EVENT_LOCAT_XAXIS, CVF_EVENT_LOCAT_YAXIS.

pick: CVF_IQ_QUERY_PROBE

• ‘item’: The query probe item (index)

Other useful menu functions

• core.userdefinedmenus.doPopup(infodict) : popup the current RMB menu at the mouse. You must pass a proper info dictionary (see: _info above)

Note: with this latter function, the caller needs to create the _info dictionary. One special key has been defined: ‘mode’. If this key is present, it will override the current EnSight mode value for validFilter() filtering. 

d = {'pick': ensight.CVF_PART, 'item': partid, 'target': partobj, 
     'pos': (0,0,0), 'mousepos': (-1,-1) }
ensight.core.userdefinedmenus.doPopup(d)

The feature_extension (guibase_extension)

---

Base class for an EnSight feature dialog content area.

type = “feature”

This object represents an EnSight "feature".  It can include a "feature" icon for the feature toolbar, a collection of "action" icons for the edit toolbar and a panel that will be placed in the "edit properties" (FDE) dialog when the feature is active or when specific objects have edit selected on them. See feature_extension.py for details.