1 \input texinfo @c -*-texinfo-*-
2 @c Copyright (C) 1996 by Peter Mattis. All rights reserved.
12 @set update-date 16 January 1998
13 @set update-month January 1998
16 This file documents GTK, the General Toolkit
18 Copyright (C) 1996 Peter Mattis
19 Copyright (C) 1997 Peter Mattis
21 Permission is granted to make and distribute verbatim copies of this
22 manual provided the copyright notice and this permission notice are
23 preserved on all copies
26 Permission is granted to process this file throught TeX and print the
27 results, provided the printed document carries copying permission notice
28 identical to this one except for the removal of this paragraph (this
29 paragraph not being relevant to the printed manual).
32 Permission is granted to copy and distribute modified versions of this
33 manual under the conditions for verbatim copying, provided that the
34 entire resulting derived work is distributed under the terms of a
35 permission notice identical to this one.
37 Permission is granted to copy and distribute translations of this manual
38 into another language, under the above conditions for modified versions,
39 except that this permission notice may be stated in a translation
40 approved by Peter Mattis.
44 @title The General Toolkit
45 @subtitle Version @value{edition}
46 @subtitle @value{update-month}
47 @author by Peter Mattis
50 @vskip 0pt plus 1filll
51 Copyright @copyright{} 1996 Peter Mattis
53 Copyright @copyright{} 1997 Peter Mattis
55 Permission is granted to make and distribute verbatim copies of this
56 manual provided the copyright notice and this permission notice are
57 preserved on all copies.
59 Permission is granted to copy and distribute modified versions of this
60 manual under the conditions for verbatim copying, provided that the
61 entire resulting derived work is distributed under the terms of a
62 permission notice identical to this one.
64 Permission is granted to copy and distribute translations of this manual
65 into another language, under the above conditions for modified versions,
66 except that this permission notice may be stated in a translation
67 approved by Peter Mattis.
70 @dircategory User Interface Toolkit
72 * GTK: (gtk). The General Toolkit
75 @node Top, Copying, (dir), (dir)
76 @top The General Toolkit
78 This is edition @value{edition} of the GTK documentation,
79 @w{@value{update-date}}.
81 @c FIXME: Do a introduction to the GTK?
84 * Copying:: Your rights.
85 * Overview:: What is GTK?
86 * Objects:: Object overview.
87 * Signals:: Signals overview.
88 * Widgets:: Widget overview.
89 * Other Objects:: Utility objects.
90 * Miscellaneous:: Initialization, exit and other features.
91 * Examples:: Using GTK.
92 * Object Implementation:: Object internals.
93 * Signal Implementation:: Signal internals.
94 * Widget Implementation:: Widget internals.
95 * Function Index:: Index of functions.
96 * Concept Index:: Index of concepts.
99 @node Copying, Overview, Top, Top
100 @comment node-name, next, previous, up
104 GTK is @dfn{free}; this means that everyone is free to use it and free
105 to redestribute it on a free basis. GTK is not in the public domain; it
106 is copyrighted and there are restrictions on its distribution, but
107 these restrictions are designed to permit everything that a good
108 cooperating citizen would want to do. What is not allowed is to try to
109 prevent others from further sharing any version of GTK that they might
112 Specifically, we want to make sure that you have the right to give away
113 copies of GTK, that you receive source code or else can get it if you
114 want it, that you can change GTK or use pieces of it in new free
115 programs, and that you know you can do these things.
117 To make sure that everyone has such rights, we have to forbid you to
118 deprive anyone else of these rights. For example, if you distribute
119 copies of GTK, you must give the recipients all the rights that you
120 have. You must make sure that they, too, receive or can get the source
121 code. And you must tell them their rights.
123 Also, for my own protection, we must make certain that everyone finds
124 out that there is no warranty for GTK. If GTK is modified by someone
125 else and passed on, we want their recipients to know that what they have
126 is not what we distributed, so that any problems introduced by others
127 will no reflect on our reputation.
129 The precise conditions of the licenses for GTK are found in the General
130 Public Licenses that accompanies it.
133 @node Overview, Objects, Copying, Top
134 @comment node-name, next, previous, up
135 @chapter What is GTK?
138 GTK is a library for creating graphical user interfaces similar to the
139 Motif ``look and feel''. It is designed to be small and efficient, but
140 still flexible enough to allow the programmer freedom in the interfaces
141 created. GTK allows the programmer to use a variety of standard user
142 interface widgets (@pxref{Widgets}) such as push, radio and check
143 buttons, menus, lists and frames. It also provides several ``container''
144 widgets which can be used to control the layout of the user interface
147 GTK provides some unique features. (At least, I know of no other widget
148 library which provides them). For example, a button does not contain a
149 label, it contains a child widget, which in most instances will be a
150 label. However, the child widget can also be a pixmap, image or any
151 combination possible the programmer desires. This flexibility is adhered
152 to throughout the library.
155 @node Objects, Signals, Overview, Top
156 @comment node-name, next, previous, up
157 @chapter Object Overview
160 GTK implements a semi-simple class mechanism and an associated class
161 hierarchy for widgets and several other useful objects. The GtkObject
162 type is the root of the class hierarchy. It provides a few items needed
163 by all classes, the foundation for the signal (@pxref{Signals})
164 mechanism and the ``destroy'' method.
166 The class hierarchy is defined by a type hierarchy. This hierarchy
167 allows queries to be made in regards to a type. The basic query that can
168 be performed is asking whether a given type has an ``is a'' relation
169 with another type. For instance, it is common to ask whether a general
170 widget pointer is a type of specific widget so that runtime sanity
173 @section Type utility functions
175 The @code{GtkTypeInfo} structure is used to communicate information to
176 @code{gtk_type_unique} as opposed to passing in large numbers of
180 typedef struct _GtkTypeInfo GtkTypeInfo;
187 GtkClassInitFunc class_init_func;
188 GtkObjectInitFunc object_init_func;
195 The @code{type_name} field refers to the name of the type. It is
196 convention for the type name to be the same as the C structure type. For
197 example, the type name of the @code{GtkObject} structure is
201 The @code{object_size} field refers to the size in bytes of the C
202 structure. The easiest (and portable) means of computing this size is by
203 using the C @code{sizeof} operator. For instance, the sizeof of the
204 @code{GtkObject} structure is computed by doing @code{sizeof
208 The @code{class_size} field refers to the size in bytes of the C
209 structure for the class. Again, the @code{sizeof} operator should be
210 used to compute this value.
213 The @code{class_init_func} field is a callback which is used by the type
214 mechanism to initialize class specific fields. The single argument this
215 function takes is a pointer to a class structure.
218 The @code{object_init_func} field is a callback which is used by the
219 type mechanism to initialize object specific fields. The single argument
220 this functions takes is a pointer to an object structure.
224 @deftypefun guint gtk_type_unique (guint @var{parent_type}, GtkTypeInfo *@var{type_info})
225 The @var{parent_type} is simply the value of the new types parent
226 type. If @var{parent_type} is 0, then the new type is the root of the
227 type hierarchy. @var{type_info} is a pointer to a structure which
228 contains necessary information for construction of the new
229 type. Specifically, the @code{type_name}, @code{object_size} and
230 @code{class_size} fields are required. The @code{class_init_func},
231 @code{object_init_func} and @code{value_init_func} fields may be NULL.
234 @deftypefun gchar* gtk_type_name (guint @var{type})
235 The returned string is the name of @var{type} as specified to
236 @code{gtk_type_unique}.
239 @deftypefun guint gtk_type_from_name (guchar *@var{name})
240 Return the type associated with @var{name}. If there is no type
241 associated with @var{name}, then 0 will be returned.
244 @deftypefun guint gtk_type_parent (guint @var{type})
245 Returns the parent type of @var{type} or 0 if @var{type} is the root of
249 @deftypefun gpointer gtk_type_class (guint @var{type})
250 Returns the initialized class structure for @var{type}. The class
251 structure is actually created and initialized the first time it is
252 needed. If creation and initialization occurs, the @code{class_size}
253 field of the @code{GtkTypeInfo} structure used to initialize this type
254 is used to determine how large the class structure is. The
255 @code{class_init_func} field from the @code{GtkTypeInfo} structure is
256 called for all the members in the types ancestry, including the
257 type. The order of this invocation proceeds from the root on down. For
258 example, the @code{GtkWidgetClass} is first initialized as an
259 @code{GtkObjectClass} by the object class initialization routine and
260 then by the widget class initialization routine. This allows the widget
261 class initialization routine to override values set by the object class
262 initialization routine. The returned structure is shared by all objects
263 of @var{type} and, as such, should not be modified.
266 @deftypefun gpointer gtk_type_new (guint @var{type})
267 Returns a new instance of an @var{type} object. The object structure is
268 created and initialized similarly to the class structure (as described
269 above). The @code{object_size} and @code{object_init_func} fields of the
270 @code{GtkTypeInfo} structure are used to determine the objects allocated
271 size and the object specific initialization routine. Similarly to the
272 class initialization, all the object initialization routines from the
273 root on down to the particular type being created are invoked.
276 @deftypefun void gtk_type_describe_heritage (guint @var{type})
277 Prints the type heritage for @var{type}. The heritage for a type
278 includes the type and all its parent types up the type tree.
281 @deftypefun void gtk_type_describe_tree (guint @var{type}, gint @var{show_size})
282 Prints the type tree which starts at @var{type}. @var{show_size} is a
283 boolean which determines whether type sizes are printed.
286 @deftypefun gint gtk_type_is_a (guint @var{type}, guint @var{is_a_type})
287 A predicate function which determines whether the relation @var{type}
288 is_a @var{is_a_type} is true.
291 @section Object functions
293 The GtkObject type is the root of the type hierarchy used by GTK. It
294 provides a minimal set of fields used to implement the actual
295 object, class and signal mechanisms, as well as several utility routines
296 which make dealing with objects easier.
298 For the adventurous, see @ref{Object Implementation}.
300 @deftypefun guint gtk_object_get_type (void)
301 Returns the @code{GtkObject} type identifier.
304 @deftypefun void gtk_object_class_add_signals (GtkObjectClass *@var{class}, gint *@var{signals}, gint @var{nsignals})
305 Adds @var{signals} to the @code{signals} field in the GtkObjectClass
306 structure @var{class}. @xref{Signals}.
309 @deftypefun void gtk_object_destroy (GtkObject *@var{object})
310 Performs checks to make sure it is alright to destroy @var{object} and
311 then emits the @code{destroy} signal. The check which is performed is to
312 make sure @var{object} is not already processing another signal. If this
313 were the case then destroying the object immediately would undoubtedly
314 cause problems as the other signal would not be able to tell the object
315 was destroyed. The solution is that if @var{object} is processing another
316 signal we mark @var{object} is needing to be destroyed. When we finish
317 processing of the other signal we check whether the object needs to be
321 The GtkObject type provides a mechanism for associating arbitrary
322 amounts of data with an object. The data is associated with the object
323 using a character string key. The functions @code{gtk_object_set_data},
324 @code{gtk_object_get_data}, and @code{gtk_object_remove_data} are the
325 interface to this mechanism. Two other routines,
326 @code{gtk_object_set_user_data} and @code{gtk_object_get_user_data},
327 exist as convenience functions which simply use the same mechanism.
329 @deftypefun void gtk_object_set_data (GtkObject *@var{object}, const char *@var{key}, gpointer @var{data})
330 Associate @var{data} with @var{key} in the data list of @var{object}.
333 @deftypefun gpointer gtk_object_get_data (GtkObject *@var{object}, const char *@var{key})
334 Retrieve the data associated with @var{key} in the data list of @var{object}.
337 @deftypefun void gtk_object_remove_data (GtkObject *@var{object}, const char *@var{key})
338 Remove the data associated with @var{key} in the data list of @var{object}.
341 @deftypefun void gtk_object_set_user_data (GtkObject *@var{object}, gpointer @var{data})
342 Sets @var{data} into the @code{user_data} field of @var{object}.
345 @deftypefun gpointer gtk_object_get_user_data (GtkObject *@var{object})
346 Returns the @code{user_data} field of @var{object}.
349 The GtkObject type also provides a mechanism for specifying
350 initialization values for fields. This general mechanism is called
351 object value stacks. The reason for using value stacks is that they can
352 simplify the life of the programmer. For instance, by default widgets
353 are non-visible when created. However, the ``visible'' value for widgets
354 may be specified so that widgets are made visible when created. (FIXME:
357 @deftypefun void gtk_object_value_stack_new (guint @var{object_type}, const gchar *@var{value_id}, GtkParamType @var{value_type})
360 @deftypefun void gtk_object_push_value (guint @var{object_type}, const gchar *@var{value_id}, @dots{})
361 Push a value on the value stack specified by @var{object_type} and
362 @var{value_id}. The type of value is implicitly given in the context of
363 @var{object_type} and @var{value_id}. (That is, it is not specified
364 explicitly in the function call). Only a single extra argument is
365 expected which is the data which is to be placed on the stack.
368 @deftypefun void gtk_object_pop_value (guint @var{object_type}, const gchar *@var{value_id})
369 Pop a value of the value stack specified by @var{object_type} and
373 @deftypefun gint gtk_object_peek_value (guint @var{object_type}, const gchar *@var{value_id}, gpointer @var{data})
374 Peek at the value on the top of the value stack specified by
375 @var{object_type} and @var{value_id}. The @var{data} argument is
376 interpreted as the location of where to place the ``peeked'' data. For
377 instance, if the peeked data is of type @code{GTK_PARAM_POINTER}, then
378 @var{data} will be a pointer to a pointer. If the value stack is empty
379 or does not exist or an error occurs, @code{gtk_object_peek_value} will
380 return @code{FALSE}. On success it will return @code{TRUE}.
384 @node Signals, Widgets, Objects, Top
385 @comment node-name, next, previous, up
386 @chapter Signals Overview
389 Signals are GTK's method for objects to perform callbacks. A signal is
390 an event which occurs upon an object. The programmer can connect to a
391 signal of an object which involves specifying a function to be called
392 when that signal is emitted in the specified object.
394 When a signal is emitted, both the class function associated with the
395 signal (when it was defined) and all signal handlers installed for that
396 signal on the particular object emitting the signal are called. The
397 widget programmer can specify whether the class function is to be called
398 before after or both before and after the signal handlers installed by
399 the widget user. The widget user can, however, specify that their signal
400 handler is to be run after the class function (using the ``_after''
401 signal connection routines). Any signal handling function can emit the
402 same signal on the same object while it is running causing that signal
403 emittion to either restart or to run recursively. Additionally, signal
404 emittion can be terminated prematurely. While both such abilities are
405 rarely used, they do allow for greater flexibility in regards to
406 signals. For instance, a programmer can attach to the key press event
407 signal and intercept all tab key presses from a widget. This particular
408 example is used in the file selection dialog to implement tab completion
409 of filenames and prevent the entry widget from inserting the tab into
412 Signals are selected using either an integer identifier or a character
413 string name. It is convention to name the signal the same as the class
414 function which is associated with it. There are two versions of most of
415 the signal functions, one which takes an integer identifier and one
416 which takes a character string name for the signal.
418 @deftypefun gint gtk_signal_new (gchar *@var{name}, GtkSignalRunType @var{run_type}, gint @var{object_type}, gint @var{function_offset}, GtkSignalMarsahller @var{marshaller}, GtkParamType @var{return_val}, gint @var{nparams}, @dots{})
419 Create a new signal and give it the character string identifier
420 @var{name}. @var{name} needs to be unique in the context of
421 @var{object_type}'s branch of the class hierarchy. That is,
422 @var{object_type} cannot create a signal type with the same name as a
423 signal type created by one of its parent types.
425 @var{run_type} specifies whether the class function should be run before
426 (@code{GTK_RUN_FIRST}), after (@code{GTK_RUN_LAST}) or both before and
427 after normal signal handlers (@code{GTK_RUN_BOTH}). Additionally, the
428 @code{GTK_RUN_NO_RECURSE} value can be or'ed with any of those values to
429 specify that the signal should not be recursive. By default, emitting
430 the same signal on the same widget will cause the signal to be emitted
431 twice. However, if the @code{GTK_RUN_NO_RECURSE} flag is specified,
432 emitting the same signal on the same widget will cause the current
433 signal emittion to be restarted. This allows the widget programmer to
434 specify the semantics of signal emittion on a per signal
435 basis. (The @code{GTK_RUN_NO_RECURSE} flag is used by the GtkAdjustment
438 The @var{function_offset} is the byte offset from the start of the class
439 structure to the class function field within the class structure. The
440 easiest means to compute this offset is by using the
441 @code{GTK_SIGNAL_OFFSET} macro which takes the class structure type as
442 the first argument and the field as the second argument. For example,
443 @code{GTK_SIGNAL_OFFSET (GtkObjectClass, destroy)} will give the offset
444 of the @code{destroy} class function within the
445 @code{GtkObjectClass}. Note: An offset is specified instead of an
446 absolute location since there will be multiple instances of a class
447 structure being referenced. (The @code{GtkWidgetClass} structure ``is
448 a'' @code{GtkObjectClass} structure, etc.)
450 The @var{marshaller} function is used to invoke a signal handler. Since
451 signal handlers may take different parameters and return values and a
452 general mechanism for invoking them is not apparent, the approach of
453 making the signal creator responsible for invoking the signal handler
454 was taken. (FIXME: unfinished).
456 The @var{return_val} and @var{nparams} and the remaining arguments
457 specify the return value and the arguments to the signal handler
458 respectively. Note: There is an implicit first argument to every signal
459 handler which is the widget the signal has been emitted from. The
460 variable argument list (@var{@dots{}}) specifies the types of the
461 arguments. These can be one of @code{GTK_PARAM_CHAR},
462 @code{GTK_PARAM_SHORT}, @code{GTK_PARAM_INT}, @code{GTK_PARAM_LONG},
463 @code{GTK_PARAM_POINTER} or @code{GTK_PARAM_FUNCTION}. It is undefined
464 to specify @code{GTK_PARAM_NONE} as an argument type, however it is ok
465 to use @code{GTK_PARAM_NONE} for @var{return_val}. (This corresponds to
466 returning a @code{void}).
468 @code{gtk_signal_new} returns the integer identifier of the newly
469 created signal. Signal identifiers start numbering at 1 and increase
470 upwards. A value of -1 will be returned if an error occurs.
472 @strong{Note:} @code{gtk_signal_new} is only needed by widget writers. A
473 normal user of GTK will never needed to invoke this function.
476 @deftypefun gint gtk_signal_lookup (gchar *@var{name}, gint @var{object_type})
477 Returns the integer identifier for the signal referenced by @var{name}
478 and @var{object_type}. If @var{object_type} does not define the signal
479 @var{name}, then the signal is looked for in @var{object_type}'s parent
483 @deftypefun gint gtk_signal_emit (GtkObject *@var{object}, gint @var{signal_type}, @dots{})
484 Emit the signal specified by the integer identifier @var{signal_type}
485 from @var{object}. If an error occurs, @code{gtk_signal_emit} will
486 return @code{FALSE} and will return @code{TRUE} on success. The signal
487 definition determines the parameters passed in the variable argument
488 list (@code{@dots{}}). For example, if the signal is defined as:
491 gint (* event) (GtkWidget *widget, GdkEvent *event);
494 Then a call to emit the ``event'' signal would look like:
500 gtk_signal_emit (some_object,
501 gtk_signal_lookup ("event",
502 GTK_OBJECT_TYPE (some_object)),
503 &event, &return_val);
506 Notice that the @code{widget} argument is implicit in that the first
507 argument to every signal is a type derived from @code{GtkObject}. The
508 @var{return_val} argument is actually a pointer to the return value type
509 since the signal mechanism needs to be able to place the return value in
510 an actual location. And lastly, the @code{gtk_signal_lookup} call is
511 normally avoided by using the @code{gtk_signal_emit_by_name} function
512 instead. @code{gtk_signal_emit} is normally used internally by widgets
513 which know the signal identifier (since they defined the signal) and can
514 therefore side-step the cost of calling @code{gtk_signal_lookup}.
517 @deftypefun gint gtk_signal_emit_by_name (GtkObject *@var{object}, gchar *@var{name}, @dots{})
518 Similar to @code{gtk_signal_emit} except that the signal is referenced
519 by @var{name} instead of by its integer identifier.
522 @deftypefun void gtk_signal_emit_stop (GtkObject *@var{object}, gint @var{signal_type})
523 Stop the emission of the signal @var{signal_type} on
524 @var{object}. @var{signal_type} is the integer identifier for the signal
525 and can be determined using the function
526 @code{gtk_signal_lookup}. Alternatively, the function
527 @code{gtk_signal_emit_stop_by_name} can be used to refer to the signal
528 by name. Attempting to stop the emission of a signal that isn't being
529 emitted does nothing.
532 @deftypefun void gtk_signal_emit_stop_by_name (GtkObject *@var{object}, gchar *@var{name})
533 Similar to @code{gtk_signal_emit_stop} except that the signal is
534 referenced by @var{name} instead of by its integer identifier.
537 @deftypefun gint gtk_signal_connect (GtkObject *@var{object}, gchar *@var{name}, GtkSignalFunc @var{func}, gpointer @var{func_data})
538 Connects a signal handling function to a signal emitting
539 object. @var{func} is connected to the signal @var{name} emitted by
540 @var{object}. The arguments and returns type of @var{func} should match
541 the arguments and return type of the signal @var{name}. However,
542 @var{func} may take the extra argument of @var{func_data}. Due to the C
543 calling convention it is ok to ignore the extra argument. (It is ok to
544 ignore all the arguments in fact).
546 @code{gtk_signal_connect} returns an integer identifier for the
547 connection which can be used to refer to it in the future. Specifically
548 it is useful for removing the connection and/or blocking it from being
552 @deftypefun gint gtk_signal_connect_after (GtkObject *@var{object}, gchar *@var{name}, GtkSignalFunc @var{func}, gpointer @var{func_data})
553 Similar to @code{gtk_signal_connect} except the signal handler is
554 connected in the ``after'' slot. This allows a signal handler to be
555 guaranteed to run after other signal handlers connected to the same
556 signal on the same object and after the class function associated with
559 Like @code{gtk_signal_connect}, @code{gtk_signal_connect_after} returns
560 an integer identifier which can be used to refer to the connection.
563 @deftypefun gint gtk_signal_connect_object (GtkObject *@var{object}, gchar *@var{name}, GtkSignalFunc @var{func}, GtkObject *@var{slot_object})
564 Connects @var{func} to the signal @var{name} emitted by
565 @var{object}. Similar to @code{gtk_signal_connect} with the difference
566 that @var{slot_object} is passed as the first parameter to @var{func}
567 instead of the signal emitting object. This can be useful for connecting
568 a signal emitted by one object to a signal in another object. A common
569 usage is to connect the ``destroy'' signal of dialog to the ``clicked''
570 signal emitted by a ``close'' button in the dialog. That is, the
571 ``clicked'' signal emitted by the button will caused the ``destroy''
572 signal to be emitted for the dialog. This is also the ``right'' way to
573 handle closing of a dialog since the ``destroy'' signal will be sent if
574 the dialog is deleted using a window manager function and this enables
575 the two methods of closing the window to be handled by the same
576 mechanism. Returns an integer identifier which can be used to refer to
580 @deftypefun gint gtk_signal_connect_object_after (GtkObject *@var{object}, gchar *@var{name}, GtkSignalFunc @var{func}, GtkObject *@var{slot_object})
581 Similar to @code{gtk_signal_connect_object} except the signal handler is
582 connected in the ``after'' slot. This allows a signal handler to be
583 guaranteed to run after other signal handlers connected to the same
584 signal on the same object and after the class function associated with
585 the signal. Returns an integer identifier which can be used to refer to
589 @deftypefun void gtk_signal_disconnect (GtkObject *@var{object}, gint @var{id})
590 Disconnects a signal handler from an object. The signal handler is
591 identified by the integer @var{id} which is returned by the
592 @code{gtk_signal_connect*} family of functions.
595 @deftypefun void gtk_signal_disconnect_by_data (GtkObject *@var{object}, gpointer @var{data})
596 Disconnects a signal handler from an object. The signal handler is
597 identified by the @var{data} argument specified as the @var{func_data}
598 argument to the @code{gtk_signal_connect*} family of functions. For the
599 @code{gtk_signal_connect_object*} functions, @var{data} refers to the
602 @strong{Note:} This will remove all signal handlers connected to
603 @var{object} which were connected using @var{data} as their
604 @var{func_data} argument. Multiple signal handlers may be disconnected
608 @deftypefun void gtk_signal_handler_block (GtkObject *@var{object}, gint @var{id})
609 Blocks calling of a signal handler during signal emission. The signal
610 handler is identified by the integer @var{id} which is returned by the
611 @code{gtk_signal_connect*} family of functions. If the signal is already
612 blocked no change is made.
615 @deftypefun void gtk_signal_handler_block_by_data (GtkObject *@var{object}, gint @var{data})
616 Blocks calling of a signal handler during signal emission. The signal
617 handler is identified by the @var{data} argument specified as the
618 @var{func_data} argument to the @code{gtk_signal_connect*} family of
619 functions. For the @code{gtk_signal_connect_object*} functions,
620 @var{data} refers to the @var{slot_object}. If the signal is already
621 blocked no change is made.
623 @strong{Note:} This will block all signal handlers connected to
624 @var{object} which were connected using @var{data} as their
625 @var{func_data} argument. Multiple signal handlers may be blocked
629 @deftypefun void gtk_signal_handler_unblock (GtkObject *@var{object}, gint @var{id})
630 Unblocks calling of a signal handler during signal emission. The signal
631 handler is identified by the integer @var{id} which is returned by the
632 @code{gtk_signal_connect*} family of functions. If the signal is already
633 unblocked no change is made.
636 @deftypefun void gtk_signal_handler_unblock_by_data (GtkObject *@var{object}, gint @var{data})
637 Unblocks calling of a signal handler during signal emission. The signal
638 handler is identified by the @var{data} argument specified as the
639 @var{func_data} argument to the @code{gtk_signal_connect*} family of
640 functions. For the @code{gtk_signal_connect_object*} functions,
641 @var{data} refers to the @var{slot_object}. If the signal is already
642 unblocked no change is made.
644 @strong{Note:} This will unblock all signal handlers connected to
645 @var{object} which were connected using @var{data} as their
646 @var{func_data} argument. Multiple signal handlers may be unblocked
650 @deftypefun void gtk_signal_handlers_destroy (GtkObject *@var{object})
651 Destroy all of the signal handlers connected to @var{object}. There
652 should normally never be reason to call this function as it is called
653 automatically when @var{object} is destroyed.
656 @deftypefun void gtk_signal_default_marshaller (GtkObject *@var{object}, GtkSignalFunc @var{func}, gpointer @var{func_data}, GtkSignalParam *@var{params})
657 @code{gtk_signal_new} requires a callback in order to actually call a
658 signal handler for a particular signal. The vast majority of signals are
659 of the particular form:
662 (* std_signal) (gpointer std_arg);
665 @code{gtk_signal_default_marshaller} is a signal marshaller which
666 marshals arguments for a signal of that form.
670 @node Widgets, Other Objects, Signals, Top
671 @comment node-name, next, previous, up
672 @chapter Widget Overview
676 Widgets are the general term used to describe user interface objects. A
677 widget defines a class interface that all user interface objects conform
678 to. This interface allows a uniform method for dealing with operations
679 common to all objects such as hiding and showing, size requisition and
680 allocation and events.
682 The common interface that widgets must adhere to is described by the
683 GtkWidget and GtkWidgetClass structure. For the purposes of using GTK
684 these structures can be considered read-only and, for the most part,
687 All widget creation routines in GTK return pointers to GtkWidget
688 structures. In reality, all widget creation routines create structures
689 that can be viewed as equivalent to the GtkWidget structure, but often
690 have contain additional information. @xref{Object Implementation}
692 The widgets available for use are implemented in a hierarchy. Several
693 widgets exist solely as common bases for more specific widgets. For
694 example, it is not possible to create a ruler widget itself, but the
695 ruler widget provides a base and functionality common to the horizontal
698 The available widgets (in alphabetical order):
701 * GtkAlignment:: The alignment widget.
702 * GtkArrow:: The arrow widget.
703 * GtkAspectFrame:: The aspect frame widget.
704 * GtkBin:: The bin widget.
705 * GtkBox:: The box widget.
706 * GtkButtonBox:: The button box widget.
707 * GtkButton:: The button widget.
708 * GtkCheckButton:: The check button widget.
709 * GtkCheckMenuItem:: The check menu item widget.
710 * GtkCList:: The compound list widget.
711 * GtkColorSelection:: The color selector widget.
712 * GtkComboBox:: The combobox widget.
713 * GtkContainer:: The container widget.
714 * GtkCurve:: The curve widget.
715 * GtkDialog:: The dialog widget.
716 * GtkDrawingArea:: The drawing area widget.
717 * GtkEntry:: The entry widget.
718 * GtkEventBox:: The event box widget.
719 * GtkFileSelection:: The file selection dialog widget.
720 * GtkFixed:: The fixed widget.
721 * GtkFrame:: The frame widget.
722 * GtkGamma:: The gamma widget.
723 * GtkHBox:: The horizontal box widget.
724 * GtkHButtonBox:: The horizontal button box widget.
725 * GtkHPaned:: The horizontal paned widget.
726 * GtkHRuler:: The horizontal ruler widget.
727 * GtkHScale:: The horizontal scale widget.
728 * GtkHScrollbar:: The horizontal scrollbar widget.
729 * GtkHSeparator:: The horizontal separator widget.
730 * GtkImage:: The image widget.
731 * GtkInputDialog:: The input dialog widget.
732 * GtkItem:: The item widget.
733 * GtkLabel:: The label widget.
734 * GtkList:: The list widget.
735 * GtkListItem:: The list item widget.
736 * GtkMenu:: The menu widget.
737 * GtkMenuBar:: The menu bar widget.
738 * GtkMenuItem:: The menu item widget.
739 * GtkMenuShell:: The menu shell widget.
740 * GtkMisc:: The misc widget.
741 * GtkNotebook:: The notebook widget.
742 * GtkOptionMenu:: The option menu widget.
743 * GtkPaned:: The paned widget.
744 * GtkPixmap:: The pixmap widget.
745 * GtkPreview:: The preview widget.
746 * GtkProgressBar:: The progress bar widget.
747 * GtkRadioButton:: The radio button widget.
748 * GtkRadioMenuItem:: The radio menu item widget.
749 * GtkRange:: The range widget.
750 * GtkRuler:: The ruler widget.
751 * GtkScale:: The scale widget.
752 * GtkScrollbar:: The scrollbar widget.
753 * GtkScrolledWindow:: The scrolled window widget.
754 * GtkSeparator:: The separator widget.
755 * GtkStatusbar:: The statusbar widget.
756 * GtkTable:: The table widget.
757 * GtkText:: The text widget.
758 * GtkToggleButton:: The toggle button widget.
759 * GtkToolbar:: The tool bar widget.
760 * GtkTooltips:: The tool tips widget.
761 * GtkTree:: The tree widget.
762 * GtkTreeItem:: The tree item widget.
763 * GtkVBox:: The vertical box widget.
764 * GtkVButtonBox:: The vertical button box widget.
765 * GtkViewport:: The viewport widget.
766 * GtkVPaned:: The vertical paned widget.
767 * GtkVRuler:: The vertical ruler widget.
768 * GtkVScale:: The vertical scale widget.
769 * GtkVScrollbar:: The vertical scrollbar widget.
770 * GtkVSeparator:: The vertical separator widget.
771 * GtkWidget:: The base widget type.
772 * GtkWindow:: The window widget.
775 @node GtkAlignment, GtkArrow, Widgets, Widgets
776 @comment node-name, next, previous, up
777 @section The alignment widget
780 @subsection Description
782 The alignment widget is a container (@pxref{GtkContainer}) derived from
783 the bin widget (@pxref{GtkBin}). Its entire purpose is to give the
784 programmer flexibility in how the child it manages is positioned when a
787 Normally, a widget is allocated at least as much size as it
788 requests. (@pxref{GtkContainer} for a discussion of geometry
789 management). When a widget is allocated more size than it requests there
790 is a question of how the widget should expand. By convention, most GTK
791 widgets expand to fill their allocated space. Sometimes this behavior is
792 not desired. The alignment widget allows the programmer to specify how a
793 widget should expand and position itself to fill the area it is
800 The @var{xscale} and @var{yscale} options specify how to scale the child
801 widget. If the scale value is 0.0, the child widget is allocated exactly
802 the size it requested in that dimension. If the scale value is 1.0, the
803 child widget is allocated all of the space in a dimension. A scale value
804 of 1.0 for both x and y is equivalent to not using an alignment widget.
809 The @var{xalign} and @var{yalign} options specify how to position the
810 child widget when it is not allocated all the space available to it
811 (because the @var{xscale} and/or @var{yscale} options are less than
812 1.0). If an alignment value is 0.0 the widget is positioned to the left
813 (or top) of its allocated space. An alignment value of 1.0 positions the
814 widget to the right (or bottom) of its allocated space. A common usage
815 is to specify @var{xalign} and @var{yalign} to be 0.5 which causes the
816 widget to be centered within its allocated area.
821 @subsection Functions
823 @deftypefun guint gtk_alignment_get_type (void)
824 Returns the @code{GtkAlignment} type identifier.
827 @deftypefun GtkWidget* gtk_alignment_new (gfloat @var{xalign}, gfloat @var{yalign}, gfloat @var{xscale}, gfloat @var{yscale})
828 Create a new @code{GtkAlignment} object and initialize it with the
829 values @var{xalign}, @var{yalign}, @var{xscale} and @var{yscale}. The
830 new widget is returned as a pointer to a @code{GtkWidget}
831 object. @code{NULL} is returned on failure.
834 @deftypefun void gtk_alignment_set (GtkAlignment *@var{alignment}, gfloat @var{xalign}, gfloat @var{yalign}, gfloat @var{xscale}, gfloat @var{yscale})
835 Set the @var{xalign}, @var{yalign}, @var{xscale} and @var{yscale} options
836 of an alignment widget. It is important to not set the fields of the
837 @code{GtkAlignment} structure directly (or, for that matter, any type
838 derived from @code{GtkObject}).
841 @gtkstdmacros{Alignment, ALIGNMENT}
844 @node GtkArrow, GtkAspectFrame, GtkAlignment, Widgets
845 @comment node-name, next, previous, up
846 @section The arrow widget
848 @subsection Description
850 The arrow widget is derived from the misc widget (@pxref{GtkMisc}) and
851 is intended for use where a directional arrow (in one of the four
852 cardinal directions) is desired. As such, it has very limited
853 functionality and basically only draws itself in a particular direction
854 and with a particular shadow type. The arrow widget will expand to fill
855 all the space it is allocated.
860 The @var{arrow_type} option specifies which direction the arrow will
861 point. It can be one of @code{GTK_ARROW_UP}, @code{GTK_ARROW_DOWN},
862 @code{GTK_ARROW_LEFT} or @code{GTK_ARROW_RIGHT}.
866 The @var{shadow_type} option specifies how to draw the shadow for the
867 arrow. Currently, only the @code{GTK_SHADOW_IN} and
868 @code{GTK_SHADOW_OUT} shadow types are supported for drawing
869 arrows. Other shadow types will cause nothing to be drawn.
874 @subsection Functions
876 @deftypefun guint gtk_arrow_get_type (void)
877 Returns the @code{GtkArrow} type identifier.
880 @deftypefun GtkWidget* gtk_arrow_new (GtkArrowType @var{arrow_type}, GtkShadowType @var{shadow_type})
881 Create a new @code{GtkArrow} object and initialize it with the values
882 @var{arrow_type} and @var{shadow_type}. The new widget is returned as a
883 pointer to a @code{GtkWidget} object. @code{NULL} is returned on
887 @deftypefun void gtk_arrow_set (GtkArrow *@var{arrow}, GtkArrowType @var{arrow_type}, GtkShadowType @var{shadow_type})
888 Set the @var{arrow_type} and @var{shadow_type} options of an arrow
889 widget. It is important to not set the fields of the @code{GtkArrow}
890 structure directly (or, for that matter, any type derived from
894 @gtkstdmacros{Arrow, ARROW}
898 @node GtkAspectFrame, GtkBin, GtkArrow, Widgets
899 @comment node-name, next, previous, upa
900 @section The aspect frame widget
902 @subsection Description
923 @subsection Functions
925 @deftypefun guint gtk_aspect_frame_get_type (void)
926 Returns the @code{GtkAspectFrame} type identifier.
929 @deftypefun GtkWidget* gtk_aspect_frame_new (gchar *@var{label}, gfloat @var{xalign}, gfloat @var{yalign}, gfloat @var{ratio}, gint @var{obey_child})
930 Create a new @code{GtkAspectFrame} object and initialize it with the values
931 @var{label}, @var{xalign}, @var{yalign}, @var{ratio} and @var{obey_child}.
932 The new widget is returned as a pointer to a @code{GtkWidget} object.
933 @code{NULL} is returned on failure.
936 @deftypefun void gtk_aspect_frame_set (GtkAspectFrame *@var{aspect_frame}, gfloat @var{xalign}, gfloat @var{yalign}, gfloat @var{ratio}, gint @var{obey_child})
940 @gtkstdmacros{AspectFrame, ASPECT_FRAME}
943 @node GtkBin, GtkBox, GtkAspectFrame, Widgets
944 @comment node-name, next, previous, up
945 @section The bin widget
947 @subsection Description
949 The bin widget is a container (@pxref{GtkContainer}) derived from the
950 container widget. It is an abstract base class. That is, it is not
951 possible to create an actual bin widget. It exists only to provide a
952 base of functionality for other widgets. Specifically, the bin widget
953 provides a base for several other widgets that contain only a single
954 child. These widgets include alignments (@pxref{GtkAlignment}), frames
955 (@pxref{GtkFrame}), items (@pxref{GtkItem}), viewports
956 (@pxref{GtkViewport}) and windows (@pxref{GtkWindow})
962 @subsection Functions
964 @deftypefun guint gtk_bin_get_type (void)
965 Returns the @code{GtkBin} type identifier.
968 @gtkstdmacros{Bin, BIN}
972 @node GtkBox, GtkButtonBox, GtkBin, Widgets
973 @comment node-name, next, previous, up
974 @section The box widget
977 @subsection Description
979 The box widget is a container (@pxref{GtkContainer}) derived from the
980 container widget. It is an abstract base class used by the horizontal
981 box (@pxref{GtkHBox}), the vertical box (@pxref{GtkVBox}) and the
982 (@pxref{GtkButtonBox}) widgets to provide a base of common functionality.
984 A box provides an abstraction for organizing the position and size of
985 widgets. Widgets in a box are layed out horizontally or vertically. By
986 using a box widget appropriately, a programmer can control how widgets
987 are positioned and how they will be allocated space when a window gets
990 The key attribute of boxes is that they position their children in a
991 single row (horizontal boxes) or column (vertical boxes). In the case of
992 horizontal boxes, all children are stretched vertically. The vertical
993 size of the box is determined by the largest vertical requisition of all
994 of its children. Similarly, a vertical box streches all of its children
995 horizontally. The horizontal size (of the vertical box) is determined by
996 the largest horizontal requisition of all of its children. An alignment
997 widget (@pxref{GtkAlignment}) can be used to control child allocation
998 more precisely on a per child basis.
1000 The second attribute of boxes is how they expand children. In the case
1001 of a horizontal box, the main control is over how children are expanded
1002 horizontally to fill the allocated area. (The rest of this discussion
1003 will focus on horizontal boxes but it applies to vertical boxes as
1006 There are two flags which can be set controlling how a widget is
1007 expanded horizontally in a horizontal box. These are the @code{expand}
1008 and @code{fill}. There operation is fairly simple. If @code{expand} is
1009 set, the childs potentially allocated area will expand to fill available
1010 space. If @code{fill} is set, the childs actual allocated area will be
1011 its potentially allocated area. There is a difference between
1012 the potentially area (which is the area the box widget sets aside for
1013 the child) and the actual allocated area (which is the area the box
1014 widget actual allocates for the widget via
1015 @code{gtk_widget_size_allocate}).
1017 The allocation of space to children occurs as follows (for horizontal
1021 All children are allocated at least their requested size horizontally
1022 and the maximum requested child size vertically.
1025 Any child with the @code{expand} flag set is allocated @code{extra_width
1026 / nexpand_children} extra pixels horizontally. If the @code{homogeneous}
1027 flag was set, all children are considered to have the @code{expand} flag
1028 set. That is, all children will be allocated the same area.The
1029 horizontal box is a fair widget and, as such, divides up any extra
1030 allocated space evenly among the ``expand'' children. (Those children
1031 which have the @code{expand} flag set). The exception occurs when
1032 @code{extra_width / nexpand_children} does not divide cleanly. The extra
1033 space is given to the last widget.
1036 @code{spacing} number of pixels separate each child. Note: The
1037 separation is between the potentially allocated area for each child and
1038 not the actual allocated area. The @code{padding} value associated with
1039 each child causes that many pixels to be left empty to each side of the
1043 If a child has the @code{fill} flag set it is allocated its potentially
1044 allocated area. If it does not, it is allocated its requested size
1045 horizontally and centered within its potentially allocated area. Its
1046 vertical allocation is still the maximum requested size of any child.
1049 Children placed at the start of the box are placed in order of addition
1050 to the box from left to right in the boxes allocated area.. Children
1051 placed at the end of the box are placed in order of addition from right
1052 to left in the boxes allocated area.
1055 @xref{GtkHBox}, and @ref{GtkVBox}, for code examples of using horizontal
1072 @c FIXME: options for GtkBox
1076 @subsection Functions
1078 @deftypefun guint gtk_box_get_type (void)
1079 Returns the @code{GtkBox} type identifier.
1082 @deftypefun void gtk_box_pack_start (GtkBox *@var{box}, GtkWidget *@var{child}, gint @var{expand}, gint @var{fill}, gint @var{padding})
1083 Add @var{child} to the front of @var{box}. The flags @var{expand} and
1084 @var{fill} and the padding value of @var{padding} are associated with
1088 @deftypefun void gtk_box_pack_end (GtkBox *@var{box}, GtkWidget *@var{child}, gint @var{expand}, gint @var{fill}, gint @var{padding})
1089 Add @var{child} to the end of @var{box}. The flags @var{expand} and
1090 @var{fill} and the padding value of @var{padding} are associated with
1094 @deftypefun void gtk_box_pack_start_defaults (GtkBox *@var{box}, GtkWidget *@var{widget})
1095 A convenience function which is equivalent to the following:
1098 gtk_box_pack_start (@var{box}, @var{widget}, TRUE, TRUE, 0);
1102 @deftypefun void gtk_box_pack_end_defaults (GtkBox *@var{box}, GtkWidget *@var{widget})
1103 A convenience function which is equivalent to the following:
1106 gtk_box_pack_start (@var{box}, @var{widget}, TRUE, TRUE, 0);
1110 @gtkstdmacros{Box, BOX}
1114 @node GtkButtonBox, GtkButton, GtkBox, Widgets
1115 @comment node-name, next, previous, up
1116 @section The button box widget
1118 @subsection Description
1119 The button box widget is a container (@pxref{GtkContainer}) derived from the
1120 (@pxref{GtkBox}) widget. It is an abstract base class used by the horizontal
1121 button box (@pxref{GtkHButtonBox}) and the vertical button box
1122 (@pxref{GtkVButtonBox}) widgets to provide a base of common functionality.
1125 @defopt layout_style
1128 The layout style @code{GTK_BUTTONBOX_SPREAD} will spread the buttons out
1129 evenly within the button box. When the parent window is resized they will
1130 re-adjust to the new window dimensions. The @code{gtk_button_box_set_spacing}
1131 function will set the minimum space that the buttons will leave between
1135 @code{GTK_BUTTONBOX_EDGE}
1138 The layout style @code{GTK_BUTTONBOX_START} will place the buttons at the
1139 start of the button box, taking into account the spacing as set by the
1140 @code{gtk_button_box_set_spacing} function. The buttons will not move
1141 when the parent window is re-sized.
1144 The layout style @code{GTK_BUTTONBOX_END} will place the buttons at the
1145 end of the button box, taking into account the spacing as set by the
1146 @code{gtk_button_box_set_spacing} function. Again like the
1147 @code{GTK_BUTTONBOX_START} layout style the buttons will not move when
1148 the parent window is re-sized.
1157 @subsection Functions
1159 @deftypefun guint gtk_button_box_get_type (void)
1160 Returns the @code{GtkButtonBox} type identifier.
1163 @deftypefun void gtk_button_box_set_child_size_default (gint @var{width}, gint@var{height})
1166 @deftypefun void gtk_button_box_set_child_ipadding_default (gint @var{ipad_x}, gint @var{ipad_y})
1169 @deftypefun void gtk_button_box_get_child_size_default (gint *@var{width}, gint *@var{height})
1172 @deftypefun void gtk_button_box_get_child_ipadding_default (gint *@var{ipad_x}, gint *@var{ipad_y})
1175 @deftypefun void gtk_button_box_set_child_size (GtkButtonBox *@var{widget}, gint @var{width}, gint @var{height})
1178 @deftypefun void gtk_button_box_set_child_ipadding (GtkButtonBox *@var{widget}, gint @var{ipad_x}, gint @var{ipad_y})
1181 @deftypefun void gtk_button_box_set_layout (GtkButtonBox *@var{widget}, gint @var{layout_style})
1182 This will set the layout style of the buttons within this box. Currently it can
1183 be set to one of @code{GTK_BUTTONBOX_SPREAD}, @code{GTK_BUTTONBOX_EDGE},
1184 @code{GTK_BUTTONBOX_START} or @code{GTK_BUTTONBOX_END}.
1187 gtk_button_box_set_layout (GTK_BUTTON_BOX (box),
1188 GTK_BUTTONBOX_SPREAD);
1193 @deftypefun gint gtk_button_box_get_spacing (GtkButtonBox *@var{widget})
1194 Get the per widget value for spacing within the button box. This value is
1195 the amount of space that will be between the indvidual buttons contained by
1199 @deftypefun void gtk_button_box_get_child_size (GtkButtonBox *@var{wiget}, gint *@var{width}, gint *@var{height})
1202 @deftypefun void gtk_button_box_get_child_ipadding (GtkButtonBox *@var{widget}, gint *@var{ipad_x}, gint *@var{ipad_y})
1203 Get the per widget value for the padding inside the buttons. This value
1204 controls how large the buttons will be within the box.
1207 @deftypefun gint gtk_button_box_get_layout (GtkButtonBox *@var{widget})
1208 Get the @var{layout_style} for the @code{GtkButtonBox} object passed to this
1209 function in the @var{widget} variable.
1212 layout = gtk_button_box_get_layout(GTK_BUTTON_BOX (box));
1217 @gtkstdmacros{ButtonBox, BUTTON_BOX}
1220 @node GtkButton, GtkCheckButton, GtkButtonBox, Widgets
1221 @comment node-name, next, previous, up
1222 @section The button widget
1225 @subsection Description
1229 @deftypefn Signal void GtkButton::pressed (GtkButton *@var{button})
1232 @deftypefn Signal void GtkButton::released (GtkButton *@var{button})
1235 @deftypefn Signal void GtkButton::clicked (GtkButton *@var{button})
1238 @deftypefn Signal void GtkButton::enter (GtkButton *@var{button})
1241 @deftypefn Signal void GtkButton::leave (GtkButton *@var{button})
1244 @subsection Functions
1246 @deftypefun guint gtk_button_get_type (void)
1247 Returns the @code{GtkButton} type identifier.
1250 @deftypefun GtkWidget* gtk_button_new (void)
1251 Create a new @code{GtkButton} object. The new widget is returned as a
1252 pointer to a @code{GtkWidget} object. @code{NULL} is returned on failure.
1255 @deftypefun GtkWidget* gtk_button_new_with_label (gchar *@var{label})
1256 Create a new @code{GtkButton} object and set the text that is
1257 on the button to @var{label}. The new widget is returned as a
1258 pointer to a @code{GtkWidget} object. @code{NULL} is returned on failure.
1261 @deftypefun void gtk_button_pressed (GtkButton *@var{button})
1264 @deftypefun void gtk_button_released (GtkButton *@var{button})
1267 @deftypefun void gtk_button_clicked (GtkButton *@var{button})
1270 @deftypefun void gtk_button_enter (GtkButton *@var{button})
1273 @deftypefun void gtk_button_leave (GtkButton *@var{button})
1276 @gtkstdmacros{Button, BUTTON}
1280 @node GtkCheckButton, GtkCheckMenuItem, GtkButton, Widgets
1281 @comment node-name, next, previous, up
1282 @section The check button widget
1286 @subsection Description
1292 @subsection Functions
1294 @deftypefun guint gtk_check_button_get_type (void)
1295 Returns the @code{GtkCheckButton} type identifier.
1298 @deftypefun GtkWidget* gtk_check_button_new (void)
1299 Create a new @code{GtkCheckButton} object and initialize it with the
1300 default values in the library. The new widget is returned as a pointer
1301 to a @code{GtkWidget} object. A @code{NULL} is returned on failure.
1304 @deftypefun GtkWidget* gtk_check_button_new_with_label (gchar *@var{label})
1305 Create a new @code{GtkCheckButton} object and initialize it with the
1306 values @var{label}. The new widget is returned as a pointer to a
1307 @code{GtkWidget} object. @code{NULL} is returned on any failure.
1310 @deftypefun GtkCheckButton* GTK_CHECK_BUTTON (gpointer @var{obj})
1313 @deftypefun GtkCheckButtonClass* GTK_CHECK_BUTTON_CLASS (gpointer @var{class})
1316 @deftypefun gint GTK_IS_CHECK_BUTTON (gpointer @var{obj})
1319 @gtkstdmacros{CheckButton, CHECK_BUTTON}
1322 @node GtkCheckMenuItem, GtkCList, GtkCheckButton, Widgets,
1323 @comment node-name, next, previous, up
1324 @section The check menu item widget
1326 @subsection Description
1338 @deftypefn Signal void GtkCheckMenuItem::toggled (GtkCheckMenuItem *@var{check_menu_item})
1341 @subsection Functions
1343 @deftypefun guint gtk_check_menu_item_get_type (void)
1344 Returns the @code{GtkCheckMenuItem} type identifier.
1347 @deftypefun GtkWidget* gtk_check_menu_item_new (void)
1348 Create a new @code{GtkCheckMenuItem} object. The new widget is returned as a
1349 pointer to a @code{GtkWidget} object. @code{NULL} is returned on failure.
1352 @deftypefun GtkWidget* gtk_check_menu_item_new_with_label (gchar *@var{label})
1353 Create a new @code{GtkCheckMenuItem} object and initalize it with the values
1354 @var{label}. The new widget is returned as a pointer to a @code{GtkWidget}
1355 object. @code{NULL} is returned on failure.
1358 @deftypefun void gtk_check_menu_item_set_state (GtkCheckMenuItem *@var{check_menu_item}, gint @var{state})
1361 @deftypefun void gtk_check_menu_item_toggled (GtkCheckMenuItem *@var{check_menu_item})
1364 @gtkstdmacros{CheckMenuItem, CHECK_MENU_ITEM}
1367 @node GtkCList, GtkColorSelection, GtkCheckMenuItem, Widgets
1368 @comment node-name, next, previous, up
1369 @section The compound list widget
1371 @subsection Description
1377 @subsection Functions
1379 @deftypefun guint gtk_clist_get_type (void)
1380 Returns the @code{GtkCList} type identifer.
1383 @deftypefun GtkWidget* gtk_clist_new (int @var{columns})
1384 Create a new @code{GtkCList} initilizing it with the value @var{columns}.
1385 The new widget is returned as a pointer to a @code{GtkWidget} object.
1386 @code{NULL} is returned on failure.
1389 @deftypefun GtkWidget* gtk_clist_new_with_titles (int @var{columns}, gchar *@var{titles[]})
1392 @deftypefun void gtk_clist_set_border (GtkCList *@var{clist}, GtkShadowType @var{border})
1393 Set the border style of the @var{clist} to the shadow type @var{border}.
1396 @deftypefun void gtk_clist_set_selection_mode (GtkCList *@var{clist} GtkSelectionMode @var{mode})
1397 Set the selection mode on the @var{clist} to the @var{mode} selection mode.
1400 @deftypefun void gtk_clist_set_policy (GtkCList *@var{clist}, GtkPolicyType @var{vscrollbar_policy}, GtkPolicyType @var{hscrollbar_policy})
1401 Set the policy on the scrollbars on the @var{clist} to @var{vscrollbar_policy} and @var{hscrollbar_policy}.
1404 @deftypefun void gtk_clist_freeze (GtkCList *@var{clist})
1405 Stop all visual updates of the @var{clist}. Useful for when making a large
1406 number of changes to a @code{GtkCList}.
1409 @deftypefun void gtk_clist_thaw (GtkCList *@var{clist})
1410 Allow all visual updates of the @var{clist} to resume.
1413 @deftypefun void gtk_clist_column_titles_show (GtkCList *@var{clist})
1414 Show the column title buttons on the @var{clist}.
1417 @deftypefun void gtk_clist_column_titles_hide (GtkCList *@var{clist})
1418 Hide the column title buttons on the @var{clist}.
1421 @deftypefun void gtk_clist_set_column_title (GtkCList *@var{clist}, gint @var{column}, gchar *@var{title})
1422 Set the title in column @var{column} of the @var{clist} button to @var{title}.
1425 @deftypefun void gtk_clist_set_column_widget (GtkCList *@var{clist}, gint @var{column}, GtkWidget *@var{widget})
1426 Set the @var{widget} instead of the title button for the column @var{column}
1430 @deftypefun void gtk_clist_set_column_justification (GtkCList *@var{clist}, gint @var{column}, GtkJustification @var{justification})
1431 Set the @var{column}'s justification, in the @var{clist} to @var{justification}.
1434 @deftypefun void gtk_clist_set_column_width (GtkCList *@var{clist}, gint @var{column}, gint @var{width})
1435 Set the pixel width of column @var{column} in the @code{GtkCList} @var{clist}
1436 to @var{width}. This function is a necessary steo in creating a
1437 @code{GtkCList} because otherwise the column width is chosen from the width
1438 of the column title, which is almost never correct.
1441 @deftypefun void gtk_clist_set_row_height (GtkCList *@var{clist}, gint @var{height})
1442 Change the height of the rows in the @var{clist} to @var{height}. The default
1443 is the height of the current font.
1446 @deftypefun void gtk_clist_moveto (GtkCList *@var{clist}, gint @var{row}, gint@var{column}, gfloat @var{row_align}, gfloat @var{col_align})
1447 Scroll the viewing area of the @code{GtkClist} in @var{clist} to @var{column}
1448 and @var{row}. The @var{row_align} and @var{col_align} are between zero and
1449 one, representing the location the row should appear on screen. Setting
1450 @var{row_align} or the @var{col_align} to 0.0 will be the top or left of the
1451 viewing area. Setting the @var{row_align} or @var{col_align} to 1.0 will
1452 be the bottom or right of the viewing area. If the @var{row} or @var{column}
1453 is -1 then there is no change.
1456 @deftypefun void gtk_clist_set_text (GtkCList *@var{clist}, gint @var{row}, gint @var{column}, gchar *@var{text})
1457 Set a given cell's text, located by the @var{row} and @var{column}, to
1458 @var{text} replacing its current contents.
1461 @deftypefun void gtk_clist_set_pixmap (GtkCList *@var{clist}, gint @var{row}, gint @var{column}, GdkPixmap *@var{pixmap}, GdkBitmap *@var{mask})
1462 Set a given cell's text, located by the @var{column} and @var{row} arguments,
1463 to the pixmap described by the @var{pixmap} argument using the @var{mask} as
1464 its mask. The current contents of the cell will be replaced.
1467 @deftypefun void gtk_clist_setpixtext (GtkCList *@var{clist}, gint @var{row}, gint @var{column}, gchar *@var{text}, guint8 @var{spacing}, GdkPixmap *@var{pixmap}, GdkBitmap *@var{mask})
1468 Set a given cell's text and pixmap, located by the @var{row} and @var{column}
1469 arguments, to the text and pixmap described by the @var{pixmap} and @var{text}
1470 arguments. The @var{mask} will be used for the pixmap mask and the
1471 @var{spacing} argument specifies the spacing between the two.
1474 @deftypefun void gtk_clist_set_foreground (GtkCList *@var{clist}, gint @var{row}, GdkColor *@var{color})
1475 Set the foreground color of row @var{row} to @var{color} in the
1476 @code{GtkCList} @var{clist}. The @var{color} must
1477 already be allocated.
1480 @deftypefun void gtk_clist_set_background (GtkCList *@var{clist}, gint @var{row}, GdkColor *@var{color})
1481 Set the background color of row @var{row} to @var{color} in the
1482 @code{GtkCList} pointed to by @var{clist}. The color must be previously
1486 @deftypefun void gtk_clist_set_shift (GtkCList *@var{clist}, gint @var{row}, gint @var{column}, gint @var{vertical}, gint @var{horizontal})
1487 Set the horizontal and vertical shift for drawing the contents of the cell
1488 located at @var{row} and @var{column}. The @var{vertical} and @var{horizontal}
1489 arguments can be positive or negitive.
1492 @deftypefun gint gtk_clist_append (GtkCList *@var{clist}, gchar *@var{text[]})
1493 Append the given text, in the @var{text[]} argument, to the @code{GtkCList}
1494 pointed to by the @var{clist}. The return value is the index of the row that
1498 @deftypefun void gtk_clist_insert (GtkCList *@var{clist}, gint @var{row}, gchar *@var{text[]})
1499 Insert a row into the @code{GtkCList} pointed to by @var{clist} at row
1500 @var{row} with the text in @var{text[]}.
1503 @deftypefun void gtk_clist_remove (GtkCList *@var{clist}, gint @var{row})
1504 Remove row index @var{row} from the @var{clist}.
1507 @deftypefun void gtk_clist_set_row_data (GtkCList *@var{clist}, gint @var{row}, gpointer @var{data})
1508 Will set an arbitrary data pointer, @var{data}, for row @var{row} in the
1509 @code{GtkCList} pointed to by @var{clist}.
1512 @deftypefun gpointer gtk_clist_get_row_data (GtkCList *@var{clist}, gint @var{row})
1513 Return the data that was set for row @var{row} from the @code{GtkCList} pointed
1514 to by @var{clist}. @code{NULL} is returned if no data was set.
1517 @deftypefun void gtk_clist_select_row (GtkCList *@var{clist}, gint @var{row}, gint @var{column})
1518 Force selection of a row, located by @var{row} and @var{column}, in the
1519 @code{GtkCList} pointed to by @var{clist}.
1522 @deftypefun void gtk_clist_unselect_row (GtkCList *@var{clist}, gint @var{row}, gint @var{column})
1523 Force the unselection of a row, located by @var{row} and @var{column}, in the
1524 @code{GtkCList} pointed to by @var{clist}.
1527 @deftypefun void gtk_clist_clear (GtkCList *@var{clist})
1528 Clear the entire contents of the @code{GtkCList} pointed to by @var{clist}.
1529 This is much faster then removing each item seperatly with
1530 @code{gtk_clist_remove}.
1533 @gtkstdmacros{CList, CLIST}
1536 @node GtkColorSelection, GtkComboBox, GtkCList, Widgets
1537 @comment node-name, next, previous, up
1538 @section The color selector widget
1540 @subsection Description
1546 GTK_UPDATE_CONTINUOUS
1548 GTK_UPDATE_DISCONTINOUS
1565 @subsection Functions
1567 @deftypefun guint gtk_color_selection_get_type (void)
1568 Returns the @code{GtkColorSelection} type identifier.
1571 @deftypefun GtkWidget* gtk_color_selection_new (void)
1572 Create a new @code{GtkColorSelection} object. The new object is returned as a
1573 pointer to a @code{GtkWidget} object. @code{NULL} is returned on failure.
1576 @deftypefun void gtk_color_selection_set_update_policy (GtkColorSelection *@var{colorsel}, GtkUpdateType @var{policy})
1579 @deftypefun void gtk_color_selection_set_color (GtkColorSelection *@var{colorsel}, gdouble *@var{color})
1582 @deftypefun void gtk_color_selection_get_color (GtkColorSelection *@var{colorsel}, gdouble *@var{color})
1585 @deftypefun void gtk_color_selection_set_opacity (GtkColorSelection *@var{colorsel}, gint @var{use_opacity})
1588 @deftypefun guint gtk_color_selection_dialog_get_type (void)
1591 @deftypefun GtkWidget* gtk_color_selection_dialog_new (gchar *@var{title})
1594 @gtkstdmacros{ColorSelection, COLOR_SELECTION}
1597 @node GtkComboBox, GtkContainer, GtkColorSelection, Widgets
1598 @comment node-name, next, previous, up
1599 @section The combobox widget
1601 @subsection Description
1607 @subsection Functions
1609 @deftypefun guint gtk_combo_box_get_type (void)
1610 Returns the @code{GtkComboBox} type identifier.
1613 @deftypefun GtkWidget* gtk_combo_box_new (GList *@var{popdown_strings})
1616 @deftypefun GtkWidget* gtk_combo_box_new_with_max_length (GList *@var{popdown_strings}, guint16 @var{max})
1619 @deftypefun void gtk_combo_box_set_popdown_strings(GtkComboBox *@var{combobox}, GList *@var{popdown_strings})
1622 @gtkstdmacros{ComboBox, COMBO_BOX}
1625 @node GtkContainer, GtkCurve, GtkComboBox, Widgets
1626 @comment node-name, next, previous, up
1627 @section The container widget
1629 @subsection Description
1633 @defopt border_width
1638 @deftypefn Signal void GtkContainer::add (GtkContainer *@var{container}, GtkWidget *@var{widget})
1641 @deftypefn Signal void GtkContainer::remove (GtkContainer *@var{container}, GtkWidget *@var{widget})
1644 @deftypefn Signal void GtkContainer::need_resize (GtkContainer *@var{container}, GtkWidget *@var{widget})
1647 @deftypefn Signal void GtkContainer::foreach (GtkContainer *@var{container}, GtkCallback @var{callback}, gpointer @var{callback_data})
1650 @deftypefn Signal gint GtkContainer::focus (GtkContainer *@var{container}, GtkDirectionType @var{direction})
1653 @subsection Functions
1655 @deftypefun guint gtk_container_get_type (void)
1656 Returns the @code{GtkContainer} type identifier.
1659 @deftypefun void gtk_container_border_width (GtkContainer *@var{container}, gint @var{border_width})
1662 @deftypefun void gtk_container_add (GtkContainer *@var{container}, GtkWidget *@var{widget})
1663 Add @var{widget} to the @var{container}.
1666 @deftypefun void gtk_container_remove (GtkContainer *@var{container}, GtkWidget *@var{widget})
1667 Remove @var{widget} from @var{container}.
1670 @deftypefun void gtk_container_disable_resize (GtkContainer *@var{container})
1673 @deftypefun void gtk_container_enable_resize (GtkContainer *@var{container})
1676 @deftypefun void gtk_container_block_resize (GtkContainer *@var{container})
1679 @deftypefun void gtk_container_unblock_resize (GtkContainer *@var{container})
1682 @deftypefun gint gtk_container_need_resize (GtkContainer *@var{container}, GtkWidget *@var{widget})
1685 @deftypefun void gtk_container_check_resize (GtkContainer *@var{container}, GtkWidget *@var{widget})
1688 @deftypefun void gtk_container_foreach (GtkContainer *@var{container}, GtkCallback @var{callback}, gpointer @var{callback_data})
1691 @deftypefun void gtk_container_focus (GtkContainer *@var{container}, GtkDirectionType @var{direction})
1694 @deftypefun GList* gtk_container_children (GtkContainer @var{container})
1697 @gtkstdmacros{Container, CONTAINER}
1700 @node GtkCurve, GtkDialog, GtkContainer, Widgets
1701 @comment node-name, next, previous, up
1702 @section The curve widget
1704 @subsection Description
1710 @item GTK_CURVE_TYPE_LINEAR
1711 @item GTK_CURVE_TYPE_SPLINE
1712 @item GTK_CURVE_TYPE_FREE
1718 @subsection Functions
1720 @deftypefun guint gtk_curve_get_type (void)
1721 Returns the @code{GtkCurve} type identifier.
1724 @deftypefun GtkWidget* gtk_curve_new (void)
1725 Create a new @code{GtkCurve} returning the new widget as a pointer to a
1726 @code{GtkWidget} object.
1729 @deftypefun void gtk_curve_reset (GtkCurve *@var{curve})
1732 @deftypefun void gtk_curve_set_gamma (GtkCurve *@var{curve}, gfloat @var{gamma})
1735 @deftypefun void gtk_curve_set_range (GtkCurve *@var{curve}, gfloat @var{min_x}, gfloat @var{max_x}, gfloat @var{min_y}, gfloat @var{max_y})
1738 @deftypefun void gtk_curve_get_vector (GtkCurve *@var{curve}, int @var{veclen}, gfloat @var{vector[]})
1741 @deftypefun void gtk_curve_set_vector (GtkCurve *@var{curve}, int @var{vaclen}, gfloat @var{vector[]})
1744 @deftypefun void gtk_curve_set_curve_type (GtkCurve *@var{curve}, GtkCurveType @var{type})
1747 @gtkstdmacros{Curve, CURVE}
1750 @node GtkDialog, GtkDrawingArea, GtkCurve, Widgets
1751 @comment node-name, next, previous, up
1752 @section The dialog widget
1755 @subsection Description
1756 The dialog widget is a window (@pxref{GtkWindow}) that has a vertical box
1757 (@pxref{GtkVBox}), a horizontal box (@pxref{GtkHBox}), separated with a
1758 horizontal separator (@pxref{GtkHSeparator}).
1764 @subsection Functions
1766 @deftypefun guint gtk_dialog_get_type (void)
1767 Returns the @code{GtkDialog} type identifier.
1770 @deftypefun GtkWidget* gtk_dialog_new (void)
1771 Create a new @code{GtkDialog} object and return the new widget as a pointer
1772 to a @code{GtkWidget} object. @code{NULL} is returned on failure.
1775 @gtkstdmacros{Dialog, DIALOG}
1779 @node GtkDrawingArea, GtkEntry, GtkDialog, Widgets
1780 @comment node-name, next, previous, up
1781 @section The drawing area widget
1783 @subsection Description
1795 @subsection Functions
1797 @deftypefun guint gtk_drawing_area_get_type (void)
1798 Returns the @code{GtkDrawingArea} type identifier.
1801 @deftypefun GtkWidget* gtk_drawing_area_new (void)
1802 Create a new @code{GtkDrawingArea} object returning the new widget as a
1803 pointer to a @code{GtwWidget} object. @code{NULL} is returned on failure.
1806 @deftypefun void gtk_drawing_area_size (GtkDrawingArea *@var{darea}, gint @var{width}, gint @var{height})
1809 @gtkstdmacros{DrawingArea, DRAWING_AREA}
1813 @node GtkEntry, GtkEventBox, GtkDrawingArea, Widgets
1814 @comment node-name, next, previous, up
1815 @section The entry widget
1818 @subsection Description
1823 With this option it is possible to set the @var{text_max_length} to the
1824 value speified in the @var{max} option. This value is a guint16 value.
1832 @deftypefn Signal void GtkEntry::insert_text (GtkEntry *@var{entry}, gchar *@var{text}, gint @var{length}, gint *@var{position})
1835 @deftypefn Signal void GtkEntry::delete_text (GtkEntry *@var{entry}, gint @var{start_pos}, gint @var{end_pos})
1838 @deftypefn Signal void GtkEntry::changed (GtkEntry *@var{entry})
1841 @deftypefn Signal void GtkEntry::set_text (GtkEntry *@var{entry})
1844 @deftypefn Signal void GtkEntry::activate (GtkEntry *@var{entry})
1847 @subsection Functions
1849 @deftypefun guint gtk_entry_get_type (void)
1850 Returns the @code{GtkEntry} type identifier.
1853 @deftypefun GtkWidget* gtk_entry_new (void)
1854 Create a new @code{GtkEntry} object. The new widget is returned
1855 as a pointer to a @code{GtkWidget} object. @code{NULL} is returned on
1859 @deftypefun GtkWidget* gtk_entry_new_with_max_length (guint16 @var{max})
1860 Create a new @code{GtkEntry} object initilizing it with the value @var{max}.
1861 The new widget is returned as a pointer to a @code{GtkWidget} object.
1862 @code{NULL} is returned on failure.
1865 @deftypefun void gtk_entry_set_text (GtkEntry *@var{entry}, gchar *@var{text})
1866 Will set the text in the previously created @code{GtkEntry} object to
1867 @var{text}. It is important to not set the fields of the @code{GtkEntry}
1868 structure directly (or, for that matter, any type derived from
1872 @deftypefun void gtk_entry_append_text (GtkEntry *@var{entry}, gchar *@var{text})
1873 Append the text that is in the @var{text} argument to the widgets text. It is
1874 important to not set the fields of the @code{GtkEntry} structure directly.
1877 @deftypefun void gtk_entry_prepend_text (GtkEntry *@var{entry}, gchar *@var{text})
1878 Add the text in the @var{text} argument to the text in the @code{GtkEntry}
1879 widget. It is important to not set the fields of the @code{GtkEntry} structure
1883 @deftypefun void gtk_entry_set_position (GtkEntry *@var{entry}, gint @var{position})
1886 @deftypefun void gtk_entry_set_visibility (GtkEntry *@var{entry}, gint @var{visible})
1887 Will make the keystrokes entered into the @code{GtkEntry} object invisible
1888 when @var{visible} is @code{TRUE}. Defaults to @code{FALSE}.
1891 @deftypefun gchar* gtk_entry_get_text (GtkEntry *@var{entry})
1892 Returns the text that is contained in the @code{GtkEntry} as a pointer to a
1893 @code{gchar} variable.
1896 @gtkstdmacros{Entry, ENTRY}
1899 @node GtkEventBox, GtkFileSelection, GtkEntry, Widgets
1900 @comment node-name, next, previous, up
1901 @section The event box widget
1903 @subsection Description
1909 @subsection Functions
1910 @deftypefun guint gtk_event_box_get_type (void)
1911 Returns the @code{GtkEventBox} type identifier.
1914 @deftypefun GtkWidget* gtk_event_box_new (void)
1915 Create a new @code{GtkEventBox} returning the new widget as a pointer to
1916 a @code{GtkWidget} object. @code{NULL} is returned on failure.
1919 @gtkstdmacros{GtkEventBox, EVENT_BOX}
1922 @node GtkFileSelection, GtkFixed, GtkEventBox, Widgets
1923 @comment node-name, next, previous, up
1924 @section The file selection dialog widget
1926 @subsection Description
1938 @subsection Functions
1940 @deftypefun guint gtk_file_selection_get_type (void)
1941 Returns the @code{GtkFileSelection} type identifier.
1944 @deftypefun GtkWidget* gtk_file_selection_new (gchar *@var{title})
1945 Create a new @code{GtkFileSelection} object and return the new widget as a
1946 pointer to a @code{GtkWidget}. @code{NULL} is returned on failure.
1949 @deftypefun void gtk_file_selection_set_filename (GtkFileSelection *@var{filesel}, gchar *@var{filename})
1952 @deftypefun gchar* gtk_file_selection_get_filename (GtkFileSelection *@var{filesel})
1955 @gtkstdmacros{FileSelection, FILE_SELECTION}
1958 @node GtkFixed, GtkFrame, GtkFileSelection, Widgets
1959 @comment node-name, next, previous, up
1960 @section The fixed widget
1962 @subsection Description
1968 @subsection Functions
1970 @deftypefun guint gtk_fixed_get_type (void)
1971 Returns the @code{GtkFixed} type identifier.
1974 @deftypefun GtkWidget* gtk_fixed_new (void)
1975 Create a new @code{GtkFixed} object returning the new widget as a pointer to
1976 a @code{GtkWidget} object. @code{NULL} is returned on failure.
1979 @deftypefun void gtk_fixed_put_new (GtkFixed *@var{fixed}, GtkWidget *@var{widget}, gint16 @var{x}, gint16 @var{y})
1982 @deftypefun void gtk_fixed_move (GtkFixed *@var{fixed}, GtkWidget *@var{widget}, gint16 @var{x}, gint16 @var{y})
1985 @gtkstdmacros{Fixed, FIXED}
1988 @node GtkFrame, GtkGamma, GtkFixed, Widgets
1989 @comment node-name, next, previous, up
1990 @section The frame widget
2006 @subsection Description
2010 @subsection Functions
2012 @deftypefun guint gtk_frame_get_type (void)
2013 Returns the @code{GtkFrame} type identifier.
2016 @deftypefun GtkWidget* gtk_frame_new (gchar *@var{label})
2017 Create a new @code{GtkFrame} object initilizing it with the value in
2018 @var{label}. The new widget is returned as a pointer to a @code{GtkWidget}
2019 object. @code{NULL} is returned on failure.
2022 @deftypefun void gtk_frame_set_label (GtkFrame *@var{frame}, gchar *@var{label})
2025 @deftypefun void gtk_frame_set_label_align (GtkFrame *@var{frame}, gfloat @var{xalign}, gfloat @var{yalign})
2028 @deftypefun void gtk_frame_set_shadow_type (GtkFrame *@var{frame}, GtkShadowType @var{type})
2031 @gtkstdmacros{Frame, FRAME}
2034 @node GtkGamma, GtkHBox, GtkFrame, Widgets
2035 @comment node-name, next, previous, up
2036 @section The gamma widget
2038 @subsection Description
2044 @subsection Functions
2046 @deftypefun guint gtk_gamma_curve_get_type (void)
2047 Returns the @code{GtkGamma} type identifier.
2050 @deftypefun GtkWidget* gtk_gamma_curve_new (void)
2051 Create a new @code{GtkGamma} object returning the new widget as a pointer
2052 to a @code{GtkWidget} object. @code{NULL} is returned on failure.
2055 @gtkstdmacros{Gamma, GAMMA}
2058 @node GtkHBox, GtkHButtonBox, GtkGamma, Widgets
2059 @comment node-name, next, previous, up
2060 @section The horizontal box widget
2063 @subsection Description
2068 This option controls whether each object in the box has the same size. In the
2069 case of the @code{GtkHBox}, this effects the width. If this option is set then
2070 the @var{expand} option to the @code{gtk_box_pack} (@pxref{GtkBox}) routines
2071 is always set to @code{TRUE}.
2075 This option controls the amount of space that is added between the objects
2076 packed into this @code{GtkVBox} object.
2081 @subsection Functions
2083 @deftypefun guint gtk_hbox_get_type (void)
2084 Returns the @code{GtkHBox} type identifier.
2087 @deftypefun GtkWidget* gtk_hbox_new (gint @var{homogeneous}, gint @var{spacing})
2088 Create a new @code{GtkHBox} object initilizing it with the values in
2089 @var{homogeneous} and @var{spacing}. The new widget is returned as a pointer
2090 to a @code{GtkWidget} object. @code{NULL} is returned on failure.
2093 @gtkstdmacros{HBox, HBOX}
2096 @node GtkHButtonBox, GtkHPaned, GtkHBox, Widgets
2097 @comment node-name, next, previous, up
2098 @section The horizontal button box widget
2100 @subsection Description
2112 @subsection Functions
2114 @deftypefun guint gtk_hbutton_box_get_type (void)
2115 Returns the @code{GtkHButtonBox} type identifier.
2118 @deftypefun GtkWidget* gtk_hbutton_box_new (void)
2119 Create a new @code{GtkHButtonBox} object returning the new widget as a pointer
2120 to a @code{GtkWidget} object. @code{NULL} is returned on failure.
2123 @deftypefun void gtk_hbutton_box_set_spacing_default (gint @var{spacing})
2126 @deftypefun void gtk_hbutton_box_set_layout_default (gint @var{layout})
2129 @deftypefun gint gtk_hbutton_box_get_spacing_default (void)
2132 @deftypefun gint gtk_hbutton_box_get_layout_default (void)
2135 @gtkstdmacros {HButtonBox, HBUTTON_BOX}
2138 @node GtkHPaned, GtkHRuler, GtkHButtonBox, Widgets
2139 @comment node-name, next, previous, up
2140 @section The horizontal paned widget
2142 @subsection Description
2148 @subsection Functions
2150 @deftypefun void gtk_hpaned_get_type (void)
2151 Returns the @code{GtkHPaned} type identifier.
2154 @deftypefun GtkWidget* gtk_hpaned_new (void)
2155 Create a new @code{GtkHPaned} object returning the new widget as a pointer
2156 to a @code{GtkWidget} object.
2159 @gtkstdmacros{HPaned, HPANED}
2162 @node GtkHRuler, GtkHScale, GtkHPaned, Widgets
2163 @comment node-name, next, previous, up
2164 @section The horizontal ruler widget
2167 @subsection Description
2173 @subsection Functions
2175 @deftypefun guint gtk_hruler_get_type (void)
2176 Returns the @code{GtkHRuler} type identifier.
2179 @deftypefun GtkWidget* gtk_hruler_new (void)
2180 Create a new @code{GtkHRuler} object returning the new widget as a pointer
2181 to a @code{GtkWidget} object. @code{NULL} is returned on failure.
2184 @gtkstdmacros{HRuler, HRULER}
2188 @node GtkHScale, GtkHScrollbar, GtkHRuler, Widgets
2189 @comment node-name, next, previous, up
2190 @section The horizontal scale widget
2193 @subsection Description
2199 @subsection Functions
2201 @deftypefun guint gtk_hscale_get_type (void)
2202 Returns the @code{GtkHScale} type identifier.
2205 @deftypefun GtkWidget* gtk_hscale_new (GtkAdjustment *@var{adjustment})
2206 Create a new @code{GtkHScale} object returning the new widget as a pointer
2207 to a @code{GtkWidget} object. @code{NULL} is returned on failure.
2210 @gtkstdmacros{HScale, HSCALE}
2214 @node GtkHScrollbar, GtkHSeparator, GtkHScale, Widgets
2215 @comment node-name, next, previous, up
2216 @section The horizontal scrollbar widget
2219 @subsection Description
2225 @subsection Functions
2227 @deftypefun guint gtk_hscrollbar_get_type (void)
2228 Returns the @code{GtkHScrollbar} type identifier.
2231 @deftypefun GtkWidget* gtk_hscrollbar_new (GtkAdjustment *@var{adjustment})
2232 Create a new @code{GtkHScrollbar} object returning the new widget as a
2233 pointer to a @code{GtkWidget} object. @code{NULL} is returned on failure.
2236 @gtkstdmacros{HScrollbar, HSCROLLBAR}
2240 @node GtkHSeparator, GtkImage, GtkHScrollbar, Widgets
2241 @comment node-name, next, previous, up
2242 @section The horizontal separator widget
2245 @subsection Description
2251 @subsection Functions
2253 @deftypefun guint gtk_hseparator_get_type (void)
2254 Returns the @code{GtkHSeparator} type identifier.
2257 @deftypefun GtkWidget* gtk_hseparator_new (void)
2258 Create a new @code{GtkHSeparator} object returning the new widget as a pointer
2259 to a @code{GtkWidget} object. @code{NULL} is returned on failure.
2262 @gtkstdmacros{HSeparator, HSEPARATOR}
2266 @node GtkImage, GtkInputDialog, GtkHSeparator, Widgets
2267 @comment node-name, next, previous, up
2268 @section The image widget
2271 @subsection Description
2277 @subsection Functions
2279 @deftypefun guint gtk_image_get_type (void)
2280 Returns the @code{GtkImage} type identifier.
2283 @deftypefun GtkWidget* gtk_image_new (GdkImage *@var{val}, GdkBitmap *@var{mask})
2284 Create a new @code{GtkImage} object initilizing it with the values in
2285 @var{val} and @var{mask}. The new widget is returned as a pointer to a
2286 @code{GtkWidget} object. @code{NULL} is returned on failure.
2289 @deftypefun void gtk_image_set (GtkImage *@var{image}, GdkImage *@var{val}, GdkBitmap *@var{mask})
2292 @deftypefun void gtk_image_get (GtkImage *@var{image}, GdkImage **@var{val}, GdkBitmap **@var{mask})
2295 @gtkstdmacros{Image, IMAGE}
2298 @node GtkInputDialog, GtkItem, GtkImage, Widgets
2299 @comment node-name, next, previous, up
2300 @section The input dialog widget
2302 @subsection Description
2308 @deftypefn Signal void GtkInputDialog::enable_device (GtkInputDialog *@var{inputd}, guint32 @var{devid}, gpointer *@var{data})
2311 @deftypefn Signal void GtkInputDialog::disable_device (GtkInputDialog *@var{inputd}, guint32 @var{devid}, gpointer *@var{data})
2314 @subsection Functions
2316 @deftypefun guint gtk_input_dialog_get_type (void)
2317 Returns the @code{GtkInputDialog} type identifier.
2320 @deftypefun GtkWidget* gtk_input_dialog_new (void)
2321 Create a new @code{GtkInputDialog} object and return the new widget as a
2322 pointer to a @code{GtkWidget} object. @code{NULL} is returned on failure.
2326 @gtkstdmacros{InputDialog, INPUTDIALOG}
2329 @node GtkItem, GtkLabel, GtkInputDialog, Widgets
2330 @comment node-name, next, previous, up
2331 @section The item widget
2334 @subsection Description
2338 @deftypefn Signal void GtkItem::select (GtkItem *@var{item})
2341 @deftypefn Signal void GtkItem::deselect (GtkItem *@var{item})
2344 @deftypefn Signal void GtkItem::toggle (GtkItem *@var{toggle})
2347 @subsection Functions
2349 @deftypefun guint gtk_item_get_type (void)
2350 Returns the @code{GtkItem} type identifier.
2353 @deftypefun void gtk_item_select (GtkItem *@var{item})
2356 @deftypefun void gtk_item_deselect (GtkItem *@var{item})
2359 @deftypefun void gtk_item_toggle (GtkItem *@var{item})
2362 @gtkstdmacros{Item, ITEM}
2366 @node GtkLabel, GtkList, GtkItem, Widgets
2367 @comment node-name, next, previous, up
2368 @section The label widget
2370 @subsection Description
2379 @subsection Functions
2381 @deftypefun guint gtk_label_get_type (void)
2382 Returns the @code{GtkLabel} type identifer.
2385 @deftypefun GtkWidget* gtk_label_new (GtkLabel *@var{label}, gchar *@var{str})
2386 Create a new @code{GtkLabel} object and initialize it with the
2387 text in @var{str}. The new widget is returned as a pointer to a
2388 @code{GtkWidget} object. @code{NULL} is returned on faulure.
2391 @deftypefun void gtk_label_set (GtkLabel *@var{label}, gchar *@var{str})
2392 Set the @code{GtkLabel} label value to the value passed in the @var{str}
2396 @deftypefun void gtk_label_get (GtkLabel *@var{label}, gchar **@var{str})
2397 Copies the current value in the @code{GtkLabel} label field to the variable
2398 passed in the @var{str} argument.
2401 @gtkstdmacros{Label, LABEL}
2405 @node GtkList, GtkListItem, GtkLabel, Widgets
2406 @comment node-name, next, previous, up
2407 @section The list widget
2410 @subsection Description
2414 @deftypefn Signal void GtkList::selection_changed (GtkList *@var{list})
2417 @deftypefn Signal void GtkList::select_child (GtkList *@var{list}, GtkWidget *@var{child})
2420 @deftypefn Signal void GtkList::unselect_child (GtkList *@var{list}, GtkWidget *@var{child})
2423 @subsection Functions
2425 @deftypefun guint gtk_list_get_type (void)
2426 Returns the @code{GtkList} type identifier.
2429 @deftypefun GtkWidget* gtk_list_new (void)
2430 Create a new @code{GtkList} object and return the new widget as a pointer to
2431 a @code{GtkWidget} object. @code{NULL} is returned on failure.
2434 @deftypefun void gtk_list_insert_items (GtkList *@var{list}, GList *@var{items}, gint @var{position})
2437 @deftypefun void gtk_list_append_items (GtkList *@var{list}, GList *@var{items})
2440 @deftypefun void gtk_list_prepend_items (GtkList *@var{list}, GList *@var{items})
2443 @deftypefun void gtk_list_remove_items (GtkList *@var{list}, GList *@var{items})
2446 @deftypefun void gtk_list_clear_items (GtkList *@var{list}, gint @var{start}, gint @var{end})
2449 @deftypefun void gtk_list_select_item (GtkList *@var{list}, gint @var{item})
2452 @deftypefun void gtk_list_unselect_item (GtkList *@var{list}, gint @var{item})
2455 @deftypefun void gtk_list_select_child (GtkList *@var{list}, GtkWidget *@var{child})
2458 @deftypefun void gtk_list_unselect_child (GtkList *@var{list}, GtkWidget *@var{child})
2461 @deftypefun gint gtk_list_child_position (GtkList *@var{list}, GtkWidget *@var{child})
2464 @deftypefun void gtk_list_set_selection_mode (GtkList *@var{list}, GtkSelectionMode @var{mode})
2467 @gtkstdmacros{List, LIST}
2471 @node GtkListItem, GtkMenu, GtkList, Widgets
2472 @comment node-name, next, previous, up
2473 @section The list item widget
2476 @subsection Description
2482 @subsection Functions
2484 @deftypefun guint gtk_list_item_get_type (void)
2485 Returns the @code{GtkListItem} type identifier.
2488 @deftypefun GtkWidget* gtk_list_item_new (void)
2489 Create a new @code{GtkListItem} object and return the new widget as a
2490 pointer to a @code{GtkWidget} object. @code{NULL} is returned on failure.
2493 @deftypefun GtkWidget* gtk_list_item_new_with_label (gchar *@var{label})
2494 Create a new @code{GtkListItem} object initalizing with the value @var{label}.
2495 The new widget is returned as a pointer to a @code{GtkWidget} object.
2496 @code{NULL} is returned on failure.
2499 @deftypefun void gtk_list_item_select (GtkListItem *@var{list_item})
2502 @deftypefun void gtk_list_item_deselect (GtkListItem *@var{list_item})
2505 @gtkstdmacros{ListItem, LIST_ITEM}
2509 @node GtkMenu, GtkMenuBar, GtkListItem, Widgets
2510 @comment node-name, next, previous, up
2511 @section The menu widget
2514 @subsection Description
2520 @subsection Functions
2522 @deftypefun guint gtk_menu_get_type (void)
2523 Returns the @code{GtkMenu} type identifier.
2526 @deftypefun GtkWidget* gtk_menu_new (void)
2527 Create a new @code{GtkMenu} object returning the new widget as a pointer to
2528 a @code{GtkWidget}. @code{NULL} is returned on failure.
2531 @deftypefun void gtk_menu_append (GtkMenu *@var{menu}, GtkWidget *@var{child})
2534 @deftypefun void gtk_menu_prepend (GtkMenu *@var{menu}, GtkWidget *@var{child})
2537 @deftypefun void gtk_menu_insert (GtkMenu *@var{menu}, GtkWidget *@var{child}, gint @var{position})
2540 @deftypefun void gtk_menu_popup (GtkMenu *@var{menu}, GtkWidget *@var{parent_menu_shell}, GtkWidget *@var{parent_menu_item}, GtkMenuPositionFunc @var{func}, gpointer @var{data}, gint @var{button})
2543 @deftypefun void gtk_menu_popdown (GtkMenu *@var{menu})
2546 @deftypefun GtkWidget* gtk_menu_get_active (GtkMenu *@var{menu})
2549 @deftypefun void gtk_menu_set_active (GtkMenu *@var{menu})
2552 @deftypefun void gtk_menu_set_accelerator_table (GtkMenu *@var{menu}, GtkAcceleratorTable *@var{table})
2555 @gtkstdmacros{Menu, MENU}
2559 @node GtkMenuBar, GtkMenuItem, GtkMenu, Widgets
2560 @comment node-name, next, previous, up
2561 @section The menu bar widget
2563 @subsection Description
2572 @subsection Functions
2574 @deftypefun guint gtk_menu_bar_get_type (void)
2575 Returns the @code{GtkMenuBar} type identifier.
2578 @deftypefun GtkWidget* gtk_menu_bar_new (void)
2579 Create a new @code{GtkMenuBar} object returning the new widget as a pointer
2580 to a @code{GtkWidget} object. @code{NULL} is returned on failure.
2583 @deftypefun void gtk_menu_bar_append (GtkMenuBar *@var{menu_bar}, GtkWidget *@var{child})
2586 @deftypefun void gtk_menu_bar_prepend (GtkMenuBar *@var{menu_bar}, GtkWidget *@var{child})
2589 @deftypefun void gtk_menu_bar_insert (GtkMenuBar *@var{menu_bar}, GtkWidget *@var{child}, gint @var{position})
2592 @gtkstdmacros{MenuBar, MENU_BAR}
2596 @node GtkMenuItem, GtkMenuShell, GtkMenuBar, Widgets
2597 @comment node-name, next, previous, up
2598 @section The menu item widget
2601 @subsection Description
2607 @deftypefn Signal void GtkMenuItem::activate (GtkMenuItem *@var{menu_item})
2610 @subsection Functions
2612 @deftypefun guint gtk_menu_item_get_type (void)
2613 Returns the @code{GtkMenuItem} type identifier.
2616 @deftypefun GtkWidget* gtk_menu_item_new (void)
2617 Create a new @code{GtkMenuItem} object returning the new widget as a pointer
2618 to a @code{GtkWidget} object. @code{NULL} is returned on failure.
2621 @deftypefun GtkWidget* gtk_menu_item_new_with_label (gchar *@var{label})
2622 Create a new @code{GtkMenuItem} object initilizing it with the value in
2623 @var{label}. The new widget is returned as a pointer to a @code{GtkWidget}
2624 object. @code{NULL} is returned on failure.
2627 @deftypefun void gtk_menu_item_set_submenu (GtkMenuItem *@var{menu_item}, GtkWidget *@var{submenu})
2630 @deftypefun void gtk_menu_item_set_placement (GtkMenuItem *@var{menu_item}, GtkSubmenuPlacement @var{placement})
2633 @deftypefun void gtk_menu_item_accelerator_size (GtkMenuItem *@var{menu_item})
2636 @deftypefun void gtk_menu_item_accelerator_text (GtkMenuItem *@var{menu_item}, gchar *@var{buffer})
2639 @deftypefun void gtk_menu_item_configure (GtkMenuItem *@var{menu_item}, gint @var{show_toggle_indicator}, gint @var{show_submenu_indicator})
2642 @deftypefun void gtk_menu_item_select (GtkMenuItem *@var{menu_item})
2645 @deftypefun void gtk_menu_item_deselect (GtkMenuItem *@var{menu_item})
2648 @deftypefun void gtk_menu_item_activate (GtkMenuItem *@var{menu_item})
2651 @gtkstdmacros{MenuItem, MENU_ITEM}
2655 @node GtkMenuShell, GtkMisc, GtkMenuItem, Widgets
2656 @comment node-name, next, previous, up
2657 @section The menu shell widget
2660 @subsection Description
2666 @deftypefn Signal void GtkMenuShell::deactivate (GtkMenuShell *@var{menu_shell})
2669 @subsection Functions
2671 @deftypefun guint gtk_menu_shell_get_type (void)
2672 Returns the @code{GtkMenuShell} type identifier.
2675 @deftypefun void gtk_menu_shell_append (GtkMenuShell *@var{menu_shell}, GtkWidget *@var{child})
2678 @deftypefun void gtk_menu_shell_prepend (GtkMenuShell *@var{menu_shell}, GtkWidget *@var{child})
2681 @deftypefun void gtk_menu_shell_insert (GtkMenuShell *@var{menu_shell}, GtkWidget *@var{child}, gint @var{position})
2684 @deftypefun void gtk_menu_shell_deactivate (GtkMenuShell *@var{menu_shell})
2687 @gtkstdmacros{MenuShell, MENU_SHELL}
2691 @node GtkMisc, GtkNotebook, GtkMenuShell, Widgets
2692 @comment node-name, next, previous, up
2693 @section The misc widget
2695 @subsection Description
2713 @subsection Functions
2715 @deftypefun guint gtk_misc_get_type (void)
2716 Returns the @code{GtkMisc} type identifier.
2719 @deftypefun void gtk_misc_set_alignment (GtkMisc *@var{misc}, gfloat @var{xalign}, gfloat @var{yalign})
2722 @deftypefun void gtk_misc_set_padding (GtkMisc *@var{misc}, gint @var{xpad}, gint @var{ypad})
2725 @gtkstdmacros{Misc, MISC}
2729 @node GtkNotebook, GtkOptionMenu, GtkMisc, Widgets
2730 @comment node-name, next, previous, up
2731 @section The notebook widget
2733 @subsection Description
2739 @subsection Functions
2741 @deftypefun guint gtk_notebook_get_type (void)
2742 Returns the @code{GtkNotebook} type identifier.
2745 @deftypefun GtkWidget* gtk_notebook_new (void)
2746 Create a new @code{GtkNotebook} object returning the new widget as a pointer
2747 to a @code{GtkWidget} object. @code{NULL} is returned on a failure.
2750 @deftypefun void gtk_notebook_append_page (GtkNotebook *@var{notebook}, GtkWidget *@var{child}, GtkWidget *@var{tab_label})
2753 @deftypefun void gtk_notebook_prepend_page (GtkNotebook *@var{notebook}, GtkWidget *@var{child}, GtkWidget *@var{tab_label})
2756 @deftypefun void gtk_notebook_insert_page (GtkNotebook *@var{notebook}, GtkWidget *@var{child}, GtkWidget *@var{tab_label}, gint @var{position})
2759 @deftypefun void gtk_notebook_remove_page (GtkNotebook *@var{notebook}, gint @var{page_num})
2762 @deftypefun void gtk_notebook_set_page (GtkNotebook *@var{notebook}, gint @var{page_num})
2765 @deftypefun void gtk_notebook_next_page (GtkNotebook *@var{notebook})
2768 @deftypefun void gtk_notebook_prev_page (GtkNotebook *@var{notebook})
2771 @deftypefun void gtk_notebook_set_tab_pos (GtkNotebook *@var{notebook}, GtkPositionType @var{pos})
2774 @deftypefun void gtk_notebook_set_show_tabs (GtkNotebook *@var{notebook}, gint @var{show_tabs})
2777 @deftypefun void gtk_notebook_set_show_border (GtkNotebook *@var{notebook}, gint @var{show_border})
2780 @gtkstdmacros{Notebook, NOTEBOOK}
2784 @node GtkOptionMenu, GtkPaned, GtkNotebook, Widgets
2785 @comment node-name, next, previous, up
2786 @section The option menu widget
2788 @subsection Description
2797 @subsection Functions
2799 @deftypefun guint gtk_option_menu_get_type (void)
2800 Returns the @code{GtkOptionMenu} type identifier.
2803 @deftypefun GtkWidget* gtk_option_menu_new (void)
2804 Create a new @code{GtkOptionMenu} object returning the new widget as a
2805 pointer to a @code{GtkWidget} object. @code{NULL} is returned on failure.
2808 @deftypefun GtkWidget* gtk_option_menu_get_menu (GtkOptionMenu *@var{option_menu})
2811 @deftypefun void gtk_option_menu_set_menu (GtkOptionMenu *@var{option_menu}, GtkWidget *@var{menu})
2814 @deftypefun void gtk_option_menu_remove_menu (GtkOptionMenu *@var{option_menu})
2817 @deftypefun void gtk_option_menu_set_history (GtkOptionMenu *@var{option_menu}, gint @var{index})
2820 @gtkstdmacros{OptionMenu, OPTION_MENU}
2823 @node GtkPaned, GtkPixmap, GtkOptionMenu, Widgets
2824 @comment node-name, next, previous, up
2825 @section The paned widget
2827 @subsection Description
2833 @subsection Functions
2835 @deftypefun guint gtk_paned_get_type (void)
2836 Returns the @code{GtkPaned} type identifier.
2839 @deftypefun void gtk_paned_add1 (GtkPaned *@var{paned}, GtkWidget *@var{child})
2842 @deftypefun void gtk_paned_add2 (GtkPaned *@var{paned}, GtkWidget *@var{child})
2845 @deftypefun void gtk_paned_handle_size (GtkPaned *@var{paned}, guint16 @var{size})
2849 @deftypefun void gtk_paned_gutter_size (GtkPaned *@var{paned}, guint16 @var{size})
2852 @gtkstdmacros{Paned, PANED}
2855 @node GtkPixmap, GtkPreview, GtkPaned, Widgets
2856 @comment node-name, next, previous, up
2857 @section The pixmap widget
2860 @subsection Description
2866 @subsection Functions
2868 @deftypefun guint gtk_pixmap_get_type (void)
2869 Returns the @code{GtkPixmap} type identifier.
2872 @deftypefun GtkWidget* gtk_pixmap_new (GdkPixmap *@var{normal}, GdkPixmap *@var{active}, GdkPixmap *@var{prelight}, GdkPixmap *@var{selected}, GdkPixmap *@var{insensitive})
2875 @deftypefun void gtk_pixmap_set (GtkPixmap *@var{pixmap}, GdkPixmap *@var{val}, GtkStateType @var{state})
2878 @deftypefun void gtk_pixmap_get (GtkPixmap *@var{pixmap}, GdkPixmap **@var{val}, GtkStateType @var{state})
2881 @gtkstdmacros{Pixmap, PIXMAP}
2885 @node GtkPreview, GtkProgressBar, GtkPixmap, Widgets
2886 @comment node-name, next, previous, up
2887 @section The preview widget
2889 @subsection Description
2904 @subsection Functions
2906 @deftypefun guint gtk_preview_get_type (void)
2907 Returns the @code{GtkPreview} type identifier.
2910 @deftypefun void gtk_preview_uninit (void)
2913 @deftypefun GtkWidget* gtk_preview_new (GtkPreviewType @var{type})
2914 Create a new @code{GtkPreview} object initilizing it with the values in
2915 @var{type}. The new widget is returned as a pointer to a @code{GtwWidget}
2916 object. @code{NULL} is returned on failure.
2919 @deftypefun void gtk_preview_size (GtkPreview *@var{preview}, gint @var{width}, gint @var{height})
2920 Set the size of the @var{preview} object to @var{width} and @var{height}.
2923 @deftypefun void gtk_preview_put (GtkPreview *@var{preview}, GdkWindow *@var{window}, GdkGC *@var{gc}, gint @var{srcx}, gint @var{srcy}, gint @var{destx}, gint @var{desty}, gint @var{width}, gint @var{height})
2926 @deftypefun void gtk_preview_put_row (GtkPreview *@var{preview}, guchar *@var{src}, guchar *@var{dest}, gint @var{x}, gint @var{y}, gint @var{w})
2929 @deftypefun void gtk_preview_draw_row (GtkPreview *@var{preview}, guchar @var{data}, gint @var{x}, gint @var{y}, gint @var{w})
2932 @deftypefun void gtk_preview_set_expand (GtkPreview *@var{preview}, gint @var{expand})
2935 @deftypefun void gtk_preview_set_gamma (double @var{gamma})
2938 @deftypefun void gtk_preview_set_color_cube (guint @var{nred_shades}, guint @var{ngreen_shades}, guint @var{nblue_shades}, guint @var{ngray_shades})
2941 @deftypefun void gtk_preview_set_install_cmap (gint @var{install_cmap})
2944 @deftypefun void gtk_preview_set_reserved (gint @var{nreserved})
2947 @deftypefun GdkVisual* gtk_preview_get_visual (void)
2950 @deftypefun GdkColormap* gtk_preview_get_cmap (void)
2953 @deftypefun GtkPreviewInfo* gtk_preview_get_info (void)
2956 @gtkstdmacros{Preview, PREVIEW}
2960 @node GtkProgressBar, GtkRadioButton, GtkPreview, Widgets
2961 @comment node-name, next, previous, up
2962 @section The progress bar widget
2965 @subsection Description
2974 @subsection Functions
2976 @deftypefun guint gtk_progress_bar_get_type (void)
2977 Returns the @code{GtkProgressBar} type identifier.
2980 @deftypefun GtkWidget* gtk_progress_bar_new (void)
2981 Create a new @code{GtkProgressBar} object returning the new widget as a
2982 pointer to a @code{GtkWidget} object. @code{NULL} is returned on failure.
2985 @deftypefun void gtk_progress_bar_update (GtkProgressBar *@var{pbar}, gfloat @var{percentage})
2986 Cause the @code{GtkProgessBar} to update its visual apperance to reflect the
2990 @gtkstdmacros{ProgressBar, PROGRESS_BAR}
2994 @node GtkRadioButton, GtkRadioMenuItem, GtkProgressBar, Widgets
2995 @comment node-name, next, previous, up
2996 @section The radio button widget
2998 @subsection Description
3010 @subsection Functions
3012 @deftypefun guint gtk_radio_button_get_type (void)
3013 Returns the @code{GtkRadioButton} type identifier.
3016 @deftypefun GtkWidget* gtk_radio_button_new (GSList *@var{group})
3017 Create a new @code{GtkRadioButton} object initilizing it with the value
3018 in the @var{group} argument. The new widget is returned as a pointer to a
3019 @code{GtkWidget} object. @code{NULL} is returned on failure.
3022 @deftypefun GtkWidget* gtk_radio_button_new_with_label (GSList *@var{group}, gchar *@var{label})
3023 Create a new @code{GtkRadioButton} object initilizing it with the values in
3024 the @var{group} and @var{label} arguments. The new widget is returned as a
3025 pointer to @code{GtkWidget} object. @code{NULL} is returned on failure.
3028 @deftypefun GSList* gtk_radio_button_group (GtkRadioButton *@var{radio_button})
3031 @gtkstdmacros{RadioButton, RADIO_BUTTON}
3035 @node GtkRadioMenuItem, GtkRange, GtkRadioButton, Widgets
3036 @comment node-name, next, previous, up
3037 @section The radio button widget
3040 @subsection Description
3052 @subsection Functions
3054 @deftypefun guint gtk_radio_menu_item_get_type (void)
3055 Returns the @code{GtkRadioMenuItem} type identifier.
3058 @deftypefun GtkWidget* gtk_radio_menu_item_new (GSList *@var{group})
3059 Create a new @code{GtkRadioMenuItem} object and initilize it with the
3060 values in @var{group}. The new widget is returned as a pointer to a
3061 @code{GtkWidget} object. @code{NULL} is returned on failure.
3064 @deftypefun GtkWidget* gtk_radio_menu_item_new_with_label (GSList *@var{group}, gchar *@var{label})
3067 @deftypefun GSList* gtk_radio_menu_item_group (GtkRadioMenuItem *@var{radio_menu_item})
3070 @gtkstdmacros{RadioMenuItem, RADIO_MENU_ITEM}
3074 @node GtkRange, GtkRuler, GtkRadioMenuItem, Widgets
3075 @comment node-name, next, previous, up
3076 @section The range widget
3078 @subsection Description
3084 @subsection Functions
3086 @deftypefun guint gtk_range_get_type (void)
3087 Returns the @code{GtkRange} type identifier.
3090 @deftypefun GtkAdjustment* gtk_range_get_adjustment (GtkRange *@var{range})
3093 @deftypefun void gtk_range_set_update_policy (GtkRange *@var{range}, GtkUpdatePolicy @var{policy})
3096 @deftypefun void gtk_range_set_adjustment (GtkRange *@var{range}, GtkAdjustment *@var{adjustment})
3099 @deftypefun void gtk_range_draw_background (GtkRange *@var{range})
3102 @deftypefun void gtk_range_draw_trough (GtkRange *@var{range})
3105 @deftypefun void gtk_range_draw_slider (GtkRange *@var{range})
3108 @deftypefun void gtk_range_draw_step_forw (GtkRange *@var{range})
3111 @deftypefun void gtk_range_draw_step_back (GtkRange *@var{range})
3114 @deftypefun void gtk_range_slider_update (GtkRange *@var{range})
3117 @deftypefun gint gtk_range_trough_click (GtkRange *@var{range}, gint @var{x}, gint @var{y})
3120 @deftypefun void gtk_range_default_hslider_update (GtkRange *@var{range})
3123 @deftypefun void gtk_range_default_vslider_update (GtkRange *@var{range})
3126 @deftypefun gint gtk_range_default_htrough_click (GtkRange *@var{range}, gint @var{x}, gint @var{y})
3129 @deftypefun gint gtk_range_default_vtrough_click (GtkRange *@var{range}, gint @var{x}, gint @var{y})
3132 @deftypefun void gtk_range_default_hmotion (GtkRange *@var{range}, gint @var{xdelta}, gint @var{ydelta})
3135 @deftypefun void gtk_range_default_vmotion (GtkRange *@var{range}, gint @var{xdelta}, gint @var{ydelta})
3138 @deftypefun gfloat gtk_range_calc_value (GtkRange *@var{ragne}, gint @var{position})
3141 @gtkstdmacros{Range, RANGE}
3145 @node GtkRuler, GtkScale, GtkRange, Widgets
3146 @comment node-name, next, previous, up
3147 @section The ruler widget
3149 @subsection Description
3170 @subsection Functions
3172 @deftypefun guint gtk_ruler_get_type (void)
3173 Returns the @code{GtkRuler} type identifier.
3176 @deftypefun void gtk_ruler_set_metric (GtkRuler *@var{ruler}, GtkMetricType @var{metric})
3179 @deftypefun void gtk_ruler_set_range (GtkRuler *@var{ruler}, gfloat @var{lower}, gfloat @var{upper}, gfloat @var{position}, gfloat @var{max_size})
3182 @deftypefun void gtk_ruler_draw_ticks (GtkRuler *@var{ruler})
3185 @deftypefun void gtk_ruler_draw_pos (GtkRuler *@var{ruler})
3188 @gtkstdmacros{Ruler, RULER}
3192 @node GtkScale, GtkScrollbar, GtkRuler, Widgets
3193 @comment node-name, next, previous, up
3194 @section The scale widget
3197 @subsection Description
3212 @subsection Functions
3214 @deftypefun guint gtk_scale_get_type (void)
3215 Returns the @code{GtkScale} type identifier.
3218 @deftypefun void gtk_scale_set_digits (GtkScale *@var{scale}, gint @var{digits})
3221 @deftypefun void gtk_scale_set_draw_value (GtkScale *@var{scale}, gint @var{draw_value})
3224 @deftypefun void gtk_scale_set_value_pos (GtkScale *@var{scale}, gint @var{pos})
3227 @deftypefun gint gtk_scale_value_width (GtkScale *@var{scale})
3230 @deftypefun void gtk_scale_draw_value (GtkScale *@var{scale})
3233 @gtkstdmacros{Scale, SCALE}
3237 @node GtkScrollbar, GtkScrolledWindow, GtkScale, Widgets
3238 @comment node-name, next, previous, up
3239 @section The scrollbar widget
3242 @subsection Description
3248 @subsection Functions
3250 @deftypefun guint gtk_scrollbar_get_type (void)a
3251 Returns the @code{GtkScrollbar} type identifier.
3254 @gtkstdmacros{Scrollbar, SCROLLBAR}
3258 @node GtkScrolledWindow, GtkSeparator, GtkScrollbar, Widgets
3259 @comment node-name, next, previous, up
3260 @section The scrolled window widget
3263 @subsection Description
3269 @subsection Functions
3271 @deftypefun guint gtk_scrolled_window_get_type (void)
3272 Returns the @code{GtkScrolledWindow} type identifier.
3275 @deftypefun GtkWidget* gtk_scrolled_window_new (GtkAdjustment *@var{hadjustment}, GtkAdjustment *@var{vadjustment})
3276 Create a new @code{GtkScrolledWindow} object initilizing it with the values in
3277 @var{adjustment} and @var{adjustment}. The new widget is returned as a
3278 pointer to a @code{GtkWidget} object. @code{NULL} is returned on failure.
3281 @deftypefun GtkAdjustment* gtk_scrolled_window_get_hadjustment (GtkScrolledWindow *@var{scrolled_window})
3284 @deftypefun GtkAdjustment* gtk_scrolled_window_get_vadjustment (GtkScrolledWindow *@var{scrolled_window})
3287 @deftypefun void gtk_scrolled_window_set_policy (GtkScrolledWindow *@var{scrolled_window}, GtkPolicyType @var{hscrollbar_policy}, GtkPolicyType @var{vscrollbar_policy})
3290 @gtkstdmacros{ScrolledWindow, SCROLLED_WINDOW}
3294 @node GtkSeparator, GtkStatusbar, GtkScrolledWindow, Widgets
3295 @comment node-name, next, previous, up
3296 @section The separator widget
3299 @subsection Description
3305 @subsection Functions
3307 @deftypefun guint gtk_separator_get_type (void)
3308 Returns the @code{GtkSeparator} type identifier.
3311 @gtkstdmacros{Separator, SEPARATOR}
3314 @node GtkStatusbar, GtkTable, GtkSeparator, Widgets
3315 @comment node-name, next, previous, up
3316 @section The statusbar widget
3318 @subsection Description
3324 @subsection Functions
3326 @deftypefun guint gtk_statusbar_get_type (void)
3327 Returns the @code{GtkStatusbar} type identifier.
3330 @deftypefun GtkWidget* gtk_statusbar_new (void)
3331 Create a new @code{GtkStatusbar} object returning the new widget as a pointer
3332 to a @code{GtkWidget} object. @code{NULL} is returned on failure.
3335 @deftypefun gint gtk_statusbar_push (GtkStatusbar *@var{statusbar}, gchar *@var{text})
3338 @deftypefun void gtk_statusbar_pop (GtkStatusbar *@var{statusbar}, gint @var{ststusid})
3341 @gtkstdmacros{Statusbar, STATUSBAR}
3344 @node GtkTable, GtkText, GtkStatusbar, Widgets
3345 @comment node-name, next, previous, up
3346 @section The table widget
3348 @subsection Description
3359 This option controls whether all child widgets in the @code{GtkTable} will
3360 be of the same size. The child widgets will be the size of the largest child.
3365 @subsection Functions
3367 @deftypefun guint gtk_table_get_type (void)
3368 Returns the @code{GtkTable} type identifier.
3371 @deftypefun GtkWidget* gtk_table_new (gint @var{rows}, gint @var{columns}, gint @var{homogeneous})
3372 Create a new @code{GtkTable} object initilizing it with the values in
3373 @var{rows}, @var{columns} and @var{homogeneous}. The new widget is returned
3374 as a pointer to a @code{GtkWidget}. @code{NULL} is returned on failure.
3377 @deftypefun void gtk_table_attach (GtkTable *@var{table}, GtkWidget *@var{child}, gint @var{left_attach}, gint @var{right_attach}, gint @var{top_attach}, gint @var{bottom_attach}, gint @var{xoptions}, gint @var{yoptions}, gint @var{xpadding}, gint @var{ypadding})
3380 @deftypefun void gtk_table_attach_defaults (GtkTable *@var{table}, GtkWidget *@var{widget}, gint @var{left_attach}, gint @var{right_attach}, gint @var{top_attach}, gint @var{bottom_attach})
3383 @deftypefun void gtk_table_set_row_spacing (GtkTable *@var{table}, gint @var{row}, gint @var{spacing})
3386 @deftypefun void gtk_table_set_col_spacing (GtkTable *@var{table}, gint @var{col}, gint @var{spacing})
3389 @deftypefun void gtk_table_set_row_spacings (GtkTable *@var{table}, gint @var{spacing})
3392 @deftypefun void gtk_table_set_col_spacings (GtkTable *@var{table}, gint @var{spacing})
3395 @gtkstdmacros{Table, TABLE}
3399 @node GtkText, GtkToggleButton, GtkTable, Widgets
3400 @comment node-name, next, previous, up
3401 @section The text widget
3404 @subsection Description
3408 @subsection Functions
3410 @deftypefun guint gtk_text_get_type (void)
3411 Returns the @code{GtkText} type identifier.
3414 @deftypefun GtkWidget* gtk_text_new (GtkAdjustment *@var{hadj}, GtkAdjustment *@var{vadj});
3415 Create a new @code{GtkText} object initilizing it with the values in
3416 @var{hadj} and @var{vadj}. The new widget is returned as a pointer to a
3417 @code{GtkWidget}. @code{NULL} is returned on failure.
3420 @deftypefun void gtk_text_set_editable (GtkText *@var{text}, gint @var{editable})
3423 @deftypefun void gtk_text_set_adjustments (GtkText *@var{text}, GtkAdjustment *@var{hadj}, GtkAdjustment *@var{vadj})
3426 @deftypefun void gtk_text_set_point (GtkText *@var{text}, guint @var{index})
3429 @deftypefun guint gtk_text_get_point (GtkText *@var{text})
3432 @deftypefun guint gtk_text_get_length (GtkText *@var{text})
3435 @deftypefun void gtk_text_freeze (GtkText *@var{text})
3438 @deftypefun void gtk_text_thaw (GtkText *@var{text})
3441 @deftypefun void gtk_text_insert (GtkText *@var{text}, GdkFont *@var{font}, GdkColor *@var{fore}, GdkColor *@var{back}, char *@var{chars}, gint @var{length})
3444 @deftypefun gint gtk_text_forward_delete (GtkText *@var{text}, guint @var{nchars})
3447 @deftypefun gint gtk_text_backward_delete (GtkText *@var{text}, guint @var{nchars})
3451 @gtkstdmacros{Text, TEXT}
3455 @node GtkToggleButton, GtkToolbar, GtkText, Widgets
3456 @comment node-name, next, previous, up
3457 @section The toggle button widget
3460 @subsection Description
3469 @deftypefn Signal void GtkToggleButton::toggled (GtkToggleButton *@var{toggle_button})
3472 @subsection Functions
3474 @deftypefun guint gtk_toggle_button_get_type (void)
3475 Returns the @code{GtkToggleButton} type identifier.
3478 @deftypefun GtkWidget* gtk_toggle_button_new (void)
3479 Create a new @code{GtkToggleButton} object returning the new widget as a
3480 pointer to a @code{GtkWidget} object. @code{NULL} is returned on failure.
3483 @deftypefun GtkWidget* gtk_toggle_button_new_with_label (gchar *@var{label})
3484 Create a new @code{GtkToggleButton} object initilizing it with the values in
3485 @var{label}. The new widget is returned as a pointer to a @code{GtkWidget}
3486 object. @code{NULL} is returned on failure.
3489 @deftypefun void gtk_toggle_button_set_mode (GtkToggleButton *@var{toggle_button}, gint @var{draw_indicator})
3492 @deftypefun void gtk_toggle_button_set_state (GtkToggleButton *@var{toggle_button}, gint @var{state})
3495 @deftypefun void gtk_toggle_button_toggled (GtkToggleButotn *@var{toggle_button})
3498 @gtkstdmacros{ToggleButton, TOGGLE_BUTTON}
3502 @node GtkToolbar, GtkTooltips, GtkToggleButton, Widgets
3503 @comment node-name, next, previous, up
3504 @section The tool bar widget
3506 @subsection Description
3512 @item GTK_ORIENTATION_HORIZONTAL
3514 @item GTK_ORIENTATION_VERTICAL
3520 @item GTK_TOOLBAR_ICONS
3521 @item GTK_TOOLBAR_TEXT
3522 @item GTK_TOOLBAR_BOTH
3531 @subsection Functions
3533 @deftypefun guint gtk_toolbar_get_type (void)
3534 Returns the @code{GtkToolbar} type identifier.
3537 @deftypefun GtkWidget* gtk_toolbar_new (GtkOrientation @var{orientation}, GtkToolbarStyle @var{style})
3538 Create a new @code{GtkToolbar} object initilizing it with the values
3539 @var{orientation} and @var{style}. @code{NULL} is returned on failure.
3542 @deftypefun void gtk_toolbar_append_item (GtkToolbar *@var{toolbar}, char *@var{text}, char *@var{tooltip_text}, GtkPixmap *@var{icon}, GtkSignalFunc @var{callback}, gpointer @var{user_data})
3545 @deftypefun void gtk_toolbar_prepend_item (GtkToolbar *@var{toolbar}, char *@var{text}, char *@var{tooltip_text}, GtkPixmap *@var{icon}, GtkSignalFunc @var{callback}, gpointer @var{user_data})
3548 @deftypefun void gtk_toolbar_insert_item (GtkToolbar *@var{toolbar}, char *@var{text}, char *@var{tooltip_text}, GtkPixmap *@var{icon}, GtkSignalFunc @var{callback}, gpointer @var{user_data}, gint @var{position})
3551 @deftypefun void gtk_toolbar_append_space (GtkToolbar *@var{toolbar})
3554 @deftypefun void gtk_toolbar_prepend_space (GtkToolbar *@var{toolbar})
3557 @deftypefun void gtk_toolbar_insert_space (GtkToolbar *@var{toolbar}, gint @var{position})
3560 @deftypefun void gtk_toolbar_set_orientation (GtkToolbar *@var{toolbar}, GtkOrientation @var{orientation})
3563 @deftypefun void gtk_toolbar_set_style (GtkToolbar *@var{toolbar}, GtkToolbarStyle @var{style})
3564 Set the @var{style} of the @var{toolbar} to @var{style}.
3567 @deftypefun void gtk_toolbar_set_space_size (GtkToolbar *@var{toolbar}, gint @var{space_size})
3570 @deftypefun void gtk_toolbar_set_tooltips (GtkToolbar *@var{toolbar}, gint @var{enable})
3574 @gtkstdmacros{Toolbar, TOOLBAR}
3578 @node GtkTooltips, GtkTree, GtkToolbar, Widgets
3579 @comment node-name, next, previous, up
3580 @section The tool tips widget
3582 @subsection Description
3588 @subsection Functions
3590 @deftypefun GtkTooltips* gtk_tooltips_new (void)
3591 Create a new @code{GtkTooltips} object returning the new widget as a
3592 pointer to a @code{GtkWidget} object. @code{NULL} is returned on failure.
3595 @deftypefun GtkTooltips* gtk_tooltips_ref (GtkTooltips *@var{tooltips})
3598 @deftypefun void gtk_tooltips_unref (GtkTooltips *@var{tooltips})
3601 @deftypefun void gtk_tooltips_free_string (gpointer @var{data}, gpointer @var{user_data})
3604 @deftypefun void gtk_tooltips_enable (GtkTooltips *@var{tooltips})
3607 @deftypefun void gtk_tooltips_disable (GtkTooltips *@var{tooltips})
3610 @deftypefun void gtk_tooltips_set_delay (GtkTooltips *@var{tooltips}, GtkWidget *@var{widget}, gchar *@var{tips_text})
3613 @deftypefun void gtk_tooltips_set_colors (GtkTooltips *@var{tooltips}, GdkColor *@var{background}, GdkColor *@var{foreground})
3617 @gtkstdmacros{Tooltips, TOOLTIPS}
3621 @node GtkTree, GtkTreeItem, GtkTooltips, Widgets
3622 @comment node-name, next, previous, up
3623 @section The tree widget
3626 @subsection Description
3632 @subsection Functions
3634 @deftypefun guint gtk_tree_get_type (void)
3635 Returns the @code{GtkTree} type identifier.
3638 @deftypefun GtkWidget* gtk_tree_new (void)
3639 Create a new @code{GtkTree} object returning the new widget as a pointer to
3640 a @code{GtkWidget} object. @code{NULL} is returned on failure.
3643 @deftypefun void gtk_tree_append (GtkTree *@var{tree}, GtkWidget *@var{child})
3646 @deftypefun void gtk_tree_prepend (GtkTree *@var{tree}, GtkWidget *@var{child})
3649 @deftypefun void gtk_tree_insert (GtkTree *@var{tree}, GtkWidget *@var{child}, gint @var{position})
3652 @deftypefun gint gtk_tree_child_position (GtkTree *@var{tree}, GtkWidget *@var{child})
3655 @deftypefun void gtk_tree_clear_items (GtkTree *@var{tree}, gint @var{start}, gint @var{end})
3658 @deftypefun void gtk_tree_remove_items (GtkTree *@var{tree}, GList *@var{items})
3661 @deftypefun void gtk_tree_select_child (GtkTree *@var{tree}, GtkWidget *@var{child})
3664 @deftypefun void gtk_tree_select_item (GtkTree *@var{tree}, gint @var{item})
3667 @deftypefun void gtk_tree_unselect_child (GtkTree *@var{tree}, GtkWidget *@var{child})
3670 @deftypefun void gtk_tree_unselect_item (GtkTree *@var{tree}, gint @var{item})
3673 @deftypefun void gtk_tree_set_selection_mode (GtkTree *@var{tree}, GtkSelectionMode @var{mode})
3676 @deftypefun void gtk_tree_set_view_mode (GtkTree *@var{tree}, GtkTreeViewMode @var{mode})
3679 @deftypefun void gtk_tree_set_view_lines (GtkTree *@var{tree}, guint @var{flag})
3683 @gtkstdmacros{Tree, TREE}
3687 @node GtkTreeItem, GtkVBox, GtkTree, Widgets
3688 @comment node-name, next, previous, up
3689 @section The tree item widget
3692 @subsection Description
3698 @subsection Functions
3700 @deftypefun guint gtk_tree_item_get_type (void)
3701 Returns the @code{GtkTreeItem} type identifier.
3704 @deftypefun GtkWidget* gtk_tree_item_new (void)
3705 Create a new @code{GtkTreeItem} object returning the new widget as a
3706 pointer to a @code{GtkWidget} object. @code{NULL} is returned on failure.
3709 @deftypefun GtkWidget* gtk_tree_item_new_with_label (gchar *@var{label})
3710 Create a new @code{GtkTreeItem} object initilizing it with the values in
3711 @var{label}. The new widget is returned as a pointer to a @code{GtkWidget}
3712 object. @code{NULL} is returned on failure.
3715 @deftypefun void gtk_tree_item_set_subtree (GtkTreeItem *@var{tree_item}, GtkWidget *@var{subtree})
3718 @deftypefun void gtk_tree_item_select (GtkTreeItem *@var{tree_item})
3721 @deftypefun void gtk_tree_item_deselect (GtkTreeItem *@var{tree_item})
3724 @deftypefun void gtk_tree_item_expand (GtkTreeItem *@var{tree_item})
3727 @deftypefun void gtk_tree_item_collapse (GtkTreeItem *@var{tree_item})
3730 @deftypefun void gtk_tree_item_remove_subtree (GtkTreeItem *@var{item})
3734 @gtkstdmacros{TreeItem, TREE_ITEM}
3737 @node GtkVBox, GtkVButtonBox, GtkTreeItem, Widgets
3738 @comment node-name, next, previous, up
3739 @section The vertical box widget
3742 @subsection Description
3747 This option controls whether each object in the box has the same size. In the
3748 case of the @code{GtkVBox}, this refers to the height. If this option is set
3749 then the @var{expand} option to the @code{gtk_box_pack} (@pxref{GtkBox})
3750 routines is always turned on.
3754 This option sets the amount of space that is added between the objects packed
3755 into this @code{GtkVBox} object.
3760 This widget does not define any new signals.
3762 @subsection Functions
3764 @deftypefun guint gtk_vbox_get_type (void)
3765 Returns the @code{GtkVBox} type identifier.
3768 @deftypefun GtkWidget* gtk_vbox_new (gint @var{homogeneous}, gint @var{spacing})
3769 Create a new @code{GtkVBox} object initilizing it with the values in
3770 @var{homogeneous} and @var{spacing}. The new widget is returned as a
3771 pointer to a @code{GtkWidget} object. @code{NULL} is returned on failure.
3774 @gtkstdmacros{VBox, VBOX}
3777 @node GtkVButtonBox, GtkViewport, GtkVBox, Widgets
3778 @comment node-name, next, previous, up
3779 @section The vertical button box widget
3782 @subsection Description
3793 @subsection Functions
3795 @deftypefun guint gtk_vbutton_box_get_type (void)
3796 Returns the @code{GtkVButtonBox} type identifier.
3799 @deftypefun GtkWidget* gtk_vbutton_box_new (void)
3800 Create a new @code{GtkVButtonBox} object returning the new widget as a
3801 pointer to a @code{GtkWidget} object. @code{NULL} is returned on failure.
3804 @deftypefun void gtk_vbutton_box_set_spacing_default (gint @var{spacing})
3807 @deftypefun void gtk_vbutton_box_set_layout_default (gint @var{layout})
3810 @deftypefun gint gtk_vbutton_box_get_spacing_default (void)
3813 @deftypefun gint gtk_vbutton_box_get_layout_default (void)
3816 @gtkstdmacros{VButtonBox, VBUTTON_BOX}
3820 @node GtkViewport, GtkVPaned, GtkVButtonBox, Widgets
3821 @comment node-name, next, previous, up
3822 @section The viewport widget
3825 @subsection Description
3829 @subsection Functions
3831 @deftypefun guint gtk_viewport_get_type (void)
3832 Returns the @code{GtkViewport} type identifier.
3835 @deftypefun GtkWidget* gtk_viewport_new (GtkAdjustment *@var{hadjustment}, GtkAdjustment *@var{vadjustment})
3838 @deftypefun GtkAdjustment* gtk_viewport_get_hadjustment (GtkViewport *@var{viewport})
3841 @deftypefun GtkAdjustment* gtk_viewport_get_vadjustment (GtkViewport *@var{viewport})
3844 @deftypefun void gtk_viewport_set_hadjustment (GtkViewport *@var{viewport}, GtkAdjustment *@var{adjustment})
3847 @deftypefun void gtk_viewport_set_vadjustment (GtkViewport *@var{viewport}, GtkAdjustment *@var{adjustment})
3850 @deftypefun void gtk_viewport_set_shadow_type (GtkViewport *@var{viewport}, GtkShadowType @var{type})
3853 @gtkstdmacros{Viewport, VIEWPORT}
3856 @node GtkVPaned, GtkVRuler, GtkViewport, Widgets
3857 @comment node-name, next, previous, up
3858 @section The vertical paned widget
3860 @subsection Description
3866 @subsection Functions
3868 @deftypefun guint gtk_vpaned_get_type (void)
3869 Returns the @code{GtkVPaned} type identifier.
3872 @deftypefun GtkWidget* gtk_vpaned_new (void)
3873 Create a new @code{GtkVPaned} object returning the new widget as a pointer
3874 to a @code{GtkWidget} object. @code{NULL} is returned on failure.
3877 @gtkstdmacros{VPaned, VPANED}
3880 @node GtkVRuler, GtkVScale, GtkVPaned, Widgets
3881 @comment node-name, next, previous, up
3882 @section The vertical ruler widget
3885 @subsection Description
3891 @subsection Functions
3893 @deftypefun guint gtk_vruler_get_type (void)
3894 Returns the @code{GtkVRuler} type identifier.
3897 @deftypefun GtkWidget* gtk_vruler_new (void)
3898 Create a new @code{GtkVRuler} object returning the new widget as a pointer to
3899 a @code{GtkWidget} object. @code{NULL} is returned on failure.
3902 @gtkstdmacros{VRuler, VRULER}
3906 @node GtkVScale, GtkVScrollbar, GtkVRuler, Widgets
3907 @comment node-name, next, previous, up
3908 @section The vertical ruler widget
3911 @subsection Description
3917 @subsection Functions
3919 @deftypefun guint gtk_vscale_get_type (void)
3920 Returns the @code{GtkVScale} type identifier.
3923 @deftypefun GtkWidget* gtk_vscale_new (GtkAdjustment *@var{adjustment})
3924 Create a new @code{GtkVScale} object returning the new widget as a pointer
3925 to a @code{GtkWidget} object. @code{NULL} is returned on failure.
3928 @gtkstdmacros{VScale, VSCALE}
3932 @node GtkVScrollbar, GtkVSeparator, GtkVScale, Widgets
3933 @comment node-name, next, previous, up
3934 @section The vertical scrollbar widget
3937 @subsection Description
3943 @subsection Functions
3945 @deftypefun guint gtk_vscrollbar_get_type (void)
3946 Returns the @code{GtkVScrollbar} type identifier.
3949 @deftypefun GtkWidget* gtk_vscrollbar_new (GtkAdjustment *@var{adjustment})
3950 Create a new @code{GtkVScrollbar} object initilizing it with the values in
3951 @var{adjusment}. The new widget is returned as a pointer to a @code{GtkWidget}
3952 object. @code{NULL} is returned on failure.
3955 @gtkstdmacros{VScrollbar, VSCROLLBAR}
3959 @node GtkVSeparator, GtkWidget, GtkVScrollbar, Widgets
3960 @comment node-name, next, previous, up
3961 @section The vertical separator widget
3964 @subsection Description
3968 @subsection Functions
3970 @deftypefun guint gtk_vseparator_get_type (void)
3971 Returns the @code{GtkVSeparator} type identifier.
3974 @deftypefun GtkWidget* gtk_vseparator_new (void)
3975 Create a new @code{GtkVSeparator} object and return the new widget as a
3976 pointer to a @code{GtkWidget} object. @code{NULL} is returned on failure.
3979 @gtkstdmacros{VSeparator, VSEPARATOR}
3983 @node GtkWidget, GtkWindow, GtkVSeparator, Widgets
3984 @comment node-name, next, previous, up
3985 @section The base widget
3988 @subsection Description
3992 @deftypefn Signal void GtkWidget::show (GtkWidget *@var{widget})
3995 @deftypefn Signal void GtkWidget::hide (GtkWidget *@var{widget})
3998 @deftypefn Signal void GtkWidget::map (GtkWidget *@var{widget})
4001 @deftypefn Signal void GtkWidget::unmap (GtkWidget *@var{widget})
4004 @deftypefn Signal void GtkWidget::realize (GtkWidget *@var{widget})
4007 @deftypefn Signal void GtkWidget::unrealize (GtkWidget *@var{widget})
4010 @deftypefn Signal void GtkWidget::draw (GtkWidget *@var{widget}, GdkRectangle *@var{area})
4013 @deftypefn Signal void GtkWidget::draw_focus (GtkWidget *@var{widget})
4016 @deftypefn Signal void GtkWidget::draw_default (GtkWidget *@var{widget})
4019 @deftypefn Signal void GtkWidget::size_request (GtkWidget *@var{widget}, GtkRequisition *@var{requisition})
4022 @deftypefn Signal void GtkWidget::size_allocate (GtkWidget *@var{widget}, GtkAllocation *@var{allocation})
4025 @deftypefn Signal void GtkWidget::state_changed (GtkWidget *@var{widget})
4028 @deftypefn Signal gint GtkWidget::install_accelerator (GtkWidget *@var{widget}, gchar *@var{signal_name}, gchar @var{key}, guint8 @var{modifiers})
4031 @deftypefn Signal void GtkWidget::remove_accelerator (GtkWidget *@var{widget}, gchar *@var{signal_name})
4034 @deftypefn Signal gint GtkWidget::event (GtkWidget *@var{widget}, GdkEvent *@var{event})
4037 @deftypefn Signal gint GtkWidget::button_press_event (GtkWidget *@var{widget}, GdkEventButton *@var{event})
4040 @deftypefn Signal gint GtkWidget::button_release_event (GtkWidget *@var{widget}, GdkEventButton *@var{event})
4043 @deftypefn Signal gint GtkWidget::motion_notify_event (GtkWidget *@var{widget}, GdkEventMotion *@var{event})
4046 @deftypefn Signal gint GtkWidget::delete_event (GtkWidget *@var{widget}, GdkEventAny *@var{event})
4049 @deftypefn Signal gint GtkWidget::destroy_event (GtkWidget *@var{widget}, GdkEventAny *@var{event})
4052 @deftypefn Signal gint GtkWidget::expose_event (GtkWidget *@var{widget}, GdkEventExpose *@var{event})
4055 @deftypefn Signal gint GtkWidget::key_press_event (GtkWidget *@var{widget}, GdkEventKey *@var{event})
4058 @deftypefn Signal gint GtkWidget::key_release_event (GtkWidget *@var{widget}, GdkEventKey *@var{event})
4061 @deftypefn Signal gint GtkWidget::enter_notify_event (GtkWidget *@var{widget}, GdkEventCrossing *@var{event})
4064 @deftypefn Signal gint GtkWidget::leave_notify_event (GtkWidget *@var{widget}, GdkEventCrossing *@var{event})
4067 @deftypefn Signal gint GtkWidget::configure_event (GtkWidget *@var{widget}, GdkEventConfigure *@var{event})
4070 @deftypefn Signal gint GtkWidget::focus_in_event (GtkWidget *@var{widget}, GdkEventFocus *@var{event})
4073 @deftypefn Signal gint GtkWidget::focus_out_event (GtkWidget *@var{widget}, GdkEventFocus *@var{event})
4076 @deftypefn Signal gint GtkWidget::map_event (GtkWidget *@var{widget}, GdkEventAny *@var{event})
4079 @deftypefn Signal gint GtkWidget::unmap_event (GtkWidget *@var{widget}, GdkEventAny *@var{event})
4082 @deftypefn Signal gint GtkWidget::property_notify_event (GtkWidget *@var{widget}, GdkEventProperty *@var{event})
4085 @deftypefn Signal gint GtkWidget::selection_clear_event (GtkWidget *@var{widget}, GdkEventSelection *@var{event})
4088 @deftypefn Signal gint GtkWidget::selection_request_event (GtkWidget *@var{widget}, GdkEventSelection *@var{event})
4091 @deftypefn Signal gint GtkWidget::selection_notify_event (GtkWidget *@var{widget}, GdkEventSelection *@var{event})
4094 @deftypefn Signal gint GtkWidget::drop_event (GtkWidget *@var{widget}, GdkEventDrop *@var{event})
4097 @deftypefn Signal gint GtkWidget::drag_begin_event (GtkWidget *@var{widget}, GdkEventDragBegin *@var{event})
4100 @deftypefn Signal gint GtkWidget::other_event (GtkWidget *@var{widget}, GdkEventOther *@var{event})
4103 @subsection Functions
4105 @deftypefun guint gtk_widget_get_type (void)
4106 Returns the @code{GtkWidget} type identifier.
4109 @deftypefun void gtk_widget_class_init (GtkWidgetClass *@var{class})
4112 @deftypefun void gtk_widget_init (GtkWidget *@var{widget})
4115 @deftypefun void gtk_widget_destroy (GtkWidget *@var{widget})
4118 @deftypefun void gtk_widget_show (GtkWidget *@var{widget})
4121 @deftypefun void gtk_widget_hide (GtkWidget *@var{widget})
4124 @deftypefun void gtk_widget_map (GtkWidget *@var{widget})
4127 @deftypefun void gtk_widget_unmap (GtkWidget *@var{widget})
4130 @deftypefun void gtk_widget_realize (GtkWidget *@var{widget})
4133 @deftypefun void gtk_widget_unrealize (GtkWidget *@var{widget})
4136 @deftypefun void gtk_widget_draw (GtkWidget *@var{widget}, GdkRectangle *@var{area})
4139 @deftypefun void gtk_widget_draw_focus (GtkWidget *@var{widget})
4142 @deftypefun void gtk_widget_draw_children (GtkWidget *@var{widget})
4145 @deftypefun void gtk_widget_size_request (GtkWidget *@var{widget}, GtkRequisition *@var{requisition})
4148 @deftypefun void gtk_widget_size_allocate (GtkWidget *@var{widget}, GtkAllocation *@var{allocation})
4151 @deftypefun void gtk_widget_install_accelerator (GtkWidget *@var{widget}, GtkAcceleratorTable *@var{table}, gchar *@var{signal_name}, gchar @var{key}, guint8 @var{modifiers})
4154 @deftypefun void gtk_widget_remove_accelerator (GtkWidget *@var{widget}, GtkAcceleratorTable *@var{table}, gchar *@var{signal_name})
4157 @deftypefun gint gtk_widget_event (GtkWidget *@var{widget}, GdkEvent *@var{event})
4160 @deftypefun void gtk_widget_reparent (GtkWidget *@var{widget}, GtkWidget *@var{new_parent})
4163 @deftypefun void gtk_widget_popup (GtkWidget *@var{widget}, gint @var{x}, gint @var{y})
4166 @deftypefun gint gtk_widget_intersect (GtkWidget *@var{widget}, GdkRectangle *@var{area}, GdkRectangle *@var{intersection})
4169 @deftypefun void gtk_widget_grab_focus (GtkWidget *@var{widget})
4172 @deftypefun void gtk_widget_grab_default (GtkWidget *@var{widget})
4175 @deftypefun void gtk_widget_restore_state (GtkWidget *@var{widget})
4178 @deftypefun void gtk_widget_set_name (GtkWidget *@var{widget}, gchar *@var{name})
4181 @deftypefun void gtk_widget_set_state (GtkWidget *@var{widget}, GtkStateType @var{state})
4184 @deftypefun void gtk_widget_set_sensitive (GtkWidget *@var{widget}, gint sensitive)
4187 @deftypefun void gtk_widget_set_parent (GtkWidget *@var{widget}, GtkWidget *@var{parent})
4190 @deftypefun void gtk_widget_set_style (GtkWidget *@var{widget}, GtkStyle *@var{style})
4193 @deftypefun void gtk_widget_set_uposition (GtkWidget *@var{widget}, gint @var{x}, gint @var{y})
4196 @deftypefun void gtk_widget_set_usize (GtkWidget *@var{widget}, gint @var{width}, gint @var{height})
4199 @deftypefun GtkWidget* gtk_widget_get_toplevel (GtkWidget *@var{widget})
4202 @deftypefun GtkWidget* gtk_widget_get_ancestor (GtkWidget *@var{widget}, gint @var{type})
4205 @deftypefun GdkColormap* gtk_widget_get_colormap (GtkWidget *@var{widget})
4208 @deftypefun GdkVisual* gtk_widget_get_visual (GtkWidget *@var{visual})
4211 @deftypefun GtkStyle* gtk_widget_get_style (GtkWidget *@var{style})
4214 @gtkstdmacros{Widget, WIDGET}
4218 @node GtkWindow, , GtkWidget, Widgets
4219 @comment node-name, next, previous, up
4220 @section The window widget
4223 @subsection Description
4228 The @var{type} options specify how this widget will interact with the
4229 window manager. Currently the following types and the effect they have
4230 on the window to window manager interaction is as follows.
4234 @code{GTK_WINDOW_TOPLEVEL}
4237 The option @code{GTK_WINDOW_TOPLEVEL} is usually used for the main application
4238 window that will remain for the entire application run.
4241 @code{GTK_WINDOW_DIALOG}
4244 The option @code{GTK_WINDOW_DIALOG} is usually used for transient
4245 windows. These windows will open up, gather some input or provide some
4246 application specific updates, then close. The window manager is free not
4247 to provide all the 'normal' window functions to this window.
4250 @code{GTK_WINDOW_POPUP}
4253 The option @code{GTK_WINDOW_POPUP} is usually used for transient windows.
4254 These windows are typically used for when no user interaction is required,
4255 to notify the user of some condition. Other uses for these types of windows
4256 are for 'about windows', startup windows and the like. Typically the window
4257 manager will @strong{not} provide the usual widgets that surround the
4258 window. At the most all that will be provided is a border. Also note that
4259 windows that set this @var{type} will not be in any window list of the window
4260 manager. Though this window will @strong{not} get the kill and close widgets
4261 of the window manager they still can recieve said events and should be
4268 The @var{title} option will set the title of the window in the window manager.
4269 @strong{Note:} On windows that have the @var{type} option set to
4270 @code{GTK_WINDOW_POPUP} there is a strong possiblity that this will text
4275 The @var{position} option will determine where the window will be displayed
4276 when it is finally drawn to the screen. Currently the following positions
4277 and the effect they have on window placement can be specified.
4282 @code{GTK_WIN_POS_NONE}
4285 This @var{position} type will allow the window manager full freedom, depending
4286 on the current settings in the window manager. As to where the window will
4290 @code{GTK_WIN_POS_CENTER}
4293 This @var{position} option will cause the window to center itself on the
4294 the screen. This option setting will take into account the @var{virtual screen}
4295 size when calculating the center. This is @strong{not} the same as the
4296 @var{virtual desktop} setting of many window managers. It will center itself
4297 on the current @var{virtual desktop}.
4300 @code{GTK_WIN_POS_MOUSE}
4302 This @var{position} option will cause the window to center itself under the
4303 mouse pointers' current location. Typical uses for this setting is in
4304 warning/error/informational dialogs where user interaction is desired.
4312 @deftypefn Signal void GtkWindow::move_resize (GtkWindow *@var{window}, gint *@var{x}, gint *@var{y}, gint @var{width}, gint @var{height})
4315 @deftypefn Signal void GtkWindow::set_focus (GtkWindow *@var{window}, GtkWidget *@var{focus})
4318 @subsection Functions
4320 @deftypefun guint gtk_window_get_type (void)
4321 Returns the @code{GtkWindow} type identifier.
4324 @deftypefun GtkWidget* gtk_window_new (GtkWindowType @var{type})
4325 Create a new @code{GtkWindow} object. The new widget is returned as a
4326 pointer to a @code{GtkWidget} object. @code{NULL} is returned on failure.
4327 The @var{type} can be one of @code{GTK_WINDOW_TOPLEVEL},
4328 @code{GTK_WINDOW_DIALOG} or, @code{GTK_WINDOW_POPUP}. The @var{type}
4329 value determines how this widget will interact with the window manager.
4332 @deftypefun void gtk_window_set_title (GtkWindow *@var{window}, gchar *@var{title})
4333 Set the title of this window to the text in the @var{title} argument. It is
4334 important to not set the fields of the @code{GtkWindow} structure directly.
4337 @deftypefun void gtk_window_set_focus (GtkWindow *@var{window}, GtkWidget *@var{focus})
4340 @deftypefun void gtk_window_set_default (GtkWindow *@var{window}, GtkWidget *@var{defaultw})
4343 @deftypefun void gtk_window_set_policy (GtkWindow *@var{window}, gint @var{allow_shrink}, gint @var{allow_grow}, gint @var{auto_shrink})
4346 @deftypefun void gtk_window_add_accelerator_table (GtkWindow *@var{window}, GtkAcceleratorTable *@var{table})
4349 @deftypefun void gtk_window_remove_accelerator_table (GtkWindow *@var{window}, GtkAcceleratorTable *@var{table})
4352 @deftypefun void gtk_window_position (GtkWindow *@var{window}, GtkWindowPosition @var{position})
4353 Set the position that the window will be at when it is finally drawn to the
4354 screen. The @var{position} argument effects the the position as described
4358 @gtkstdmacros{Window, WINDOW}
4361 @node Other Objects, Miscellaneous, Widgets, Top
4362 @comment node-name, next, previous, up
4363 @chapter Utility objects
4367 * GtkAcceleratorTable:: The accelerator table object.
4368 * GtkAdjustment:: The adjustment object.
4369 * GtkGC:: The GC object.
4370 * GtkData:: The data object.
4371 * GtkStyle:: The style object.
4375 @node GtkAcceleratorTable, GtkAdjustment, Other Objects, Other Objects
4376 @comment node-name, next, previous, up
4377 @section The accelerator table object
4379 @subsection Description
4381 @subsection Functions
4383 @deftypefun GtkAcceleratorTable* gtk_accelerator_table_new (void)
4386 @deftypefun GtkAcceleratorTable* gtk_accelerator_table_find (GtkObject *@var{object}, gchar *@var{signal_name}, guchar @var{accelerator_key}, guint8 @var{accelerator_mods})
4389 @deftypefun GtkAccelerator *gtk_accelerator_table_ref (GtkAcceleratorTable *@var{table})
4392 @deftypefun void gtk_accelerator_table_unref (GtkAcceleratorTable *@var{table})
4395 @deftypefun void gtk_accelerator_table_install (GtkAcceleratorTable *@var{table}, GtkObject *@var{object}, gchar *@var{signal_name}, guchar @var{accelerator_key}, guint8 @var{accelerator_mods})
4398 @deftypefun void gtk_accelerator_table_remove (GtkAcceleratorTable *@var{table}, GtkObject *@var{object}, gchar *@var{signal_name})
4401 @deftypefun void gtk_accelerator_table_check (GtkAcceleratorTable *@var{table}, guchar @var{accelerator_key}, guint8 @var{accelerator_mods})
4404 @deftypefun void gtk_accelerator_table_set_mod_mask (GtkAcceleratorTable *@var{table}, guint8 @var{modifier_mask})
4408 @node GtkAdjustment, GtkGC, GtkAcceleratorTable, Other Objects
4409 @comment node-name, next, previous, up
4410 @section The adjustment object
4412 @subsection Description
4414 @subsection Functions
4416 @deftypefun guint gtk_adjustment_get_type (void)
4417 Returns the @code{GtkAdjustment} type identifier.
4420 @deftypefun GtkObject* gtk_adjustment_new (gfloat @var{value}, gfloat @var{lower}, gfloat @var{upper}, gfloat @var{step_increment}, gfloat @var{page_increment}, gfloat @var{page_size})
4423 @gtkstdmacros{GtkAdjustment, ADJUSTMENT}
4426 @node GtkGC, GtkData, GtkAdjustment, Other Objects
4427 @section The GC object
4429 @subsection Description
4431 @subsection Functions
4433 @deftypefun GdkGC* gtk_gc_get (gint @var{depth}, GdkColormap *@var{colormap}, GdkGCValues *@var{values}, GdkGCValuesMask @var{values_mask})
4436 @deftypefun void gtk_gc_release (GdkGC *@var{gc})
4440 @node GtkData, GtkStyle, GtkGC, Other Objects
4441 @comment node-name, next, previous, up
4442 @section The data object
4444 @subsection Description
4446 @subsection Functions
4448 @deftypefun guint gtk_data_get_type (void)
4449 Returns the @code{GtkData} type identifier.
4452 @gtkstdmacros{Data, DATA}
4454 @node GtkStyle, ,GtkData, Other Objects
4455 @section The style object
4457 @subsection Description
4459 @subsection Functions
4462 @node Miscellaneous, Examples, Other Objects, Top
4463 @comment node-name, next, previous, up
4464 @chapter Initialization, exit and other features
4468 * Initialization and exit:: Initializing and exiting GTK.
4469 * Customization:: Customizing the library.
4470 * Menu Factories:: Simplified menu creation.
4471 * Tree Factories:: Simplified tree creation.
4472 * Tool Tips:: Pop up help mechanism.
4473 * Resource Files:: Resource files.
4474 * Standard Macros:: Macros defined by all objects.
4478 @node Initialization and exit, Customization, Miscellaneous, Miscellaneous
4479 @comment node-name, next, previous, up
4480 @section Initializing and exiting GTK
4482 @subsection Initializing
4483 Before any GTK functions can be utilized the library must be initilized. This
4484 can be accomplished by calling the @code{gtk_init} function. The arguments
4485 you pass to this function should be the same arguments that were passed to
4486 your application. This function will parse the arguments that it understands
4487 and handle initilizing the GDK library for you.
4491 @subsection Functions
4493 @deftypefun void gtk_init (int *@var{argc}, char **@var{argv})
4494 Function to initilize GTK and GDK for you. This function will remove any
4495 command line arguments from @var{argc} and @var{argv} that it understands.
4498 int main (int argc, char *argv[])
4500 @dots{Any local variables or non GTK/GDK initilization}
4502 gtk_init(&argc, &argc);
4508 @deftypefun void gtk_main (void)
4512 @node Customization, Menu Factories, Initialization and exit, Miscellaneous
4513 @comment node-name, next, previous, up
4514 @section Customization of the library
4516 @subsection Description
4517 Like other X-windows applications the GTK library provides a way for the
4518 user and application programmer to change the colors of just about any widget.
4519 You can also specify what pixmap should be tiled onto the background of some
4520 widgets. All this is handled through a similar method as in the standard
4521 X-windows environment, through the use of 'rc' files. The format and
4522 functions available in these files is discussed below.
4524 @subsection Functions
4525 The following functions are available to handle the rc files.
4527 @deftypefun void gtk_rc_parse (char *@var{filename})
4528 This function will parse the @var{filename} that is passed to it as its
4529 argument. It will use the style settings for the widget types defined there.
4532 @deftypefun void gtk_rc_init (void)
4533 This function will initilize the rc file parser, normally this need not
4534 be called directly as the @code{gtk_init} function will handle this for
4539 @node Menu Factories, Tree Factories, Customization, Miscellaneous
4540 @comment node-name, next, previous, up
4541 @section Simplified menu creation
4544 @node Tree Factories, Tool Tips, Menu Factories, Miscellaneous
4545 @comment node-name, next, previous, up
4546 @section Simplified tree creation
4549 @node Tool Tips, Resource Files, Tree Factories, Miscellaneous
4550 @comment node-name, next, previous, up
4551 @section Pop up help mechanism
4553 @subsection Description
4556 @node Resource Files, Standard Macros, Tool Tips, Miscellaneous
4557 @comment node-name, next, previous, up
4558 @section Resource Files
4561 @node Standard Macros, , Resource Files, Miscellaneous
4562 @comment node-name, next, previous, up
4563 @section Macros defined by all objects
4565 There are three macros that are defined by all object types. The first
4566 two are used for performing casts and the last is for querying whether
4567 an object is of a particular type. These macros are both conveniences
4568 and debugging tools. If the GTK library was compiled with @code{NDEBUG}
4569 defined as a preprocessor symbol (via the -DNDEBUG to cc), then the
4570 macros check the object type and emit a warning if the cast is
4571 invalid. Doing such checking is fairly expensive since the cast macros
4572 are used everywhere in GTK and would normally be turned off in a public
4573 release of a product. Note: The functions below are indeed macros, but
4574 they may be considered functions for most purposes.
4576 @deftypefun Gtk<ObjectType>* GTK_<OBJECT_TYPE> (gpointer @var{obj})
4577 Cast a generic pointer to @code{Gtk<ObjectType>*}. This function is
4578 provided in order to be able to provide checking during development
4579 stages of code development since it is possible to examine the actual
4580 type of object (using @code{gtk_type_is_a}) before performing the cast.
4583 @deftypefun Gtk<ObjectType>Class* GTK_<OBJECT_TYPE>_CLASS (gpointer @var{class})
4584 Cast a generic pointer to @code{Gtk<ObjectType>Class*}. Like
4585 @code{GTK_<ObjectType>}, this function is, in reality, a macro.
4588 @deftypefun gint GTK_IS_<ObjectType> (gpointer @var{obj})
4589 Determine if a generic pointer refers to a @code{Gtk<ObjectType>}
4590 object. This function is, in reality, a macro wrapper around the
4591 @code{gtk_type_is_a} function (@pxref{Objects}).
4595 @node Examples, Object Implementation, Miscellaneous, Top
4596 @comment node-name, next, previous, up
4601 * Simple:: The simplest GTK program.
4602 * Hello World:: Hello world in GTK.
4603 * Hello World II:: An enhanced hello world.
4604 * Hello World III:: Making Hello World II robust.
4608 @node Simple, Hello World, Examples, Examples
4609 @comment node-name, next, previous, up
4610 @section The simplest GTK program
4613 The 16 line GTK program shown below is just about the simplest possible
4614 program which uses GTK. (Well, technically, you don't have to create the
4615 window and it would still be a program which uses GTK). The program,
4616 when compiled and run, will create a single window 200x200 pixels in
4617 size. The program does not exit until its is explicitly killed using the
4618 shell or a window manager function.
4621 #include <gtk/gtk.h>
4624 main (int argc, char *argv[])
4628 gtk_init (&argc, &argv);
4630 window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
4631 gtk_widget_show (window);
4639 The first point of interest in this program is the standard
4640 initialization line.
4643 gtk_init (&argc, &argv);
4646 Almost every GTK program will contain such a line. GTK will initialize
4647 itself and GDK and remove any command line arguments it recognizes from
4648 @var{argc} and @var{argv}.
4650 The next two lines of code create and display a window.
4653 window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
4654 gtk_widget_show (window);
4657 The @code{GTK_WINDOW_TOPLEVEL} argument specifies that we want the
4658 window to undergo window manager decoration and placement. One might be
4659 lead to think that the window, since it has no children, would be 0x0
4660 pixels in size. But, this is not the case because a window that has no
4661 children defaults to 200x200 pixels in size. Mainly because 0x0 windows
4662 are annoying to manipulate or even see in some cases.
4664 The last line enters the GTK main processing loop.
4670 Normally, @code{gtk_main} is called once and the program should exit
4671 when it returns. @xref{Initialization and exit}.
4674 @node Hello World, Hello World II, Simple, Examples
4675 @comment node-name, next, previous, up
4676 @section Hello world in GTK
4680 #include <gtk/gtk.h>
4683 main (int argc, char *argv[])
4688 gtk_init (&argc, &argv);
4690 window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
4691 gtk_container_border_width (GTK_CONTAINER (window), 10);
4693 label = gtk_label_new ("Hello World");
4694 gtk_container_add (GTK_CONTAINER (window), label);
4695 gtk_widget_show (label);
4697 gtk_widget_show (window);
4706 @node Hello World II, Hello World III, Hello World, Examples
4707 @comment node-name, next, previous, up
4708 @section An enhanced hello world
4717 g_print ("Hello World\n");
4722 main (int argc, char *argv[])
4727 gtk_init (&argc, &argv);
4729 window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
4730 gtk_container_border_width (GTK_CONTAINER (window), 10);
4732 button = gtk_button_new_with_label ("Hello World");
4733 gtk_signal_connect (GTK_OBJECT (button), "clicked",
4734 GTK_SIGNAL_FUNC (hello), NULL);
4735 gtk_container_add (GTK_CONTAINER (window), button);
4736 gtk_widget_show (button);
4738 gtk_widget_show (window);
4747 @node Hello World III, , Hello World II, Examples
4748 @comment node-name, next, previous, up
4749 @section Making Hello World II robust
4758 g_print ("Hello World\n");
4769 main (int argc, char *argv[])
4774 gtk_init (&argc, &argv);
4776 window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
4777 gtk_signal_connect (GTK_OBJECT (window), "destroy",
4778 GTK_SIGNAL_FUNC (destroy), NULL);
4779 gtk_container_border_width (GTK_CONTAINER (window), 10);
4781 button = gtk_button_new_with_label ("Hello World");
4782 gtk_signal_connect (GTK_OBJECT (button), "clicked",
4783 GTK_SIGNAL_FUNC (hello), NULL);
4784 gtk_signal_connect_object (GTK_OBJECT (button), "clicked",
4785 GTK_SIGNAL_FUNC (gtk_widget_destroy),
4786 GTK_OBJECT (window));
4787 gtk_container_add (GTK_CONTAINER (window), button);
4788 gtk_widget_show (button);
4790 gtk_widget_show (window);
4799 @node Object Implementation, Signal Implementation, Examples, Top
4800 @comment node-name, next, previous, up
4801 @chapter Object internals
4802 @cindex Object Implementaton
4804 Objects (or the @code{GtkObject} type) and the class hierarchy in
4805 general is implemented via a hierarchy of structs and type casting. Be
4806 aware that when classes are mentioned it is the conceptual idea of
4807 classes that is being referred to. GTK is written entirely in C which
4808 provides no direct support for classes.
4810 The first part to the class mechanism is the object fields. These are
4811 fields that will be used on a per object basis. For example, the widget
4812 type contains a field for the widgets parent. Every derived type needs a
4813 reference to its parent type. A descendant class of @code{GtkObject}
4814 would define itself like:
4825 It is important to note that the @code{GtkObject} field needs to appear
4826 first in the descendant type structure. This allows pointers to objects
4827 of type @code{Descendant} to be cast to pointers to @code{GtkObjects}'s
4830 The second part to the class mechanism is the class fields. These fields
4831 are defined on a per class basis. In the case of widgets, the class
4832 fields are all the ``virtual'' functions for widgets. The
4833 @code{GtkObject} class defines the @code{destroy} virtual function and
4834 the necessary fields for the signal mechanism as well as a field for
4835 determining the runtime type of an object. A virtual function is
4836 semantically the same as it is in C++. That is, the actual function that
4837 is called is determined based on the type of the object. Or, more
4838 specifically, the actual function call depends on the class structure
4839 that is pointed to by the @code{klass} field of the @code{GtkObject}
4842 To see how the class fields work it is necessary to see the object
4843 fields for a @code{GtkObject}. The @code{GtkObject} type is defined as
4847 typedef struct _GtkObject GtkObject;
4852 GtkObjectClass *klass;
4853 gpointer object_data;
4857 The @code{class} field actually points to a class structure derived from
4858 @code{GtkObjectClass}. By convention, each new type defines its own
4859 class structure even if it is unnecessary. As an example, the
4860 hypothetical @code{Descendant} class would define its class structure
4864 struct DescendantClass
4866 GtkObjectClass parent_class;
4872 It is convention to name the parent class field (@code{GtkObjectClass}
4873 in this case), @code{parent_class}. For the same reason as stated above
4874 for the object structure, the parent class field must be the first field
4875 in the class structure.
4877 @strong{Note:} GTK assumes that the first field in a structure will be
4878 placed by the compiler at the start of the structure. This is certainly
4879 true for gcc, however, from my precursory reading of the C standard I
4880 was unable to come to a definite conclusion as to whether this was
4881 required or simply done for simplicity. I'm not too worried about this
4882 assumption, though, as every C compiler I've ever encountered would work
4885 The @code{flags} field of the @code{GtkObject} structure is used to keep
4886 track of a relatively few object flags and is also used by the
4887 @code{GtkWidget} type to store additional flags. At this time, the upper
4888 16 bits of the flags field are reserved but unused.
4890 The @code{object_data} field of the @code{GtkObject} structure is an
4891 opaque pointer used by the object data mechanism. In truth, it is a
4892 pointer to the beginning of the data list which is composed of the
4893 following structures.
4896 typedef struct _GtkObjectData GtkObjectData;
4898 struct _GtkObjectData
4902 GtkObjectData *next;
4906 The data mechanism allows arbitrary data to be associated with a
4907 character string key in any object. A hash table is used to transform
4908 the character string key into the data id and then a search through the
4909 list is made to see if the data exists. The assumption being that the
4910 data list will usually be short and therefore a linear search is
4911 ok. Future work on the data mechanism might make use of a resizable
4912 array instead of a linked list. This would shrink the overhead of the
4913 @code{GtkObjectData} structure by 4 bytes on 32 bit architectures.
4916 @node Signal Implementation, Widget Implementation, Object Implementation, Top
4917 @comment node-name, next, previous, up
4918 @chapter Signal internals
4919 @cindex Signal Implementation
4922 @node Widget Implementation, Function Index, Signal Implementation, Top
4923 @comment node-name, next, previous, up
4924 @chapter Widget internals
4925 @cindex Widget Implementation
4928 @node Function Index, Concept Index, Widget Implementation, Top
4929 @comment node-name, next, previous, up
4930 @unnumbered Function Index
4935 @node Concept Index, , Function Index, Top
4936 @comment node-name, next, previous, up
4937 @unnumbered Concept Index