31. appMenu — Menu with pyFormex apps.

Classes defined in module appMenu

class appMenu.AppMenu(title, dir=None, files=None, mode='app', ext=None, recursive=None, max=0, autoplay=False, toplevel=True, parent=None, before=None, runall=True)

A menu of pyFormex applications in a directory or list.

This class creates a menu of pyFormex applications or scripts collected from a directory or specified as a list of modules. It is used in the pyFormex GUI to create the examples menu, and for the apps history. The pyFormex apps can then be run from the menu or from the button toolbar. The user may use this class to add his own apps/scripts into the pyFormex GUI.

Apps are simply Python modules that have a ‘run’ function. Only these modules will be added to the menu. Only files that are recognized by utils.is_pyFormex() as being pyFormex scripts will be added to the menu.

The constructor takes the following arguments:

• title: the top level label for the menu
• dir: an optional directory path. If specified, and no files argument is specified, all Python files in dir that do not start with either ‘.’ or ‘_’, will be considered for inclusion in the menu. If mode==’app’, they will only be included if they can be loaded as a module. If mode==’script’, they will only be included if they are considered a pyFormex script by utils.is_pyFormex. If files is specified, dir will just be prepended to each file in the list.
• files: an explicit list of file names of pyFormex scripts. If no dir nor ext arguments are given, these should be the full path names to the script files. Otherwise, dir is prepended and ext is appended to each filename.
• ext: an extension to be added to each filename. If dir was specified, the default extension is ‘.py’. If no dir was specified, the default extension is an empty string.
• recursive: if True, a cascading menu of all pyFormex scripts in the directory and below will be constructed. If only dir and no files are specified, the default is True
• max: if specified, the list of files will be truncated to this number of items. Adding more files to the menu will then be done at the top and the surplus number of files will be dropped from the bottom of the list.

The defaults were thus chosen to be convenient for the three most frequent uses of this class:

AppMenu('My Apps',dir="/path/to/my/appsdir")

creates a menu with all pyFormex apps in the specified path and its subdirectories.

ApptMenu('My Scripts',dir="/path/to/my/sciptsdir",mode='scripts')

creates a menu with all pyFormex scripts in the specified path and its subdirectories.

AppMenu('History',files=["/my/script1.py","/some/other/script.pye"],          mode='script',recursive=False)

is typically used to create a history menu of previously visited script files.

With the resulting file list, a menu is created. Selecting a menu item will make the corresponding file the current script and unless the autoplay configuration variable was set to False, the script is executed.

Furthermore, if the menu is a toplevel one, it will have the following extra options:

• Classify scripts
• Remove catalog
• Reload scripts

The first option uses the keyword specifications in the scripts docstring to make a classification of the scripts according to keywords. See the scriptKeywords() function for more info. The second option removes the classification. Both options are especially useful for the pyFormex examples.

The last option reloads a ScriptMenu. This can be used to update the menu when you created a new script file.

getFiles()

Get a list of scripts in self.dir

filterFiles(files)

Filter a list of scripts

loadFiles(files=None)

Load the app/script files in this menu

fileName(script)

Return the full pathname for a script.

fullAppName(app)

Return the pkg.module name for an app.

run(action)

Run the selected app.

This function is executed when the menu item is selected.

runApp(app, play=True)

Set/Run the specified app.

Set the specified app as the current app, and run it if play==True.

runAll(first=0, last=None, random=False, count=-1, recursive=True)

Run all apps in the range [first,last].

Runs the apps in the range first:last. If last is None, the length of the file list is used. If count is positive, at most count scripts per submenu are executed. Notice that the range is Python style. If random is True, the files are shuffled before running. If recursive is True, also the files in submenu are played. The first and last arguments do not apply to the submenus.

runAllNext(offset=1, count=-1)

Run a sequence of apps, starting with the current plus offset.

If a positive count is specified, at most count scripts will be run. A nonzero offset may be specified to not start with the current script.

