]> Pileus Git - ~andy/gtk/blob - gtk/gtkwidget.h
Initial revision
[~andy/gtk] / gtk / gtkwidget.h
1 /* GTK - The GIMP Toolkit
2  * Copyright (C) 1995-1997 Peter Mattis, Spencer Kimball and Josh MacDonald
3  *
4  * This library is free software; you can redistribute it and/or
5  * modify it under the terms of the GNU Library General Public
6  * License as published by the Free Software Foundation; either
7  * version 2 of the License, or (at your option) any later version.
8  *
9  * This library is distributed in the hope that it will be useful,
10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
12  * Library General Public License for more details.
13  *
14  * You should have received a copy of the GNU Library General Public
15  * License along with this library; if not, write to the Free
16  * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
17  */
18 #ifndef __GTK_WIDGET_H__
19 #define __GTK_WIDGET_H__
20
21
22 #include <gdk/gdk.h>
23 #include <gtk/gtkaccelerator.h>
24 #include <gtk/gtkobject.h>
25 #include <gtk/gtkstyle.h>
26
27
28 #ifdef __cplusplus
29 extern "C" {
30 #endif /* __cplusplus */
31
32
33 /* The flags that are used in the flags member of the GtkObject
34  *  structure.
35  */
36 enum
37 {
38   GTK_VISIBLE          = 1 << 3,
39   GTK_MAPPED           = 1 << 4,
40   GTK_UNMAPPED         = 1 << 5,
41   GTK_REALIZED         = 1 << 6,
42   GTK_SENSITIVE        = 1 << 7,
43   GTK_PARENT_SENSITIVE = 1 << 8,
44   GTK_NO_WINDOW        = 1 << 9,
45   GTK_HAS_FOCUS        = 1 << 10,
46   GTK_CAN_FOCUS        = 1 << 11,
47   GTK_HAS_DEFAULT      = 1 << 12,
48   GTK_CAN_DEFAULT      = 1 << 13,
49   GTK_PROPAGATE_STATE  = 1 << 14,
50   GTK_ANCHORED         = 1 << 15,
51   GTK_BASIC            = 1 << 16,
52   GTK_USER_STYLE       = 1 << 17,
53   GTK_GRAB_ALL         = 1 << 18,
54   GTK_REDRAW_PENDING   = 1 << 19,
55   GTK_RESIZE_PENDING   = 1 << 20,
56   GTK_RESIZE_NEEDED    = 1 << 21,
57   GTK_HAS_SHAPE_MASK   = 1 << 22
58 };
59
60
61 /* Macro for casting a pointer to a GtkWidget pointer.
62  */
63 #define GTK_WIDGET(obj)                   GTK_CHECK_CAST (obj, gtk_widget_get_type (), GtkWidget)
64
65 /* Macro for casting the "class" field of an object to
66  *  a GtkWidgetClass pointer.
67  */
68 #define GTK_WIDGET_CLASS(klass)           GTK_CHECK_CLASS_CAST (klass, gtk_widget_get_type (), GtkWidgetClass)
69
70 /* Macros for extracting various fields from GtkWidget and
71  *  GtkWidgetClass structures.
72  */
73 #define GTK_WIDGET_TYPE(obj)              (GTK_OBJECT_TYPE (obj))
74 #define GTK_WIDGET_STATE(obj)             (GTK_WIDGET (obj)->state)
75 #define GTK_WIDGET_SAVED_STATE(obj)       (GTK_WIDGET (obj)->saved_state)
76 #define GTK_WIDGET_VISIBLE(obj)           (GTK_OBJECT_FLAGS (obj) & GTK_VISIBLE)
77 #define GTK_WIDGET_MAPPED(obj)            (GTK_OBJECT_FLAGS (obj) & GTK_MAPPED)
78 #define GTK_WIDGET_UNMAPPED(obj)          (GTK_OBJECT_FLAGS (obj) & GTK_UNMAPPED)
79 #define GTK_WIDGET_REALIZED(obj)          (GTK_OBJECT_FLAGS (obj) & GTK_REALIZED)
80 #define GTK_WIDGET_SENSITIVE(obj)         (GTK_OBJECT_FLAGS (obj) & GTK_SENSITIVE)
81 #define GTK_WIDGET_PARENT_SENSITIVE(obj)  (GTK_OBJECT_FLAGS (obj) & GTK_PARENT_SENSITIVE)
82 #define GTK_WIDGET_IS_SENSITIVE(obj)      ((GTK_WIDGET_SENSITIVE (obj) && \
83                                             GTK_WIDGET_PARENT_SENSITIVE (obj)) != 0)
84 #define GTK_WIDGET_NO_WINDOW(obj)         (GTK_OBJECT_FLAGS (obj) & GTK_NO_WINDOW)
85 #define GTK_WIDGET_HAS_FOCUS(obj)         (GTK_OBJECT_FLAGS (obj) & GTK_HAS_FOCUS)
86 #define GTK_WIDGET_CAN_FOCUS(obj)         (GTK_OBJECT_FLAGS (obj) & GTK_CAN_FOCUS)
87 #define GTK_WIDGET_HAS_DEFAULT(obj)       (GTK_OBJECT_FLAGS (obj) & GTK_HAS_DEFAULT)
88 #define GTK_WIDGET_CAN_DEFAULT(obj)       (GTK_OBJECT_FLAGS (obj) & GTK_CAN_DEFAULT)
89 #define GTK_WIDGET_PROPAGATE_STATE(obj)   (GTK_OBJECT_FLAGS (obj) & GTK_PROPAGATE_STATE)
90 #define GTK_WIDGET_DRAWABLE(obj)          (GTK_WIDGET_VISIBLE (obj) && GTK_WIDGET_MAPPED (obj))
91 #define GTK_WIDGET_ANCHORED(obj)          (GTK_OBJECT_FLAGS (obj) & GTK_ANCHORED)
92 #define GTK_WIDGET_BASIC(obj)             (GTK_OBJECT_FLAGS (obj) & GTK_BASIC)
93 #define GTK_WIDGET_USER_STYLE(obj)        (GTK_OBJECT_FLAGS (obj) & GTK_USER_STYLE)
94 #define GTK_WIDGET_GRAB_ALL(obj)          (GTK_OBJECT_FLAGS (obj) & GTK_GRAB_ALL)
95 #define GTK_WIDGET_REDRAW_PENDING(obj)    (GTK_OBJECT_FLAGS (obj) & GTK_REDRAW_PENDING)
96 #define GTK_WIDGET_RESIZE_PENDING(obj)    (GTK_OBJECT_FLAGS (obj) & GTK_RESIZE_PENDING)
97 #define GTK_WIDGET_RESIZE_NEEDED(obj)     (GTK_OBJECT_FLAGS (obj) & GTK_RESIZE_NEEDED)
98 #define GTK_WIDGET_HAS_SHAPE_MASK(obj)    (GTK_OBJECT_FLAGS (obj) & GTK_HAS_SHAPE_MASK)
99
100 #define GTK_TYPE_WIDGET                   (gtk_widget_get_type ())
101
102 /* Macro for testing whether "obj" is of type GtkWidget.
103  */
104 #define GTK_IS_WIDGET(obj)                GTK_CHECK_TYPE (obj, GTK_TYPE_WIDGET)
105
106 /* Macros for setting and clearing widget flags. Notice
107  *  that these are only wrappers for the macros which
108  *  set and clear the flags in the GtkObject structure.
109  */
110 #define GTK_WIDGET_SET_FLAGS(obj,flag)    (GTK_OBJECT_SET_FLAGS (obj, flag))
111 #define GTK_WIDGET_UNSET_FLAGS(obj,flag)  (GTK_OBJECT_UNSET_FLAGS (obj, flag))
112
113
114
115 typedef struct _GtkRequisition    GtkRequisition;
116 typedef struct _GtkAllocation     GtkAllocation;
117 typedef struct _GtkSelectionData GtkSelectionData;
118 typedef struct _GtkWidget         GtkWidget;
119 typedef struct _GtkWidgetClass    GtkWidgetClass;
120 typedef struct _GtkWidgetAuxInfo  GtkWidgetAuxInfo;
121 typedef struct _GtkWidgetShapeInfo GtkWidgetShapeInfo;
122
123 typedef void (*GtkCallback) (GtkWidget *widget,
124                              gpointer   data);
125
126 /* A requisition is a desired amount of space which a
127  *  widget may request.
128  */
129 struct _GtkRequisition
130 {
131   guint16 width;
132   guint16 height;
133 };
134
135 /* An allocation is a size and position. Where a widget
136  *  can ask for a desired size, it is actually given
137  *  this amount of space at the specified position.
138  */
139 struct _GtkAllocation
140 {
141   gint16 x;
142   gint16 y;
143   guint16 width;
144   guint16 height;
145 };
146
147 /* The contents of a selection are returned in a GtkSelectionData
148    structure. selection/target identify the request. 
149    type specifies the type of the return; if length < 0, and
150    the data should be ignored. This structure has object semantics -
151    no fields should be modified directly, they should not be created
152    directly, and pointers to them should not be stored beyond the duration of
153    a callback. (If the last is changed, we'll need to add reference
154    counting) */
155
156 struct _GtkSelectionData
157 {
158   GdkAtom selection;
159   GdkAtom target;
160   GdkAtom type;
161   gint    format;
162   guchar *data;
163   gint    length;
164 };
165
166 /* The widget is the base of the tree for displayable objects.
167  *  (A displayable object is one which takes up some amount
168  *  of screen real estate). It provides a common base and interface
169  *  which actual widgets must adhere to.
170  */
171 struct _GtkWidget
172 {
173   /* The object structure needs to be the first
174    *  element in the widget structure in order for
175    *  the object mechanism to work correctly. This
176    *  allows a GtkWidget pointer to be cast to a
177    *  GtkObject pointer.
178    */
179   GtkObject object;
180
181   /* The state of the widget. There are actually only
182    *  5 widget states (defined in "gtkenums.h").
183    */
184   guint8 state;
185
186   /* The saved state of the widget. When a widgets state
187    *  is changed via "gtk_widget_set_state" the old state
188    *  is kept around in this field. The state may be
189    *  restored using "gtk_widget_restore_state".
190    */
191   guint8 saved_state;
192
193   /* The widgets name. If the widget does not have a name
194    *  (the name is NULL), then its name (as returned by
195    *  "gtk_widget_get_name") is its classes name.
196    * The widget name is used to determine the style to
197    *  use for a widget.
198    */
199   gchar *name;
200
201   /* The style for the widget. The style contains the
202    *  colors the widget should be drawn in for each state
203    *  along with graphics contexts used to draw with and
204    *  the font to use for text.
205    */
206   GtkStyle *style;
207
208   /* The widgets desired size.
209    */
210   GtkRequisition requisition;
211
212   /* The widgets allocated size.
213    */
214   GtkAllocation allocation;
215
216   /* The widgets window or its parent window if it does
217    *  not have a window. (Which will be indicated by the
218    *  GTK_NO_WINDOW flag being set).
219    */
220   GdkWindow *window;
221
222   /* The widgets parent.
223    */
224   GtkWidget *parent;
225 };
226
227 struct _GtkWidgetClass
228 {
229   /* The object class structure needs to be the first
230    *  element in the widget class structure in order for
231    *  the class mechanism to work correctly. This allows a
232    *  GtkWidgetClass pointer to be cast to a GtkObjectClass
233    *  pointer.
234    */
235   GtkObjectClass parent_class;
236
237   /* The signal to emit when an object of this class is activated.
238    *  This is used when activating the current focus widget and
239    *  the default widget.
240    */
241   gint activate_signal;
242
243   /* basics */
244   void (* show)                (GtkWidget      *widget);
245   void (* hide)                (GtkWidget      *widget);
246   void (* map)                 (GtkWidget      *widget);
247   void (* unmap)               (GtkWidget      *widget);
248   void (* realize)             (GtkWidget      *widget);
249   void (* unrealize)           (GtkWidget      *widget);
250   void (* draw)                (GtkWidget      *widget,
251                                 GdkRectangle   *area);
252   void (* draw_focus)          (GtkWidget      *widget);
253   void (* draw_default)        (GtkWidget      *widget);
254   void (* size_request)        (GtkWidget      *widget,
255                                 GtkRequisition *requisition);
256   void (* size_allocate)       (GtkWidget      *widget,
257                                 GtkAllocation  *allocation);
258   void (* state_changed)       (GtkWidget      *widget);
259
260   /* accelerators */
261   gint (* install_accelerator) (GtkWidget      *widget,
262                                 const gchar    *signal_name,
263                                 gchar           key,
264                                 guint8          modifiers);
265   void (* remove_accelerator)  (GtkWidget      *widget,
266                                 const gchar    *signal_name);
267
268   /* events */
269   gint (* event)                   (GtkWidget         *widget,
270                                     GdkEvent          *event);
271   gint (* button_press_event)      (GtkWidget         *widget,
272                                     GdkEventButton    *event);
273   gint (* button_release_event)    (GtkWidget         *widget,
274                                     GdkEventButton    *event);
275   gint (* motion_notify_event)     (GtkWidget         *widget,
276                                     GdkEventMotion    *event);
277   gint (* delete_event)            (GtkWidget         *widget,
278                                     GdkEventAny       *event);
279   gint (* destroy_event)           (GtkWidget         *widget,
280                                     GdkEventAny       *event);
281   gint (* expose_event)            (GtkWidget         *widget,
282                                     GdkEventExpose    *event);
283   gint (* key_press_event)         (GtkWidget         *widget,
284                                     GdkEventKey       *event);
285   gint (* key_release_event)       (GtkWidget         *widget,
286                                     GdkEventKey       *event);
287   gint (* enter_notify_event)      (GtkWidget         *widget,
288                                     GdkEventCrossing  *event);
289   gint (* leave_notify_event)      (GtkWidget         *widget,
290                                     GdkEventCrossing  *event);
291   gint (* configure_event)         (GtkWidget         *widget,
292                                     GdkEventConfigure *event);
293   gint (* focus_in_event)          (GtkWidget         *widget,
294                                     GdkEventFocus     *event);
295   gint (* focus_out_event)         (GtkWidget         *widget,
296                                     GdkEventFocus     *event);
297   gint (* map_event)               (GtkWidget         *widget,
298                                     GdkEventAny       *event);
299   gint (* unmap_event)             (GtkWidget         *widget,
300                                     GdkEventAny       *event);
301   gint (* property_notify_event)   (GtkWidget         *widget,
302                                     GdkEventProperty  *event);
303   gint (* selection_clear_event)   (GtkWidget         *widget,
304                                     GdkEventSelection *event);
305   gint (* selection_request_event) (GtkWidget         *widget,
306                                     GdkEventSelection *event);
307   gint (* selection_notify_event)  (GtkWidget         *widget,
308                                     GdkEventSelection *event);
309   gint (* proximity_in_event)      (GtkWidget         *widget,
310                                     GdkEventProximity *event);
311   gint (* proximity_out_event)     (GtkWidget         *widget,
312                                     GdkEventProximity *event);
313   gint (* drag_begin_event)        (GtkWidget         *widget,
314                                     GdkEventDragBegin *event);
315   gint (* drag_request_event)      (GtkWidget         *widget,
316                                     GdkEventDragRequest *event);
317   gint (* drop_enter_event)        (GtkWidget         *widget,
318                                     GdkEventDropEnter *event);
319   gint (* drop_leave_event)        (GtkWidget         *widget,
320                                     GdkEventDropLeave *event);
321   gint (* drop_data_available_event)   (GtkWidget         *widget,
322                                     GdkEventDropDataAvailable *event);
323   gint (* other_event)             (GtkWidget         *widget,
324                                     GdkEventOther     *event);
325
326   /* selection */
327   void (* selection_received)  (GtkWidget      *widget,
328                                 GtkSelectionData *selection_data);
329
330  gint (* client_event)             (GtkWidget         *widget,
331                                     GdkEventClient    *event);
332 };
333
334 struct _GtkWidgetAuxInfo
335 {
336   gint16  x;
337   gint16  y;
338   guint16 width;
339   guint16 height;
340 };
341
342 struct _GtkWidgetShapeInfo
343 {
344   gint16     offset_x;
345   gint16     offset_y;
346   GdkBitmap *shape_mask;
347 };
348
349
350 guint      gtk_widget_get_type            (void);
351 GtkWidget* gtk_widget_new                 (guint                type,
352                                            ...);
353 GtkWidget* gtk_widget_newv                (guint                type,
354                                            gint                 nargs,
355                                            GtkArg              *args);
356 void       gtk_widget_set                 (GtkWidget           *widget,
357                                            ...);
358 void       gtk_widget_setv                (GtkWidget           *widget,
359                                            gint                 nargs,
360                                            GtkArg              *args);
361 void       gtk_widget_destroy             (GtkWidget           *widget);
362 void       gtk_widget_unparent            (GtkWidget           *widget);
363 void       gtk_widget_show                (GtkWidget           *widget);
364 void       gtk_widget_hide                (GtkWidget           *widget);
365 void       gtk_widget_map                 (GtkWidget           *widget);
366 void       gtk_widget_unmap               (GtkWidget           *widget);
367 void       gtk_widget_realize             (GtkWidget           *widget);
368 void       gtk_widget_unrealize           (GtkWidget           *widget);
369 void       gtk_widget_queue_draw          (GtkWidget           *widget);
370 void       gtk_widget_queue_resize        (GtkWidget           *widget);
371 void       gtk_widget_draw                (GtkWidget           *widget,
372                                            GdkRectangle        *area);
373 void       gtk_widget_draw_focus          (GtkWidget           *widget);
374 void       gtk_widget_draw_default        (GtkWidget           *widget);
375 void       gtk_widget_draw_children       (GtkWidget           *widget);
376 void       gtk_widget_size_request        (GtkWidget           *widget,
377                                            GtkRequisition      *requisition);
378 void       gtk_widget_size_allocate       (GtkWidget           *widget,
379                                            GtkAllocation       *allocation);
380 void       gtk_widget_install_accelerator (GtkWidget           *widget,
381                                            GtkAcceleratorTable *table,
382                                            const gchar         *signal_name,
383                                            gchar                key,
384                                            guint8               modifiers);
385 void       gtk_widget_remove_accelerator  (GtkWidget           *widget,
386                                            GtkAcceleratorTable *table,
387                                            const gchar         *signal_name);
388 gint       gtk_widget_event               (GtkWidget           *widget,
389                                            GdkEvent            *event);
390
391 void       gtk_widget_activate            (GtkWidget           *widget);
392 void       gtk_widget_reparent            (GtkWidget           *widget,
393                                            GtkWidget           *new_parent);
394 void       gtk_widget_popup               (GtkWidget           *widget,
395                                            gint                 x,
396                                            gint                 y);
397 gint       gtk_widget_intersect           (GtkWidget           *widget,
398                                            GdkRectangle        *area,
399                                            GdkRectangle        *intersection);
400 gint       gtk_widget_basic               (GtkWidget           *widget);
401
402 void       gtk_widget_grab_focus          (GtkWidget           *widget);
403 void       gtk_widget_grab_default        (GtkWidget           *widget);
404
405 void       gtk_widget_restore_state       (GtkWidget           *widget);
406 void       gtk_widget_set_name            (GtkWidget           *widget,
407                                            const gchar         *name);
408 gchar*     gtk_widget_get_name            (GtkWidget           *widget);
409 void       gtk_widget_set_state           (GtkWidget           *widget,
410                                            GtkStateType         state);
411 void       gtk_widget_set_sensitive       (GtkWidget           *widget,
412                                            gint                 sensitive);
413 void       gtk_widget_set_parent          (GtkWidget           *widget,
414                                            GtkWidget           *parent);
415 void       gtk_widget_set_style           (GtkWidget           *widget,
416                                            GtkStyle            *style);
417 void       gtk_widget_set_uposition       (GtkWidget           *widget,
418                                            gint                 x,
419                                            gint                 y);
420 void       gtk_widget_set_usize           (GtkWidget           *widget,
421                                            gint                 width,
422                                            gint                 height);
423 void       gtk_widget_set_events          (GtkWidget           *widget,
424                                            gint                 events);
425 void       gtk_widget_set_extension_events (GtkWidget           *widget,
426                                             GdkExtensionMode    mode);
427
428 GtkWidget*   gtk_widget_get_toplevel  (GtkWidget *widget);
429 GtkWidget*   gtk_widget_get_ancestor  (GtkWidget *widget,
430                                        gint       type);
431 GdkColormap* gtk_widget_get_colormap  (GtkWidget *widget);
432 GdkVisual*   gtk_widget_get_visual    (GtkWidget *widget);
433 GtkStyle*    gtk_widget_get_style     (GtkWidget *widget);
434 gint         gtk_widget_get_events    (GtkWidget *widget);
435 GdkExtensionMode gtk_widget_get_extension_events    (GtkWidget *widget);
436 void         gtk_widget_get_pointer   (GtkWidget *widget,
437                                        gint      *x,
438                                        gint      *y);
439
440 gint         gtk_widget_is_ancestor (GtkWidget *widget,
441                                      GtkWidget *ancestor);
442 gint         gtk_widget_is_child    (GtkWidget *widget,
443                                      GtkWidget *child);
444
445 void         gtk_widget_push_colormap    (GdkColormap   *cmap);
446 void         gtk_widget_push_visual      (GdkVisual     *visual);
447 void         gtk_widget_push_style       (GtkStyle      *style);
448
449 void         gtk_widget_pop_colormap     (void);
450 void         gtk_widget_pop_visual       (void);
451 void         gtk_widget_pop_style        (void);
452
453 void         gtk_widget_set_default_colormap (GdkColormap *colormap);
454 void         gtk_widget_set_default_visual   (GdkVisual   *visual);
455 void         gtk_widget_set_default_style    (GtkStyle    *style);
456 /* Tells other Gtk applications to use the same default style */
457 void         gtk_widget_propagate_default_style(void);
458 GdkColormap* gtk_widget_get_default_colormap (void);
459 GdkVisual*   gtk_widget_get_default_visual   (void);
460 GtkStyle*    gtk_widget_get_default_style    (void);
461
462 /* 
463  * see gdk_window_shape_combine_mask
464  */
465 void         gtk_widget_shape_combine_mask (GtkWidget *widget,
466                                             GdkBitmap *shape_mask,
467                                             gint       offset_x,
468                                             gint       offset_y);
469
470 /* 
471  * When you get a drag_enter event, you can use this to tell Gtk of other
472  *  items that are to be dragged as well...
473  */
474 void         gtk_widget_dnd_drag_add (GtkWidget *widget);
475
476 /* 
477  * These two functions enable drag and/or drop on a widget,
478  * and also let Gtk know what data types will be accepted (use MIME type
479  *  naming, plus tacking "URL:" on the front for link dragging)
480  */
481 void         gtk_widget_dnd_drag_set (GtkWidget     *widget,
482                                       guint8         drag_enable,
483                                       gchar        **type_accept_list,
484                                       guint          numtypes);
485 void         gtk_widget_dnd_drop_set (GtkWidget     *widget,
486                                       guint8         drop_enable,
487                                       gchar        **type_accept_list,
488                                       guint          numtypes,
489                                       guint8         is_destructive_operation);
490
491 /* 
492  * used to reply to a DRAG_REQUEST event - if you don't want to 
493  * give the data then pass in NULL for it 
494  */
495 void         gtk_widget_dnd_data_set (GtkWidget     *widget,
496                                       GdkEvent      *event,
497                                       gpointer       data,
498                                       gulong         data_numbytes);
499
500 #ifdef __cplusplus
501 }
502 #endif /* __cplusplus */
503
504
505 #endif /* __GTK_WIDGET_H__ */