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: GtkWidget,  Next: GtkWindow,  Prev: GtkVSeparator,  Up: Widgets

The base widget
===============

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

Signals
-------

 - Signal: void GtkWidget::show (GtkWidget *WIDGET)

 - Signal: void GtkWidget::hide (GtkWidget *WIDGET)

 - Signal: void GtkWidget::map (GtkWidget *WIDGET)

 - Signal: void GtkWidget::unmap (GtkWidget *WIDGET)

 - Signal: void GtkWidget::realize (GtkWidget *WIDGET)

 - Signal: void GtkWidget::unrealize (GtkWidget *WIDGET)

 - Signal: void GtkWidget::draw (GtkWidget *WIDGET, GdkRectangle *AREA)

 - Signal: void GtkWidget::draw_focus (GtkWidget *WIDGET)

 - Signal: void GtkWidget::draw_default (GtkWidget *WIDGET)

 - Signal: void GtkWidget::size_request (GtkWidget *WIDGET,
          GtkRequisition *REQUISITION)

 - Signal: void GtkWidget::size_allocate (GtkWidget *WIDGET,
          GtkAllocation *ALLOCATION)

 - Signal: void GtkWidget::state_changed (GtkWidget *WIDGET)

 - Signal: gint GtkWidget::install_accelerator (GtkWidget *WIDGET,
          gchar *SIGNAL_NAME, gchar KEY, guint8 MODIFIERS)

 - Signal: void GtkWidget::remove_accelerator (GtkWidget *WIDGET, gchar
          *SIGNAL_NAME)

 - Signal: gint GtkWidget::event (GtkWidget *WIDGET, GdkEvent *EVENT)

 - Signal: gint GtkWidget::button_press_event (GtkWidget *WIDGET,
          GdkEventButton *EVENT)

 - Signal: gint GtkWidget::button_release_event (GtkWidget *WIDGET,
          GdkEventButton *EVENT)

 - Signal: gint GtkWidget::motion_notify_event (GtkWidget *WIDGET,
          GdkEventMotion *EVENT)

 - Signal: gint GtkWidget::delete_event (GtkWidget *WIDGET, GdkEventAny
          *EVENT)

 - Signal: gint GtkWidget::destroy_event (GtkWidget *WIDGET,
          GdkEventAny *EVENT)

 - Signal: gint GtkWidget::expose_event (GtkWidget *WIDGET,
          GdkEventExpose *EVENT)

 - Signal: gint GtkWidget::key_press_event (GtkWidget *WIDGET,
          GdkEventKey *EVENT)

 - Signal: gint GtkWidget::key_release_event (GtkWidget *WIDGET,
          GdkEventKey *EVENT)

 - Signal: gint GtkWidget::enter_notify_event (GtkWidget *WIDGET,
          GdkEventCrossing *EVENT)

 - Signal: gint GtkWidget::leave_notify_event (GtkWidget *WIDGET,
          GdkEventCrossing *EVENT)

 - Signal: gint GtkWidget::configure_event (GtkWidget *WIDGET,
          GdkEventConfigure *EVENT)

 - Signal: gint GtkWidget::focus_in_event (GtkWidget *WIDGET,
          GdkEventFocus *EVENT)

 - Signal: gint GtkWidget::focus_out_event (GtkWidget *WIDGET,
          GdkEventFocus *EVENT)

 - Signal: gint GtkWidget::map_event (GtkWidget *WIDGET, GdkEventAny
          *EVENT)

 - Signal: gint GtkWidget::unmap_event (GtkWidget *WIDGET, GdkEventAny
          *EVENT)

 - Signal: gint GtkWidget::property_notify_event (GtkWidget *WIDGET,
          GdkEventProperty *EVENT)

 - Signal: gint GtkWidget::selection_clear_event (GtkWidget *WIDGET,
          GdkEventSelection *EVENT)

 - Signal: gint GtkWidget::selection_request_event (GtkWidget *WIDGET,
          GdkEventSelection *EVENT)

 - Signal: gint GtkWidget::selection_notify_event (GtkWidget *WIDGET,
          GdkEventSelection *EVENT)

 - Signal: gint GtkWidget::other_event (GtkWidget *WIDGET,
          GdkEventOther *EVENT)

