ROX-Menu version 0.6.2
Simple application menu for the ROX Desktop environment.
Web site: http://www.cs.sunyit.edu/~geerp/rox

Copyright (C) 2001 Leandro Pereira <leandro@linuxmag.com.br>
Copyright (C) 2002, 2003 Peter Geer <geerp@cs.sunyit.edu>

Current maintainer: Peter Geer <geerp@cs.sunyit.edu>

- - -

Introduction
~~~~~~~~~~~~

ROX-Menu is a panel applet for ROX-Filer and the ROX desktop that
pops up a menu that you can use to start your favorite application 
directories.  It serves the same purpose as the KDE "K" menu or the 
Windows "Start" menu.

Requirements
~~~~~~~~~~~~

ROX-Menu requires ROX-Filer version 2.0 or greater (http://rox.sf.net) and 
ROX-CLib version 1.1 or greater (http://www.kerofin.demon.co.uk/rox/libs.html) 
in order to run.

Installation
~~~~~~~~~~~~
To install ROX-Menu, simply extract the archive to the directory where 
you keep your ROX applications and click on the ROX-Menu application 
directory to run it.  When you first run ROX-Menu, it will compile 
itself if a binary is not present and create a default configuration 
if you do not have one.

Menu Configuration
~~~~~~~~~~~~~~~~~~
As of version 0.5.0, 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 done by renaming directories.  Please note that
the old "Apps" configuration file is still supported.  If the file is present,
it will be used, but it is considered deprecated.

To configure your menu, right-click on the running applet and select
"Choices dir...".  In the ROX-Filer window that pops up, there should be
a directory named "Menu_Root".  This directory represents the top-level
menu of ROX-Menu.  You can add menu items by adding AppDirs or symlinks
to AppDirs to this directory.  You can also create submenus by adding 
subdirectories containing AppDirs to the Menu_Root.  You can, likewise,
create as many levels of submenus as you like by adding subdirectories
to the subdirectories. These can be real directories containing symlinks to 
AppDirs, or symlinks to real directories, or a combination of real AppDirs, 
directories, and symlinks.  Note that ROX-Menu will ignore hidden files
and directories and will ignore all regular files, i.e. not AppDirs or
symlinks to AppDirs.

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 via a call to 
system() when the menu is built or refreshed.  ROX-Menu will report an error if
the program exits with a non-zero status, but no other error checking is done.  

The MenuRun file can be used as a method for dynamic menu building or keeping 
the menu automatically synchronized with a directory.  There is an example
MenuRun script in the ROX-Menu Help directory with a couple of supporting 
scripts.  
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.

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.

Multiple Independent Configurations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
As of RoX-Menu 0.5.0, it is possible to run multiple, independent
ROX-Menu configuration simultaneously.  This will allow you to put two
instances of ROX-Menu in your pane, but have them display different
menus, have different icons, and different behavior.

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" configuration will be stored in a directory
named Start-Menu located under your Choices directory. 

Options
~~~~~~~
There are a few configuration options for ROX-Menu that can be modified 
by choosing "Options" from the context menu.  These options are separated into
two sections.  You can change sections by clicking on the "Button" or "Menu" 
labels in the box on the left.  Most options will take effect as soon as the 
change is made.  Exceptions are noted.

In the "Button" section, there are options to change the maximum height and 
width of the ROX-Menu icon.  Rather than displaying the image at actual size, 
ROX-Menu will scale the icon such that it is no larger than the height and width
specified here.  Since the size of the icon determines the size of the applet, 
you can scale the icon down if ROX-Menu makes your panel increase in size.  The
default maximum sizes are 38 pixels high and 60 pixels wide, which corresponds 
to the default icon.

There is also an option to set the "Mouse-over" and "Normal" icons for the menu.
These are simply the icons that are displayed when your mouse is over the applet
or not over it, respectively.  They can be in any format and should be between 
30 and 50 pixels high for most panels.  The default icons are images of the ROX
eagle.  (The mouse-over icon is the same image as the normal icon, but darkened
slightly.)  There are some alternative menu icons in the src/Alt_Icons and 
src/Old_Icons directories.

In the "Menu" section, there is an option to control the position of the group 
entries in nested submenus.  By default, they are at the top of the submenu.
When the "groups on bottom" option is specified, nested group entries
will appear at the bottom of the submenu after all the AppDirs are listed.

There is an option to strip initial numbers from entry names.  When this is set,
ROX-Menu will examine the name of each AppDir and directory it adds to the menu.
If the name starts with a digit (0-9), then ROX-Menu will search for the first 
underscore in the name and set the menu item text to everything after this 
point.  Thus, the name "1_Sylpheed" would display as "Sylpheed" and "2a_Opera" 
as "Opera".  Since the menu items are sorted alphabetically, this allows you to
manually sort the names without having them displayed in the menu.

The "group entry image" and "application image" are the files that will be used
for the default image when a directory or AppDir does not have an icon of its 
own.  If these are empty, ROX-Menu will default to the built-in images.  These
options require a manual refresh to take effect.

Lastly, there are the options to control the maximum height and width of the 
images used for menu entries.  The icons for AppDirs and directories in the menu
will be scaled to be no larger than the dimensions specified here.  These 
options also require a manual refresh to take effect. 

License
~~~~~~~
This program is licensed under the GNU General Public License version 2.
A copy of the license is available in the COPYING file located in this
directory.

