a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_bThis file is meant to contain a little documentation about the GdlDock
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_band related widgets. It's incomplete and probably a bit out of date.
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_bAnd it probably belongs to a doc/ subdirectory.
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_bPlease send comments to the devtools list (gnome-devtools@gnome.org)
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_band report bugs to bugzilla (bugzilla.gnome.org). Also check the todo
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_blist at the end of this document.
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_bThe GdlDock is a hierarchical based docking widget. It is composed of
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_bwidgets derived from the abstract class GdlDockObject which defines
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_bthe basic interface for docking widgets on top of others.
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_bThe toplevel entries for docks are GdlDock widgets, which in turn hold
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_ba tree of GdlDockItem widgets. For the toplevel docks to be able to
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_binteract with each other (when the user drags items from one place to
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_banother) they're all kept in a user-invisible and automatic object
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_bcalled the master. To participate in docking operations every
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_bGdlDockObject must have the same master (the binding to the master is
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_bdone automatically). The master also keeps track of the manual items
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b(mostly those created with gdl_dock_*_new functions) which are in the
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_bLayout loading/saving service is provided by a separate object called
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_bGdlDockLayout. Currently it stores information in XML format, but
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_banother backend could be easily written. To keep the external XML
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_bfile in sync with the dock, monitor the "dirty" property of the layout
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_bobject and call gdl_dock_layout_save_to_file when this changes to
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_bTRUE. No other action is required (the layout_changed is monitored by
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_bthe layout object for you now).
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_bGdlDockObject
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b=============
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_bA DockObject has:
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b- a master, which manages all the objects in a dock ring ("master"
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b property, construct only).
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b- a name. If the object is manual the name can be used to recall the
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b object from any other object in the ring ("name" property).
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b- a long, descriptive name ("long-name" property).
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_bA DockObject can be:
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b- automatic or manual. If it's automatic it means the lifecycle of
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b the object is entirely managed by the dock master. If it's manual
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b in general means the user specified such object, and so it's not to
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b be destroyed automatically at any time.
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b- frozen. In this case any call to reduce on the object has no
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b immediate effect. When the object is later thawn, any pending
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b reduce calls are made (maybe leading to the destruction of the
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b- attached or detached. In general for dock items, being attached
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b will mean the item has its widget->parent set. For docks it will
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b mean they belong to some dock master's ring. In general, automatic
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b objects which are detached will be destroyed (unless frozen).
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b- bound to a master or free. In order to participate in dock
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b operations, each dock object must be bound to a dock master (which
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b is a separate, non-gui object). In general, bindings are treated
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b automatically by the object, and this is entirely true for automatic
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b objects. For manual objects, the master holds an additional
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b reference and has structures to store and recall them by nick names.
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b Normally, a manual object will only be destroyed when it's unbound
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b from the master.
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b- simple or compound. This actually depends on the subclass of the
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b dock object. The difference is made so we can put restrictions in
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b how the objects are docked on top of another (e.g. you can't dock a
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b compound object inside a notebook). If you look at the whole
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b docking layout as a tree, simple objects are the leaves, while all
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b the interior nodes are compound.
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b- reduced. This is only meaningful for compound objects. If the
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b number of contained items has decreased to one the compound type
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b object is no longer necessary to hold the child. In this case the
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b child is reattached to the object's parent. If the number of
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b contained items has reached zero, the object is detached and reduce
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b is called on its parent. For toplevel docks, the object is only
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b detached if it's automatic. In any case, the future of the object
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b itself depends on whether it's automatic or manual.
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b- requested to possibly dock another object. Depending on the
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b type's behavior, the object can accept or reject this request. If
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b it accepts it, it should fill in some additional information
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b regarding how it will host the peer object.
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b- asked to dock another object. Depending on the object's internal
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b structure and behavior two options can be taken: to dock the object
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b directly (e.g. a notebook docking another object); or to create an
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b automatic compound object which will be attached in place of the
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b actual object, and will host both the original object and the
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b requestor (e.g. a simple item docking another simple item, which
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b should create a paned/notebook). The type of the new object will be
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b decided by the original objet based on the docking position.
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_bDETACHING: the action by which an object is unparented. The object is
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_bthen ready to be docked in some other place. Newly created objects
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_bare always detached, except for toplevels (which are created attached
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_bby default). An automatic object which is detached gets destroyed
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_bafterwards, since its ref count drops to zero. Floating automatic
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_btoplevels never reach a zero ref count when detached, since the
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_bGtkWindow always keeps a reference to it (and the GtkWindow has a user
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_breference). That's why floating automatic toplevels are destroyed
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_bwhen reduced.
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_bREDUCING: for compound objects, when the number of contained children
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_bdrops to one or zero, the container is no longer necessary. In this
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_bcase, the object is detached, and any remaining child is reattached to
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_bthe object's former parent. The limit for toplevels is one for
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_bautomatic objects and zero for manual (i.e. they can even be empty).
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_bFor simple (not compound) objects reducing doesn't make sense.
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_bUNBINDING: to participate in a dock ring, every object must be bound
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_bto a master. The master connects to dock item signals and keeps a
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_blist of bound toplevels. Additionally, a reference is kept for manual
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_bobjects (this is so the user doesn't need to keep track of them, but
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_bcan perform operations like hiding and such).
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b- Properties:
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b "floating" (gboolean, construct-only): whether the dock is floating in
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b its own window or not.
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b "default-title" (gchar, read-write): title for new floating docks.
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b This property is proxied to the master, which truly holds it.
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_bThe title for the floating docks is: the user supplied title
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b(GdlDockObject's long_name property) if it's set, the default title
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b(from the master) or an automatically generated title.
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b "layout-changed": emitted when the user changed the layout of the
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b dock somehow.
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b- Functionality for the item grip: provide a11y
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b- Implement notebook tab reordering
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b- Implement dock bands for toolbars and menus.
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b- A dock-related thing is to build resizable toolbars (something like
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b the ones Windows have, where the buttons are reflowed according to
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b the space available).
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b- Redesign paneds so they can hold more than two items and resize all
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b of them at once by using the handle (see if gimpdock does that).
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b- Find a way to allow the merging of menu items to the item's popup
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b menu. Also, there should be a way for the master to insert some
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b menu items.
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b- Bonobo UI synchronizer.
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b- Item behavoirs: implement the ones missing and maybe think more of
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b them (e.g. positions where it's possible to dock the item, etc.)
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b- Make a nicer dragbar for the items, with buttons for undocking,
a0df1b8dd5b14367c583ce2f72a2ca6bf1cde799gustav_b closing, hidding, etc. (See sodipodi, kdevelop)