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