ROX-Menu 
An application menu for the ROX Desktop environment.
Web site: http://www.skepticats.com/rox

Copyright (C) 2001 Leandro Pereira <leandro@linuxmag.com.br>
Copyright (C) 2004 Peter Geer <peter@skepticats.com>

Current maintainer: Peter Geer <peter@skepticats.com>

- - -

Introduction
~~~~~~~~~~~~
ROX-Menu is an application launcher that works with the ROX Desktop.  It
doubles as a "Start-menu" panel applet and a popup menu.  It allows you to 
create menus to launch applications and open files.  In keeping with the 
philosophy of the ROX Desktop, ROX-Menu uses the filesystem to build configure 
the menu rather than a traditional menu editor.

Requirements
~~~~~~~~~~~~
ROX-Menu requires ROX-Filer (any version) (http://rox.sourceforge.net),
GTK+ 2.2 or greater (supplied with most modern Linux distributions), and 
ROX-CLib version 1.1 or greater (http://www.kerofin.demon.co.uk/rox/libs.html). 

Installing and Running ROX-Menu
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
ROX-Menu is packaged as a ROX Application Directory (AppDir), so there is no 
installation required - just extract the compressed archive to the location 
of your choice and run it.  To run it as a "Start menu" applet, drag the
AppDir to your panel and it will display a button with an eagle icon on it.  
Clicking the icon will display an application menu.  Right-clicking it will 
display the configuration menu.  

Running ROX-Menu as a windowless popup menu is a bit more involved.  Please 
see the section below entitled "Key Bindings and Popup Menus" for instructions.

Menu Configuration
~~~~~~~~~~~~~~~~~~
ROX-Menu uses the filesystem for configuration.  Adding items to the menu is 
done by creating links and directories, while sorting of menu items is 
alphabetical and is done by renaming directories.  

Please note: the old "Apps" configuration file, which was deprecated in
version 0.5.0, is no longer supported as of version 1.0.0. 

To configure your menu, right-click on the applet button and select
"Menu setup...".  This will display some basic instructions and pop up 
the directory that represents the top-level menu of ROX-Menu.  You can 
add items to the menu by adding or linking files, AppDirs, and directories 
to this location.  Each directory will be treated as a submenu and each 
AppDir will be treated as a regular menu entries.  If you set the option to show
regular files (i.e. not directories or AppDirs), those will also be displayed 
as menu entries as well.  ROX-Menu will ignore hidden files and directories, as
well as any directory or AppDir that contains a file named ".rox-menu_ignore".

As an example, suppose you have a $HOME/Apps folder that contains some AppDirs,
a Games folder, and an Applets folder.  If you add a link to $HOME/Apps in your
top-level menu folder, ROX-Menu will add an "Apps" submenu to your top-level
menu.  This submenu will contain the AppDirs in $HOME/Apps as well as a "Games"
and an "Applets" submenu, containing entries for the AppDirs in $HOME/Apps/Games
and $HOME/Apps/Applets respectively.  If you wanted to exclude the Applets
subdirectory from appearing in the menu, you would create a .rox-menu_ignore
file inside it.

Key Binding and Popup Menus
~~~~~~~~~~~~~~~~~~~~~~~~~~~
ROX-Menu supports popping up the menu via a command-line option.  There
are three relevant options:
--menu       Pops up the main application menu.
--sys-menu   Pops up the right-click context menu.  
--no-window  Starts ROX-Menu without creating a window.

To make a key press pop up the application menu, simply use your window
manager configuration program to bind a button to this command (assuming you
placed ROX-Menu in $HOME/Apps):
    $HOME/Apps/ROX-Menu/AppRun --menu
You can use this to make your "Windows" key pop up the menu, for example.
	 
To use ROX-Menu like a widnow manager popup menu, create an executable 
shell script in your ROX-Session AutoStart folder that contains the following:
    #!/bin/sh
    exec $HOME/Apps/ROX-Menu/AppRun --no-window
(If you don't use ROX-Session, you can add the command to the appropriate 
initialization file for your window manager.)  Then, use your window manager
configuration program to bind the command "$HOME/Apps/ROX-Menu/AppRun --menu" 
to the desired key or mouse button.  You might use this to make ROX-Menu show 
a popup menu when you right-click on the desktop.  This is handy if your window
manager doesn't provide a popup application menu (or if it does, but the 
menu is slow, a pain to customize, and not very attractive, like Sawfish).

If you want to use both a panel menu and a popup menu, you will have to use 
two independent configurations (described below).  To do this, simply make a 
link to the ROX-Menu application directory by running a command like this:
    cd $HOME/Apps ; ln -s ROX-Menu Popup-Menu
You can then drag the ROX-Menu AppDir to your panel and setup the popup menu 
using the above procedure, but using $HOME/Apps/Popup-Menu instead of
$HOME/Apps/ROX-Menu.  Using this method, you will be able to configure each
menu seperately and you will also still be able to pop up the panel menu with 
a key binding.  Please note that you will need to run the command 
    $HOME/Apps/Popup-Menu/AppRun --sys-menu
to bring up the configuration for the popup menu.  For convenience, you may wish
to add an AppDir wrapper to your menu to run this command.

Menu By Script
~~~~~~~~~~~~~~
Many popular window managers provide a facility to build a menu from script 
output.  This configuration method is undoubtedly useful, but it runs counter to
the easy-to-use, filesystem-based model of ROX.  As a compromise, ROX-Menu 
provides an option to run an arbitrary executable when the menu is refreshed.  
This executable must be located in the ROX-Menu choices directory and must be 
named "MenuRun".  If present, this program will be executed every time the menu
is refreshed.  ROX-Menu will report an error if the program exits with a 
non-zero status, but no other error checking is done.  

Please note that this is not the recommended method of menu configuration and 
you should not use it unless you're certain you know what you're doing.

Multiple Independent Configurations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
It is possible to run multiple, independent ROX-Menu configuration 
simultaneously.  This will allow you to put two or more instances of ROX-Menu 
in your panel, and have them display different menus, have different icons, and
different behavior.  This is also handy if you want ROX-Menu in your panel and 
also want to use it as a window manager-style popup applciation menu.

To do this, simply create a copy of or symlink to the ROX-Menu AppDir
with a different name and the configuration will be stored in your
Choices directory under a directory of the same name.  For example, you might 
create a symlink to ROX-Menu called "Start-Menu".  You can then drag the 
"ROX-Menu" and the "Start-Menu" AppDirs to your panel and run them both.  The
configuration for the "Start-Menu" AppDir will be stored in the 
$HOME/Choices/Start-Menu directory while the regular ROX-Menu AppDir will store
its configuraiton in the normal $HOME/Choices/ROX-Menu location. 

Drag-and-Drop Launching
~~~~~~~~~~~~~~~~~~~~~~~
As of ROX-Menu 0.6.2, you can drag files from a ROX-Filer window onto the 
ROX-Menu button to open them.  The file paths are converted to local paths and
passed to the "rox" script (found via the PATH environment variable), which
should have the same effect as dropping the files on the ROX-Filer AppDir, i.e.
they will be opened with whatever default program is specified for them by
ROX-Filer.

License
~~~~~~~
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
