This is Info file gtk.info, produced by Makeinfo version 1.67 from the
input file gtk.texi.

   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

   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.

INFO-DIR-SECTION User Interface Toolkit
START-INFO-DIR-ENTRY
* GTK: (gtk).		The General Toolkit
END-INFO-DIR-ENTRY


File: gtk.info,  Node: Top,  Next: Copying,  Prev: (dir),  Up: (dir)

The General Toolkit
*******************

   This is edition 1.0 of the GTK documentation, 9 April 1997.

* 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.


File: gtk.info,  Node: Copying,  Next: Overview,  Prev: Top,  Up: Top

Copying
*******

   GTK is "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.


File: gtk.info,  Node: Overview,  Next: Objects,  Prev: Copying,  Up: Top

What is GTK?
************

   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 (*note 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.


File: gtk.info,  Node: Objects,  Next: Signals,  Prev: Overview,  Up: Top

Object Overview
***************

   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 (*note 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.

Type utility functions
======================

   The `GtkTypeInfo' structure is used to communicate information to
`gtk_type_unique' as opposed to passing in large numbers of parameters.

     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;
     }

   * The `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 `GtkObject' structure is
     "GtkObject".

   * The `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 `sizeof' operator. For instance, the sizeof of
     the `GtkObject' structure is computed by doing `sizeof
     (GtkObject)'.

   * The `class_size' field refers to the size in bytes of the C
     structure for the class. Again, the `sizeof' operator should be
     used to compute this value.

   * The `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.

   * The `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.

   * The `value_init_func' field is a callback which is used by the type
     mechanism to initialize object stack value types. (FIXME:
     unfinished).

 - Function: guint gtk_type_unique (guint PARENT_TYPE, GtkTypeInfo
          *TYPE_INFO)
     The PARENT_TYPE is simply the value of the new types parent type.
     If PARENT_TYPE is 0, then the new type is the root of the type
     hierarchy. TYPE_INFO is a pointer to a structure which contains
     necessary information for construction of the new type.
     Specifically, the `type_name', `object_size' and `class_size'
     fields are required. The `class_init_func', `object_init_func' and
     `value_init_func' fields may be NULL.

 - Function: gchar* gtk_type_name (guint TYPE)
     The returned string is the name of TYPE as specified to
     `gtk_type_unique'.

 - Function: guint gtk_type_from_name (guchar *NAME)
     Return the type associated with NAME. If there is no type
     associated with NAME, then 0 will be returned.

 - Function: guint gtk_type_parent (guint TYPE)
     Returns the parent type of TYPE or 0 if TYPE is the root of the
     type hierarchy.

 - Function: gpointer gtk_type_class (guint TYPE)
     Returns the initialized class structure for TYPE. The class
     structure is actually created and initialized the first time it is
     needed. If creation and initialization occurs, the `class_size'
     field of the `GtkTypeInfo' structure used to initialize this type
     is used to determine how large the class structure is. The
     `class_init_func' field from the `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 `GtkWidgetClass' is first initialized as an
     `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 TYPE and, as such, should not be modified.

 - Function: gpointer gtk_type_new (guint TYPE)
     Returns a new instance of an TYPE object. The object structure is
     created and initialized similarly to the class structure (as
     described above). The `object_size' and `object_init_func' fields
     of the `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.

 - Function: void gtk_type_describe_heritage (guint TYPE)
     Prints the type heritage for TYPE. The heritage for a type
     includes the type and all its parent types up the type tree.

 - Function: void gtk_type_describe_tree (guint TYPE, gint SHOW_SIZE)
     Prints the type tree which starts at TYPE. SHOW_SIZE is a boolean
     which determines whether type sizes are printed.

 - Function: gint gtk_type_is_a (guint TYPE, guint IS_A_TYPE)
     A predicate function which determines whether the relation TYPE
     is_a IS_A_TYPE is true.

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 *Note Object Implementation::.

 - Function: guint gtk_object_get_type (void)
     Returns the `GtkObject' type identifier.

 - Function: void gtk_object_class_add_signals (GtkObjectClass *CLASS,
          gint *SIGNALS, gint NSIGNALS)
     Adds SIGNALS to the `signals' field in the GtkObjectClass
     structure CLASS. *Note Signals::.

 - Function: void gtk_object_destroy (GtkObject *OBJECT)
     Performs checks to make sure it is alright to destroy OBJECT and
     then emits the `destroy' signal. The check which is performed is to
     make sure 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 OBJECT
     is processing another signal we mark OBJECT is needing to be
     destroyed. When we finish processing of the other signal we check
     whether the object needs to be destroyed.

   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 `gtk_object_set_data',
`gtk_object_get_data', and `gtk_object_remove_data' are the interface
to this mechanism. Two other routines, `gtk_object_set_user_data' and
`gtk_object_get_user_data', exist as convenience functions which simply
use the same mechanism.

 - Function: void gtk_object_set_data (GtkObject *OBJECT, const char
          *KEY, gpointer DATA)
     Associate DATA with KEY in the data list of OBJECT.

 - Function: gpointer gtk_object_get_data (GtkObject *OBJECT, const
          char *KEY)
     Retrieve the data associated with KEY in the data list of OBJECT.

 - Function: void gtk_object_remove_data (GtkObject *OBJECT, const char
          *KEY)
     Remove the data associated with KEY in the data list of OBJECT.

 - Function: void gtk_object_set_user_data (GtkObject *OBJECT, gpointer
          DATA)
     Sets DATA into the `user_data' field of OBJECT.

 - Function: gpointer gtk_object_get_user_data (GtkObject *OBJECT)
     Returns the `user_data' field of OBJECT.

   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).

 - Function: void gtk_object_value_stack_new (guint OBJECT_TYPE, const
          gchar *VALUE_ID, GtkParamType VALUE_TYPE)

 - Function: void gtk_object_push_value (guint OBJECT_TYPE, const gchar
          *VALUE_ID, ...)
     Push a value on the value stack specified by OBJECT_TYPE and
     VALUE_ID. The type of value is implicitly given in the context of
     OBJECT_TYPE and 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.

 - Function: void gtk_object_pop_value (guint OBJECT_TYPE, const gchar
          *VALUE_ID)
     Pop a value of the value stack specified by OBJECT_TYPE and
     VALUE_ID.

 - Function: gint gtk_object_peek_value (guint OBJECT_TYPE, const gchar
          *VALUE_ID, gpointer DATA)
     Peek at the value on the top of the value stack specified by
     OBJECT_TYPE and VALUE_ID. The DATA argument is interpreted as the
     location of where to place the "peeked" data. For instance, if the
     peeked data is of type `GTK_PARAM_POINTER', then DATA will be a
     pointer to a pointer. If the value stack is empty or does not
     exist or an error occurs, `gtk_object_peek_value' will return
     `FALSE'. On success it will return `TRUE'.


