wmpamgen Code
Preferred applications menu generator for Fluxbox,OpenBox,Window Maker
Brought to you by:
phenixia2003
Menu
▾
▴
Tree [10961f] default tip / History
Read Me
__ ___ __ ___ _ __ __ _ _ __ ___ __ _ ___ _ __
\ \ /\ / / '_ ` _ \| '_ \ / _` | '_ ` _ \ / _` |/ _ \ '_ \
\ V V /| | | | | | |_) | (_| | | | | | | (_| | __/ | | |
\_/\_/ |_| |_| |_| .__/ \__,_|_| |_| |_|\__, |\___|_| |_|
| | __/ |
|_| |___/
About
-----
wmpamgen is designed to generate a menu to ease access to user's preferred
applications under the following window managers :
Fluxbox
Openbox
Window Maker
The menu is generated according to the installed applications, and, the
user's preferred applications given as a list of .desktop file names.
The generated menu only includes entries for the preferred applications
which are already installed when wmpamgen is run. Therefore, to ensure
the menu is up-to-date, wmpamgen needs to be run on a regular basis: at
startup of the window manager, or when application(s) is/are installed or
removed for instance. Under Linux, this can be automated using the inotify
API.
Requirements
------------
* cmake
Installation
------------
To compile wmpamgen with default settings and install it in /usr/bin, run
the following commands :
8<--------------------------------------------------------------------
$ mkdir _build
$ cd _build
$ cmake -DCMAKE_INSTALL_PREFIX=/usr -DCMAKE_BUILD_TYPE=Release ..
$ make
$ make install
8<--------------------------------------------------------------------
Note that Native Language Support (NLS) can be disabled by passing
-DENABLE_NLS=OFF to cmake.
Usage
-----
wmpamgen requires a configuration file that must be specified in argument
of option --config, like in example below :
8<--------------------------------------------------------------------
$ wmpamgen --config /path/to/wmpamgen-sample.conf
[11:06:55] Configuration:
[11:06:55] target-window-manager : fluxbox
[11:06:55] enable-icons : 1
[11:06:55] preferred-applications : xterm,htop
[11:06:55] desktop-file-search-path : /usr/share/applications
[11:06:55] icon-search-path : /usr/share/pixmaps
[11:06:55] preferred-terminals : /usr/bin/xterm
[11:06:55] top-separator : 0
[11:06:55] bottom-separator : 0
[11:06:55] Generates the menu ...
[11:06:55] 8<-------------------------------------------------------
[exec] (XTerm) {xterm} </usr/share/pixmaps/xterm-color_48x48.xpm>
[exec] (Htop) {/usr/bin/xterm -e htop} </usr/share/pixmaps/htop.png>
[11:06:55] 8<-------------------------------------------------------
[11:06:55] Done (28 ms).
[11:06:55] Exiting...
[11:06:55] Cleaning all resources and memory in use....
[11:06:55] Done.
8<--------------------------------------------------------------------
In the example above, wmpmangen is run with a configuration to generate a
menu of preferred applications to fluxbox format. 1st, wmpamgen prints the
current configuration on stdout, then the menu is generated and printed on
stdout, and wmpamgen exits.
To prevent wmpamgen to print informational messages, the option --quiet must
be passed on the command line :
8<--------------------------------------------------------------------
$ wmpamgen --quiet --config /path/to/wmpamgen-sample.conf
[exec] (XTerm) {xterm} </usr/share/pixmaps/xterm-color_48x48.xpm>
[exec] (Htop) {/usr/bin/xterm -e htop} </usr/share/pixmaps/htop.png>
8<--------------------------------------------------------------------
Note that wmpamgen terminates with exit-code 0 on success, 1 otherwise.
Configuration File
------------------
The configuration file passed in argument to option --config must be to
plain text format with entries to the format :
property=value
Commented lines, i.e. which start with a # - preceded or not by space(s) -,
are ignored.
Spaces at both side of loaded values are automatically removed.
When there are more than one occurence of a given property, only the first
value is loaded, the others being ignored.
Here is the list of supported properties :
target-window-manager
---------------------
The name of the window-manager for which the menu must be generated. Can
be one of the following :
fluxbox
openbox
windowmaker
enable-icons
------------
Defines whether or not the generated menu must includes the icons (when
available) for the preferred applications.
Can be set to: 1,true,on,yes,0,false,off,no.
Note that Window Maker does not support icons in menus, and thus, the
property enable-icons is ignored when this window manager is selected.
preferred-applications
----------------------
The user's preferred applications as a comma separated list of entries
using the syntax :
list ::= <entry>[,<list>]
entry ::= <item>[:<item>]
item ::= <pathname>|<name>
Each entry in this list can be :
1. The absolute path of a .desktop file.
2. A .desktop file name, with or without .desktop extension in which
case wmpamgen selects the 1st matching .desktop file found on the
'desktop file search path', if any.
3. An alternative-expression as a colon separated list of .desktop
file (path)names. In such case, wmpamgen selects the 1st of the
specified (path)names found on the system, if any.
The property preferred-applications must be set to "" when there is no
preferred applications defined.
desktop-file-search-path
------------------------
Colon separated list of path to prepend to the ".desktop files search
path", which is initially set to :
XDG_DATA_HOME/applications:XDG_DATA_DIRS/applications
When XDG_DATA_HOME is either not set or empty, a default equal to
$HOME/.local/share is used.
When XDG_DATA_DIRS is either not set or empty, a default equal to
/usr/local/share:/usr/share is used.
see https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
icon-search-path
----------------
Defines the 'icon file search paths'. This must be a colon separated list
of the paths in which to search for the icon files.
This property is ignored when icons are disabled (see property enable-icons)
and when Window Maker, which does not support icons in menus, is the targeted
window manager.
preferred-terminals
-------------------
The terminal emulators, in order of preference, as a comma separated
list of entry.
-------------------------------------------------------------------
! At runtime, the 1st terminal in this list present on the system !
! is defined as to be used to execute the command of any preferred !
! application to run in a terminal, ie. whose the .desktop file has !
! an entry 'Terminal=true'. !
-------------------------------------------------------------------
Each entry in this list must be to the following syntax :
term[:exec-option]
term:
the program name, with or without path specification, in which case
wmpamgen will search the program on the PATH.
exec-option:
The option to pass to the terminal to execute a program. When not
specified, wmpamgen assumes the terminal supports the option '-e'
the same way as xterm.
top-separator
-------------
Defines whether or not a separator must be added at top of the menu.
This property is ignored in the following cases :
* none of the applications specified by property preferred-applications
is installed.
* the property target-window-manager is set to windowmaker.
bottom-separator
----------------
Defines whether or not a separator must be added at bottom of the menu.
This property is ignored in the following cases :
* none of the applications specified by property preferred-applications
is installed.
* the property target-window-manager is set to windowmaker.
Sample configuration files
--------------------------
wmpamgen comes with the sample configuration files below :
* /usr/doc/wmpamgen/wmpamgen-sample.conf, which is designed to be used
under Linux.
* /usr/doc/wmpamgen/wmpamgen-sample_slackware.conf, which is designed to
be used under Linux/Slackware.
* /usr/doc/wmpamgen/wmpamgen-sample_freebsd.conf, which is designed to
be used under FreeBSD.
These configurations target the window manager fluxbox with icons support
enabled.
The configuration wmpamgen-sample.conf and wmpamgen-sample_freebsd.conf
defines the following preferred applications :
firefox
thunderbird
gimp
xterm
htop
The configuration wmpamgen-sample_slackware.conf defines the following
preferred applications :
thunar
firefox
thunderbird
geeqie
gimp
audacious
gmplayer
xterm
htop
Access the preferred applications menu from window managers
-----------------------------------------------------------
To access the preferred applications menu generated for a given window
manager, this one need to be configured beforehand.
The instructions below assumes that generated menu files are stored in
~/.wmpamgen, and have been generated by running wmpamgen like in example
below :
8<--------------------------------------------------------------------
$ wmpamgen -q -c /path/to/wmpamgen.conf > ~/.wmpamgen/fluxbox.pamenu
$ wmpamgen -q -c /path/to/wmpamgen.conf > ~/.wmpamgen/openbox.pamenu
$ wmpamgen -q -c /path/to/wmpamgen.conf > ~/.wmpamgen/wmaker.pamenu
8<--------------------------------------------------------------------
1. Fluxbox configuration
---------------------
a. Configuration for an access from root-menu
------------------------------------------
Open the root menu file (~/.fluxbox/menu by default), then, after
the entry "[encoding]", add the following :
8<--------------------------------------------------------------
[include] (~/.wmpamgen/fluxbox.pamenu)
[separator]
8<--------------------------------------------------------------
b. Configuration for an access from a sub-menu of the root-menu
------------------------------------------------------------
Open the root menu file (~/.fluxbox/menu by default), then, after
the entry "[encoding]", add the following :
8<--------------------------------------------------------------
[submenu] (Preferred Applications)
[include] (~/.wmpamgen/fluxbox.pamenu)
[end]
[separator]
8<--------------------------------------------------------------
c. Configuration for an access from a popup-menu
---------------------------------------------
Open the keyboard shortcuts configuration file ~/.fluxbox/keys,
then at the end of this file, add the following :
8<--------------------------------------------------------------
Mod4 p :CustomMenu ~/.wmpamgen/fluxbox.pamenu
8<--------------------------------------------------------------
This allows to access the preferred applications menu with the
shortcut <WinKey> + <P>.
2. Openbox configuration
---------------------
To access the preferred applications menu from OpenBox main menu, open
~/.config/openbox/menu.xml, then :
1. Above the line <menu id="root-menu" label="Openbox 3">, add the
following :
8<-------------------------------------------------------------
<menu id="preferred-applications"
label="Preferred Applications"
execute="cat ~/.wmpamgen/openbox.pamenu" />
8<-------------------------------------------------------------
2. Above the line <separator label="Applications" />, add the following :
8<-------------------------------------------------------------
<menu id="preferred-applications" />
8<-------------------------------------------------------------
3. Window Maker configuration
--------------------------
To access the preferred applications menu from Window Maker main menu,
open ~/GNUstep/Defaults/WMRootMenu, then, below the line "Window Maker",
add the following :
8<-------------------------------------------------------------
("Preferred Applications",OPEN_MENU,"~/.wmpamgen/wmaker.pamenu"),
8<-------------------------------------------------------------
Troubleshooting
---------------
In case of issue with wmpamgen, rebuild it with debug informations by passing
-DCMAKE_BUILD_TYPE=Debug (or RelWithDebInfo) to cmake, re-run wmpamgen to
reproduce the issue, then send the system configuration in use, the output
of wmpamgen, the back/stack trace, if any, and any other informations that
could be useful to solve the issue, at :
<slacker6896@gmail.com>
Known issues
------------
None
Translation
-----------
At the moment, wmpamgen manual page and messages (including help page),
are only translated in french.
Anybody who wants to contribute to translation (or even correction) is
welcome and can contact me at <slacker6896@gmail.com>.
Authors
-------
+ Sébastien Ballet <slacker6896@gmail.com>
License
-------
The source code of this program is governed by the BSD 3-clause license
that can be found in the LICENSE file.
Credits
-------
wmpamgen logo was generated on patorjk.com/software/taag using font Doom.
