src/libgdl/README.gdl-dock

   1 This file is meant to contain a little documentation about the GdlDock
   2 and related widgets.  It's incomplete and probably a bit out of date.
   3 And it probably belongs to a doc/ subdirectory.
   4
   5 Please send comments to the devtools list (gnome-devtools@gnome.org)
   6 and report bugs to bugzilla (bugzilla.gnome.org).  Also check the todo
   7 list at the end of this document.
   8
   9 Have fun,
  10 Gustavo
  11
  12
  13 Overview
  14 --------
  15
  16 The GdlDock is a hierarchical based docking widget.  It is composed of
  17 widgets derived from the abstract class GdlDockObject which defines
  18 the basic interface for docking widgets on top of others.
  19
  20 The toplevel entries for docks are GdlDock widgets, which in turn hold
  21 a tree of GdlDockItem widgets.  For the toplevel docks to be able to
  22 interact with each other (when the user drags items from one place to
  23 another) they're all kept in a user-invisible and automatic object
  24 called the master.  To participate in docking operations every
  25 GdlDockObject must have the same master (the binding to the master is
  26 done automatically).  The master also keeps track of the manual items
  27 (mostly those created with gdl_dock_*_new functions) which are in the
  28 dock.
  29
  30 Layout loading/saving service is provided by a separate object called
  31 GdlDockLayout.  Currently it stores information in XML format, but
  32 another backend could be easily written.  To keep the external XML
  33 file in sync with the dock, monitor the "dirty" property of the layout
  34 object and call gdl_dock_layout_save_to_file when this changes to
  35 TRUE.  No other action is required (the layout_changed is monitored by
  36 the layout object for you now).
  37
  38
  39 GdlDockObject
  40 =============
  41
  42 A DockObject has:
  43
  44 - a master, which manages all the objects in a dock ring ("master"
  45   property, construct only).
  46
  47 - a name.  If the object is manual the name can be used to recall the
  48   object from any other object in the ring ("name" property).
  49
  50 - a long, descriptive name ("long-name" property).
  51
  52 A DockObject can be:
  53
  54 - automatic or manual.  If it's automatic it means the lifecycle of
  55   the object is entirely managed by the dock master.  If it's manual
  56   in general means the user specified such object, and so it's not to
  57   be destroyed automatically at any time.
  58
  59 - frozen.  In this case any call to reduce on the object has no
  60   immediate effect.  When the object is later thawn, any pending
  61   reduce calls are made (maybe leading to the destruction of the
  62   object).
  63
  64 - attached or detached.  In general for dock items, being attached
  65   will mean the item has its widget->parent set.  For docks it will
  66   mean they belong to some dock master's ring.  In general, automatic
  67   objects which are detached will be destroyed (unless frozen).
  68
  69 - bound to a master or free.  In order to participate in dock
  70   operations, each dock object must be bound to a dock master (which
  71   is a separate, non-gui object).  In general, bindings are treated
  72   automatically by the object, and this is entirely true for automatic
  73   objects.  For manual objects, the master holds an additional
  74   reference and has structures to store and recall them by nick names.
  75   Normally, a manual object will only be destroyed when it's unbound
  76   from the master.
  77
  78 - simple or compound.  This actually depends on the subclass of the
  79   dock object.  The difference is made so we can put restrictions in
  80   how the objects are docked on top of another (e.g. you can't dock a
  81   compound object inside a notebook).  If you look at the whole
  82   docking layout as a tree, simple objects are the leaves, while all
  83   the interior nodes are compound.
  84
  85 - reduced.  This is only meaningful for compound objects.  If the
  86   number of contained items has decreased to one the compound type
  87   object is no longer necessary to hold the child.  In this case the
  88   child is reattached to the object's parent.  If the number of
  89   contained items has reached zero, the object is detached and reduce
  90   is called on its parent.  For toplevel docks, the object is only
  91   detached if it's automatic.  In any case, the future of the object
  92   itself depends on whether it's automatic or manual.
  93
  94 - requested to possibly dock another object.  Depending on the
  95   type's behavior, the object can accept or reject this request.  If
  96   it accepts it, it should fill in some additional information
  97   regarding how it will host the peer object.
  98
  99 - asked to dock another object.  Depending on the object's internal
 100   structure and behavior two options can be taken: to dock the object
 101   directly (e.g. a notebook docking another object); or to create an
 102   automatic compound object which will be attached in place of the
 103   actual object, and will host both the original object and the
 104   requestor (e.g. a simple item docking another simple item, which
 105   should create a paned/notebook).  The type of the new object will be
 106   decided by the original objet based on the docking position.
 107
 108
 109 DETACHING: the action by which an object is unparented.  The object is
 110 then ready to be docked in some other place.  Newly created objects
 111 are always detached, except for toplevels (which are created attached
 112 by default).  An automatic object which is detached gets destroyed
 113 afterwards, since its ref count drops to zero.  Floating automatic
 114 toplevels never reach a zero ref count when detached, since the
 115 GtkWindow always keeps a reference to it (and the GtkWindow has a user
 116 reference).  That's why floating automatic toplevels are destroyed
 117 when reduced.
 118
 119 REDUCING: for compound objects, when the number of contained children
 120 drops to one or zero, the container is no longer necessary.  In this
 121 case, the object is detached, and any remaining child is reattached to
 122 the object's former parent.  The limit for toplevels is one for
 123 automatic objects and zero for manual (i.e. they can even be empty).
 124 For simple (not compound) objects reducing doesn't make sense.
 125
 126 UNBINDING: to participate in a dock ring, every object must be bound
 127 to a master.  The master connects to dock item signals and keeps a
 128 list of bound toplevels.  Additionally, a reference is kept for manual
 129 objects (this is so the user doesn't need to keep track of them, but
 130 can perform operations like hiding and such).
 131
 132
 133
 134 GdlDock
 135 =======
 136
 137 - Properties:
 138
 139   "floating" (gboolean, construct-only): whether the dock is floating in
 140   its own window or not.
 141
 142   "default-title" (gchar, read-write): title for new floating docks.
 143   This property is proxied to the master, which truly holds it.
 144
 145 The title for the floating docks is: the user supplied title
 146 (GdlDockObject's long_name property) if it's set, the default title
 147 (from the master) or an automatically generated title.
 148
 149
 150 - Signals:
 151
 152   "layout-changed": emitted when the user changed the layout of the
 153   dock somehow.
 154
 155
 156 TODO LIST
 157 =========
 158
 159 - Functionality for the item grip: provide a11y
 160
 161 - Implement notebook tab reordering
 162
 163 - Implement dock bands for toolbars and menus.
 164
 165 - A dock-related thing is to build resizable toolbars (something like
 166   the ones Windows have, where the buttons are reflowed according to
 167   the space available).
 168
 169 - Redesign paneds so they can hold more than two items and resize all
 170   of them at once by using the handle (see if gimpdock does that).
 171
 172 - Find a way to allow the merging of menu items to the item's popup
 173   menu.  Also, there should be a way for the master to insert some
 174   menu items.
 175
 176 - Bonobo UI synchronizer.
 177
 178 - Item behavoirs: implement the ones missing and maybe think more of
 179   them (e.g. positions where it's possible to dock the item, etc.)
 180
 181 - Make a nicer dragbar for the items, with buttons for undocking,
 182   closing, hidding, etc. (See sodipodi, kdevelop)
 183
 184