runCurrent()

Run the current app, or the first if none was played yet.

runNextApp()

Run the next app, or the first if none was played yet.

runRandom()

Run a random script.

reload()

Reload the scripts from dir.

This is only available if a directory path was specified and no files.

add(name, strict=True, skipconfig=True)

Add a new filename to the front of the menu.

This function is used to add app/scripts to the history menus. By default, only legal pyFormex apps or scripts can be added, and scripts from the user config will not be added. Setting strict and or skipconfig to False will skip the filter(s).

actionList()

Return a list with the current actions.

actionsLike(clas)

Return a list with the current actions of given class.

subMenus()

Return a list with the submenus

index(text)

Return the index of the specified item in the actionlist.

If the requested item is not in the actionlist, -1 is returned.

action(text)

Return the action with specified text.

First, a normal action is tried. If none is found, a separator is tried.

item(text)

Return the item with specified text.

For a normal action or a separator, an action is returned. For a menu action, a menu is returned.

nextitem(text)

Returns the name of the next item.

This can be used to replace the current item with another menu. If the item is the last, None is returned.

removeItem(item)

Remove an item from this menu.

insert_sep(before=None)

Create and insert a separator

insert_menu(menu, before=None)

Insert an existing menu.

insert_action(action, before=None)

Insert an action.

create_insert_action(name, val, before=None)

Create and insert an action.

insertItems(items, before=None, debug=False)

Insert a list of items in the menu.

Parameters:

• items: a list of menuitem tuples. Each item is a tuple of two or three elements: (text, action, options):
  • text: the text that will be displayed in the menu item. It is stored in a normalized way: all lower case and with ‘&’ removed.
  • action: can be any of the following:
    • a Python function or instance method : it will be called when the item is selected,
    • a string with the name of a function/method,
    • a list of Menu Items: a popup Menu will be created that will appear when the item is selected,
    • an existing Menu,
    • None : this will create a separator item with no action.
  • options: optional dictionary with following honoured fields:
    • icon: the name of an icon to be displayed with the item text. This name should be that of one of the icons in the pyFormex icondir.
    • shortcut: is an optional key combination to select the item.
    • tooltip: a text that is displayed as popup help.
• before: if specified, should be the text or the action of one of the items in the Menu (not the items list!): the new list of items will be inserted before the specified item.

Functions defined in module appMenu

appMenu.sortSets(d)

Turn the set values in d into sorted lists.

• d: a Python dictionary

All the values in the dictionary are checked. Those that are of type set are converted to a sorted list.

appMenu.classify(appdir, pkg, nmax=0)

Classify the files in submenus according to keywords.

appMenu.splitAlpha(strings, n, ignorecase=True)

Split a series of strings in alphabetic collections.

The strings are split over a series of bins in alphabetical order. Each bin can contain strings starting with multiple successive characters, but not more than n items. Items starting with the same character are always in the same bin. If any starting character occurs more than n times, the maximum will be exceeded.

• files: a list of strings start with an upper case letter (‘A’-‘Z’)
• n: the desired maximum number of items in a bin.

Returns: a tuple of

• labels: a list of strings specifying the range of start characters (or the single start character) for the bins
• groups: a list with the contents of the bins. Each item is a list of sorted strings starting with one of the characters in the corresponding label

appMenu.createAppMenu(mode='app', parent=None, before=None)

Create the menu(s) with pyFormex apps

This creates a menu with all examples distributed with pyFormex. By default, this menu is put in the top menu bar with menu label ‘Examples’.

The user can add his own app directories through the configuration settings. In that case the ‘Examples’ menu and menus for all the configured app paths will be gathered in a top level popup menu labeled ‘Apps’.

The menu will be placed in the top menu bar before the specified item. If a menu item named ‘Examples’ or ‘Apps’ already exists, it is replaced.

appMenu.reloadMenu(mode='app')

Reload the named menu.