GdlDockItem

GdlDockItem — Adds docking capability to its child widget.

Stability Level

Unstable, unless otherwise indicated

Properties

GdlDockItemBehavior behavior Read / Write
gboolean closed Read / Write
gboolean iconified Read / Write
gboolean locked Read / Write
GtkOrientation orientation Read / Write / Construct
gint preferred-height Read / Write
gint preferred-width Read / Write
gboolean resize Read / Write

Types and Values

Object Hierarchy

    GFlags
    ├── GdlDockItemBehavior
    ╰── GdlDockItemFlags
    GObject
    ╰── GInitiallyUnowned
        ╰── GtkWidget
            ╰── GtkContainer
                ╰── GdlDockObject
                    ╰── GdlDockItem
                        ├── GdlDockNotebook
                        ╰── GdlDockPaned

Implemented Interfaces

GdlDockItem implements AtkImplementorIface and GtkBuildable.

Description

A dock item is a container widget that can be docked at different place. It accepts a single child and adds a grip allowing the user to click on it to drag and drop the widget.

The grip is implemented as a GdlDockItemGrip.

Functions

GDL_DOCK_ITEM_CANT_CLOSE()

#define GDL_DOCK_ITEM_CANT_CLOSE(item) ((gdl_dock_item_get_behavior_flags(item) & GDL_DOCK_ITEM_BEH_CANT_CLOSE) != 0)

Evaluates to TRUE the item cannot be closed.

Parameters

item

A GdlDockObject

 

GDL_DOCK_ITEM_CANT_ICONIFY()

#define GDL_DOCK_ITEM_CANT_ICONIFY(item) ((gdl_dock_item_get_behavior_flags(item) & GDL_DOCK_ITEM_BEH_CANT_ICONIFY) != 0)

Evaluates to TRUE the item cannot be iconifyed.

Parameters

item

A GdlDockObject

 

GDL_DOCK_ITEM_FLAGS()

#define GDL_DOCK_ITEM_FLAGS(item)     (GDL_DOCK_OBJECT (item)->flags)

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

Use GDL_DOCK_OBJECT_FLAGS instead

Get all flags of GdlDockObject.

Parameters

item

A GdlDockObject

 

GDL_DOCK_ITEM_HAS_GRIP()

#define GDL_DOCK_ITEM_HAS_GRIP(item) ((gdl_dock_item_get_behavior_flags (item) & GDL_DOCK_ITEM_BEH_NO_GRIP) == 0)

Evaluates to TRUE the item has a handle, so it can be moved.

Parameters

item

A GdlDockObject

 

GDL_DOCK_ITEM_ICONIFIED()

#define             GDL_DOCK_ITEM_ICONIFIED(item)

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

Use GDL_DOCK_OBJECT_UNSET_FLAGS instead

Evaluates to TRUE if the item is iconified, appearing only as a button in the dock bar.

Parameters

item

A GdlDockObject

 

GDL_DOCK_ITEM_IN_DRAG()

#define             GDL_DOCK_ITEM_IN_DRAG(item)

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

Use a private flag instead

Evaluates to TRUE if the user is dragging the item.

Parameters

item

A GdlDockObject

 

GDL_DOCK_ITEM_IN_PREDRAG()

#define             GDL_DOCK_ITEM_IN_PREDRAG(item)

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

Use a private flag instead

Evaluates to TRUE if the user has clicked on the item but hasn't made a big enough move to start the drag operation.

Parameters

item

A GdlDockObject

 

GDL_DOCK_ITEM_NOT_LOCKED()

#define GDL_DOCK_ITEM_NOT_LOCKED(item) ((gdl_dock_item_get_behavior_flags(item) & GDL_DOCK_ITEM_BEH_LOCKED) == 0)

Evaluates to TRUE the item can be moved, closed, or iconified.

Parameters

item

A GdlDockObject

 

GDL_DOCK_ITEM_NO_GRIP()

