# 32. `gui.appMenu` — Menu with pyFormex apps.

class `gui.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`(startfrom='A', stopat='[', count=-1, recursive=True, random=False)

    Run all apps with a name in the range [startfrom,stopat].

    Runs the apps with a name >= startfrom and < stopat. The default will run all apps starting with a capital (like the examples). Specify None to disable the limit. If count is positive, at most count scripts are executed. If recursive is True, also the files in submenu are played. If random is True, the files in any submenu are shuffled before running.

  `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).

## 32.1. Functions defined in module gui.appMenu

`gui.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.

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

  Classify the files in submenus according to keywords.

`gui.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

`gui.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.

`gui.appMenu.``reloadMenu`(mode='app')

  Reload the named menu.