GdlDockObject

## GdlDockObject GdlDockObject — Base class for all dock objects |

## Stability Level

Unstable, unless otherwise indicated

## Synopsis

    #define             GDL_DOCK_OBJECT_ATTACHED            (obj)
    #define             GDL_DOCK_OBJECT_AUTOMATIC           (obj)
    #define             GDL_DOCK_OBJECT_FLAGS               (obj)
    #define             GDL_DOCK_OBJECT_FLAGS_SHIFT
    #define             GDL_DOCK_OBJECT_FROZEN              (obj)
    #define             GDL_DOCK_OBJECT_IN_DETACH           (obj)
    #define             GDL_DOCK_OBJECT_IN_REFLOW           (obj)
    #define             GDL_DOCK_OBJECT_SET_FLAGS           (obj,
                                                             flag)
    #define             GDL_DOCK_OBJECT_UNSET_FLAGS         (obj,
                                                             flag)
    #define             GDL_TRACE_OBJECT                    (object,
                                                             format,
                                                             ...)
    struct              GdlDockObject;
    struct              GdlDockObjectClass;
    enum                GdlDockObjectFlags;
    enum                GdlDockParamFlags;
    enum                GdlDockPlacement;
    struct              GdlDockRequest;
    void                gdl_dock_object_bind                (GdlDockObject *object,
                                                             GObject *master);
    gboolean            gdl_dock_object_child_placement     (GdlDockObject *object,
                                                             GdlDockObject *child,
                                                             GdlDockPlacement *placement);
    void                gdl_dock_object_detach              (GdlDockObject *object,
                                                             gboolean recursive);
    void                gdl_dock_object_dock                (GdlDockObject *object,
                                                             GdlDockObject *requestor,
                                                             GdlDockPlacement position,
                                                             GValue *other_data);
    gboolean            gdl_dock_object_dock_request        (GdlDockObject *object,
                                                             gint x,
                                                             gint y,
                                                             GdlDockRequest *request);
    void                gdl_dock_object_freeze              (GdlDockObject *object);
    GdlDockObject *     gdl_dock_object_get_parent_object   (GdlDockObject *object);
    gboolean            gdl_dock_object_is_bound            (GdlDockObject *object);
    gboolean            gdl_dock_object_is_compound         (GdlDockObject *object);
    const gchar *       gdl_dock_object_nick_from_type      (GType type);
    void                gdl_dock_object_present             (GdlDockObject *object,
                                                             GdlDockObject *child);
    void                gdl_dock_object_reduce              (GdlDockObject *object);
    gboolean            gdl_dock_object_reorder             (GdlDockObject *object,
                                                             GdlDockObject *child,
                                                             GdlDockPlacement new_position,
                                                             GValue *other_data);
    GType               gdl_dock_object_set_type_for_nick   (const gchar *nick,
                                                             GType type);
    void                gdl_dock_object_thaw                (GdlDockObject *object);
    GType               gdl_dock_object_type_from_nick      (const gchar *nick);
    void                gdl_dock_object_unbind              (GdlDockObject *object);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----GtkWidget
                   +----GtkContainer
                         +----GdlDockObject
                               +----GdlDock
                               +----GdlDockItem
                               +----GdlDockPlaceholder

## Implemented Interfaces

GdlDockObject implements AtkImplementorIface and GtkBuildable.

## Properties

      "long-name"                gchar*                : Read / Write / Construct
      "master"                   GdlDockMaster*        : Read / Write / Construct
      "name"                     gchar*                : Read / Write / Construct Only
      "pixbuf-icon"              gpointer              : Read / Write
      "stock-id"                 gchar*                : Read / Write / Construct

## Signals

      "detach"                                         : Run Last
      "dock"                                           : Run First

## Description

A GdlDockObject is an abstract class which defines the basic interface for docking widgets.

## Details

### GDL_DOCK_OBJECT_ATTACHED()

    #define GDL_DOCK_OBJECT_ATTACHED(obj) (!gdl_dock_object_is_closed(GDL_DOCK_OBJECT (obj)))