#define GDL_DOCK_ITEM_NO_GRIP(item) ((gdl_dock_item_get_behavior_flags(item) & GDL_DOCK_ITEM_BEH_NO_GRIP) != 0)

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

Use !GDL_DOCK_ITEM_HAS_GRIP instead

Evaluates to TRUE the item has not handle, so it cannot be moved.

Parameters

item

A GdlDockObject

 

GDL_DOCK_ITEM_SET_FLAGS()

#define             GDL_DOCK_ITEM_SET_FLAGS(item,flag)

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

Use GDL_DOCK_OBJECT_SET_FLAGS instead

Set one or more flags of a dock object.

Parameters

item

A GdlDockObject

 

flag

One or more GdlDockObjectFlags

 

GDL_DOCK_ITEM_UNSET_FLAGS()

#define             GDL_DOCK_ITEM_UNSET_FLAGS(item,flag)

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

Use GDL_DOCK_OBJECT_UNSET_FLAGS instead

Clear one or more flags of a dock object.

Parameters

item

A GdlDockObject

 

flag

One or more GdlDockObjectFlags

 

GDL_DOCK_ITEM_USER_ACTION()

#define             GDL_DOCK_ITEM_USER_ACTION(item)

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

Use a private flag instead

Evaluates to TRUE if the user currently use the item, by example dragging division of a GdlDockPaned object.

Parameters

item

A GdlDockObject

 

gdl_dock_item_new ()

GtkWidget *
gdl_dock_item_new (const gchar *name,
                   const gchar *long_name,
                   GdlDockItemBehavior behavior);

Creates a new dock item widget.

Parameters

name

Unique name for identifying the dock object.

 

long_name

Human readable name for the dock object.

 

behavior

