HowTo: Add a Menu Entry for a Script

Version: 16.2

Table of Contents

Preface

This document outlines how to add a menu entry to MineSight® 3D for an embedded MineSight® Grail Script.

Getting Started

In order to add scripts as menu options directly into MineSight® 3D, the proper folder structure must be in place.

If they do not exist, you must create a "plugin" directory within the same directory as ms3d.exe and add "scriptmenu" as a sub-directory.

<ms3d.exe path>\plugin\scriptmenu

You will be working within the "scriptmenu" directory.

Creating a Configuration File

A configuration file is a text file which outlines which menu items you want to add to the MineSight® 3D menu and where they should be placed.

All configuration files must be named "menuConfig.mni".

Each line in the configuration file corresponds to one element added to the menu system. Each element consists of a TYPE and some properties.

Types

There are 4 types of elements which can be added to the menu:

  • Root - (ROOT)
    • A root is a highest level menu items and appears in the menu bar
    • e.g. File, Help, etc.
  • Group - (GROUP)
    • A group is a section on the menu which would appear with divider lines. They allow you to group related items.
  • Submenu - (SUBMENU)
    • A submenu appears as an entry in the menu with an arrow which brings up another menu. Submenus contain groups.
  • Item - (ITEM)
    • An item is the entry in the menu which performs an action
    • In this context, each script you want to add to the menu will be added as an item.
    • e.g. Open, Save, etc.

Properties

Properties describe the element and allow you to specify where and how and element is displayed.

The element type will determine if a property is required, optional, or even applicable. For a full listing of properties and options, please go here.

Below is a list of properties. They key for the property is specified in parenthesis

  • Tag - (tag)
    • Tag is the unique identifier for an element.
    • Since tags must be unique, use a descriptive tag to prevent duplications accidentally.
    • Required for every type
    • e.g. tag = myCalcGroup
  • Title - (title)
    • Displayed text for the element
    • Required for Roots, Sub menus, and Items
    • e.g. title= Average Ore Value
  • Mnemonic - (mnemonic)
    • Single character which acts as short cut
    • Optional for Roots, Sub menus, and Items
    • e.g. mnemonic = H
  • Popup Title -(popuptitle)
    • This is the text which will appear on the right-click popup menu in the most recently used items section
    • Applies only to Items and is optional.
    • e.g. popuptitle = Average Ore Value
  • Priority - (priority)
    • A number which determines the location of the element relative to other elements at the same level. Lower numbers have a higher priority and appear earlier in the list.
    • Applies to Roots, Groups, and Items only and is optional
    • By default, items will be sorted alphabetically.
    • e.g. priority = 0
  • Script - (script)
    • The relative path of the python script to be run with this Item
    • Required for Items
    • e.g. script = calculateAverageOre.py
  • Keyword - (kw)
    • Used to determine where elements are placed in the menu.
    • Applies to Groups, Sub menus, and Items
    • If no keywords are specified, elements will appear in the MineSight root menu.
    • Elements may have multiple keywords.
    • e.g. kw = Help

Format

The configuration file is delimited using commas with one element per line.

Each line will have the following format:
TYPE, key = value, key = value, ...
Here is an example file:
ROOT, tag= operations, title = Operations
ITEM, kw = operations, tag = script1, title = Script 1, mnemonic = 1, script = pypdkScript1.py
ITEM, kw = operations, tag = script2, title = Script 2, mnemonic = 2, script = pypdkscript2.py
ITEM, kw = operations, tag = script3, title = Script 3, mnemonic = 3, script = pypdkscript3.py

This would produce a menu item like this:

pythonMenuSimple.png

Notes about Format

There are several key things to note about the format:
  • Optional properties which you do not wish to specify should be omitted. Do not attempt to use some sort default value for these.
  • The type must always be first, but the rest of the properties can appear in any order. It seems useful to place keywords and tags first in the line because they are used for determining layout and may need to be easily referenced. Similarly, placing script at the end makes it easy to spot a problem should the item list the wrong script.
  • The order of the elements in the file make no difference, though grouping related elements will make it easier to spot problems.
  • Spacing is not significant in the file. Feel free to use spaces to make the file more readable, but no more than 1000 characters per line.

Keywords

Keywords are used to denote where in the menu an element should be placed.

  • Elements without keywords, or those that have incorrect keywords, will appear in the MineSight menu.
  • Keywords will correspond to the tags of other elements. In the above example, the tag for the Root is "operations", so each item which appears in the menu will need a keyword "operations"
  • Keywords have to be chained up to the root, i.e. each element must not only specify its parent, but its parent's parent, and so on.

Here is an example of a configuration file which chains keywords:

ROOT, tag= operations, title = Operations
SUBMENU, kw = operations, tag = submenu1, title = SubMenu, mnemonic = S
GROUP, kw = operations, kw = submenu1, tag =subMenuGroup
ITEM, kw = operations, kw = submenu1, kw = subMenuGroup, tag = script1, title = Script 1, mnemonic = 1, script = pypdkScript1.py
ITEM, kw = operations, kw = submenu1, kw = subMenuGroup, tag = script2, title = Script 2, mnemonic = 2, script = pypdkScript2.py
GROUP, kw = operations, tag = group2
ITEM, kw = operations, kw = group2, tag = script3, title = Script 3, mnemonic = 3, script = pypdkScript3.py

This produces a a menu like this:

pythonMenuSubmenu.png

Putting It Together

Once you have your configuration file and scripts written and you have your directory structure set up, you can now get your scripts to appear as menu items.

In order to allow easy addition of scripts new scripts without worrying about naming conflicts or overwriting another's work, each "unit" of related scripts should be placed into a separate folder with the configuration file.

This means that within the scriptmenu directory, you will have 1 or more other sub-directories of related scripts and configuration files.

e.g. <ms3d.exe path>\plugin\scriptmenu\OreControl

Each sub-directory (in this case OreControl) will contain:
  • menuConfig.mni
  • python scripts referenced in that config file
pythonMenuFolderStruct.png

The benefit of splitting the scripts up in such a manner allows you to more easily organize your files. In addition, each group is standalone, i.e. it does not rely on any other groups of scripts to ensure that the menu structure is in place.

For example, a second configuration file in another directory could contain ROOT, tag = operations, title = Operations. You will still only see one Operations root menu item.

Items of Note:

  • A configuration file in the scriptmenu directory will not be evaluated for adding to the menu. You must use a sub-directory.
  • Sub-directories will not be recursively searched for configuration files. menuConfig.mni must be at the top of the sub-directory.
  • Errors in the configuration file will not trigger any notification. If your item is not where you expected it to be, it will often be in the MineSight menu.
View document source. Generated on: 2024-04-16 17:27 UTC.