### Warning

`GDL_DOCK_OBJECT_ATTACHED` has been deprecated since version 3.6 and should not be used in newly-written code. Use

Evaluates to `TRUE` if the object has a parent.

`obj` : | A GdlDockObject

### GDL_DOCK_OBJECT_AUTOMATIC()

    #define GDL_DOCK_OBJECT_AUTOMATIC(obj) gdl_dock_object_is_automatic (GDL_DOCK_OBJECT (obj))

### Warning

`GDL_DOCK_OBJECT_AUTOMATIC` has been deprecated since version 3.6 and should not be used in newly-written code. Use `gdl_dock_object_is_automatic()`

Evaluates to `TRUE` if the object's lifecycle is entirely managed by the dock master.

`obj` : | A GdlDockObject

### GDL_DOCK_OBJECT_FLAGS()

    #define GDL_DOCK_OBJECT_FLAGS(obj)  (GDL_DOCK_OBJECT (obj)->deprecated_flags)

### Warning

`GDL_DOCK_OBJECT_FLAGS` has been deprecated since version 3.6 and should not be used in newly-written code. The flags are not accessible anymore.

Get all flags of GdlDockObject.

`obj` : | A GdlDockObject

### GDL_DOCK_OBJECT_FLAGS_SHIFT

    #define GDL_DOCK_OBJECT_FLAGS_SHIFT 8

### Warning

`GDL_DOCK_OBJECT_FLAGS_SHIFT` has been deprecated since version 3.6 and should not be used in newly-written code. Use a private flag instead

Minimum shift count to be used for user defined flags, to be stored in GdlDockObject.flags.

### GDL_DOCK_OBJECT_FROZEN()

    #define GDL_DOCK_OBJECT_FROZEN(obj) gdl_dock_object_is_frozen(GDL_DOCK_OBJECT (obj))

### Warning

`GDL_DOCK_OBJECT_FROZEN` has been deprecated since version 3.6 and should not be used in newly-written code. Use `gdl_dock_object_is_frozen()`

Evaluates to `TRUE` if the object is frozen.

`obj` : | A GdlDockObject

### GDL_DOCK_OBJECT_IN_DETACH()

    #define             GDL_DOCK_OBJECT_IN_DETACH(obj)

### Warning

`GDL_DOCK_OBJECT_IN_DETACH` has been deprecated since version 3.6 and should not be used in newly-written code. This flag is no longer available

Evaluates to `TRUE` if the object will be detached.

`obj` : | A GdlDockObject

### GDL_DOCK_OBJECT_IN_REFLOW()

    #define             GDL_DOCK_OBJECT_IN_REFLOW(obj)

### Warning

`GDL_DOCK_OBJECT_IN_REFLOW` has been deprecated since version 3.6 and should not be used in newly-written code. Use `gdl_dock_object_is_frozen()`

Evaluates to `TRUE` if the object is currently rearranged.

`obj` : | A GdlDockObject

### GDL_DOCK_OBJECT_SET_FLAGS()

    #define             GDL_DOCK_OBJECT_SET_FLAGS(obj,flag)

### Warning

`GDL_DOCK_OBJECT_SET_FLAGS` has been deprecated since version 3.6 and should not be used in newly-written code. This flags are no longer accessible.

Set one or more flags of a dock object.

`obj` : | A GdlDockObject
`flag` : | One or more GdlDockObjectFlags

### GDL_DOCK_OBJECT_UNSET_FLAGS()

    #define             GDL_DOCK_OBJECT_UNSET_FLAGS(obj,flag)

### Warning

`GDL_DOCK_OBJECT_UNSET_FLAGS` has been deprecated since version 3.6 and should not be used in newly-written code. This flags are no longer accessible.

Clear one or more flags of a dock object.

`obj` : | A GdlDockObject
`flag` : | One or more GdlDockObjectFlags

### GDL_TRACE_OBJECT()

    #define             GDL_TRACE_OBJECT(object, format, args...)