General behavior for the dock item (i.e. whether it can float, if it's locked, etc.), as specified by GdlDockItemBehavior flags.

 

Returns

The newly created dock item grip widget.


gdl_dock_item_new_with_pixbuf_icon ()

GtkWidget *
gdl_dock_item_new_with_pixbuf_icon (const gchar *name,
                                    const gchar *long_name,
                                    const GdkPixbuf *pixbuf_icon,
                                    GdlDockItemBehavior behavior);

Creates a new dock item grip widget with a given pixbuf icon.

Parameters

name

Unique name for identifying the dock object.

 

long_name

Human readable name for the dock object.

 

pixbuf_icon

Pixbuf icon for the dock object.

 

behavior

General behavior for the dock item (i.e. whether it can float, if it's locked, etc.), as specified by GdlDockItemBehavior flags.

 

Returns

The newly created dock item grip widget.

Since 3.3.2


gdl_dock_item_new_with_stock ()

GtkWidget *
gdl_dock_item_new_with_stock (const gchar *name,
                              const gchar *long_name,
                              const gchar *stock_id,
                              GdlDockItemBehavior behavior);

Creates a new dock item grip widget with a given stock id.

Parameters

name

Unique name for identifying the dock object.

 

long_name

Human readable name for the dock object.

 

stock_id

Stock icon for the dock object.

 

behavior

General behavior for the dock item (i.e. whether it can float, if it's locked, etc.), as specified by GdlDockItemBehavior flags.

 

Returns

The newly created dock item grip widget.


gdl_dock_item_bind ()

void
gdl_dock_item_bind (GdlDockItem *item,
                    GtkWidget *dock);

Binds this dock item to a new dock master.

Parameters

item

The item to bind.

 

dock

The GdlDock widget to bind it to. Note that this widget must be a type of GdlDock.

 

gdl_dock_item_unbind ()

void
gdl_dock_item_unbind (GdlDockItem *item);

Unbinds this dock item from it's dock master.

Parameters

item

The item to unbind.

 

gdl_dock_item_show_grip ()

void
gdl_dock_item_show_grip (GdlDockItem *item);

This function shows the dock item's grip widget.

Parameters

item

The dock item to show the grip of.

 

gdl_dock_item_hide_grip ()

void
gdl_dock_item_hide_grip (GdlDockItem *item);

This function hides the dock item's grip widget.

Parameters

item

The dock item to hide the grip of.

 

gdl_dock_item_show_item ()

void
gdl_dock_item_show_item (GdlDockItem *item);

This function shows the dock item. When dock items are shown, they are displayed in their normal layout position.

Parameters

item

The dock item to show.

 

gdl_dock_item_hide_item ()

void
gdl_dock_item_hide_item (GdlDockItem *item);

This function hides the dock item. Since version 3.6, when dock items are hidden they are not removed from the layout.

The dock item close button causes the panel to be hidden.

Parameters

item

The dock item to hide.

 

gdl_dock_item_iconify_item ()

void
gdl_dock_item_iconify_item (GdlDockItem *item);

This function iconifies the dock item. When dock items are iconified they are hidden, and appear only as icons in dock bars.

The dock item iconify button causes the panel to be iconified.

Parameters

item

The dock item to iconify.

 

gdl_dock_item_dock_to ()

void
gdl_dock_item_dock_to (GdlDockItem *item,
                       GdlDockItem *target,
                       GdlDockPlacement position,
                       gint docking_param);

Relocates a dock item to a new location relative to another dock item.

Parameters

item

The dock item that will be relocated to the dock position.

 

target

The dock item that will be used as the point of reference.

[allow-none]

position

The position to dock item, relative to target.

 

docking_param

This value is unused, and will be ignored.

 

gdl_dock_item_lock ()

void
gdl_dock_item_lock (GdlDockItem *item);

This function locks the dock item. When locked the dock item cannot be dragged around and it doesn't show a grip.

Parameters

item

The dock item to lock.

 

gdl_dock_item_unlock ()

void
gdl_dock_item_unlock (GdlDockItem *item);

This function unlocks the dock item. When unlocked the dock item can be dragged around and can show a grip.

Parameters

item

The dock item to unlock.

 

gdl_dock_item_notify_deselected ()

void
gdl_dock_item_notify_deselected (GdlDockItem *item);

This function emits the deselected signal. It is used by GdlSwitcher to let clients know that this item has been deselected.

Parameters

item

the dock item to emit a deselected signal on.

 

gdl_dock_item_notify_selected ()

void
gdl_dock_item_notify_selected (GdlDockItem *item);

This function emits the selected signal. It is to be used by GdlSwitcher to let clients know that this item has been switched to.

Parameters

item

the dock item to emit a selected signal on.

 

gdl_dock_item_get_grip ()

GtkWidget *
gdl_dock_item_get_grip (GdlDockItem *item);

This function returns the dock item's grip label widget.

Parameters

item

The dock item from which to to get the grip of.

 

Returns

Returns the current label widget.

[allow-none][transfer none]


gdl_dock_item_get_tablabel ()

GtkWidget *
gdl_dock_item_get_tablabel (GdlDockItem *item);

Gets the current tab label widget. Note that this label widget is only visible when the "switcher-style" property of the GdlDockMaster is set to GDL_SWITCHER_STYLE_TABS

Parameters

item

The dock item from which to get the tab label widget.

 

Returns

Returns the tab label widget.

[transfer none]


gdl_dock_item_or_child_has_focus ()

gboolean
gdl_dock_item_or_child_has_focus (GdlDockItem *item);

Checks whether a given GdlDockItem or its child widget has focus. This check is performed recursively on child widgets.

Parameters

item

The dock item to be checked

 

Returns

TRUE if the dock item or its child widget has focus; FALSE otherwise.

Since 3.3.2


gdl_dock_item_preferred_size ()

void
gdl_dock_item_preferred_size (GdlDockItem *item,
                              GtkRequisition *req);

Gets the preferred size of the dock item in pixels.

Parameters

item

The dock item to get the preferred size of.

 

req

A pointer to a GtkRequisition into which the preferred size will be written.

 

gdl_dock_item_set_default_position ()

void
gdl_dock_item_set_default_position (GdlDockItem *item,
                                    GdlDockObject *reference);

This method has only an effect when you add you dock_item with GDL_DOCK_ITEM_BEH_NEVER_FLOATING. In this case you have to assign it a default position.*

Deprecated 3.6: This function is doing nothing now.

Parameters

item

The dock item

 

reference

The GdlDockObject which is the default dock for item

 

gdl_dock_item_set_orientation ()

void
gdl_dock_item_set_orientation (GdlDockItem *item,
                               GtkOrientation orientation);

This function sets the layout of the dock item.

Parameters

item

The dock item which will get it's orientation set.

 

orientation

The orientation to set the item to. If the orientation is set to GTK_ORIENTATION_VERTICAL, the grip widget will be shown along the top of the edge of item (if it is not hidden). If the orientation is set to GTK_ORIENTATION_HORIZONTAL, the grip widget will be shown down the left edge of the item (even if the widget text direction is set to RTL).

 

gdl_dock_item_set_tablabel ()

void
gdl_dock_item_set_tablabel (GdlDockItem *item,
                            GtkWidget *tablabel);

Replaces the current tab label widget with another widget. Note that this label widget is only visible when the "switcher-style" property of the GdlDockMaster is set to GDL_SWITCHER_STYLE_TABS

Parameters

item

The dock item which will get it's tab label widget set.

 

tablabel

The widget that will become the tab label.

 

Types and Values

struct GdlDockItem

struct GdlDockItem;


enum GdlDockItemBehavior

Described the behaviour of a doc item. The item can have multiple flags set.

Members

GDL_DOCK_ITEM_BEH_NORMAL

Normal dock item

 

GDL_DOCK_ITEM_BEH_NEVER_FLOATING

item cannot be undocked

 

GDL_DOCK_ITEM_BEH_NEVER_VERTICAL

item cannot be docked vertically

 

GDL_DOCK_ITEM_BEH_NEVER_HORIZONTAL

item cannot be docked horizontally

 

GDL_DOCK_ITEM_BEH_LOCKED

item is locked, it cannot be moved around

 

GDL_DOCK_ITEM_BEH_CANT_DOCK_TOP

item cannot be docked at top

 

GDL_DOCK_ITEM_BEH_CANT_DOCK_BOTTOM

item cannot be docked at bottom

 

GDL_DOCK_ITEM_BEH_CANT_DOCK_LEFT

item cannot be docked left

 

GDL_DOCK_ITEM_BEH_CANT_DOCK_RIGHT

item cannot be docked right

 

GDL_DOCK_ITEM_BEH_CANT_DOCK_CENTER

item cannot be docked at center

 

GDL_DOCK_ITEM_BEH_CANT_CLOSE

item cannot be closed

 

GDL_DOCK_ITEM_BEH_CANT_ICONIFY

item cannot be iconified

 

GDL_DOCK_ITEM_BEH_NO_GRIP

item doesn't have a grip

 

struct GdlDockItemClass

struct GdlDockItemClass {
    GdlDockObjectClass  parent_class;

    GdlDockItemClassPrivate *priv;

    /* virtuals */
    void     (* set_orientation)  (GdlDockItem    *item,
                                   GtkOrientation  orientation);

    /* signals */
    void     (* dock_drag_begin)  (GdlDockItem    *item);
    void     (* dock_drag_motion) (GdlDockItem    *item,
                                   GdkDevice      *device,
                                   gint            x,
                                   gint            y);
    void     (* dock_drag_end)    (GdlDockItem    *item,
                                   gboolean        cancelled);
    void     (* move_focus_child) (GdlDockItem      *item,
                                   GtkDirectionType  direction);
};


enum GdlDockItemFlags

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

Use your own private data instead.

Status flag of a GdlDockItem. Don't use unless you derive a widget from GdlDockItem

Members

GDL_DOCK_IN_DRAG

item is in a drag operation

 

GDL_DOCK_IN_PREDRAG

item is in a predrag operation

 

GDL_DOCK_ICONIFIED

item is iconified

 

GDL_DOCK_USER_ACTION

indicates the user has started an action on the dock item

 

Property Details

The “behavior” property

  “behavior”                 GdlDockItemBehavior

General behavior for the dock item (i.e. whether it can float, if it's locked, etc.).

Flags: Read / Write


The “closed” property

  “closed”                   gboolean

If set, the dock item is closed.

Flags: Read / Write

Default value: FALSE

Since 3.6


The “iconified” property

  “iconified”                gboolean

If set, the dock item is hidden but it has a corresponding icon in the dock bar allowing to show it again.

Flags: Read / Write

Default value: FALSE

Since 3.6


The “locked” property

  “locked”                   gboolean

If set, the dock item cannot be dragged around and it doesn't show a grip.

Flags: Read / Write

Default value: FALSE


The “orientation” property

  “orientation”              GtkOrientation

The orientation of the docking item. If the orientation is set to GTK_ORIENTATION_VERTICAL, the grip widget will be shown along the top of the edge of item (if it is not hidden). If the orientation is set to GTK_ORIENTATION_HORIZONTAL, the grip widget will be shown down the left edge of the item (even if the widget text direction is set to RTL).

Flags: Read / Write / Construct

Default value: GTK_ORIENTATION_VERTICAL


The “preferred-height” property

  “preferred-height”         gint

Preferred height for the dock item.

Flags: Read / Write

Allowed values: >= -1

Default value: -1


The “preferred-width” property

  “preferred-width”          gint

Preferred width for the dock item.

Flags: Read / Write

Allowed values: >= -1

Default value: -1


The “resize” property

  “resize”                   gboolean

If set, the dock item can be resized when docked in a GtkPanel widget.

Flags: Read / Write

Default value: TRUE

Signal Details

The “deselected” signal

void
user_function (GdlDockItem *arg0,
               gpointer     user_data)

Signals that this dock has been deselected in a switcher.

Parameters

user_data

user data set when the signal handler was connected.

 

Flags: Run First


The “dock-drag-begin” signal

void
user_function (GdlDockItem *item,
               gpointer     user_data)

Signals that the dock item has begun to be dragged.

Parameters

item

The dock item which is being dragged.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First


The “dock-drag-end” signal

void
user_function (GdlDockItem *item,
               gboolean     cancel,
               gpointer     user_data)

Signals that the dock item dragging has ended.

Parameters

item

The dock item which is no longer being dragged.

 

cancel

This value is set to TRUE if the drag was cancelled by the user. cancel is set to FALSE if the drag was accepted.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First


The “dock-drag-motion” signal

void
user_function (GdlDockItem *item,
               GdkDevice   *device,
               gint         x,
               gint         y,
               gpointer     user_data)

Signals that a dock item dragging motion event has occured.

Parameters

item

The dock item which is being dragged.

 

device

The device used.

 

x

The x-position that the dock item has been dragged to.

 

y

The y-position that the dock item has been dragged to.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First


The “move-focus-child” signal

void
user_function (GdlDockItem     *gdldockitem,
               GtkDirectionType dir,
               gpointer         user_data)

The ::move-focus-child signal is emitted when a change of focus is requested for the child widget of a dock item. The dir parameter specifies the direction in which focus is to be shifted.

Parameters

gdldockitem

The dock item in which a change of focus is requested

 

dir

The direction in which to move focus

 

user_data

user data set when the signal handler was connected.

 

Flags: Action

Since 3.3.2


The “selected” signal

void
user_function (GdlDockItem *arg0,
               gpointer     user_data)

Signals that this dock has been selected from a switcher.

Parameters

user_data

user data set when the signal handler was connected.

 

Flags: Run First

See Also

GdlDockItem