Copyright (c) 2002 by Steve Cooper
parts Copyright (c) 1998-2000 by John Kennis
parts Copyright (c) 1997,1998 by Brad Hughes.
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.
675
Mass Ave
Cambridge, MA 02139, USA
(See the included file COPYING / GPL-2.0)
Author: Steve Cooper:
Email: stevencooper@isomedia.com
Web: http://www.isomedia.com/homes/stevencooper
John Kennis - Author of bbpager
Brad Hughes - For writing the Blackbox Window Manager (and with this a great deal of the low level code for this application).
Nat Friedman with modifications by Gerald Britton - For the Esetroot code used for displaying wallpaper
Fluxspace enhances Fluxbox and similar window managers by providing a framework for loading Python modules with new workspace-oriented features. The framework should make it easy to develop new modules with unforeseen functionality. Modules using this framework can add event-driven behavior to Fluxbox as an external component, without modifying Fluxbox's C++ code.
Existing modules that integrate with Rox Filer or Idesk can add effective desktop management to a pure window manager, like Fluxbox. It goes beyond the normal desktop capabilities to allow you to customize each workspace with its own panels, desktop icons and running applets.
The C++ portion of the source code is originally based on bbpager, which evolved to fluxter. It includes code from Esetroot to perform the root window painting.
This is partly an experiment. I hope you find it useful. But please let me know either way. :-)
It can add desktop icons and panels to a pure window manager, such as Fluxbox, by leveraging tools like Rox Filer and Idesk. Just select a desktop management module and install the appropriate external package, e.g. Rox Filer.
It can decorate each workspace with different wallpaper.
It can manage your startup applications.
It can automatically start and stop applets as you enter and leave workspaces.
Each workspace can have its own unique tools running and dockapps visible.
It provides a Python framework for constructing your own event-driven applets.
Event tracing for debugging.
Rox Filer integration, including per-workspace panels, per-workspace pinboards (icons and wallpaper on each desktop).
Idesk integration, providing per-workspace desktop icons.
An event-driven Python library for building other workspace or window manager enhancements. Currently events are distributed for workspace changes and various major window changes.
Uses a single/simple XML configuration file.
Python-dev >= 2.1 - Tested with python
v2.2.
http://www.python.org/download/
imlib2-dev
http://enlightenment.org/
GNU build tools (automake, autoconf, libtool, aclocal, etc.)
- no known special version requirements
http://www.gnu.org/
These are only needed if "make distclean" is used to start from "bare metal":
automake >= 1.5
autoconf >= 1.5
SWIG (for interfacing C++ to Python)
Fluxbox or other Blackbox
derivative - Tested with Fluxbox. Untested with
others.
http://fluxbox.sourceforge.net/
python >= 2.1 (interpreter and
core modules, with core XML support)
http://www.python.org/download/
imlib2 (for setting the root
background)
http://enlightenment.org/
rox (Rox Filer) - for the rox fluxlet. Not required otherwise.
idesk (desktop icons) - for the idesk fluxlet. Not required otherwise.
The concept of workspaces is great. But little rhyme, reason or guidance exists on the best way to use them. This initial package is a big step towards making workspaces into fully customizable task-oriented "rooms".
You may change the way you use workspaces and window managers. Or you may hate it. :)
Related tool icons can be grouped together in different workspaces with single click access. This can promote more consistent usage patterns and less window congestion. If so, you will run into fewer situations where you have an urgent need to reduce window clutter, and park windows somewhere/anywhere.
Windows will live in task-oriented rooms. For example, your browser will tend to run in a different room than your word processor. Using the "rox" module you may have grouped the browser, email and ftp program icons on a panel in one workspace, and your productivity applications on a panel in a different workspace.
This release is just a starting point. Hopefully the framework will grow in power, and new modules will be developed. It need not be limited to workspace enhancements. See the Future Possibilities section below.
You can make your Fluxbox life easier by using Fluxspace to manage:
Startup applications.
Painting the wallpaper (no external app needed, just the imlib2 library). I.e. just specify the path to the image.
Fluxspace requires a Python interpreter. It will consume more memory and run at interpreted speeds.
I have seen a 4 MB memory overhead, but little or no noticable performance degradation. In fact wallpaper swapping is somewhat faster since a new process is not spawned for a root command. A C library function is used instead.
Note that I do have a fast system. But fluxspace currently only participates in major/infrequent events. Hopefully the customization and enhancement ease will more than make up for any inefficiency.
The early feature set assumes you want to use workspaces as task-centric rooms. If that's not your style you may not benefit.
For now you have to directly edit an XML configuration file. XML is uglier and harder to edit than regular flat text files. A graphical editor is on the wish list.
To compensate, the chosen XML grammar is as simple and readable as possible.
Verify that fluxbox, Imlib2, SWIG, Python, and whatever optional programs you need, such as Rox Filer, are installed and working.
Fluxbox: http://fluxbox.sourceforge.net/
Imlib2: http://enlightenment.org/
SWIG: http://www.swig.org/
Python: http://www.python.org/
Rox Filer: http://rox.sourceforge.net/
idesk: http://linuxhelp.hn.org/idesk.php
All or most of these should be available through the appropriate packaging mechanism provided by distributions, such as Debian, Gentoo, Mandrake, RedHat, etc.
You will also need the development packages for Imlib2 and Python in order to build.
$ ./configure $ make $ su -c make install
It targets the /usr/local directory by default. Modify the target directory with the –prefix= option to ./configure.
Run the following to check for options to view the possible configuration options:
$ ./configure --help
$ make distclean
$ make maintainer-clean
You need to run the bootstrap script:
$ ./bootstrap
Fluxspace is packaged with some pre-built components so that you shouldn't need to run the bootstrap script. If you start playing with the SWIG interfaces you may need to either manually delete fluxspace_wrap.cxx and fluxspace.py or run "make distclean". This forces the SWIG code to get regenerated.
Running "make distclean" will require the use of ./bootstrap to get going again.
The following steps will get you quickly started.
Copy fluxspace.xml from the examples directory (e.g. /usr/local/fluxspace/examples) to "~/.fluxbox".
Edit fluxspace.xml with a text editor to customize it to your needs. The example has most features enabled or visible in the configuration. Almost everything should be changed for your environment, including paths to images, program lists, panel options, etc. Enable the modules you want by setting their "enable" attribute to "yes". See the Configuration reference below. The sample file has everything disabled.
Replace or set the Fluxbox root command to “fluxspace”. You can find this setting in ~/.fluxbox/init.
You may want to remove the starting of dockapps from the X initialization script (.xinitrc, .xsession, etc.) and add them to the fluxspace runner module configuration.
You should be ready to go.
The following instructions assume you understand XML syntax. In the future a graphical should be available.
The outer <fluxspace> element pair is mandatory.
Each module has an element with the module name as the tag. The only attribute is "enable". Set "enable" to "yes" to load and use the module. Set "enable" to "no" to prevent it from loading.
Packaged modules are documented below.
Displays wallpaper on each workspace. Uses Enlightenment code. So most image formats are supported. Pseudo-transparent terminals display correctly.
One wallpaper option element should be provided for each workspace.
A number from 0 to n selecting the workspace to receive the wallpaper.
The path to the image displayed as the wallpaper. '~' expansion is performed to substitute the full path to the user home directory.
This attribute is required.
The optional name of a background color using standard X color names or RGB values.
You can use a tool like xcolors to display the named colors. Standard RGB values are also excepted, e.g. "RGB:FF/00/00" for bright red.
See X documentation for more information.
If set to "yes" the image stretches to the full screen size. This option can distort the image's aspect ratio.
If set to "yes" the image appears centered on the screen. This option prevents image tiling.
If set to "yes" image stretches to fill the screen as much as it can without changing the aspect ratio.
If set to "yes" some image tiles flip to show a mirror image.
This module leverages Rox Filer to display a different panel and or pinboard for each workspace.
Pinboards provide a surface for desktop icons and allow Rox to paint background wallpaper.
Note that Rox pinboards duplicate the functionality of the painter module for displaying wallpaper. So they fight with each other to paint the desktop. They both lose. :) Disable the painter module if you use Rox pinboards.
Check out the Rox documentation for all of its capabilities. It's a great lightweight desktop and file manager.
IMPORTANT: Setting two Rox options will improve coexistence with fluxbox. Set these options as follows:
Run the Options dialog from the Rox context menu.
Select the Compatibility category.
Check: "Override window
manager control of the pinboard and panels".
Note that this
should become unnecessary when fluxbox fully supports the Extended
Window Manager Hints standard.
Check: "Pass all backdrop mouse clicks to window manager".
Each workspaces get its own Rox panel. Each workspace panel is individually customizable through normal Rox mechanisms.
Possible values are "left", "right", "top" or "bottom" to select the edge the panel occupies.
Each workspaces get its own Rox pinboard to manage the desktop. Each workspace desktop is individually customizable through normal Rox mechanisms. Icons can be added to access directories and for running programs. Wallpaper or a colored background can also be specified through Rox.
There are no attributes for this option.
IMPORTANT: Root menu mouse behavior will suffer without patching either Fluxbox or Rox. The Fluxbox root menu immediately goes away when the mouse button is released on top of a Rox pinboard.
Look for a link to a Fluxbox patch on the Fluxspace web page.
A potentially better recommendation is to avoid the pinboard entirely. If you really want desktop icons, use Idesk and the corresponding idesk module. Idesk does not have the same issue because it doesn't interpose its own window for the desktop background. See below for a description of this module.
The idesk module integrates with idesk in a way that allows it to provide different desktop icons in each workspace. The module manages a softlink to the current desktop and restarts Idesk with each workspace change. It effectively reconfigures Idesk each time you enter a workspace.
This module requires no attributes or options for the idesk module in fluxspace.xml. Simply adding a line like the following to enable it:
<idesk enable="yes"/>
Follow idesk's instructions concerning its initial configuration to create your ~/.ideskrc file. Do NOT create an .idesktop directory! The idesk fluxlet will dynamically create softlinks from ~/.fluxbox/idesktops/desktop(0-n) to ~/.idesktop. Desktop icon .lnk files may be placed in the various ~/.fluxbox/idesktops/ subdirectories, e.g. desktop0 for the first workspace.
There may be some cosmetic repaint issues with the desktop icons when you change workspaces with windows obscuring desktop icons. Functionality is not affected. Hopefully future releases will address this.
There are a couple of module attributes that won't be important until future enhancements appear.
The number of pixels to shift the icon grid horizontally when automatically creating icons. The external tools fluxspace-add-idesk-icon and fluxspace-sync-idesk-with-appdirs obey this setting when placing new icons.
The number of pixels to shift the icon grid vertically when automatically creating icons. The external tools fluxspace-add-idesk-icon and fluxspace-sync-idesk-with-appdirs obey this setting when placing new icons.
The runner module lets you specify programs to run once or programs to start and stop on a per-workspace basis.
Its simplest use is as a convenient dockapp startup tool. More complex usage can set up applications to provide unique functional environments for each workspace. For example, wmdrawer can be restarted with a different configuration upon entering a workspace. This will make different application icons available for different desktops. The same benefit can be obtained by enabling per-workspace Rox panels or Idesk desktops. (see above).
Specifies a program to be executed by the runner module at appropriate times.
If a workspace is specified the program is run when entering the workspace and killed (gently) when leaving.
If the "action" is "spawn" the program is not killed.
If a workspace is not specified the program is only run at startup.
Possible values are "run" (the default) and "manage". The difference is that managed programs will be killed and restarted when leaving and entering workspaces. Programs started with run are never stopped by Fluxspace.
This attribute is optional.
The value is the workspace number, 0-n. These programs will be monitored by the runner module. When entering a new workspace running programs not assigned to the workspace are killed and assigned programs are started.
When the workspace attribute is not present programs are only run at startup and forgotten.
This attribute is optional.
The value is a complete command to execute, including all arguments.
No substitutions are performed.
This modules enables event tracing to standard output. There are no options. It is mainly useful as a starting point for implementing new modules and for diagnostic purposes.
You will eventually want to configure Fluxspace to run from a hidden place, like a startup script or the Fluxbox init configuration file. If you experience a failure of either a specific tool or Fluxspace itself return to the command line for troubleshooting.
First stop Fluxspace, if it is still running. Try "fluxspace stop" from the command line. If that doesn't halt Fluxspace and its managed applets work with tools like ps, kill, top or your favorite graphical process manager.
Run "fluxspace" from the command line. It will generally display detailed error messages when things fail. If that doesn't help try running in verbose mode using "fluxspace -v".
If you run Fluxspace from the command line module import problems may look something like this:
Traceback (most recent call last):=20
File "/usr/local/bin/fluxspace", line 15, in ?=20
import fluxspace=20
ImportError: No module named fluxspace
Depending on your Python installation you may see this error for modules other than "fluxspace". The same concepts apply. See where the module is installed and configure Python to look for modules in that directory.
By default Fluxspace installs to /usr/local/lib/python2.x/site-packages. Substitute the decimal digit of your Python version for ".x" in the path. This directory must be in Python's module load path. You can create or add to a PYTHONPATH environment variable, or you can edit or create a sitecustomize.py file in /usr/lib/python2.x/site-packages.
Please see site -- Site-specific configuration hook from the online Python manual for more information and other possibilities. Also check for a site.py module, possibly under /etc/python2.x. It may have instructions and hooks for extending the Python load path.
A sitecustomize.py file could look something like this:
import sys
version = '%d.%d' % (sys.version_info[0], sys.version_info[1])
addPath = '/usr/local/lib/python%s/site-packages' % version
sys.path.insert(0, addPath)
/usr/lib/python2.x/site-packages/sitecustomize.py is automatically loaded by Python before loading other modules. Substitute your version digit for the 'x' in the python library root directory.
Another module import troubleshooting technique can be to run Python interactively, i.e. execute the "python" command. When you see the ">>> " prompt, type "import fluxspace" (or whatever module is the problem) and press Return. You will probably see the same error as above.
As a diagnostic run the following commands. Type the commands preceded by ">>> ". Sample output is included for reference.
$ python Python 2.2.2 (#1, Dec 26 2002, 22:54:33)=20 [GCC 3.2.1] on linux2 Type "help", "copyright", "credits" or "license" for more information. >>> import sys >>> print sys.path ['', '/usr/local/lib/python2.2/site-packages', '/opt/debian/bin', '/usr/local/bin', '/home/scooper/bin', '/usr/lib/python2.2', '/usr/lib/python2.2/plat-linux2', '/usr/lib/python2.2/lib-tk', '/usr/lib/python2.2/lib-dynload', '/usr/lib/python2.2/site-packages', '/usr/lib/python2.2/site-packages/gtk-2.0'] >>>
Notice that '/usr/local/lib/python2.2/site-packages' is in the path. Check that yours has what is needed to find the missing module. If it doesn't you may have to create or edit a sitecustomize.py file to add your python library install path, e.g. /usr/local/lib/python2.2/site-packages to the python path for loading modules.
This tool simply runs Fluxspace in the background. All command line options are passed along to the fluxspace script.
Usage: rox-add-app <submenu> <command> <name>
Creates a Rox AppDir under the ~/Apps directory hierarchy. It helps you manage a Start “menu” of sorts that is accessible through Rox Filer browser windows.
Usage: fluxspace-add-idesk-icon <workspace #> <caption> <command> <icon path>
Creates an Idesk icon on a particular desktop.
Usage: fluxspace-sync-idesk-with-appdirs <workspace #> <directory>
Generates Idesk desktop icons for the specified workspace based on the Rox AppDir icons in the specified directory. This gives you a more graphical way to manage Idesk icons. Otherwise you would have to hand-edit .lnk text files. To take advantage of this capability maintain all icons using Rox tools and AppDir's. Then run this tool to populate your Idesk workspace desktops.
A graphical configuration
editor.
One possibility would allow modules to dynamically
construct a master DTD that drives a fairly generic DTD-driven
editor.
Manage a visible and expandable chunk of slit real estate, much like gkrellm. An API would allow modules to provide user interfaces including icon drawers, menus, meters, mailboxes, or whatever. Since modules will still receive workspace and window events the visible contact can adjust to the current workspace or active window.
Leverage standard window manager properties to tweak WM behavior more directly.
See if it makes sense to integrate more directly with a window manager, such as Fluxbox.
A sticky note module to attach drawings, text, etc. to particular windows, possibly based on the current workspace.
An arranger module would apply window tiling templates to workspaces. Window types could be assigned to sections of the tiling template. E.g. your browser and email program could always position themselves a certain way when opened on your "Internet" workspace.
A 3D effects module could provide lots of superflous effects to workspace transitions, window mapping, etc.
Please send suggestions to: stevencooper@isomedia.com
All feedback is welcome!