============================MS3D APPLICATION MENU README============================

Copyright 2008 Mintec, Inc.All Rights Reserved

.. Contents:: Table of Contents

--------OVERVIEW--------

The APPMENU INI files are used for installing menu entires onto the"MineSight" application menu of MS3D. You can control what your menulooks like for all projects or on a project by project basis.

Modifications of this file should only be done if you know what you aredoing, so always MAKE A BACKUP!

--------------SPECIFICATIONS--------------

FILE NAMING AND LOCATION------------------------

The "MS3D_APPMENU_[PRODUCT].ini" files are used to help configure thecontents of the MS3D MineSight menu. The files are named according totheir products, and indicate how they should be sorted on the menu.Thus, "ms3d_appmenu_product_a.ini" is sorted before"ms3d_appmenu_product_b.ini".

If you use the project directory a separator will be added to helpdistinguish it from the MS3D process directory entries and thecustom compass procedures.

VARIABLE SUBSTITUTIONS----------------------

At runtime certain items are known, and when the INI file is loaded itwill perform variable substitutions using the $(var) notation. Forexample, consider that you want to launch a program, and supply theproject directory,

::

... program=doozle_drap.exe args="$(ProjectDir)" ...

If the project directory was, C:\projects\BigGoldMine, then the programwould get spawned with,

::

doozle_drap.exe "C:\projects\BigGoldMine"

VARIABLES

.........

$(Config)

Indicates that we are working with either a "DEBUG" or "RELEASE" version of MS3D.

$(MEDEXE)

The directory that %MEDEXE% points to.

$(MS3DProcessDir) Points to the directory that contains the MS3D.EXE.

$(ProjectDir)

Points to the directory that was selected on the MS3D Splash Screen.

$(ResourceDir)

Points to the directory that contains the MSRS (_msresource).

All variables are CASE SENSITIVE. MENU VERSUS SUBMENU-------------------

Your application menu may want to either make a single menu entry or itmay want to specify a submenu. You can handle this by specifying morethan one entry in the "menu/list" entry. As in,

::

; Example of a submenu [menu] title = Economic Planner (MSEP) mnemonic = E requires = any list = msep_compass, msepc

Where the list will give the full specifications for the menu entry. Inthis case there would need to be [msep_compass] and [msepc] sections.

If you just wanted to have a single entry (i.e. no submenu), you woulddo the following,

::

; Example of a single entry menu. [menu] list = msda

Then there would exist an [msda] section that had the full configurationoptions.

COMMON ENTRIES--------------

**type, required**

This indicates what type of menu entry you have. See the `ENTRIES BASED ON TYPES`_ section for a list of available types.

**title, required/optional**

This is the name of the menu entry.

**mnemonic, optional**

This is the mnemonic that we will use for the entry.

**requires, required/optional**

This defines what is required to enable/disable the menu entry. This has zero effect on the actual "usage" of the menu entry contents. If you are not sure, then you should probably use "any" for this value.

ENTRIES BASED ON TYPES----------------------

The following specifications are type specific. Any given section needsto have certain entries defined based on its type.

compass_group .............

This specifies that you wish to open a specific menu and a specificgroup on the Compass Dialog. A compass_group type should have thefollowing entries,

**mnu, required**

This is the name of the MNU file for searching for a group. If the MNU file is not found, a warning is posted to the MS3D Message Box, and MSCOMPASS is "just opened".

**group, required**

This is group to select from the supplied MNU box. This group will be active when you select this menu entry. The group name is case sensitive.

**default_group, required**

If the above group is not found, this group is activated. It is recommended that you use something generic like "All". The group name is case sensitive.

If the default group can not be found a warning is sent to the MS3D message window, and MSCOMPASS is "just opened".

**searchdirs, required**

These are the directories that need to be searched. The general search pattern should be process dir, then MEDEXE dir.

**is_recurse_search, required**

When searching, should we recursively search through a directory

and its sub-directories (sometimes this would be a very slow operation) or should we just look in the directory. Set to true if you want to recurse, set to false otherwise.

exe...

Indicates that you wish to execute a program with arguments.

**program, required**

