Mint-FM2 v3.xx - Documentation

shane
  13 years ago
  6

What is Mint-FM2?

Mint-FM2 is the auto-generated and auto-updating menu system used in Mint 9 Fluxbox Edition and newer. Releases older than this use an older version which is very different. The menu is accessed by right clicking on the desktop in Fluxbox.

The generated menu is compliant with the freedesktop.org standards. Hence, it is comparable to menus found in other desktop environments like Gnome, KDE, etc. Also, it will generate the menu in the user's default language provided translations are available and it can detect application icons provided the icon is supported by Fluxbox (PNG or XPM format).

General use

In normal use, Mint-FM2 is designed to take care of the Fluxbox menu for you. No user input or maintenance is required (if all works well). It generates the menu and it keeps it updated automatically.

Using Mint-FM2

Mint-FM2 can be run from the terminal with the following options
mint-fm2 [generate|generate-gui|update|start|restart|stop|debug]

 

  • generate: Generates a new menu while preserving user changes.

  • generate-gui: Generates a new menu while preserving user changes with a GUI progress bar.

  • update: Updates the existing menu to the current set of installed applications.

  • start: Starts the user daemon that monitors for application changes.

  • restart: Restarts the user daemon that monitors for application changes.

  • stop: Stops the user daemon that monitors for application changes.

  • debug: Launches the debug prompt for expert users.

 

Installed files and directories

The system files for Mint-FM2 are installed in /usr/lib/linuxmint/mint-fm2/. In addition to this directory, when Mint-Fm2 is run for the first time, it creates the Fluxbox menu file ~/.fluxbox/menu, the custom menu file explained below and a hidden folder ~/.mint-fm2 which contains the auto-generated menu and other files it requires.

The configuration file

Keeping with the spirit of Fluxbox, Mint-FM2 is highly configurable. The default location for the Mint-FM2 configuration file is ~/.mint-fm2/mint-fm2.conf. A copy of the default configuration file is located at /usr/lib/linuxmint/mint-fm2/mint-fm2.conf. If you need to restore the default settings you can replace your configuration file with this one.

Configuration options

 

  • MENUTITLE - This defines the main title of the Fluxbox menu

  • ENTRYORDER - This defines what menu entries should be included in the menu. It also defines the order in which they appear (top to bottom).

  • FBCUSTOM - This defines the custom menu entries file.

  • ICONS - This turns on (TRUE) or turns off (FALSE) menu icons in Fluxbox.

  • ICONTHEME - The value here should be the FULL PATH to the directory containing the icon theme you wish to use.

Examples and available options for the various configurations are available in the configuration file itself.

Custom menu entries file

This is the file defined in the FBCUSTOM option above. In this file you can add entries or import other files, etc using the standard Fluxbox format for menus. The entries in this file will be included into the menu in the location determined by the ENTRYORDER option.

Menu entry tags

The auto-generated menu entries are stored in files located in ~/.mint-fm2/submenus. A file for the menu categories and one for each category is created, all in standard Fluxbox menu format.

A 'tag' is appended to each entry when it is created. Whenever the menu is updated, Mint-FM2 checks the tag for each entry. This provides the user the option to instruct Mint-FM2 how to deal with the entry. There are three (3) available states for each entry.

 

  • Mint-FM2 controlled entries:
    ###-[name of .desktop file]
    This tag indicates that the entry is controlled by mint-fm2. It will be updated/deleted irrespective of user changes. These entries will be recreated when the menu is regenerated.

  • User controlled entries:
    #+#-[name of .desktop file]
    This tag indicates that the entry is under the user's control. Mint-fm2 will detect it and will not add a second entry of the same .desktop file. These entries will remain unchanged even if the menu is regenerated. To take control of a menu entry, edit the tag to this format.

  • Entries with no tags:
    These entries will be ignored by Mint-fm2 and will remain unchanged even if the menu is regenerated. However, it will still generate the normal ###-[name of .desktop file] tagged entry probably giving duplicate entries.

 

Use cases

 

  • To generate a new menu from scratch:
    1. Open a terminal
    2. Delete ~/.fluxbox/menu and ~/.mint-fm2
    3. run 'mint-fm2 generate'

  • To add an entry in the top section of the menu:
    1. Open the custom menu entry file defined by FBCUSTOM (default is ~/.fluxbox/customMenuEntries)
    2. Add the custom entry

  • To have only the Home directory, web browser and quit dialog in the top section and the generated menu below with a separator in between:
    1. Open ~/.mint-fm2/mint-fm2.conf
    2. Edit ENTRYORDER to
    ENTRYORDER=("homeEntry" "browserEntry" "quitEntry" "separator" "generatedEntry")
    3. In a terminal run 'mint-fm2 generate'

  • To start Firefox with the profile dialog (customizing menu entries)
    1. Open the submenu file (~/.mint-fm2/submenus/Internet)
    2. Change the menu entry (replace 'firefox' with 'firefox -p')
    3. Make the entry user controlled to prevent automatic changes (change the '###' tag to '#+#')
    4. Save the submenu file.

The above information should be enough for almost all situations. Below is information for more advanced use and debugging. It is not required for normal use.

Debug mode

The debug mode is a customized Bash shell which can be used in a variety of ways for more complex tasks. Customizations of the Bash shell include:

  • a custom $PATH that only provides commands used by Mint-FM2 and builtin commands.

  • functions and variables generated and used are automatically sourced and available in the shell.

  • it runs in a verbose mode giving informative output at each stage.

 

While in debug mode, run 'welcomeMsg' and 'help' for some information.

Debug mode use cases

* 'Mint-FM2 >>' in the code below is to differentiate the debug mode from normal Bash shell. You do not have to type it.

 

  • Menu not being generated properly:
    1. Start the debug mode
    mint-fm2 debug
    2. Generate the menu
    Mint-FM2 >> utilsGenerate
    3. Watch the output for errors
    4. For even more detailed output
    Mint-FM2 >> set -x
    Mint-FM2 >> utilsGenerate

  • Check variables used by Mint-Fm2
    1. Start the debug mode
    mint-fm2 debug
    2. Print all relevant variables to stdout
    Mint-FM2 >> echoVariables

  • Check all generated entries
    1. Start the debug mode
    mint-fm2 debug
    2. Print all menu entries to stdout
    Mint-FM2 >> getAllApps

  • Generate a menu entry for a specified application (e.g. Abiword)
    1. Start the debug mode
    mint-fm2 debug
    2. Set the RAWINDEX variable for the application in Mint-FM2
    Mint-FM2 >> getIndex
    ==> Enter the application or category to search for:
    >>> abiword
    ==> Search in new or current list? [n/c]
    >>> c
    137:-abiword.desktop
    ==> Please enter the number corresponding to the best match
    >>> 137
    ==> RAWINDEX has been set to 137
    ==> You can now run other functions

    3. Output the entry
    Mint-FM2 >> createAppEntry
    [exec] (Traitement de texte AbiWord) {abiword} </usr/share/icons/gnome-colors-common/16x16/apps/abiword_48.png> ###-abiword.desktop

Comments
shane 13 years ago

Yes, this is for version Mint 9 Fluxbox and later. It is still in testing. This version is a lot different from previous versions... many improvements were made. And since the Wiki is down and I needed to update the documentation for the upcoming release, posted here.

I hope it will be useful and if you need more clarification on anything, just let me know.

Thanks.


remoulder 13 years ago

Good one Shane!