Output a debugging message for the corresponding dock object.

`object` : | A GdlDockObject
`format` : | Additional printf format string
`...` : | Additional arguments

### struct GdlDockObject

    struct GdlDockObject;

### struct GdlDockObjectClass

    struct GdlDockObjectClass {
        GtkContainerClass parent_class;

        GdlDockObjectClassPrivate *priv;

        void     (* detach)          (GdlDockObject    *object,
                                      gboolean          recursive);
        void     (* reduce)          (GdlDockObject    *object);

        gboolean (* dock_request)    (GdlDockObject    *object,
                                      gint              x,
                                      gint              y,
                                      GdlDockRequest   *request);

        void     (* dock)            (GdlDockObject    *object,
                                      GdlDockObject    *requestor,
                                      GdlDockPlacement  position,
                                      GValue           *other_data);

        gboolean (* reorder)         (GdlDockObject    *object,
                                      GdlDockObject    *child,
                                      GdlDockPlacement  new_position,
                                      GValue           *other_data);

        void     (* present)         (GdlDockObject    *object,
                                      GdlDockObject    *child);

        gboolean (* child_placement) (GdlDockObject    *object,
                                      GdlDockObject    *child,
                                      GdlDockPlacement *placement);
    };

### enum GdlDockObjectFlags

    typedef enum {
        GDL_DOCK_AUTOMATIC  = 1 << 0,
        GDL_DOCK_ATTACHED   = 1 << 1,
        GDL_DOCK_IN_REFLOW  = 1 << 2,
        GDL_DOCK_IN_DETACH  = 1 << 3
    } GdlDockObjectFlags;

### Warning

`GdlDockObjectFlags` is deprecated and should not be used in newly-written code.

Described the state of a GdlDockObject.

Since 3.6: These flags are available using access function, like `gdl_dock_object_is_automatic()` or `gdl_dock_object_is_closed()`.

`GDL_DOCK_AUTOMATIC` | Object is created and destroyed by the master, not the user
`GDL_DOCK_ATTACHED` | Object has a parent
`GDL_DOCK_IN_REFLOW` | Object is currently part of a rearrangement
`GDL_DOCK_IN_DETACH` | Object will be removed

### enum GdlDockParamFlags

    typedef enum {
        /* the parameter is to be exported for later layout rebuilding */
        GDL_DOCK_PARAM_EXPORT = 1 << G_PARAM_USER_SHIFT,
        /* the parameter must be set after adding the children objects */
        GDL_DOCK_PARAM_AFTER  = 1 << (G_PARAM_USER_SHIFT + 1)
    } GdlDockParamFlags;

Used to flag additional characteristics to GObject properties used in dock object.

`GDL_DOCK_PARAM_EXPORT` | The parameter is to be exported for later layout rebuilding
`GDL_DOCK_PARAM_AFTER` | The parameter must be set after adding the children objects

### enum GdlDockPlacement

    typedef enum {
        GDL_DOCK_NONE = 0,
        GDL_DOCK_TOP,
        GDL_DOCK_BOTTOM,
        GDL_DOCK_RIGHT,
        GDL_DOCK_LEFT,
        GDL_DOCK_CENTER,
        GDL_DOCK_FLOATING
    } GdlDockPlacement;

Described the docking position.

`GDL_DOCK_NONE` | No position defined
`GDL_DOCK_TOP` | Dock object on the top
`GDL_DOCK_BOTTOM` | Dock object on the bottom
`GDL_DOCK_RIGHT` | Dock object on the right
`GDL_DOCK_LEFT` | Dock object on the left
`GDL_DOCK_CENTER` | Dock object on top of the other
`GDL_DOCK_FLOATING` | Dock object in its own window

### struct GdlDockRequest

    struct GdlDockRequest {
        GdlDockObject               *applicant;
        GdlDockObject               *target;
        GdlDockPlacement            position;
        cairo_rectangle_int_t       rect;
        GValue                      extra;
    };

Full docking information.

