gdl-dock-object.h 14 KB
Newer Older
1
/* -*- Mode: C; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*-
2 3 4 5 6
 *
 * gdl-dock-object.h - Abstract base class for all dock related objects
 *
 * This file is part of the GNOME Devtools Libraries.
 *
7
 * Copyright (C) 2002 Gustavo Giráldez <gustavo.giraldez@gmx.net>
8
 *
9 10 11 12
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
13
 *
14
 * This library is distributed in the hope that it will be useful,
15
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 17
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
18
 *
19 20 21
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
22 23 24 25 26
 */

#ifndef __GDL_DOCK_OBJECT_H__
#define __GDL_DOCK_OBJECT_H__

27
#include <gtk/gtk.h>
28 29 30 31 32

G_BEGIN_DECLS

/* standard macros */
#define GDL_TYPE_DOCK_OBJECT             (gdl_dock_object_get_type ())
33 34 35 36 37
#define GDL_DOCK_OBJECT(obj)             (G_TYPE_CHECK_INSTANCE_CAST ((obj), GDL_TYPE_DOCK_OBJECT, GdlDockObject))
#define GDL_DOCK_OBJECT_CLASS(klass)     (G_TYPE_CHECK_CLASS_CAST ((klass), GDL_TYPE_DOCK_OBJECT, GdlDockObjectClass))
#define GDL_IS_DOCK_OBJECT(obj)          (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GDL_TYPE_DOCK_OBJECT))
#define GDL_IS_DOCK_OBJECT_CLASS(klass)  (G_TYPE_CHECK_CLASS_TYPE ((klass), GDL_TYPE_DOCK_OBJECT))
#define GDL_DOCK_OBJECT_GET_CLASS(obj)   (G_TYPE_INSTANCE_GET_CLASS ((obj), GTK_TYPE_DOCK_OBJECT, GdlDockObjectClass))
38 39

/* data types & structures */
40 41 42 43 44 45 46 47 48 49

/**
 * GdlDockParamFlags:
 * @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
 *
 * Used to flag additional characteristics to GObject properties used in dock
 * object.
 *
 **/
50 51 52 53 54 55 56 57 58 59
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;

#define GDL_DOCK_NAME_PROPERTY    "name"
#define GDL_DOCK_MASTER_PROPERTY  "master"

60
#ifndef GDL_DISABLE_DEPRECATED
61 62 63 64 65 66 67 68 69
/**
 * GdlDockObjectFlags:
 * @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
 *
 * Described the state of a #GdlDockObject.
 *
70 71 72
 * Since 3.6: These flags are available using access function, like
 * gdl_dock_object_is_automatic() or gdl_dock_object_is_closed().
 */
73 74 75 76 77 78
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;
79
#endif
80

81
#ifndef GDL_DISABLE_DEPRECATED
82 83 84 85 86
/**
 * GDL_DOCK_OBJECT_FLAGS_SHIFT:
 *
 * Minimum shift count to be used for user defined flags, to be stored in
 * #GdlDockObject.flags.
87
 *
88
 * Deprecated: 3.6: Use a private flag instead
89
 */
90
#define GDL_DOCK_OBJECT_FLAGS_SHIFT 8
91
#endif
92

93 94 95 96 97 98 99 100 101 102 103 104 105
/**
 * GdlDockPlacement:
 * @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
 *
 * Described the docking position.
 *
 **/
106 107 108 109 110 111 112 113 114 115
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;

116 117 118 119 120
typedef struct _GdlDockObject             GdlDockObject;
typedef struct _GdlDockObjectPrivate      GdlDockObjectPrivate;
typedef struct _GdlDockObjectClass        GdlDockObjectClass;
typedef struct _GdlDockObjectClassPrivate GdlDockObjectClassPrivate;
typedef struct _GdlDockRequest            GdlDockRequest;
121

122 123 124 125 126 127 128 129 130 131
/**
 * GdlDockRequest:
 * @applicant: A #GdlDockObject to dock
 * @target: The #GdlDockObject target
 * @position: how to dock @applicant in @target
 * @rect: Precise position
 * @extra: Additional information
 *
 * Full docking information.
 **/
132
struct _GdlDockRequest {
133 134 135 136 137
    GdlDockObject               *applicant;
    GdlDockObject               *target;
    GdlDockPlacement            position;
    cairo_rectangle_int_t       rect;
    GValue                      extra;
138 139 140 141
};

struct _GdlDockObject {
    GtkContainer        container;
142 143
#ifndef GDL_DISABLE_DEPRECATED
    /* Just for compiling, these data are not initialized anymore */
144 145
    GdlDockObjectFlags  deprecated_flags;
    GObject            *deprecated_master;
146 147 148
#endif
    /*< private >*/
    GdlDockObjectPrivate  *priv;
149 150 151 152 153
};

