Common Features of the MIEN GUIs

All of the MIEN toplevel GUIs are derived from the MIEN "BaseGUI" class, which provides some common behaviors. Custom user or extension GUIs that derive from this class and use its methods will also have these common behaviors.

Menu Commands

Mac OS X Note

If you use Mac OS, note that MIEN windows each provide their own menu bar, at the top of the window. This behavior applies to all platforms, and differs from the typical Mac behavior of one menu bar per app, at the top of the screen. When MIEN is active, the Mac menu bar will contain a single "Python" menu, which has no useful functions other than to quit the app (which can also be done from the File menu of the main window).

Some versions of MIEN have an incompatibility with some versions of Mac OS which prevents MIEN from correctly detecting that it is running on Mac. If this happens, the menu bar will display at the top of the screen, rather than the top of the window. This is a bug (descibed here), and should be corrected by updating MIEN. MIEN is usable in this single-menu bar state, but some operations are cumbersome and error prone. If an update doesn't resolve the issue, please report the bug, along with your version of MIEN and your version of Mac OS.

Standard File Menu

Most MIEN apps have a File menu as the first (left-most) menu in the menu bar, and this menu provides a set of common functions, as well as some functions specific to a particular app. In a few add-on GUIs the first menu may not be named File, but may still provide some or all of these standard File menu functions.

• New Document

  Create a new, blank, document, discarding any data from the old one. MIEN apps will always have a current document. If they are opened without one, they create one automatically, so this function is mostly useful if you want to discard a document and start over without restarting MIEN. WARNING - MIEN does not ask for confirmation here or anywhere else where a user action might destroy data. That is a design decision. Undo functionality is unstable and often not available, which is a bug (or incomplete feature). Be careful, and save your changes using files or checkpoints.

• Load

  Load a new document. This function displays a file dialog for you to select a file, and loads the mien document specified by that file (provided that MIEN knows how to read it). This document then replaces the current document. This will delete any unsaved changes to the current document. It is exactly equivalent to calling "New Document" followed by "Append".

• Append

  This function loads elements from a new file and concatenates them with the current file. Usually concatenation is done by adding every top level element of the new file as a new top level element of the current file. Names of the added elements may be automatically changed to maintain unique paths for all the elements in the current file. Some apps, notably the DataViewer, may define specialized concatenation methods for particular element types.

• Append Subset

  Choose a new file to open, and select a list of individual elements from that file to concatenate with the current document. Append Subset provides a graphical tree browser for selecting the subset of elements. Note that there is no "Load Subset" function, but that functionality can be simulated using "New Document" followed by "Append Subset".

• Save

  Write the current document to a file. If the document has been loaded from a file, or previously saved, this function will write to the same file name and file type as the previous file without prompting the user. Otherwise, it will act the same as "Save As"

• Save As

  Open a dialog allowing the user to select a file name and type, and save the current document to the specified file. The "Format" field in the dialog determines the type of file to save. The default value "guess from filename" is usually a good choice, but if you use it, you must include a recognized file type extension in the file name you enter. For example "model.mien" or "data.mat". Entering a name without an extension with the "guess from filename" type probably usually raises an error (and not a very informative one, sadly. "format bbt is read only" is a common example). If you don't know what extension to use, select the format you want from the format pull-down. If you choose a format other than "guess", the correct extension is automatically added to you file name. If you select a general format, such as "mien" or "nmpml", all elements in the current file are saved into a single file. If you select a specialized format, such as "txt" or "jpg", only certain elements will be saved. This may result in no file being saved, if no elements of appropriate type are in the current document. If a file format can only contain a single element, and the document contains many elements of the correct type, the behavior of different MIEN GUIs varies. DataViewer will usually save multiple files, one for each element. ImageViewer and CellViewer will usually save the first appropriate element that they find. If this isn't the one you want to save, use "Save Subset" to specify a single element to save.

• Save Subset

  Select one or more elements from the current document, and save a new document containing only these elements, using the same file dialog used by "Save As".