Functions
---------

 - Function: guint gtk_widget_get_type (void)

 - Function: void gtk_widget_class_init (GtkWidgetClass *CLASS)

 - Function: void gtk_widget_init (GtkWidget *WIDGET)

 - Function: void gtk_widget_destroy (GtkWidget *WIDGET)

 - Function: void gtk_widget_show (GtkWidget *WIDGET)

 - Function: void gtk_widget_hide (GtkWidget *WIDGET)

 - Function: void gtk_widget_map (GtkWidget *WIDGET)

 - Function: void gtk_widget_unmap (GtkWidget *WIDGET)

 - Function: void gtk_widget_realize (GtkWidget *WIDGET)

 - Function: void gtk_widget_unrealize (GtkWidget *WIDGET)

 - Function: void gtk_widget_draw (GtkWidget *WIDGET, GdkRectangle
          *AREA)

 - Function: void gtk_widget_draw_focus (GtkWidget *WIDGET)

 - Function: void gtk_widget_draw_children (GtkWidget *WIDGET)

 - Function: void gtk_widget_size_request (GtkWidget *WIDGET,
          GtkRequisition *REQUISITION)

 - Function: void gtk_widget_size_allocate (GtkWidget *WIDGET,
          GtkAllocation *ALLOCATION)

 - Function: void gtk_widget_install_accelerator (GtkWidget *WIDGET,
          GtkAcceleratorTable *TABLE, gchar *SIGNAL_NAME, gchar KEY,
          guint8 MODIFIERS)

 - Function: void gtk_widget_remove_accelerator (GtkWidget *WIDGET,
          GtkAcceleratorTable *TABLE, gchar *SIGNAL_NAME)

 - Function: gint gtk_widget_event (GtkWidget *WIDGET, GdkEvent *EVENT)

 - Function: void gtk_widget_reparent (GtkWidget *WIDGET, GtkWidget
          *NEW_PARENT)

 - Function: void gtk_widget_popup (GtkWidget *WIDGET, gint X, gint Y)

 - Function: gint gtk_widget_intersect (GtkWidget *WIDGET, GdkRectangle
          *AREA, GdkRectangle *INTERSECTION)

 - Function: void gtk_widget_grab_focus (GtkWidget *WIDGET)

 - Function: void gtk_widget_grab_default (GtkWidget *WIDGET)

 - Function: void gtk_widget_restore_state (GtkWidget *WIDGET)

 - Function: void gtk_widget_set_name (GtkWidget *WIDGET, gchar *NAME)

 - Function: void gtk_widget_set_state (GtkWidget *WIDGET, GtkStateType
          STATE)

 - Function: void gtk_widget_set_sensitive (GtkWidget *WIDGET, gint
          sensitive)

 - Function: void gtk_widget_set_parent (GtkWidget *WIDGET, GtkWidget
          *PARENT)

 - Function: void gtk_widget_set_style (GtkWidget *WIDGET, GtkStyle
          *STYLE)

 - Function: void gtk_widget_set_uposition (GtkWidget *WIDGET, gint X,
          gint Y)

 - Function: void gtk_widget_set_usize (GtkWidget *WIDGET, gint WIDTH,
          gint HEIGHT)

 - Function: GtkWidget* gtk_widget_get_toplevel (GtkWidget *WIDGET)

 - Function: GtkWidget* gtk_widget_get_ancestor (GtkWidget *WIDGET,
          gint TYPE)

 - Function: GdkColormap* gtk_widget_get_colormap (GtkWidget *WIDGET)

 - Function: GdkVisual* gtk_widget_get_visual (GtkWidget *VISUAL)

 - Function: GtkStyle* gtk_widget_get_style (GtkWidget *STYLE)

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

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

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


File: gtk.info,  Node: GtkWindow,  Prev: GtkWidget,  Up: Widgets

The window widget
=================

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

Signals
-------

 - Signal: void GtkWindow::move_resize (GtkWindow *WINDOW, gint *X,
          gint *Y, gint WIDTH, gint HEIGHT)

Functions
---------

 - Function: guint gtk_window_get_type (void)

 - Function: GtkWidget* gtk_window_new (GtkWindowType TYPE)

 - Function: void gtk_window_set_title (GtkWindow *WINDOW, gchar *TITLE)

 - Function: void gtk_window_set_focus (GtkWindow *WINDOW, GtkWidget
          *FOCUS)

 - Function: void gtk_window_set_default (GtkWindow *WINDOW, GtkWidget
          *DEFAULTW)

 - Function: void gtk_window_set_policy (GtkWindow *WINDOW, gint
          ALLOW_SHRINK, gint ALLOW_GROW, gint AUTO_SHRINK)

 - Function: void gtk_window_add_accelerator_table (GtkWindow *WINDOW,
          GtkAcceleratorTable *TABLE)

 - Function: void gtk_window_remove_accelerator_table (GtkWindow
          *WINDOW, GtkAcceleratorTable *TABLE)

 - Function: void gtk_window_position (GtkWindow *WINDOW,
          GtkWindowPosition POSITION)

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

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

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


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

Utility objects
***************

* Menu:

* GtkAdjustment::               The adjustment object.
* GtkData::                     The data object.


File: gtk.info,  Node: GtkAdjustment,  Next: GtkData,  Prev: Other Objects,  Up: Other Objects

The adjustment object
=====================


File: gtk.info,  Node: GtkData,  Prev: GtkAdjustment,  Up: Other Objects

The data object
===============