struct _GdlDockObjectClass {
    GtkContainerClass parent_class;

154
    GdlDockObjectClassPrivate *priv;
155

156 157 158 159 160 161 162 163 164 165 166 167 168
    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);
169

170 171 172 173 174 175 176 177 178 179 180 181 182 183
    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);
};

/* additional macros */
184

185
#ifndef GDL_DISABLE_DEPRECATED
186 187 188 189 190
/**
 * GDL_DOCK_OBJECT_FLAGS:
 * @obj: A #GdlDockObject
 *
 * Get all flags of #GdlDockObject.
191 192
 *
 * Deprecated: 3.6: The flags are not accessible anymore.
193
 */
194
#define GDL_DOCK_OBJECT_FLAGS(obj)  (GDL_DOCK_OBJECT (obj)->deprecated_flags)
195
#endif
196

197
#ifndef GDL_DISABLE_DEPRECATED
198 199 200 201 202 203
/**
 * GDL_DOCK_OBJECT_AUTOMATIC:
 * @obj: A #GdlDockObject
 *
 * Evaluates to %TRUE if the object's lifecycle is entirely managed by the dock
 * master.
204 205
 *
 * Deprecated: 3.6: Use gdl_dock_object_is_automatic()
206
 */
207
#define GDL_DOCK_OBJECT_AUTOMATIC(obj) gdl_dock_object_is_automatic (GDL_DOCK_OBJECT (obj))
208
#endif
209

210
#ifndef GDL_DISABLE_DEPRECATED
211 212 213 214 215
/**
 * GDL_DOCK_OBJECT_ATTACHED:
 * @obj: A #GdlDockObject
 *
 * Evaluates to %TRUE if the object has a parent.
216
 *
217
 * Deprecated: 3.6: Use
218
 */
219
#define GDL_DOCK_OBJECT_ATTACHED(obj) (!gdl_dock_object_is_closed(GDL_DOCK_OBJECT (obj)))
220
#endif
221

222
#ifndef GDL_DISABLE_DEPRECATED
223 224 225 226 227
/**
 * GDL_DOCK_OBJECT_IN_REFLOW:
 * @obj: A #GdlDockObject
 *
 * Evaluates to %TRUE if the object is currently rearranged.
228 229
 *
 * Deprecated: 3.6: Use gdl_dock_object_is_frozen()
230
 */
231 232
#define GDL_DOCK_OBJECT_IN_REFLOW(obj) \
    ((GDL_DOCK_OBJECT_FLAGS (obj) & GDL_DOCK_IN_REFLOW) != 0)
233
#endif
234

235
#ifndef GDL_DISABLE_DEPRECATED
236 237 238 239 240
/**
 * GDL_DOCK_OBJECT_IN_DETACH:
 * @obj: A #GdlDockObject
 *
 * Evaluates to %TRUE if the object will be detached.
241 242
 *
 * Deprecated: 3.6: This flag is no longer available
243
 */
244 245
#define GDL_DOCK_OBJECT_IN_DETACH(obj) \
    ((GDL_DOCK_OBJECT_FLAGS (obj) & GDL_DOCK_IN_DETACH) != 0)
246
#endif
247

248
#ifndef GDL_DISABLE_DEPRECATED
249 250 251
/**
 * GDL_DOCK_OBJECT_SET_FLAGS:
 * @obj: A #GdlDockObject
252
 * @flag: One or more #GdlDockObjectFlags
253 254
 *
 * Set one or more flags of a dock object.
255
 *
256
 * Deprecated: 3.6: This flags are no longer accessible.
257
 */
258 259
#define GDL_DOCK_OBJECT_SET_FLAGS(obj,flag) \
    G_STMT_START { (GDL_DOCK_OBJECT_FLAGS (obj) |= (flag)); } G_STMT_END
260
#endif
261 262


263
#ifndef GDL_DISABLE_DEPRECATED
264 265 266
/**
 * GDL_DOCK_OBJECT_UNSET_FLAGS:
 * @obj: A #GdlDockObject
267
 * @flag: One or more #GdlDockObjectFlags
268 269
 *
 * Clear one or more flags of a dock object.
270
 *
271
 * Deprecated: 3.6: This flags are no longer accessible.
272
 */
273 274
#define GDL_DOCK_OBJECT_UNSET_FLAGS(obj,flag) \
    G_STMT_START { (GDL_DOCK_OBJECT_FLAGS (obj) &= ~(flag)); } G_STMT_END
275
#endif
276

277
#ifndef GDL_DISABLE_DEPRECATED
278 279 280 281 282
/**
 * GDL_DOCK_OBJECT_FROZEN:
 * @obj: A #GdlDockObject
 *
 * Evaluates to %TRUE if the object is frozen.
283 284
 *
 * Deprecated: 3.6: Use gdl_dock_object_is_frozen()
285
 */
286
#define GDL_DOCK_OBJECT_FROZEN(obj) gdl_dock_object_is_frozen(GDL_DOCK_OBJECT (obj))
287
#endif
288 289 290