File: gtk.info,  Node: Signals,  Next: Widgets,  Prev: Objects,  Up: Top

Signals Overview
****************

   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.

 - Function: gint gtk_signal_new (gchar *NAME, GtkSignalRunType
          RUN_TYPE, gint OBJECT_TYPE, gint FUNCTION_OFFSET,
          GtkSignalMarsahller MARSHALLER, GtkParamType RETURN_VAL, gint
          NPARAMS, ...)
     Create a new signal and give it the character string identifier
     NAME. NAME needs to be unique in the context of OBJECT_TYPE's
     branch of the class hierarchy. That is, OBJECT_TYPE cannot create
     a signal type with the same name as a signal type created by one
     of its parent types.

     RUN_TYPE specifies whether the class function should be run before
     (`GTK_RUN_FIRST'), after (`GTK_RUN_LAST') or both before and after
     normal signal handlers (`GTK_RUN_BOTH'). Additionally, the
     `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 `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 `GTK_RUN_NO_RECURSE' flag is used by the
     GtkAdjustment widget).

     The 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
     `GTK_SIGNAL_OFFSET' macro which takes the class structure type as
     the first argument and the field as the second argument. For
     example, `GTK_SIGNAL_OFFSET (GtkObjectClass, destroy)' will give
     the offset of the `destroy' class function within the
     `GtkObjectClass'. Note: An offset is specified instead of an
     absolute location since there will be multiple instances of a class
     structure being referenced. (The `GtkWidgetClass' structure "is a"
     `GtkObjectClass' structure, etc.)

     The 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 RETURN_VAL and 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 (...) specifies the types of the arguments. These
     can be one of `GTK_PARAM_CHAR', `GTK_PARAM_SHORT',
     `GTK_PARAM_INT', `GTK_PARAM_LONG', `GTK_PARAM_POINTER' or
     `GTK_PARAM_FUNCTION'. It is undefined to specify `GTK_PARAM_NONE'
     as an argument type, however it is ok to use `GTK_PARAM_NONE' for
     RETURN_VAL. (This corresponds to returning a `void').

     `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.

     *Note:* `gtk_signal_new' is only needed by widget writers. A
     normal user of GTK will never needed to invoke this function.

 - Function: gint gtk_signal_lookup (gchar *NAME, gint OBJECT_TYPE)
     Returns the integer identifier for the signal referenced by NAME
     and OBJECT_TYPE. If OBJECT_TYPE does not define the signal NAME,
     then the signal is looked for in OBJECT_TYPE's parent type
     recursively.

 - Function: gint gtk_signal_emit (GtkObject *OBJECT, gint SIGNAL_TYPE,
          ...)
     Emit the signal specified by the integer identifier SIGNAL_TYPE
     from OBJECT. If an error occurs, `gtk_signal_emit' will return
     `FALSE' and will return `TRUE' on success. The signal definition
     determines the parameters passed in the variable argument list
     (`...'). For example, if the signal is defined as:

            gint (* event) (GtkWidget *widget, GdkEvent *event);

     Then a call to emit the "event" signal would look like:

            GdkEvent event;
            gint return_val;
            ...
            gtk_signal_emit (some_object,
                             gtk_signal_lookup ("event",
                               GTK_OBJECT_TYPE (some_object)),
                             &event, &return_val);

     Notice that the `widget' argument is implicit in that the first
     argument to every signal is a type derived from `GtkObject'. The
     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 `gtk_signal_lookup'
     call is normally avoided by using the `gtk_signal_emit_by_name'
     function instead. `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
     `gtk_signal_lookup'.

 - Function: gint gtk_signal_emit_by_name (GtkObject *OBJECT, gchar
          *NAME, ...)
     Similar to `gtk_signal_emit' except that the signal is referenced
     by NAME instead of by its integer identifier.

 - Function: void gtk_signal_emit_stop (GtkObject *OBJECT, gint
          SIGNAL_TYPE)
     Stop the emission of the signal SIGNAL_TYPE on OBJECT. SIGNAL_TYPE
     is the integer identifier for the signal and can be determined
     using the function `gtk_signal_lookup'. Alternatively, the function
     `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.

 - Function: void gtk_signal_emit_stop_by_name (GtkObject *OBJECT,
          gchar *NAME)
     Similar to `gtk_signal_emit_stop' except that the signal is
     referenced by NAME instead of by its integer identifier.

 - Function: gint gtk_signal_connect (GtkObject *OBJECT, gchar *NAME,
          GtkSignalFunc FUNC, gpointer FUNC_DATA)
     Connects a signal handling function to a signal emitting object.
     FUNC is connected to the signal NAME emitted by OBJECT. The
     arguments and returns type of FUNC should match the arguments and
     return type of the signal NAME. However, FUNC may take the extra
     argument of 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).

     `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.

 - Function: gint gtk_signal_connect_after (GtkObject *OBJECT, gchar
          *NAME, GtkSignalFunc FUNC, gpointer FUNC_DATA)
     Similar to `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 `gtk_signal_connect', `gtk_signal_connect_after' returns an
     integer identifier which can be used to refer to the connection.

 - Function: gint gtk_signal_connect_object (GtkObject *OBJECT, gchar
          *NAME, GtkSignalFunc FUNC, GtkObject *SLOT_OBJECT)
     Connects FUNC to the signal NAME emitted by OBJECT. Similar to
     `gtk_signal_connect' with the difference that SLOT_OBJECT is
     passed as the first parameter to 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.

 - Function: gint gtk_signal_connect_object_after (GtkObject *OBJECT,
          gchar *NAME, GtkSignalFunc FUNC, GtkObject *SLOT_OBJECT)
     Similar to `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.

 - Function: void gtk_signal_disconnect (GtkObject *OBJECT, gint ID)
     Disconnects a signal handler from an object. The signal handler is
     identified by the integer ID which is returned by the
     `gtk_signal_connect*' family of functions.

 - Function: void gtk_signal_disconnect_by_data (GtkObject *OBJECT,
          gpointer DATA)
     Disconnects a signal handler from an object. The signal handler is
     identified by the DATA argument specified as the FUNC_DATA
     argument to the `gtk_signal_connect*' family of functions. For the
     `gtk_signal_connect_object*' functions, DATA refers to the
     SLOT_OBJECT.

     *Note:* This will remove all signal handlers connected to OBJECT
     which were connected using DATA as their FUNC_DATA argument.
     Multiple signal handlers may be disconnected with this call.

 - Function: void gtk_signal_handler_block (GtkObject *OBJECT, gint ID)
     Blocks calling of a signal handler during signal emission. The
     signal handler is identified by the integer ID which is returned
     by the `gtk_signal_connect*' family of functions. If the signal is
     already blocked no change is made.

 - Function: void gtk_signal_handler_block_by_data (GtkObject *OBJECT,
          gint DATA)
     Blocks calling of a signal handler during signal emission. The
     signal handler is identified by the DATA argument specified as the
     FUNC_DATA argument to the `gtk_signal_connect*' family of
     functions. For the `gtk_signal_connect_object*' functions, DATA
     refers to the SLOT_OBJECT. If the signal is already blocked no
     change is made.

     *Note:* This will block all signal handlers connected to OBJECT
     which were connected using DATA as their FUNC_DATA argument.
     Multiple signal handlers may be blocked with this call.

 - Function: void gtk_signal_handler_unblock (GtkObject *OBJECT, gint
          ID)
     Unblocks calling of a signal handler during signal emission. The
     signal handler is identified by the integer ID which is returned
     by the `gtk_signal_connect*' family of functions. If the signal is
     already unblocked no change is made.

 - Function: void gtk_signal_handler_unblock_by_data (GtkObject
          *OBJECT, gint DATA)
     Unblocks calling of a signal handler during signal emission. The
     signal handler is identified by the DATA argument specified as the
     FUNC_DATA argument to the `gtk_signal_connect*' family of
     functions. For the `gtk_signal_connect_object*' functions, DATA
     refers to the SLOT_OBJECT. If the signal is already unblocked no
     change is made.

     *Note:* This will unblock all signal handlers connected to OBJECT
     which were connected using DATA as their FUNC_DATA argument.
     Multiple signal handlers may be unblocked with this call.

 - Function: void gtk_signal_handlers_destroy (GtkObject *OBJECT)
     Destroy all of the signal handlers connected to OBJECT. There
     should normally never be reason to call this function as it is
     called automatically when OBJECT is destroyed.

 - Function: void gtk_signal_default_marshaller (GtkObject *OBJECT,
          GtkSignalFunc FUNC, gpointer FUNC_DATA, GtkSignalParam
          *PARAMS)
     `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:

            (* std_signal) (gpointer std_arg);

     `gtk_signal_default_marshaller' is a signal marshaller which
     marshals arguments for a signal of that form.


File: gtk.info,  Node: Widgets,  Next: Other Objects,  Prev: Signals,  Up: Top

Widget Overview
***************

   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. *Note 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.


File: gtk.info,  Node: GtkAlignment,  Next: GtkArrow,  Prev: Widgets,  Up: Widgets

The alignment widget
====================

Description
-----------

   The alignment widget is a container (*note GtkContainer::.) derived
from the bin widget (*note 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. (*note 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.

Options
-------

 - User Option: xscale
 - User Option: yscale
     The XSCALE and 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.

 - User Option: xalign
 - User Option: yalign
     The XALIGN and YALIGN options specify how to position the child
     widget when it is not allocated all the space available to it
     (because the XSCALE and/or 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 XALIGN and YALIGN to be 0.5 which
     causes the widget to be centered within its allocated area.

Signals
-------

Functions
---------

 - Function: guint gtk_alignment_get_type (void)
     Returns the `GtkAlignment' type identifier.

 - Function: GtkWidget* gtk_alignment_new (gfloat XALIGN, gfloat
          YALIGN, gfloat XSCALE, gfloat YSCALE)
     Create a new `GtkAlignment' object and initialize it with the
     values XALIGN, YALIGN, XSCALE and YSCALE. The new widget is
     returned as a pointer to a `GtkWidget' object. `NULL' is returned
     on failure.

 - Function: void gtk_alignment_set (GtkAlignment *ALIGNMENT, gfloat
          XALIGN, gfloat YALIGN, gfloat XSCALE, gfloat YSCALE)
     Set the XALIGN, YALIGN, XSCALE and YSCALE options of an alignment
     widget. It is important to not set the fields of the
     `GtkAlignment' structure directly (or, for that matter, any type
     derived from `GtkObject').

 - Function: GtkAlignment* GTK_ALIGNMENT (gpointer OBJ)
     Cast a generic pointer to `GtkAlignment*'. *Note Standard
     Macros::, for more info.

 - Function: GtkAlignmentClass* GTK_ALIGNMENT_CLASS (gpointer CLASS)
     Cast a generic pointer to `GtkAlignmentClass*'. *Note Standard
     Macros::, for more info.

 - Function: gint GTK_IS_ALIGNMENT (gpointer OBJ)
     Determine if a generic pointer refers to a `GtkAlignment' object.
     *Note Standard Macros::, for more info.


File: gtk.info,  Node: GtkArrow,  Next: GtkBin,  Prev: GtkAlignment,  Up: Widgets

The arrow widget
================

Description
-----------

   The arrow widget is derived from the misc widget (*note 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.

Options
-------

 - User Option: arrow_type
     The ARROW_TYPE option specifies which direction the arrow will
     point. It can be one of `GTK_ARROW_UP', `GTK_ARROW_DOWN',
     `GTK_ARROW_LEFT' or `GTK_ARROW_RIGHT'.

 - User Option: shadow_type
     The SHADOW_TYPE option specifies how to draw the shadow for the
     arrow. Currently, only the `GTK_SHADOW_IN' and `GTK_SHADOW_OUT'
     shadow types are supported for drawing arrows. Other shadow types
     will cause nothing to be drawn.

Signals
-------

Functions
---------

 - Function: guint gtk_arrow_get_type (void)
     Returns the `GtkArrow' type identifier.

 - Function: GtkWidget* gtk_arrow_new (GtkArrowType ARROW_TYPE,
          GtkShadowType SHADOW_TYPE)
     Create a new `GtkArrow' object and initialize it with the values
     ARROW_TYPE and SHADOW_TYPE. The new widget is returned as a
     pointer to a `GtkWidget' object. `NULL' is returned on failure.

 - Function: void gtk_arrow_set (GtkArrow *ARROW, GtkArrowType
          ARROW_TYPE, GtkShadowType SHADOW_TYPE)
     Set the ARROW_TYPE and SHADOW_TYPE options of an arrow widget. It
     is important to not set the fields of the `GtkArrow' structure
     directly (or, for that matter, any type derived from `GtkObject').

 - Function: GtkArrow* GTK_ARROW (gpointer OBJ)
     Cast a generic pointer to `GtkArrow*'. *Note Standard Macros::, for
     more info.

 - Function: GtkArrowClass* GTK_ARROW_CLASS (gpointer CLASS)
     Cast a generic pointer to `GtkArrowClass*'. *Note Standard
     Macros::, for more info.

 - Function: gint GTK_IS_ARROW (gpointer OBJ)
     Determine if a generic pointer refers to a `GtkArrow' object.
     *Note Standard Macros::, for more info.


File: gtk.info,  Node: GtkBin,  Next: GtkBox,  Prev: GtkArrow,  Up: Widgets

The bin widget
==============

Description
-----------

   The bin widget is a container (*note 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 (*note GtkAlignment::.), frames
(*note GtkFrame::.), items (*note GtkItem::.), viewports (*note
GtkViewport::.) and windows (*note GtkWindow::.)

Signals
-------

Functions
---------

 - Function: guint gtk_bin_get_type (void)
     Returns the `GtkBin' type identifier.

 - Function: GtkBin* GTK_BIN (gpointer OBJ)
     Cast a generic pointer to `GtkBin*'. *Note Standard Macros::, for
     more info.

 - Function: GtkBinClass* GTK_BIN_CLASS (gpointer CLASS)
     Cast a generic pointer to `GtkBinClass*'. *Note Standard Macros::,
     for more info.

 - Function: gint GTK_IS_BIN (gpointer OBJ)
     Determine if a generic pointer refers to a `GtkBin' object. *Note
     Standard Macros::, for more info.


File: gtk.info,  Node: GtkBox,  Next: GtkButton,  Prev: GtkBin,  Up: Widgets

The box widget
==============

Description
-----------

   The box widget is a container (*note GtkContainer::.) derived from
the container widget. It is an abstract base class used by the
horizontal box (*note GtkHBox::.) and vertical box (*note 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 (*note 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 `expand' and
`fill'. There operation is fairly simple. If `expand' is set, the
childs potentially allocated area will expand to fill available space.
If `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 `gtk_widget_size_allocate').

   The allocation of space to children occurs as follows (for horizontal
boxes):
  1. All children are allocated at least their requested size
     horizontally and the maximum requested child size vertically.

  2. Any child with the `expand' flag set is allocated `extra_width /
     nexpand_children' extra pixels horizontally. If the `homogeneous'
     flag was set, all children are considered to have the `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 `expand' flag set). The exception occurs when
     `extra_width / nexpand_children' does not divide cleanly. The extra
     space is given to the last widget.

  3. `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 `padding' value
     associated with each child causes that many pixels to be left
     empty to each side of the child.

  4. If a child has the `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.

  5. 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.

   *Note GtkHBox::, and *Note GtkVBox::, for code examples of using
horizontal and vertical boxes.

Options
-------

Signals
-------

Functions
---------

 - Function: guint gtk_box_get_type (void)
     Returns the `GtkBox' type identifier.

 - Function: void gtk_box_pack_start (GtkBox *BOX, GtkWidget *CHILD,
          gint EXPAND, gint FILL, gint PADDING)
     Add CHILD to the front of BOX. The flags EXPAND and FILL and the
     padding value of PADDING are associated with CHILD.

 - Function: void gtk_box_pack_end (GtkBox *BOX, GtkWidget *CHILD, gint
          EXPAND, gint FILL, gint PADDING)
     Add CHILD to the end of BOX. The flags EXPAND and FILL and the
     padding value of PADDING are associated with CHILD.

 - Function: void gtk_box_pack_start_defaults (GtkBox *BOX, GtkWidget
          *WIDGET)
     A convenience function which is equivalent to the following:

            gtk_box_pack_start (BOX, WIDGET, TRUE, TRUE, 0);

 - Function: void gtk_box_pack_end_defaults (GtkBox *BOX, GtkWidget
          *WIDGET)
     A convenience function which is equivalent to the following:

            gtk_box_pack_start (BOX, WIDGET, TRUE, TRUE, 0);

 - Function: GtkBox* GTK_BOX (gpointer OBJ)
     Cast a generic pointer to `GtkBox*'. *Note Standard Macros::, for
     more info.

 - Function: GtkBoxClass* GTK_BOX_CLASS (gpointer CLASS)
     Cast a generic pointer to `GtkBoxClass*'. *Note Standard Macros::,
     for more info.

 - Function: gint GTK_IS_BOX (gpointer OBJ)
     Determine if a generic pointer refers to a `GtkBox' object. *Note
     Standard Macros::, for more info.


File: gtk.info,  Node: GtkButton,  Next: GtkCheckButton,  Prev: GtkBox,  Up: Widgets

The button widget
=================

Description
-----------

Signals
-------

 - Signal: void GtkButton::pressed (GtkButton *BUTTON)

 - Signal: void GtkButton::released (GtkButton *BUTTON)

 - Signal: void GtkButton::clicked (GtkButton *BUTTON)

 - Signal: void GtkButton::enter (GtkButton *BUTTON)

 - Signal: void GtkButton::leave (GtkButton *BUTTON)

Functions
---------

 - Function: guint gtk_button_get_type (void)

 - Function: GtkWidget* gtk_button_new (void)

 - Function: GtkWidget* gtk_button_new_with_label (gchar *LABEL)

 - Function: void gtk_button_pressed (GtkButton *BUTTON)

 - Function: void gtk_button_released (GtkButton *BUTTON)

 - Function: void gtk_button_clicked (GtkButton *BUTTON)

 - Function: void gtk_button_enter (GtkButton *BUTTON)

 - Function: void gtk_button_leave (GtkButton *BUTTON)

 - Function: GtkButton* GTK_BUTTON (gpointer OBJ)
     Cast a generic pointer to `GtkButton*'. *Note Standard Macros::,
     for more info.

 - Function: GtkButtonClass* GTK_BUTTON_CLASS (gpointer CLASS)
     Cast a generic pointer to `GtkButtonClass*'. *Note Standard
     Macros::, for more info.

 - Function: gint GTK_IS_BUTTON (gpointer OBJ)
     Determine if a generic pointer refers to a `GtkButton' object.
     *Note Standard Macros::, for more info.


File: gtk.info,  Node: GtkCheckButton,  Next: GtkCheckMenuItem,  Prev: GtkButton,  Up: Widgets

The check button widget
=======================

Description
-----------

Signals
-------

Functions
---------

 - Function: guint gtk_check_button_get_type (void)

 - Function: GtkWidget* gtk_check_button_new (void)

 - Function: GtkWidget* gtk_check_button_new_with_label (gchar *LABEL)

 - Function: GtkCheckButton* GTK_CHECK_BUTTON (gpointer OBJ)

 - Function: GtkCheckButtonClass* GTK_CHECK_BUTTON_CLASS (gpointer
          CLASS)

 - Function: gint GTK_IS_CHECK_BUTTON (gpointer OBJ)

 - Function: GtkCheckButton* GTK_CHECK_BUTTON (gpointer OBJ)
     Cast a generic pointer to `GtkCheckButton*'. *Note Standard
     Macros::, for more info.

 - Function: GtkCheckButtonClass* GTK_CHECK_BUTTON_CLASS (gpointer
          CLASS)
     Cast a generic pointer to `GtkCheckButtonClass*'. *Note Standard
     Macros::, for more info.

 - Function: gint GTK_IS_CHECK_BUTTON (gpointer OBJ)
     Determine if a generic pointer refers to a `GtkCheckButton'
     object. *Note Standard Macros::, for more info.


File: gtk.info,  Node: GtkCheckMenuItem,  Next: GtkContainer,  Prev: GtkCheckButton,  Up: Widgets

The check menu item widget
==========================

Description
-----------

Signals
-------

 - Signal: void GtkCheckMenuItem::toggled (GtkCheckMenuItem
          *CHECK_MENU_ITEM)

Functions
---------

 - Function: guint gtk_check_menu_item_get_type (void)

 - Function: GtkWidget* gtk_check_menu_item_new (void)

 - Function: GtkWidget* gtk_check_menu_item_new_with_label (gchar
          *LABEL)

 - Function: void gtk_check_menu_item_set_state (GtkCheckMenuItem
          *CHECK_MENU_ITEM, gint STATE)

 - Function: void gtk_check_menu_item_toggled (GtkCheckMenuItem
          *CHECK_MENU_ITEM)

 - Function: GtkCheckMenuItem* GTK_CHECK_MENU_ITEM (gpointer OBJ)
     Cast a generic pointer to `GtkCheckMenuItem*'. *Note Standard
     Macros::, for more info.

 - Function: GtkCheckMenuItemClass* GTK_CHECK_MENU_ITEM_CLASS (gpointer
          CLASS)
     Cast a generic pointer to `GtkCheckMenuItemClass*'. *Note Standard
     Macros::, for more info.

 - Function: gint GTK_IS_CHECK_MENU_ITEM (gpointer OBJ)
     Determine if a generic pointer refers to a `GtkCheckMenuItem'
     object. *Note Standard Macros::, for more info.

