The Launcher is a Python based, menu oriented application which allows users to launch applications and execute scripts. The Launcher is a customizable tool which builds its appearance (e.g. for different facilitates) depending on (menu) configuration files.

The Launcher can be started as follows:

pylauncher <configuration>

where configuration is the configuration file that defines the Launcher menu e.g. for a specific facility, beamline, setup, etc. .

It is possible to override the Launchers default mapping and/or default color scheme (style). This can be done using the options:

• -m (--mapping) <mapping_file>
• -s (--style) <style_qss_file>

For all available options and detailed help run

~$ pylauncher -h
usage: pylauncher [-h] [-m MAPPING] [-s STYLE] [--position X Y] configuration

positional arguments:
  configuration         menu/configuration file

optional arguments:
  -h, --help            show this help message and exit
  -m MAPPING, --mapping MAPPING
                        overwrite default mapping file
  -s STYLE, --style STYLE
                        overwrite default style (qss file)
  --position X Y        set initial position on the screen

Note: --position - 0 0 is on the top left, -1 -1 is on the lower right.

Launcher menus are defined via JSON configuration file(s). On top level, the configuration of the menu is divided in the following 3 sections:

• menu-title - An optional section to set the menu title. If no title is specified a file name is used instead.

"menu-title": {
  "text": "This is the menu title",
}

• file-choice - An optional section to specify possible views of the launcher (e.g. expert, user, ...) It can be omitted if no views need to be defined. Once the Launcher application is opened, one can select the different views from the View menu in menu bar. Selecting new view reloads Launcher from file specified in the parameter file.

"file-choice": [
  { "text": "This is view 1", "file": "menu1.json" },
  { "text": "This is view 2", "file": "menu2.json" }
]

• menu - Main section to define launcher items. The type of each item is defined with the type property. All supported types with available parameters are described in the next section.

"menu": [
    {
        "type": "menu",
        "text": "Submenu",
        "file": "submenu.json",
        "tip": "Menu tip.",
        "help-link": "http://www.link.com/to/help"
    },
    {
        "type": "separator"
    },
    { ...
    }
]

An detailed example can be found at examples/menus/menu_example.json.

For any menu item the two optional parameters help_link and tip can be specified to provide user help.

• tip - Shows as standard tool-tip (on mouse hover). If not defined, default tool-tip is applied, showing text representation of corresponding command.
• help-link - Can be accessed with right mouse click on an item

The appearance of a menu item can be customized via styles and themes. Therefore each menu item has following 2 optional paramters:

• style - Enables very flexible customization with QSS syntax
• theme - Enables customization using one of the predefined themes. How to define a theme is described in section Stylesheet. However we strongly discourage the use of theme on a per menu item basis.

Note: There are currently no themes defined.

If both parameters are defined, both are used but style has a higher priority.

{
  "type": "title",
  "text": "Title 2 - changed style",
  "style":"color: #ff0000",
  "theme":"green"
}

There are 2 classes of item types, build-in item types and types specified in the launcher mapping file.

Other/New, custom types can be specified within a launcher mapping file. See section Mapping for details.

• separator - Visually separate menu items with line.

{
  "type": "separator"
}

• title - A special separator with text. By default it is visually distinguishable from other items.

{
  "type": "title",
  "text": "This is shown title"
}

• menu - An element which opens a sub-menu that is specified in an external menu file that is defined with parameter file.

{
  "type": "menu",
  "text": "This is shown text",
  "file": "menu_2.json"
}

The default mapping file of pylauncher specifies following types.

• cmd - Executes a shell command defined with parameter command.

{
  "type": "cmd",
  "text": "This is shown text",
  "command": "shell_command",
  "tip": "What command does.",
  "help-link": "http://www.link.com/to/help"
}

• caqtdm - Opens a caQtDM screen defined with parameter panel. Macros are defined with parameter macros. Additional arguments can be passed with parameter param.

{
  "type": "caqtdm",
  "text": "This is shown text",
  "panel": "screen_name.ui",
  "macros": "MACRO1=M1,MACRO2=M2",
  "param": "-attach -dg +250+250",
  "tip": "What this screen does.",
  "help-link": "http://www.link.com/to/help"
}

• medm - Opens a medm screen defined with parameter panel. Macros are defined with parameter macros. Additional arguments can be passed with parameter param.

