1 \input texinfo @c -*-texinfo-*-
2 @c Copyright (C) 1996 by Peter Mattis. All rights reserved.
3 @c Portions Copyright (C) 1998 Marius Vollmer
13 @set update-date 23 August 1998
14 @set update-month August 1998
17 This file documents GTK, the GIMP Toolkit
19 Copyright (C) 1996 Peter Mattis
20 Copyright (C) 1997 Peter Mattis
22 Permission is granted to make and distribute verbatim copies of this
23 manual provided the copyright notice and this permission notice are
24 preserved on all copies
27 Permission is granted to process this file through TeX and print the
28 results, provided the printed document carries copying permission notice
29 identical to this one except for the removal of this paragraph (this
30 paragraph not being relevant to the printed manual).
33 Permission is granted to copy and distribute modified versions of this
34 manual under the conditions for verbatim copying, provided that the
35 entire resulting derived work is distributed under the terms of a
36 permission notice identical to this one.
38 Permission is granted to copy and distribute translations of this manual
39 into another language, under the above conditions for modified versions,
40 except that this permission notice may be stated in a translation
41 approved by Peter Mattis.
45 @title The GIMP Toolkit
46 @subtitle Version @value{edition}
47 @subtitle @value{update-month}
48 @author by Peter Mattis and the GTK+ team
51 @vskip 0pt plus 1filll
52 Copyright @copyright{} 1996 Peter Mattis
54 Copyright @copyright{} 1997 Peter Mattis
56 Permission is granted to make and distribute verbatim copies of this
57 manual provided the copyright notice and this permission notice are
58 preserved on all copies.
60 Permission is granted to copy and distribute modified versions of this
61 manual under the conditions for verbatim copying, provided that the
62 entire resulting derived work is distributed under the terms of a
63 permission notice identical to this one.
65 Permission is granted to copy and distribute translations of this manual
66 into another language, under the above conditions for modified versions,
67 except that this permission notice may be stated in a translation
68 approved by Peter Mattis.
71 @dircategory User Interface Toolkit
73 * GTK: (gtk). The GIMP Toolkit
76 @node Top, Copying, (dir), (dir)
79 This is edition @value{edition} of the GTK documentation,
80 @w{@value{update-date}}.
82 @c FIXME: Do an introduction to the GTK?
85 * Copying:: Your rights.
86 * Overview:: What is GTK?
89 * Signals:: Signals overview.
90 * Widgets:: Widget overview.
91 * Other Objects:: Utility objects.
92 * Miscellaneous:: Initialization, exit and other features.
93 * Examples:: Using GTK.
94 * Object Implementation:: Object internals.
95 * Signal Implementation:: Signal internals.
96 * Widget Implementation:: Widget internals.
97 * Function Index:: Index of functions.
98 * Concept Index:: Index of concepts.
101 @node Copying, Overview, Top, Top
102 @comment node-name, next, previous, up
106 GTK is @dfn{free}; this means that everyone is free to use it and free
107 to redistribute it on a free basis. GTK is not in the public domain; it
108 is copyrighted and there are restrictions on its distribution, but
109 these restrictions are designed to permit everything that a good
110 cooperating citizen would want to do. What is not allowed is to try to
111 prevent others from further sharing any version of GTK that they might
114 Specifically, we want to make sure that you have the right to give away
115 copies of GTK, that you receive source code or else can get it if you
116 want it, that you can change GTK or use pieces of it in new free
117 programs, and that you know you can do these things.
119 To make sure that everyone has such rights, we have to forbid you to
120 deprive anyone else of these rights. For example, if you distribute
121 copies of GTK, you must give the recipients all the rights that you
122 have. You must make sure that they, too, receive or can get the source
123 code. And you must tell them their rights.
125 Also, for our own protection, we must make certain that everyone finds
126 out that there is no warranty for GTK. If GTK is modified by someone
127 else and passed on, we want their recipients to know that what they have
128 is not what we distributed, so that any problems introduced by others
129 will no reflect on our reputation.
131 The precise conditions of the licenses for GTK are found in the General
132 Public Licenses that accompany it.
135 @node Overview, Types, Copying, Top
136 @comment node-name, next, previous, up
137 @chapter What is GTK?
140 GTK is a library for creating graphical user interfaces similar to the
141 Motif ``look and feel''. It is designed to be small and efficient, but
142 still flexible enough to allow the programmer freedom in the interfaces
143 created. GTK allows the programmer to use a variety of standard user
144 interface widgets (@pxref{Widgets}) such as push, radio and check
145 buttons, menus, lists and frames. It also provides several ``container''
146 widgets which can be used to control the layout of the user interface
149 GTK provides some unique features. (At least, I know of no other widget
150 library which provides them). For example, a button does not contain a
151 label, it contains a child widget, which in most instances will be a
152 label. However, the child widget can also be a pixmap, image or any
153 combination possible the programmer desires. This flexibility is adhered
154 to throughout the library.
156 @c I think the next paragraph takes unproportionally much space for
157 @c the thing it wants to say (compared to the rest of this overview).
158 @c So Somebody please extend this overview with more generally interesting
161 To make life easier for you, GTK presents this flexibility in a uniform
162 framework. Specifically, it implements its own support for object
163 oriented programming that is well adapted to the purposes of a user
164 interface toolkit and it aims at providing a reasonable sane and
165 disciplined programming interface. This uniformity and discipline is
166 intended to make it easy and reliable to access GTK from languages other
167 than C. Especially more dynamic languages like Perl, Python or Scheme
168 will find amble support, and in fact, bindings to these languages
171 @node Types, Objects, Overview, Top
172 @comment node-name, next, previous, up
179 Other kid's games are all such a bore!
180 They've gotta have rules and they gotta keep score!
182 -- Calvin about CalvinBall(tm)
185 GTK implements a semi-simple type system with an associated class
186 mechanism for widgets and several other useful objects. This type
187 system is intended to be general enough to allow both a smooth binding
188 of dynamically typed languages to Gtk, as well as to serve for a
189 rigorous and formalistic definition of the larger part of the Gtk API.
192 @c type is the root of the class hierarchy. It provides a few items needed
193 @c by all classes, the foundation for the signal (@pxref{Signals})
194 @c mechanism and the ``destroy'' method.
196 The classes for the individual widgets are by far the most important
197 part of this type system, but before we get to them, we describe the
198 basics of the type system itself. This is mostly of interest for widget
199 writers and language binders, so you might want to skip ahead to the
200 next chapter, which talks about the object oriented stuff.
203 * Type introduction::
206 * Enumerations and flags::
213 @node Type introduction, Basics, Types, Types
214 @section Introduction to the Type System
216 Gtk defines its own system of types, much like a computer language
217 defines what types it supports. Of course, the Gtk type system is build
218 on top of the types that C provides, so it includes members like
219 @samp{int}, @samp{long} and @samp{float}. But, compared to C, it allows
220 only few carefully selected types and specifies a lot of restrictions on
221 the way you can use values of these types. For example, there is no
222 general facility for specifying @emph{pointer to X}. Instead, we take a
223 more higher level approach and define such things as @samp{string},
224 which is just like a @code{char*} but with additional rules about how to
225 manage the memory that it points to.
227 The type system has two purposes: to define a formal system with which
228 to describe the various exported features of Gtk; and to implement this
229 system at run-time so that we get sound and flexible @dfn{dynamic} types
230 for the dynamic languages that want to interface with Gtk.
232 Let me restate this with different words, because I think it is
233 important to understand this idea. We will see in a moment that the
234 type system is indeed well defined and all this detail is implemented
235 with functions and data structures in Gtk. For example, every type (and
236 there can be any number of them) can be represented with a unique
237 integer and Gtk has support for the necessary bookkeeping for this.
238 Every type also has a name and there are functions for converting
239 between the name of a type and its unique number. Maybe more useful,
240 there is a big discriminated union that can be used to pass around a
241 value of any representable type, together with its precise type.
243 This is the run-time or dynamic side of the type system. Mostly, you do
244 not need to use it when you don't want to. The compile-time or static
245 side of the type system can is used to statically define the programming
246 interface of Gtk. For example, suppose there is function @code{gtk_foo}
247 in the Gtk API that has a prototype
250 char *gtk_foo (char *);
253 This looks like it does something with strings. But what does it do
254 with the memory of the string that has been passed in, and what are we
255 supposed or allowed to do with the memory that the returned pointer
256 points to? The more restricted type @samp{string} from the Gtk type
257 system can be used to be more precise. In fact, the definition of
258 @samp{string} below includes the rule that when a @samp{string} is
259 passed to a function, that function is not allowed to retain a pointer
260 into the string beyond the life time of that function call. So we are
261 safe to deallocate it or override it when the function has returned.
262 Likewise, the definition specifies that the memory of a @samp{string}
263 that is returned from a function becomes the sole property of the
264 calling function. The calling function is responsible for deallocating
265 it eventually and it can be sure that nobody else scribbles in it. When
266 @samp{gtk_foo} really obeys these rules, we can say that it takes one
267 argument, which is a @samp{string}, and it returns a @samp{string}.
269 Now we can understand why it makes sense to have a more restrictive type
270 system than that of C. With it, it is possible to be more precise and
271 we actually have a framework where we can be sure that as long as we
272 stay inside this framework we are not gratuitously causing trouble for
273 languages that are more disciplined than C. Of course, you are not
274 restricted to making all your interfaces expressible within the
275 framework. There are valid reasons for breaking it, for performance or
276 simply for convenience. But please try to provide all the functionality
277 of your module in such a way that it can be described with this type
278 system and treat the non-conforming functions as additional goodies that
279 are nice to have but not essential. The reward is an instant
280 accessibility of your code from a huge number of scripting and extension
281 languages such as Perl, Python, and Guile.
283 These formal specifications of the Gtk interface are contained in
284 special declarations in the header files of Gtk. They are ignored by
285 the C compiler, but can be used by other language processors. For extra
286 convenience, these declarations are also available in a more condensed
287 form that is easier to parse. Tools for generating bindings of Gtk to
288 other languages can read these declarations and---because all the
289 important details are defined---automatically generate the bulk of the
290 needed glue code. It is also possible to feed these declarations into a
291 running application (an interface builder, say) and thus make it aware of
292 new widgets and functions without recompiling anything.
294 The run-time side of the type system is also somewhat introspective.
295 This means that you can query Gtk about all the members of an
296 enumeration for example. Gtk provides tools that help you provide this
297 introspection for your definitions also.
299 Types are not enough to completely specify an interface, so GTK also has
300 @dfn{modes}. A mode specifies what happens to a value when it crosses a
301 module boundary; it can be @samp{in}, @samp{out}, or @samp{inout}. Most
302 fundamental types (and their derived types) support only mode @samp{in}.
303 The modes @samp{out} and @samp{inout} can only be used with the
304 composite types: lists and vectors. When argument of these types are
305 marked as @samp{out} or @samp{inout} it means that the called module is
306 allowed to change the contents of the composite value and that these
307 changes need to be propagated back to the originator of the value. Mode
308 @samp{out} means that the argument has no meaningful value at the
309 beginning and should not be read. Mode @samp{in} specifies that the
310 called module is not allowed to change the value in any way.
312 The type system allows for an unbounded number of types. Every widget
313 is a type for example and you can add new widget types at any time
314 without confusing the run-time implementation of the type system.
315 Nevertheless, all types are derived from a certain @dfn{fundamental}
316 type, and there are only a small and finite number of fundamental types.
317 We only specify rules for the fundamental types and all other types
318 inherit these rules from their fundamental type. For example,
319 @samp{int} is a fundamental type, as is @samp{GtkObject}. All widgets
320 derive from @samp{GtkObject} and so the rules for @samp{GtkObject} apply
321 to all widgets as well.
323 This derivation defines a type hierarchy, but this hierarchy is not
324 completely general. You can't derive from @samp{int} for example, and
325 you can only have one level of derivation from @samp{enum}. The
326 fundamental type @samp{GtkObject}, however, is the basis for the large
327 and deep hierarchy of widget types.
329 The individual fundamental types are defined and explained in the
330 following sections. Here is a complete list of them:
334 The not-a-value type, similar to @samp{void}.
336 A character. Internationalization issues are still undecided.
339 @item byte, ubyte, int, uint, long, ulong, float, double
340 The usual assortment of scalar types.
342 A string. Internationalization issues are still undecided.
344 Enumerations with a fixed set of literals. Either used to express a
345 single choice from this set or to individually turn on and off several
348 A pointer to an opaque structure that can be copied and destroyed.
350 A pointer to a function with enough extra information so that it can
351 also be used for functions written in languages completely different
354 A pointer to a GtkObject or derived type. The fun starts here.
355 @item args, slist, dlist, cvec, tvec
356 An assortment of composite types like linked lists and counted or
357 zero-terminated arrays.
358 @item pointer, signal, c_callback
362 @node Basics, Simple types, Type introduction, Types
363 @section Basic Concepts
365 The basis for the type system are the fundamental types. At run-time,
366 they are represented by members of the @code{GtkFundamentalType}
367 enumeration. For the static declarations, they are identified with a
370 @deftp {Enumeration} GtkFundamentalType
371 This enumeration contains a member for each defined fundamental type.
372 Most members are listed along with the description of their semantics,
373 but one is listed here:
376 @item GTK_TYPE_INVALID
377 No valid type is derived from this. Use @code{GTK_TYPE_INVALID} to
378 express exceptional situations. This member does not really correspond
379 to a fundamental type and thus there is no name for it.
383 @deftp {Data type} GtkType
384 The type @code{GtkType} holds the run-time representation of a type. It
385 is an integer of a certain size. The follwing macros are defined to
386 access the basic properties of a @code{GtkType}:
388 @deftypefn {Macro} {unsigned int} GTK_TYPE_SEQNO (GtkType type)
389 Returns the sequence number of @var{type}. The sequence numbers are
390 guaranteed to be dense, i.e., you can use them to index a table and the
391 table need not be much larger than the number of different GtkTypes that
395 @deftypefn {Macro} GtkFundamentalType GTK_FUNDAMENTAL_TYPE (GtkType type)
396 Returns the fundamental type of @var{type}.
399 Both macros simply access different bit-fields of a @code{GtkType}, so
400 they are very efficient.
403 New types are registered with the @code{gtk_type_unique} function. Any
404 kind oftype can be registered with @code{gtk_type_unique} but there are
405 convenience functions for most fundamental types. Each fundamental type
406 has its own interpretation of the rules below and these convenience
407 functions should be used to automatically get the type registration
408 right. So, don't be put off by the apparent complexity of the interface
409 to @code{gtk_type_unique}. You will be using it only for new widgets,
410 and there the rules are simple.
412 The @code{GtkTypeInfo} structure is used to communicate information to
413 @code{gtk_type_unique} as opposed to passing in large numbers of
417 typedef struct _GtkTypeInfo GtkTypeInfo;
424 GtkClassInitFunc class_init_func;
425 GtkObjectInitFunc object_init_func;
428 GtkClassInitFunc base_class_init_func;
434 The @code{type_name} field refers to the name of the type. This is the
435 same name that is used in the static definitions. It is convention for
436 the type name to be closely related to the name of the underlying C
437 type. For example, the type name of the @code{GtkObject} structure is
438 ``GtkObject'', and the name of the @code{GtkWindowType} enumeration is
439 ``GtkWindowType''. Note that the C type corresponding to ``GtkObject''
440 is really a pointer to a @code{GtkObject} struct, but the name has no
444 The @code{object_size} field refers to the size in bytes of the C
445 structure for types that have such a structure. The easiest (and
446 portable) means of computing this size is by using the C @code{sizeof}
447 operator. For instance, the sizeof of the @code{GtkObject} structure is
448 computed by doing @code{sizeof (GtkObject)}. When the type has no
449 associated structure or when you do not want to support the
450 @code{gtk_type_new} function for the new type, set @code{object_size} to
451 0. Only types derived from GTK_TYPE_OBJECT can be handled by
452 @code{gtk_type_new}, anyway.
455 The @code{class_size} field refers to the size in bytes of the C
456 structure for the class. Again, the @code{sizeof} operator should be
457 used to compute this value. If you don't want to have a class structure
458 for this type, set the field to 0. @code{gtk_type_class} will then
459 always return @code{NULL}.
462 The @code{class_init_func} and @code{base_class_init_func} fields are
463 callbacks which are used by the type mechanism to initialize class
464 specific fields. The single argument these functions take is a pointer to
465 a class structure. When you do not need one or both of them, set the
466 corresponding field to @code{NULL}. The @code{class_init_func} will be
467 called at most once, right after the class structure of size
468 @code{class_size} has been allocated. The interaction between
469 @code{class_init_func} and @code{base_class_init_func} is only really
470 useful for the full-fledged object system. It is described there
474 The @code{object_init_func} field is a callback which is used by the
475 type mechanism to initialize object specific fields for structures that
476 have been allocated via @code{gtk_type_new}. The single argument this
477 functions takes is a pointer to an object structure. If you do not want
478 any special object initialization to take place, set this to
479 @code{NULL}. All object initialization functions for all types that are
480 part of the inheritance chain are called, starting with the most basic
485 @deftypefun guint gtk_type_unique (GtkType @var{parent_type}, GtkTypeInfo *@var{type_info})
486 The @var{parent_type} is simply the new types parent type. If
487 @var{parent_type} is GTK_TYPE_INVALID, then the new type is a new
488 fundamental type. You should @b{never} register new fundamental types.
489 @var{type_info} is a pointer to a structure which contains necessary
490 information for construction of the new type.
492 You can only register a specific name once.
495 @deftypefun gchar* gtk_type_name (GtkType @var{type})
496 The returned string is the name of @var{type} as specified to
497 @code{gtk_type_unique}.
500 @deftypefun GtkType gtk_type_from_name (guchar *@var{name})
501 Return the type associated with @var{name}. If there is no type
502 associated with @var{name}, then GTK_TYPE_INVALID will be returned.
505 @deftypefun GtkType gtk_type_parent (GtkType @var{type})
506 Returns the parent type of @var{type} or GTK_TYPE_INVALID if @var{type}
507 is a fundamental type.
510 @deftypefun gpointer gtk_type_class (GtkType @var{type})
511 Returns the initialized class structure for @var{type}. The class
512 structure is actually created and initialized the first time it is
513 needed. Refer to @pxref{Objects} for details on how this initialization works for GTK_TYPE_OBJECT derived types.
515 @c If creation and initialization occurs, the @code{class_size}
516 @c field of the @code{GtkTypeInfo} structure used to initialize this type
517 @c is used to determine how large the class structure is. The
518 @c @code{class_init_func} field from the @code{GtkTypeInfo} structure is
519 @c called for all the members in the types ancestry, including the
520 @c type. The order of this invocation proceeds from the root on down. For
521 @c example, the @code{GtkWidgetClass} is first initialized as an
522 @c @code{GtkObjectClass} by the object class initialization routine and
523 @c then by the widget class initialization routine. This allows the widget
524 @c class initialization routine to override values set by the object class
525 @c initialization routine.
527 The returned structure is shared by all objects of @var{type} and, as
528 such, should not be modified.
531 @deftypefun gpointer gtk_type_new (GtkType @var{type})
532 Returns a new instance of an @var{type} object. This works only for GTK_TYPE_OBJECT derived types. Please see @pxref{Objects}.
533 @c The @code{object_size}
534 @c and @code{object_init_func} fields of the @code{GtkTypeInfo} structure
535 @c are used to determine the objects allocated size and the object specific
536 @c initialization routine. Similarly to the class initialization, all the
537 @c object initialization routines from the root on down to the particular
538 @c type being created are invoked.
541 @deftypefun void gtk_type_describe_heritage (GtkType @var{type})
542 Prints the type heritage for @var{type}. The heritage for a type
543 includes the type and all its parent types up the type tree.
546 @deftypefun void gtk_type_describe_tree (GtkType @var{type}, gboolean @var{show_size})
547 Prints the type tree which starts at @var{type}. @var{show_size} is a
548 boolean which determines whether type sizes are printed.
551 @deftypefun gboolean gtk_type_is_a (GtkType @var{type}, GtkType @var{is_a_type})
552 A predicate function which determines whether the relation @var{type}
553 is_a @var{is_a_type} is true.
556 @c @deftypefun void gtk_type_get_arg (GtkObject *@var{object}, GtkType @var{type}, GtkArg *@var{arg}, guint @var{arg_id})
559 @c @deftypefun void gtk_type_set_arg (GtkObject *@var{object}, GtkType @var{type}, GtkArg *@var{arg}, guint @var{arg_id})
562 Values of all types can be handled uniformly by storing them into a
563 @code{GtkArg} structure. The @code{GtkArg} has the following fields:
567 This can be used to give the value represented by this @code{GtkArg}
568 structure a name. It is not used much.
571 The type of this value.
574 A big union that has (at least conceptually) one member for each
575 fundamental type. You should not access these members directly.
576 Rather, use the @code{GTK_VALUE_*} macros. There is one macro for each
577 fundamental type, and its name is derived from the name of the
578 GtkFundamentalType enumeration members simply by replacing ``Gtk_TYPE''
579 with ``GTK_VALUE''. All @code{GTK_VALUE_*} macros take a @code{GtkArg}
580 structure as their only parameter (@emph{not} a pointer) and evaluate to
584 For example, the accessor for the fundamental type GTK_TYPE_INT is
585 called GTK_VALUE_INT and you could use it like this:
591 value.type = GTK_TYPE_INT;
592 GTK_VALUE_INT(value) = 7;
595 @node Simple types, Enumerations and flags, Basics, Types
596 @section Simple Types
598 The Gtk type system has a full set of the usual simple types: integers,
599 floating point numbers, but also boolean and character. You can not
600 derive new types from these.
602 @multitable {GTK_TYPE_POINTER} {"gpointer"} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
603 @item Enum @tab Name @tab Description
604 @item GTK_TYPE_NONE @tab "void"
605 @tab A type without value.
606 @item GTK_TYPE_CHAR @tab "char"
607 @tab A 8-bit unsigned number representing a character. Numbers
608 between 0 and 127 are ASCII, the rest is undefined.
609 @item GTK_TYPE_BOOL @tab "gboolean"
610 @tab The boolean type. It is some small integer where the number 0
611 represents false and 1 is true. No other values are allowed.
612 @item GTK_TYPE_INT @tab "gint"
613 @tab A signed integer with at least 32 bits.
614 @item GTK_TYPE_UINT @tab "guint"
615 @tab A unsigned integer with at least 32 bits.
616 @item GTK_TYPE_LONG @tab "glong"
617 @tab A signed integer with at least 32 bits.
618 @item GTK_TYPE_ULONG @tab "gulong"
619 @tab A unsigned integer with at least 32 bits. This is large enough to
620 hold a coerced pointer.
621 @item GTK_TYPE_FLOAT @tab "gfloat"
622 @tab A single precision floating point number.
623 @item GTK_TYPE_DOUBLE @tab "gfloat"
624 @tab A souble precision floating point number.
625 @item GTK_TYPE_POINTER @tab "gpointer"
626 @tab A untyped pointer. Do not use this if you can avoid it.
629 The values of these types are all represented `directly' with the C
630 types that are indicated in the `name' column above. @pxref{Boxed
631 types} for a discussion of this.
633 @node Enumerations and flags, Strings, Simple types, Types
634 @section Enumerations and Flags
636 @node Strings, Boxed types, Enumerations and flags, Types
639 @node Boxed types, Callbacks, Strings, Types
642 @node Callbacks, Composite types, Boxed types, Types
645 @node Composite types, , Callbacks, Types
646 @section Composite Types
648 @node Objects, Signals, Types, Top
671 @section Object functions
673 The GtkObject type is the root of the type hierarchy used by GTK. It
674 provides a minimal set of fields used to implement the actual object,
675 class and signal mechanisms, as well as several utility routines which
676 make dealing with objects easier.
678 For the adventurous, see @ref{Object Implementation}.
680 @deftypefun guint gtk_object_get_type (void)
681 Returns the @code{GtkObject} type identifier.
684 @deftypefun void gtk_object_class_add_signals (GtkObjectClass *@var{class}, gint *@var{signals}, gint @var{nsignals})
685 Adds @var{signals} to the @code{signals} field in the GtkObjectClass
686 structure @var{class}. @xref{Signals}.
689 @deftypefun GtkObject* gtk_object_new (guint @var{type}, @dots{})
692 @deftypefun GtkObject* gtk_object_newv (guint @var{type}, guint @var{nargs}, GtkArg *@var{args})
695 @deftypefun void gtk_object_ref (GtkObject *@var{object});
698 @deftypefun void gtk_object_unref (GtkObject *@var{object});
701 @deftypefun void gtk_object_getv (GtkObject *@var{object}, guint @var{nargs}, GtkArg *@var{args})
704 @deftypefun void gtk_object_set (GtkObject *@var{object}, @dots{})
707 @deftypefun void gtk_object_setv (GtkObject *@var{object}, guint @var{nargs}, GtkArg *@var{args})
710 @deftypefun GtkArg* gtk_object_query_args (GtkType @var{class_type}, guint *@var{nargs})
713 @deftypefun void gtk_object_add_arg_type (gchar *@var{arg_name}, GtkType @var{arg_type}, guint @var{arg_id})
716 @deftypefun GtkType gtk_object_get_arg_type (gchar *@var{arg_name})
720 @deftypefun void gtk_object_destroy (GtkObject *@var{object})
721 Performs checks to make sure it is alright to destroy @var{object} and
722 then emits the @code{destroy} signal. The check which is performed is to
723 make sure @var{object} is not already processing another signal. If this
724 were the case then destroying the object immediately would undoubtedly
725 cause problems as the other signal would not be able to tell the object
726 was destroyed. The solution is that if @var{object} is processing another
727 signal we mark @var{object} is needing to be destroyed. When we finish
728 processing of the other signal we check whether the object needs to be
732 The GtkObject type provides a mechanism for associating arbitrary
733 amounts of data with an object. The data is associated with the object
734 using a character string key. The functions @code{gtk_object_set_data},
735 @code{gtk_object_get_data}, and @code{gtk_object_remove_data} are the
736 interface to this mechanism. Two other routines,
737 @code{gtk_object_set_user_data} and @code{gtk_object_get_user_data},
738 exist as convenience functions which simply use the same mechanism.
740 @deftypefun void gtk_object_set_data (GtkObject *@var{object}, const char *@var{key}, gpointer @var{data})
741 Associate @var{data} with @var{key} in the data list of @var{object}.
744 @deftypefun gpointer gtk_object_get_data (GtkObject *@var{object}, const char *@var{key})
745 Retrieve the data associated with @var{key} in the data list of @var{object}.
748 @deftypefun void gtk_object_remove_data (GtkObject *@var{object}, const char *@var{key})
749 Remove the data associated with @var{key} in the data list of @var{object}.
752 @deftypefun void gtk_object_set_user_data (GtkObject *@var{object}, gpointer @var{data})
753 Sets @var{data} into the @code{user_data} field of @var{object}.
756 @deftypefun gpointer gtk_object_get_user_data (GtkObject *@var{object})
757 Returns the @code{user_data} field of @var{object}.
760 @c ------------ Is this deprecated? -----------------
762 The GtkObject type also provides a mechanism for specifying
763 initialization values for fields. This general mechanism is called
764 object value stacks. The reason for using value stacks is that they can
765 simplify the life of the programmer. For instance, by default widgets
766 are non-visible when created. However, the ``visible'' value for widgets
767 may be specified so that widgets are made visible when created. (FIXME:
770 @deftypefun void gtk_object_value_stack_new (guint @var{object_type}, const gchar *@var{value_id}, GtkParamType @var{value_type})
773 @deftypefun void gtk_object_push_value (guint @var{object_type}, const gchar *@var{value_id}, @dots{})
774 Push a value on the value stack specified by @var{object_type} and
775 @var{value_id}. The type of value is implicitly given in the context of
776 @var{object_type} and @var{value_id}. (That is, it is not specified
777 explicitly in the function call). Only a single extra argument is
778 expected which is the data which is to be placed on the stack.
781 @deftypefun void gtk_object_pop_value (guint @var{object_type}, const gchar *@var{value_id})
782 Pop a value of the value stack specified by @var{object_type} and
786 @deftypefun gint gtk_object_peek_value (guint @var{object_type}, const gchar *@var{value_id}, gpointer @var{data})
787 Peek at the value on the top of the value stack specified by
788 @var{object_type} and @var{value_id}. The @var{data} argument is
789 interpreted as the location of where to place the ``peeked'' data. For
790 instance, if the peeked data is of type @code{GTK_PARAM_POINTER}, then
791 @var{data} will be a pointer to a pointer. If the value stack is empty
792 or does not exist or an error occurs, @code{gtk_object_peek_value} will
793 return @code{FALSE}. On success it will return @code{TRUE}.
797 @node Signals, Widgets, Objects, Top
798 @comment node-name, next, previous, up
799 @chapter Signals Overview
802 Signals are GTK's method for objects to perform callbacks. A signal is
803 an event which occurs upon an object. The programmer can connect to a
804 signal of an object which involves specifying a function to be called
805 when that signal is emitted in the specified object.
807 When a signal is emitted, both the class function associated with the
808 signal (when it was defined) and all signal handlers installed for that
809 signal on the particular object emitting the signal are called. The
810 widget programmer can specify whether the class function is to be called
811 before after or both before and after the signal handlers installed by
812 the widget user. The widget user can, however, specify that their signal
813 handler is to be run after the class function (using the ``_after''
814 signal connection routines). Any signal handling function can emit the
815 same signal on the same object while it is running causing that signal
816 emission to either restart or to run recursively. Additionally, signal
817 emission can be terminated prematurely. While both such abilities are
818 rarely used, they do allow for greater flexibility in regards to
819 signals. For instance, a programmer can attach to the key press event
820 signal and intercept all tab key presses from a widget. This particular
821 example is used in the file selection dialog to implement tab completion
822 of filenames and prevent the entry widget from inserting the tab into
825 Signals are selected using either an integer identifier or a character
826 string name. It is convention to name the signal the same as the class
827 function which is associated with it. There are two versions of most of
828 the signal functions, one which takes an integer identifier and one
829 which takes a character string name for the signal.
831 @deftypefun gint gtk_signal_new (gchar *@var{name}, GtkSignalRunType @var{run_type}, gint @var{object_type}, gint @var{function_offset}, GtkSignalMarshaller @var{marshaller}, GtkParamType @var{return_val}, gint @var{nparams}, @dots{})
832 Create a new signal and give it the character string identifier
833 @var{name}. @var{name} needs to be unique in the context of
834 @var{object_type}'s branch of the class hierarchy. That is,
835 @var{object_type} cannot create a signal type with the same name as a
836 signal type created by one of its parent types.
838 @var{run_type} specifies whether the class function should be run before
839 (@code{GTK_RUN_FIRST}), after (@code{GTK_RUN_LAST}) or both before and
840 after normal signal handlers (@code{GTK_RUN_BOTH}). Additionally, the
841 @code{GTK_RUN_NO_RECURSE} value can be or'ed with any of those values to
842 specify that the signal should not be recursive. By default, emitting
843 the same signal on the same widget will cause the signal to be emitted
844 twice. However, if the @code{GTK_RUN_NO_RECURSE} flag is specified,
845 emitting the same signal on the same widget will cause the current
846 signal emission to be restarted. This allows the widget programmer to
847 specify the semantics of signal emission on a per signal
848 basis. (The @code{GTK_RUN_NO_RECURSE} flag is used by the GtkAdjustment
851 The @var{function_offset} is the byte offset from the start of the class
852 structure to the class function field within the class structure. The
853 easiest means to compute this offset is by using the
854 @code{GTK_SIGNAL_OFFSET} macro which takes the class structure type as
855 the first argument and the field as the second argument. For example,
856 @code{GTK_SIGNAL_OFFSET (GtkObjectClass, destroy)} will give the offset
857 of the @code{destroy} class function within the
858 @code{GtkObjectClass}. Note: An offset is specified instead of an
859 absolute location since there will be multiple instances of a class
860 structure being referenced. (The @code{GtkWidgetClass} structure ``is
861 a'' @code{GtkObjectClass} structure, etc.)
863 The @var{marshaller} function is used to invoke a signal handler. Since
864 signal handlers may take different parameters and return values and a
865 general mechanism for invoking them is not apparent, the approach of
866 making the signal creator responsible for invoking the signal handler
867 was taken. (FIXME: unfinished).
869 The @var{return_val} and @var{nparams} and the remaining arguments
870 specify the return value and the arguments to the signal handler
871 respectively. Note: There is an implicit first argument to every signal
872 handler which is the widget the signal has been emitted from. The
873 variable argument list (@var{@dots{}}) specifies the types of the
874 arguments. These can be one of @code{GTK_PARAM_CHAR},
875 @code{GTK_PARAM_SHORT}, @code{GTK_PARAM_INT}, @code{GTK_PARAM_LONG},
876 @code{GTK_PARAM_POINTER} or @code{GTK_PARAM_FUNCTION}. It is undefined
877 to specify @code{GTK_PARAM_NONE} as an argument type, however it is OK
878 to use @code{GTK_PARAM_NONE} for @var{return_val}. (This corresponds to
879 returning a @code{void}).
881 @code{gtk_signal_new} returns the integer identifier of the newly
882 created signal. Signal identifiers start numbering at 1 and increase
883 upwards. A value of -1 will be returned if an error occurs.
885 @strong{Note:} @code{gtk_signal_new} is only needed by widget writers. A
886 normal user of GTK will never needed to invoke this function.
889 @deftypefun gint gtk_signal_lookup (gchar *@var{name}, gint @var{object_type})
890 Returns the integer identifier for the signal referenced by @var{name}
891 and @var{object_type}. If @var{object_type} does not define the signal
892 @var{name}, then the signal is looked for in @var{object_type}'s parent
896 @deftypefun gchar* gtk_signal_name (gint @var{signal_num})
899 @deftypefun gint gtk_signal_emit (GtkObject *@var{object}, gint @var{signal_type}, @dots{})
900 Emit the signal specified by the integer identifier @var{signal_type}
901 from @var{object}. If an error occurs, @code{gtk_signal_emit} will
902 return @code{FALSE} and will return @code{TRUE} on success. The signal
903 definition determines the parameters passed in the variable argument
904 list (@code{@dots{}}). For example, if the signal is defined as:
907 gint (* event) (GtkWidget *widget, GdkEvent *event);
910 Then a call to emit the ``event'' signal would look like:
916 gtk_signal_emit (some_object,
917 gtk_signal_lookup ("event",
918 GTK_OBJECT_TYPE (some_object)),
919 &event, &return_val);
922 Notice that the @code{widget} argument is implicit in that the first
923 argument to every signal is a type derived from @code{GtkObject}. The
924 @var{return_val} argument is actually a pointer to the return value type
925 since the signal mechanism needs to be able to place the return value in
926 an actual location. And lastly, the @code{gtk_signal_lookup} call is
927 normally avoided by using the @code{gtk_signal_emit_by_name} function
928 instead. @code{gtk_signal_emit} is normally used internally by widgets
929 which know the signal identifier (since they defined the signal) and can
930 therefore side-step the cost of calling @code{gtk_signal_lookup}.
933 @deftypefun gint gtk_signal_emit_by_name (GtkObject *@var{object}, gchar *@var{name}, @dots{})
934 Similar to @code{gtk_signal_emit} except that the signal is referenced
935 by @var{name} instead of by its integer identifier.
938 @deftypefun void gtk_signal_emit_stop (GtkObject *@var{object}, gint @var{signal_type})
939 Stop the emission of the signal @var{signal_type} on
940 @var{object}. @var{signal_type} is the integer identifier for the signal
941 and can be determined using the function
942 @code{gtk_signal_lookup}. Alternatively, the function
943 @code{gtk_signal_emit_stop_by_name} can be used to refer to the signal
944 by name. Attempting to stop the emission of a signal that isn't being
945 emitted does nothing.
948 @deftypefun void gtk_signal_emit_stop_by_name (GtkObject *@var{object}, gchar *@var{name})
949 Similar to @code{gtk_signal_emit_stop} except that the signal is
950 referenced by @var{name} instead of by its integer identifier.
953 @deftypefun gint gtk_signal_connect (GtkObject *@var{object}, gchar *@var{name}, GtkSignalFunc @var{func}, gpointer @var{func_data})
954 Connects a signal handling function to a signal emitting
955 object. @var{func} is connected to the signal @var{name} emitted by
956 @var{object}. The arguments and returns type of @var{func} should match
957 the arguments and return type of the signal @var{name}. However,
958 @var{func} may take the extra argument of @var{func_data}. Due to the C
959 calling convention it is OK to ignore the extra argument. (It is OK to
960 ignore all the arguments in fact).
962 @code{gtk_signal_connect} returns an integer identifier for the
963 connection which can be used to refer to it in the future. Specifically
964 it is useful for removing the connection and/or blocking it from being
968 @deftypefun gint gtk_signal_connect_after (GtkObject *@var{object}, gchar *@var{name}, GtkSignalFunc @var{func}, gpointer @var{func_data})
969 Similar to @code{gtk_signal_connect} except the signal handler is
970 connected in the ``after'' slot. This allows a signal handler to be
971 guaranteed to run after other signal handlers connected to the same
972 signal on the same object and after the class function associated with
975 Like @code{gtk_signal_connect}, @code{gtk_signal_connect_after} returns
976 an integer identifier which can be used to refer to the connection.
979 @deftypefun gint gtk_signal_connect_object (GtkObject *@var{object}, gchar *@var{name}, GtkSignalFunc @var{func}, GtkObject *@var{slot_object})
980 Connects @var{func} to the signal @var{name} emitted by
981 @var{object}. Similar to @code{gtk_signal_connect} with the difference
982 that @var{slot_object} is passed as the first parameter to @var{func}
983 instead of the signal emitting object. This can be useful for connecting
984 a signal emitted by one object to a signal in another object. A common
985 usage is to connect the ``destroy'' signal of dialog to the ``clicked''
986 signal emitted by a ``close'' button in the dialog. That is, the
987 ``clicked'' signal emitted by the button will caused the ``destroy''
988 signal to be emitted for the dialog. This is also the ``right'' way to
989 handle closing of a dialog since the ``destroy'' signal will be sent if
990 the dialog is deleted using a window manager function and this enables
991 the two methods of closing the window to be handled by the same
992 mechanism. Returns an integer identifier which can be used to refer to
996 @deftypefun gint gtk_signal_connect_object_after (GtkObject *@var{object}, gchar *@var{name}, GtkSignalFunc @var{func}, GtkObject *@var{slot_object})
997 Similar to @code{gtk_signal_connect_object} except the signal handler is
998 connected in the ``after'' slot. This allows a signal handler to be
999 guaranteed to run after other signal handlers connected to the same
1000 signal on the same object and after the class function associated with
1001 the signal. Returns an integer identifier which can be used to refer to
1005 @deftypefun gint gtk_signal_connect_interp (GtkObject *@var{object}, gchar *@var{name}, GtkCallbackMarshal @var{func}, gpointer @var{data}, GtkDestroyNotify @var{destroy_func}, gint @var{after})
1008 @deftypefun void gtk_signal_disconnect (GtkObject *@var{object}, gint @var{id})
1009 Disconnects a signal handler from an object. The signal handler is
1010 identified by the integer @var{id} which is returned by the
1011 @code{gtk_signal_connect*} family of functions.
1014 @deftypefun void gtk_signal_disconnect_by_data (GtkObject *@var{object}, gpointer @var{data})
1015 Disconnects a signal handler from an object. The signal handler is
1016 identified by the @var{data} argument specified as the @var{func_data}
1017 argument to the @code{gtk_signal_connect*} family of functions. For the
1018 @code{gtk_signal_connect_object*} functions, @var{data} refers to the
1021 @strong{Note:} This will remove all signal handlers connected to
1022 @var{object} which were connected using @var{data} as their
1023 @var{func_data} argument. Multiple signal handlers may be disconnected
1027 @deftypefun void gtk_signal_handler_block (GtkObject *@var{object}, gint @var{id})
1028 Blocks calling of a signal handler during signal emission. The signal
1029 handler is identified by the integer @var{id} which is returned by the
1030 @code{gtk_signal_connect*} family of functions. If the signal is already
1031 blocked no change is made.
1034 @deftypefun void gtk_signal_handler_block_by_data (GtkObject *@var{object}, gint @var{data})
1035 Blocks calling of a signal handler during signal emission. The signal
1036 handler is identified by the @var{data} argument specified as the
1037 @var{func_data} argument to the @code{gtk_signal_connect*} family of
1038 functions. For the @code{gtk_signal_connect_object*} functions,
1039 @var{data} refers to the @var{slot_object}. If the signal is already
1040 blocked no change is made.
1042 @strong{Note:} This will block all signal handlers connected to
1043 @var{object} which were connected using @var{data} as their
1044 @var{func_data} argument. Multiple signal handlers may be blocked
1048 @deftypefun void gtk_signal_handler_unblock (GtkObject *@var{object}, gint @var{id})
1049 Unblocks calling of a signal handler during signal emission. The signal
1050 handler is identified by the integer @var{id} which is returned by the
1051 @code{gtk_signal_connect*} family of functions. If the signal is already
1052 unblocked no change is made.
1055 @deftypefun void gtk_signal_handler_unblock_by_data (GtkObject *@var{object}, gint @var{data})
1056 Unblocks calling of a signal handler during signal emission. The signal
1057 handler is identified by the @var{data} argument specified as the
1058 @var{func_data} argument to the @code{gtk_signal_connect*} family of
1059 functions. For the @code{gtk_signal_connect_object*} functions,
1060 @var{data} refers to the @var{slot_object}. If the signal is already
1061 unblocked no change is made.
1063 @strong{Note:} This will unblock all signal handlers connected to
1064 @var{object} which were connected using @var{data} as their
1065 @var{func_data} argument. Multiple signal handlers may be unblocked
1069 @deftypefun void gtk_signal_handlers_destroy (GtkObject *@var{object})
1070 Destroy all of the signal handlers connected to @var{object}. There
1071 should normally never be reason to call this function as it is called
1072 automatically when @var{object} is destroyed.
1075 @deftypefun void gtk_signal_default_marshaller (GtkObject *@var{object}, GtkSignalFunc @var{func}, gpointer @var{func_data}, GtkSignalParam *@var{params})
1076 @code{gtk_signal_new} requires a callback in order to actually call a
1077 signal handler for a particular signal. The vast majority of signals are
1078 of the particular form:
1081 (* std_signal) (gpointer std_arg);
1084 @code{gtk_signal_default_marshaller} is a signal marshaller which
1085 marshals arguments for a signal of that form.
1088 @deftypefun void gtk_signal_set_funcs (GtkSignalMarshal @var{marshal_func}, GtkSignalDestroy @var{destroy_fun})
1092 @node Widgets, Other Objects, Signals, Top
1093 @comment node-name, next, previous, up
1094 @chapter Widget Overview
1098 Widgets are the general term used to describe user interface objects. A
1099 widget defines a class interface that all user interface objects conform
1100 to. This interface allows a uniform method for dealing with operations
1101 common to all objects such as hiding and showing, size requisition and
1102 allocation and events.
1104 The common interface that widgets must adhere to is described by the
1105 GtkWidget and GtkWidgetClass structure. For the purposes of using GTK
1106 these structures can be considered read-only and, for the most part,
1109 All widget creation routines in GTK return pointers to GtkWidget
1110 structures. In reality, all widget creation routines create structures
1111 that can be viewed as equivalent to the GtkWidget structure, but often
1112 have contain additional information. @xref{Object Implementation}.
1114 The widgets available for use are implemented in a hierarchy. Several
1115 widgets exist solely as common bases for more specific widgets. For
1116 example, it is not possible to create a ruler widget itself, but the
1117 ruler widget provides a base and functionality common to the horizontal
1118 and vertical rulers.
1120 The available widgets (in alphabetical order):
1123 * GtkAlignment:: The alignment widget.
1124 * GtkArrow:: The arrow widget.
1125 * GtkAspectFrame:: The aspect frame widget.
1126 * GtkBin:: The bin widget.
1127 * GtkBox:: The box widget.
1128 * GtkButtonBox:: The button box widget.
1129 * GtkButton:: The button widget.
1130 * GtkCheckButton:: The check button widget.
1131 * GtkCheckMenuItem:: The check menu item widget.
1132 * GtkCList:: The compound list widget.
1133 * GtkColorSelection:: The color selector widget.
1134 * GtkCombo:: The combo box widget.
1135 * GtkContainer:: The container widget.
1136 * GtkCTree:: The multi-column tree widget.
1137 * GtkCurve:: The curve widget.
1138 * GtkGammaCurve:: The gamma curve widget.
1139 * GtkDialog:: The dialog widget.
1140 * GtkDrawingArea:: The drawing area widget.
1141 * GtkEntry:: The entry widget.
1142 * GtkEventBox:: The event box widget.
1143 * GtkFileSelection:: The file selection dialog widget.
1144 * GtkFixed:: The fixed widget.
1145 * GtkFrame:: The frame widget.
1146 * GtkGamma:: The gamma widget.
1147 * GtkHBox:: The horizontal box widget.
1148 * GtkHButtonBox:: The horizontal button box widget.
1149 * GtkHPaned:: The horizontal paned widget.
1150 * GtkHRuler:: The horizontal ruler widget.
1151 * GtkHScale:: The horizontal scale widget.
1152 * GtkHScrollbar:: The horizontal scrollbar widget.
1153 * GtkHSeparator:: The horizontal separator widget.
1154 * GtkImage:: The image widget.
1155 * GtkInputDialog:: The input dialog widget.
1156 * GtkItem:: The item widget.
1157 * GtkLabel:: The label widget.
1158 * GtkList:: The list widget.
1159 * GtkListItem:: The list item widget.
1160 * GtkMenu:: The menu widget.
1161 * GtkMenuBar:: The menu bar widget.
1162 * GtkMenuItem:: The menu item widget.
1163 * GtkMenuShell:: The menu shell widget.
1164 * GtkMisc:: The misc widget.
1165 * GtkNotebook:: The notebook widget.
1166 * GtkOptionMenu:: The option menu widget.
1167 * GtkPaned:: The paned widget.
1168 * GtkPixmap:: The pixmap widget.
1169 * GtkPreview:: The preview widget.
1170 * GtkProgressBar:: The progress bar widget.
1171 * GtkRadioButton:: The radio button widget.
1172 * GtkRadioMenuItem:: The radio menu item widget.
1173 * GtkRange:: The range widget.
1174 * GtkRuler:: The ruler widget.
1175 * GtkScale:: The scale widget.
1176 * GtkScrollbar:: The scrollbar widget.
1177 * GtkScrolledWindow:: The scrolled window widget.
1178 * GtkSeparator:: The separator widget.
1179 * GtkStatusbar:: The statusbar widget.
1180 * GtkTable:: The table widget.
1181 * GtkText:: The text widget.
1182 * GtkToggleButton:: The toggle button widget.
1183 * GtkToolbar:: The tool bar widget.
1184 * GtkTooltips:: The tool tips widget.
1185 * GtkTree:: The tree widget.
1186 * GtkTreeItem:: The tree item widget.
1187 * GtkVBox:: The vertical box widget.
1188 * GtkVButtonBox:: The vertical button box widget.
1189 * GtkViewport:: The viewport widget.
1190 * GtkVPaned:: The vertical paned widget.
1191 * GtkVRuler:: The vertical ruler widget.
1192 * GtkVScale:: The vertical scale widget.
1193 * GtkVScrollbar:: The vertical scrollbar widget.
1194 * GtkVSeparator:: The vertical separator widget.
1195 * GtkWidget:: The base widget type.
1196 * GtkWindow:: The window widget.
1199 @node GtkAlignment, GtkArrow, Widgets, Widgets
1200 @comment node-name, next, previous, up
1201 @section The alignment widget
1204 @subsection Description
1206 The alignment widget is a container (@pxref{GtkContainer}) derived from
1207 the bin widget (@pxref{GtkBin}). Its entire purpose is to give the
1208 programmer flexibility in how the child it manages is positioned when a
1211 Normally, a widget is allocated at least as much size as it
1212 requests. (@pxref{GtkContainer} for a discussion of geometry
1213 management). When a widget is allocated more size than it requests there
1214 is a question of how the widget should expand. By convention, most GTK
1215 widgets expand to fill their allocated space. Sometimes this behavior is
1216 not desired. The alignment widget allows the programmer to specify how a
1217 widget should expand and position itself to fill the area it is
1224 The @var{xscale} and @var{yscale} options specify how to scale the child
1225 widget. If the scale value is 0.0, the child widget is allocated exactly
1226 the size it requested in that dimension. If the scale value is 1.0, the
1227 child widget is allocated all of the space in a dimension. A scale value
1228 of 1.0 for both x and y is equivalent to not using an alignment widget.
1233 The @var{xalign} and @var{yalign} options specify how to position the
1234 child widget when it is not allocated all the space available to it
1235 (because the @var{xscale} and/or @var{yscale} options are less than
1236 1.0). If an alignment value is 0.0 the widget is positioned to the left
1237 (or top) of its allocated space. An alignment value of 1.0 positions the
1238 widget to the right (or bottom) of its allocated space. A common usage
1239 is to specify @var{xalign} and @var{yalign} to be 0.5 which causes the
1240 widget to be centered within its allocated area.
1245 @subsection Functions
1247 @deftypefun guint gtk_alignment_get_type (void)
1248 Returns the @code{GtkAlignment} type identifier.
1251 @deftypefun GtkWidget* gtk_alignment_new (gfloat @var{xalign}, gfloat @var{yalign}, gfloat @var{xscale}, gfloat @var{yscale})
1252 Create a new @code{GtkAlignment} object and initialize it with the
1253 values @var{xalign}, @var{yalign}, @var{xscale} and @var{yscale}. The
1254 new widget is returned as a pointer to a @code{GtkWidget}
1255 object. @code{NULL} is returned on failure.
1258 @deftypefun void gtk_alignment_set (GtkAlignment *@var{alignment}, gfloat @var{xalign}, gfloat @var{yalign}, gfloat @var{xscale}, gfloat @var{yscale})
1259 Set the @var{xalign}, @var{yalign}, @var{xscale} and @var{yscale} options
1260 of an alignment widget. It is important to not set the fields of the
1261 @code{GtkAlignment} structure directly (or, for that matter, any type
1262 derived from @code{GtkObject}).
1265 @gtkstdmacros{Alignment, ALIGNMENT}
1268 @node GtkArrow, GtkAspectFrame, GtkAlignment, Widgets
1269 @comment node-name, next, previous, up
1270 @section The arrow widget
1272 @subsection Description
1274 The arrow widget is derived from the misc widget (@pxref{GtkMisc}) and
1275 is intended for use where a directional arrow (in one of the four
1276 cardinal directions) is desired. As such, it has very limited
1277 functionality and basically only draws itself in a particular direction
1278 and with a particular shadow type. The arrow widget will expand to fill
1279 all the space it is allocated.
1284 The @var{arrow_type} option specifies which direction the arrow will
1285 point. It can be one of @code{GTK_ARROW_UP}, @code{GTK_ARROW_DOWN},
1286 @code{GTK_ARROW_LEFT} or @code{GTK_ARROW_RIGHT}. This will set the arrow
1287 pointing in the direction specified.
1291 The @var{shadow_type} option specifies how to draw the shadow for the
1292 arrow. Currently, only the @code{GTK_SHADOW_IN} and
1293 @code{GTK_SHADOW_OUT} shadow types are supported for drawing
1294 arrows. Other shadow types will cause nothing to be drawn.
1299 @subsection Functions
1301 @deftypefun guint gtk_arrow_get_type (void)
1302 Returns the @code{GtkArrow} type identifier.
1305 @deftypefun GtkWidget* gtk_arrow_new (GtkArrowType @var{arrow_type}, GtkShadowType @var{shadow_type})
1306 Create a new @code{GtkArrow} object and initialize it with the values
1307 @var{arrow_type} and @var{shadow_type}. The new widget is returned as a
1308 pointer to a @code{GtkWidget} object. @code{NULL} is returned on
1312 @deftypefun void gtk_arrow_set (GtkArrow *@var{arrow}, GtkArrowType @var{arrow_type}, GtkShadowType @var{shadow_type})
1313 Set the @var{arrow_type} and @var{shadow_type} options of an arrow
1314 widget. It is important to not set the fields of the @code{GtkArrow}
1315 structure directly (or, for that matter, any type derived from
1319 @gtkstdmacros{Arrow, ARROW}
1323 @node GtkAspectFrame, GtkBin, GtkArrow, Widgets
1324 @comment node-name, next, previous, upa
1325 @section The aspect frame widget
1327 @subsection Description
1329 Ensure that the child window has a specified aspect ratio or, if
1330 obey_child, has the same aspect ratio as its requested size. Derived
1331 from @pxref{GtkFrame}).
1352 @subsection Functions
1354 @deftypefun guint gtk_aspect_frame_get_type (void)
1355 Returns the @code{GtkAspectFrame} type identifier.
1358 @deftypefun GtkWidget* gtk_aspect_frame_new (gchar *@var{label}, gfloat @var{xalign}, gfloat @var{yalign}, gfloat @var{ratio}, gint @var{obey_child})
1359 Create a new @code{GtkAspectFrame} object and initialize it with the values
1360 @var{label}, @var{xalign}, @var{yalign}, @var{ratio} and @var{obey_child}.
1361 The new widget is returned as a pointer to a @code{GtkWidget} object.
1362 @code{NULL} is returned on failure.
1365 @deftypefun void gtk_aspect_frame_set (GtkAspectFrame *@var{aspect_frame}, gfloat @var{xalign}, gfloat @var{yalign}, gfloat @var{ratio}, gint @var{obey_child})
1369 @gtkstdmacros{AspectFrame, ASPECT_FRAME}
1372 @node GtkBin, GtkBox, GtkAspectFrame, Widgets
1373 @comment node-name, next, previous, up
1374 @section The bin widget
1376 @subsection Description
1378 The bin widget is a container (@pxref{GtkContainer}) derived from the
1379 container widget. It is an abstract base class. That is, it is not
1380 possible to create an actual bin widget. It exists only to provide a
1381 base of functionality for other widgets. Specifically, the bin widget
1382 provides a base for several other widgets that contain only a single
1383 child. These widgets include alignments (@pxref{GtkAlignment}), frames
1384 (@pxref{GtkFrame}), items (@pxref{GtkItem}), viewports
1385 (@pxref{GtkViewport}) and windows (@pxref{GtkWindow})
1391 @subsection Functions
1393 @deftypefun guint gtk_bin_get_type (void)
1394 Returns the @code{GtkBin} type identifier.
1397 @gtkstdmacros{Bin, BIN}
1401 @node GtkBox, GtkButtonBox, GtkBin, Widgets
1402 @comment node-name, next, previous, up
1403 @section The box widget
1406 @subsection Description
1408 The box widget is a container (@pxref{GtkContainer}) derived from the
1409 container widget. It is an abstract base class used by the horizontal
1410 box (@pxref{GtkHBox}), the vertical box (@pxref{GtkVBox}) and the
1411 (@pxref{GtkButtonBox}) widgets to provide a base of common functionality.
1413 A box provides an abstraction for organizing the position and size of
1414 widgets. Widgets in a box are laid out horizontally or vertically. By
1415 using a box widget appropriately, a programmer can control how widgets
1416 are positioned and how they will be allocated space when a window gets
1419 The key attribute of boxes is that they position their children in a
1420 single row (horizontal boxes) or column (vertical boxes). In the case of
1421 horizontal boxes, all children are stretched vertically. The vertical
1422 size of the box is determined by the largest vertical requisition of all
1423 of its children. Similarly, a vertical box stretches all of its children
1424 horizontally. The horizontal size (of the vertical box) is determined by
1425 the largest horizontal requisition of all of its children. An alignment
1426 widget (@pxref{GtkAlignment}) can be used to control child allocation
1427 more precisely on a per child basis.
1429 The second attribute of boxes is how they expand children. In the case
1430 of a horizontal box, the main control is over how children are expanded
1431 horizontally to fill the allocated area. (The rest of this discussion
1432 will focus on horizontal boxes but it applies to vertical boxes as
1435 There are two flags which can be set controlling how a widget is
1436 expanded horizontally in a horizontal box. These are the @code{expand}
1437 and @code{fill}. There operation is fairly simple. If @code{expand} is
1438 set, the child's potentially allocated area will expand to fill available
1439 space. If @code{fill} is set, the child's actual allocated area will be
1440 its potentially allocated area. There is a difference between
1441 the potentially area (which is the area the box widget sets aside for
1442 the child) and the actual allocated area (which is the area the box
1443 widget actual allocates for the widget via
1444 @code{gtk_widget_size_allocate}).
1446 The allocation of space to children occurs as follows (for horizontal
1450 All children are allocated at least their requested size horizontally
1451 and the maximum requested child size vertically.
1454 Any child with the @code{expand} flag set is allocated @code{extra_width
1455 / nexpand_children} extra pixels horizontally. If the @code{homogeneous}
1456 flag was set, all children are considered to have the @code{expand} flag
1457 set. That is, all children will be allocated the same area.The
1458 horizontal box is a fair widget and, as such, divides up any extra
1459 allocated space evenly among the ``expand'' children. (Those children
1460 which have the @code{expand} flag set). The exception occurs when
1461 @code{extra_width / nexpand_children} does not divide cleanly. The extra
1462 space is given to the last widget.
1465 @code{spacing} number of pixels separate each child. Note: The
1466 separation is between the potentially allocated area for each child and
1467 not the actual allocated area. The @code{padding} value associated with
1468 each child causes that many pixels to be left empty to each side of the
1472 If a child has the @code{fill} flag set it is allocated its potentially
1473 allocated area. If it does not, it is allocated its requested size
1474 horizontally and centered within its potentially allocated area. Its
1475 vertical allocation is still the maximum requested size of any child.
1478 Children placed at the start of the box are placed in order of addition
1479 to the box from left to right in the boxes allocated area.. Children
1480 placed at the end of the box are placed in order of addition from right
1481 to left in the boxes allocated area.
1484 @xref{GtkHBox}, and @ref{GtkVBox}, for code examples of using horizontal
1501 @c FIXME: options for GtkBox
1505 @subsection Functions
1507 @deftypefun guint gtk_box_get_type (void)
1508 Returns the @code{GtkBox} type identifier.
1511 @deftypefun void gtk_box_pack_start (GtkBox *@var{box}, GtkWidget *@var{child}, gint @var{expand}, gint @var{fill}, gint @var{padding})
1512 Add @var{child} to the front of @var{box}. The flags @var{expand} and
1513 @var{fill} and the padding value of @var{padding} are associated with
1517 @deftypefun void gtk_box_pack_end (GtkBox *@var{box}, GtkWidget *@var{child}, gint @var{expand}, gint @var{fill}, gint @var{padding})
1518 Add @var{child} to the end of @var{box}. The flags @var{expand} and
1519 @var{fill} and the padding value of @var{padding} are associated with
1523 @deftypefun void gtk_box_pack_start_defaults (GtkBox *@var{box}, GtkWidget *@var{widget})
1524 A convenience function which is equivalent to the following:
1527 gtk_box_pack_start (@var{box}, @var{widget}, TRUE, TRUE, 0);
1531 @deftypefun void gtk_box_pack_end_defaults (GtkBox *@var{box}, GtkWidget *@var{widget})
1532 A convenience function which is equivalent to the following:
1535 gtk_box_pack_start (@var{box}, @var{widget}, TRUE, TRUE, 0);
1539 @deftypefun void gtk_box_set_homogeneous (GtkBox *@var{box}, gint @var{homogeneous})
1540 Set the homogeneous setting of this box to @var{homogeneous}.
1543 @deftypefun void gtk_box_set_spacing (GtkBox *@var{box}, gint @var{spacing})
1546 @deftypefun void gtk_box_reorder_child (GtkBox *@var{box}, GtkWidget *@var{child}, guint @var{pos})
1549 @deftypefun void gtk_box_query_child_packing (GtkBox *@var{box}, GtkWidget *@var{child}, gint *@var{expand}, gint *@var{fill}, gint *@var{padding}, GtkPackType *@var{pack_type})
1552 @deftypefun void gtk_box_set_child_packing (GtkBox *@var{box}, GtkWidget *@var{child}, gint @var{expand}, gint @var{fill}, gint @var{padding}, GtkPackType *@var{pack_type})
1555 @gtkstdmacros{Box, BOX}
1559 @node GtkButtonBox, GtkButton, GtkBox, Widgets
1560 @comment node-name, next, previous, up
1561 @section The button box widget
1563 @subsection Description
1564 The button box widget is a container (@pxref{GtkContainer}) derived from the
1565 (@pxref{GtkBox}) widget. It is an abstract base class used by the horizontal
1566 button box (@pxref{GtkHButtonBox}) and the vertical button box
1567 (@pxref{GtkVButtonBox}) widgets to provide a base of common functionality.
1569 The button box, like the box widget, (@pxref{GtkBox}) provides an abstraction
1570 for organizing position and size of widgets. In the case of the button box
1571 it is targeted at the button widget,(@pxref{GtkButton}). Button widgets are
1572 laid out in the box horizontally or vertically. By using a button box widget
1573 appropriately, a programmer can control how the button widgets are positioned
1574 and how they will be allocated space when a window gets resized.
1577 @defopt layout_style
1581 @code{GTK_BUTTONBOX_SPREAD}
1585 The layout style @code{GTK_BUTTONBOX_SPREAD} will spread the buttons out
1586 evenly within the button box. When the parent window is resized they will
1587 re-adjust to the new window dimensions. The @code{gtk_button_box_set_spacing}
1588 function will set the minimum space that the buttons will leave between
1593 @code{GTK_BUTTONBOX_EDGE}
1599 @code{GTK_BUTTONBOX_START}
1603 The layout style @code{GTK_BUTTONBOX_START} will place the buttons at the
1604 start of the button box, taking into account the spacing as set by the
1605 @code{gtk_button_box_set_spacing} function. The buttons will not move
1606 when the parent window is re-sized.
1610 @code{GTK_BUTTONBOX_END}
1614 The layout style @code{GTK_BUTTONBOX_END} will place the buttons at the
1615 end of the button box, taking into account the spacing as set by the
1616 @code{gtk_button_box_set_spacing} function. Again like the
1617 @code{GTK_BUTTONBOX_START} layout style the buttons will not move when
1618 the parent window is re-sized.
1634 @subsection Functions
1636 @deftypefun guint gtk_button_box_get_type (void)
1637 Returns the @code{GtkButtonBox} type identifier.
1640 @deftypefun void gtk_button_box_set_child_size_default (gint @var{width}, gint@var{height})
1643 @deftypefun void gtk_button_box_set_child_ipadding_default (gint @var{ipad_x}, gint @var{ipad_y})
1646 @deftypefun void gtk_button_box_get_child_size_default (gint *@var{width}, gint *@var{height})
1649 @deftypefun void gtk_button_box_get_child_ipadding_default (gint *@var{ipad_x}, gint *@var{ipad_y})
1652 @deftypefun void gtk_button_box_set_child_size (GtkButtonBox *@var{widget}, gint @var{width}, gint @var{height})
1655 @deftypefun void gtk_button_box_set_child_ipadding (GtkButtonBox *@var{widget}, gint @var{ipad_x}, gint @var{ipad_y})
1658 @deftypefun void gtk_button_box_set_layout (GtkButtonBox *@var{widget}, gint @var{layout_style})
1659 This will set the layout style of the buttons within this box. Currently it can
1660 be set to one of @code{GTK_BUTTONBOX_SPREAD}, @code{GTK_BUTTONBOX_EDGE},
1661 @code{GTK_BUTTONBOX_START} or @code{GTK_BUTTONBOX_END}.
1663 The following example:
1665 gtk_button_box_set_layout (GTK_BUTTON_BOX (box),
1666 GTK_BUTTONBOX_SPREAD);
1668 Will set the @var{box} argument to the @dfn{SPREAD} layout style described
1672 @deftypefun gint gtk_button_box_get_spacing (GtkButtonBox *@var{widget})
1673 Get the per widget value for spacing within the button box. This value is
1674 the amount of space that will be between the individual buttons contained by
1678 @deftypefun void gtk_button_box_get_child_size (GtkButtonBox *@var{widget}, gint *@var{width}, gint *@var{height})
1681 @deftypefun void gtk_button_box_get_child_ipadding (GtkButtonBox *@var{widget}, gint *@var{ipad_x}, gint *@var{ipad_y})
1682 Get the per widget value for the padding inside the buttons. This value
1683 controls how large the buttons will be within the box.
1686 @deftypefun gint gtk_button_box_get_layout (GtkButtonBox *@var{widget})
1687 Get the @var{layout_style} for the @code{GtkButtonBox} object passed to this
1688 function in the @var{widget} variable.
1691 layout = gtk_button_box_get_layout(GTK_BUTTON_BOX (box));
1696 @gtkstdmacros{ButtonBox, BUTTON_BOX}
1699 @node GtkButton, GtkCheckButton, GtkButtonBox, Widgets
1700 @comment node-name, next, previous, up
1701 @section The button widget
1704 @subsection Description
1706 A pressable button. Contains a widget. Changes its appearance
1707 (hilites) when it gets the focus. Changes its appearance (pressed) when
1708 activated. Derived from @pxref{GtkContainer}.
1712 @deftypefn Signal void GtkButton::pressed (GtkButton *@var{button})
1715 @deftypefn Signal void GtkButton::released (GtkButton *@var{button})
1718 @deftypefn Signal void GtkButton::clicked (GtkButton *@var{button})
1721 @deftypefn Signal void GtkButton::enter (GtkButton *@var{button})
1724 @deftypefn Signal void GtkButton::leave (GtkButton *@var{button})
1727 @subsection Functions
1729 @deftypefun guint gtk_button_get_type (void)
1730 Returns the @code{GtkButton} type identifier.
1733 @deftypefun GtkWidget* gtk_button_new (void)
1734 Create a new @code{GtkButton} object. The new widget is returned as a
1735 pointer to a @code{GtkWidget} object. @code{NULL} is returned on failure.
1738 @deftypefun GtkWidget* gtk_button_new_with_label (gchar *@var{label})
1739 Create a new @code{GtkButton} object and set the text that is
1740 on the button to @var{label}. The new widget is returned as a
1741 pointer to a @code{GtkWidget} object. @code{NULL} is returned on failure.
1744 @deftypefun void gtk_button_pressed (GtkButton *@var{button})
1747 @deftypefun void gtk_button_released (GtkButton *@var{button})
1750 @deftypefun void gtk_button_clicked (GtkButton *@var{button})
1753 @deftypefun void gtk_button_enter (GtkButton *@var{button})
1756 @deftypefun void gtk_button_leave (GtkButton *@var{button})
1759 @gtkstdmacros{Button, BUTTON}
1763 @node GtkCheckButton, GtkCheckMenuItem, GtkButton, Widgets
1764 @comment node-name, next, previous, up
1765 @section The check button widget
1768 @subsection Description
1770 Another form of toggle button (@pxref{GtkToggleButton}) with an
1771 indicator. Contains a widget to the right of the indicator. Changes
1772 its appearance (hilites) when it gets the focus.
1778 @subsection Functions
1780 @deftypefun guint gtk_check_button_get_type (void)
1781 Returns the @code{GtkCheckButton} type identifier.
1784 @deftypefun GtkWidget* gtk_check_button_new (void)
1785 Create a new @code{GtkCheckButton} object and initialize it with the
1786 default values in the library. The new widget is returned as a pointer
1787 to a @code{GtkWidget} object. A @code{NULL} is returned on failure.
1790 @deftypefun GtkWidget* gtk_check_button_new_with_label (gchar *@var{label})
1791 Create a new @code{GtkCheckButton} object and initialize it with the
1792 values @var{label}. The new widget is returned as a pointer to a
1793 @code{GtkWidget} object. @code{NULL} is returned on any failure.
1796 @deftypefun GtkCheckButton* GTK_CHECK_BUTTON (gpointer @var{obj})
1799 @deftypefun GtkCheckButtonClass* GTK_CHECK_BUTTON_CLASS (gpointer @var{class})
1802 @deftypefun gint GTK_IS_CHECK_BUTTON (gpointer @var{obj})
1805 @gtkstdmacros{CheckButton, CHECK_BUTTON}
1808 @node GtkCheckMenuItem, GtkCList, GtkCheckButton, Widgets
1809 @comment node-name, next, previous, up
1810 @section The check menu item widget
1812 @subsection Description
1814 Derived from @pxref{GtkMenuItem}. Very similar to a checkbutton
1815 (@pxref{GtkCheckButton}), except that it's a menu item. Has a toggled
1816 state which is displayed in a small rectangle to the left of the
1829 @deftypefn Signal void GtkCheckMenuItem::toggled (GtkCheckMenuItem *@var{check_menu_item})
1832 @subsection Functions
1834 @deftypefun guint gtk_check_menu_item_get_type (void)
1835 Returns the @code{GtkCheckMenuItem} type identifier.
1838 @deftypefun GtkWidget* gtk_check_menu_item_new (void)
1839 Create a new @code{GtkCheckMenuItem} object. The new widget is returned as a
1840 pointer to a @code{GtkWidget} object. @code{NULL} is returned on failure.
1843 @deftypefun GtkWidget* gtk_check_menu_item_new_with_label (gchar *@var{label})
1844 Create a new @code{GtkCheckMenuItem} object and initialize it with the values
1845 @var{label}. The new widget is returned as a pointer to a @code{GtkWidget}
1846 object. @code{NULL} is returned on failure.
1849 @deftypefun void gtk_check_menu_item_set_state (GtkCheckMenuItem *@var{check_menu_item}, gint @var{state})
1852 @deftypefun void gtk_check_menu_item_toggled (GtkCheckMenuItem *@var{check_menu_item})
1855 @gtkstdmacros{CheckMenuItem, CHECK_MENU_ITEM}
1858 @node GtkCList, GtkColorSelection, GtkCheckMenuItem, Widgets
1859 @comment node-name, next, previous, up
1860 @section The compound list widget
1862 @subsection Description
1864 A list of rows of columns, with a title row. You can insert rows, and
1865 delete rows. The user can scroll around and select a row. Derived from
1866 @pxref{GtkContainer}. Cells can be empty, have a text and/or pixmap, or
1873 @subsection Functions
1875 @deftypefun guint gtk_clist_get_type (void)
1876 Returns the @code{GtkCList} type identifier.
1879 @deftypefun GtkWidget* gtk_clist_new (int @var{columns})
1880 Create a new @code{GtkCList} initializing it with the value @var{columns}.
1881 The new widget is returned as a pointer to a @code{GtkWidget} object.
1882 @code{NULL} is returned on failure.
1886 @deftypefun GtkWidget* gtk_clist_new_with_titles (int @var{columns}, gchar *@var{titles[]})
1889 @deftypefun void gtk_clist_set_border (GtkCList *@var{clist}, GtkShadowType @var{border})
1890 Set the border style of the @var{clist} to the shadow type @var{border}.
1893 @deftypefun void gtk_clist_set_selection_mode (GtkCList *@var{clist} GtkSelectionMode @var{mode})
1894 Set the selection mode on the @var{clist} to the @var{mode} selection mode.
1897 @deftypefun void gtk_clist_set_policy (GtkCList *@var{clist}, GtkPolicyType @var{vscrollbar_policy}, GtkPolicyType @var{hscrollbar_policy})
1898 Set the policy on the scrollbars on the @var{clist} to @var{vscrollbar_policy} and @var{hscrollbar_policy}.
1901 @deftypefun void gtk_clist_freeze (GtkCList *@var{clist})
1902 Stop all visual updates of the @var{clist}. Useful for when making a large
1903 number of changes to a @code{GtkCList}.
1906 @deftypefun void gtk_clist_thaw (GtkCList *@var{clist})
1907 Allow all visual updates of the @var{clist} to resume.
1910 @deftypefun void gtk_clist_column_titles_show (GtkCList *@var{clist})
1911 Show the column title buttons on the @var{clist}.
1914 @deftypefun void gtk_clist_column_titles_hide (GtkCList *@var{clist})
1915 Hide the column title buttons on the @var{clist}.
1918 @deftypefun void gtk_clist_set_column_title (GtkCList *@var{clist}, gint @var{column}, gchar *@var{title})
1919 Set the title in column @var{column} of the @var{clist} button to @var{title}.
1922 @deftypefun void gtk_clist_set_column_widget (GtkCList *@var{clist}, gint @var{column}, GtkWidget *@var{widget})
1923 Set the @var{widget} instead of the title button for the column @var{column}
1927 @deftypefun void gtk_clist_set_column_justification (GtkCList *@var{clist}, gint @var{column}, GtkJustification @var{justification})
1928 Set the @var{column}'s justification, in the @var{clist} to @var{justification}.
1931 @deftypefun void gtk_clist_set_column_width (GtkCList *@var{clist}, gint @var{column}, gint @var{width})
1932 Set the pixel width of column @var{column} in the @code{GtkCList} @var{clist}
1933 to @var{width}. This function is a necessary step in creating a
1934 @code{GtkCList} because otherwise the column width is chosen from the width
1935 of the column title, which is almost never correct.
1938 @deftypefun void gtk_clist_set_row_height (GtkCList *@var{clist}, gint @var{height})
1939 Change the height of the rows in the @var{clist} to @var{height}. The default
1940 is the height of the current font.
1943 @deftypefun void gtk_clist_moveto (GtkCList *@var{clist}, gint @var{row}, gint@var{column}, gfloat @var{row_align}, gfloat @var{col_align})
1944 Scroll the viewing area of the @code{GtkClist} in @var{clist} to @var{column}
1945 and @var{row}. The @var{row_align} and @var{col_align} are between zero and
1946 one, representing the location the row should appear on screen. Setting
1947 @var{row_align} or the @var{col_align} to 0.0 will be the top or left of the
1948 viewing area. Setting the @var{row_align} or @var{col_align} to 1.0 will
1949 be the bottom or right of the viewing area. If the @var{row} or @var{column}
1950 is -1 then there is no change.
1953 @deftypefun void gtk_clist_set_text (GtkCList *@var{clist}, gint @var{row}, gint @var{column}, gchar *@var{text})
1954 Set a given cell's text, located by the @var{row} and @var{column}, to
1955 @var{text} replacing its current contents.
1958 @deftypefun void gtk_clist_set_pixmap (GtkCList *@var{clist}, gint @var{row}, gint @var{column}, GdkPixmap *@var{pixmap}, GdkBitmap *@var{mask})
1959 Set a given cell's text, located by the @var{column} and @var{row} arguments,
1960 to the pixmap described by the @var{pixmap} argument using the @var{mask} as
1961 its mask. The current contents of the cell will be replaced.
1964 @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})
1965 Set a given cell's text and pixmap, located by the @var{row} and @var{column}
1966 arguments, to the text and pixmap described by the @var{pixmap} and @var{text}
1967 arguments. The @var{mask} will be used for the pixmap mask and the
1968 @var{spacing} argument specifies the spacing between the two.
1971 @deftypefun void gtk_clist_set_foreground (GtkCList *@var{clist}, gint @var{row}, GdkColor *@var{color})
1972 Set the foreground color of row @var{row} to @var{color} in the
1973 @code{GtkCList} @var{clist}. The @var{color} must
1974 already be allocated.
1977 @deftypefun void gtk_clist_set_background (GtkCList *@var{clist}, gint @var{row}, GdkColor *@var{color})
1978 Set the background color of row @var{row} to @var{color} in the
1979 @code{GtkCList} pointed to by @var{clist}. The color must be previously
1983 @deftypefun void gtk_clist_set_shift (GtkCList *@var{clist}, gint @var{row}, gint @var{column}, gint @var{vertical}, gint @var{horizontal})
1984 Set the horizontal and vertical shift for drawing the contents of the cell
1985 located at @var{row} and @var{column}. The @var{vertical} and @var{horizontal}
1986 arguments can be positive or negative.
1989 @deftypefun gint gtk_clist_append (GtkCList *@var{clist}, gchar *@var{text[]})
1990 Append the given text, in the @var{text[]} argument, to the @code{GtkCList}
1991 pointed to by the @var{clist}. The return value is the index of the row that
1995 @deftypefun void gtk_clist_insert (GtkCList *@var{clist}, gint @var{row}, gchar *@var{text[]})
1996 Insert a row into the @code{GtkCList} pointed to by @var{clist} at row
1997 @var{row} with the text in @var{text[]}.
2000 @deftypefun void gtk_clist_remove (GtkCList *@var{clist}, gint @var{row})
2001 Remove row index @var{row} from the @var{clist}.
2004 @deftypefun void gtk_clist_set_row_data (GtkCList *@var{clist}, gint @var{row}, gpointer @var{data})
2005 Will set an arbitrary data pointer, @var{data}, for row @var{row} in the
2006 @code{GtkCList} pointed to by @var{clist}.
2009 @deftypefun gpointer gtk_clist_get_row_data (GtkCList *@var{clist}, gint @var{row})
2010 Return the data that was set for row @var{row} from the @code{GtkCList} pointed
2011 to by @var{clist}. @code{NULL} is returned if no data was set.
2014 @deftypefun void gtk_clist_select_row (GtkCList *@var{clist}, gint @var{row}, gint @var{column})
2015 Force selection of a row, located by @var{row} and @var{column}, in the
2016 @code{GtkCList} pointed to by @var{clist}.
2019 @deftypefun void gtk_clist_unselect_row (GtkCList *@var{clist}, gint @var{row}, gint @var{column})
2020 Force the unselection of a row, located by @var{row} and @var{column}, in the
2021 @code{GtkCList} pointed to by @var{clist}.
2024 @deftypefun void gtk_clist_clear (GtkCList *@var{clist})
2025 Clear the entire contents of the @code{GtkCList} pointed to by @var{clist}.
2026 This is much faster then removing each item separately with
2027 @code{gtk_clist_remove}.
2030 @gtkstdmacros{CList, CLIST}
2033 @node GtkColorSelection, GtkCombo, GtkCList, Widgets
2034 @comment node-name, next, previous, up
2035 @section The color selector widget
2037 @subsection Description
2039 A widget that allows a user to pick a color in one of many ways. They
2040 can click on a color wheel or saturation bar. They can change hue,
2041 saturation, value, red, green, or blue with a slider, or by entering
2042 values. Also allows the user to set an alpha (opacity) value. Derived
2043 from @pxref{GtkVBox}.
2049 GTK_UPDATE_CONTINUOUS
2051 GTK_UPDATE_DISCONTINUOUS
2068 @subsection Functions
2070 @deftypefun guint gtk_color_selection_get_type (void)
2071 Returns the @code{GtkColorSelection} type identifier.
2074 @deftypefun GtkWidget* gtk_color_selection_new (void)
2075 Create a new @code{GtkColorSelection} object. The new object is returned as a
2076 pointer to a @code{GtkWidget} object. @code{NULL} is returned on failure.
2079 @deftypefun void gtk_color_selection_set_update_policy (GtkColorSelection *@var{colorsel}, GtkUpdateType @var{policy})
2082 @deftypefun void gtk_color_selection_set_color (GtkColorSelection *@var{colorsel}, gdouble *@var{color})
2085 @deftypefun void gtk_color_selection_get_color (GtkColorSelection *@var{colorsel}, gdouble *@var{color})
2088 @deftypefun void gtk_color_selection_set_opacity (GtkColorSelection *@var{colorsel}, gint @var{use_opacity})
2091 @deftypefun guint gtk_color_selection_dialog_get_type (void)
2092 Returns the @code{GtkColorSelection} type identifier.
2095 @deftypefun GtkWidget* gtk_color_selection_dialog_new (gchar *@var{title})
2096 Create a new @code{GtkColorSelection} object initializing the title bar of
2097 the resulting dialog to @var{title}. The new widget is returned as a pointer
2098 to a @code{GtkWidget} object. @code{NULL} is returned on failure.
2101 @gtkstdmacros{ColorSelection, COLOR_SELECTION}
2104 @node GtkCombo, GtkContainer, GtkColorSelection, Widgets
2105 @comment node-name, next, previous, up
2106 @section The combo widget
2108 @subsection Description
2110 Text input box which also lets you choose from pre-defined values from a
2111 drop-down menu. Derived from @pxref{GtkHBox}.
2117 @subsection Functions
2119 @deftypefun guint gtk_combo_get_type (void)
2120 Returns the @code{GtkCombo} type identifier.
2123 @deftypefun GtkWidget* gtk_combo_new (void)
2124 Create a new @code{GtkCombo} object returning the new widget as a pointer to
2125 a @code{GtkWidget} object. @code{NULL} is returned on failure.
2128 @deftypefun void gtk_combo_set_value_in_list (GtkCombo *@var{combo}, gint @var{val}, gint @var{ok_if_empty})
2131 @deftypefun void gtk_combo_set_use_arrows (GtkCombo *@var{combo}, gint @var{val})
2134 @deftypefun void gtk_combo_set_use_arrows_always (GtkCombo *@var{combo}, gint @var{val})
2137 @deftypefun void gtk_combo_set_case_sensitive (GtkCombo *@var{combo}, gint @var{val})
2140 @deftypefun void gtk_combo_set_item_string (GtkCombo *@var{combo}, GtkItem *@var{item}, gchar *@var{item_value})
2143 @deftypefun void gtk_combo_set_popdown_strings (GtkCombo *@var{combo}, GList *@var{strings})
2146 @gtkstdmacros{Combo, COMBO}
2149 @node GtkContainer, GtkCTree, GtkCombo, Widgets
2150 @comment node-name, next, previous, up
2151 @section The container widget
2153 @subsection Description
2155 A base class for objects that are built out of other widgets. Many
2156 widgets are containers. For example, a button contains a widget. That
2157 widget might be a text label (usually is), or a pixmap, or even an hbox
2158 which has a label and a pixmap.
2162 @defopt border_width
2167 @deftypefn Signal void GtkContainer::add (GtkContainer *@var{container}, GtkWidget *@var{widget})
2170 @deftypefn Signal void GtkContainer::remove (GtkContainer *@var{container}, GtkWidget *@var{widget})
2173 @deftypefn Signal void GtkContainer::need_resize (GtkContainer *@var{container}, GtkWidget *@var{widget})
2176 @deftypefn Signal void GtkContainer::foreach (GtkContainer *@var{container}, GtkCallback @var{callback}, gpointer @var{callback_data})
2179 @deftypefn Signal gint GtkContainer::focus (GtkContainer *@var{container}, GtkDirectionType @var{direction})
2182 @subsection Functions
2184 @deftypefun guint gtk_container_get_type (void)
2185 Returns the @code{GtkContainer} type identifier.
2188 @deftypefun void gtk_container_border_width (GtkContainer *@var{container}, gint @var{border_width})
2191 @deftypefun void gtk_container_add (GtkContainer *@var{container}, GtkWidget *@var{widget})
2192 Add @var{widget} to the @var{container}.
2195 @deftypefun void gtk_container_remove (GtkContainer *@var{container}, GtkWidget *@var{widget})
2196 Remove @var{widget} from @var{container}.
2199 @deftypefun void gtk_container_disable_resize (GtkContainer *@var{container})
2202 @deftypefun void gtk_container_enable_resize (GtkContainer *@var{container})
2205 @deftypefun void gtk_container_block_resize (GtkContainer *@var{container})
2208 @deftypefun void gtk_container_unblock_resize (GtkContainer *@var{container})
2211 @deftypefun gint gtk_container_need_resize (GtkContainer *@var{container}, GtkWidget *@var{widget})
2214 @deftypefun void gtk_container_check_resize (GtkContainer *@var{container}, GtkWidget *@var{widget})
2217 @deftypefun void gtk_container_foreach (GtkContainer *@var{container}, GtkCallback @var{callback}, gpointer @var{callback_data})
2220 @deftypefun void gtk_container_focus (GtkContainer *@var{container}, GtkDirectionType @var{direction})
2223 @deftypefun GList* gtk_container_children (GtkContainer @var{container})
2226 @gtkstdmacros{Container, CONTAINER}
2229 @node GtkCTree, GtkCurve, GtkContainer, Widgets
2230 @comment node-name, next, previous, up
2231 @section The multi-column tree widget
2233 @subsection Description
2235 The GtkCTree widget is a multi-columned list with a designated column, the
2236 @code{tree column}, to display hierarchically-organized data. Each node is
2237 either a folder (a branch of the tree) or a leaf. Nodes can be
2238 (recursively) expanded, collapsed, (un)selected, removed, moved, sorted etc.
2240 GtkCTree is a descendant of @pxref{GtkCList}. Therefore, a cell in a column
2241 other than the tree column can only contain a string, a pixmap, both or
2242 nothing. A node in the tree column can contain a string and up to two pixmaps
2243 and masks, indicating the "folder openend" and "folder closed" status.
2245 Compared to GtkCList, there is no concept of row numbers. Therefore, a number
2246 of GtkCList methods had to be re-implemented taking @code{GList *node}
2247 arguments instead of @code{gint row}.
2253 @deftypefn Signal void GtkCTree::tree_expand (GtkCTree *@var{ctree}, GList *@var{node})
2255 @deftypefn Signal void GtkCTree::tree_collapse (GtkCTree *@var{ctree}, GList *@var{node})
2257 @deftypefn Signal void GtkCTree::tree_move (GtkCTree *@var{ctree}, GList *@var{node}, GList *@var{new_parent}, GList *@var{new_sibling})
2259 @deftypefn Signal void GtkCTree::tree_select_row (GtkCTree *@var{ctree}, GList *@var{row}, gint @var{column})
2261 @deftypefn Signal void GtkCTree::tree_unselect_row (GtkCTree *@var{ctree}, GList *@var{row}, gint @var{column})
2264 @subsection Functions
2266 @deftypefun GtkType gtk_ctree_get_type (void)
2267 Returns the @code{GtkCTree} type identifier.
2270 @deftypefun GtkWidget* gtk_ctree_new (gint @var{columns}, gint @var{tree_column})
2271 Creates a new GtkCTree widget with the given number of columns and the given tree column.
2273 On success, a pointer to the newly created widget is returned, and @code{NULL} otherwise.
2276 @deftypefun GtkWidget* gtk_ctree_new_with_titles (gint @var{columns}, gint @var{tree_column}, gchar *@var{titles[]})
2277 Creates a new GtkCTree widget with the given number of columns and the given tree column. The column titles are initialized to the strings of the array @var{titles}.
2279 On success, a pointer to the newly created widget is returned, and @code{NULL} otherwise.
2282 @deftypefun GList* gtk_ctree_insert (GtkCTree *@var{ctree}, GList *@var{parent}, GList *@var{sibling}, gchar *@var{text[]}, guint8 @var{spacing}, GdkPixmap *@var{pixmap_closed}, GdkPixmap *@var{mask_closed}, GdkPixmap *@var{pixmap_opened}, GdkPixmap *@var{mask_opened}, gboolean @var{is_leaf}, gboolean @var{expanded})
2283 Inserts a new node at the given position. If @var{parent} == NULL, the node is
2284 inserted at root level. If @var{sibling} == NULL, the node is appended to the
2285 existing list of siblings. Otherwise, the node is inserted before @var{sibling}.
2286 If not NULL, the two pixmaps/masks are used to indicate the opened/closed status
2287 of the node. @var{spacing} is the number of pixels between pixmap and text.
2288 If @var{is_leaf} == TRUE, the node cannot have any children.
2289 The initial expanded/collapsed status is given by @var{expanded}.
2291 On success, the pointer to the newly inserted node is returned, and NULL
2295 @deftypefun void gtk_ctree_remove (GtkCTree *@var{ctree}, GList *@var{node})
2296 Removes the given node and all its children.
2299 @deftypefun void gtk_ctree_clear (GtkCTree *@var{ctree})
2300 Removes all nodes of @var{ctree}.
2303 @deftypefun void gtk_ctree_post_recursive (GtkCTree *@var{ctree}, GList *@var{node}, GtkCTreeFunc @var{func}, gpointer @var{data})
2304 Apply @var{func} to @var{node} and all its children, traversing @var{ctree} in
2308 @deftypefun void gtk_ctree_pre_recursive (GtkCTree *@var{ctree}, GList *@var{node}, GtkCTreeFunc @var{func}, gpointer @var{data})
2309 Apply @var{func} to @var{node} and all its children, traversing @var{ctree} in
2313 @deftypefun gboolean gtk_ctree_is_visible (GtkCTree *@var{ctree}, GList *@var{node})
2314 Returns the visibility status of the given node. A node is said to be visible
2315 if in the chain of parent nodes every node is expanded. Or : the node is
2316 currently being displayed (but not necessarily inside the viewing area).
2319 @c @deftypefun void gtk_ctree_scroll_to (GtkCTree *@var{ctree}, gint @var{row}, gint@var{column}, gfloat @var{row_align}, gfloat @var{col_align})
2320 @c Scroll the viewing area of the @code{GtkCtree} in @var{ctree} to @var{column}
2321 @c and @var{row}. The @var{row_align} and @var{col_align} are between zero and
2322 @c one, representing the location the row should appear on screen. Setting
2323 @c @var{row_align} or the @var{col_align} to 0.0 will be the top or left of the
2324 @c viewing area. Setting the @var{row_align} or @var{col_align} to 1.0 will
2325 @c be the bottom or right of the viewing area. If the @var{row} or @var{column}
2326 @c is -1 then there is no change.
2329 @gtkstdmacros{CTree, CTREE}
2332 @node GtkCurve, GtkGammaCurve, GtkCTree, Widgets
2333 @comment node-name, next, previous, up
2334 @section The curve widget
2336 @subsection Description
2338 Derived from @pxref{GtkDrawingArea}.
2344 @item GTK_CURVE_TYPE_LINEAR
2345 @item GTK_CURVE_TYPE_SPLINE
2346 @item GTK_CURVE_TYPE_FREE
2352 @subsection Functions
2354 @deftypefun guint gtk_curve_get_type (void)
2355 Returns the @code{GtkCurve} type identifier.
2358 @deftypefun GtkWidget* gtk_curve_new (void)
2359 Create a new @code{GtkCurve} returning the new widget as a pointer to a
2360 @code{GtkWidget} object.
2363 @deftypefun void gtk_curve_reset (GtkCurve *@var{curve})
2366 @deftypefun void gtk_curve_set_gamma (GtkCurve *@var{curve}, gfloat @var{gamma})
2369 @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})
2372 @deftypefun void gtk_curve_get_vector (GtkCurve *@var{curve}, int @var{veclen}, gfloat @var{vector[]})
2375 @deftypefun void gtk_curve_set_vector (GtkCurve *@var{curve}, int @var{veclen}, gfloat @var{vector[]})
2378 @deftypefun void gtk_curve_set_curve_type (GtkCurve *@var{curve}, GtkCurveType @var{type})
2381 @gtkstdmacros{Curve, CURVE}
2384 @node GtkGammaCurve, GtkDialog, GtkCurve, Widgets
2385 @comment node-name, next, previous, up
2386 @section The gamma curve widget
2388 @subsection Description
2390 Lets the user edit a gamma curve (a one-to-one mapping usually used to
2391 adjust the intensity of an image to the physical characteristics of the
2392 output device). You can set the minimum and maximum values for input
2393 and output. You can set the initial vector as well. You are guaranteed
2394 that every input value will have a (not necessarily unique) output value
2395 specified. Derived from @pxref{GtkVBox}. Makes use of @pxref{GtkCurve} to
2402 @subsection Functions
2404 @deftypefun guint gtk_gamma_curve_get_type (void)
2405 Returns the @code{GtkGamma} type identifier.
2408 @deftypefun GtkWidget* gtk_gamma_curve_new (void)
2409 Create a new @code{GtkGamma} returning the new widget as a pointer to a
2410 @code{GtkWidget} object.
2413 @gtkstdmacros{GammaCurve, GAMMACURVE}
2416 @node GtkDialog, GtkDrawingArea, GtkGammaCurve, Widgets
2417 @comment node-name, next, previous, up
2418 @section The dialog widget
2421 @subsection Description
2422 The dialog widget is a window (@pxref{GtkWindow}) that has a vertical box
2423 (@pxref{GtkVBox}), a horizontal box (@pxref{GtkHBox}), separated with a
2424 horizontal separator (@pxref{GtkHSeparator}).
2430 @subsection Functions
2432 @deftypefun guint gtk_dialog_get_type (void)
2433 Returns the @code{GtkDialog} type identifier.
2436 @deftypefun GtkWidget* gtk_dialog_new (void)
2437 Create a new @code{GtkDialog} object and return the new widget as a pointer
2438 to a @code{GtkWidget} object. @code{NULL} is returned on failure.
2441 @gtkstdmacros{Dialog, DIALOG}
2445 @node GtkDrawingArea, GtkEntry, GtkDialog, Widgets
2446 @comment node-name, next, previous, up
2447 @section The drawing area widget
2449 @subsection Description
2451 A base class for widgets that need a box to draw into. So far, only
2464 @subsection Functions
2466 @deftypefun guint gtk_drawing_area_get_type (void)
2467 Returns the @code{GtkDrawingArea} type identifier.
2470 @deftypefun GtkWidget* gtk_drawing_area_new (void)
2471 Create a new @code{GtkDrawingArea} object returning the new widget as a
2472 pointer to a @code{GtkWidget} object. @code{NULL} is returned on failure.
2475 @deftypefun void gtk_drawing_area_size (GtkDrawingArea *@var{darea}, gint @var{width}, gint @var{height})
2476 Set the size of the @var{darea} widget, created previously, to @var{width} and @var{height}.
2479 @gtkstdmacros{DrawingArea, DRAWING_AREA}
2483 @node GtkEntry, GtkEventBox, GtkDrawingArea, Widgets
2484 @comment node-name, next, previous, up
2485 @section The entry widget
2488 @subsection Description
2490 @comment Enter text into this widget. Derived from @pxref{GtkEditable}. Can be
2491 @comment set so it isn't editable.
2493 Enter text into this widget. Derived from GtkEditable. Can be
2494 set so it isn't editable.
2499 With this option it is possible to set the @var{text_max_length} to the
2500 value specified in the @var{max} option. This value is a guint16 value.
2504 With this option it is possible to 'preload' the text that will be displayed
2505 in the @code{entry} widget to the string pointed to by @var{text}.
2510 @deftypefn Signal void GtkEntry::insert_text (GtkEntry *@var{entry}, gchar *@var{text}, gint @var{length}, gint *@var{position})
2513 @deftypefn Signal void GtkEntry::delete_text (GtkEntry *@var{entry}, gint @var{start_pos}, gint @var{end_pos})
2516 @deftypefn Signal void GtkEntry::changed (GtkEntry *@var{entry})
2519 @deftypefn Signal void GtkEntry::set_text (GtkEntry *@var{entry})
2522 @deftypefn Signal void GtkEntry::activate (GtkEntry *@var{entry})
2525 @subsection Functions
2527 @deftypefun guint gtk_entry_get_type (void)
2528 Returns the @code{GtkEntry} type identifier.
2531 @deftypefun GtkWidget* gtk_entry_new (void)
2532 Create a new @code{GtkEntry} object. The new widget is returned
2533 as a pointer to a @code{GtkWidget} object. @code{NULL} is returned on
2537 @deftypefun GtkWidget* gtk_entry_new_with_max_length (guint16 @var{max})
2538 Create a new @code{GtkEntry} object initializing it with the value @var{max}.
2539 The new widget is returned as a pointer to a @code{GtkWidget} object.
2540 @code{NULL} is returned on failure.
2543 @deftypefun void gtk_entry_set_text (GtkEntry *@var{entry}, gchar *@var{text})
2544 Will set the text in the previously created @code{GtkEntry} object to
2545 @var{text}. It is important to not set the fields of the @code{GtkEntry}
2546 structure directly (or, for that matter, any type derived from
2550 @deftypefun void gtk_entry_append_text (GtkEntry *@var{entry}, gchar *@var{text})
2551 Append the text that is in the @var{text} argument to the widgets text. It is
2552 important to not set the fields of the @code{GtkEntry} structure directly.
2555 @deftypefun void gtk_entry_prepend_text (GtkEntry *@var{entry}, gchar *@var{text})
2556 Add the text in the @var{text} argument to the text in the @code{GtkEntry}
2557 widget. It is important to not set the fields of the @code{GtkEntry} structure
2561 @deftypefun void gtk_entry_set_position (GtkEntry *@var{entry}, gint @var{position})
2564 @deftypefun void gtk_entry_set_visibility (GtkEntry *@var{entry}, gint @var{visible})
2565 Will make the keystrokes entered into the @code{GtkEntry} object invisible
2566 when @var{visible} is @code{TRUE}. Defaults to @code{FALSE}.
2569 @deftypefun gchar* gtk_entry_get_text (GtkEntry *@var{entry})
2570 Returns the text that is contained in the @code{GtkEntry} as a pointer to a
2571 @code{gchar} variable.
2574 @gtkstdmacros{Entry, ENTRY}
2577 @node GtkEventBox, GtkFileSelection, GtkEntry, Widgets
2578 @comment node-name, next, previous, up
2579 @section The event box widget
2581 @subsection Description
2583 Derived from @pxref{GtkBin}. Used by @pxref{GtkTreeItem}.
2589 @subsection Functions
2590 @deftypefun guint gtk_event_box_get_type (void)
2591 Returns the @code{GtkEventBox} type identifier.
2594 @deftypefun GtkWidget* gtk_event_box_new (void)
2595 Create a new @code{GtkEventBox} returning the new widget as a pointer to
2596 a @code{GtkWidget} object. @code{NULL} is returned on failure.
2599 @gtkstdmacros{GtkEventBox, EVENT_BOX}
2602 @node GtkFileSelection, GtkFixed, GtkEventBox, Widgets
2603 @comment node-name, next, previous, up
2604 @section The file selection dialog widget
2606 @subsection Description
2618 @subsection Functions
2620 @deftypefun guint gtk_file_selection_get_type (void)
2621 Returns the @code{GtkFileSelection} type identifier.
2624 @deftypefun GtkWidget* gtk_file_selection_new (gchar *@var{title})
2625 Create a new @code{GtkFileSelection} object and return the new widget as a
2626 pointer to a @code{GtkWidget}. @code{NULL} is returned on failure.
2629 @deftypefun void gtk_file_selection_set_filename (GtkFileSelection *@var{filesel}, gchar *@var{filename})
2632 @deftypefun gchar* gtk_file_selection_get_filename (GtkFileSelection *@var{filesel})
2635 @gtkstdmacros{FileSelection, FILE_SELECTION}
2638 @node GtkFixed, GtkFrame, GtkFileSelection, Widgets
2639 @comment node-name, next, previous, up
2640 @section The fixed widget
2642 @subsection Description
2648 @subsection Functions
2650 @deftypefun guint gtk_fixed_get_type (void)
2651 Returns the @code{GtkFixed} type identifier.
2654 @deftypefun GtkWidget* gtk_fixed_new (void)
2655 Create a new @code{GtkFixed} object returning the new widget as a pointer to
2656 a @code{GtkWidget} object. @code{NULL} is returned on failure.
2659 @deftypefun void gtk_fixed_put_new (GtkFixed *@var{fixed}, GtkWidget *@var{widget}, gint16 @var{x}, gint16 @var{y})
2662 @deftypefun void gtk_fixed_move (GtkFixed *@var{fixed}, GtkWidget *@var{widget}, gint16 @var{x}, gint16 @var{y})
2665 @gtkstdmacros{Fixed, FIXED}
2668 @node GtkFrame, GtkGamma, GtkFixed, Widgets
2669 @comment node-name, next, previous, up
2670 @section The frame widget
2686 @subsection Description
2690 @subsection Functions
2692 @deftypefun guint gtk_frame_get_type (void)
2693 Returns the @code{GtkFrame} type identifier.
2696 @deftypefun GtkWidget* gtk_frame_new (gchar *@var{label})
2697 Create a new @code{GtkFrame} object initializing it with the value in
2698 @var{label}. The new widget is returned as a pointer to a @code{GtkWidget}
2699 object. @code{NULL} is returned on failure.
2702 @deftypefun void gtk_frame_set_label (GtkFrame *@var{frame}, gchar *@var{label})
2705 @deftypefun void gtk_frame_set_label_align (GtkFrame *@var{frame}, gfloat @var{xalign}, gfloat @var{yalign})
2708 @deftypefun void gtk_frame_set_shadow_type (GtkFrame *@var{frame}, GtkShadowType @var{type})
2711 @gtkstdmacros{Frame, FRAME}
2714 @node GtkGamma, GtkHBox, GtkFrame, Widgets
2715 @comment node-name, next, previous, up
2716 @section The gamma widget
2718 @subsection Description
2724 @subsection Functions
2726 @deftypefun guint gtk_gamma_curve_get_type (void)
2727 Returns the @code{GtkGamma} type identifier.
2730 @deftypefun GtkWidget* gtk_gamma_curve_new (void)
2731 Create a new @code{GtkGamma} object returning the new widget as a pointer
2732 to a @code{GtkWidget} object. @code{NULL} is returned on failure.
2735 @gtkstdmacros{Gamma, GAMMA}
2738 @node GtkHBox, GtkHButtonBox, GtkGamma, Widgets
2739 @comment node-name, next, previous, up
2740 @section The horizontal box widget
2743 @subsection Description
2748 This option controls whether each object in the box has the same size. In the
2749 case of the @code{GtkHBox}, this effects the width. If this option is set then
2750 the @var{expand} option to the @code{gtk_box_pack} (@pxref{GtkBox}) routines
2751 is always set to @code{TRUE}.
2755 This option controls the amount of space that is added between the objects
2756 packed into this @code{GtkVBox} object.
2761 @subsection Functions
2763 @deftypefun guint gtk_hbox_get_type (void)
2764 Returns the @code{GtkHBox} type identifier.
2767 @deftypefun GtkWidget* gtk_hbox_new (gint @var{homogeneous}, gint @var{spacing})
2768 Create a new @code{GtkHBox} object initializing it with the values in
2769 @var{homogeneous} and @var{spacing}. The new widget is returned as a pointer
2770 to a @code{GtkWidget} object. @code{NULL} is returned on failure.
2773 @gtkstdmacros{HBox, HBOX}
2776 @node GtkHButtonBox, GtkHPaned, GtkHBox, Widgets
2777 @comment node-name, next, previous, up
2778 @section The horizontal button box widget
2780 @subsection Description
2792 @subsection Functions
2794 @deftypefun guint gtk_hbutton_box_get_type (void)
2795 Returns the @code{GtkHButtonBox} type identifier.
2798 @deftypefun GtkWidget* gtk_hbutton_box_new (void)
2799 Create a new @code{GtkHButtonBox} object returning the new widget as a pointer
2800 to a @code{GtkWidget} object. @code{NULL} is returned on failure.
2803 @deftypefun void gtk_hbutton_box_set_spacing_default (gint @var{spacing})
2806 @deftypefun void gtk_hbutton_box_set_layout_default (gint @var{layout})
2809 @deftypefun gint gtk_hbutton_box_get_spacing_default (void)
2812 @deftypefun gint gtk_hbutton_box_get_layout_default (void)
2815 @gtkstdmacros {HButtonBox, HBUTTON_BOX}
2818 @node GtkHPaned, GtkHRuler, GtkHButtonBox, Widgets
2819 @comment node-name, next, previous, up
2820 @section The horizontal paned widget
2822 @subsection Description
2828 @subsection Functions
2830 @deftypefun void gtk_hpaned_get_type (void)
2831 Returns the @code{GtkHPaned} type identifier.
2834 @deftypefun GtkWidget* gtk_hpaned_new (void)
2835 Create a new @code{GtkHPaned} object returning the new widget as a pointer
2836 to a @code{GtkWidget} object.
2839 @gtkstdmacros{HPaned, HPANED}
2842 @node GtkHRuler, GtkHScale, GtkHPaned, Widgets
2843 @comment node-name, next, previous, up
2844 @section The horizontal ruler widget
2847 @subsection Description
2853 @subsection Functions
2855 @deftypefun guint gtk_hruler_get_type (void)
2856 Returns the @code{GtkHRuler} type identifier.
2859 @deftypefun GtkWidget* gtk_hruler_new (void)
2860 Create a new @code{GtkHRuler} object returning the new widget as a pointer
2861 to a @code{GtkWidget} object. @code{NULL} is returned on failure.
2864 @gtkstdmacros{HRuler, HRULER}
2868 @node GtkHScale, GtkHScrollbar, GtkHRuler, Widgets
2869 @comment node-name, next, previous, up
2870 @section The horizontal scale widget
2873 @subsection Description
2879 @subsection Functions
2881 @deftypefun guint gtk_hscale_get_type (void)
2882 Returns the @code{GtkHScale} type identifier.
2885 @deftypefun GtkWidget* gtk_hscale_new (GtkAdjustment *@var{adjustment})
2886 Create a new @code{GtkHScale} object returning the new widget as a pointer
2887 to a @code{GtkWidget} object. @code{NULL} is returned on failure.
2890 @gtkstdmacros{HScale, HSCALE}
2894 @node GtkHScrollbar, GtkHSeparator, GtkHScale, Widgets
2895 @comment node-name, next, previous, up
2896 @section The horizontal scrollbar widget
2899 @subsection Description
2905 @subsection Functions
2907 @deftypefun guint gtk_hscrollbar_get_type (void)
2908 Returns the @code{GtkHScrollbar} type identifier.
2911 @deftypefun GtkWidget* gtk_hscrollbar_new (GtkAdjustment *@var{adjustment})
2912 Create a new @code{GtkHScrollbar} object returning the new widget as a
2913 pointer to a @code{GtkWidget} object. @code{NULL} is returned on failure.
2916 @gtkstdmacros{HScrollbar, HSCROLLBAR}
2920 @node GtkHSeparator, GtkImage, GtkHScrollbar, Widgets
2921 @comment node-name, next, previous, up
2922 @section The horizontal separator widget
2925 @subsection Description
2931 @subsection Functions
2933 @deftypefun guint gtk_hseparator_get_type (void)
2934 Returns the @code{GtkHSeparator} type identifier.
2937 @deftypefun GtkWidget* gtk_hseparator_new (void)
2938 Create a new @code{GtkHSeparator} object returning the new widget as a pointer
2939 to a @code{GtkWidget} object. @code{NULL} is returned on failure.
2942 @gtkstdmacros{HSeparator, HSEPARATOR}
2946 @node GtkImage, GtkInputDialog, GtkHSeparator, Widgets
2947 @comment node-name, next, previous, up
2948 @section The image widget
2951 @subsection Description
2957 @subsection Functions
2959 @deftypefun guint gtk_image_get_type (void)
2960 Returns the @code{GtkImage} type identifier.
2963 @deftypefun GtkWidget* gtk_image_new (GdkImage *@var{val}, GdkBitmap *@var{mask})
2964 Create a new @code{GtkImage} object initializing it with the values in
2965 @var{val} and @var{mask}. The new widget is returned as a pointer to a
2966 @code{GtkWidget} object. @code{NULL} is returned on failure.
2969 @deftypefun void gtk_image_set (GtkImage *@var{image}, GdkImage *@var{val}, GdkBitmap *@var{mask})
2972 @deftypefun void gtk_image_get (GtkImage *@var{image}, GdkImage **@var{val}, GdkBitmap **@var{mask})
2975 @gtkstdmacros{Image, IMAGE}
2978 @node GtkInputDialog, GtkItem, GtkImage, Widgets
2979 @comment node-name, next, previous, up
2980 @section The input dialog widget
2982 @subsection Description
2988 @deftypefn Signal void GtkInputDialog::enable_device (GtkInputDialog *@var{inputd}, guint32 @var{devid}, gpointer *@var{data})
2991 @deftypefn Signal void GtkInputDialog::disable_device (GtkInputDialog *@var{inputd}, guint32 @var{devid}, gpointer *@var{data})
2994 @subsection Functions
2996 @deftypefun guint gtk_input_dialog_get_type (void)
2997 Returns the @code{GtkInputDialog} type identifier.
3000 @deftypefun GtkWidget* gtk_input_dialog_new (void)
3001 Create a new @code{GtkInputDialog} object and return the new widget as a
3002 pointer to a @code{GtkWidget} object. @code{NULL} is returned on failure.
3006 @gtkstdmacros{InputDialog, INPUTDIALOG}
3009 @node GtkItem, GtkLabel, GtkInputDialog, Widgets
3010 @comment node-name, next, previous, up
3011 @section The item widget
3014 @subsection Description
3018 @deftypefn Signal void GtkItem::select (GtkItem *@var{item})
3021 @deftypefn Signal void GtkItem::deselect (GtkItem *@var{item})
3024 @deftypefn Signal void GtkItem::toggle (GtkItem *@var{toggle})
3027 @subsection Functions
3029 @deftypefun guint gtk_item_get_type (void)
3030 Returns the @code{GtkItem} type identifier.
3033 @deftypefun void gtk_item_select (GtkItem *@var{item})
3036 @deftypefun void gtk_item_deselect (GtkItem *@var{item})
3039 @deftypefun void gtk_item_toggle (GtkItem *@var{item})
3042 @gtkstdmacros{Item, ITEM}
3046 @node GtkLabel, GtkList, GtkItem, Widgets
3047 @comment node-name, next, previous, up
3048 @section The label widget
3050 @subsection Description
3059 @subsection Functions
3061 @deftypefun guint gtk_label_get_type (void)
3062 Returns the @code{GtkLabel} type identifier.
3065 @deftypefun GtkWidget* gtk_label_new (GtkLabel *@var{label}, gchar *@var{str})
3066 Create a new @code{GtkLabel} object and initialize it with the
3067 text in @var{str}. The new widget is returned as a pointer to a
3068 @code{GtkWidget} object. @code{NULL} is returned on failure.
3071 @deftypefun void gtk_label_set (GtkLabel *@var{label}, gchar *@var{str})
3072 Set the @code{GtkLabel} label value to the value passed in the @var{str}
3076 @deftypefun void gtk_label_get (GtkLabel *@var{label}, gchar **@var{str})
3077 Copies the current value in the @code{GtkLabel} label field to the variable
3078 passed in the @var{str} argument.
3081 @gtkstdmacros{Label, LABEL}
3085 @node GtkList, GtkListItem, GtkLabel, Widgets
3086 @comment node-name, next, previous, up
3087 @section The list widget
3090 @subsection Description
3094 @deftypefn Signal void GtkList::selection_changed (GtkList *@var{list})
3097 @deftypefn Signal void GtkList::select_child (GtkList *@var{list}, GtkWidget *@var{child})
3100 @deftypefn Signal void GtkList::unselect_child (GtkList *@var{list}, GtkWidget *@var{child})
3103 @subsection Functions
3105 @deftypefun guint gtk_list_get_type (void)
3106 Returns the @code{GtkList} type identifier.
3109 @deftypefun GtkWidget* gtk_list_new (void)
3110 Create a new @code{GtkList} object and return the new widget as a pointer to
3111 a @code{GtkWidget} object. @code{NULL} is returned on failure.
3114 @deftypefun void gtk_list_insert_items (GtkList *@var{list}, GList *@var{items}, gint @var{position})
3117 @deftypefun void gtk_list_append_items (GtkList *@var{list}, GList *@var{items})
3120 @deftypefun void gtk_list_prepend_items (GtkList *@var{list}, GList *@var{items})
3123 @deftypefun void gtk_list_remove_items (GtkList *@var{list}, GList *@var{items})
3126 @deftypefun void gtk_list_clear_items (GtkList *@var{list}, gint @var{start}, gint @var{end})
3129 @deftypefun void gtk_list_select_item (GtkList *@var{list}, gint @var{item})
3132 @deftypefun void gtk_list_unselect_item (GtkList *@var{list}, gint @var{item})
3135 @deftypefun void gtk_list_select_child (GtkList *@var{list}, GtkWidget *@var{child})
3138 @deftypefun void gtk_list_unselect_child (GtkList *@var{list}, GtkWidget *@var{child})
3141 @deftypefun gint gtk_list_child_position (GtkList *@var{list}, GtkWidget *@var{child})
3144 @deftypefun void gtk_list_set_selection_mode (GtkList *@var{list}, GtkSelectionMode @var{mode})
3147 @gtkstdmacros{List, LIST}
3151 @node GtkListItem, GtkMenu, GtkList, Widgets
3152 @comment node-name, next, previous, up
3153 @section The list item widget
3156 @subsection Description
3162 @subsection Functions
3164 @deftypefun guint gtk_list_item_get_type (void)
3165 Returns the @code{GtkListItem} type identifier.
3168 @deftypefun GtkWidget* gtk_list_item_new (void)
3169 Create a new @code{GtkListItem} object and return the new widget as a
3170 pointer to a @code{GtkWidget} object. @code{NULL} is returned on failure.
3173 @deftypefun GtkWidget* gtk_list_item_new_with_label (gchar *@var{label})
3174 Create a new @code{GtkListItem} object initializing with the value @var{label}.
3175 The new widget is returned as a pointer to a @code{GtkWidget} object.
3176 @code{NULL} is returned on failure.
3179 @deftypefun void gtk_list_item_select (GtkListItem *@var{list_item})
3182 @deftypefun void gtk_list_item_deselect (GtkListItem *@var{list_item})
3185 @gtkstdmacros{ListItem, LIST_ITEM}
3189 @node GtkMenu, GtkMenuBar, GtkListItem, Widgets
3190 @comment node-name, next, previous, up
3191 @section The menu widget
3194 @subsection Description
3200 @subsection Functions
3202 @deftypefun guint gtk_menu_get_type (void)
3203 Returns the @code{GtkMenu} type identifier.
3206 @deftypefun GtkWidget* gtk_menu_new (void)
3207 Create a new @code{GtkMenu} object returning the new widget as a pointer to
3208 a @code{GtkWidget}. @code{NULL} is returned on failure.
3211 @deftypefun void gtk_menu_append (GtkMenu *@var{menu}, GtkWidget *@var{child})
3214 @deftypefun void gtk_menu_prepend (GtkMenu *@var{menu}, GtkWidget *@var{child})
3217 @deftypefun void gtk_menu_insert (GtkMenu *@var{menu}, GtkWidget *@var{child}, gint @var{position})
3220 @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})
3223 @deftypefun void gtk_menu_popdown (GtkMenu *@var{menu})
3226 @deftypefun GtkWidget* gtk_menu_get_active (GtkMenu *@var{menu})
3229 @deftypefun void gtk_menu_set_active (GtkMenu *@var{menu})
3232 @deftypefun void gtk_menu_set_accelerator_table (GtkMenu *@var{menu}, GtkAcceleratorTable *@var{table})
3235 @gtkstdmacros{Menu, MENU}
3239 @node GtkMenuBar, GtkMenuItem, GtkMenu, Widgets
3240 @comment node-name, next, previous, up
3241 @section The menu bar widget
3243 @subsection Description
3252 @subsection Functions
3254 @deftypefun guint gtk_menu_bar_get_type (void)
3255 Returns the @code{GtkMenuBar} type identifier.
3258 @deftypefun GtkWidget* gtk_menu_bar_new (void)
3259 Create a new @code{GtkMenuBar} object returning the new widget as a pointer
3260 to a @code{GtkWidget} object. @code{NULL} is returned on failure.
3263 @deftypefun void gtk_menu_bar_append (GtkMenuBar *@var{menu_bar}, GtkWidget *@var{child})
3266 @deftypefun void gtk_menu_bar_prepend (GtkMenuBar *@var{menu_bar}, GtkWidget *@var{child})
3269 @deftypefun void gtk_menu_bar_insert (GtkMenuBar *@var{menu_bar}, GtkWidget *@var{child}, gint @var{position})
3272 @gtkstdmacros{MenuBar, MENU_BAR}
3276 @node GtkMenuItem, GtkMenuShell, GtkMenuBar, Widgets
3277 @comment node-name, next, previous, up
3278 @section The menu item widget
3281 @subsection Description
3287 @deftypefn Signal void GtkMenuItem::activate (GtkMenuItem *@var{menu_item})
3290 @subsection Functions
3292 @deftypefun guint gtk_menu_item_get_type (void)
3293 Returns the @code{GtkMenuItem} type identifier.
3296 @deftypefun GtkWidget* gtk_menu_item_new (void)
3297 Create a new @code{GtkMenuItem} object returning the new widget as a pointer
3298 to a @code{GtkWidget} object. @code{NULL} is returned on failure.
3301 @deftypefun GtkWidget* gtk_menu_item_new_with_label (gchar *@var{label})
3302 Create a new @code{GtkMenuItem} object initializing it with the value in
3303 @var{label}. The new widget is returned as a pointer to a @code{GtkWidget}
3304 object. @code{NULL} is returned on failure.
3307 @deftypefun void gtk_menu_item_set_submenu (GtkMenuItem *@var{menu_item}, GtkWidget *@var{submenu})
3310 @deftypefun void gtk_menu_item_set_placement (GtkMenuItem *@var{menu_item}, GtkSubmenuPlacement @var{placement})
3313 @deftypefun void gtk_menu_item_accelerator_size (GtkMenuItem *@var{menu_item})
3316 @deftypefun void gtk_menu_item_accelerator_text (GtkMenuItem *@var{menu_item}, gchar *@var{buffer})
3319 @deftypefun void gtk_menu_item_configure (GtkMenuItem *@var{menu_item}, gint @var{show_toggle_indicator}, gint @var{show_submenu_indicator})
3322 @deftypefun void gtk_menu_item_select (GtkMenuItem *@var{menu_item})
3325 @deftypefun void gtk_menu_item_deselect (GtkMenuItem *@var{menu_item})
3328 @deftypefun void gtk_menu_item_activate (GtkMenuItem *@var{menu_item})
3331 @gtkstdmacros{MenuItem, MENU_ITEM}
3335 @node GtkMenuShell, GtkMisc, GtkMenuItem, Widgets
3336 @comment node-name, next, previous, up
3337 @section The menu shell widget
3340 @subsection Description
3346 @deftypefn Signal void GtkMenuShell::deactivate (GtkMenuShell *@var{menu_shell})
3349 @subsection Functions
3351 @deftypefun guint gtk_menu_shell_get_type (void)
3352 Returns the @code{GtkMenuShell} type identifier.
3355 @deftypefun void gtk_menu_shell_append (GtkMenuShell *@var{menu_shell}, GtkWidget *@var{child})
3358 @deftypefun void gtk_menu_shell_prepend (GtkMenuShell *@var{menu_shell}, GtkWidget *@var{child})
3361 @deftypefun void gtk_menu_shell_insert (GtkMenuShell *@var{menu_shell}, GtkWidget *@var{child}, gint @var{position})
3364 @deftypefun void gtk_menu_shell_deactivate (GtkMenuShell *@var{menu_shell})
3367 @gtkstdmacros{MenuShell, MENU_SHELL}
3371 @node GtkMisc, GtkNotebook, GtkMenuShell, Widgets
3372 @comment node-name, next, previous, up
3373 @section The misc widget
3375 @subsection Description
3393 @subsection Functions
3395 @deftypefun guint gtk_misc_get_type (void)
3396 Returns the @code{GtkMisc} type identifier.
3399 @deftypefun void gtk_misc_set_alignment (GtkMisc *@var{misc}, gfloat @var{xalign}, gfloat @var{yalign})
3402 @deftypefun void gtk_misc_set_padding (GtkMisc *@var{misc}, gint @var{xpad}, gint @var{ypad})
3405 @gtkstdmacros{Misc, MISC}
3409 @node GtkNotebook, GtkOptionMenu, GtkMisc, Widgets
3410 @comment node-name, next, previous, up
3411 @section The notebook widget
3413 @subsection Description
3419 @subsection Functions
3421 @deftypefun guint gtk_notebook_get_type (void)
3422 Returns the @code{GtkNotebook} type identifier.
3425 @deftypefun GtkWidget* gtk_notebook_new (void)
3426 Create a new @code{GtkNotebook} object returning the new widget as a pointer
3427 to a @code{GtkWidget} object. @code{NULL} is returned on a failure.
3430 @deftypefun void gtk_notebook_append_page (GtkNotebook *@var{notebook}, GtkWidget *@var{child}, GtkWidget *@var{tab_label})
3433 @deftypefun void gtk_notebook_prepend_page (GtkNotebook *@var{notebook}, GtkWidget *@var{child}, GtkWidget *@var{tab_label})
3436 @deftypefun void gtk_notebook_insert_page (GtkNotebook *@var{notebook}, GtkWidget *@var{child}, GtkWidget *@var{tab_label}, gint @var{position})
3439 @deftypefun void gtk_notebook_remove_page (GtkNotebook *@var{notebook}, gint @var{page_num})
3442 @deftypefun void gtk_notebook_set_page (GtkNotebook *@var{notebook}, gint @var{page_num})
3445 @deftypefun void gtk_notebook_next_page (GtkNotebook *@var{notebook})
3448 @deftypefun void gtk_notebook_prev_page (GtkNotebook *@var{notebook})
3451 @deftypefun void gtk_notebook_set_tab_pos (GtkNotebook *@var{notebook}, GtkPositionType @var{pos})
3454 @deftypefun void gtk_notebook_set_show_tabs (GtkNotebook *@var{notebook}, gint @var{show_tabs})
3457 @deftypefun void gtk_notebook_set_show_border (GtkNotebook *@var{notebook}, gint @var{show_border})
3460 @gtkstdmacros{Notebook, NOTEBOOK}
3464 @node GtkOptionMenu, GtkPaned, GtkNotebook, Widgets
3465 @comment node-name, next, previous, up
3466 @section The option menu widget
3468 @subsection Description
3477 @subsection Functions
3479 @deftypefun guint gtk_option_menu_get_type (void)
3480 Returns the @code{GtkOptionMenu} type identifier.
3483 @deftypefun GtkWidget* gtk_option_menu_new (void)
3484 Create a new @code{GtkOptionMenu} object returning the new widget as a
3485 pointer to a @code{GtkWidget} object. @code{NULL} is returned on failure.
3488 @deftypefun GtkWidget* gtk_option_menu_get_menu (GtkOptionMenu *@var{option_menu})
3491 @deftypefun void gtk_option_menu_set_menu (GtkOptionMenu *@var{option_menu}, GtkWidget *@var{menu})
3494 @deftypefun void gtk_option_menu_remove_menu (GtkOptionMenu *@var{option_menu})
3497 @deftypefun void gtk_option_menu_set_history (GtkOptionMenu *@var{option_menu}, gint @var{index})
3500 @gtkstdmacros{OptionMenu, OPTION_MENU}
3503 @node GtkPaned, GtkPixmap, GtkOptionMenu, Widgets
3504 @comment node-name, next, previous, up
3505 @section The paned widget
3507 @subsection Description
3513 @subsection Functions
3515 @deftypefun guint gtk_paned_get_type (void)
3516 Returns the @code{GtkPaned} type identifier.
3519 @deftypefun void gtk_paned_add1 (GtkPaned *@var{paned}, GtkWidget *@var{child})
3522 @deftypefun void gtk_paned_add2 (GtkPaned *@var{paned}, GtkWidget *@var{child})
3525 @deftypefun void gtk_paned_handle_size (GtkPaned *@var{paned}, guint16 @var{size})
3529 @deftypefun void gtk_paned_gutter_size (GtkPaned *@var{paned}, guint16 @var{size})
3532 @gtkstdmacros{Paned, PANED}
3535 @node GtkPixmap, GtkPreview, GtkPaned, Widgets
3536 @comment node-name, next, previous, up
3537 @section The pixmap widget
3540 @subsection Description
3546 @subsection Functions
3548 @deftypefun guint gtk_pixmap_get_type (void)
3549 Returns the @code{GtkPixmap} type identifier.
3552 @deftypefun GtkWidget* gtk_pixmap_new (GdkPixmap *@var{normal}, GdkPixmap *@var{active}, GdkPixmap *@var{prelight}, GdkPixmap *@var{selected}, GdkPixmap *@var{insensitive})
3555 @deftypefun void gtk_pixmap_set (GtkPixmap *@var{pixmap}, GdkPixmap *@var{val}, GtkStateType @var{state})
3558 @deftypefun void gtk_pixmap_get (GtkPixmap *@var{pixmap}, GdkPixmap **@var{val}, GtkStateType @var{state})
3561 @gtkstdmacros{Pixmap, PIXMAP}
3565 @node GtkPreview, GtkProgressBar, GtkPixmap, Widgets
3566 @comment node-name, next, previous, up
3567 @section The preview widget
3569 @subsection Description
3584 @subsection Functions
3586 @deftypefun guint gtk_preview_get_type (void)
3587 Returns the @code{GtkPreview} type identifier.
3590 @deftypefun void gtk_preview_uninit (void)
3593 @deftypefun GtkWidget* gtk_preview_new (GtkPreviewType @var{type})
3594 Create a new @code{GtkPreview} object initializing it with the values in
3595 @var{type}. The new widget is returned as a pointer to a @code{GtkWidget}
3596 object. @code{NULL} is returned on failure.
3599 @deftypefun void gtk_preview_size (GtkPreview *@var{preview}, gint @var{width}, gint @var{height})
3600 Set the size of the @var{preview} object to @var{width} and @var{height}.
3603 @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})
3606 @deftypefun void gtk_preview_put_row (GtkPreview *@var{preview}, guchar *@var{src}, guchar *@var{dest}, gint @var{x}, gint @var{y}, gint @var{w})
3609 @deftypefun void gtk_preview_draw_row (GtkPreview *@var{preview}, guchar @var{data}, gint @var{x}, gint @var{y}, gint @var{w})
3612 @deftypefun void gtk_preview_set_expand (GtkPreview *@var{preview}, gint @var{expand})
3615 @deftypefun void gtk_preview_set_gamma (double @var{gamma})
3618 @deftypefun void gtk_preview_set_color_cube (guint @var{nred_shades}, guint @var{ngreen_shades}, guint @var{nblue_shades}, guint @var{ngray_shades})
3621 @deftypefun void gtk_preview_set_install_cmap (gint @var{install_cmap})
3624 @deftypefun void gtk_preview_set_reserved (gint @var{nreserved})
3627 @deftypefun GdkVisual* gtk_preview_get_visual (void)
3630 @deftypefun GdkColormap* gtk_preview_get_cmap (void)
3633 @deftypefun GtkPreviewInfo* gtk_preview_get_info (void)
3636 @gtkstdmacros{Preview, PREVIEW}
3640 @node GtkProgressBar, GtkRadioButton, GtkPreview, Widgets
3641 @comment node-name, next, previous, up
3642 @section The progress bar widget
3645 @subsection Description
3654 @subsection Functions
3656 @deftypefun guint gtk_progress_bar_get_type (void)
3657 Returns the @code{GtkProgressBar} type identifier.
3660 @deftypefun GtkWidget* gtk_progress_bar_new (void)
3661 Create a new @code{GtkProgressBar} object returning the new widget as a
3662 pointer to a @code{GtkWidget} object. @code{NULL} is returned on failure.
3665 @deftypefun void gtk_progress_bar_update (GtkProgressBar *@var{pbar}, gfloat @var{percentage})
3666 Cause the @code{GtkProgressBar} to update its visual appearance to reflect the
3670 @gtkstdmacros{ProgressBar, PROGRESS_BAR}
3674 @node GtkRadioButton, GtkRadioMenuItem, GtkProgressBar, Widgets
3675 @comment node-name, next, previous, up
3676 @section The radio button widget
3678 @subsection Description
3690 @subsection Functions
3692 @deftypefun guint gtk_radio_button_get_type (void)
3693 Returns the @code{GtkRadioButton} type identifier.
3696 @deftypefun GtkWidget* gtk_radio_button_new (GSList *@var{group})
3697 Create a new @code{GtkRadioButton} object initializing it with the value
3698 in the @var{group} argument. The new widget is returned as a pointer to a
3699 @code{GtkWidget} object. @code{NULL} is returned on failure.
3702 @deftypefun GtkWidget* gtk_radio_button_new_with_label (GSList *@var{group}, gchar *@var{label})
3703 Create a new @code{GtkRadioButton} object initializing it with the values in
3704 the @var{group} and @var{label} arguments. The new widget is returned as a
3705 pointer to @code{GtkWidget} object. @code{NULL} is returned on failure.
3708 @deftypefun GSList* gtk_radio_button_group (GtkRadioButton *@var{radio_button})
3711 @gtkstdmacros{RadioButton, RADIO_BUTTON}
3715 @node GtkRadioMenuItem, GtkRange, GtkRadioButton, Widgets
3716 @comment node-name, next, previous, up
3717 @section The radio button widget
3720 @subsection Description
3732 @subsection Functions
3734 @deftypefun guint gtk_radio_menu_item_get_type (void)
3735 Returns the @code{GtkRadioMenuItem} type identifier.
3738 @deftypefun GtkWidget* gtk_radio_menu_item_new (GSList *@var{group})
3739 Create a new @code{GtkRadioMenuItem} object and initialize it with the
3740 values in @var{group}. The new widget is returned as a pointer to a
3741 @code{GtkWidget} object. @code{NULL} is returned on failure.
3744 @deftypefun GtkWidget* gtk_radio_menu_item_new_with_label (GSList *@var{group}, gchar *@var{label})
3747 @deftypefun GSList* gtk_radio_menu_item_group (GtkRadioMenuItem *@var{radio_menu_item})
3750 @gtkstdmacros{RadioMenuItem, RADIO_MENU_ITEM}
3754 @node GtkRange, GtkRuler, GtkRadioMenuItem, Widgets
3755 @comment node-name, next, previous, up
3756 @section The range widget
3758 @subsection Description
3764 @subsection Functions
3766 @deftypefun guint gtk_range_get_type (void)
3767 Returns the @code{GtkRange} type identifier.
3770 @deftypefun GtkAdjustment* gtk_range_get_adjustment (GtkRange *@var{range})
3773 @deftypefun void gtk_range_set_update_policy (GtkRange *@var{range}, GtkUpdatePolicy @var{policy})
3776 @deftypefun void gtk_range_set_adjustment (GtkRange *@var{range}, GtkAdjustment *@var{adjustment})
3779 @deftypefun void gtk_range_draw_background (GtkRange *@var{range})
3782 @deftypefun void gtk_range_draw_trough (GtkRange *@var{range})
3785 @deftypefun void gtk_range_draw_slider (GtkRange *@var{range})
3788 @deftypefun void gtk_range_draw_step_forw (GtkRange *@var{range})
3791 @deftypefun void gtk_range_draw_step_back (GtkRange *@var{range})
3794 @deftypefun void gtk_range_slider_update (GtkRange *@var{range})
3797 @deftypefun gint gtk_range_trough_click (GtkRange *@var{range}, gint @var{x}, gint @var{y})
3800 @deftypefun void gtk_range_default_hslider_update (GtkRange *@var{range})
3803 @deftypefun void gtk_range_default_vslider_update (GtkRange *@var{range})
3806 @deftypefun gint gtk_range_default_htrough_click (GtkRange *@var{range}, gint @var{x}, gint @var{y})
3809 @deftypefun gint gtk_range_default_vtrough_click (GtkRange *@var{range}, gint @var{x}, gint @var{y})
3812 @deftypefun void gtk_range_default_hmotion (GtkRange *@var{range}, gint @var{xdelta}, gint @var{ydelta})
3815 @deftypefun void gtk_range_default_vmotion (GtkRange *@var{range}, gint @var{xdelta}, gint @var{ydelta})
3818 @deftypefun gfloat gtk_range_calc_value (GtkRange *@var{range}, gint @var{position})
3821 @gtkstdmacros{Range, RANGE}
3825 @node GtkRuler, GtkScale, GtkRange, Widgets
3826 @comment node-name, next, previous, up
3827 @section The ruler widget
3829 @subsection Description
3850 @subsection Functions
3852 @deftypefun guint gtk_ruler_get_type (void)
3853 Returns the @code{GtkRuler} type identifier.
3856 @deftypefun void gtk_ruler_set_metric (GtkRuler *@var{ruler}, GtkMetricType @var{metric})
3859 @deftypefun void gtk_ruler_set_range (GtkRuler *@var{ruler}, gfloat @var{lower}, gfloat @var{upper}, gfloat @var{position}, gfloat @var{max_size})
3862 @deftypefun void gtk_ruler_draw_ticks (GtkRuler *@var{ruler})
3865 @deftypefun void gtk_ruler_draw_pos (GtkRuler *@var{ruler})
3868 @gtkstdmacros{Ruler, RULER}
3872 @node GtkScale, GtkScrollbar, GtkRuler, Widgets
3873 @comment node-name, next, previous, up
3874 @section The scale widget
3877 @subsection Description
3892 @subsection Functions
3894 @deftypefun guint gtk_scale_get_type (void)
3895 Returns the @code{GtkScale} type identifier.
3898 @deftypefun void gtk_scale_set_digits (GtkScale *@var{scale}, gint @var{digits})
3901 @deftypefun void gtk_scale_set_draw_value (GtkScale *@var{scale}, gint @var{draw_value})
3904 @deftypefun void gtk_scale_set_value_pos (GtkScale *@var{scale}, gint @var{pos})
3907 @deftypefun gint gtk_scale_value_width (GtkScale *@var{scale})
3910 @deftypefun void gtk_scale_draw_value (GtkScale *@var{scale})
3913 @gtkstdmacros{Scale, SCALE}
3917 @node GtkScrollbar, GtkScrolledWindow, GtkScale, Widgets
3918 @comment node-name, next, previous, up
3919 @section The scrollbar widget
3922 @subsection Description
3928 @subsection Functions
3930 @deftypefun guint gtk_scrollbar_get_type (void)a
3931 Returns the @code{GtkScrollbar} type identifier.
3934 @gtkstdmacros{Scrollbar, SCROLLBAR}
3938 @node GtkScrolledWindow, GtkSeparator, GtkScrollbar, Widgets
3939 @comment node-name, next, previous, up
3940 @section The scrolled window widget
3943 @subsection Description
3949 @subsection Functions
3951 @deftypefun guint gtk_scrolled_window_get_type (void)
3952 Returns the @code{GtkScrolledWindow} type identifier.
3955 @deftypefun GtkWidget* gtk_scrolled_window_new (GtkAdjustment *@var{hadjustment}, GtkAdjustment *@var{vadjustment})
3956 Create a new @code{GtkScrolledWindow} object initializing it with the values in
3957 @var{adjustment} and @var{adjustment}. The new widget is returned as a
3958 pointer to a @code{GtkWidget} object. @code{NULL} is returned on failure.
3961 @deftypefun GtkAdjustment* gtk_scrolled_window_get_hadjustment (GtkScrolledWindow *@var{scrolled_window})
3964 @deftypefun GtkAdjustment* gtk_scrolled_window_get_vadjustment (GtkScrolledWindow *@var{scrolled_window})
3967 @deftypefun void gtk_scrolled_window_set_policy (GtkScrolledWindow *@var{scrolled_window}, GtkPolicyType @var{hscrollbar_policy}, GtkPolicyType @var{vscrollbar_policy})
3970 @gtkstdmacros{ScrolledWindow, SCROLLED_WINDOW}
3974 @node GtkSeparator, GtkStatusbar, GtkScrolledWindow, Widgets
3975 @comment node-name, next, previous, up
3976 @section The separator widget
3979 @subsection Description
3985 @subsection Functions
3987 @deftypefun guint gtk_separator_get_type (void)
3988 Returns the @code{GtkSeparator} type identifier.
3991 @gtkstdmacros{Separator, SEPARATOR}
3994 @node GtkStatusbar, GtkTable, GtkSeparator, Widgets
3995 @comment node-name, next, previous, up
3996 @section The statusbar widget
3998 @subsection Description
4004 @subsection Functions
4006 @deftypefun guint gtk_statusbar_get_type (void)
4007 Returns the @code{GtkStatusbar} type identifier.
4010 @deftypefun GtkWidget* gtk_statusbar_new (void)
4011 Create a new @code{GtkStatusbar} object returning the new widget as a pointer
4012 to a @code{GtkWidget} object. @code{NULL} is returned on failure.
4015 @deftypefun gint gtk_statusbar_push (GtkStatusbar *@var{statusbar}, gchar *@var{text})
4018 @deftypefun void gtk_statusbar_pop (GtkStatusbar *@var{statusbar}, gint @var{context_id})
4021 @gtkstdmacros{Statusbar, STATUSBAR}
4024 @node GtkTable, GtkText, GtkStatusbar, Widgets
4025 @comment node-name, next, previous, up
4026 @section The table widget
4028 @subsection Description
4039 This option controls whether all child widgets in the @code{GtkTable} will
4040 be of the same size. The child widgets will be the size of the largest child.
4045 @subsection Functions
4047 @deftypefun guint gtk_table_get_type (void)
4048 Returns the @code{GtkTable} type identifier.
4051 @deftypefun GtkWidget* gtk_table_new (gint @var{rows}, gint @var{columns}, gint @var{homogeneous})
4052 Create a new @code{GtkTable} object initializing it with the values in
4053 @var{rows}, @var{columns} and @var{homogeneous}. The new widget is returned
4054 as a pointer to a @code{GtkWidget}. @code{NULL} is returned on failure.
4057 @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})
4060 @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})
4063 @deftypefun void gtk_table_set_row_spacing (GtkTable *@var{table}, gint @var{row}, gint @var{spacing})
4066 @deftypefun void gtk_table_set_col_spacing (GtkTable *@var{table}, gint @var{col}, gint @var{spacing})
4069 @deftypefun void gtk_table_set_row_spacings (GtkTable *@var{table}, gint @var{spacing})
4072 @deftypefun void gtk_table_set_col_spacings (GtkTable *@var{table}, gint @var{spacing})
4075 @gtkstdmacros{Table, TABLE}
4079 @node GtkText, GtkToggleButton, GtkTable, Widgets
4080 @comment node-name, next, previous, up
4081 @section The text widget
4084 @subsection Description
4088 @subsection Functions
4090 @deftypefun guint gtk_text_get_type (void)
4091 Returns the @code{GtkText} type identifier.
4094 @deftypefun GtkWidget* gtk_text_new (GtkAdjustment *@var{hadj}, GtkAdjustment *@var{vadj});
4095 Create a new @code{GtkText} object initializing it with the values in
4096 @var{hadj} and @var{vadj}. The new widget is returned as a pointer to a
4097 @code{GtkWidget}. @code{NULL} is returned on failure.
4100 @deftypefun void gtk_text_set_editable (GtkText *@var{text}, gint @var{editable})
4103 @deftypefun void gtk_text_set_adjustments (GtkText *@var{text}, GtkAdjustment *@var{hadj}, GtkAdjustment *@var{vadj})
4106 @deftypefun void gtk_text_set_point (GtkText *@var{text}, guint @var{index})
4109 @deftypefun guint gtk_text_get_point (GtkText *@var{text})
4112 @deftypefun guint gtk_text_get_length (GtkText *@var{text})
4115 @deftypefun void gtk_text_freeze (GtkText *@var{text})
4118 @deftypefun void gtk_text_thaw (GtkText *@var{text})
4121 @deftypefun void gtk_text_insert (GtkText *@var{text}, GdkFont *@var{font}, GdkColor *@var{fore}, GdkColor *@var{back}, char *@var{chars}, gint @var{length})
4124 @deftypefun gint gtk_text_forward_delete (GtkText *@var{text}, guint @var{nchars})
4127 @deftypefun gint gtk_text_backward_delete (GtkText *@var{text}, guint @var{nchars})
4131 @gtkstdmacros{Text, TEXT}
4135 @node GtkToggleButton, GtkToolbar, GtkText, Widgets
4136 @comment node-name, next, previous, up
4137 @section The toggle button widget
4140 @subsection Description
4142 Another form of button (@pxref{GtkButton}) with two states: on and off.
4143 The appearance is that of a button which stays pressed on the first
4144 click, and is released on the second click.
4153 @deftypefn Signal void GtkToggleButton::toggled (GtkToggleButton *@var{toggle_button})
4156 @subsection Functions
4158 @deftypefun guint gtk_toggle_button_get_type (void)
4159 Returns the @code{GtkToggleButton} type identifier.
4162 @deftypefun GtkWidget* gtk_toggle_button_new (void)
4163 Create a new @code{GtkToggleButton} object returning the new widget as a
4164 pointer to a @code{GtkWidget} object. @code{NULL} is returned on failure.
4167 @deftypefun GtkWidget* gtk_toggle_button_new_with_label (gchar *@var{label})
4168 Create a new @code{GtkToggleButton} object initializing it with the values in
4169 @var{label}. The new widget is returned as a pointer to a @code{GtkWidget}
4170 object. @code{NULL} is returned on failure.
4173 @deftypefun void gtk_toggle_button_set_mode (GtkToggleButton *@var{toggle_button}, gint @var{draw_indicator})
4176 @deftypefun void gtk_toggle_button_set_state (GtkToggleButton *@var{toggle_button}, gint @var{state})
4179 @deftypefun void gtk_toggle_button_toggled (GtkToggleButton *@var{toggle_button})
4182 @gtkstdmacros{ToggleButton, TOGGLE_BUTTON}
4186 @node GtkToolbar, GtkTooltips, GtkToggleButton, Widgets
4187 @comment node-name, next, previous, up
4188 @section The tool bar widget
4190 @subsection Description
4196 @item GTK_ORIENTATION_HORIZONTAL
4198 @item GTK_ORIENTATION_VERTICAL
4204 @item GTK_TOOLBAR_ICONS
4205 @item GTK_TOOLBAR_TEXT
4206 @item GTK_TOOLBAR_BOTH
4215 @subsection Functions
4217 @deftypefun guint gtk_toolbar_get_type (void)
4218 Returns the @code{GtkToolbar} type identifier.
4221 @deftypefun GtkWidget* gtk_toolbar_new (GtkOrientation @var{orientation}, GtkToolbarStyle @var{style})
4222 Create a new @code{GtkToolbar} object initializing it with the values
4223 @var{orientation} and @var{style}. @code{NULL} is returned on failure.
4226 @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})
4229 @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})
4232 @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})
4235 @deftypefun void gtk_toolbar_append_space (GtkToolbar *@var{toolbar})
4238 @deftypefun void gtk_toolbar_prepend_space (GtkToolbar *@var{toolbar})
4241 @deftypefun void gtk_toolbar_insert_space (GtkToolbar *@var{toolbar}, gint @var{position})
4244 @deftypefun void gtk_toolbar_set_orientation (GtkToolbar *@var{toolbar}, GtkOrientation @var{orientation})
4247 @deftypefun void gtk_toolbar_set_style (GtkToolbar *@var{toolbar}, GtkToolbarStyle @var{style})
4248 Set the @var{style} of the @var{toolbar} to @var{style}.
4251 @deftypefun void gtk_toolbar_set_space_size (GtkToolbar *@var{toolbar}, gint @var{space_size})
4254 @deftypefun void gtk_toolbar_set_tooltips (GtkToolbar *@var{toolbar}, gint @var{enable})
4258 @gtkstdmacros{Toolbar, TOOLBAR}
4262 @node GtkTooltips, GtkTree, GtkToolbar, Widgets
4263 @comment node-name, next, previous, up
4264 @section The tool tips widget
4266 @subsection Description
4272 @subsection Functions
4274 @deftypefun GtkTooltips* gtk_tooltips_new (void)
4275 Create a new @code{GtkTooltips} object returning the new widget as a
4276 pointer to a @code{GtkWidget} object. @code{NULL} is returned on failure.
4279 @deftypefun GtkTooltips* gtk_tooltips_ref (GtkTooltips *@var{tooltips})
4282 @deftypefun void gtk_tooltips_unref (GtkTooltips *@var{tooltips})
4285 @deftypefun void gtk_tooltips_free_string (gpointer @var{data}, gpointer @var{user_data})
4288 @deftypefun void gtk_tooltips_enable (GtkTooltips *@var{tooltips})
4291 @deftypefun void gtk_tooltips_disable (GtkTooltips *@var{tooltips})
4294 @deftypefun void gtk_tooltips_set_delay (GtkTooltips *@var{tooltips}, GtkWidget *@var{widget}, gchar *@var{tips_text})
4297 @deftypefun void gtk_tooltips_set_colors (GtkTooltips *@var{tooltips}, GdkColor *@var{background}, GdkColor *@var{foreground})
4301 @gtkstdmacros{Tooltips, TOOLTIPS}
4305 @node GtkTree, GtkTreeItem, GtkTooltips, Widgets
4306 @comment node-name, next, previous, up
4307 @section The tree widget
4310 @subsection Description
4316 @subsection Functions
4318 @deftypefun guint gtk_tree_get_type (void)
4319 Returns the @code{GtkTree} type identifier.
4322 @deftypefun GtkWidget* gtk_tree_new (void)
4323 Create a new @code{GtkTree} object returning the new widget as a pointer to
4324 a @code{GtkWidget} object. @code{NULL} is returned on failure.
4327 @deftypefun void gtk_tree_append (GtkTree *@var{tree}, GtkWidget *@var{child})
4330 @deftypefun void gtk_tree_prepend (GtkTree *@var{tree}, GtkWidget *@var{child})
4333 @deftypefun void gtk_tree_insert (GtkTree *@var{tree}, GtkWidget *@var{child}, gint @var{position})
4336 @deftypefun gint gtk_tree_child_position (GtkTree *@var{tree}, GtkWidget *@var{child})
4339 @deftypefun void gtk_tree_clear_items (GtkTree *@var{tree}, gint @var{start}, gint @var{end})
4342 @deftypefun void gtk_tree_remove_items (GtkTree *@var{tree}, GList *@var{items})
4345 @deftypefun void gtk_tree_select_child (GtkTree *@var{tree}, GtkWidget *@var{child})
4348 @deftypefun void gtk_tree_select_item (GtkTree *@var{tree}, gint @var{item})
4351 @deftypefun void gtk_tree_unselect_child (GtkTree *@var{tree}, GtkWidget *@var{child})
4354 @deftypefun void gtk_tree_unselect_item (GtkTree *@var{tree}, gint @var{item})
4357 @deftypefun void gtk_tree_set_selection_mode (GtkTree *@var{tree}, GtkSelectionMode @var{mode})
4360 @deftypefun void gtk_tree_set_view_mode (GtkTree *@var{tree}, GtkTreeViewMode @var{mode})
4363 @deftypefun void gtk_tree_set_view_lines (GtkTree *@var{tree}, guint @var{flag})
4367 @gtkstdmacros{Tree, TREE}
4371 @node GtkTreeItem, GtkVBox, GtkTree, Widgets
4372 @comment node-name, next, previous, up
4373 @section The tree item widget
4376 @subsection Description
4382 @subsection Functions
4384 @deftypefun guint gtk_tree_item_get_type (void)
4385 Returns the @code{GtkTreeItem} type identifier.
4388 @deftypefun GtkWidget* gtk_tree_item_new (void)
4389 Create a new @code{GtkTreeItem} object returning the new widget as a
4390 pointer to a @code{GtkWidget} object. @code{NULL} is returned on failure.
4393 @deftypefun GtkWidget* gtk_tree_item_new_with_label (gchar *@var{label})
4394 Create a new @code{GtkTreeItem} object initializing it with the values in
4395 @var{label}. The new widget is returned as a pointer to a @code{GtkWidget}
4396 object. @code{NULL} is returned on failure.
4399 @deftypefun void gtk_tree_item_set_subtree (GtkTreeItem *@var{tree_item}, GtkWidget *@var{subtree})
4402 @deftypefun void gtk_tree_item_select (GtkTreeItem *@var{tree_item})
4405 @deftypefun void gtk_tree_item_deselect (GtkTreeItem *@var{tree_item})
4408 @deftypefun void gtk_tree_item_expand (GtkTreeItem *@var{tree_item})
4411 @deftypefun void gtk_tree_item_collapse (GtkTreeItem *@var{tree_item})
4414 @deftypefun void gtk_tree_item_remove_subtree (GtkTreeItem *@var{item})
4418 @gtkstdmacros{TreeItem, TREE_ITEM}
4421 @node GtkVBox, GtkVButtonBox, GtkTreeItem, Widgets
4422 @comment node-name, next, previous, up
4423 @section The vertical box widget
4426 @subsection Description
4431 This option controls whether each object in the box has the same size. In the
4432 case of the @code{GtkVBox}, this refers to the height. If this option is set
4433 then the @var{expand} option to the @code{gtk_box_pack} (@pxref{GtkBox})
4434 routines is always turned on.
4438 This option sets the amount of space that is added between the objects packed
4439 into this @code{GtkVBox} object.
4444 This widget does not define any new signals.
4446 @subsection Functions
4448 @deftypefun guint gtk_vbox_get_type (void)
4449 Returns the @code{GtkVBox} type identifier.
4452 @deftypefun GtkWidget* gtk_vbox_new (gint @var{homogeneous}, gint @var{spacing})
4453 Create a new @code{GtkVBox} object initializing it with the values in
4454 @var{homogeneous} and @var{spacing}. The new widget is returned as a
4455 pointer to a @code{GtkWidget} object. @code{NULL} is returned on failure.
4458 @gtkstdmacros{VBox, VBOX}
4461 @node GtkVButtonBox, GtkViewport, GtkVBox, Widgets
4462 @comment node-name, next, previous, up
4463 @section The vertical button box widget
4466 @subsection Description
4477 @subsection Functions
4479 @deftypefun guint gtk_vbutton_box_get_type (void)
4480 Returns the @code{GtkVButtonBox} type identifier.
4483 @deftypefun GtkWidget* gtk_vbutton_box_new (void)
4484 Create a new @code{GtkVButtonBox} object returning the new widget as a
4485 pointer to a @code{GtkWidget} object. @code{NULL} is returned on failure.
4488 @deftypefun void gtk_vbutton_box_set_spacing_default (gint @var{spacing})
4491 @deftypefun void gtk_vbutton_box_set_layout_default (gint @var{layout})
4494 @deftypefun gint gtk_vbutton_box_get_spacing_default (void)
4497 @deftypefun gint gtk_vbutton_box_get_layout_default (void)
4500 @gtkstdmacros{VButtonBox, VBUTTON_BOX}
4504 @node GtkViewport, GtkVPaned, GtkVButtonBox, Widgets
4505 @comment node-name, next, previous, up
4506 @section The viewport widget
4509 @subsection Description
4513 @subsection Functions
4515 @deftypefun guint gtk_viewport_get_type (void)
4516 Returns the @code{GtkViewport} type identifier.
4519 @deftypefun GtkWidget* gtk_viewport_new (GtkAdjustment *@var{hadjustment}, GtkAdjustment *@var{vadjustment})
4522 @deftypefun GtkAdjustment* gtk_viewport_get_hadjustment (GtkViewport *@var{viewport})
4525 @deftypefun GtkAdjustment* gtk_viewport_get_vadjustment (GtkViewport *@var{viewport})
4528 @deftypefun void gtk_viewport_set_hadjustment (GtkViewport *@var{viewport}, GtkAdjustment *@var{adjustment})
4531 @deftypefun void gtk_viewport_set_vadjustment (GtkViewport *@var{viewport}, GtkAdjustment *@var{adjustment})
4534 @deftypefun void gtk_viewport_set_shadow_type (GtkViewport *@var{viewport}, GtkShadowType @var{type})
4537 @gtkstdmacros{Viewport, VIEWPORT}
4540 @node GtkVPaned, GtkVRuler, GtkViewport, Widgets
4541 @comment node-name, next, previous, up
4542 @section The vertical paned widget
4544 @subsection Description
4550 @subsection Functions
4552 @deftypefun guint gtk_vpaned_get_type (void)
4553 Returns the @code{GtkVPaned} type identifier.
4556 @deftypefun GtkWidget* gtk_vpaned_new (void)
4557 Create a new @code{GtkVPaned} object returning the new widget as a pointer
4558 to a @code{GtkWidget} object. @code{NULL} is returned on failure.
4561 @gtkstdmacros{VPaned, VPANED}
4564 @node GtkVRuler, GtkVScale, GtkVPaned, Widgets
4565 @comment node-name, next, previous, up
4566 @section The vertical ruler widget
4569 @subsection Description
4575 @subsection Functions
4577 @deftypefun guint gtk_vruler_get_type (void)
4578 Returns the @code{GtkVRuler} type identifier.
4581 @deftypefun GtkWidget* gtk_vruler_new (void)
4582 Create a new @code{GtkVRuler} object returning the new widget as a pointer to
4583 a @code{GtkWidget} object. @code{NULL} is returned on failure.
4586 @gtkstdmacros{VRuler, VRULER}
4590 @node GtkVScale, GtkVScrollbar, GtkVRuler, Widgets
4591 @comment node-name, next, previous, up
4592 @section The vertical ruler widget
4595 @subsection Description
4601 @subsection Functions
4603 @deftypefun guint gtk_vscale_get_type (void)
4604 Returns the @code{GtkVScale} type identifier.
4607 @deftypefun GtkWidget* gtk_vscale_new (GtkAdjustment *@var{adjustment})
4608 Create a new @code{GtkVScale} object returning the new widget as a pointer
4609 to a @code{GtkWidget} object. @code{NULL} is returned on failure.
4612 @gtkstdmacros{VScale, VSCALE}
4616 @node GtkVScrollbar, GtkVSeparator, GtkVScale, Widgets
4617 @comment node-name, next, previous, up
4618 @section The vertical scrollbar widget
4621 @subsection Description
4627 @subsection Functions
4629 @deftypefun guint gtk_vscrollbar_get_type (void)
4630 Returns the @code{GtkVScrollbar} type identifier.
4633 @deftypefun GtkWidget* gtk_vscrollbar_new (GtkAdjustment *@var{adjustment})
4634 Create a new @code{GtkVScrollbar} object initializing it with the values in
4635 @var{adjustment}. The new widget is returned as a pointer to a @code{GtkWidget}
4636 object. @code{NULL} is returned on failure.
4639 @gtkstdmacros{VScrollbar, VSCROLLBAR}
4643 @node GtkVSeparator, GtkWidget, GtkVScrollbar, Widgets
4644 @comment node-name, next, previous, up
4645 @section The vertical separator widget
4648 @subsection Description
4652 @subsection Functions
4654 @deftypefun guint gtk_vseparator_get_type (void)
4655 Returns the @code{GtkVSeparator} type identifier.
4658 @deftypefun GtkWidget* gtk_vseparator_new (void)
4659 Create a new @code{GtkVSeparator} object and return the new widget as a
4660 pointer to a @code{GtkWidget} object. @code{NULL} is returned on failure.
4663 @gtkstdmacros{VSeparator, VSEPARATOR}
4667 @node GtkWidget, GtkWindow, GtkVSeparator, Widgets
4668 @comment node-name, next, previous, up
4669 @section The base widget
4672 @subsection Description
4676 @deftypefn Signal void GtkWidget::show (GtkWidget *@var{widget})
4679 @deftypefn Signal void GtkWidget::hide (GtkWidget *@var{widget})
4682 @deftypefn Signal void GtkWidget::map (GtkWidget *@var{widget})
4685 @deftypefn Signal void GtkWidget::unmap (GtkWidget *@var{widget})
4688 @deftypefn Signal void GtkWidget::realize (GtkWidget *@var{widget})
4691 @deftypefn Signal void GtkWidget::unrealize (GtkWidget *@var{widget})
4694 @deftypefn Signal void GtkWidget::draw (GtkWidget *@var{widget}, GdkRectangle *@var{area})
4697 @deftypefn Signal void GtkWidget::draw_focus (GtkWidget *@var{widget})
4700 @deftypefn Signal void GtkWidget::draw_default (GtkWidget *@var{widget})
4703 @deftypefn Signal void GtkWidget::size_request (GtkWidget *@var{widget}, GtkRequisition *@var{requisition})
4706 @deftypefn Signal void GtkWidget::size_allocate (GtkWidget *@var{widget}, GtkAllocation *@var{allocation})
4709 @deftypefn Signal void GtkWidget::state_changed (GtkWidget *@var{widget})
4712 @deftypefn Signal gint GtkWidget::install_accelerator (GtkWidget *@var{widget}, gchar *@var{signal_name}, gchar @var{key}, guint8 @var{modifiers})
4715 @deftypefn Signal void GtkWidget::remove_accelerator (GtkWidget *@var{widget}, gchar *@var{signal_name})
4718 @deftypefn Signal gint GtkWidget::event (GtkWidget *@var{widget}, GdkEvent *@var{event})
4721 @deftypefn Signal gint GtkWidget::button_press_event (GtkWidget *@var{widget}, GdkEventButton *@var{event})
4724 @deftypefn Signal gint GtkWidget::button_release_event (GtkWidget *@var{widget}, GdkEventButton *@var{event})
4727 @deftypefn Signal gint GtkWidget::motion_notify_event (GtkWidget *@var{widget}, GdkEventMotion *@var{event})
4730 @deftypefn Signal gint GtkWidget::delete_event (GtkWidget *@var{widget}, GdkEventAny *@var{event})
4733 @deftypefn Signal gint GtkWidget::destroy_event (GtkWidget *@var{widget}, GdkEventAny *@var{event})
4736 @deftypefn Signal gint GtkWidget::expose_event (GtkWidget *@var{widget}, GdkEventExpose *@var{event})
4739 @deftypefn Signal gint GtkWidget::key_press_event (GtkWidget *@var{widget}, GdkEventKey *@var{event})
4742 @deftypefn Signal gint GtkWidget::key_release_event (GtkWidget *@var{widget}, GdkEventKey *@var{event})
4745 @deftypefn Signal gint GtkWidget::enter_notify_event (GtkWidget *@var{widget}, GdkEventCrossing *@var{event})
4748 @deftypefn Signal gint GtkWidget::leave_notify_event (GtkWidget *@var{widget}, GdkEventCrossing *@var{event})
4751 @deftypefn Signal gint GtkWidget::configure_event (GtkWidget *@var{widget}, GdkEventConfigure *@var{event})
4754 @deftypefn Signal gint GtkWidget::focus_in_event (GtkWidget *@var{widget}, GdkEventFocus *@var{event})
4757 @deftypefn Signal gint GtkWidget::focus_out_event (GtkWidget *@var{widget}, GdkEventFocus *@var{event})
4760 @deftypefn Signal gint GtkWidget::map_event (GtkWidget *@var{widget}, GdkEventAny *@var{event})
4763 @deftypefn Signal gint GtkWidget::unmap_event (GtkWidget *@var{widget}, GdkEventAny *@var{event})
4766 @deftypefn Signal gint GtkWidget::property_notify_event (GtkWidget *@var{widget}, GdkEventProperty *@var{event})
4769 @deftypefn Signal gint GtkWidget::selection_clear_event (GtkWidget *@var{widget}, GdkEventSelection *@var{event})
4772 @deftypefn Signal gint GtkWidget::selection_request_event (GtkWidget *@var{widget}, GdkEventSelection *@var{event})
4775 @deftypefn Signal gint GtkWidget::selection_notify_event (GtkWidget *@var{widget}, GdkEventSelection *@var{event})
4778 @deftypefn Signal gint GtkWidget::drop_event (GtkWidget *@var{widget}, GdkEventDrop *@var{event})
4781 @deftypefn Signal gint GtkWidget::drag_begin_event (GtkWidget *@var{widget}, GdkEventDragBegin *@var{event})
4784 @deftypefn Signal gint GtkWidget::other_event (GtkWidget *@var{widget}, GdkEventOther *@var{event})
4787 @subsection Functions
4789 @deftypefun guint gtk_widget_get_type (void)
4790 Returns the @code{GtkWidget} type identifier.
4793 @deftypefun void gtk_widget_class_init (GtkWidgetClass *@var{class})
4796 @deftypefun void gtk_widget_init (GtkWidget *@var{widget})
4799 @deftypefun void gtk_widget_destroy (GtkWidget *@var{widget})
4802 @deftypefun void gtk_widget_show (GtkWidget *@var{widget})
4805 @deftypefun void gtk_widget_hide (GtkWidget *@var{widget})
4808 @deftypefun void gtk_widget_map (GtkWidget *@var{widget})
4811 @deftypefun void gtk_widget_unmap (GtkWidget *@var{widget})
4814 @deftypefun void gtk_widget_realize (GtkWidget *@var{widget})
4817 @deftypefun void gtk_widget_unrealize (GtkWidget *@var{widget})
4820 @deftypefun void gtk_widget_draw (GtkWidget *@var{widget}, GdkRectangle *@var{area})
4823 @deftypefun void gtk_widget_draw_focus (GtkWidget *@var{widget})
4826 @deftypefun void gtk_widget_draw_children (GtkWidget *@var{widget})
4829 @deftypefun void gtk_widget_size_request (GtkWidget *@var{widget}, GtkRequisition *@var{requisition})
4832 @deftypefun void gtk_widget_size_allocate (GtkWidget *@var{widget}, GtkAllocation *@var{allocation})
4835 @deftypefun void gtk_widget_install_accelerator (GtkWidget *@var{widget}, GtkAcceleratorTable *@var{table}, gchar *@var{signal_name}, gchar @var{key}, guint8 @var{modifiers})
4838 @deftypefun void gtk_widget_remove_accelerator (GtkWidget *@var{widget}, GtkAcceleratorTable *@var{table}, gchar *@var{signal_name})
4841 @deftypefun gint gtk_widget_event (GtkWidget *@var{widget}, GdkEvent *@var{event})
4844 @deftypefun void gtk_widget_reparent (GtkWidget *@var{widget}, GtkWidget *@var{new_parent})
4847 @deftypefun void gtk_widget_popup (GtkWidget *@var{widget}, gint @var{x}, gint @var{y})
4850 @deftypefun gint gtk_widget_intersect (GtkWidget *@var{widget}, GdkRectangle *@var{area}, GdkRectangle *@var{intersection})
4853 @deftypefun void gtk_widget_grab_focus (GtkWidget *@var{widget})
4856 @deftypefun void gtk_widget_grab_default (GtkWidget *@var{widget})
4859 @deftypefun void gtk_widget_restore_state (GtkWidget *@var{widget})
4862 @deftypefun void gtk_widget_set_name (GtkWidget *@var{widget}, gchar *@var{name})
4865 @deftypefun void gtk_widget_set_state (GtkWidget *@var{widget}, GtkStateType @var{state})
4868 @deftypefun void gtk_widget_set_sensitive (GtkWidget *@var{widget}, gint sensitive)
4871 @deftypefun void gtk_widget_set_parent (GtkWidget *@var{widget}, GtkWidget *@var{parent})
4874 @deftypefun void gtk_widget_set_style (GtkWidget *@var{widget}, GtkStyle *@var{style})
4877 @deftypefun void gtk_widget_set_uposition (GtkWidget *@var{widget}, gint @var{x}, gint @var{y})
4880 @deftypefun void gtk_widget_set_usize (GtkWidget *@var{widget}, gint @var{width}, gint @var{height})
4883 @deftypefun GtkWidget* gtk_widget_get_toplevel (GtkWidget *@var{widget})
4886 @deftypefun GtkWidget* gtk_widget_get_ancestor (GtkWidget *@var{widget}, gint @var{type})
4889 @deftypefun GdkColormap* gtk_widget_get_colormap (GtkWidget *@var{widget})
4892 @deftypefun GdkVisual* gtk_widget_get_visual (GtkWidget *@var{visual})
4895 @deftypefun GtkStyle* gtk_widget_get_style (GtkWidget *@var{style})
4898 @gtkstdmacros{Widget, WIDGET}
4902 @node GtkWindow, , GtkWidget, Widgets
4903 @comment node-name, next, previous, up
4904 @section The window widget
4907 @subsection Description
4912 The @var{type} options specify how this widget will interact with the
4913 window manager. Currently the following types and the effect they have
4914 on the window to window manager interaction is as follows.
4918 @code{GTK_WINDOW_TOPLEVEL}
4921 The option @code{GTK_WINDOW_TOPLEVEL} is usually used for the main application
4922 window that will remain for the entire application run.
4925 @code{GTK_WINDOW_DIALOG}
4928 The option @code{GTK_WINDOW_DIALOG} is usually used for transient
4929 windows. These windows will open up, gather some input or provide some
4930 application specific updates, then close. The window manager is free not
4931 to provide all the 'normal' window functions to this window.
4934 @code{GTK_WINDOW_POPUP}
4937 The option @code{GTK_WINDOW_POPUP} is usually used for transient windows.
4938 These windows are typically used for when no user interaction is required,
4939 to notify the user of some condition. Other uses for these types of windows
4940 are for 'about windows', startup windows and the like. Typically the window
4941 manager will @strong{not} provide the usual widgets that surround the
4942 window. At the most all that will be provided is a border. Also note that
4943 windows that set this @var{type} will not be in any window list of the window
4944 manager. Though this window will @strong{not} get the kill and close widgets
4945 of the window manager they still can receive said events and should be
4952 The @var{title} option will set the title of the window in the window manager.
4953 @strong{Note:} On windows that have the @var{type} option set to
4954 @code{GTK_WINDOW_POPUP} there is a strong possibility that this will text
4959 The @var{position} option will determine where the window will be displayed
4960 when it is finally drawn to the screen. Currently the following positions
4961 and the effect they have on window placement can be specified.
4966 @code{GTK_WIN_POS_NONE}
4969 This @var{position} type will allow the window manager full freedom, depending
4970 on the current settings in the window manager. As to where the window will
4974 @code{GTK_WIN_POS_CENTER}
4977 This @var{position} option will cause the window to center itself on the
4978 the screen. This option setting will take into account the @var{virtual screen}
4979 size when calculating the center. This is @strong{not} the same as the
4980 @var{virtual desktop} setting of many window managers. It will center itself
4981 on the current @var{virtual desktop}.
4984 @code{GTK_WIN_POS_MOUSE}
4986 This @var{position} option will cause the window to center itself under the
4987 mouse pointers' current location. Typical uses for this setting is in
4988 warning/error/informational dialogs where user interaction is desired.
4996 @deftypefn Signal void GtkWindow::move_resize (GtkWindow *@var{window}, gint *@var{x}, gint *@var{y}, gint @var{width}, gint @var{height})
4999 @deftypefn Signal void GtkWindow::set_focus (GtkWindow *@var{window}, GtkWidget *@var{focus})
5002 @subsection Functions
5004 @deftypefun guint gtk_window_get_type (void)
5005 Returns the @code{GtkWindow} type identifier.
5008 @deftypefun GtkWidget* gtk_window_new (GtkWindowType @var{type})
5009 Create a new @code{GtkWindow} object. The new widget is returned as a
5010 pointer to a @code{GtkWidget} object. @code{NULL} is returned on failure.
5011 The @var{type} can be one of @code{GTK_WINDOW_TOPLEVEL},
5012 @code{GTK_WINDOW_DIALOG} or, @code{GTK_WINDOW_POPUP}. The @var{type}
5013 value determines how this widget will interact with the window manager.
5016 @deftypefun void gtk_window_set_title (GtkWindow *@var{window}, gchar *@var{title})
5017 Set the title of this window to the text in the @var{title} argument. It is
5018 important to not set the fields of the @code{GtkWindow} structure directly.
5021 @deftypefun void gtk_window_set_focus (GtkWindow *@var{window}, GtkWidget *@var{focus})
5024 @deftypefun void gtk_window_set_default (GtkWindow *@var{window}, GtkWidget *@var{defaultw})
5027 @deftypefun void gtk_window_set_policy (GtkWindow *@var{window}, gint @var{allow_shrink}, gint @var{allow_grow}, gint @var{auto_shrink})
5030 @deftypefun void gtk_window_add_accelerator_table (GtkWindow *@var{window}, GtkAcceleratorTable *@var{table})
5033 @deftypefun void gtk_window_remove_accelerator_table (GtkWindow *@var{window}, GtkAcceleratorTable *@var{table})
5036 @deftypefun void gtk_window_position (GtkWindow *@var{window}, GtkWindowPosition @var{position})
5037 Set the position that the window will be at when it is finally drawn to the
5038 screen. The @var{position} argument effects the the position as described
5042 @gtkstdmacros{Window, WINDOW}
5045 @node Other Objects, Miscellaneous, Widgets, Top
5046 @comment node-name, next, previous, up
5047 @chapter Utility objects
5051 * GtkAcceleratorTable:: The accelerator table object.
5052 * GtkAdjustment:: The adjustment object.
5053 * GtkGC:: The GC object.
5054 * GtkData:: The data object.
5055 * GtkStyle:: The style object.
5059 @node GtkAcceleratorTable, GtkAdjustment, Other Objects, Other Objects
5060 @comment node-name, next, previous, up
5061 @section The accelerator table object
5063 @subsection Description
5065 @subsection Functions
5067 @deftypefun GtkAcceleratorTable* gtk_accelerator_table_new (void)
5070 @deftypefun GtkAcceleratorTable* gtk_accelerator_table_find (GtkObject *@var{object}, gchar *@var{signal_name}, guchar @var{accelerator_key}, guint8 @var{accelerator_mods})
5073 @deftypefun GtkAccelerator *gtk_accelerator_table_ref (GtkAcceleratorTable *@var{table})
5076 @deftypefun void gtk_accelerator_table_unref (GtkAcceleratorTable *@var{table})
5079 @deftypefun void gtk_accelerator_table_install (GtkAcceleratorTable *@var{table}, GtkObject *@var{object}, gchar *@var{signal_name}, guchar @var{accelerator_key}, guint8 @var{accelerator_mods})
5082 @deftypefun void gtk_accelerator_table_remove (GtkAcceleratorTable *@var{table}, GtkObject *@var{object}, gchar *@var{signal_name})
5085 @deftypefun void gtk_accelerator_table_check (GtkAcceleratorTable *@var{table}, guchar @var{accelerator_key}, guint8 @var{accelerator_mods})
5088 @deftypefun void gtk_accelerator_table_set_mod_mask (GtkAcceleratorTable *@var{table}, guint8 @var{modifier_mask})
5092 @node GtkAdjustment, GtkGC, GtkAcceleratorTable, Other Objects
5093 @comment node-name, next, previous, up
5094 @section The adjustment object
5096 @subsection Description
5098 @subsection Functions
5100 @deftypefun guint gtk_adjustment_get_type (void)
5101 Returns the @code{GtkAdjustment} type identifier.
5104 @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})
5107 @gtkstdmacros{GtkAdjustment, ADJUSTMENT}
5110 @node GtkGC, GtkData, GtkAdjustment, Other Objects
5111 @section The GC object
5113 @subsection Description
5115 @subsection Functions
5117 @deftypefun GdkGC* gtk_gc_get (gint @var{depth}, GdkColormap *@var{colormap}, GdkGCValues *@var{values}, GdkGCValuesMask @var{values_mask})
5120 @deftypefun void gtk_gc_release (GdkGC *@var{gc})
5124 @node GtkData, GtkStyle, GtkGC, Other Objects
5125 @comment node-name, next, previous, up
5126 @section The data object
5128 @subsection Description
5130 @subsection Functions
5132 @deftypefun guint gtk_data_get_type (void)
5133 Returns the @code{GtkData} type identifier.
5136 @gtkstdmacros{Data, DATA}
5138 @node GtkStyle, , GtkData, Other Objects
5139 @section The style object
5141 @subsection Description
5143 @subsection Functions
5146 @node Miscellaneous, Examples, Other Objects, Top
5147 @comment node-name, next, previous, up
5148 @chapter Initialization, exit and other features
5152 * Initialization and exit:: Initializing and exiting GTK.
5153 * Customization:: Customizing the library.
5154 * Menu Factories:: Simplified menu creation.
5155 * Tree Factories:: Simplified tree creation.
5156 * Tool Tips:: Pop up help mechanism.
5157 * Resource Files:: Resource files.
5158 * Standard Macros:: Macros defined by all objects.
5162 @node Initialization and exit, Customization, Miscellaneous, Miscellaneous
5163 @comment node-name, next, previous, up
5164 @section Initializing and exiting GTK
5166 @subsection Initializing
5167 Before any GTK functions can be utilized the library must be initialized. This
5168 can be accomplished by calling the @code{gtk_init} function. The arguments
5169 you pass to this function should be the same arguments that were passed to
5170 your application. This function will parse the arguments that it understands
5171 and handle initializing the GDK library for you.
5175 @subsection Functions
5177 @deftypefun void gtk_init (int *@var{argc}, char **@var{argv})
5178 Function to initialize GTK and GDK for you. This function will remove any
5179 command line arguments from @var{argc} and @var{argv} that it understands.
5182 int main (int argc, char *argv[])
5184 @dots{Any local variables or non GTK/GDK initialization}
5186 /* Initialize GTK. */
5187 gtk_init(&argc, &argc);
5193 @deftypefun void gtk_exit (int @var{error_code})
5194 Exit GTK and perform any necessary cleanup. @code{gtk_exit} will call the
5195 systems @code{exit} function passing @var{error_code} as the parameter.
5198 @deftypefun gint gtk_events_pending (void)
5199 Returns the number of events pending on the event queue.
5202 @deftypefun void gtk_main (void)
5205 @deftypefun guint gtk_main_level (void)
5208 @deftypefun void gtk_main_quit (void)
5209 A call to this function will cause the @code{gtk_main} function to exit,
5210 thereby allowing your application to exit.
5214 @node Customization, Menu Factories, Initialization and exit, Miscellaneous
5215 @comment node-name, next, previous, up
5216 @section Customization of the library
5218 @subsection Description
5219 Like other X-windows applications the GTK library provides a way for the
5220 user and application programmer to change the colors of just about any widget.
5221 You can also specify what pixmap should be tiled onto the background of some
5222 widgets. All this is handled through a similar method as in the standard
5223 X-windows environment, through the use of 'rc' files. The format and
5224 functions available in these files is discussed below.
5226 @subsection Functions
5227 The following functions are available to handle the rc files.
5229 @deftypefun void gtk_rc_parse (char *@var{filename})
5230 This function will parse the @var{filename} that is passed to it as its
5231 argument. It will use the style settings for the widget types defined there.
5234 @deftypefun void gtk_rc_init (void)
5235 This function will initialize the rc file parser, normally this need not
5236 be called directly as the @code{gtk_rc_parse} function will handle this for
5241 @node Menu Factories, Tree Factories, Customization, Miscellaneous
5242 @comment node-name, next, previous, up
5243 @section Simplified menu creation
5246 @node Tree Factories, Tool Tips, Menu Factories, Miscellaneous
5247 @comment node-name, next, previous, up
5248 @section Simplified tree creation
5251 @node Tool Tips, Resource Files, Tree Factories, Miscellaneous
5252 @comment node-name, next, previous, up
5253 @section Pop up help mechanism
5255 @subsection Description
5258 @node Resource Files, Standard Macros, Tool Tips, Miscellaneous
5259 @comment node-name, next, previous, up
5260 @section Resource Files
5263 @node Standard Macros, , Resource Files, Miscellaneous
5264 @comment node-name, next, previous, up
5265 @section Macros defined by all objects
5267 There are three macros that are defined by all object types. The first
5268 two are used for performing casts and the last is for querying whether
5269 an object is of a particular type. These macros are both conveniences
5270 and debugging tools. If the GTK library was compiled with @code{NDEBUG}
5271 defined as a preprocessor symbol (via the -DNDEBUG to cc), then the
5272 macros check the object type and emit a warning if the cast is
5273 invalid. Doing such checking is fairly expensive since the cast macros
5274 are used everywhere in GTK and would normally be turned off in a public
5275 release of a product. Note: The functions below are indeed macros, but
5276 they may be considered functions for most purposes.
5278 @deftypefun Gtk<ObjectType>* GTK_<OBJECT_TYPE> (gpointer @var{obj})
5279 Cast a generic pointer to @code{Gtk<ObjectType>*}. This function is
5280 provided in order to be able to provide checking during development
5281 stages of code development since it is possible to examine the actual
5282 type of object (using @code{gtk_type_is_a}) before performing the cast.
5285 @deftypefun Gtk<ObjectType>Class* GTK_<OBJECT_TYPE>_CLASS (gpointer @var{class})
5286 Cast a generic pointer to @code{Gtk<ObjectType>Class*}. Like
5287 @code{GTK_<ObjectType>}, this function is, in reality, a macro.
5290 @deftypefun gint GTK_IS_<ObjectType> (gpointer @var{obj})
5291 Determine if a generic pointer refers to a @code{Gtk<ObjectType>}
5292 object. This function is, in reality, a macro wrapper around the
5293 @code{gtk_type_is_a} function (@pxref{Types}).
5297 @node Examples, Object Implementation, Miscellaneous, Top
5298 @comment node-name, next, previous, up
5303 * Simple:: The simplest GTK program.
5304 * Hello World:: Hello world in GTK.
5305 * Hello World II:: An enhanced hello world.
5306 * Hello World III:: Making Hello World II robust.
5310 @node Simple, Hello World, Examples, Examples
5311 @comment node-name, next, previous, up
5312 @section The simplest GTK program
5315 The 16 line GTK program shown below is just about the simplest possible
5316 program which uses GTK. (Well, technically, you don't have to create the
5317 window and it would still be a program which uses GTK). The program,
5318 when compiled and run, will create a single window 200x200 pixels in
5319 size. The program does not exit until its is explicitly killed using the
5320 shell or a window manager function.
5323 #include <gtk/gtk.h>
5326 main (int argc, char *argv[])
5330 gtk_init (&argc, &argv);
5332 window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
5333 gtk_widget_show (window);
5341 The first point of interest in this program is the standard
5342 initialization line.
5345 gtk_init (&argc, &argv);
5348 Almost every GTK program will contain such a line. GTK will initialize
5349 itself and GDK and remove any command line arguments it recognizes from
5350 @var{argc} and @var{argv}.
5352 The next two lines of code create and display a window.
5355 window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
5356 gtk_widget_show (window);
5359 The @code{GTK_WINDOW_TOPLEVEL} argument specifies that we want the
5360 window to undergo window manager decoration and placement. One might be
5361 lead to think that the window, since it has no children, would be 0x0
5362 pixels in size. But, this is not the case because a window that has no
5363 children defaults to 200x200 pixels in size. Mainly because 0x0 windows
5364 are annoying to manipulate or even see in some cases.
5366 The last line enters the GTK main processing loop.
5372 Normally, @code{gtk_main} is called once and the program should exit
5373 when it returns. @xref{Initialization and exit}.
5376 @node Hello World, Hello World II, Simple, Examples
5377 @comment node-name, next, previous, up
5378 @section Hello world in GTK
5382 #include <gtk/gtk.h>
5385 main (int argc, char *argv[])
5390 gtk_init (&argc, &argv);
5392 window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
5393 gtk_container_border_width (GTK_CONTAINER (window), 10);
5395 label = gtk_label_new ("Hello World");
5396 gtk_container_add (GTK_CONTAINER (window), label);
5397 gtk_widget_show (label);
5399 gtk_widget_show (window);
5408 @node Hello World II, Hello World III, Hello World, Examples
5409 @comment node-name, next, previous, up
5410 @section An enhanced hello world
5419 g_print ("Hello World\n");
5424 main (int argc, char *argv[])
5429 gtk_init (&argc, &argv);
5431 window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
5432 gtk_container_border_width (GTK_CONTAINER (window), 10);
5434 button = gtk_button_new_with_label ("Hello World");
5435 gtk_signal_connect (GTK_OBJECT (button), "clicked",
5436 GTK_SIGNAL_FUNC (hello), NULL);
5437 gtk_container_add (GTK_CONTAINER (window), button);
5438 gtk_widget_show (button);
5440 gtk_widget_show (window);
5449 @node Hello World III, , Hello World II, Examples
5450 @comment node-name, next, previous, up
5451 @section Making Hello World II robust
5460 g_print ("Hello World\n");
5471 main (int argc, char *argv[])
5476 gtk_init (&argc, &argv);
5478 window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
5479 gtk_signal_connect (GTK_OBJECT (window), "destroy",
5480 GTK_SIGNAL_FUNC (destroy), NULL);
5481 gtk_container_border_width (GTK_CONTAINER (window), 10);
5483 button = gtk_button_new_with_label ("Hello World");
5484 gtk_signal_connect (GTK_OBJECT (button), "clicked",
5485 GTK_SIGNAL_FUNC (hello), NULL);
5486 gtk_signal_connect_object (GTK_OBJECT (button), "clicked",
5487 GTK_SIGNAL_FUNC (gtk_widget_destroy),
5488 GTK_OBJECT (window));
5489 gtk_container_add (GTK_CONTAINER (window), button);
5490 gtk_widget_show (button);
5492 gtk_widget_show (window);
5501 @node Object Implementation, Signal Implementation, Examples, Top
5502 @comment node-name, next, previous, up
5503 @chapter Object internals
5504 @cindex Object Implementation
5506 Objects (or the @code{GtkObject} type) and the class hierarchy in
5507 general is implemented via a hierarchy of structs and type casting. Be
5508 aware that when classes are mentioned it is the conceptual idea of
5509 classes that is being referred to. GTK is written entirely in C which
5510 provides no direct support for classes.
5512 The first part to the class mechanism is the object fields. These are
5513 fields that will be used on a per object basis. For example, the widget
5514 type contains a field for the widgets parent. Every derived type needs a
5515 reference to its parent type. A descendant class of @code{GtkObject}
5516 would define itself like:
5527 It is important to note that the @code{GtkObject} field needs to appear
5528 first in the descendant type structure. This allows pointers to objects
5529 of type @code{Descendant} to be cast to pointers to @code{GtkObject}'s
5532 The second part to the class mechanism is the class fields. These fields
5533 are defined on a per class basis. In the case of widgets, the class
5534 fields are all the ``virtual'' functions for widgets. The
5535 @code{GtkObject} class defines the @code{destroy} virtual function and
5536 the necessary fields for the signal mechanism as well as a field for
5537 determining the runtime type of an object. A virtual function is
5538 semantically the same as it is in C++. That is, the actual function that
5539 is called is determined based on the type of the object. Or, more
5540 specifically, the actual function call depends on the class structure
5541 that is pointed to by the @code{klass} field of the @code{GtkObject}
5544 To see how the class fields work it is necessary to see the object
5545 fields for a @code{GtkObject}. The @code{GtkObject} type is defined as
5549 typedef struct _GtkObject GtkObject;
5554 GtkObjectClass *klass;
5555 gpointer object_data;
5559 The @code{class} field actually points to a class structure derived from
5560 @code{GtkObjectClass}. By convention, each new type defines its own
5561 class structure even if it is unnecessary. As an example, the
5562 hypothetical @code{Descendant} class would define its class structure
5566 struct DescendantClass
5568 GtkObjectClass parent_class;
5574 It is convention to name the parent class field (@code{GtkObjectClass}
5575 in this case), @code{parent_class}. For the same reason as stated above
5576 for the object structure, the parent class field must be the first field
5577 in the class structure.
5579 @strong{Note:} GTK assumes that the first field in a structure will be
5580 placed by the compiler at the start of the structure. This is certainly
5581 true for gcc, however, from my precursory reading of the C standard I
5582 was unable to come to a definite conclusion as to whether this was
5583 required or simply done for simplicity. I'm not too worried about this
5584 assumption, though, as every C compiler I've ever encountered would work
5587 The @code{flags} field of the @code{GtkObject} structure is used to keep
5588 track of a relatively few object flags and is also used by the
5589 @code{GtkWidget} type to store additional flags. At this time, the upper
5590 16 bits of the flags field are reserved but unused.
5592 The @code{object_data} field of the @code{GtkObject} structure is an
5593 opaque pointer used by the object data mechanism. In truth, it is a
5594 pointer to the beginning of the data list which is composed of the
5595 following structures.
5598 typedef struct _GtkObjectData GtkObjectData;
5600 struct _GtkObjectData
5604 GtkObjectData *next;
5608 The data mechanism allows arbitrary data to be associated with a
5609 character string key in any object. A hash table is used to transform
5610 the character string key into the data id and then a search through the
5611 list is made to see if the data exists. The assumption being that the
5612 data list will usually be short and therefore a linear search is
5613 OK. Future work on the data mechanism might make use of a resizable
5614 array instead of a linked list. This would shrink the overhead of the
5615 @code{GtkObjectData} structure by 4 bytes on 32 bit architectures.
5618 @node Signal Implementation, Widget Implementation, Object Implementation, Top
5619 @comment node-name, next, previous, up
5620 @chapter Signal internals
5621 @cindex Signal Implementation
5624 @node Widget Implementation, Function Index, Signal Implementation, Top
5625 @comment node-name, next, previous, up
5626 @chapter Widget internals
5627 @cindex Widget Implementation
5630 @node Function Index, Concept Index, Widget Implementation, Top
5631 @comment node-name, next, previous, up
5632 @unnumbered Function Index
5637 @node Concept Index, , Function Index, Top
5638 @comment node-name, next, previous, up
5639 @unnumbered Concept Index
5648 @c LocalWords: Gtk API formalistic