File: gtk.info,  Node: Miscellaneous,  Next: Examples,  Prev: Other Objects,  Up: Top

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.


File: gtk.info,  Node: Initialization and exit,  Next: Menu Factories,  Prev: Miscellaneous,  Up: Miscellaneous

Initializing and exiting GTK
============================


File: gtk.info,  Node: Menu Factories,  Next: Tree Factories,  Prev: Initialization and exit,  Up: Miscellaneous

Simplified menu creation
========================


File: gtk.info,  Node: Tree Factories,  Next: Tool Tips,  Prev: Menu Factories,  Up: Miscellaneous

Simplified tree creation
========================


File: gtk.info,  Node: Tool Tips,  Next: Resource Files,  Prev: Tree Factories,  Up: Miscellaneous

Pop up help mechanism
=====================


File: gtk.info,  Node: Resource Files,  Next: Standard Macros,  Prev: Tool Tips,  Up: Miscellaneous

Pop up help mechanism
=====================


File: gtk.info,  Node: Standard Macros,  Prev: Resource Files,  Up: Miscellaneous

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

 - Function: Gtk<ObjectType>* GTK_<OBJECT_TYPE> (gpointer OBJ)
     Cast a generic pointer to `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 `gtk_type_is_a') before performing
     the cast.

 - Function: Gtk<ObjectType>Class* GTK_<OBJECT_TYPE>_CLASS (gpointer
          CLASS)
     Cast a generic pointer to `Gtk<ObjectType>Class*'. Like
     `GTK_<ObjectType>', this function is, in reality, a macro.

 - Function: gint GTK_IS_<ObjectType> (gpointer OBJ)
     Determine if a generic pointer refers to a `Gtk<ObjectType>'
     object. This function is, in reality, a macro wrapper around the
     `gtk_type_is_a' function (*note Objects::.).


File: gtk.info,  Node: Examples,  Next: Object Implementation,  Prev: Miscellaneous,  Up: Top

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.


File: gtk.info,  Node: Simple,  Next: Hello World,  Prev: Examples,  Up: Examples

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.

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

   The first point of interest in this program is the standard
initialization line.

       gtk_init (&argc, &argv);

   Almost every GTK program will contain such a line. GTK will
initialize itself and GDK and remove any command line arguments it
recognizes from ARGC and ARGV.

   The next two lines of code create and display a window.

       window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
       gtk_widget_show (window);

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

       gtk_main ();

   Normally, `gtk_main' is called once and the program should exit when
it returns. *Note Initialization and exit::.


File: gtk.info,  Node: Hello World,  Next: Hello World II,  Prev: Simple,  Up: Examples

Hello world in GTK
==================

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


File: gtk.info,  Node: Hello World II,  Next: Hello World III,  Prev: Hello World,  Up: Examples

An enhanced hello world
=======================

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


File: gtk.info,  Node: Hello World III,  Prev: Hello World II,  Up: Examples

Making Hello World II robust
============================

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


File: gtk.info,  Node: Object Implementation,  Next: Signal Implementation,  Prev: Examples,  Up: Top

Object internals
****************

   Objects (or the `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 `GtkObject' would
define itself like:

     struct Descendant
     {
       GtkObject object;
     
       ...
     };

   It is important to note that the `GtkObject' field needs to appear
first in the descendant type structure. This allows pointers to objects
of type `Descendant' to be cast to pointers to `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
`GtkObject' class defines the `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 `klass' field of the `GtkObject' structure.

   To see how the class fields work it is necessary to see the object
fields for a `GtkObject'. The `GtkObject' type is defined as follows:

     typedef struct _GtkObject GtkObject;
     
     struct _GtkObject
     {
       guint32 flags;
       GtkObjectClass *klass;
       gpointer object_data;
     };

   The `class' field actually points to a class structure derived from
`GtkObjectClass'. By convention, each new type defines its own class
structure even if it is unnecessary. As an example, the hypothetical
`Descendant' class would define its class structure as:

     struct DescendantClass
     {
       GtkObjectClass parent_class;
     
       ...
     };

   It is convention to name the parent class field (`GtkObjectClass' in
this case), `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.

   *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 `flags' field of the `GtkObject' structure is used to keep track
of a relatively few object flags and is also used by the `GtkWidget'
type to store additional flags. At this time, the upper 16 bits of the
flags field are reserved but unused.

   The `object_data' field of the `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.

     typedef struct _GtkObjectData GtkObjectData;
     
     struct _GtkObjectData
     {
       guint id;
       gpointer data;
       GtkObjectData *next;
     };

   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
`GtkObjectData' structure by 4 bytes on 32 bit architectures.


File: gtk.info,  Node: Signal Implementation,  Next: Widget Implementation,  Prev: Object Implementation,  Up: Top

Signal internals
****************


File: gtk.info,  Node: Widget Implementation,  Next: Function Index,  Prev: Signal Implementation,  Up: Top

Widget internals
****************