{
  "type": "medm",
  "text": "This is shown text",
  "panel": "screen_name.adl",
  "macros": "MACRO1=M1,MACRO2=M2",
  "param": "-attach -dg +250+400",
  "tip": "What this screen does.",
  "help-link": "http://www.link.com/to/help"
}

• pep - Opens a PEP screen defined with parameter panel (i.e. .prc file). Additional arguments can be passed with parameter param.

{
  "type": "pep",
  "text": "This is shown text",
  "panel": "screen_cfg.prc",
  "param": "-ws PV",
  "tip": "What this screen does.",
  "help-link": "http://www.link.com/to/help"
}

pylauncher uses a mapping (json) file to specify the behavior of specific menu items on different systems. The default mapping file can be overwritten with the -m <mapping option.

The mapping file has sections for each operating system, for Linux, Windows and OS_X right now.

{
    "Linux": { ...
    },
    "Windows": { ...
    },
    "OS_X": { ...
    }
}

For each operating system following options can be configured:

• theme_base for defining a path to a directory where applicable themes are stored
• Any number of menu item type definitions that are according to following rules.

A new menu item type is defined by adding a key value pair, where key is the name of the type and value is a structure with two parameters defining the command to be executed on the shell as well as possible arguments.

"my-type":{
    "command": "my-awsome-program {arg1} {arg2} {configuration}",
    "arg_flags": {"arg1": "--option ", "arg2": "--macro "}
}

The parameter command specifies the main layout of command, where each {arg} represents an argument which can be accessed with the keyword arg. In addition to this, the parameter arg_flags specifies if any of this arguments has a flag (switch). If arg_flags is not defined it equals to arg_flags= {}

Note: The example above shows a definition of type "my-type" which opens the my-awsome-program application with argument arg1 and arg2. So defined type will result in a shell command

my-awsome-program --option <arg1> --macro <arg2> <configuration>

Menu items defined like this can be used in a launcher configuration as follows:

{
    "type": "my-type",
    "text": "This is the text shown as label",
    "arg1": "myoption",
    "arg2": "example/my-macros.json"
    "configuration": "example/menus/menu_example.json"
}

Besides the attributes shown also "tip", "style", "theme" and "help-link" can be defined as well.

A full example of a mapping file can be found in examples/mapping/mapping.json.

The appearance of the Launcher or individual menu items can be customized via a QSS. The default appearance style can be overwritten at startup via the --style option.

The class names used in the qss file strongly depend on the Launcher implementation. There are 3 major classes that are used:

• LauncherButton - Defines the appearance of main title button and menu items of type: cmd, caqtdm, medm, menu and possible custom types
• LauncherMenuTitle - Defines the appearance of menu item of type title
• LauncherDetachButton - Defines the appearance of detached button

The style configuration needs to be saved to a file with the suffix .qss. The file name of the file defines the theme name that can be used in the menu item configuration. For example, the stylesheed named green.qss defines the theme with name green.

Example:

LauncherButton{
    background-color: #e9e9e9;
    text-align:left;
    border-image: none;
    border: none;
}

LauncherButton:focus, LauncherButton:pressed {
    background-color: #bdbdbd;
    outline: none
}

LauncherMenuTitle{
    background-color: #e9e9e9;
    text-align:left;
    color: #0000FF
}

LauncherDetachButton{
    background-color: #666666;
}

Anaconda comes with all required packages for pylauncher. To install the package use

conda install -c https://conda.anaconda.org/paulscherrerinstitute pylauncher

To use pylauncher with a standard Python following requirements need to be met:

• Qt 4 (4.8 or higher)
• PyQt4 (4.8 or higher)
• pyparsing

To "install" the latest version clone Git repository

git clone https://github.com/paulscherrerinstitute/pylauncher.git

The code is then located in the src/ directory.

This section assumes that one already has a working Anaconda environment on his machine and conda-build is installed.

To build an Anaconda package of the last stable version of pylauncher do

• Clone Git repository

git clone https://github.com/paulscherrerinstitute/pylauncher.git

• Build package

cd ./utils/conda_package
conda build pylauncher

Note: To be able to build the Anaconda package you need to have the patchelf package installed in your Anaconda installation. If it is not provided in the central installation, create a new Anaconda environment and install the package in there before building

conda create -n build_environment python patchelf
source activate build_environment