>GnomeDock

GnomeDock

Name

GnomeDock -- A widget supporting movable and detachable widgets.

Synopsis


#include <gnome.h>


struct      GnomeDock;
enum        GnomeDockPlacement;
GtkWidget*  gnome_dock_new                  (void);
void        gnome_dock_allow_floating_items (GnomeDock *dock,
                                             gboolean enable);
void        gnome_dock_add_item             (GnomeDock *dock,
                                             GnomeDockItem *item,
                                             GnomeDockPlacement placement,
                                             guint band_num,
                                             gint position,
                                             guint offset,
                                             gboolean in_new_band);
void        gnome_dock_add_floating_item    (GnomeDock *dock,
                                             GnomeDockItem *widget,
                                             gint x,
                                             gint y,
                                             GtkOrientation orientation);
void        gnome_dock_set_client_area      (GnomeDock *dock,
                                             GtkWidget *widget);
GtkWidget*  gnome_dock_get_client_area      (GnomeDock *dock);
GnomeDockItem* gnome_dock_get_item_by_name  (GnomeDock *dock,
                                             const gchar *name,
                                             GnomeDockPlacement *placement_return,
                                             guint *num_band_return,
                                             guint *band_position_return,
                                             guint *offset_return);
GnomeDockLayout* gnome_dock_get_layout      (GnomeDock *dock);
gboolean    gnome_dock_add_from_layout      (GnomeDock *dock,
                                             GnomeDockLayout *layout);

Object Hierarchy


  GtkObject
   +----GtkWidget
         +----GtkContainer
               +----GnomeDock

Description

GnomeDock is a container widget designed to let users move around widgets such as toolbars, menubars and so on.

Every GnomeDock contains a widget called the "client area". On the four sides of the client area, there are four "dock areas", which can contain an arbitrary number of dockable widgets. All the dockable widgets should be GnomeDockItem widgets; the GnomeDockItem widget can in turn contain any kind of widget, and implements the dragging functionality: every GnomeDockItem has a handle that users can use to move them within the dock, or even move them outside it, so that they become "floating items".

Every "dock area" is implemented by means of zero or more "dock bands": a dock band is a horizontal or vertical stripe containing one or more dock items, and is implemented by the GnomeDockBand widget. Items are ordered from top to bottom in vertical bands, and from left to right in horizontal bands. Every dock item in a band is given an offset value that defines the distance, in pixels, from the previous item in the same band; if the item is first in the band, the offset defines the distance from the start of the band.

As a consequence, the position of an item in the dock can be specified by means of the following values: a "placement" specifying what area is being used (top, bottom, left, right), a "band number" specifying the number of the band within the specified area, a "position" within the band and a "offset" from the previous item in the same band.

Details

struct GnomeDock

struct GnomeDock;


enum GnomeDockPlacement

typedef enum
{
  GNOME_DOCK_TOP,
  GNOME_DOCK_RIGHT,
  GNOME_DOCK_BOTTOM,
  GNOME_DOCK_LEFT,
  GNOME_DOCK_FLOATING
} GnomeDockPlacement;

This enumeration is used to specify the position of a dock item in the dock widget.


gnome_dock_new ()

GtkWidget*  gnome_dock_new                  (void);

Creates a new GnomeDock widget.

Returns : The new widget.


gnome_dock_allow_floating_items ()

void        gnome_dock_allow_floating_items (GnomeDock *dock,
                                             gboolean enable);

Enable or disable floating items on dock, according to enable.

dock : A pointer to a GnomeDock widget
enable : Specifies whether floating items are allowed in this dock


gnome_dock_add_item ()

void        gnome_dock_add_item             (GnomeDock *dock,
                                             GnomeDockItem *item,
                                             GnomeDockPlacement placement,
                                             guint band_num,
                                             gint position,
                                             guint offset,
                                             gboolean in_new_band);

Add item to dock. placement can be either GNOME_DOCK_TOP, GNOME_DOCK_RIGHT, GNOME_DOCK_BOTTOM or GNOME_DOCK_LEFT, and specifies what area of the dock should contain the item. If in_new_band is TRUE, a new dock band is created at the position specified by band_num; otherwise, the item is added to the band_num'th band.

dock : A pointer to a GnomeDock widget
item : The item to add
placement : Placement for the new item
band_num : Number of the band the new item must be added to
position : Position of the item in the specified band
offset : Offset (in pixels) from the previous item in the same band
in_new_band : Specifies whether a new band must be created for this item


gnome_dock_add_floating_item ()

void        gnome_dock_add_floating_item    (GnomeDock *dock,
                                             GnomeDockItem *widget,
                                             gint x,
                                             gint y,
                                             GtkOrientation orientation);

Add item to dock and make it floating at the specified (x, y) coordinates (relative to the root window of the screen).

dock : A GnomeDock widget
widget : 
x : X-coordinate for the floating item
y : Y-coordinate for the floating item
orientation : Orientation for the new item.


gnome_dock_set_client_area ()

void        gnome_dock_set_client_area      (GnomeDock *dock,
                                             GtkWidget *widget);

Specify a widget for the dock's client area.

dock : A GnomeDock widget
widget : The widget to be used for the client area.


gnome_dock_get_client_area ()

GtkWidget*  gnome_dock_get_client_area      (GnomeDock *dock);

Retrieve the widget being used as the client area in dock.

dock : A GnomeDock widget.
Returns : The client area widget.


gnome_dock_get_item_by_name ()

GnomeDockItem* gnome_dock_get_item_by_name  (GnomeDock *dock,
                                             const gchar *name,
                                             GnomeDockPlacement *placement_return,
                                             guint *num_band_return,
                                             guint *band_position_return,
                                             guint *offset_return);

Retrieve the dock item named name; information about its position in the dock is returned via placement_return, num_band_return, band_position_return and offset_return. If the placement is GNOME_DOCK_FLOATING *num_band_return, *band_position_return and *offset_return are not set.

dock : A GnomeDock widget.
name : The name of the dock item to retrieve
placement_return : A pointer to a variable holding the item's placement
num_band_return : A pointer to a variable holding the band number
band_position_return : A pointer to a variable holding the position of the item within the band
offset_return : A pointer to a variable holding the offset of the item from the previous item in the same band
Returns : The named GnomeDockItem widget, or NULL if no item with such name exists.


gnome_dock_get_layout ()

GnomeDockLayout* gnome_dock_get_layout      (GnomeDock *dock);

Retrieve the layout of dock.

dock : A GnomeDock widget
Returns : dock's layout as a GnomeDockLayout object.


gnome_dock_add_from_layout ()

gboolean    gnome_dock_add_from_layout      (GnomeDock *dock,
                                             GnomeDockLayout *layout);

Add all the items in layout to the specified dock.

dock : The GnomeDock widget
layout : A GnomeDockLayout widget
Returns : TRUE if the operation succeeds, FALSE if it fails.

See Also

GnomeDockItem GnomeDockBand GnomeDockLayout