=============================== ``grail.compass.cmpsys`` module =============================== .. include:: ../version.h .. include:: ref.h .. contents:: Table of Contents :backlinks: top ----------- Description ----------- This module contains all the standard function calls that can be made in the context of a compass-style script. --------- Functions --------- :df:`executeprocedure(exename, runfiledir, runfilename)` Utility, executes the executable against the run file. Assuming that the runfile is dumped into the project directory. It starts a search for the executable with in this order: 1. local directory 2. project directory 3. METLIB directory If we are unable to locate the executable, we simply run it without an explicit directory, and rely on the fact generally %MEDEXE% is on your path. This function is equivalent to making the following call: \\ /f Where the was determined by the above rules. Arguments: :a:`exename` : string Name of the executable. :a:`runfiledir` : string The directory to perform the execution within. :a:`runfilename` : string Name of the run file to pass to the executable. :df:`fromcommandline(argv, mainfn)` Utility to allow you to run compass-style procedures from the command line. This function also goes ahead and attempts to read the command line arguments for various options. When executing the procedure from the command line use --help (-h) for a usage message. You can also see the help message by inspecting cmpsys.COMMANDLINE_USAGE. Arguments: :a:`argv` : list of strings The :d:`sys.argv` [#python-lib-sys]_ variable's contents. :a:`mainfn` : function A reference to your scripts gmain function Returns: === ========================================================== 0 Indicates the user simply quit the panel-application window. 1 Indicates that the user wanted to execute their procedure against the sub-routine === ========================================================== Side-effects: If a -h or --help option is found in the command line arguments, the program will display an usage message to sys.stdout, and the script will terminate via a :f:`sys.exit(0)` call. If an unknown option is found in the command line arguments, the program will display an usage message to sys.stderr, and the script will terminate via a :f:`sys.exit(-1)` call. If an program error occurs, such as selecting an invalid project file with the command line option or anything else, then a :f:`sys.exit(-2)` is generated. :df:`getfilelistbytype(type)` Returns a list of files for a given type. This examines the Project Control File (PCF) and the project directory to return a listing of files for a given type. So for example, say the PCF had the following file 15s listed in it, * :file:`test15.dat` * :file:`test15.blt` * :file:`test15.slt` But the project directory only had the :file:`test15.blt` file located in it, then a call to this function would return, .. Python:: ["test15.blt"] This is useful, since most of the time a user may have only copied a select list of files that are described within the PCF's file 15 list. :df:`getmetlibdir()` Returns the location of the METLIB directory. The location is determined by the METLIB environment variable. If the environment variable is not defined, then an empty string ("") is returned. :df:`getmode()` *For internal usage only*. Returns the current mode. :df:`getpanel(panelname)` Retrieves a panel reference from the currently active procedure based on the title (or :a:`panelname`) of that panel. There are two major assumptions that are made when you call this function: 1. That the panel has already been constructed. The order of construction is not guaranteed, so its best not to call this function within the context of :f:`GPanel.makewidgets()`. 2. That there is an active procedure window open. When the procedure window closes, all resources are released, which implies that we can no longer access the panels. This function could generate either a * :e:`GWidgetError` if no panel exists with that panelname. * :e:`AttributeError` if the application is not running. :df:`getpcf()` Returns the current :c:`Pcf` object used by the grail compass system. :df:`getproject()` Returns a :c:`ProjectInfo` reference for the currently active project. :df:`getrunfilepath()` Returns the directory location for the run file. :df:`gmain(message, data)` Standard compass gmain. .. Note:: That the :f:`grailmain` function defined in the grail.gsys_ module will automatically select this function and all its configuration options, if and only if you are running within a compass application. In other words, you do not need to insert any reference to this function within your script. :df:`isgo()` Indicates if a procedure was a go (1) or not (0). :df:`ismultirun()` Predicate indicates if we are in multi run mode or not. :df:`ismultirunsetup()` Predicate indicates if we are in multi-run setup mode or not. :df:`itemlistforfile(filename)` Returns a sorted list of items for the given :a:`filename` assuming that :a:`filename` is part of the current PCF. If the :a:`filename` is not part of the filelist expect a :e:`PcfError` to be generated. :df:`runprocedure(procfilename, proctitle, panellayout[, startpanel, version, copyright, aboutphotoimage])` Starts the procedure's window and event loop. Arguments: :a:`procfilename`: string The name of the procedure, typically :a:`sys.argv[0]` [#python-lib-sys]_. :a:`proctitle` : string Title of your procedure. :a:`panellayout` : :c:`GFolder` The layout structure for the panel application, using the :c:`grail.widgets.GFolder` and :c:`grail.widgets.GItem`. :a:`startpanel` : string Optionally specify, currently by title, the name of the first panel you want to display. Default is not to display any first panel. :a:`version` : string A string indicating the version (for the about window). :a:`copyright` Copyright notice (for the about window). :a:`aboutphotoimage` A :c:`Tkinter.PhotoImage` [#tkinter-photoimage]_ object (for use in the about window). :df:`setmode(mode)` *For internal use only*. Sets the execution mode: standard, multi-run, or multi-run-setup. Valid arguments are: :d:`message.STANDARD`, :d:`message.MULTIRUN`, or :d:`message.MULTIRUN_SETUP`. :df:`setproject(path)` Sets the compass system's project and Project Control File (PCF) based on the info in the path. :df:`startmxepert(mxpertstring)` Will take the :a:`mxpertstring` and insert it into a batch file. The batch file will have a :mxend label, and will set minteract equal to "on" at the start, and equal to nothing at the end. For example, the following string, :: REM this is a test. will generate the following batch file, :: set minteract=on REM this is a test :mxend set minteract= If your compass style script is being executed from the command line, then you will need to use this function in order to execute the contents of your mxpert string. :df:`stdinipath()` Returns path to the grail procedures configuration file. Location is determined by examining the User's ROOT_DIR. The grail procedures configuration filename is defined by this modules :d:`CMPSYS_USR_FILE` constant. --------- Exception --------- exception :de:`CompassError` Defines the standard error from the compass package. ---- Data ---- :dd:`CMPSYS_USR_FILE` Defines the name of the standard procedure INI file name. :dd:`COMMANDLINE_USAGE` Defines the command line usage. This message is displayed if, 1. A compass-style script is created. 2. The script uses :f:`fromcommandline()`. 3. The user types --help (-h) to display the usage message. .. [#python-lib-sys] "sys -- System-specific parameters and functions." *Python Library Reference*. 28 May 2004. 21 December 2001. .. [#tkinter-photoimage] Lundh, Fredrik. "The PhotoImage Class". *An Introduction to Tkinter*. 28 May 2004. 1 December 1999.