/* public interface */
291

292 293 294 295 296 297 298 299 300 301 302
GType          gdl_dock_object_get_type          (void);

gboolean       gdl_dock_object_is_compound       (GdlDockObject    *object);

void           gdl_dock_object_detach            (GdlDockObject    *object,
                                                  gboolean          recursive);

GdlDockObject *gdl_dock_object_get_parent_object (GdlDockObject    *object);

void           gdl_dock_object_freeze            (GdlDockObject    *object);
void           gdl_dock_object_thaw              (GdlDockObject    *object);
303
gboolean       gdl_dock_object_is_frozen          (GdlDockObject    *object);
304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319

void           gdl_dock_object_reduce            (GdlDockObject    *object);

gboolean       gdl_dock_object_dock_request      (GdlDockObject    *object,
                                                  gint              x,
                                                  gint              y,
                                                  GdlDockRequest   *request);
void           gdl_dock_object_dock              (GdlDockObject    *object,
                                                  GdlDockObject    *requestor,
                                                  GdlDockPlacement  position,
                                                  GValue           *other_data);

void           gdl_dock_object_bind              (GdlDockObject    *object,
                                                  GObject          *master);
void           gdl_dock_object_unbind            (GdlDockObject    *object);
gboolean       gdl_dock_object_is_bound          (GdlDockObject    *object);
320 321 322
GObject       *gdl_dock_object_get_master        (GdlDockObject    *object);
GdlDockObject *gdl_dock_object_get_controller    (GdlDockObject    *object);
void           gdl_dock_object_layout_changed_notify (GdlDockObject *object);
323 324 325 326 327 328 329 330 331 332 333 334 335

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

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

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

336 337
gboolean       gdl_dock_object_is_closed         (GdlDockObject    *object);

338 339 340
gboolean       gdl_dock_object_is_automatic      (GdlDockObject    *object);
void           gdl_dock_object_set_manual        (GdlDockObject    *object);

341 342 343 344 345 346 347 348 349 350 351 352 353 354
const gchar   *gdl_dock_object_get_name          (GdlDockObject    *object);
void           gdl_dock_object_set_name          (GdlDockObject    *object,
                                                  const gchar      *name);
const gchar   *gdl_dock_object_get_long_name     (GdlDockObject    *object);
void           gdl_dock_object_set_long_name     (GdlDockObject    *object,
                                                  const gchar      *name);
const gchar   *gdl_dock_object_get_stock_id      (GdlDockObject    *object);
void           gdl_dock_object_set_stock_id      (GdlDockObject    *object,
                                                  const gchar      *stock_id);
GdkPixbuf     *gdl_dock_object_get_pixbuf        (GdlDockObject    *object);
void           gdl_dock_object_set_pixbuf        (GdlDockObject    *object,
                                                  GdkPixbuf        *icon);


355 356 357 358 359 360 361 362 363 364
/* other types */

/* this type derives from G_TYPE_STRING and is meant to be the basic
   type for serializing object parameters which are exported
   (i.e. those that are needed for layout rebuilding) */
#define GDL_TYPE_DOCK_PARAM   (gdl_dock_param_get_type ())

GType gdl_dock_param_get_type (void);

/* functions for setting/retrieving nick names for serializing GdlDockObject types */
365
const gchar          *gdl_dock_object_nick_from_type    (GType        type);
366 367 368 369 370 371
GType                 gdl_dock_object_type_from_nick    (const gchar *nick);
GType                 gdl_dock_object_set_type_for_nick (const gchar *nick,
                                                         GType        type);


/* helper macros */
372 373
/**
 * GDL_TRACE_OBJECT:
374
 * @object: A #GdlDockObject
375 376 377 378 379
 * @format: Additional printf format string
 * @...: Additional arguments
 *
 * Output a debugging message for the corresponding dock object.
 */
380 381 382 383
#define GDL_TRACE_OBJECT(object, format, args...) \
    G_STMT_START {                            \
    g_log (G_LOG_DOMAIN,                      \
	   G_LOG_LEVEL_DEBUG,                 \
384
           "%s:%d (%s) %s [%p %d%s:%d]: " format, \
385 386 387 388 389
	   __FILE__,                          \
	   __LINE__,                          \
	   __PRETTY_FUNCTION__,               \
           G_OBJECT_TYPE_NAME (object), object, \
           G_OBJECT (object)->ref_count, \
390
           (GTK_IS_OBJECT (object) && g_object_is_floating (object)) ? "(float)" : "", \
391
           GDL_IS_DOCK_OBJECT (object) ? gdl_dock_object_is_frozen (GDL_DOCK_OBJECT (object)) : -1, \
392 393
	   ##args); } G_STMT_END

394 395 396 397 398 399


G_END_DECLS

#endif  /* __GDL_DOCK_OBJECT_H__ */