Helper Classes

There are a number of useful classes that simplify and standardize common operations. Developers are encouraged to use these classes when possible to ensure a common user experience.

'cei' module helper classes

Some tools have been moved to the site-packages/cei directory in the apex32 python directory. Tools included in that directory include:

• printdlg.py → CeiPrintDlg class for PyQt based rendering and printing of the main window
• qtimgformats.py → CeiQtImageFormatOptions class for prompting the user for UDIL selection/options
• qtimgformats.py → CeiQtSaveImage class to prompt the user for a complete set of image size/saving options (includes the render and save)
• plots.py → CeiPlot classes to wrapper matplotlib. Create a graph, save it to disk
• qtplots.py → CeiQtPlotWindow class providing a dockable Qt4 widget that contains a CeiPlot object (copy and print operations defined)
• qtlanguage.py → CEItranslate class that acts as a repository for .qm translation files and allows for dynamic changing of the language for all objects (includes method to get a language menu)
• ceisplash.py → ceisplash class to manage a splash screen from a .svg file
• ceilogging.py → CeiLogging, logging shortcuts
• qtgenericdlg.py → CeiQtGenericDialog() class that generates dynamic dialogs from simple lists and prompts the user for values. It can handle things like text, checkboxes, ints, floats, variables, parts, option menus, strings, filenames, etc.

More tools exist, but the idea is that tools in this dir would be usable in apps that did not have the ‘ensight’ module. Note: these tools are allowed to enhance their functionality if the ‘ensight’ module is present.

cei.qtgenericdlg module

The module implements a dynamically generated modal dialog from a list of lists. It is a simpler interface to the Qt library for simple prompting and queries. This module has one class and a number of enums.  The enums defined by the module include:

Item types: ITEM_TEXT, ITEM_BOOL, ITEM_INT, ITEM_FLT, ITEM_COMBO, ITEM_STR, ITEM_STR_RO, ITEM_FILE, ITEM_PART, ITEM_VAR

File options: OPT_FILE_OPEN, OPT_FILE_SAVE, OPT_FILE_DIR

Variable options: OPT_VAR_CON, OPT_VAR_SCL, OPT_VAR_VEC, OPT_VAR_TEN, OPT_VAR_SCLCPX, OPT_VAR_VECCPX, OPT_VAR_ACT, OPT_VAR_ELEM, OPT_VAR_NODE, OPT_VAR_TIME, OPT_VAR_COORDS

Part options:OPT_PART_SINGLE, OPT_PART_STRUCT, OPT_PART_UNSTRUCT

Misc options: OPT_OBJECT 

CeiQtGenericDialog class

Methods:

dlg = CeiQtGenericDialog(items,parent=None,title="",ok="Ok",cancel="Cancel",help=None)

Constructs a generic dialog object. Items is a Python list of lists. Each list in the list describes a single dialog GUI item (see "item details" below). Options are included for the caller to support a QtWidget as the parent of the dialog and to supply text strings for the title of the dialog and the ok and cancel dialog buttons.  The help parameter allows the caller to specify an instance of an object subclassing from guibase_extension (a tool extension for example).  If the class has a help URL or HTML, a 'Help...' button will be added at the bottom of the dialog and it will display the noted URL (via web browser) or HTML via a modal dialog.

ret = dlg.doit()

Displays the dialog and allows the user to interact with it. The return value is True (non-zero) if the user clicked 'Ok'.

taglist = dlg.getValues()

Returns a list of all of the 'tags' passed in the items list in the dialog constructor.

value = dlg.getValue('tag')

Returns the final value the user entered for the item with the 'tag' when they clicked 'Ok'.

Item details:

Each list in the 'items' list has the following basic format:

['tag',type,"text","tooltip"...]

The 'tag' is a string that names the item.  This tag is used later by the getValue() method to get the actual value the user entered.  You can also get a complete list of the tags from a dialog using the getValues() method.

The type is an enum value from the list: ITEM_TEXT, ITEM_BOOL, ITEM_INT, ITEM_FLT, ITEM_COMBO, ITEM_STR, ITEM_FILE, ITEM_PART, ITEM_VAR.  Details for specific types are described later.

The 'text' string is a label that will be displayed to the left of the item in the dialog. 

The 'tooltip' is a string that will be displayed when the mouse hovers over the item in the dialog.

Each type may have other options:

• ITEM_TEXT - simple text label with no extra options: ['tag',ITEM_TEXT,"text","tooltip"]
• ITEM_BOOL - checkbox with a label to the left: ['tag',ITEM_BOOL,"text","tooltip",bool] The bool value is the initial value for the checkbox.
• ITEM_INT - enter an integer with a label to the left: ['tag',ITEM_INT,"text","tooltip",value,min,max] The value is the initial integer value. min and max are the lower and upper limits on the value. In 9.1, these values are optional.
• ITEM_FLT - enter a floating point number: ['tag',ITEM_FLT,"text","tooltip",value,min,max] The value is the initial integer value. min and max are the lower and upper limits on the value. In 9.1, these values are optional.
• ITEM_COMBO - a popup list of items: ['tag',ITEM_COMBO,"text","tooltip",value,["value1","value2",...]] The value is the initial value and should be a string in the list of strings that follows it in the list.  The last list contains the strings to be listed in the combo box.
•  
• ITEM_STR - enter a text string: ['tag',ITEM_STR,"text","tooltip",value]. The string value is the initial value for the string box.
• ITEM_STR_RO - behaves like ITEM_STR except that the string displayed is read only.
• ITEM_FILE - select a filename by typing or the system filer dialog: ['tag', ITEM_FILE, "text", "tooltip", value, opt].  Value is the original initial value of the filename. The opt value is optional and there are a number of possible options: OPT_FILE_OPEN uses the standard file open dialog, OPT_FILE_SAVE uses the standard file save dialog, OPT_FILE_DIR allows for the selection of directories instead of files.  
• ITEM_PART - select and EnSight part: ['tag',ITEM_PART,"text","tooltip",value,opt,types,filter] value is the initial part to be selected.  There are a large number of options that can be used in the opt field and these can be combined using the Python '|' operator. By default, the item allows for multiple parts to be selected. Including OPT_PART_SINGLE in opt selects a single part. By default, both structured and unstructured parts are displayed. The OPT_PART_STRUCT or OPT_PART_UNSTRUCT values can be included in opt to display only structured or only unstructured parts. If the option OPT_OBJECT is included in opt, the return value will be part objects instead of part names (which is the default). The types field is optional and allows the user to specify a list of part types that should be included in the list. For example, a types field of [ensight.PART_MODEL, ensight.PART_CONTOUR] would display only model and contour parts. To display all types, pass an empty list '[]'. The filter field is also optional. It allows the user to specify a wildcard string to filter the partlist by part names.  For example, "Block*" would only display parts that start with the word "Block".
• ITEM_VAR - select and EnSight variable:['tag',ITEM_VAR,"text","tooltip",value,opt,filter] value is the initial variable to be selected.  There are a large number of options that can be used in the opt field and these can be combined using the Python '|' operator. By default, both nodal and element variables are displayed. The OPT_VAR_ELEM or OPT_VAR_NODE values can be included in opt to display only element or only nodal variables. If the option OPT_VAR_ACT is included in opt, then only active variables will be included in the list. If the option OPT_OBJECT is included in opt, the return value will be variable objects instead of variable names (which is the default). The opt field can also be used to filter the variables by their type. Including one or more of the following enums: OPT_VAR_CON, OPT_VAR_SCL, OPT_VAR_VEC, OPT_VAR_TEN, OPT_VAR_SCLCPX, OPT_VAR_VECCPX, OPT_VAR_TIME, OPT_VAR_COORDS triggers this filtering. For example, specifying OPT_VAR_SCL|OPT_VAR_VEC will only include scalar and vector variable types. The filter field is also optional. It allows the user to specify a wildcard string to filter the variable list by variable names.  For example, "*vel" would only display variables that start with the word "vel".

A simple example of all of the item types would be:

items = []
items.append(['text',ITEM_TEXT,"Here is some example text...",""])
items.append(['bool',ITEM_BOOL,"Checkbox","An example Boolean",1])
items.append(['int',ITEM_INT,"Integer","An example integer",10,0,100])
items.append(['flt',ITEM_FLT,"Float","An example float",0.0,-10.0,10.0])
list = ["choice0","choice1","choice2"]
items.append(['combo',ITEM_COMBO,"Combo","An example Combobox",1,list])
items.append(['str',ITEM_STR,"Str","An example string","here we have a string"])
items.append(['file',ITEM_FILE,"File to read","An example file to read","/tmp", OPT_FILE_OPEN])

items.append(['file',ITEM_FILE,"File to write","An example file to write","/tmp", OPT_FILE_SAVE])
items.append(['part',ITEM_PART,"Parts:","An example partlist",[""],0])
items.append(['parto',ITEM_PART,"Object parts:","An example partlist",[""],OPT_OBJECT])
items.append(['var',ITEM_VAR,"Vars:","An example varlist","",0])
items.append(['varo',ITEM_VAR,"Object vars:","An example varlist","",OPT_OBJECT|OPT_VAR_SCL|OPT_VAR_VEC])
a = CeiQtGenericDialog(items,None,"Test case","Ok","Cancel")
ret = a.doit()
print("Return = {}".format(ret))
for i in a.getValues():
    print("value for {} is {}".format(i, a.getValue(i)))

#
# Looking for part IDs?  Use the object interface and a little glue
#
from cei.qtgenericdlg import *
items = []
items.append(['parts',ITEM_PART,"Parts:","An example partlist",[""],OPT_OBJECT])
dlg = CeiQtGenericDialog(items,None,"Test case","Ok","Cancel")
ret = dlg.doit()
if (ret):
    part_ids = map(lambda x: x.PARTNUMBER, dlg.getValue('parts'))
    print("Part ids: {}".format(part_ids))

Note: this class is also available for non-EnSight use (e.g. cpython21), but the variable and part item types are not supported.

'ensight.core' module helper classes

• qtimageutils.py → CeiEnSightPrintWindow() class for rasterizing and printing
• qtimageutils.py → CeiEnSightCopyWindow() copy to clipboard
• qtimageutils.py → CeiEnSightSaveImage() save image to disk
• qtimageutils.py → CeiEnSightImportImageAnnot() import image file/movie as an annotation
• snl_DART_partlist.py → specific to the Exodus II reader