mod_dock/README.dock

   1 Ion dock module
   2 Copyright (c) Tom Payne 2003
   3 Copyright (c) Per Olofsson 2003
   4
   5 by Tom Payne <ion@tompayne.org>
   6 based on code by Per Olofsson <pelle@dsv.su.se>
   7
   8 INTRODUCTION
   9
  10         This module provides a dock for the Ion window manager.
  11
  12         Features:
  13         - supports most dockapps
  14         - configurable layout
  15         - configurable dockapp order
  16         - supports shaped dockapps
  17         - uses ion's drawing engine
  18
  19 DEPENDENCIES
  20
  21         ion3
  22
  23 USAGE
  24
  25         1. Copy the configuration files cfg_dock.lua and dock-draw.lua to
  26            your ~/.ion3 directory. Edit cfg_dock.lua and dock-draw.lua to
  27            suit your preferences.
  28
  29         2. Add load_module("mod_dock") to ~/.ion3/cfg_ion.lua.
  30
  31         3. Add include("dock-draw.lua") near the end of ~/.ion3/draw.lua,
  32            before gr_refresh().
  33
  34         4. (Re)start ion3.
  35
  36 CONFIGURATION
  37
  38         See the comments in cfg_dock.lua and dock-draw.lua.
  39
  40 KNOWN BUGS
  41
  42         Not all dockapps dock. This is because dockapps use a variety of methods
  43         to signal that they are dockapps and the dock doesn't yet
  44         recognise all of them. If your favourite dockapp does not work then
  45         please inform the author (email address at top of file).
  46
  47         The following dockapps are known to have problems:
  48
  49         - gkrellm2 can have the wrong shape if it is started after the dock
  50           module is loaded.
  51
  52         - wmxmms needs a winprop{...}. See the example cfg_dock.lua. Ion
  53           complains: Client window "wmxmms" has broken transient_for hint.
  54           ("Extended WM hints" multi-parent brain damage?).
  55
  56 IMPLEMENTATION NOTES
  57
  58         If you would like to help improve the dock then the following
  59         notes might be useful.
  60
  61         You should use folding in your editor when you edit/view the source
  62         code. The code follows ion's coding standards, but there are many more
  63         folds. VIM and Emacs both support folding.
  64
  65         Dockapps use a variety of methods to signal to the window manager that
  66         they are a dockapp. Ion automatically detects some (see
  67         manage_clientwin() in ioncore/clientwin.c), and the dock detects
  68         some others (see dock_clientwin_is_dockapp() in dock.c).  Adding more
  69         dockapp types will require editing these functions and possibly writing
  70         type-specific management code.
  71
  72         The dock should really implement region_save_to_file()/region_load() to
  73         maintain state over a restart and session management. However, over
  74         restart a new dock will also be created by cfg_dock.lua, meaning that there
  75         will be multiple docks on the same screen. The solution is probably to
  76         automatically create docks as they are required, with cfg_dock.lua
  77         specifying the default configuration of new docks but not actually
  78         creating any docks.
  79
  80         As far as I can tell the gkrellm2 problem is a race condition and the
  81         sequence of events is as follows:
  82         1. gkrellm2 starts and gets added to the dock with is initial geom.
  83         2. gkrellm2 grows as it loads plugins.
  84         3. The dock allocates more space to gkrellm2 and requests
  85            gkrellm2's new shape, but gkrellm2 reports its old shape.
  86         4. Further requests to gkrellm2 return is new (actual) shape, but by
  87             now it's too late...
  88         Any assistance in fixing this bug would be much appreciated.
  89
  90 AUTHORS
  91
  92         Tom Payne <ion@tompayne.org>
  93         Per Olofsson <pelle@dsv.su.se>
  94
  95 LICENSE
  96
  97         This program is licensed under the terms of the Lesser General Public
  98         License (LGPL) version 2.1. See the file COPYING for details.