This is the program EXE that we are too search for.

**args, optional**

These are args that are applied to the given program. Tip, use the "ini" variables to get interesting results (see "Variable Substitutions" above).

**searchdirs, required**

These are the directories that need to be searched. The general search pattern should be process dir, then MEDEXE dir.

**is_recurse_search, required**

When searching, should we recursively search through the directory and its sub-directories (sometimes this would be a very slow operation) or should we just look in the directory. Set to true if you want to recurse, set to false otherwise. **is_dotnet, optional**

Set to false if the application is a "native" application. Set to true if it is a .NET application.

**reg, optional** This is where to go looking for the given reg_key. The registry search has a lower priority than the directory search. We will search in both "HKEY_CURRENT_USER" and "HKEY_LOCAL_MACHINE", in that order.

This is not the recommended way to search for a program, and is only maintained for some older programs.

**reg_key, optional**

Set this to a registry key that can be used in a last ditch effort to locate a file.

function........ This is a special type. It is used to invoke functions from within MS3D,but still give exterior control to such things as Title, Mnemonic, andrequirements.

**function, required**

The name of an entry in the msappmenu.c's "func_name_to_func" table. The program will attempt to invoke the given function in the table. An example of this type of menu entry would be the"ms3d_appmenu_mscompass.ini".

msge....

This will launch a python script as a MineSight(r) Grail Embeddedscript (MSGe).

**script, required**

This is the script file name that we are too search for.

**searchdirs, required**

These are the directories that need to be searched. The general search pattern should be process dir, then MEDEXE dir.

**is_recurse_search, required**

When searching, should we recursively search through the directory and its sub-directories (sometimes this would be a very slow operation) or should we just look in the directory. Set to true if you want to recurse, set to false otherwise. -------------ERROR LOGGING-------------

Errors are reported in a file called :file:`ms3d_appmenu.log` within theMS3D project directory (if and only if there is read access). Sometimesyou may be missing a product that has a corresponding INI file, in thatcase you may see spurious errors in the error log. Those errors are mostlikely OK.

--------EXAMPLES--------

SUB-MENU--------

The following is a simple example of setting up a sub-menu to launch twonative exe's.

::

[menu] title = My Applications mnemonic = M requires = any list = fizzle_wizzle, fuzzle_goozzle

[fizzle_wizzle] type=exe title=Fizzle Wizzle

mnemonic=F requires=any program=fizzle_wizzle.exe searchdir=$(MS3DProcessDir)\my_apps, $(MEDEXE)\my_apps is_rescurse_search=false is_dotnet=false

[fuzzle_goozzle] type=exe title=Fuzzle Goozzle mnemonic=F requires=any program=fuzzle_goozzle.exe searchdir=$(MS3DProcessDir)\my_apps, $(MEDEXE)\my_apps is_rescurse_search=false is_dotnet=false

This will make a menu entry that appears as,

:: My Applications->Fizzle Wizzle Fuzzle Goozzle

Each of these applications are searched for first under

:: [ms3d.exe dir]\my_apps [%medexe%]\my_apps

The search is not recursive.

MENU----

This example illustrates setting up a menu entry to launch a .NETapplication,

::

; This is a one-entry menu. [menu] list=watcha_ma_callit

[watcha_ma_callit] type=exe title=New Watcha Ma Callit mnemonic=N requires=watcha program=watcha.exe searchdir=$(MS3DProcessDir)\watcha, $(MS3DProcessDir)\watcha_beta, $(MEDEXE)\watcha, $(MEDEXE)\watcha is_recurse=false is_dotnet=true

That will make a new menu entry that looks like,

::

New Watcha Ma Callit

when the user clicks that menu entry, it will find the program ineither,

::

[ms3d.exe dir]\watcha [ms3d.exe dir]\watcha_beta [%medexe%]\watcha [%medexe%]\watcha_beta The search will not recurse into sub-directories.

LAUNCHING STANDALONE PYTHON SCRIPTS-----------------------------------

As an interesting aside, you can use these mechanics to launch a pythonscript. In this example, we will create a script called:file:`helloworld_project.py` and store it in a sub-directory of aproject at :file:`c:\\myproject`.

