README.gdl-dock revision a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799
40c5626383ebd5e8cf11a636f864023a2aafcd6bDaniel Couto ValeThis file is meant to contain a little documentation about the GdlDock
40c5626383ebd5e8cf11a636f864023a2aafcd6bDaniel Couto Valeand related widgets. It's incomplete and probably a bit out of date.
58721b9d3a8cd6a624269ddf507f80af4417c9bdhenning muellerAnd it probably belongs to a doc/ subdirectory.
ec416eab0158cfe34b77cea4a11f8b84bc194a7aDaniel Couto ValePlease send comments to the devtools list (gnome-devtools@gnome.org)
40c5626383ebd5e8cf11a636f864023a2aafcd6bDaniel Couto Valeand report bugs to bugzilla (bugzilla.gnome.org). Also check the todo
40c5626383ebd5e8cf11a636f864023a2aafcd6bDaniel Couto Valelist at the end of this document.
58721b9d3a8cd6a624269ddf507f80af4417c9bdhenning muellerThe GdlDock is a hierarchical based docking widget. It is composed of
58721b9d3a8cd6a624269ddf507f80af4417c9bdhenning muellerwidgets derived from the abstract class GdlDockObject which defines
58721b9d3a8cd6a624269ddf507f80af4417c9bdhenning muellerthe basic interface for docking widgets on top of others.
58721b9d3a8cd6a624269ddf507f80af4417c9bdhenning muellerThe toplevel entries for docks are GdlDock widgets, which in turn hold
40c5626383ebd5e8cf11a636f864023a2aafcd6bDaniel Couto Valea tree of GdlDockItem widgets. For the toplevel docks to be able to
40c5626383ebd5e8cf11a636f864023a2aafcd6bDaniel Couto Valeinteract with each other (when the user drags items from one place to
82d525750e23960f3f2cc6a11220e0ef8505918fhenning muelleranother) they're all kept in a user-invisible and automatic object
82d525750e23960f3f2cc6a11220e0ef8505918fhenning muellercalled the master. To participate in docking operations every
82d525750e23960f3f2cc6a11220e0ef8505918fhenning muellerGdlDockObject must have the same master (the binding to the master is
58721b9d3a8cd6a624269ddf507f80af4417c9bdhenning muellerdone automatically). The master also keeps track of the manual items
a837d007b255d7a6cca7994e1e555aba95ce41cchenning mueller(mostly those created with gdl_dock_*_new functions) which are in the
a837d007b255d7a6cca7994e1e555aba95ce41cchenning muellerLayout loading/saving service is provided by a separate object called
a837d007b255d7a6cca7994e1e555aba95ce41cchenning muellerGdlDockLayout. Currently it stores information in XML format, but
58721b9d3a8cd6a624269ddf507f80af4417c9bdhenning muelleranother backend could be easily written. To keep the external XML
a837d007b255d7a6cca7994e1e555aba95ce41cchenning muellerfile in sync with the dock, monitor the "dirty" property of the layout
a837d007b255d7a6cca7994e1e555aba95ce41cchenning muellerobject and call gdl_dock_layout_save_to_file when this changes to
a837d007b255d7a6cca7994e1e555aba95ce41cchenning muellerTRUE. No other action is required (the layout_changed is monitored by
a837d007b255d7a6cca7994e1e555aba95ce41cchenning muellerthe layout object for you now).
40c5626383ebd5e8cf11a636f864023a2aafcd6bDaniel Couto ValeA DockObject has:
b0c849916b1471424344717ada19c745833e4c5bhenning mueller- a master, which manages all the objects in a dock ring ("master"
40c5626383ebd5e8cf11a636f864023a2aafcd6bDaniel Couto Vale property, construct only).
40c5626383ebd5e8cf11a636f864023a2aafcd6bDaniel Couto Vale- a name. If the object is manual the name can be used to recall the
b0c849916b1471424344717ada19c745833e4c5bhenning mueller object from any other object in the ring ("name" property).
b0c849916b1471424344717ada19c745833e4c5bhenning mueller- a long, descriptive name ("long-name" property).
40c5626383ebd5e8cf11a636f864023a2aafcd6bDaniel Couto ValeA DockObject can be:
71fdc30cc6e637d99cacb455537e7b8fbfe77395henning mueller- automatic or manual. If it's automatic it means the lifecycle of
b0c849916b1471424344717ada19c745833e4c5bhenning mueller the object is entirely managed by the dock master. If it's manual
71fdc30cc6e637d99cacb455537e7b8fbfe77395henning mueller in general means the user specified such object, and so it's not to
71fdc30cc6e637d99cacb455537e7b8fbfe77395henning mueller be destroyed automatically at any time.
71fdc30cc6e637d99cacb455537e7b8fbfe77395henning mueller- frozen. In this case any call to reduce on the object has no
40c5626383ebd5e8cf11a636f864023a2aafcd6bDaniel Couto Vale immediate effect. When the object is later thawn, any pending
40c5626383ebd5e8cf11a636f864023a2aafcd6bDaniel Couto Vale reduce calls are made (maybe leading to the destruction of the
40c5626383ebd5e8cf11a636f864023a2aafcd6bDaniel Couto Vale- attached or detached. In general for dock items, being attached
40c5626383ebd5e8cf11a636f864023a2aafcd6bDaniel Couto Vale will mean the item has its widget->parent set. For docks it will
a837d007b255d7a6cca7994e1e555aba95ce41cchenning mueller mean they belong to some dock master's ring. In general, automatic
a837d007b255d7a6cca7994e1e555aba95ce41cchenning mueller objects which are detached will be destroyed (unless frozen).
58721b9d3a8cd6a624269ddf507f80af4417c9bdhenning mueller- bound to a master or free. In order to participate in dock
58721b9d3a8cd6a624269ddf507f80af4417c9bdhenning mueller operations, each dock object must be bound to a dock master (which
58721b9d3a8cd6a624269ddf507f80af4417c9bdhenning mueller is a separate, non-gui object). In general, bindings are treated
58721b9d3a8cd6a624269ddf507f80af4417c9bdhenning mueller automatically by the object, and this is entirely true for automatic
58721b9d3a8cd6a624269ddf507f80af4417c9bdhenning mueller objects. For manual objects, the master holds an additional
58721b9d3a8cd6a624269ddf507f80af4417c9bdhenning mueller reference and has structures to store and recall them by nick names.
58721b9d3a8cd6a624269ddf507f80af4417c9bdhenning mueller Normally, a manual object will only be destroyed when it's unbound
705933deb08bc4269e8c08d50143af3cb5c1c670henning mueller from the master.
705933deb08bc4269e8c08d50143af3cb5c1c670henning mueller- simple or compound. This actually depends on the subclass of the
705933deb08bc4269e8c08d50143af3cb5c1c670henning mueller dock object. The difference is made so we can put restrictions in
705933deb08bc4269e8c08d50143af3cb5c1c670henning mueller how the objects are docked on top of another (e.g. you can't dock a
a837d007b255d7a6cca7994e1e555aba95ce41cchenning mueller compound object inside a notebook). If you look at the whole
705933deb08bc4269e8c08d50143af3cb5c1c670henning mueller docking layout as a tree, simple objects are the leaves, while all
705933deb08bc4269e8c08d50143af3cb5c1c670henning mueller the interior nodes are compound.
b5bf21df9d1d61069e6dc9e13569543d0b868bc8Daniel Couto Vale- reduced. This is only meaningful for compound objects. If the
b5bf21df9d1d61069e6dc9e13569543d0b868bc8Daniel Couto Vale number of contained items has decreased to one the compound type
705933deb08bc4269e8c08d50143af3cb5c1c670henning mueller object is no longer necessary to hold the child. In this case the
b5bf21df9d1d61069e6dc9e13569543d0b868bc8Daniel Couto Vale child is reattached to the object's parent. If the number of
b5bf21df9d1d61069e6dc9e13569543d0b868bc8Daniel Couto Vale contained items has reached zero, the object is detached and reduce
b5bf21df9d1d61069e6dc9e13569543d0b868bc8Daniel Couto Vale is called on its parent. For toplevel docks, the object is only
58721b9d3a8cd6a624269ddf507f80af4417c9bdhenning mueller detached if it's automatic. In any case, the future of the object
7ea9649883e1bbe8f2582db1a3c66af8b7206056henning mueller itself depends on whether it's automatic or manual.
b5bf21df9d1d61069e6dc9e13569543d0b868bc8Daniel Couto Vale- requested to possibly dock another object. Depending on the
b5bf21df9d1d61069e6dc9e13569543d0b868bc8Daniel Couto Vale type's behavior, the object can accept or reject this request. If
b5bf21df9d1d61069e6dc9e13569543d0b868bc8Daniel Couto Vale it accepts it, it should fill in some additional information
b5bf21df9d1d61069e6dc9e13569543d0b868bc8Daniel Couto Vale regarding how it will host the peer object.
b5bf21df9d1d61069e6dc9e13569543d0b868bc8Daniel Couto Vale- asked to dock another object. Depending on the object's internal
3c11d09eefb778da1ccf77a5de6bd70c0f4c0181Daniel Couto Vale structure and behavior two options can be taken: to dock the object
a837d007b255d7a6cca7994e1e555aba95ce41cchenning mueller directly (e.g. a notebook docking another object); or to create an
ec416eab0158cfe34b77cea4a11f8b84bc194a7aDaniel Couto Vale automatic compound object which will be attached in place of the
ec416eab0158cfe34b77cea4a11f8b84bc194a7aDaniel Couto Vale actual object, and will host both the original object and the
a837d007b255d7a6cca7994e1e555aba95ce41cchenning mueller requestor (e.g. a simple item docking another simple item, which
a837d007b255d7a6cca7994e1e555aba95ce41cchenning mueller should create a paned/notebook). The type of the new object will be
a837d007b255d7a6cca7994e1e555aba95ce41cchenning mueller decided by the original objet based on the docking position.
7176611933342f2f57c1eee8342be273cf33c539Daniel Couto ValeDETACHING: the action by which an object is unparented. The object is
7176611933342f2f57c1eee8342be273cf33c539Daniel Couto Valethen ready to be docked in some other place. Newly created objects
7176611933342f2f57c1eee8342be273cf33c539Daniel Couto Valeare always detached, except for toplevels (which are created attached
a837d007b255d7a6cca7994e1e555aba95ce41cchenning muellerby default). An automatic object which is detached gets destroyed
a837d007b255d7a6cca7994e1e555aba95ce41cchenning muellerafterwards, since its ref count drops to zero. Floating automatic
7176611933342f2f57c1eee8342be273cf33c539Daniel Couto Valetoplevels never reach a zero ref count when detached, since the
7176611933342f2f57c1eee8342be273cf33c539Daniel Couto ValeGtkWindow always keeps a reference to it (and the GtkWindow has a user
a837d007b255d7a6cca7994e1e555aba95ce41cchenning muellerreference). That's why floating automatic toplevels are destroyed
a837d007b255d7a6cca7994e1e555aba95ce41cchenning muellerREDUCING: for compound objects, when the number of contained children
7176611933342f2f57c1eee8342be273cf33c539Daniel Couto Valedrops to one or zero, the container is no longer necessary. In this
7176611933342f2f57c1eee8342be273cf33c539Daniel Couto Valecase, the object is detached, and any remaining child is reattached to
a837d007b255d7a6cca7994e1e555aba95ce41cchenning muellerthe object's former parent. The limit for toplevels is one for
7176611933342f2f57c1eee8342be273cf33c539Daniel Couto Valeautomatic objects and zero for manual (i.e. they can even be empty).
7176611933342f2f57c1eee8342be273cf33c539Daniel Couto ValeFor simple (not compound) objects reducing doesn't make sense.
7176611933342f2f57c1eee8342be273cf33c539Daniel Couto ValeUNBINDING: to participate in a dock ring, every object must be bound
7176611933342f2f57c1eee8342be273cf33c539Daniel Couto Valeto a master. The master connects to dock item signals and keeps a
a837d007b255d7a6cca7994e1e555aba95ce41cchenning muellerlist of bound toplevels. Additionally, a reference is kept for manual
a837d007b255d7a6cca7994e1e555aba95ce41cchenning muellerobjects (this is so the user doesn't need to keep track of them, but
7176611933342f2f57c1eee8342be273cf33c539Daniel Couto Valecan perform operations like hiding and such).
3b8ddf9c7bdfd34cfc7dd41ff603f83dba6ed7d4Daniel Couto Vale "floating" (gboolean, construct-only): whether the dock is floating in
3b8ddf9c7bdfd34cfc7dd41ff603f83dba6ed7d4Daniel Couto Vale its own window or not.
a837d007b255d7a6cca7994e1e555aba95ce41cchenning mueller "default-title" (gchar, read-write): title for new floating docks.
a837d007b255d7a6cca7994e1e555aba95ce41cchenning mueller This property is proxied to the master, which truly holds it.
a837d007b255d7a6cca7994e1e555aba95ce41cchenning muellerThe title for the floating docks is: the user supplied title
a837d007b255d7a6cca7994e1e555aba95ce41cchenning mueller(GdlDockObject's long_name property) if it's set, the default title
a837d007b255d7a6cca7994e1e555aba95ce41cchenning mueller(from the master) or an automatically generated title.
them (e.g. positions where it's possible to dock the item, etc.)