GdlDockObject: GNOME Docking Library Reference Manual

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

## Stability Level

Unstable, unless otherwise indicated

## Functions

#define | GDL_DOCK_OBJECT_ATTACHED()
#define | GDL_DOCK_OBJECT_AUTOMATIC()
#define | GDL_DOCK_OBJECT_FLAGS()
#define | GDL_DOCK_OBJECT_FROZEN()
#define | GDL_DOCK_OBJECT_IN_DETACH()
#define | GDL_DOCK_OBJECT_IN_REFLOW()
#define | GDL_DOCK_OBJECT_SET_FLAGS()
#define | GDL_DOCK_OBJECT_UNSET_FLAGS()
#define | GDL_TRACE_OBJECT()
void | gdl_dock_object_bind ()
gboolean | gdl_dock_object_child_placement ()
void | gdl_dock_object_detach ()
void | gdl_dock_object_dock ()
gboolean | gdl_dock_object_dock_request ()
void | gdl_dock_object_freeze ()
GdlDockObject * | gdl_dock_object_get_parent_object ()
gboolean | gdl_dock_object_is_bound ()
gboolean | gdl_dock_object_is_compound ()
const gchar * | gdl_dock_object_nick_from_type ()
void | gdl_dock_object_present ()
void | gdl_dock_object_reduce ()
gboolean | gdl_dock_object_reorder ()
GType | gdl_dock_object_set_type_for_nick ()
void | gdl_dock_object_thaw ()
GType | gdl_dock_object_type_from_nick ()
void | gdl_dock_object_unbind ()

## Properties

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

## Signals

void | detach | Run Last
void | dock | Run First

## Types and Values

#define | GDL_DOCK_OBJECT_FLAGS_SHIFT
struct | GdlDockObject
struct | GdlDockObjectClass
enum | GdlDockObjectFlags
enum | GdlDockParamFlags
enum | GdlDockPlacement
struct | GdlDockRequest

## Object Hierarchy

        GEnum
        ╰── GdlDockPlacement
        GFlags
        ├── GdlDockObjectFlags
        ╰── GdlDockParamFlags
        GObject
        ╰── GInitiallyUnowned
            ╰── GtkWidget
                ╰── GtkContainer
                    ╰── GdlDockObject
                        ├── GdlDock
                        ├── GdlDockItem
                        ╰── GdlDockPlaceholder

## Implemented Interfaces

GdlDockObject implements AtkImplementorIface and GtkBuildable.

## Description

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

## Functions

### GDL_DOCK_OBJECT_ATTACHED()

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

`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.

#### Parameters

obj | A GdlDockObject |

### GDL_DOCK_OBJECT_AUTOMATIC()

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

`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.

#### Parameters

obj | A GdlDockObject |

### GDL_DOCK_OBJECT_FLAGS()

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

`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.

#### Parameters

obj | A GdlDockObject |

### GDL_DOCK_OBJECT_FROZEN()

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

`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.

#### Parameters

obj | A GdlDockObject |

### GDL_DOCK_OBJECT_IN_DETACH()

    #define             GDL_DOCK_OBJECT_IN_DETACH(obj)

`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.

#### Parameters

obj | A GdlDockObject |

### GDL_DOCK_OBJECT_IN_REFLOW()

    #define             GDL_DOCK_OBJECT_IN_REFLOW(obj)

`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.

#### Parameters

obj | A GdlDockObject |

### GDL_DOCK_OBJECT_SET_FLAGS()

    #define             GDL_DOCK_OBJECT_SET_FLAGS(obj,flag)

`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.

#### Parameters

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

### GDL_DOCK_OBJECT_UNSET_FLAGS()

    #define             GDL_DOCK_OBJECT_UNSET_FLAGS(obj,flag)

`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.

#### Parameters

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.

#### Parameters

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

### 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.

#### Parameters

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` .

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

object | A GdlDockObject |

## Types and Values

### GDL_DOCK_OBJECT_FLAGS_SHIFT

    #define GDL_DOCK_OBJECT_FLAGS_SHIFT 8

`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.

### 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

`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()`.

#### Members

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

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

#### Members

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

Described the docking position.

#### Members

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.

#### Members

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 |

## Property Details

### The `“long-name”` property

      “long-name”                gchar *

A long descriptive name.

Owner: GdlDockObject

Flags: Read / Write / Construct

Default value: NULL

### The `“master”` property

      “master”                   GdlDockMaster *

The master which manages all the objects in a dock ring

Owner: GdlDockObject

Flags: Read / Write / Construct

### The `“name”` property

      “name”                     gchar *

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

Owner: GdlDockObject

Flags: Read / Write / Construct Only

Default value: NULL

### The `“pixbuf-icon”` property

      “pixbuf-icon”              gpointer

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

Owner: GdlDockObject

Flags: Read / Write

Since: 3.3.2

### The `“stock-id”` property

      “stock-id”                 gchar *

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

Owner: GdlDockObject

Flags: Read / Write / Construct

Default value: NULL

## Signal Details

### The `“detach”` signal

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

Signals that the GdlDockObject is detached.

#### Parameters

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. |

Flags: Run Last

### The `“dock”` signal

    void
    user_function (GdlDockObject   *item,
                   GdlDockObject   *requestor,
                   GdlDockPlacement position,
                   GValue          *other_data,
                   gpointer         user_data)

Signals that the GdlDockObject has been docked.

#### Parameters

item | The docked dock object. |
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. |

Flags: Run First

## See Also

GdlDockMaster