First, lets consider what the script will do. In this case the scriptwill take one parameter -- the project directory -- and print it on aTkinter dialog.

.. python::

import sys import Tkinter import tkMessageBox

tk = Tkinter.Tk() tk.withdraw()

# First argument to this script should be the project path, if not, # post a dialog and say bye, bye. try: project_path = sys.argv[1] except IndexError, e: tkMessageBox.showerror( "Error: Missing argument", "require path to project directory as first argument" ) sys.exit(-1)

lbl_helloworld = Tkinter.Label(tk, text="Hello World!") lbl_project = Tkinter.Label( tk, text=("The project is: '%s'" % (project_path)) ) lbl_helloworld.pack(padx=10, pady=10) lbl_project.pack(padx=10, pady=10)

tk.deiconify() tk.lift() tk.mainloop()

That's the script to print the dialog. Now lets create a "command file"

run python against this script.

::

SETLOCAL

:: Determine the directory that this script resides in. SET MYROOT=%~d0%~p0

:: Configure the pythonpath so future imports in the python script also :: look in the same directory as the helloworld script. SET PYTHONPATH=%MYROOT%;%PYTHONPATH%

:: Define a full path to the script. Quotes are IMPORTANT! SET SCRIPTPATH="%MYROOT%helloworld_project.py"

:: Determine how we are going to call PYTHON.EXE, if there is a hint to :: its location use it, otherwise, just rely on the path to define the :: location. IF /I [%PYTHONHOME%] NEQ [] SET CALL_PYTHON="%PYTHONHOME%\python.exe" IF /I [%PYTHONHOME%] EQU [] SET CALL_PYTHON=python.exe

:: Execute %CALL_PYTHON% %SCRIPTPATH% %*

ENDLOCAL

There are a few important items in this command script,

1. The ability to locate the directory that the command scripts resides within via the,

::

SET MYROOT=%~d0%~p0

this lets you,

a. Enhance the %PYTHONPATH% to ensure that when you do an import in Python, you also look in the same directory as your command script. b. This is really helpful if you are writing a script that uses some third party library, but you want to make sure your script works with a particular version. For example, consider that you want to use wxWidgets, you could then install your script as,

::

c:\myproject\python_scripts\my_script.py \wxWidgets\__init__.py ...other wxWidgets ...files...

Then if you ran this from the my_script.py,

.. python::

import wxWidgets print wxWidgets.__file__

you would get

::

c:\myproject\python_scripts\wxWidgets\__init__.py

you see, it picked up *your* wxWidgets first, not some global system one.

2. Ability to control how to run python, and what python to use. In this case we simply decided to either use the one defined by PYTHONHOME or default to the one located on the path.

Now that we have all that defined, lets create our appmenu INI file. Inthis case we will create a single entry,

::

[menu] list=helloworld_project

[helloworld_project] ; It is an EXE project, we are launching Python.exe type=exe title=Helloworld Project! mnemonic=H requires=anykey ; We want to spawn the command file that we created, since that file ; controls how the data is outputted. program=helloworld_project.cmd args=$(ProjectDir) searchdir=$(ProjectDir)\python_scripts is_recurse=false is_dotnet=false

You could have put the :file:`python_scripts` sub directory into the samedirectory as :file:`MS3D.EXE`, and get a result that runs across all projects ata particular site.

LAUNCHING MSGe PYTHON SCRIPTS-----------------------------

This can be best illustrated with an example,

::

[menu] list=em_info [em_info] type=msge title=Python/MSGRAIL Info mnemonic=P requires=anykey script=em-info.py searchdirs=$(MS3DProcessDir)\scripts, $(MEDEXE)\scripts is_recurse=false

This will create a menu entry called "Python/MSGRAIL Info" that when

activated will launch the "em-info.py" script as an "Embedded" script.

---FAQ---

1. I HAVE A DISABLED ENTRY? HOW CAN I TO ENABLE IT?---------------------------------------------------

First you should check the :file:`$(ProjectDir)\\ms3d_appmenu.log` filefor any hints. Second, ensure that your "requires" field is correct --it is case sensitive.