diff options
Diffstat (limited to 'docs/gtk.texi')
| -rw-r--r-- | docs/gtk.texi | 3285 |
1 files changed, 3285 insertions, 0 deletions
diff --git a/docs/gtk.texi b/docs/gtk.texi new file mode 100644 index 0000000000..93daf5b83a --- /dev/null +++ b/docs/gtk.texi @@ -0,0 +1,3285 @@ +\input texinfo @c -*-texinfo-*- +@c Copyright (C) 1996 by Peter Mattis. All rights reserved. +@c +@c %**start of header +@setfilename gtk.info +@settitle GTK +@setchapternewpage odd +@include macros.texi +@c %**end of header + +@set edition 1.0 +@set update-date 9 April 1997 +@set update-month April 1997 + +@ifinfo +This file documents GTK, the General Toolkit + +Copyright (C) 1996 Peter Mattis +Copyright (C) 1997 Peter Mattis + +Permission is granted to make and distribute verbatim copies of this +manual provided the copyright notice and this permission notice are +preserved on all copies + +@ignore +Permission is granted to process this file throught TeX and print the +results, provided the printed document carries copying permission notice +identical to this one except for the removal of this paragraph (this +paragraph not being relevant to the printed manual). + +@end ignore +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the +entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that this permission notice may be stated in a translation +approved by Peter Mattis. +@end ifinfo + +@titlepage +@title The General Toolkit +@subtitle Version @value{edition} +@subtitle @value{update-month} +@author by Peter Mattis + +@page +@vskip 0pt plus 1filll +Copyright @copyright{} 1996 Peter Mattis +Copyright @copyright{} 1997 Peter Mattis + +Permission is granted to make and distribute verbatim copies of this +manual provided the copyright notice and this permission notice are +preserved on all copies. + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the +entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that this permission notice may be stated in a translation +approved by Peter Mattis. +@end titlepage + +@dircategory User Interface Toolkit +@direntry +* GTK: (gtk). The General Toolkit +@end direntry + +@node Top, Copying, (dir), (dir) +@top The General Toolkit +@ifinfo +This is edition @value{edition} of the GTK documentation, +@w{@value{update-date}}. +@end ifinfo + +@menu +* Copying:: Your rights. +* Overview:: What is GTK? +* Objects:: Object overview. +* Signals:: Signals overview. +* Widgets:: Widget overview. +* Other Objects:: Utility objects. +* Miscellaneous:: Initialization, exit and other features. +* Examples:: Using GTK. +* Object Implementation:: Object internals. +* Signal Implementation:: Signal internals. +* Widget Implementation:: Widget internals. +* Function Index:: Index of functions. +* Concept Index:: Index of concepts. +@end menu + +@node Copying, Overview, Top, Top +@comment node-name, next, previous, up +@chapter Copying + +GTK is @dfn{free}; this means that everyone is free to use it and free +to redestribute it on a free basis. GTK is not in the public domain; it +is copyrighted and there are restrictions on its distribution, but +these restrictions are designed to permit everything that a good +cooperating citizen would want to do. What is not allowed is to try to +prevent others from further sharing any version of GTK that they might +get from you. + +Specifically, we want to make sure that you have the right to give away +copies of GTK, that you receive source code or else can get it if you +want it, that you can change GTK or use pieces of it in new free +programs, and that you know you can do these things. + +To make sure that everyone has such rights, we have to forbid you to +deprive anyone else of these rights. For example, if you distribute +copies of GTK, you must give the recipients all the rights that you +have. You must make sure that they, too, receive or can get the source +code. And you must tell them their rights. + +Also, for my own protection, we must make certain that everyone finds +out that there is no warranty for GTK. If GTK is modified by someone +else and passed on, we want their recipients to know that what they have +is not what we distributed, so that any problems introduced by others +will no reflect on our reputation. + +The precise conditions of the licenses for GTK are found in the General +Public Licenses that accompanies it. + + +@node Overview, Objects, Copying, Top +@comment node-name, next, previous, up +@chapter What is GTK? +@cindex Overview + +GTK is a library for creating graphical user interfaces similar to the +Motif ``look and feel''. It is designed to be small and efficient, but +still flexible enough to allow the programmer freedom in the interfaces +created. GTK allows the programmer to use a variety of standard user +interface widgets (@pxref{Widgets}) such as push, radio and check +buttons, menus, lists and frames. It also provides several ``container'' +widgets which can be used to control the layout of the user interface +elements. + +GTK provides some unique features. (At least, I know of no other widget +library which provides them). For example, a button does not contain a +label, it contains a child widget, which in most instances will be a +label. However, the child widget can also be a pixmap, image or any +combination possible the programmer desires. This flexibility is adhered +to throughout the library. + + +@node Objects, Signals, Overview, Top +@comment node-name, next, previous, up +@chapter Object Overview +@cindex Objects + +GTK implements a semi-simple class mechanism and an associated class +hierarchy for widgets and several other useful objects. The GtkObject +type is the root of the class hierarchy. It provides a few items needed +by all classes, the foundation for the signal (@pxref{Signals}) +mechanism and the ``destroy'' method. + +The class hierarchy is defined by a type hierarchy. This hierarchy +allows queries to be made in regards to a type. The basic query that can +be performed is asking whether a given type has an ``is a'' relation +with another type. For instance, it is common to ask whether a general +widget pointer is a type of specific widget so that runtime sanity +checks can be made. + +@section Type utility functions + +The @code{GtkTypeInfo} structure is used to communicate information to +@code{gtk_type_unique} as opposed to passing in large numbers of +parameters. + +@example +typedef struct _GtkTypeInfo GtkTypeInfo; + +struct _GtkTypeInfo +@{ + gchar *type_name; + guint object_size; + guint class_size; + GtkClassInitFunc class_init_func; + GtkObjectInitFunc object_init_func; + GtkValueInitFunc value_init_func; +@} +@end example + +@itemize @bullet +@item +The @code{type_name} field refers to the name of the type. It is +convention for the type name to be the same as the C structure type. For +example, the type name of the @code{GtkObject} structure is +``GtkObject''. + +@item +The @code{object_size} field refers to the size in bytes of the C +structure. The easiest (and portable) means of computing this size is by +using the C @code{sizeof} operator. For instance, the sizeof of the +@code{GtkObject} structure is computed by doing @code{sizeof +(GtkObject)}. + +@item +The @code{class_size} field refers to the size in bytes of the C +structure for the class. Again, the @code{sizeof} operator should be +used to compute this value. + +@item +The @code{class_init_func} field is a callback which is used by the type +mechanism to initialize class specific fields. The single argument this +function takes is a pointer to a class structure. + +@item +The @code{object_init_func} field is a callback which is used by the +type mechanism to initialize object specific fields. The single argument +this functions takes is a pointer to an object structure. + +@item +The @code{value_init_func} field is a callback which is used by the type +mechanism to initialize object stack value types. (FIXME: unfinished). +@end itemize + +@deftypefun guint gtk_type_unique (guint @var{parent_type}, GtkTypeInfo *@var{type_info}) +The @var{parent_type} is simply the value of the new types parent +type. If @var{parent_type} is 0, then the new type is the root of the +type hierarchy. @var{type_info} is a pointer to a structure which +contains necessary information for construction of the new +type. Specifically, the @code{type_name}, @code{object_size} and +@code{class_size} fields are required. The @code{class_init_func}, +@code{object_init_func} and @code{value_init_func} fields may be NULL. +@end deftypefun + +@deftypefun gchar* gtk_type_name (guint @var{type}) +The returned string is the name of @var{type} as specified to +@code{gtk_type_unique}. +@end deftypefun + +@deftypefun guint gtk_type_from_name (guchar *@var{name}) +Return the type associated with @var{name}. If there is no type +associated with @var{name}, then 0 will be returned. +@end deftypefun + +@deftypefun guint gtk_type_parent (guint @var{type}) +Returns the parent type of @var{type} or 0 if @var{type} is the root of +the type hierarchy. +@end deftypefun + +@deftypefun gpointer gtk_type_class (guint @var{type}) +Returns the initialized class structure for @var{type}. The class +structure is actually created and initialized the first time it is +needed. If creation and initialization occurs, the @code{class_size} +field of the @code{GtkTypeInfo} structure used to initialize this type +is used to determine how large the class structure is. The +@code{class_init_func} field from the @code{GtkTypeInfo} structure is +called for all the members in the types ancestry, including the +type. The order of this invocation proceeds from the root on down. For +example, the @code{GtkWidgetClass} is first initialized as an +@code{GtkObjectClass} by the object class initialization routine and +then by the widget class initialization routine. This allows the widget +class initialization routine to override values set by the object class +initialization routine. The returned structure is shared by all objects +of @var{type} and, as such, should not be modified. +@end deftypefun + +@deftypefun gpointer gtk_type_new (guint @var{type}) +Returns a new instance of an @var{type} object. The object structure is +created and initialized similarly to the class structure (as described +above). The @code{object_size} and @code{object_init_func} fields of the +@code{GtkTypeInfo} structure are used to determine the objects allocated +size and the object specific initialization routine. Similarly to the +class initialization, all the object initialization routines from the +root on down to the particular type being created are invoked. +@end deftypefun + +@deftypefun void gtk_type_describe_heritage (guint @var{type}) +Prints the type heritage for @var{type}. The heritage for a type +includes the type and all its parent types up the type tree. +@end deftypefun + +@deftypefun void gtk_type_describe_tree (guint @var{type}, gint @var{show_size}) +Prints the type tree which starts at @var{type}. @var{show_size} is a +boolean which determines whether type sizes are printed. +@end deftypefun + +@deftypefun gint gtk_type_is_a (guint @var{type}, guint @var{is_a_type}) +A predicate function which determines whether the relation @var{type} +is_a @var{is_a_type} is true. +@end deftypefun + +@section Object functions + +The GtkObject type is the root of the type hierarchy used by GTK. It +provides a minimal set of fields used to implement the actual +object, class and signal mechanisms, as well as several utility routines +which make dealing with objects easier. + +For the adventurous, see @ref{Object Implementation}. + +@deftypefun guint gtk_object_get_type (void) +Returns the @code{GtkObject} type identifier. +@end deftypefun + +@deftypefun void gtk_object_class_add_signals (GtkObjectClass *@var{class}, gint *@var{signals}, gint @var{nsignals}) +Adds @var{signals} to the @code{signals} field in the GtkObjectClass +structure @var{class}. @xref{Signals}. +@end deftypefun + +@deftypefun void gtk_object_destroy (GtkObject *@var{object}) +Performs checks to make sure it is alright to destroy @var{object} and +then emits the @code{destroy} signal. The check which is performed is to +make sure @var{object} is not already processing another signal. If this +were the case then destroying the object immediately would undoubtedly +cause problems as the other signal would not be able to tell the object +was destroyed. The solution is that if @var{object} is processing another +signal we mark @var{object} is needing to be destroyed. When we finish +processing of the other signal we check whether the object needs to be +destroyed. +@end deftypefun + +The GtkObject type provides a mechanism for associating arbitrary +amounts of data with an object. The data is associated with the object +using a character string key. The functions @code{gtk_object_set_data}, +@code{gtk_object_get_data}, and @code{gtk_object_remove_data} are the +interface to this mechanism. Two other routines, +@code{gtk_object_set_user_data} and @code{gtk_object_get_user_data}, +exist as convenience functions which simply use the same mechanism. + +@deftypefun void gtk_object_set_data (GtkObject *@var{object}, const char *@var{key}, gpointer @var{data}) +Associate @var{data} with @var{key} in the data list of @var{object}. +@end deftypefun + +@deftypefun gpointer gtk_object_get_data (GtkObject *@var{object}, const char *@var{key}) +Retrieve the data associated with @var{key} in the data list of @var{object}. +@end deftypefun + +@deftypefun void gtk_object_remove_data (GtkObject *@var{object}, const char *@var{key}) +Remove the data associated with @var{key} in the data list of @var{object}. +@end deftypefun + +@deftypefun void gtk_object_set_user_data (GtkObject *@var{object}, gpointer @var{data}) +Sets @var{data} into the @code{user_data} field of @var{object}. +@end deftypefun + +@deftypefun gpointer gtk_object_get_user_data (GtkObject *@var{object}) +Returns the @code{user_data} field of @var{object}. +@end deftypefun + +The GtkObject type also provides a mechanism for specifying +initialization values for fields. This general mechanism is called +object value stacks. The reason for using value stacks is that they can +simplify the life of the programmer. For instance, by default widgets +are non-visible when created. However, the ``visible'' value for widgets +may be specified so that widgets are made visible when created. (FIXME: +unfinished). + +@deftypefun void gtk_object_value_stack_new (guint @var{object_type}, const gchar *@var{value_id}, GtkParamType @var{value_type}) +@end deftypefun + +@deftypefun void gtk_object_push_value (guint @var{object_type}, const gchar *@var{value_id}, @dots{}) +Push a value on the value stack specified by @var{object_type} and +@var{value_id}. The type of value is implicitly given in the context of +@var{object_type} and @var{value_id}. (That is, it is not specified +explicitly in the function call). Only a single extra argument is +expected which is the data which is to be placed on the stack. +@end deftypefun + +@deftypefun void gtk_object_pop_value (guint @var{object_type}, const gchar *@var{value_id}) +Pop a value of the value stack specified by @var{object_type} and +@var{value_id}. +@end deftypefun + +@deftypefun gint gtk_object_peek_value (guint @var{object_type}, const gchar *@var{value_id}, gpointer @var{data}) +Peek at the value on the top of the value stack specified by +@var{object_type} and @var{value_id}. The @var{data} argument is +interpreted as the location of where to place the ``peeked'' data. For +instance, if the peeked data is of type @code{GTK_PARAM_POINTER}, then +@var{data} will be a pointer to a pointer. If the value stack is empty +or does not exist or an error occurs, @code{gtk_object_peek_value} will +return @code{FALSE}. On success it will return @code{TRUE}. +@end deftypefun + + +@node Signals, Widgets, Objects, Top +@comment node-name, next, previous, up +@chapter Signals Overview +@cindex Signals + +Signals are GTK's method for objects to perform callbacks. A signal is +an event which occurs upon an object. The programmer can connect to a +signal of an object which involves specifying a function to be called +when that signal is emitted in the specified object. + +When a signal is emitted, both the class function associated with the +signal (when it was defined) and all signal handlers installed for that +signal on the particular object emitting the signal are called. The +widget programmer can specify whether the class function is to be called +before after or both before and after the signal handlers installed by +the widget user. The widget user can, however, specify that their signal +handler is to be run after the class function (using the ``_after'' +signal connection routines). Any signal handling function can emit the +same signal on the same object while it is running causing that signal +emittion to either restart or to run recursively. Additionally, signal +emittion can be terminated prematurely. While both such abilities are +rarely used, they do allow for greater flexibility in regards to +signals. For instance, a programmer can attach to the key press event +signal and intercept all tab key presses from a widget. This particular +example is used in the file selection dialog to implement tab completion +of filenames and prevent the entry widget from inserting the tab into +its buffer. + +Signals are selected using either an integer identifier or a character +string name. It is convention to name the signal the same as the class +function which is associated with it. There are two versions of most of +the signal functions, one which takes an integer identifier and one +which takes a character string name for the signal. + +@deftypefun gint gtk_signal_new (gchar *@var{name}, GtkSignalRunType @var{run_type}, gint @var{object_type}, gint @var{function_offset}, GtkSignalMarsahller @var{marshaller}, GtkParamType @var{return_val}, gint @var{nparams}, @dots{}) +Create a new signal and give it the character string identifier +@var{name}. @var{name} needs to be unique in the context of +@var{object_type}'s branch of the class hierarchy. That is, +@var{object_type} cannot create a signal type with the same name as a +signal type created by one of its parent types. + +@var{run_type} specifies whether the class function should be run before +(@code{GTK_RUN_FIRST}), after (@code{GTK_RUN_LAST}) or both before and +after normal signal handlers (@code{GTK_RUN_BOTH}). Additionally, the +@code{GTK_RUN_NO_RECURSE} value can be or'ed with any of those values to +specify that the signal should not be recursive. By default, emitting +the same signal on the same widget will cause the signal to be emitted +twice. However, if the @code{GTK_RUN_NO_RECURSE} flag is specified, +emitting the same signal on the same widget will cause the current +signal emittion to be restarted. This allows the widget programmer to +specify the semantics of signal emittion on a per signal +basis. (The @code{GTK_RUN_NO_RECURSE} flag is used by the GtkAdjustment +widget). + +The @var{function_offset} is the byte offset from the start of the class +structure to the class function field within the class structure. The +easiest means to compute this offset is by using the +@code{GTK_SIGNAL_OFFSET} macro which takes the class structure type as +the first argument and the field as the second argument. For example, +@code{GTK_SIGNAL_OFFSET (GtkObjectClass, destroy)} will give the offset +of the @code{destroy} class function within the +@code{GtkObjectClass}. Note: An offset is specified instead of an +absolute location since there will be multiple instances of a class +structure being referenced. (The @code{GtkWidgetClass} structure ``is +a'' @code{GtkObjectClass} structure, etc.) + +The @var{marshaller} function is used to invoke a signal handler. Since +signal handlers may take different parameters and return values and a +general mechanism for invoking them is not apparent, the approach of +making the signal creator responsible for invoking the signal handler +was taken. (FIXME: unfinished). + +The @var{return_val} and @var{nparams} and the remaining arguments +specify the return value and the arguments to the signal handler +respectively. Note: There is an implicit first argument to every signal +handler which is the widget the signal has been emitted from. The +variable argument list (@var{@dots{}}) specifies the types of the +arguments. These can be one of @code{GTK_PARAM_CHAR}, +@code{GTK_PARAM_SHORT}, @code{GTK_PARAM_INT}, @code{GTK_PARAM_LONG}, +@code{GTK_PARAM_POINTER} or @code{GTK_PARAM_FUNCTION}. It is undefined +to specify @code{GTK_PARAM_NONE} as an argument type, however it is ok +to use @code{GTK_PARAM_NONE} for @var{return_val}. (This corresponds to +returning a @code{void}). + +@code{gtk_signal_new} returns the integer identifier of the newly +created signal. Signal identifiers start numbering at 1 and increase +upwards. A value of -1 will be returned if an error occurs. + +@strong{Note:} @code{gtk_signal_new} is only needed by widget writers. A +normal user of GTK will never needed to invoke this function. +@end deftypefun + +@deftypefun gint gtk_signal_lookup (gchar *@var{name}, gint @var{object_type}) +Returns the integer identifier for the signal referenced by @var{name} +and @var{object_type}. If @var{object_type} does not define the signal +@var{name}, then the signal is looked for in @var{object_type}'s parent +type recursively. +@end deftypefun + +@deftypefun gint gtk_signal_emit (GtkObject *@var{object}, gint @var{signal_type}, @dots{}) +Emit the signal specified by the integer identifier @var{signal_type} +from @var{object}. If an error occurs, @code{gtk_signal_emit} will +return @code{FALSE} and will return @code{TRUE} on success. The signal +definition determines the parameters passed in the variable argument +list (@code{@dots{}}). For example, if the signal is defined as: + +@example + gint (* event) (GtkWidget *widget, GdkEvent *event); +@end example + +Then a call to emit the ``event'' signal would look like: + +@example + GdkEvent event; + gint return_val; + @dots{} + gtk_signal_emit (some_object, + gtk_signal_lookup ("event", + GTK_OBJECT_TYPE (some_object)), + &event, &return_val); +@end example + +Notice that the @code{widget} argument is implicit in that the first +argument to every signal is a type derived from @code{GtkObject}. The +@var{return_val} argument is actually a pointer to the return value type +since the signal mechanism needs to be able to place the return value in +an actual location. And lastly, the @code{gtk_signal_lookup} call is +normally avoided by using the @code{gtk_signal_emit_by_name} function +instead. @code{gtk_signal_emit} is normally used internally by widgets +which know the signal identifier (since they defined the signal) and can +therefore side-step the cost of calling @code{gtk_signal_lookup}. +@end deftypefun + +@deftypefun gint gtk_signal_emit_by_name (GtkObject *@var{object}, gchar *@var{name}, @dots{}) +Similar to @code{gtk_signal_emit} except that the signal is referenced +by @var{name} instead of by its integer identifier. +@end deftypefun + +@deftypefun void gtk_signal_emit_stop (GtkObject *@var{object}, gint @var{signal_type}) +Stop the emission of the signal @var{signal_type} on +@var{object}. @var{signal_type} is the integer identifier for the signal +and can be determined using the function +@code{gtk_signal_lookup}. Alternatively, the function +@code{gtk_signal_emit_stop_by_name} can be used to refer to the signal +by name. Attempting to stop the emission of a signal that isn't being +emitted does nothing. +@end deftypefun + +@deftypefun void gtk_signal_emit_stop_by_name (GtkObject *@var{object}, gchar *@var{name}) +Similar to @code{gtk_signal_emit_stop} except that the signal is +referenced by @var{name} instead of by its integer identifier. +@end deftypefun + +@deftypefun gint gtk_signal_connect (GtkObject *@var{object}, gchar *@var{name}, GtkSignalFunc @var{func}, gpointer @var{func_data}) +Connects a signal handling function to a signal emitting +object. @var{func} is connected to the signal @var{name} emitted by +@var{object}. The arguments and returns type of @var{func} should match +the arguments and return type of the signal @var{name}. However, +@var{func} may take the extra argument of @var{func_data}. Due to the C +calling convention it is ok to ignore the extra argument. (It is ok to +ignore all the arguments in fact). + +@code{gtk_signal_connect} returns an integer identifier for the +connection which can be used to refer to it in the future. Specifically +it is useful for removing the connection and/or blocking it from being +used. +@end deftypefun + +@deftypefun gint gtk_signal_connect_after (GtkObject *@var{object}, gchar *@var{name}, GtkSignalFunc @var{func}, gpointer @var{func_data}) +Similar to @code{gtk_signal_connect} except the signal handler is +connected in the ``after'' slot. This allows a signal handler to be +guaranteed to run after other signal handlers connected to the same +signal on the same object and after the class function associated with +the signal. + +Like @code{gtk_signal_connect}, @code{gtk_signal_connect_after} returns +an integer identifier which can be used to refer to the connection. +@end deftypefun + +@deftypefun gint gtk_signal_connect_object (GtkObject *@var{object}, gchar *@var{name}, GtkSignalFunc @var{func}, GtkObject *@var{slot_object}) +Connects @var{func} to the signal @var{name} emitted by +@var{object}. Similar to @code{gtk_signal_connect} with the difference +that @var{slot_object} is passed as the first parameter to @var{func} +instead of the signal emitting object. This can be useful for connecting +a signal emitted by one object to a signal in another object. A common +usage is to connect the ``destroy'' signal of dialog to the ``clicked'' +signal emitted by a ``close'' button in the dialog. That is, the +``clicked'' signal emitted by the button will caused the ``destroy'' +signal to be emitted for the dialog. This is also the ``right'' way to +handle closing of a dialog since the ``destroy'' signal will be sent if +the dialog is deleted using a window manager function and this enables +the two methods of closing the window to be handled by the same +mechanism. Returns an integer identifier which can be used to refer to +the connection. +@end deftypefun + +@deftypefun gint gtk_signal_connect_object_after (GtkObject *@var{object}, gchar *@var{name}, GtkSignalFunc @var{func}, GtkObject *@var{slot_object}) +Similar to @code{gtk_signal_connect_object} except the signal handler is +connected in the ``after'' slot. This allows a signal handler to be +guaranteed to run after other signal handlers connected to the same +signal on the same object and after the class function associated with +the signal. Returns an integer identifier which can be used to refer to +the connection. +@end deftypefun + +@deftypefun void gtk_signal_disconnect (GtkObject *@var{object}, gint @var{id}) +Disconnects a signal handler from an object. The signal handler is +identified by the integer @var{id} which is returned by the +@code{gtk_signal_connect*} family of functions. +@end deftypefun + +@deftypefun void gtk_signal_disconnect_by_data (GtkObject *@var{object}, gpointer @var{data}) +Disconnects a signal handler from an object. The signal handler is +identified by the @var{data} argument specified as the @var{func_data} +argument to the @code{gtk_signal_connect*} family of functions. For the +@code{gtk_signal_connect_object*} functions, @var{data} refers to the +@var{slot_object}. + +@strong{Note:} This will remove all signal handlers connected to +@var{object} which were connected using @var{data} as their +@var{func_data} argument. Multiple signal handlers may be disconnected +with this call. +@end deftypefun + +@deftypefun void gtk_signal_handler_block (GtkObject *@var{object}, gint @var{id}) +Blocks calling of a signal handler during signal emission. The signal +handler is identified by the integer @var{id} which is returned by the +@code{gtk_signal_connect*} family of functions. If the signal is already +blocked no change is made. +@end deftypefun + +@deftypefun void gtk_signal_handler_block_by_data (GtkObject *@var{object}, gint @var{data}) +Blocks calling of a signal handler during signal emission. The signal +handler is identified by the @var{data} argument specified as the +@var{func_data} argument to the @code{gtk_signal_connect*} family of +functions. For the @code{gtk_signal_connect_object*} functions, +@var{data} refers to the @var{slot_object}. If the signal is already +blocked no change is made. + +@strong{Note:} This will block all signal handlers connected to +@var{object} which were connected using @var{data} as their +@var{func_data} argument. Multiple signal handlers may be blocked +with this call. +@end deftypefun + +@deftypefun void gtk_signal_handler_unblock (GtkObject *@var{object}, gint @var{id}) +Unblocks calling of a signal handler during signal emission. The signal +handler is identified by the integer @var{id} which is returned by the +@code{gtk_signal_connect*} family of functions. If the signal is already +unblocked no change is made. +@end deftypefun + +@deftypefun void gtk_signal_handler_unblock_by_data (GtkObject *@var{object}, gint @var{data}) +Unblocks calling of a signal handler during signal emission. The signal +handler is identified by the @var{data} argument specified as the +@var{func_data} argument to the @code{gtk_signal_connect*} family of +functions. For the @code{gtk_signal_connect_object*} functions, +@var{data} refers to the @var{slot_object}. If the signal is already +unblocked no change is made. + +@strong{Note:} This will unblock all signal handlers connected to +@var{object} which were connected using @var{data} as their +@var{func_data} argument. Multiple signal handlers may be unblocked +with this call. +@end deftypefun + +@deftypefun void gtk_signal_handlers_destroy (GtkObject *@var{object}) +Destroy all of the signal handlers connected to @var{object}. There +should normally never be reason to call this function as it is called +automatically when @var{object} is destroyed. +@end deftypefun + +@deftypefun void gtk_signal_default_marshaller (GtkObject *@var{object}, GtkSignalFunc @var{func}, gpointer @var{func_data}, GtkSignalParam *@var{params}) +@code{gtk_signal_new} requires a callback in order to actually call a +signal handler for a particular signal. The vast majority of signals are +of the particular form: + +@example + (* std_signal) (gpointer std_arg); +@end example + +@code{gtk_signal_default_marshaller} is a signal marshaller which +marshals arguments for a signal of that form. +@end deftypefun + + +@node Widgets, Other Objects, Signals, Top +@comment node-name, next, previous, up +@chapter Widget Overview +@cindex Widgets + + +Widgets are the general term used to describe user interface objects. A +widget defines a class interface that all user interface objects conform +to. This interface allows a uniform method for dealing with operations +common to all objects such as hiding and showing, size requisition and +allocation and events. + +The common interface that widgets must adhere to is described by the +GtkWidget and GtkWidgetClass structure. For the purposes of using GTK +these structures can be considered read-only and, for the most part, +opaque. + +All widget creation routines in GTK return pointers to GtkWidget +structures. In reality, all widget creation routines create structures +that can be viewed as equivalent to the GtkWidget structure, but often +have contain additional information. @xref{Object Implementation} + +The widgets available for use are implemented in a hierarchy. Several +widgets exist solely as common bases for more specific widgets. For +example, it is not possible to create a ruler widget itself, but the +ruler widget provides a base and functionality common to the horizontal +and vertical rulers. + +The available widgets (in alphabetical order): + +@menu +* GtkAlignment:: The alignment widget. +* GtkArrow:: The arrow widget. +* GtkBin:: The bin widget. +* GtkBox:: The box widget. +* GtkButton:: The button widget. +* GtkCheckButton:: The check button widget. +* GtkCheckMenuItem:: The check menu item widget. +* GtkContainer:: The container widget. +* GtkDialog:: The dialog widget. +* GtkDrawingArea:: The drawing area widget. +* GtkEntry:: The entry widget. +* GtkFileSelection:: The file selection dialog widget. +* GtkFrame:: The frame widget. +* GtkHBox:: The horizontal box widget. +* GtkHRuler:: The horizontal ruler widget. +* GtkHScale:: The horizontal scale widget. +* GtkHScrollbar:: The horizontal scrollbar widget. +* GtkHSeparator:: The horizontal separator widget. +* GtkImage:: The image widget. +* GtkItem:: The item widget. +* GtkLabel:: The label widget. +* GtkList:: The list widget. +* GtkListItem:: The list item widget. +* GtkMenu:: The menu widget. +* GtkMenuBar:: The menu bar widget. +* GtkMenuItem:: The menu item widget. +* GtkMenuShell:: The menu shell widget. +* GtkMisc:: The misc widget. +* GtkNotebook:: The notebook widget. +* GtkOptionMenu:: The option menu widget. +* GtkPixmap:: The pixmap widget. +* GtkPreview:: The preview widget. +* GtkProgressBar:: The progress bar widget. +* GtkRadioButton:: The radio button widget. +* GtkRadioMenuItem:: The radio menu item widget. +* GtkRange:: The range widget. +* GtkRuler:: The ruler widget. +* GtkScale:: The scale widget. +* GtkScrollbar:: The scrollbar widget. +* GtkScrolledWindow:: The scrolled window widget. +* GtkSeparator:: The separator widget. +* GtkTable:: The table widget. +* GtkText:: The text widget. +* GtkToggleButton:: The toggle button widget. +* GtkTree:: The tree widget. +* GtkTreeItem:: The tree item widget. +* GtkVBox:: The vertical box widget. +* GtkViewport:: The viewport widget. +* GtkVRuler:: The vertical ruler widget. +* GtkVScale:: The vertical scale widget. +* GtkVScrollbar:: The vertical scrollbar widget. +* GtkVSeparator:: The vertical separator widget. +* GtkWidget:: The base widget type. +* GtkWindow:: The window widget. +@end menu + + +@node GtkAlignment, GtkArrow, Widgets, Widgets +@comment node-name, next, previous, up +@section The alignment widget + + +@subsection Description + +The alignment widget is a container (@pxref{GtkContainer}) derived from +the bin widget (@pxref{GtkBin}). Its entire purpose is to give the +programmer flexibility in how the child it manages is positioned when a +window is resized. + +Normally, a widget is allocated at least as much size as it +requests. (@pxref{GtkContainer} for a discussion of geometry +management). When a widget is allocated more size than it requests there +is a question of how the widget should expand. By convention, most GTK +widgets expand to fill their allocated space. Sometimes this behavior is +not desired. The alignment widget allows the programmer to specify how a +widget should expand and position itself to fill the area it is +allocated. + +@subsection Options + +@defopt xscale +@defoptx yscale +The @var{xscale} and @var{yscale} options specify how to scale the child +widget. If the scale value is 0.0, the child widget is allocated exactly +the size it requested in that dimension. If the scale value is 1.0, the +child widget is allocated all of the space in a dimension. A scale value +of 1.0 for both x and y is equivalent to not using an alignment widget. +@end defopt + +@defopt xalign +@defoptx yalign +The @var{xalign} and @var{yalign} options specify how to position the +child widget when it is not allocated all the space available to it +(because the @var{xscale} and/or @var{yscale} options are less than +1.0). If an alignment value is 0.0 the widget is positioned to the left +(or top) of its allocated space. An alignment value of 1.0 positions the +widget to the right (or bottom) of its allocated space. A common usage +is to specify @var{xalign} and @var{yalign} to be 0.5 which causes the +widget to be centered within its allocated area. +@end defopt + +@subsection Signals + +@subsection Functions + +@deftypefun guint gtk_alignment_get_type (void) +Returns the @code{GtkAlignment} type identifier. +@end deftypefun + +@deftypefun GtkWidget* gtk_alignment_new (gfloat @var{xalign}, gfloat @var{yalign}, gfloat @var{xscale}, gfloat @var{yscale}) +Create a new @code{GtkAlignment} object and initialize it with the +values @var{xalign}, @var{yalign}, @var{xscale} and @var{yscale}. The +new widget is returned as a pointer to a @code{GtkWidget} +object. @code{NULL} is returned on failure. +@end deftypefun + +@deftypefun void gtk_alignment_set (GtkAlignment *@var{alignment}, gfloat @var{xalign}, gfloat @var{yalign}, gfloat @var{xscale}, gfloat @var{yscale}) +Set the @var{xalign}, @var{yalign}, @var{xscale} and @var{yscale} options +of an alignment widget. It is important to not set the fields of the +@code{GtkAlignment} structure directly (or, for that matter, any type +derived from @code{GtkObject}). +@end deftypefun + +@gtkstdmacros{Alignment, ALIGNMENT} + + +@page +@node GtkArrow, GtkBin, GtkAlignment, Widgets +@comment node-name, next, previous, up +@section The arrow widget + +@subsection Description + +The arrow widget is derived from the misc widget (@pxref{GtkMisc}) and +is intended for use where a directional arrow (in one of the four +cardinal directions) is desired. As such, it has very limited +functionality and basically only draws itself in a particular direction +and with a particular shadow type. The arrow widget will expand to fill +all the space it is allocated. + +@subsection Options + +@defopt arrow_type +The @var{arrow_type} option specifies which direction the arrow will +point. It can be one of @code{GTK_ARROW_UP}, @code{GTK_ARROW_DOWN}, +@code{GTK_ARROW_LEFT} or @code{GTK_ARROW_RIGHT}. +@end defopt + +@defopt shadow_type +The @var{shadow_type} option specifies how to draw the shadow for the +arrow. Currently, only the @code{GTK_SHADOW_IN} and +@code{GTK_SHADOW_OUT} shadow types are supported for drawing +arrows. Other shadow types will cause nothing to be drawn. +@end defopt + +@subsection Signals + +@subsection Functions + +@deftypefun guint gtk_arrow_get_type (void) +Returns the @code{GtkArrow} type identifier. +@end deftypefun + +@deftypefun GtkWidget* gtk_arrow_new (GtkArrowType @var{arrow_type}, GtkShadowType @var{shadow_type}) +Create a new @code{GtkArrow} object and initialize it with the values +@var{arrow_type} and @var{shadow_type}. The new widget is returned as a +pointer to a @code{GtkWidget} object. @code{NULL} is returned on +failure. +@end deftypefun + +@deftypefun void gtk_arrow_set (GtkArrow *@var{arrow}, GtkArrowType @var{arrow_type}, GtkShadowType @var{shadow_type}) +Set the @var{arrow_type} and @var{shadow_type} options of an arrow +widget. It is important to not set the fields of the @code{GtkArrow} +structure directly (or, for that matter, any type derived from +@code{GtkObject}). +@end deftypefun + +@gtkstdmacros{Arrow, ARROW} + + +@page +@node GtkBin, GtkBox, GtkArrow, Widgets +@comment node-name, next, previous, up +@section The bin widget + +@subsection Description + +The bin widget is a container (@pxref{GtkContainer}) derived from the +container widget. It is an abstract base class. That is, it is not +possible to create an actual bin widget. It exists only to provide a +base of functionality for other widgets. Specifically, the bin widget +provides a base for several other widgets that contain only a single +child. These widgets include alignments (@pxref{GtkAlignment}), frames +(@pxref{GtkFrame}), items (@pxref{GtkItem}), viewports +(@pxref{GtkViewport}) and windows (@pxref{GtkWindow}) + +@subsection Signals + +@subsection Functions + +@deftypefun guint gtk_bin_get_type (void) +Returns the @code{GtkBin} type identifier. +@end deftypefun + +@gtkstdmacros{Bin, BIN} + + +@page +@node GtkBox, GtkButton, GtkBin, Widgets +@comment node-name, next, previous, up +@section The box widget + + +@subsection Description + +The box widget is a container (@pxref{GtkContainer}) derived from the +container widget. It is an abstract base class used by the horizontal +box (@pxref{GtkHBox}) and vertical box (@pxref{GtkVBox}) widgets to +provide a base of common functionality. + +A box provides an abstraction for organizing the position and size of +widgets. Widgets in a box are layed out horizontally or vertically. By +using a box widget appropriately, a programmer can control how widgets +are positioned and how they will be allocated space when a window gets +resized. + +The key attribute of boxes is that they position their children in a +single row (horizontal boxes) or column (vertical boxes). In the case of +horizontal boxes, all children are stretched vertically. The vertical +size of the box is determined by the largest vertical requisition of all +of its children. Similarly, a vertical box streches all of its children +horizontally. The horizontal size (of the vertical box) is determined by +the largest horizontal requisition of all of its children. An alignment +widget (@pxref{GtkAlignment}) can be used to control child allocation +more precisely on a per child basis. + +The second attribute of boxes is how they expand children. In the case +of a horizontal box, the main control is over how children are expanded +horizontally to fill the allocated area. (The rest of this discussion +will focus on horizontal boxes but it applies to vertical boxes as +well). + +There are two flags which can be set controlling how a widget is +expanded horizontally in a horizontal box. These are the @code{expand} +and @code{fill}. There operation is fairly simple. If @code{expand} is +set, the childs potentially allocated area will expand to fill available +space. If @code{fill} is set, the childs actual allocated area will be +its potentially allocated area. There is a difference between +the potentially area (which is the area the box widget sets aside for +the child) and the actual allocated area (which is the area the box +widget actual allocates for the widget via +@code{gtk_widget_size_allocate}). + +The allocation of space to children occurs as follows (for horizontal +boxes): +@enumerate +@item +All children are allocated at least their requested size horizontally +and the maximum requested child size vertically. + +@item +Any child with the @code{expand} flag set is allocated @code{extra_width +/ nexpand_children} extra pixels horizontally. If the @code{homogeneous} +flag was set, all children are considered to have the @code{expand} flag +set. That is, all children will be allocated the same area.The +horizontal box is a fair widget and, as such, divides up any extra +allocated space evenly among the ``expand'' children. (Those children +which have the @code{expand} flag set). The exception occurs when +@code{extra_width / nexpand_children} does not divide cleanly. The extra +space is given to the last widget. + +@item +@code{spacing} number of pixels separate each child. Note: The +separation is between the potentially allocated area for each child and +not the actual allocated area. The @code{padding} value associated with +each child causes that many pixels to be left empty to each side of the +child. + +@item +If a child has the @code{fill} flag set it is allocated its potentially +allocated area. If it does not, it is allocated its requested size +horizontally and centered within its potentially allocated area. Its +vertical allocation is still the maximum requested size of any child. + +@item +Children placed at the start of the box are placed in order of addition +to the box from left to right in the boxes allocated area.. Children +placed at the end of the box are placed in order of addition from right +to left in the boxes allocated area. +@end enumerate + +@xref{GtkHBox}, and @ref{GtkVBox}, for code examples of using horizontal +and vertical boxes. + +@subsection Options + +@c FIXME: options for GtkBox + +@subsection Signals + +@subsection Functions + +@deftypefun guint gtk_box_get_type (void) +Returns the @code{GtkBox} type identifier. +@end deftypefun + +@deftypefun void gtk_box_pack_start (GtkBox *@var{box}, GtkWidget *@var{child}, gint @var{expand}, gint @var{fill}, gint @var{padding}) +Add @var{child} to the front of @var{box}. The flags @var{expand} and +@var{fill} and the padding value of @var{padding} are associated with +@var{child}. +@end deftypefun + +@deftypefun void gtk_box_pack_end (GtkBox *@var{box}, GtkWidget *@var{child}, gint @var{expand}, gint @var{fill}, gint @var{padding}) +Add @var{child} to the end of @var{box}. The flags @var{expand} and +@var{fill} and the padding value of @var{padding} are associated with +@var{child}. +@end deftypefun + +@deftypefun void gtk_box_pack_start_defaults (GtkBox *@var{box}, GtkWidget *@var{widget}) +A convenience function which is equivalent to the following: + +@example + gtk_box_pack_start (@var{box}, @var{widget}, TRUE, TRUE, 0); +@end example +@end deftypefun + +@deftypefun void gtk_box_pack_end_defaults (GtkBox *@var{box}, GtkWidget *@var{widget}) +A convenience function which is equivalent to the following: + +@example + gtk_box_pack_start (@var{box}, @var{widget}, TRUE, TRUE, 0); +@end example +@end deftypefun + +@gtkstdmacros{Box, BOX} + + +@page +@node GtkButton, GtkCheckButton, GtkBox, Widgets +@comment node-name, next, previous, up +@section The button widget + + +@subsection Description + +@subsection Signals + +@deftypefn Signal void GtkButton::pressed (GtkButton *@var{button}) +@end deftypefn + +@deftypefn Signal void GtkButton::released (GtkButton *@var{button}) +@end deftypefn + +@deftypefn Signal void GtkButton::clicked (GtkButton *@var{button}) +@end deftypefn + +@deftypefn Signal void GtkButton::enter (GtkButton *@var{button}) +@end deftypefn + +@deftypefn Signal void GtkButton::leave (GtkButton *@var{button}) +@end deftypefn + +@subsection Functions + +@deftypefun guint gtk_button_get_type (void) +@end deftypefun + +@deftypefun GtkWidget* gtk_button_new (void) +@end deftypefun + +@deftypefun GtkWidget* gtk_button_new_with_label (gchar *@var{label}) +@end deftypefun + +@deftypefun void gtk_button_pressed (GtkButton *@var{button}) +@end deftypefun + +@deftypefun void gtk_button_released (GtkButton *@var{button}) +@end deftypefun + +@deftypefun void gtk_button_clicked (GtkButton *@var{button}) +@end deftypefun + +@deftypefun void gtk_button_enter (GtkButton *@var{button}) +@end deftypefun + +@deftypefun void gtk_button_leave (GtkButton *@var{button}) +@end deftypefun + +@gtkstdmacros{Button, BUTTON} + + +@page +@node GtkCheckButton, GtkCheckMenuItem, GtkButton, Widgets +@comment node-name, next, previous, up +@section The check button widget + + +@subsection Description + +@subsection Signals + +@subsection Functions + +@deftypefun guint gtk_check_button_get_type (void) +@end deftypefun + +@deftypefun GtkWidget* gtk_check_button_new (void) +@end deftypefun + +@deftypefun GtkWidget* gtk_check_button_new_with_label (gchar *@var{label}) +@end deftypefun + +@deftypefun GtkCheckButton* GTK_CHECK_BUTTON (gpointer @var{obj}) +@end deftypefun + +@deftypefun GtkCheckButtonClass* GTK_CHECK_BUTTON_CLASS (gpointer @var{class}) +@end deftypefun + +@deftypefun gint GTK_IS_CHECK_BUTTON (gpointer @var{obj}) +@end deftypefun + +@gtkstdmacros{CheckButton, CHECK_BUTTON} + + +@page +@node GtkCheckMenuItem, GtkContainer, GtkCheckButton, Widgets, +@comment node-name, next, previous, up +@section The check menu item widget + + +@subsection Description + +@subsection Signals + +@deftypefn Signal void GtkCheckMenuItem::toggled (GtkCheckMenuItem *@var{check_menu_item}) +@end deftypefn + +@subsection Functions + +@deftypefun guint gtk_check_menu_item_get_type (void) +@end deftypefun + +@deftypefun GtkWidget* gtk_check_menu_item_new (void) +@end deftypefun + +@deftypefun GtkWidget* gtk_check_menu_item_new_with_label (gchar *@var{label}) +@end deftypefun + +@deftypefun void gtk_check_menu_item_set_state (GtkCheckMenuItem *@var{check_menu_item}, gint @var{state}) +@end deftypefun + +@deftypefun void gtk_check_menu_item_toggled (GtkCheckMenuItem *@var{check_menu_item}) +@end deftypefun + +@gtkstdmacros{CheckMenuItem, CHECK_MENU_ITEM} + + +@page +@node GtkContainer, GtkDialog, GtkCheckMenuItem, Widgets +@comment node-name, next, previous, up +@section The container widget + + +@subsection Description + +@subsection Signals + +@deftypefn Signal void GtkContainer::add (GtkContainer *@var{container}, GtkWidget *@var{widget}) +@end deftypefn + +@deftypefn Signal void GtkContainer::remove (GtkContainer *@var{container}, GtkWidget *@var{widget}) +@end deftypefn + +@deftypefn Signal void GtkContainer::need_resize (GtkContainer *@var{container}, GtkWidget *@var{widget}) +@end deftypefn + +@deftypefn Signal void GtkContainer::foreach (GtkContainer *@var{container}, GtkCallback @var{callback}, gpointer @var{callback_data}) +@end deftypefn + +@deftypefn Signal gint GtkContainer::focus (GtkContainer *@var{container}, GtkDirectionType @var{direction}) +@end deftypefn + +@subsection Functions + +@deftypefun guint gtk_container_get_type (void) +@end deftypefun + +@deftypefun void gtk_container_border_width (GtkContainer *@var{container}, gint @var{border_width}) +@end deftypefun + +@deftypefun void gtk_container_add (GtkContainer *@var{container}, GtkWidget *@var{widget}) +@end deftypefun + +@deftypefun void gtk_container_remove (GtkContainer *@var{container}, GtkWidget *@var{widget}) +@end deftypefun + +@deftypefun void gtk_container_disable_resize (GtkContainer *@var{container}) +@end deftypefun + +@deftypefun void gtk_container_enable_resize (GtkContainer *@var{container}) +@end deftypefun + +@deftypefun void gtk_container_block_resize (GtkContainer *@var{container}) +@end deftypefun + +@deftypefun void gtk_container_unblock_resize (GtkContainer *@var{container}) +@end deftypefun + +@deftypefun gint gtk_container_need_resize (GtkContainer *@var{container}, GtkWidget *@var{widget}) +@end deftypefun + +@deftypefun void gtk_container_check_resize (GtkContainer *@var{container}, GtkWidget *@var{widget}) +@end deftypefun + +@deftypefun void gtk_container_foreach (GtkContainer *@var{container}, GtkCallback @var{callback}, gpointer @var{callback_data}) +@end deftypefun + +@deftypefun void gtk_container_focus (GtkContainer *@var{container}, GtkDirectionType @var{direction}) +@end deftypefun + +@deftypefun GList* gtk_container_children (GtkContainer @var{container}) +@end deftypefun + +@gtkstdmacros{Container, CONTAINER} + + +@page +@node GtkDialog, GtkDrawingArea, GtkContainer, Widgets +@comment node-name, next, previous, up +@section The dialog widget + + +@subsection Description + +@subsection Signals + +@subsection Functions + +@deftypefun guint gtk_dialog_get_type (void) +@end deftypefun + +@deftypefun GtkWidget* gtk_dialog_new (void) +@end deftypefun + +@gtkstdmacros{Dialog, DIALOG} + + +@page +@node GtkDrawingArea, GtkEntry, GtkDialog, Widgets +@comment node-name, next, previous, up +@section The drawing area widget + + +@subsection Description + +@subsection Signals + +@subsection Functions + +@deftypefun guint gtk_drawing_area_get_type (void) +@end deftypefun + +@deftypefun GtkWidget* gtk_drawing_area_new (void) +@end deftypefun + +@deftypefun void gtk_drawing_area_size (GtkDrawingArea *@var{darea}, gint @var{width}, gint @var{height}) +@end deftypefun + +@gtkstdmacros{DrawingArea, DRAWING_AREA} + + +@page +@node GtkEntry, GtkFileSelection, GtkDrawingArea, Widgets +@comment node-name, next, previous, up +@section The entry widget + + +@subsection Description + +@subsection Signals + +@deftypefn Signal void GtkEntry::insert (GtkEntry *@var{entry}, gchar *@var{text}, gint @var{length}, gint *@var{position}) +@end deftypefn + +@deftypefn Signal void GtkEntry::delete (GtkEntry *@var{entry}, gint @var{start_pos}, gint @var{end_pos}) +@end deftypefn + +@deftypefn Signal void GtkEntry::changed (GtkEntry *@var{entry}) +@end deftypefn + +@subsection Functions + +@deftypefun guint gtk_entry_get_type (void) +@end deftypefun + +@deftypefun GtkWidget* gtk_entry_new (void) +@end deftypefun + +@deftypefun void gtk_entry_set_text (GtkEntry *@var{entry}, gchar *@var{text}) +@end deftypefun + +@deftypefun void gtk_entry_append_text (GtkEntry *@var{entry}, gchar *@var{text}) +@end deftypefun + +@deftypefun void gtk_entry_prepend_text (GtkEntry *@var{entry}, gchar *@var{text}) +@end deftypefun + +@deftypefun void gtk_entry_set_position (GtkEntry *@var{entry}, gint @var{position}) +@end deftypefun + +@deftypefun gchar* gtk_entry_get_text (GtkEntry *@var{entry}) +@end deftypefun + +@gtkstdmacros{Entry, ENTRY} + + +@page +@node GtkFileSelection, GtkFrame, GtkEntry, Widgets +@comment node-name, next, previous, up +@section The file selection dialog widget + + +@subsection Description + +@subsection Signals + +@subsection Functions + +@deftypefun guint gtk_file_selection_get_Type (void) +@end deftypefun + +@deftypefun GtkWidget* gtk_file_selection_new (gchar *@var{title}) +@end deftypefun + +@deftypefun void gtk_file_selection_set_filename (GtkFileSelection *@var{filesel}, gchar *@var{filename}) +@end deftypefun + +@deftypefun gchar* gtk_file_selection_get_filename (GtkFileSelection *@var{filesel}) +@end deftypefun + +@gtkstdmacros{FileSelection, FILE_SELECTION} + + +@page +@node GtkFrame, GtkHBox, GtkFileSelection, Widgets +@comment node-name, next, previous, up +@section The frame widget + + +@subsection Description + +@subsection Signals + +@subsection Functions + +@deftypefun guint gtk_frame_get_type (void) +@end deftypefun + +@deftypefun GtkWidget* gtk_frame_new (gchar *@var{label}) +@end deftypefun + +@deftypefun void gtk_frame_set_label (GtkFrame *@var{frame}, gchar *@var{label}) +@end deftypefun + +@deftypefun void gtk_frame_set_label_align (GtkFrame *@var{frame}, gfloat @var{xalign}, gfloat @var{yalign}) +@end deftypefun + +@deftypefun void gtk_frame_set_shadow_type (GtkFrame *@var{frame}, GtkShadowType @var{type}) +@end deftypefun + +@gtkstdmacros{Frame, FRAME} + + +@page +@node GtkHBox, GtkHRuler, GtkFrame, Widgets +@comment node-name, next, previous, up +@section The horizontal box widget + + +@subsection Description + +@subsection Signals + +@subsection Functions + +@deftypefun guint gtk_hbox_get_type (void) +@end deftypefun + +@deftypefun GtkWidget* gtk_hbox_new (gint @var{homogeneous}, gint @var{spacing}) +@end deftypefun + +@gtkstdmacros{HBox, HBOX} + + +@page +@node GtkHRuler, GtkHScale, GtkHBox, Widgets +@comment node-name, next, previous, up +@section The horizontal ruler widget + + +@subsection Description + +@subsection Signals + +@subsection Functions + +@deftypefun guint gtk_hruler_get_type (void) +@end deftypefun + +@deftypefun GtkWidget* gtk_hruler_new (void) +@end deftypefun + +@gtkstdmacros{HRuler, HRULER} + + +@page +@node GtkHScale, GtkHScrollbar, GtkHRuler, Widgets +@comment node-name, next, previous, up +@section The horizontal scale widget + + +@subsection Description + +@subsection Signals + +@subsection Functions + +@deftypefun guint gtk_hscale_get_type (void) +@end deftypefun + +@deftypefun GtkWidget* gtk_hscale_new (GtkAdjustment *@var{adjustment}) +@end deftypefun + +@gtkstdmacros{HScale, HSCALE} + + +@page +@node GtkHScrollbar, GtkHSeparator, GtkHScale, Widgets +@comment node-name, next, previous, up +@section The horizontal scrollbar widget + + +@subsection Description + +@subsection Signals + +@subsection Functions + +@deftypefun guint gtk_hscrollbar_get_type (void) +@end deftypefun + +@deftypefun GtkWidget* gtk_hscrollbar_new (GtkAdjustment *@var{adjustment}) +@end deftypefun + +@gtkstdmacros{HScrollbar, HSCROLLBAR} + + +@page +@node GtkHSeparator, GtkImage, GtkHScrollbar, Widgets +@comment node-name, next, previous, up +@section The horizontal separator widget + + +@subsection Description + +@subsection Signals + +@subsection Functions + +@deftypefun guint gtk_hseparator_get_type (void) +@end deftypefun + +@deftypefun GtkWidget* gtk_hseparator_new (void) +@end deftypefun + +@gtkstdmacros{HSeparator, HSEPARATOR} + + +@page +@node GtkImage, GtkItem, GtkHSeparator, Widgets +@comment node-name, next, previous, up +@section The image widget + + +@subsection Description + +@subsection Signals + +@subsection Functions + +@deftypefun guint gtk_image_get_type (void) +@end deftypefun + +@deftypefun GtkWidget* gtk_image_new (GdkImage *@var{val}) +@end deftypefun + +@deftypefun void gtk_image_set (GtkImage *@var{image}, GdkImage *@var{val}) +@end deftypefun + +@deftypefun void gtk_image_get (GtkImage *@var{image}, GdkImage **@var{val}) +@end deftypefun + +@gtkstdmacros{Image, IMAGE} + + +@page +@node GtkItem, GtkLabel, GtkImage, Widgets +@comment node-name, next, previous, up +@section The item widget + + +@subsection Description + +@subsection Signals + +@deftypefn Signal void GtkItem::select (GtkItem *@var{item}) +@end deftypefn + +@deftypefn Signal void GtkItem::deselect (GtkItem *@var{item}) +@end deftypefn + +@deftypefn Signal void GtkItem::toggle (GtkItem *@var{toggle}) +@end deftypefn + +@subsection Functions + +@deftypefun guint gtk_item_get_type (void) +@end deftypefun + +@deftypefun void gtk_item_select (GtkItem *@var{item}) +@end deftypefun + +@deftypefun void gtk_item_deselect (GtkItem *@var{item}) +@end deftypefun + +@deftypefun void gtk_item_toggle (GtkItem *@var{item}) +@end deftypefun + +@gtkstdmacros{Item, ITEM} + + +@page +@node GtkLabel, GtkList, GtkItem, Widgets +@comment node-name, next, previous, up +@section The label widget + + +@subsection Description + +@subsection Signals + +@subsection Functions + +@deftypefun guint gtk_label_get_type (void) +@end deftypefun + +@deftypefun GtkWidget* gtk_label_new (GtkLabel *@var{label}, gchar *@var{str}) +@end deftypefun + +@deftypefun void gtk_label_set (GtkLabel *@var{label}, gchar *@var{str}) +@end deftypefun + +@deftypefun void gtk_label_get (GtkLabel *@var{label}, gchar **@var{str}) +@end deftypefun + +@gtkstdmacros{Label, LABEL} + + +@page +@node GtkList, GtkListItem, GtkLabel, Widgets +@comment node-name, next, previous, up +@section The list widget + + +@subsection Description + +@subsection Signals + +@deftypefn Signal void GtkList::selection_changed (GtkList *@var{list}) +@end deftypefn + +@deftypefn Signal void GtkList::select_child (GtkList *@var{list}, GtkWidget *@var{child}) +@end deftypefn + +@deftypefn Signal void GtkList::unselect_child (GtkList *@var{list}, GtkWidget *@var{child}) +@end deftypefn + +@subsection Functions + +@deftypefun guint gtk_list_get_type (void) +@end deftypefun + +@deftypefun GtkWidget* gtk_list_new (void) +@end deftypefun + +@deftypefun void gtk_list_insert_items (GtkList *@var{list}, GList *@var{items}, gint @var{position}) +@end deftypefun + +@deftypefun void gtk_list_append_items (GtkList *@var{list}, GList *@var{items}) +@end deftypefun + +@deftypefun void gtk_list_prepend_items (GtkList *@var{list}, GList *@var{items}) +@end deftypefun + +@deftypefun void gtk_list_remove_items (GtkList *@var{list}, GList *@var{items}) +@end deftypefun + +@deftypefun void gtk_list_clear_items (GtkList *@var{list}, gint @var{start}, gint @var{end}) +@end deftypefun + +@deftypefun void gtk_list_select_item (GtkList *@var{list}, gint @var{item}) +@end deftypefun + +@deftypefun void gtk_list_unselect_item (GtkList *@var{list}, gint @var{item}) +@end deftypefun + +@deftypefun void gtk_list_select_child (GtkList *@var{list}, GtkWidget *@var{child}) +@end deftypefun + +@deftypefun void gtk_list_unselect_child (GtkList *@var{list}, GtkWidget *@var{child}) +@end deftypefun + +@deftypefun gint gtk_list_child_position (GtkList *@var{list}, GtkWidget *@var{child}) +@end deftypefun + +@deftypefun void gtk_list_set_selection_mode (GtkList *@var{list}, GtkSelectionMode @var{mode}) +@end deftypefun + +@gtkstdmacros{List, LIST} + + +@page +@node GtkListItem, GtkMenu, GtkList, Widgets +@comment node-name, next, previous, up +@section The list item widget + + +@subsection Description + +@subsection Signals + +@subsection Functions + +@deftypefun guint gtk_list_item_get_type (void) +@end deftypefun + +@deftypefun GtkWidget* gtk_list_item_new (void) +@end deftypefun + +@deftypefun GtkWidget* gtk_list_item_new_with_label (gchar *@var{label}) +@end deftypefun + +@deftypefun void gtk_list_item_select (GtkListItem *@var{list_item}) +@end deftypefun + +@deftypefun void gtk_list_item_deselect (GtkListItem *@var{list_item}) +@end deftypefun + +@gtkstdmacros{ListItem, LIST_ITEM} + + +@page +@node GtkMenu, GtkMenuBar, GtkListItem, Widgets +@comment node-name, next, previous, up +@section The menu widget + + +@subsection Description + +@subsection Signals + +@subsection Functions + +@deftypefun guint gtk_menu_get_type (void) +@end deftypefun + +@deftypefun GtkWidget* gtk_menu_new (void) +@end deftypefun + +@deftypefun void gtk_menu_append (GtkMenu *@var{menu}, GtkWidget *@var{child}) +@end deftypefun + +@deftypefun void gtk_menu_prepend (GtkMenu *@var{menu}, GtkWidget *@var{child}) +@end deftypefun + +@deftypefun void gtk_menu_insert (GtkMenu *@var{menu}, GtkWidget *@var{child}, gint @var{position}) +@end deftypefun + +@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}) +@end deftypefun + +@deftypefun void gtk_menu_popdown (GtkMenu *@var{menu}) +@end deftypefun + +@deftypefun GtkWidget* gtk_menu_get_active (GtkMenu *@var{menu}) +@end deftypefun + +@deftypefun void gtk_menu_set_active (GtkMenu *@var{menu}) +@end deftypefun + +@deftypefun void gtk_menu_set_accelerator_table (GtkMenu *@var{menu}, GtkAcceleratorTable *@var{table}) +@end deftypefun + +@gtkstdmacros{Menu, MENU} + + +@page +@node GtkMenuBar, GtkMenuItem, GtkMenu, Widgets +@comment node-name, next, previous, up +@section The menu bar widget + + +@subsection Description + +@subsection Signals + +@subsection Functions + +@deftypefun guint gtk_menu_bar_get_type (void) +@end deftypefun + +@deftypefun GtkWidget* gtk_menu_bar_new (void) +@end deftypefun + +@deftypefun void gtk_menu_bar_append (GtkMenuBar *@var{menu_bar}, GtkWidget *@var{child}) +@end deftypefun + +@deftypefun void gtk_menu_bar_prepend (GtkMenuBar *@var{menu_bar}, GtkWidget *@var{child}) +@end deftypefun + +@deftypefun void gtk_menu_bar_insert (GtkMenuBar *@var{menu_bar}, GtkWidget *@var{child}, gint @var{position}) +@end deftypefun + +@gtkstdmacros{MenuBar, MENU_BAR} + + +@page +@node GtkMenuItem, GtkMenuShell, GtkMenuBar, Widgets +@comment node-name, next, previous, up +@section The menu item widget + + +@subsection Description + +@subsection Signals + +@deftypefn Signal void GtkMenuItem::activate (GtkMenuItem *@var{menu_item}) +@end deftypefn + +@subsection Functions + +@deftypefun guint gtk_menu_item_get_type (void) +@end deftypefun + +@deftypefun GtkWidget* gtk_menu_item_new (void) +@end deftypefun + +@deftypefun GtkWidget* gtk_menu_item_new_with_label (gchar *@var{label}) +@end deftypefun + +@deftypefun void gtk_menu_item_set_submenu (GtkMenuItem *@var{menu_item}, GtkWidget *@var{submenu}) +@end deftypefun + +@deftypefun void gtk_menu_item_set_placement (GtkMenuItem *@var{menu_item}, GtkSubmenuPlacement @var{placement}) +@end deftypefun + +@deftypefun void gtk_menu_item_accelerator_size (GtkMenuItem *@var{menu_item}) +@end deftypefun + +@deftypefun void gtk_menu_item_accelerator_text (GtkMenuItem *@var{menu_item}, gchar *@var{buffer}) +@end deftypefun + +@deftypefun void gtk_menu_item_configure (GtkMenuItem *@var{menu_item}, gint @var{show_toggle_indicator}, gint @var{show_submenu_indicator}) +@end deftypefun + +@deftypefun void gtk_menu_item_select (GtkMenuItem *@var{menu_item}) +@end deftypefun + +@deftypefun void gtk_menu_item_deselect (GtkMenuItem *@var{menu_item}) +@end deftypefun + +@deftypefun void gtk_menu_item_activate (GtkMenuItem *@var{menu_item}) +@end deftypefun + +@gtkstdmacros{MenuItem, MENU_ITEM} + + +@page +@node GtkMenuShell, GtkMisc, GtkMenuItem, Widgets +@comment node-name, next, previous, up +@section The menu shell widget + + +@subsection Description + +@subsection Signals + +@deftypefn Signal void GtkMenuShell::deactivate (GtkMenuShell *@var{menu_shell}) +@end deftypefn + +@subsection Functions + +@deftypefun guint gtk_menu_shell_get_type (void) +@end deftypefun + +@deftypefun void gtk_menu_shell_append (GtkMenuShell *@var{menu_shell}, GtkWidget *@var{child}) +@end deftypefun + +@deftypefun void gtk_menu_shell_prepend (GtkMenuShell *@var{menu_shell}, GtkWidget *@var{child}) +@end deftypefun + +@deftypefun void gtk_menu_shell_insert (GtkMenuShell *@var{menu_shell}, GtkWidget *@var{child}, gint @var{position}) +@end deftypefun + +@deftypefun void gtk_menu_shell_deactivate (GtkMenuShell *@var{menu_shell}) +@end deftypefun + +@gtkstdmacros{MenuShell, MENU_SHELL} + + +@page +@node GtkMisc, GtkNotebook, GtkMenuShell, Widgets +@comment node-name, next, previous, up +@section The misc widget + + +@subsection Description + +@subsection Signals + +@subsection Functions + +@deftypefun guint gtk_misc_get_type (void) +@end deftypefun + +@deftypefun void gtk_misc_set_alignment (GtkMisc *@var{misc}, gfloat @var{xalign}, gfloat @var{yalign}) +@end deftypefun + +@deftypefun void gtk_misc_set_padding (GtkMisc *@var{misc}, gint @var{xpad}, gint @var{ypad}) +@end deftypefun + +@gtkstdmacros{Misc, MISC} + + +@page +@node GtkNotebook, GtkOptionMenu, GtkMisc, Widgets +@comment node-name, next, previous, up +@section The notebook widget + + +@subsection Description + +@subsection Signals + +@subsection Functions + +@deftypefun guint gtk_notebook_get_type (void) +@end deftypefun + +@deftypefun GtkWidget* gtk_notebook_new (void) +@end deftypefun + +@deftypefun void gtk_notebook_append_page (GtkNotebook *@var{notebook}, GtkWidget *@var{child}, GtkWidget *@var{tab_label}) +@end deftypefun + +@deftypefun void gtk_notebook_prepend_page (GtkNotebook *@var{notebook}, GtkWidget *@var{child}, GtkWidget *@var{tab_label}) +@end deftypefun + +@deftypefun void gtk_notebook_insert_page (GtkNotebook *@var{notebook}, GtkWidget *@var{child}, GtkWidget *@var{tab_label}, gint @var{position}) +@end deftypefun + +@deftypefun void gtk_notebook_remove_page (GtkNotebook *@var{notebook}, gint @var{page_num}) +@end deftypefun + +@deftypefun void gtk_notebook_set_page (GtkNotebook *@var{notebook}, gint @var{page_num}) +@end deftypefun + +@deftypefun void gtk_notebook_next_page (GtkNotebook *@var{notebook}) +@end deftypefun + +@deftypefun void gtk_notebook_prev_page (GtkNotebook *@var{notebook}) +@end deftypefun + +@deftypefun void gtk_notebook_set_tab_pos (GtkNotebook *@var{notebook}, GtkPositionType @var{pos}) +@end deftypefun + +@deftypefun void gtk_notebook_set_show_tabs (GtkNotebook *@var{notebook}, gint @var{show_tabs}) +@end deftypefun + +@deftypefun void gtk_notebook_set_show_border (GtkNotebook *@var{notebook}, gint @var{show_border}) +@end deftypefun + +@gtkstdmacros{Notebook, NOTEBOOK} + + +@page +@node GtkOptionMenu, GtkPixmap, GtkNotebook, Widgets +@comment node-name, next, previous, up +@section The option menu widget + + +@subsection Description + +@subsection Signals + +@subsection Functions + +@deftypefun guint gtk_option_menu_get_type (void) +@end deftypefun + +@deftypefun GtkWidget* gtk_option_menu_new (void) +@end deftypefun + +@deftypefun GtkWidget* gtk_option_menu_get_menu (GtkOptionMenu *@var{option_menu}) +@end deftypefun + +@deftypefun void gtk_option_menu_set_menu (GtkOptionMenu *@var{option_menu}, GtkWidget *@var{menu}) +@end deftypefun + +@deftypefun void gtk_option_menu_remove_menu (GtkOptionMenu *@var{option_menu}) +@end deftypefun + +@deftypefun void gtk_option_menu_set_history (GtkOptionMenu *@var{option_menu}, gint @var{index}) +@end deftypefun + +@gtkstdmacros{OptionMenu, OPTION_MENU} + + +@page +@node GtkPixmap, GtkPreview, GtkOptionMenu, Widgets +@comment node-name, next, previous, up +@section The pixmap widget + + +@subsection Description + +@subsection Signals + +@subsection Functions + +@deftypefun guint gtk_pixmap_get_type (void) +@end deftypefun + +@deftypefun GtkWidget* gtk_pixmap_new (GdkPixmap *@var{normal}, GdkPixmap *@var{active}, GdkPixmap *@var{prelight}, GdkPixmap *@var{selected}, GdkPixmap *@var{insensitive}) +@end deftypefun + +@deftypefun void gtk_pixmap_set (GtkPixmap *@var{pixmap}, GdkPixmap *@var{val}, GtkStateType @var{state}) +@end deftypefun + +@deftypefun void gtk_pixmap_get (GtkPixmap *@var{pixmap}, GdkPixmap **@var{val}, GtkStateType @var{state}) +@end deftypefun + +@gtkstdmacros{Pixmap, PIXMAP} + + +@page +@node GtkPreview, GtkProgressBar, GtkPixmap, Widgets +@comment node-name, next, previous, up +@section The preview widget + + +@subsection Description + +@subsection Signals + +@subsection Functions + +@deftypefun guint gtk_preview_get_type (void) +@end deftypefun + +@deftypefun void gtk_preview_uninit (void) +@end deftypefun + +@deftypefun GtkWidget* gtk_preview_new (GtkPreviewType @var{type}) +@end deftypefun + +@deftypefun void gtk_preview_size (GtkPreview *@var{preview}, gint @var{width}, gint @var{height}) +@end deftypefun + +@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}) +@end deftypefun + +@deftypefun void gtk_preview_put_row (GtkPreview *@var{preview}, guchar *@var{src}, guchar *@var{dest}, gint @var{x}, gint @var{y}, gint @var{w}) +@end deftypefun + +@deftypefun void gtk_preview_draw_row (GtkPreview *@var{preview}, guchar @var{data}, gint @var{x}, gint @var{y}, gint @var{w}) +@end deftypefun + +@deftypefun void gtk_preview_set_expand (GtkPreview *@var{preview}, gint @var{expand}) +@end deftypefun + +@deftypefun void gtk_preview_set_gamma (double @var{gamma}) +@end deftypefun + +@deftypefun void gtk_preview_set_color_cube (guint @var{nred_shades}, guint @var{ngreen_shades}, guint @var{nblue_shades}, guint @var{ngray_shades}) +@end deftypefun + +@deftypefun void gtk_preview_set_install_cmap (gint @var{install_cmap}) +@end deftypefun + +@deftypefun void gtk_preview_set_reserved (gint @var{nreserved}) +@end deftypefun + +@deftypefun GdkVisual* gtk_preview_get_visual (void) +@end deftypefun + +@deftypefun GdkColormap* gtk_preview_get_cmap (void) +@end deftypefun + +@deftypefun GtkPreviewInfo* gtk_preview_get_info (void) +@end deftypefun + +@gtkstdmacros{Preview, PREVIEW} + + +@page +@node GtkProgressBar, GtkRadioButton, GtkPreview, Widgets +@comment node-name, next, previous, up +@section The progress bar widget + + +@subsection Description + +@subsection Signals + +@subsection Functions + +@deftypefun guint gtk_progress_bar_get_type (void) +@end deftypefun + +@deftypefun GtkWidget* gtk_progress_bar_new (void) +@end deftypefun + +@deftypefun void gtk_progress_bar_update (GtkProgressBar *@var{pbar}, gfloat @var{percentage}) +@end deftypefun + +@gtkstdmacros{ProgressBar, PROGRESS_BAR} + + +@page +@node GtkRadioButton, GtkRadioMenuItem, GtkProgressBar, Widgets +@comment node-name, next, previous, up +@section The radio button widget + + +@subsection Description + +@subsection Signals + +@subsection Functions + +@deftypefun guint gtk_radio_button_get_type (void) +@end deftypefun + +@deftypefun GtkWidget* gtk_radio_button_new (GSList *@var{group}) +@end deftypefun + +@deftypefun GtkWidget* gtk_radio_button_new_with_label (GSList *@var{group}, gchar *@var{label}) +@end deftypefun + +@deftypefun GSList* gtk_radio_button_group (GtkRadioButton *@var{radio_button}) +@end deftypefun + +@gtkstdmacros{RadioButton, RADIO_BUTTON} + + +@page +@node GtkRadioMenuItem, GtkRange, GtkRadioButton, Widgets +@comment node-name, next, previous, up +@section The radio button widget + + +@subsection Description + +@subsection Signals + +@subsection Functions + +@deftypefun guint gtk_radio_menu_item_get_type (void) +@end deftypefun + +@deftypefun GtkWidget* gtk_radio_menu_item_new (GSList *@var{group}) +@end deftypefun + +@deftypefun GtkWidget* gtk_radio_menu_item_new_with_label (GSList *@var{group}, gchar *@var{label}) +@end deftypefun + +@deftypefun GSList* gtk_radio_menu_item_group (GtkRadioMenuItem *@var{radio_menu_item}) +@end deftypefun + +@gtkstdmacros{RadioMenuItem, RADIO_MENU_ITEM} + + +@page +@node GtkRange, GtkRuler, GtkRadioMenuItem, Widgets +@comment node-name, next, previous, up +@section The range widget + + +@subsection Description + +@subsection Signals + +@subsection Functions + +@deftypefun guint gtk_range_get_type (void) +@end deftypefun + +@deftypefun GtkAdjustment* gtk_range_get_adjustment (GtkRange *@var{range}) +@end deftypefun + +@deftypefun void gtk_range_set_update_policy (GtkRange *@var{range}, GtkUpdatePolicy @var{policy}) +@end deftypefun + +@deftypefun void gtk_range_set_adjustment (GtkRange *@var{range}, GtkAdjustment *@var{adjustment}) +@end deftypefun + +@deftypefun void gtk_range_draw_background (GtkRange *@var{range}) +@end deftypefun + +@deftypefun void gtk_range_draw_trough (GtkRange *@var{range}) +@end deftypefun + +@deftypefun void gtk_range_draw_slider (GtkRange *@var{range}) +@end deftypefun + +@deftypefun void gtk_range_draw_step_forw (GtkRange *@var{range}) +@end deftypefun + +@deftypefun void gtk_range_draw_step_back (GtkRange *@var{range}) +@end deftypefun + +@deftypefun void gtk_range_slider_update (GtkRange *@var{range}) +@end deftypefun + +@deftypefun gint gtk_range_trough_click (GtkRange *@var{range}, gint @var{x}, gint @var{y}) +@end deftypefun + +@deftypefun void gtk_range_default_hslider_update (GtkRange *@var{range}) +@end deftypefun + +@deftypefun void gtk_range_default_vslider_update (GtkRange *@var{range}) +@end deftypefun + +@deftypefun gint gtk_range_default_htrough_click (GtkRange *@var{range}, gint @var{x}, gint @var{y}) +@end deftypefun + +@deftypefun gint gtk_range_default_vtrough_click (GtkRange *@var{range}, gint @var{x}, gint @var{y}) +@end deftypefun + +@deftypefun void gtk_range_default_hmotion (GtkRange *@var{range}, gint @var{xdelta}, gint @var{ydelta}) +@end deftypefun + +@deftypefun void gtk_range_default_vmotion (GtkRange *@var{range}, gint @var{xdelta}, gint @var{ydelta}) +@end deftypefun + +@deftypefun gfloat gtk_range_calc_value (GtkRange *@var{ragne}, gint @var{position}) +@end deftypefun + +@gtkstdmacros{Range, RANGE} + + +@page +@node GtkRuler, GtkScale, GtkRange, Widgets +@comment node-name, next, previous, up +@section The ruler widget + + +@subsection Description + +@subsection Signals + +@subsection Functions + +@deftypefun guint gtk_ruler_get_type (void) +@end deftypefun + +@deftypefun void gtk_ruler_set_metric (GtkRuler *@var{ruler}, GtkMetricType @var{metric}) +@end deftypefun + +@deftypefun void gtk_ruler_set_range (GtkRuler *@var{ruler}, gfloat @var{lower}, gfloat @var{upper}, gfloat @var{position}, gfloat @var{max_size}) +@end deftypefun + +@deftypefun void gtk_ruler_draw_ticks (GtkRuler *@var{ruler}) +@end deftypefun + +@deftypefun void gtk_ruler_draw_pos (GtkRuler *@var{ruler}) +@end deftypefun + +@gtkstdmacros{Ruler, RULER} + + +@page +@node GtkScale, GtkScrollbar, GtkRuler, Widgets +@comment node-name, next, previous, up +@section The scale widget + + +@subsection Description + +@subsection Signals + +@subsection Functions + +@deftypefun guint gtk_scale_get_type (void) +@end deftypefun + +@deftypefun void gtk_scale_set_digits (GtkScale *@var{scale}, gint @var{digits}) +@end deftypefun + +@deftypefun void gtk_scale_set_draw_value (GtkScale *@var{scale}, gint @var{draw_value}) +@end deftypefun + +@deftypefun void gtk_scale_set_value_pos (GtkScale *@var{scale}, gint @var{pos}) +@end deftypefun + +@deftypefun gint gtk_scale_value_width (GtkScale *@var{scale}) +@end deftypefun + +@deftypefun void gtk_scale_draw_value (GtkScale *@var{scale}) +@end deftypefun + +@gtkstdmacros{Scale, SCALE} + + +@page +@node GtkScrollbar, GtkScrolledWindow, GtkScale, Widgets +@comment node-name, next, previous, up +@section The scrollbar widget + + +@subsection Description + +@subsection Signals + +@subsection Functions + +@deftypefun guint gtk_scrollbar_get_type (void) +@end deftypefun + +@gtkstdmacros{Scrollbar, SCROLLBAR} + + +@page +@node GtkScrolledWindow, GtkSeparator, GtkScrollbar, Widgets +@comment node-name, next, previous, up +@section The scrolled window widget + + +@subsection Description + +@subsection Signals + +@subsection Functions + +@deftypefun guint gtk_scrolled_window_get_type (void) +@end deftypefun + +@deftypefun GtkWidget* gtk_scrolled_window_new (GtkAdjustment *@var{hadjustment}, GtkAdjustment *@var{vadjustment}) +@end deftypefun + +@deftypefun GtkAdjustment* gtk_scrolled_window_get_hadjustment (GtkScrolledWindow *@var{scrolled_window}) +@end deftypefun + +@deftypefun GtkAdjustment* gtk_scrolled_window_get_vadjustment (GtkScrolledWindow *@var{scrolled_window}) +@end deftypefun + +@deftypefun void gtk_scrolled_window_set_policy (GtkScrolledWindow *@var{scrolled_window}, GtkPolicyType @var{hscrollbar_policy}, GtkPolicyType @var{vscrollbar_policy}) +@end deftypefun + +@gtkstdmacros{ScrolledWindow, SCROLLED_WINDOW} + + +@page +@node GtkSeparator, GtkTable, GtkScrolledWindow, Widgets +@comment node-name, next, previous, up +@section The separator widget + + +@subsection Description + +@subsection Signals + +@subsection Functions + +@deftypefun guint gtk_separator_get_type (void) +@end deftypefun + +@gtkstdmacros{Separator, SEPARATOR} + + +@page +@node GtkTable, GtkText, GtkSeparator, Widgets +@comment node-name, next, previous, up +@section The table widget + + +@subsection Description + +@subsection Signals + +@subsection Functions + +@deftypefun guint gtk_table_get_type (void) +@end deftypefun + +@deftypefun GtkWidget* gtk_table_new (gint @var{rows}, gint @var{columns}, gint @var{homogeneous}) +@end deftypefun + +@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}) +@end deftypefun + +@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}) +@end deftypefun + +@deftypefun void gtk_table_set_row_spacing (GtkTable *@var{table}, gint @var{row}, gint @var{spacing}) +@end deftypefun + +@deftypefun void gtk_table_set_col_spacing (GtkTable *@var{table}, gint @var{col}, gint @var{spacing}) +@end deftypefun + +@deftypefun void gtk_table_set_row_spacings (GtkTable *@var{table}, gint @var{spacing}) +@end deftypefun + +@deftypefun void gtk_table_set_col_spacings (GtkTable *@var{table}, gint @var{spacing}) +@end deftypefun + +@gtkstdmacros{Table, TABLE} + + +@page +@node GtkText, GtkToggleButton, GtkTable, Widgets +@comment node-name, next, previous, up +@section The text widget + + +@subsection Description + +@subsection Signals + +@subsection Functions + +@deftypefun guint gtk_text_get_type (void) +@end deftypefun + +@gtkstdmacros{Text, TEXT} + + +@page +@node GtkToggleButton, GtkTree, GtkText, Widgets +@comment node-name, next, previous, up +@section The toggle button widget + + +@subsection Description + +@subsection Signals + +@deftypefn Signal void GtkToggleButton::toggled (GtkToggleButton *@var{toggle_button}) +@end deftypefn + +@subsection Functions + +@deftypefun guint gtk_toggle_button_get_type (void) +@end deftypefun + +@deftypefun GtkWidget* gtk_toggle_button_new (void) +@end deftypefun + +@deftypefun GtkWidget* gtk_toggle_button_new_with_label (gchar *@var{label}) +@end deftypefun + +@deftypefun void gtk_toggle_button_set_mode (GtkToggleButton *@var{toggle_button}, gint @var{draw_indicator}) +@end deftypefun + +@deftypefun void gtk_toggle_button_set_state (GtkToggleButton *@var{toggle_button}, gint @var{state}) +@end deftypefun + +@deftypefun void gtk_toggle_button_toggled (GtkToggleButotn *@var{toggle_button}) +@end deftypefun + +@gtkstdmacros{ToggleButton, TOGGLE_BUTTON} + + +@page +@node GtkTree, GtkTreeItem, GtkToggleButton, Widgets +@comment node-name, next, previous, up +@section The tree widget + + +@subsection Description + +@subsection Signals + +@subsection Functions + +@deftypefun guint gtk_tree_get_type (void) +@end deftypefun + +@gtkstdmacros{Tree, TREE} + + +@page +@node GtkTreeItem, GtkVBox, GtkTree, Widgets +@comment node-name, next, previous, up +@section The tree item widget + + +@subsection Description + +@subsection Signals + +@subsection Functions + +@deftypefun guint gtk_tree_item_get_type (void) +@end deftypefun + +@gtkstdmacros{TreeItem, TREE_ITEM} + + +@page +@node GtkVBox, GtkViewport, GtkTreeItem, Widgets +@comment node-name, next, previous, up +@section The vertical box widget + + +@subsection Description + +@subsection Signals + +@subsection Functions + +@deftypefun guint gtk_vbox_get_type (void) +@end deftypefun + +@deftypefun GtkWidget* gtk_vbox_new (gint @var{homogeneous}, gint @var{spacing}) +@end deftypefun + +@gtkstdmacros{VBox, VBOX} + + +@page +@node GtkViewport, GtkVRuler, GtkVBox, Widgets +@comment node-name, next, previous, up +@section The viewport widget + + +@subsection Description + +@subsection Signals + +@subsection Functions + +@deftypefun guint gtk_viewport_get_type (void) +@end deftypefun + +@deftypefun GtkWidget* gtk_viewport_new (GtkAdjustment *@var{hadjustment}, GtkAdjustment *@var{vadjustment}) +@end deftypefun + +@deftypefun GtkAdjustment* gtk_viewport_get_hadjustment (GtkViewport *@var{viewport}) +@end deftypefun + +@deftypefun GtkAdjustment* gtk_viewport_get_vadjustment (GtkViewport *@var{viewport}) +@end deftypefun + +@deftypefun void gtk_viewport_set_hadjustment (GtkViewport *@var{viewport}, GtkAdjustment *@var{adjustment}) +@end deftypefun + +@deftypefun void gtk_viewport_set_vadjustment (GtkViewport *@var{viewport}, GtkAdjustment *@var{adjustment}) +@end deftypefun + +@deftypefun void gtk_viewport_set_shadow_type (GtkViewport *@var{viewport}, GtkShadowType @var{type}) +@end deftypefun + +@gtkstdmacros{Viewport, VIEWPORT} + + +@page +@node GtkVRuler, GtkVScale, GtkViewport, Widgets +@comment node-name, next, previous, up +@section The vertical ruler widget + + +@subsection Description + +@subsection Signals + +@subsection Functions + +@deftypefun guint gtk_vruler_get_type (void) +@end deftypefun + +@deftypefun GtkWidget* gtk_vruler_new (void) +@end deftypefun + +@gtkstdmacros{VRuler, VRULER} + + +@page +@node GtkVScale, GtkVScrollbar, GtkVRuler, Widgets +@comment node-name, next, previous, up +@section The vertical ruler widget + + +@subsection Description + +@subsection Signals + +@subsection Functions + +@deftypefun guint gtk_vscale_get_type (void) +@end deftypefun + +@deftypefun GtkWidget* gtk_vscale_new (GtkAdjustment *@var{adjustment}) +@end deftypefun + +@gtkstdmacros{VScale, VSCALE} + + +@page +@node GtkVScrollbar, GtkVSeparator, GtkVScale, Widgets +@comment node-name, next, previous, up +@section The vertical scrollbar widget + + +@subsection Description + +@subsection Signals + +@subsection Functions + +@deftypefun guint gtk_vscrollbar_get_type (void) +@end deftypefun + +@deftypefun GtkWidget* gtk_vscrollbar_new (GtkAdjustment *@var{adjustment}) +@end deftypefun + +@gtkstdmacros{VScrollbar, VSCROLLBAR} + + +@page +@node GtkVSeparator, GtkWidget, GtkVScrollbar, Widgets +@comment node-name, next, previous, up +@section The vertical separator widget + + +@subsection Description + +@subsection Signals + +@subsection Functions + +@deftypefun guint gtk_vseparator_get_type (void) +@end deftypefun + +@deftypefun GtkWidget* gtk_vseparator_new (void) +@end deftypefun + +@gtkstdmacros{VSeparator, VSEPARATOR} + + +@page +@node GtkWidget, GtkWindow, GtkVSeparator, Widgets +@comment node-name, next, previous, up +@section The base widget + + +@subsection Description + +@subsection Signals + +@deftypefn Signal void GtkWidget::show (GtkWidget *@var{widget}) +@end deftypefn + +@deftypefn Signal void GtkWidget::hide (GtkWidget *@var{widget}) +@end deftypefn + +@deftypefn Signal void GtkWidget::map (GtkWidget *@var{widget}) +@end deftypefn + +@deftypefn Signal void GtkWidget::unmap (GtkWidget *@var{widget}) +@end deftypefn + +@deftypefn Signal void GtkWidget::realize (GtkWidget *@var{widget}) +@end deftypefn + +@deftypefn Signal void GtkWidget::unrealize (GtkWidget *@var{widget}) +@end deftypefn + +@deftypefn Signal void GtkWidget::draw (GtkWidget *@var{widget}, GdkRectangle *@var{area}) +@end deftypefn + +@deftypefn Signal void GtkWidget::draw_focus (GtkWidget *@var{widget}) +@end deftypefn + +@deftypefn Signal void GtkWidget::draw_default (GtkWidget *@var{widget}) +@end deftypefn + +@deftypefn Signal void GtkWidget::size_request (GtkWidget *@var{widget}, GtkRequisition *@var{requisition}) +@end deftypefn + +@deftypefn Signal void GtkWidget::size_allocate (GtkWidget *@var{widget}, GtkAllocation *@var{allocation}) +@end deftypefn + +@deftypefn Signal void GtkWidget::state_changed (GtkWidget *@var{widget}) +@end deftypefn + +@deftypefn Signal gint GtkWidget::install_accelerator (GtkWidget *@var{widget}, gchar *@var{signal_name}, gchar @var{key}, guint8 @var{modifiers}) +@end deftypefn + +@deftypefn Signal void GtkWidget::remove_accelerator (GtkWidget *@var{widget}, gchar *@var{signal_name}) +@end deftypefn + +@deftypefn Signal gint GtkWidget::event (GtkWidget *@var{widget}, GdkEvent *@var{event}) +@end deftypefn + +@deftypefn Signal gint GtkWidget::button_press_event (GtkWidget *@var{widget}, GdkEventButton *@var{event}) +@end deftypefn + +@deftypefn Signal gint GtkWidget::button_release_event (GtkWidget *@var{widget}, GdkEventButton *@var{event}) +@end deftypefn + +@deftypefn Signal gint GtkWidget::motion_notify_event (GtkWidget *@var{widget}, GdkEventMotion *@var{event}) +@end deftypefn + +@deftypefn Signal gint GtkWidget::delete_event (GtkWidget *@var{widget}, GdkEventAny *@var{event}) +@end deftypefn + +@deftypefn Signal gint GtkWidget::destroy_event (GtkWidget *@var{widget}, GdkEventAny *@var{event}) +@end deftypefn + +@deftypefn Signal gint GtkWidget::expose_event (GtkWidget *@var{widget}, GdkEventExpose *@var{event}) +@end deftypefn + +@deftypefn Signal gint GtkWidget::key_press_event (GtkWidget *@var{widget}, GdkEventKey *@var{event}) +@end deftypefn + +@deftypefn Signal gint GtkWidget::key_release_event (GtkWidget *@var{widget}, GdkEventKey *@var{event}) +@end deftypefn + +@deftypefn Signal gint GtkWidget::enter_notify_event (GtkWidget *@var{widget}, GdkEventCrossing *@var{event}) +@end deftypefn + +@deftypefn Signal gint GtkWidget::leave_notify_event (GtkWidget *@var{widget}, GdkEventCrossing *@var{event}) +@end deftypefn + +@deftypefn Signal gint GtkWidget::configure_event (GtkWidget *@var{widget}, GdkEventConfigure *@var{event}) +@end deftypefn + +@deftypefn Signal gint GtkWidget::focus_in_event (GtkWidget *@var{widget}, GdkEventFocus *@var{event}) +@end deftypefn + +@deftypefn Signal gint GtkWidget::focus_out_event (GtkWidget *@var{widget}, GdkEventFocus *@var{event}) +@end deftypefn + +@deftypefn Signal gint GtkWidget::map_event (GtkWidget *@var{widget}, GdkEventAny *@var{event}) +@end deftypefn + +@deftypefn Signal gint GtkWidget::unmap_event (GtkWidget *@var{widget}, GdkEventAny *@var{event}) +@end deftypefn + +@deftypefn Signal gint GtkWidget::property_notify_event (GtkWidget *@var{widget}, GdkEventProperty *@var{event}) +@end deftypefn + +@deftypefn Signal gint GtkWidget::selection_clear_event (GtkWidget *@var{widget}, GdkEventSelection *@var{event}) +@end deftypefn + +@deftypefn Signal gint GtkWidget::selection_request_event (GtkWidget *@var{widget}, GdkEventSelection *@var{event}) +@end deftypefn + +@deftypefn Signal gint GtkWidget::selection_notify_event (GtkWidget *@var{widget}, GdkEventSelection *@var{event}) +@end deftypefn + +@deftypefn Signal gint GtkWidget::drop_event (GtkWidget *@var{widget}, GdkEventDrop *@var{event}) +@end deftypefn + +@deftypefn Signal gint GtkWidget::drag_begin_event (GtkWidget *@var{widget}, GdkEventDragBegin *@var{event}) +@end deftypefn + +@deftypefn Signal gint GtkWidget::other_event (GtkWidget *@var{widget}, GdkEventOther *@var{event}) +@end deftypefn + +@subsection Functions + +@deftypefun guint gtk_widget_get_type (void) +@end deftypefun + +@deftypefun void gtk_widget_class_init (GtkWidgetClass *@var{class}) +@end deftypefun + +@deftypefun void gtk_widget_init (GtkWidget *@var{widget}) +@end deftypefun + +@deftypefun void gtk_widget_destroy (GtkWidget *@var{widget}) +@end deftypefun + +@deftypefun void gtk_widget_show (GtkWidget *@var{widget}) +@end deftypefun + +@deftypefun void gtk_widget_hide (GtkWidget *@var{widget}) +@end deftypefun + +@deftypefun void gtk_widget_map (GtkWidget *@var{widget}) +@end deftypefun + +@deftypefun void gtk_widget_unmap (GtkWidget *@var{widget}) +@end deftypefun + +@deftypefun void gtk_widget_realize (GtkWidget *@var{widget}) +@end deftypefun + +@deftypefun void gtk_widget_unrealize (GtkWidget *@var{widget}) +@end deftypefun + +@deftypefun void gtk_widget_draw (GtkWidget *@var{widget}, GdkRectangle *@var{area}) +@end deftypefun + +@deftypefun void gtk_widget_draw_focus (GtkWidget *@var{widget}) +@end deftypefun + +@deftypefun void gtk_widget_draw_children (GtkWidget *@var{widget}) +@end deftypefun + +@deftypefun void gtk_widget_size_request (GtkWidget *@var{widget}, GtkRequisition *@var{requisition}) +@end deftypefun + +@deftypefun void gtk_widget_size_allocate (GtkWidget *@var{widget}, GtkAllocation *@var{allocation}) +@end deftypefun + +@deftypefun void gtk_widget_install_accelerator (GtkWidget *@var{widget}, GtkAcceleratorTable *@var{table}, gchar *@var{signal_name}, gchar @var{key}, guint8 @var{modifiers}) +@end deftypefun + +@deftypefun void gtk_widget_remove_accelerator (GtkWidget *@var{widget}, GtkAcceleratorTable *@var{table}, gchar *@var{signal_name}) +@end deftypefun + +@deftypefun gint gtk_widget_event (GtkWidget *@var{widget}, GdkEvent *@var{event}) +@end deftypefun + +@deftypefun void gtk_widget_reparent (GtkWidget *@var{widget}, GtkWidget *@var{new_parent}) +@end deftypefun + +@deftypefun void gtk_widget_popup (GtkWidget *@var{widget}, gint @var{x}, gint @var{y}) +@end deftypefun + +@deftypefun gint gtk_widget_intersect (GtkWidget *@var{widget}, GdkRectangle *@var{area}, GdkRectangle *@var{intersection}) +@end deftypefun + +@deftypefun void gtk_widget_grab_focus (GtkWidget *@var{widget}) +@end deftypefun + +@deftypefun void gtk_widget_grab_default (GtkWidget *@var{widget}) +@end deftypefun + +@deftypefun void gtk_widget_restore_state (GtkWidget *@var{widget}) +@end deftypefun + +@deftypefun void gtk_widget_set_name (GtkWidget *@var{widget}, gchar *@var{name}) +@end deftypefun + +@deftypefun void gtk_widget_set_state (GtkWidget *@var{widget}, GtkStateType @var{state}) +@end deftypefun + +@deftypefun void gtk_widget_set_sensitive (GtkWidget *@var{widget}, gint sensitive) +@end deftypefun + +@deftypefun void gtk_widget_set_parent (GtkWidget *@var{widget}, GtkWidget *@var{parent}) +@end deftypefun + +@deftypefun void gtk_widget_set_style (GtkWidget *@var{widget}, GtkStyle *@var{style}) +@end deftypefun + +@deftypefun void gtk_widget_set_uposition (GtkWidget *@var{widget}, gint @var{x}, gint @var{y}) +@end deftypefun + +@deftypefun void gtk_widget_set_usize (GtkWidget *@var{widget}, gint @var{width}, gint @var{height}) +@end deftypefun + +@deftypefun GtkWidget* gtk_widget_get_toplevel (GtkWidget *@var{widget}) +@end deftypefun + +@deftypefun GtkWidget* gtk_widget_get_ancestor (GtkWidget *@var{widget}, gint @var{type}) +@end deftypefun + +@deftypefun GdkColormap* gtk_widget_get_colormap (GtkWidget *@var{widget}) +@end deftypefun + +@deftypefun GdkVisual* gtk_widget_get_visual (GtkWidget *@var{visual}) +@end deftypefun + +@deftypefun GtkStyle* gtk_widget_get_style (GtkWidget *@var{style}) +@end deftypefun + +@gtkstdmacros{Widget, WIDGET} + + +@page +@node GtkWindow, , GtkWidget, Widgets +@comment node-name, next, previous, up +@section The window widget + + +@subsection Description + +@subsection Signals + +@deftypefn Signal void GtkWindow::move_resize (GtkWindow *@var{window}, gint *@var{x}, gint *@var{y}, gint @var{width}, gint @var{height}) +@end deftypefn + +@subsection Functions + +@deftypefun guint gtk_window_get_type (void) +@end deftypefun + +@deftypefun GtkWidget* gtk_window_new (GtkWindowType @var{type}) +@end deftypefun + +@deftypefun void gtk_window_set_title (GtkWindow *@var{window}, gchar *@var{title}) +@end deftypefun + +@deftypefun void gtk_window_set_focus (GtkWindow *@var{window}, GtkWidget *@var{focus}) +@end deftypefun + +@deftypefun void gtk_window_set_default (GtkWindow *@var{window}, GtkWidget *@var{defaultw}) +@end deftypefun + +@deftypefun void gtk_window_set_policy (GtkWindow *@var{window}, gint @var{allow_shrink}, gint @var{allow_grow}, gint @var{auto_shrink}) +@end deftypefun + +@deftypefun void gtk_window_add_accelerator_table (GtkWindow *@var{window}, GtkAcceleratorTable *@var{table}) +@end deftypefun + +@deftypefun void gtk_window_remove_accelerator_table (GtkWindow *@var{window}, GtkAcceleratorTable *@var{table}) +@end deftypefun + +@deftypefun void gtk_window_position (GtkWindow *@var{window}, GtkWindowPosition @var{position}) +@end deftypefun + +@gtkstdmacros{Window, WINDOW} + + +@node Other Objects, Miscellaneous, Widgets, Top +@comment node-name, next, previous, up +@chapter Utility objects + + +@menu +* GtkAdjustment:: The adjustment object. +* GtkData:: The data object. +@end menu + + +@node GtkAdjustment, GtkData, Other Objects, Other Objects +@comment node-name, next, previous, up +@section The adjustment object + + +@node GtkData, , GtkAdjustment, Other Objects +@comment node-name, next, previous, up +@section The data object + + +@node Miscellaneous, Examples, Other Objects, Top +@comment node-name, next, previous, up +@chapter Initialization, exit and other features + + +@menu +* Initialization and exit:: Initializing and exiting GTK. +* Menu Factories:: Simplified menu creation. +* Tree Factories:: Simplified tree creation. +* Tool Tips:: Pop up help mechanism. +* Resource Files:: Resource files. +* Standard Macros:: Macros defined by all objects. +@end menu + + +@node Initialization and exit, Menu Factories, Miscellaneous, Miscellaneous +@comment node-name, next, previous, up +@section Initializing and exiting GTK + + +@node Menu Factories, Tree Factories, Initialization and exit, Miscellaneous +@comment node-name, next, previous, up +@section Simplified menu creation + + +@node Tree Factories, Tool Tips, Menu Factories, Miscellaneous +@comment node-name, next, previous, up +@section Simplified tree creation + + +@node Tool Tips, Resource Files, Tree Factories, Miscellaneous +@comment node-name, next, previous, up +@section Pop up help mechanism + + +@node Resource Files, Standard Macros, Tool Tips, Miscellaneous +@comment node-name, next, previous, up +@section Pop up help mechanism + + +@node Standard Macros, , Resource Files, Miscellaneous +@comment node-name, next, previous, up +@section Macros defined by all objects + +There are three macros that are defined by all object types. The first +two are used for performing casts and the last is for querying whether +an object is of a particular type. These macros are both conveniences +and debugging tools. If the GTK library was compiled with @code{NDEBUG} +defined as a preprocessor symbol (via the -DNDEBUG to cc), then the +macros check the object type and emit a warning if the cast is +invalid. Doing such checking is fairly expensive since the cast macros +are used everywhere in GTK and would normally be turned off in a public +release of a product. Note: The functions below are indeed macros, but +they may be considered functions for most purposes. + +@deftypefun Gtk<ObjectType>* GTK_<OBJECT_TYPE> (gpointer @var{obj}) +Cast a generic pointer to @code{Gtk<ObjectType>*}. This function is +provided in order to be able to provide checking during development +stages of code development since it is possible to examine the actual +type of object (using @code{gtk_type_is_a}) before performing the cast. +@end deftypefun + +@deftypefun Gtk<ObjectType>Class* GTK_<OBJECT_TYPE>_CLASS (gpointer @var{class}) +Cast a generic pointer to @code{Gtk<ObjectType>Class*}. Like +@code{GTK_<ObjectType>}, this function is, in reality, a macro. +@end deftypefun + +@deftypefun gint GTK_IS_<ObjectType> (gpointer @var{obj}) +Determine if a generic pointer refers to a @code{Gtk<ObjectType>} +object. This function is, in reality, a macro wrapper around the +@code{gtk_type_is_a} function (@pxref{Objects}). +@end deftypefun + + +@node Examples, Object Implementation, Miscellaneous, Top +@comment node-name, next, previous, up +@chapter Using GTK + + +@menu +* Simple:: The simplest GTK program. +* Hello World:: Hello world in GTK. +* Hello World II:: An enhanced hello world. +* Hello World III:: Making Hello World II robust. +@end menu + + +@node Simple, Hello World, Examples, Examples +@comment node-name, next, previous, up +@section The simplest GTK program + + +The 16 line GTK program shown below is just about the simplest possible +program which uses GTK. (Well, technically, you don't have to create the +window and it would still be a program which uses GTK). The program, +when compiled and run, will create a single window 200x200 pixels in +size. The program does not exit until its is explicitly killed using the +shell or a window manager function. + +@example +#include <gtk/gtk.h> + +int +main (int argc, char *argv[]) +@{ + GtkWidget *window; + + gtk_init (&argc, &argv); + + window = gtk_window_new (GTK_WINDOW_TOPLEVEL); + gtk_widget_show (window); + + gtk_main (); + + return 0; +@} +@end example + +The first point of interest in this program is the standard +initialization line. + +@example + gtk_init (&argc, &argv); +@end example + +Almost every GTK program will contain such a line. GTK will initialize +itself and GDK and remove any command line arguments it recognizes from +@var{argc} and @var{argv}. + +The next two lines of code create and display a window. + +@example + window = gtk_window_new (GTK_WINDOW_TOPLEVEL); + gtk_widget_show (window); +@end example + +The @code{GTK_WINDOW_TOPLEVEL} argument specifies that we want the +window to undergo window manager decoration and placement. One might be +lead to think that the window, since it has no children, would be 0x0 +pixels in size. But, this is not the case because a window that has no +children defaults to 200x200 pixels in size. Mainly because 0x0 windows +are annoying to manipulate or even see in some cases. + +The last line enters the GTK main processing loop. + +@example + gtk_main (); +@end example + +Normally, @code{gtk_main} is called once and the program should exit +when it returns. @xref{Initialization and exit}. + + +@node Hello World, Hello World II, Simple, Examples +@comment node-name, next, previous, up +@section Hello world in GTK + + +@example +#include <gtk/gtk.h> + +int +main (int argc, char *argv[]) +@{ + GtkWidget *window; + GtkWidget *label; + + gtk_init (&argc, &argv); + + window = gtk_window_new (GTK_WINDOW_TOPLEVEL); + gtk_container_border_width (GTK_CONTAINER (window), 10); + + label = gtk_label_new ("Hello World"); + gtk_container_add (GTK_CONTAINER (window), label); + gtk_widget_show (label); + + gtk_widget_show (window); + + gtk_main (); + + return 0; +@} +@end example + + +@node Hello World II, Hello World III, Hello World, Examples +@comment node-name, next, previous, up +@section An enhanced hello world + + +@example +#include "gtk.h" + +void +hello (void) +@{ + g_print ("Hello World\n"); + gtk_exit (0); +@} + +int +main (int argc, char *argv[]) +@{ + GtkWidget *window; + GtkWidget *button; + + gtk_init (&argc, &argv); + + window = gtk_window_new (GTK_WINDOW_TOPLEVEL); + gtk_container_border_width (GTK_CONTAINER (window), 10); + + button = gtk_button_new_with_label ("Hello World"); + gtk_signal_connect (GTK_OBJECT (button), "clicked", + GTK_SIGNAL_FUNC (hello), NULL); + gtk_container_add (GTK_CONTAINER (window), button); + gtk_widget_show (button); + + gtk_widget_show (window); + + gtk_main (); + + return 0; +@} +@end example + + +@node Hello World III, , Hello World II, Examples +@comment node-name, next, previous, up +@section Making Hello World II robust + + +@example +#include "gtk.h" + +void +hello (void) +@{ + g_print ("Hello World\n"); + gtk_exit (0); +@} + +void +destroy (void) +@{ + gtk_exit (0); +@} + +int +main (int argc, char *argv[]) +@{ + GtkWidget *window; + GtkWidget *button; + + gtk_init (&argc, &argv); + + window = gtk_window_new (GTK_WINDOW_TOPLEVEL); + gtk_signal_connect (GTK_OBJECT (window), "destroy", + GTK_SIGNAL_FUNC (destroy), NULL); + gtk_container_border_width (GTK_CONTAINER (window), 10); + + button = gtk_button_new_with_label ("Hello World"); + gtk_signal_connect (GTK_OBJECT (button), "clicked", + GTK_SIGNAL_FUNC (hello), NULL); + gtk_signal_connect_object (GTK_OBJECT (button), "clicked", + GTK_SIGNAL_FUNC (gtk_widget_destroy), + GTK_OBJECT (window)); + gtk_container_add (GTK_CONTAINER (window), button); + gtk_widget_show (button); + + gtk_widget_show (window); + + gtk_main (); + + return 0; +@} +@end example + + +@node Object Implementation, Signal Implementation, Examples, Top +@comment node-name, next, previous, up +@chapter Object internals +@cindex Object Implementaton + +Objects (or the @code{GtkObject} type) and the class hierarchy in +general is implemented via a hierarchy of structs and type casting. Be +aware that when classes are mentioned it is the conceptual idea of +classes that is being referred to. GTK is written entirely in C which +provides no direct support for classes. + +The first part to the class mechanism is the object fields. These are +fields that will be used on a per object basis. For example, the widget +type contains a field for the widgets parent. Every derived type needs a +reference to its parent type. A descendant class of @code{GtkObject} +would define itself like: + +@example +struct Descendant +@{ + GtkObject object; + + @dots{} +@}; +@end example + +It is important to note that the @code{GtkObject} field needs to appear +first in the descendant type structure. This allows pointers to objects +of type @code{Descendant} to be cast to pointers to @code{GtkObjects}'s +and vice-versa. + +The second part to the class mechanism is the class fields. These fields +are defined on a per class basis. In the case of widgets, the class +fields are all the ``virtual'' functions for widgets. The +@code{GtkObject} class defines the @code{destroy} virtual function and +the necessary fields for the signal mechanism as well as a field for +determining the runtime type of an object. A virtual function is +semantically the same as it is in C++. That is, the actual function that +is called is determined based on the type of the object. Or, more +specifically, the actual function call depends on the class structure +that is pointed to by the @code{klass} field of the @code{GtkObject} +structure. + +To see how the class fields work it is necessary to see the object +fields for a @code{GtkObject}. The @code{GtkObject} type is defined as +follows: + +@example +typedef struct _GtkObject GtkObject; + +struct _GtkObject +@{ + guint32 flags; + GtkObjectClass *klass; + gpointer object_data; +@}; +@end example + +The @code{class} field actually points to a class structure derived from +@code{GtkObjectClass}. By convention, each new type defines its own +class structure even if it is unnecessary. As an example, the +hypothetical @code{Descendant} class would define its class structure +as: + +@example +struct DescendantClass +@{ + GtkObjectClass parent_class; + + @dots{} +@}; +@end example + +It is convention to name the parent class field (@code{GtkObjectClass} +in this case), @code{parent_class}. For the same reason as stated above +for the object structure, the parent class field must be the first field +in the class structure. + +@strong{Note:} GTK assumes that the first field in a structure will be +placed by the compiler at the start of the structure. This is certainly +true for gcc, however, from my precursory reading of the C standard I +was unable to come to a definite conclusion as to whether this was +required or simply done for simplicity. I'm not too worried about this +assumption, though, as every C compiler I've ever encountered would work +with GTK. + +The @code{flags} field of the @code{GtkObject} structure is used to keep +track of a relatively few object flags and is also used by the +@code{GtkWidget} type to store additional flags. At this time, the upper +16 bits of the flags field are reserved but unused. + +The @code{object_data} field of the @code{GtkObject} structure is an +opaque pointer used by the object data mechanism. In truth, it is a +pointer to the beginning of the data list which is composed of the +following structures. + +@example +typedef struct _GtkObjectData GtkObjectData; + +struct _GtkObjectData +@{ + guint id; + gpointer data; + GtkObjectData *next; +@}; +@end example + +The data mechanism allows arbitrary data to be associated with a +character string key in any object. A hash table is used to transform +the character string key into the data id and then a search through the +list is made to see if the data exists. The assumption being that the +data list will usually be short and therefore a linear search is +ok. Future work on the data mechanism might make use of a resizable +array instead of a linked list. This would shrink the overhead of the +@code{GtkObjectData} structure by 4 bytes on 32 bit architectures. + + +@node Signal Implementation, Widget Implementation, Object Implementation, Top +@comment node-name, next, previous, up +@chapter Signal internals +@cindex Signal Implementation + + +@node Widget Implementation, Function Index, Signal Implementation, Top +@comment node-name, next, previous, up +@chapter Widget internals +@cindex Widget Implementation + + +@node Function Index, Concept Index, Widget Implementation, Top +@comment node-name, next, previous, up +@unnumbered Function Index + +@printindex fn + + +@node Concept Index, , Function Index, Top +@comment node-name, next, previous, up +@unnumbered Concept Index + +@printindex cp + + +@summarycontents +@contents +@bye |