• Preferences

  Launch the preferences editor for the current GUI. The content of this dialog will be different for each GUI, and the individual preferences will be described in the manual for the current GUI. Preferences tend to control which elements are displayed by a GUI, and how to display them. For all MIEN applications, preferences are saved in hidden files in the user's home directory (by default the preferences file will be $HOME/.mien/NameOfGUI). Preferences are persistent between MIEN sessions. Occasionally, upgrades of MIEN can cause problems if you have particular saved preferences that are now obsolete. If you upgrade and find that you can't run a GUI, or can't run the preferences dialog for a GUI, you can try deleting the saved preferences file for that GUI, running it again, and reseting your preferences from this menu option.

• Quit

  Close the current GUI. If the current GUI is also the "master" GUI (almost always the first GUI you launched in the current MIEN session), this will also close all other GUIs and exit MIEN (unless there are Python shells open as well - these can't be terminated from within a GUI, only from the shell itself). If the current GUI is not the master, this menu will close the current GUI and its children (GUIs that were spawned using menu options in the current GUI), but not its parents or siblings. In some cases, using File->Quit is "cleaner" than closing the GUI with a window manager shortcut (such as Alt-F4 on Windows or Cmd-Q on Mac), or with the "close" button on the GUI's window frame, but in most cases all these actions are equivalent.

Python Menu

Most MIEN GUIs have a "Python" main menu, although a few of them don't, or only have the menu when they are the master GUI. When this menu is present, it provides access to a Python interpreter that is bound to the current GUI. Since Python doesn't limit access to object members, this interpreter can be used to change the state of the GUI or any element of the current document in any way that you like. This can be very useful when experimenting with new analysis protocols or when writing extensions. If you need to examine the internal state, or make a quick change that isn't provided by a GUI function, the interpreter can do this for you. Needless to say this is also quite dangerous. It is easily possible to produce unstable states in the GUIs by changing things at the command line. Save your data and/or know what you are doing. Also, changes in state created at the command line are not monitored by the GUIs. You will need to manually refresh displays to see the changes you made, and you will usually not be able to use GUI Undo functions. Still, the payoff for working in this somewhat unstable environment is tremendous power and flexibility.

When you launch a Python shell from this menu, the name gui will be bound to the current GUI in the Python environment. This name gives you access to the GUIs methods and state. Since every MIEN gui carries a reference to the current document in the data member document, the interactive command line can access the current document using gui.document. To figure out what you can do with these objects, you will need to read some of the MIEN API documentation. Of course, if you are familiar with Python's introspection abilities, you can also poke around in the interpreter and see what you find. For example dir(gui), dir(gui.document), help(gui.document.getElements). Many GUI methods are undocumented at the source code level, so, for example help(gui.save) isn't very informative. Most of the methods of NMPML objects (elements of MIEN documents) are documented, though, so help(gui.docement.xpath) is more informative.

Which commands you have available at the Python menu depend on how you run MIEN, and what Python packages you have installed.

• GUI Command Line

  This is always available. It launches a "PyCrust" graphical Python shell. This shell is rather unstable and cumbersome to use compared to a terminal-based shell, but it does provide a lot of assorted information, and it is always available, even if you ran a binary port of MIEN.

• Command Line

  This option is available if you have a controlling terminal for MIEN. It opens a Python interpreter in that terminal, which is exactly like the one you would get by calling "python" from a prompt in that terminal (except that the name "gui" and a few other variables are bound to special values).

• iPython

  This option is available if you have a controlling terminal, and you have installed the "iPython" package for your Python interpreter. iPython is a nicely enhanced interactive Python shell that requires less typing than normal python, better access to operating system services, and reasonably good Tab completion. The iPython environment will be much more familiar to users that are used to the Matlab interactive shell. The one disadvantage to iPython is that stack traces (error reporting) are tremendously verbose, so debugging deeply nested functions can be harder than in normal Python. For any other purpose, though, if you have iPython, use it.