GdlDockObject *`applicant`; | A GdlDockObject to dock
GdlDockObject *`target`; | The GdlDockObject target
GdlDockPlacement `position`; | how to dock `applicant` in `target`
cairo_rectangle_int_t `rect`; | Precise position
GValue `extra`; | Additional information

### gdl_dock_object_bind ()

    void                gdl_dock_object_bind                (GdlDockObject *object,
                                                             GObject *master);

Add a link between a GdlDockObject and a master. It is normally not used directly because it is automatically called when a new object is docked.

`object` : | A GdlDockObject
`master` : | A GdlDockMaster

### gdl_dock_object_child_placement ()

    gboolean            gdl_dock_object_child_placement     (GdlDockObject *object,
                                                             GdlDockObject *child,
                                                             GdlDockPlacement *placement);

This function returns information about placement of a child dock object inside another dock object. The function returns `TRUE` if `child` is effectively a child of `object`. `placement` should normally be initially setup to `GDL_DOCK_NONE`. If it's set to some other value, this function will not touch the stored value if the specified placement is "compatible" with the actual placement of the child.

`placement` can be `NULL`, in which case the function simply tells if `child` is attached to `object`.

`object` : | the dock object we are asking for child placement
`child` : | the child of the `object` we want the placement for
`placement` : | where to return the placement information. [allow-none]
Returns : | `TRUE` if `child` is a child of `object`.

### gdl_dock_object_detach ()

    void                gdl_dock_object_detach              (GdlDockObject *object,
                                                             gboolean recursive);

Dissociate a dock object from its parent, including or not its children.

`object` : | A GdlDockObject
`recursive` : | `TRUE` to detach children

### gdl_dock_object_dock ()

    void                gdl_dock_object_dock                (GdlDockObject *object,
                                                             GdlDockObject *requestor,
                                                             GdlDockPlacement position,
                                                             GValue *other_data);

Dock a dock widget in `object` at the defined position.

`object` : | A GdlDockObject
`requestor` : | The widget to dock
`position` : | The position for the child
`other_data` : | Optional data giving additional information depending on the dock object. [allow-none]

### gdl_dock_object_dock_request ()

    gboolean            gdl_dock_object_dock_request        (GdlDockObject *object,
                                                             gint x,
                                                             gint y,
                                                             GdlDockRequest *request);

Dock a dock widget in `object` at the defined position.

`object` : | A GdlDockObject
`x` : | X coordinate
`y` : | Y coordinate
`request` : | A GdlDockRequest with information about the docking position
Returns : | `TRUE` if `object` has been docked.

### gdl_dock_object_freeze ()

    void                gdl_dock_object_freeze              (GdlDockObject *object);

Temporarily freezes a dock object, any call to reduce on the object has no immediate effect. If `gdl_dock_object_freeze()` has been called more than once, `gdl_dock_object_thaw()` must be called an equal number of times.

`object` : | A GdlDockObject

### gdl_dock_object_get_parent_object ()

    GdlDockObject *     gdl_dock_object_get_parent_object   (GdlDockObject *object);

Returns a parent GdlDockObject if it exists.

`object` : | A GdlDockObject
Returns : | a GdlDockObject or `NULL` if such object does not exist. [allow-none][transfer none]

### gdl_dock_object_is_bound ()

    gboolean            gdl_dock_object_is_bound            (GdlDockObject *object);

Check if the object is bound to a master.

`object` : | A GdlDockObject
Returns : | `TRUE` if `object` has a master

### gdl_dock_object_is_compound ()

    gboolean            gdl_dock_object_is_compound         (GdlDockObject *object);

Check if an object is a compound object, accepting children widget or not.

`object` : | A GdlDockObject
Returns : | `TRUE` if `object` is a compound object.

### gdl_dock_object_nick_from_type ()

    const gchar *       gdl_dock_object_nick_from_type      (GType type);

Finds the nickname for a given type

`type` : | The type for which to find the nickname
Returns : | If the object has a nickname, then it is returned. Otherwise, the type name.

