Gnome User Interface Library Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

# GnomeDockLayout

## Name

GnomeDockLayout -- A widget for saving and retrieving the layout of a GnomeDock widget.

## Synopsis

    #include <gnome.h>

    struct      GnomeDockLayout;
    struct      GnomeDockLayoutItem;
    GnomeDockLayout* gnome_dock_layout_new      (void);
    gboolean    gnome_dock_layout_add_item      (GnomeDockLayout *layout,
                                                 GnomeDockItem *item,
                                                 GnomeDockPlacement placement,
                                                 gint band_num,
                                                 gint band_position,
                                                 gint offset);
    gboolean    gnome_dock_layout_add_floating_item
                                                (GnomeDockLayout *layout,
                                                 GnomeDockItem *item,
                                                 gint x,
                                                 gint y,
                                                 GtkOrientation orientation);
    GnomeDockLayoutItem* gnome_dock_layout_get_item
                                                (GnomeDockLayout *layout,
                                                 GnomeDockItem *item);
    GnomeDockLayoutItem* gnome_dock_layout_get_item_by_name
                                                (GnomeDockLayout *layout,
                                                 const gchar *name);
    gboolean    gnome_dock_layout_remove_item   (GnomeDockLayout *layout,
                                                 GnomeDockItem *item);
    gboolean    gnome_dock_layout_remove_item_by_name
                                                (GnomeDockLayout *layout,
                                                 const gchar *name);
    gchar*      gnome_dock_layout_create_string (GnomeDockLayout *layout);
    gboolean    gnome_dock_layout_parse_string  (GnomeDockLayout *layout,
                                                 const gchar *string);
    gboolean    gnome_dock_layout_add_to_dock   (GnomeDockLayout *layout,
                                                 GnomeDock *dock);

## Object Hierarchy

      GtkObject
       +----GnomeDockLayout

## Description

The GnomeDockLayout widget is meant to make it simple for programmers to handle the layout of a GnomeDock widget.

GnomeDockLayout can contain an arbitrary number of GnomeDockItem widgets, each of them with its own placement information. It is possible to "extract" a layout from an existing GnomeDock widget, as well as adding the items present in a GnomeDockLayout to it. Moreover, GnomeDockLayout is able to create a layout configuration string that can be later used to re-construct the layout on a brand new GnomeDockLayout widget.

As a consequence, GnomeDockLayout is very useful to save and retrieve GnomeDock configurations into files. For example, GnomeApp uses GnomeDockLayout to create a default layout configuration, override it with the user-specific configuration file, and finally apply it to it GnomeDock.

## Details

### struct GnomeDockLayout

    struct GnomeDockLayout;

### struct GnomeDockLayoutItem

    struct GnomeDockLayoutItem
    {
      GnomeDockItem *item;

      GnomeDockPlacement placement;

      union
      {
        struct
        {
          gint x;
          gint y;
          GtkOrientation orientation;
        } floating;

        struct
        {
          gint band_num;
          gint band_position;
          gint offset;
        } docked;

      } position;
    };

### gnome_dock_layout_new ()

    GnomeDockLayout* gnome_dock_layout_new      (void);

Create a new GnomeDockLayout widget.

Returns : | The new GnomeDockLayout widget.

### gnome_dock_layout_add_item ()

    gboolean    gnome_dock_layout_add_item      (GnomeDockLayout *layout,
                                                 GnomeDockItem *item,
                                                 GnomeDockPlacement placement,
                                                 gint band_num,
                                                 gint band_position,
                                                 gint offset);

Add `item` to `layout` with the specified parameters.

`layout` : | A GnomeDockLayout widget
`item` : | The dock item to be added to `layout`
`placement` : | Placement of `item` in `layout`
`band_num` : | Band number
`band_position` : | Position within the band
`offset` : | Distance from the previous element in the band
Returns : | `TRUE` if the operation succeeds, `FALSE` if it fails.

### gnome_dock_layout_add_floating_item ()

    gboolean    gnome_dock_layout_add_floating_item
                                                (GnomeDockLayout *layout,
                                                 GnomeDockItem *item,
                                                 gint x,
                                                 gint y,
                                                 GtkOrientation orientation);

Add `item` to `layout` as a floating item with the specified (`x`, `y`) position and `orientation`.

`layout` : | A GnomeDockLayout widget
`item` : | The dock item to be added to `layout`
`x` : | X-coordinate for the floating item
`y` : | Y-coordinate for the floating item
`orientation` : | Orientation for the floating item
Returns : | `TRUE` if the operation succeeds, `FALSE` if it fails.

### gnome_dock_layout_get_item ()

    GnomeDockLayoutItem* gnome_dock_layout_get_item
                                                (GnomeDockLayout *layout,
                                                 GnomeDockItem *item);

Retrieve a layout item.

`layout` : | A GnomeDockLayout widget
`item` : | The GnomeDockItem to be retrieved
Returns : | The retrieved GnomeDockLayoutItem widget.

### gnome_dock_layout_get_item_by_name ()

    GnomeDockLayoutItem* gnome_dock_layout_get_item_by_name
                                                (GnomeDockLayout *layout,
                                                 const gchar *name);

Retrieve the dock item named `name`.

`layout` : | A GnomeDockLayout widget
`name` : | Name of the item to be retrieved
Returns : | The named GnomeDockLayoutItem widget.

### gnome_dock_layout_remove_item ()

    gboolean    gnome_dock_layout_remove_item   (GnomeDockLayout *layout,
                                                 GnomeDockItem *item);

Remove the specified `item` from `layout`.

`layout` : | A GnomeDockLayout widget
`item` : | The GnomeDockItem to be removed
Returns : | `TRUE` if the operation succeeds, `FALSE` if it fails.

### gnome_dock_layout_remove_item_by_name ()

    gboolean    gnome_dock_layout_remove_item_by_name
                                                (GnomeDockLayout *layout,
                                                 const gchar *name);

Remove the item named `name` from `layout`.

`layout` : | A GnomeDockLayout widget
`name` : | Name of the GnomeDockItem to be removed
Returns : | `TRUE` if the operation succeeds, `FALSE` if it fails.

### gnome_dock_layout_create_string ()

    gchar*      gnome_dock_layout_create_string (GnomeDockLayout *layout);

Generate a string describing the layout in `layout`.

`layout` : | A GnomeDockLayout widget
Returns : | The (malloced) layout string for `layout`.

### gnome_dock_layout_parse_string ()

    gboolean    gnome_dock_layout_parse_string  (GnomeDockLayout *layout,
                                                 const gchar *string);

Parse the layout string `string`, and move around the items in `layout` accordingly.

`layout` : | A GnomeDockLayout widget
`string` : | A layout string to be parsed
Returns : | `TRUE` if the operation succeeds, `FALSE` if it fails.

### gnome_dock_layout_add_to_dock ()

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

Add all the items in `layout` to the specified `dock`.

`layout` : | A GnomeDockLayout widget
`dock` : | The GnomeDock widget the layout items must be added to
Returns : | `TRUE` if the operation succeeds, `FALSE` if it fails.

## See Also

GnomeDock GnomeDockItem GnomeDockBand

<<< Previous Page | Home | Up | Next Page >>>
GnomeSpell | GnomeProcBar