### gdl_dock_object_present ()

    void                gdl_dock_object_present             (GdlDockObject *object,
                                                             GdlDockObject *child);

Presents the GDL object to the user. By example, this will select the corresponding page if the object is in a notebook. If `child` is missing, only the `object` will be show.

`object` : | A GdlDockObject
`child` : | The child widget to present or `NULL`. [allow-none]

### gdl_dock_object_reduce ()

    void                gdl_dock_object_reduce              (GdlDockObject *object);

Remove a compound object if it is not longer useful to hold the child. The object has to be removed and the child reattached to the parent.

`object` : | A GdlDockObject

### gdl_dock_object_reorder ()

    gboolean            gdl_dock_object_reorder             (GdlDockObject *object,
                                                             GdlDockObject *child,
                                                             GdlDockPlacement new_position,
                                                             GValue *other_data);

Move the `child` widget at another place.

`object` : | A GdlDockObject
`child` : | The child widget to reorder
`new_position` : | New position for the child
`other_data` : | Optional data giving additional information depending on the dock object. [allow-none]
Returns : | `TRUE` if `child` has been moved

### gdl_dock_object_set_type_for_nick ()

    GType               gdl_dock_object_set_type_for_nick   (const gchar *nick,
                                                             GType type);

Assigns an object type to a given nickname. If the nickname already exists, then it reassigns it to a new object type.

`nick` : | The nickname for the object type
`type` : | The object type
Returns : | If the nick was previously assigned, the old type is returned. Otherwise, `G_TYPE_NONE`.

### gdl_dock_object_thaw ()

    void                gdl_dock_object_thaw                (GdlDockObject *object);

Thaws a dock object frozen with `gdl_dock_object_freeze()`. Any pending reduce calls are made, maybe leading to the destruction of the object.

`object` : | A GdlDockObject

### gdl_dock_object_type_from_nick ()

    GType               gdl_dock_object_type_from_nick      (const gchar *nick);

Finds the object type assigned to a given nickname.

`nick` : | The nickname for the object type
Returns : | If the nickname has previously been assigned, then the corresponding object type is returned. Otherwise, `G_TYPE_NONE`.

### gdl_dock_object_unbind ()

    void                gdl_dock_object_unbind              (GdlDockObject *object);

This removes the link between an dock object and its master.

`object` : | A GdlDockObject

## Property Details

### The `"long-name"` property

      "long-name"                gchar*                : Read / Write / Construct

A long descriptive name.

Default value: NULL

### The `"master"` property

      "master"                   GdlDockMaster*        : Read / Write / Construct

The master which manages all the objects in a dock ring

### The `"name"` property

      "name"                     gchar*                : Read / Write / Construct Only

The object name. If the object is manual the name can be used to recall the object from any other object in the ring

Default value: NULL

### The `"pixbuf-icon"` property

      "pixbuf-icon"              gpointer              : Read / Write

A GdkPixbuf to use for the icon of the dock object.

Since 3.3.2

### The `"stock-id"` property

      "stock-id"                 gchar*                : Read / Write / Construct

A stock id to use for the icon of the dock object.

Default value: NULL

## Signal Details

### The `"detach"` signal

    void                user_function                      (GdlDockObject *item,
                                                            gboolean       recursive,
                                                            gpointer       user_data)      : Run Last

Signals that the GdlDockObject is detached.

`item` : | The detached dock object.
`recursive` : | `TRUE` if children have to be detached too.
`user_data` : | user data set when the signal handler was connected.

### The `"dock"` signal

    void                user_function                      (GdlDockObject   *requestor,
                                                            GdlDockObject   *position,
                                                            GdlDockPlacement other_data,
                                                            GValue          *arg3,
                                                            gpointer         user_data)       : Run First

Signals that the GdlDockObject has been docked.

`requestor` : | The widget to dock
`position` : | The position for the child
`other_data` : | Optional data giving additional information. [allow-none]
`user_data` : | user data set when the signal handler was connected.

## See Also

GdlDockMaster