This is Info file gtk.info, produced by Makeinfo version 1.67 from the input file gtk.texi. This file documents GTK, the GIMP 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 GIMP Toolkit END-INFO-DIR-ENTRY  File: gtk.info, Node: GtkViewport, Next: GtkVPaned, Prev: GtkVButtonBox, Up: Widgets The viewport widget =================== Description ----------- Signals ------- Functions --------- - Function: guint gtk_viewport_get_type (void) Returns the `GtkViewport' type identifier. - Function: GtkWidget* gtk_viewport_new (GtkAdjustment *HADJUSTMENT, GtkAdjustment *VADJUSTMENT) - Function: GtkAdjustment* gtk_viewport_get_hadjustment (GtkViewport *VIEWPORT) - Function: GtkAdjustment* gtk_viewport_get_vadjustment (GtkViewport *VIEWPORT) - Function: void gtk_viewport_set_hadjustment (GtkViewport *VIEWPORT, GtkAdjustment *ADJUSTMENT) - Function: void gtk_viewport_set_vadjustment (GtkViewport *VIEWPORT, GtkAdjustment *ADJUSTMENT) - Function: void gtk_viewport_set_shadow_type (GtkViewport *VIEWPORT, GtkShadowType TYPE) - Function: GtkViewport* GTK_VIEWPORT (gpointer OBJ) Cast a generic pointer to `GtkViewport*'. *Note Standard Macros::, for more info. - Function: GtkViewportClass* GTK_VIEWPORT_CLASS (gpointer CLASS) Cast a generic pointer to `GtkViewportClass*'. *Note Standard Macros::, for more info. - Function: gint GTK_IS_VIEWPORT (gpointer OBJ) Determine if a generic pointer refers to a `GtkViewport' object. *Note Standard Macros::, for more info.  File: gtk.info, Node: GtkVPaned, Next: GtkVRuler, Prev: GtkViewport, Up: Widgets The vertical paned widget ========================= Description ----------- Options ------- Signals ------- Functions --------- - Function: guint gtk_vpaned_get_type (void) Returns the `GtkVPaned' type identifier. - Function: GtkWidget* gtk_vpaned_new (void) Create a new `GtkVPaned' object returning the new widget as a pointer to a `GtkWidget' object. `NULL' is returned on failure. - Function: GtkVPaned* GTK_VPANED (gpointer OBJ) Cast a generic pointer to `GtkVPaned*'. *Note Standard Macros::, for more info. - Function: GtkVPanedClass* GTK_VPANED_CLASS (gpointer CLASS) Cast a generic pointer to `GtkVPanedClass*'. *Note Standard Macros::, for more info. - Function: gint GTK_IS_VPANED (gpointer OBJ) Determine if a generic pointer refers to a `GtkVPaned' object. *Note Standard Macros::, for more info.  File: gtk.info, Node: GtkVRuler, Next: GtkVScale, Prev: GtkVPaned, Up: Widgets The vertical ruler widget ========================= Description ----------- Options ------- Signals ------- Functions --------- - Function: guint gtk_vruler_get_type (void) Returns the `GtkVRuler' type identifier. - Function: GtkWidget* gtk_vruler_new (void) Create a new `GtkVRuler' object returning the new widget as a pointer to a `GtkWidget' object. `NULL' is returned on failure. - Function: GtkVRuler* GTK_VRULER (gpointer OBJ) Cast a generic pointer to `GtkVRuler*'. *Note Standard Macros::, for more info. - Function: GtkVRulerClass* GTK_VRULER_CLASS (gpointer CLASS) Cast a generic pointer to `GtkVRulerClass*'. *Note Standard Macros::, for more info. - Function: gint GTK_IS_VRULER (gpointer OBJ) Determine if a generic pointer refers to a `GtkVRuler' object. *Note Standard Macros::, for more info.  File: gtk.info, Node: GtkVScale, Next: GtkVScrollbar, Prev: GtkVRuler, Up: Widgets The vertical ruler widget ========================= Description ----------- Options ------- Signals ------- Functions --------- - Function: guint gtk_vscale_get_type (void) Returns the `GtkVScale' type identifier. - Function: GtkWidget* gtk_vscale_new (GtkAdjustment *ADJUSTMENT) Create a new `GtkVScale' object returning the new widget as a pointer to a `GtkWidget' object. `NULL' is returned on failure. - Function: GtkVScale* GTK_VSCALE (gpointer OBJ) Cast a generic pointer to `GtkVScale*'. *Note Standard Macros::, for more info. - Function: GtkVScaleClass* GTK_VSCALE_CLASS (gpointer CLASS) Cast a generic pointer to `GtkVScaleClass*'. *Note Standard Macros::, for more info. - Function: gint GTK_IS_VSCALE (gpointer OBJ) Determine if a generic pointer refers to a `GtkVScale' object. *Note Standard Macros::, for more info.  File: gtk.info, Node: GtkVScrollbar, Next: GtkVSeparator, Prev: GtkVScale, Up: Widgets The vertical scrollbar widget ============================= Description ----------- Options ------- Signals ------- Functions --------- - Function: guint gtk_vscrollbar_get_type (void) Returns the `GtkVScrollbar' type identifier. - Function: GtkWidget* gtk_vscrollbar_new (GtkAdjustment *ADJUSTMENT) Create a new `GtkVScrollbar' object initializing it with the values in ADJUSTMENT. The new widget is returned as a pointer to a `GtkWidget' object. `NULL' is returned on failure. - Function: GtkVScrollbar* GTK_VSCROLLBAR (gpointer OBJ) Cast a generic pointer to `GtkVScrollbar*'. *Note Standard Macros::, for more info. - Function: GtkVScrollbarClass* GTK_VSCROLLBAR_CLASS (gpointer CLASS) Cast a generic pointer to `GtkVScrollbarClass*'. *Note Standard Macros::, for more info. - Function: gint GTK_IS_VSCROLLBAR (gpointer OBJ) Determine if a generic pointer refers to a `GtkVScrollbar' object. *Note Standard Macros::, for more info.  File: gtk.info, Node: GtkVSeparator, Next: GtkWidget, Prev: GtkVScrollbar, Up: Widgets The vertical separator widget ============================= Description ----------- Signals ------- Functions --------- - Function: guint gtk_vseparator_get_type (void) Returns the `GtkVSeparator' type identifier. - Function: GtkWidget* gtk_vseparator_new (void) Create a new `GtkVSeparator' object and return the new widget as a pointer to a `GtkWidget' object. `NULL' is returned on failure. - Function: GtkVSeparator* GTK_VSEPARATOR (gpointer OBJ) Cast a generic pointer to `GtkVSeparator*'. *Note Standard Macros::, for more info. - Function: GtkVSeparatorClass* GTK_VSEPARATOR_CLASS (gpointer CLASS) Cast a generic pointer to `GtkVSeparatorClass*'. *Note Standard Macros::, for more info. - Function: gint GTK_IS_VSEPARATOR (gpointer OBJ) Determine if a generic pointer refers to a `GtkVSeparator' object. *Note Standard Macros::, for more info.  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::drop_event (GtkWidget *WIDGET, GdkEventDrop *EVENT) - Signal: gint GtkWidget::drag_begin_event (GtkWidget *WIDGET, GdkEventDragBegin *EVENT) - Signal: gint GtkWidget::other_event (GtkWidget *WIDGET, GdkEventOther *EVENT) Functions --------- - Function: guint gtk_widget_get_type (void) Returns the `GtkWidget' type identifier. - 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 ----------- Options ------- - User Option: type The TYPE options specify how this widget will interact with the window manager. Currently the following types and the effect they have on the window to window manager interaction is as follows. * `GTK_WINDOW_TOPLEVEL' * The option `GTK_WINDOW_TOPLEVEL' is usually used for the main application window that will remain for the entire application run. * `GTK_WINDOW_DIALOG' * The option `GTK_WINDOW_DIALOG' is usually used for transient windows. These windows will open up, gather some input or provide some application specific updates, then close. The window manager is free not to provide all the 'normal' window functions to this window. * `GTK_WINDOW_POPUP' * The option `GTK_WINDOW_POPUP' is usually used for transient windows. These windows are typically used for when no user interaction is required, to notify the user of some condition. Other uses for these types of windows are for 'about windows', startup windows and the like. Typically the window manager will *not* provide the usual widgets that surround the window. At the most all that will be provided is a border. Also note that windows that set this TYPE will not be in any window list of the window manager. Though this window will *not* get the kill and close widgets of the window manager they still can receive said events and should be taken into account. - User Option: title The TITLE option will set the title of the window in the window manager. *Note:* On windows that have the TYPE option set to `GTK_WINDOW_POPUP' there is a strong possibility that this will text will not be seen. - User Option: position The POSITION option will determine where the window will be displayed when it is finally drawn to the screen. Currently the following positions and the effect they have on window placement can be specified. * `GTK_WIN_POS_NONE' * This POSITION type will allow the window manager full freedom, depending on the current settings in the window manager. As to where the window will be placed. * `GTK_WIN_POS_CENTER' * This POSITION option will cause the window to center itself on the the screen. This option setting will take into account the VIRTUAL SCREEN size when calculating the center. This is *not* the same as the VIRTUAL DESKTOP setting of many window managers. It will center itself on the current VIRTUAL DESKTOP. * `GTK_WIN_POS_MOUSE' This POSITION option will cause the window to center itself under the mouse pointers' current location. Typical uses for this setting is in warning/error/informational dialogs where user interaction is desired. Signals ------- - Signal: void GtkWindow::move_resize (GtkWindow *WINDOW, gint *X, gint *Y, gint WIDTH, gint HEIGHT) - Signal: void GtkWindow::set_focus (GtkWindow *WINDOW, GtkWidget *FOCUS) Functions --------- - Function: guint gtk_window_get_type (void) Returns the `GtkWindow' type identifier. - Function: GtkWidget* gtk_window_new (GtkWindowType TYPE) Create a new `GtkWindow' object. The new widget is returned as a pointer to a `GtkWidget' object. `NULL' is returned on failure. The TYPE can be one of `GTK_WINDOW_TOPLEVEL', `GTK_WINDOW_DIALOG' or, `GTK_WINDOW_POPUP'. The TYPE value determines how this widget will interact with the window manager. - Function: void gtk_window_set_title (GtkWindow *WINDOW, gchar *TITLE) Set the title of this window to the text in the TITLE argument. It is important to not set the fields of the `GtkWindow' structure directly. - 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) Set the position that the window will be at when it is finally drawn to the screen. The POSITION argument effects the the position as described above. - 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: * GtkAcceleratorTable:: The accelerator table object. * GtkAdjustment:: The adjustment object. * GtkGC:: The GC object. * GtkData:: The data object. * GtkStyle:: The style object.  File: gtk.info, Node: GtkAcceleratorTable, Next: GtkAdjustment, Prev: Other Objects, Up: Other Objects The accelerator table object ============================ Description ----------- Functions --------- - Function: GtkAcceleratorTable* gtk_accelerator_table_new (void) - Function: GtkAcceleratorTable* gtk_accelerator_table_find (GtkObject *OBJECT, gchar *SIGNAL_NAME, guchar ACCELERATOR_KEY, guint8 ACCELERATOR_MODS) - Function: GtkAccelerator *gtk_accelerator_table_ref (GtkAcceleratorTable *TABLE) - Function: void gtk_accelerator_table_unref (GtkAcceleratorTable *TABLE) - Function: void gtk_accelerator_table_install (GtkAcceleratorTable *TABLE, GtkObject *OBJECT, gchar *SIGNAL_NAME, guchar ACCELERATOR_KEY, guint8 ACCELERATOR_MODS) - Function: void gtk_accelerator_table_remove (GtkAcceleratorTable *TABLE, GtkObject *OBJECT, gchar *SIGNAL_NAME) - Function: void gtk_accelerator_table_check (GtkAcceleratorTable *TABLE, guchar ACCELERATOR_KEY, guint8 ACCELERATOR_MODS) - Function: void gtk_accelerator_table_set_mod_mask (GtkAcceleratorTable *TABLE, guint8 MODIFIER_MASK)  File: gtk.info, Node: GtkAdjustment, Next: GtkGC, Prev: GtkAcceleratorTable, Up: Other Objects The adjustment object ===================== Description ----------- Functions --------- - Function: guint gtk_adjustment_get_type (void) Returns the `GtkAdjustment' type identifier. - Function: GtkObject* gtk_adjustment_new (gfloat VALUE, gfloat LOWER, gfloat UPPER, gfloat STEP_INCREMENT, gfloat PAGE_INCREMENT, gfloat PAGE_SIZE) - Function: GtkGtkAdjustment* GTK_ADJUSTMENT (gpointer OBJ) Cast a generic pointer to `GtkGtkAdjustment*'. *Note Standard Macros::, for more info. - Function: GtkGtkAdjustmentClass* GTK_ADJUSTMENT_CLASS (gpointer CLASS) Cast a generic pointer to `GtkGtkAdjustmentClass*'. *Note Standard Macros::, for more info. - Function: gint GTK_IS_ADJUSTMENT (gpointer OBJ) Determine if a generic pointer refers to a `GtkGtkAdjustment' object. *Note Standard Macros::, for more info.  File: gtk.info, Node: GtkGC, Next: GtkData, Prev: GtkAdjustment, Up: Other Objects The GC object ============= Description ----------- Functions --------- - Function: GdkGC* gtk_gc_get (gint DEPTH, GdkColormap *COLORMAP, GdkGCValues *VALUES, GdkGCValuesMask VALUES_MASK) - Function: void gtk_gc_release (GdkGC *GC)  File: gtk.info, Node: GtkData, Next: GtkStyle, Prev: GtkGC, Up: Other Objects The data object =============== Description ----------- Functions --------- - Function: guint gtk_data_get_type (void) Returns the `GtkData' type identifier. - Function: GtkData* GTK_DATA (gpointer OBJ) Cast a generic pointer to `GtkData*'. *Note Standard Macros::, for more info. - Function: GtkDataClass* GTK_DATA_CLASS (gpointer CLASS) Cast a generic pointer to `GtkDataClass*'. *Note Standard Macros::, for more info. - Function: gint GTK_IS_DATA (gpointer OBJ) Determine if a generic pointer refers to a `GtkData' object. *Note Standard Macros::, for more info.  File: gtk.info, Node: GtkStyle, Prev: GtkData, Up: Other Objects The style object ================ Description ----------- Functions ---------  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. * Customization:: Customizing the library. * 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: Customization, Prev: Miscellaneous, Up: Miscellaneous Initializing and exiting GTK ============================ Initializing ------------ Before any GTK functions can be utilized the library must be initialized. This can be accomplished by calling the `gtk_init' function. The arguments you pass to this function should be the same arguments that were passed to your application. This function will parse the arguments that it understands and handle initializing the GDK library for you. Exiting ------- Functions --------- - Function: void gtk_init (int *ARGC, char **ARGV) Function to initialize GTK and GDK for you. This function will remove any command line arguments from ARGC and ARGV that it understands. int main (int argc, char *argv[]) { ...Any local variables or non GTK/GDK initialization /* Initialize GTK. */ gtk_init(&argc, &argc); } - Function: void gtk_exit (int ERROR_CODE) Exit GTK and perform any necessary cleanup. `gtk_exit' will call the systems `exit' function passing ERROR_CODE as the parameter. - Function: gint gtk_events_pending (void) Returns the number of events pending on the event queue. - Function: void gtk_main (void) - Function: guint gtk_main_level (void) - Function: void gtk_main_quit (void) A call to this function will cause the `gtk_main' function to exit, thereby allowing your application to exit.  File: gtk.info, Node: Customization, Next: Menu Factories, Prev: Initialization and exit, Up: Miscellaneous Customization of the library ============================ Description ----------- Like other X-windows applications the GTK library provides a way for the user and application programmer to change the colors of just about any widget. You can also specify what pixmap should be tiled onto the background of some widgets. All this is handled through a similar method as in the standard X-windows environment, through the use of 'rc' files. The format and functions available in these files is discussed below. Functions --------- The following functions are available to handle the rc files. - Function: void gtk_rc_parse (char *FILENAME) This function will parse the FILENAME that is passed to it as its argument. It will use the style settings for the widget types defined there. - Function: void gtk_rc_init (void) This function will initialize the rc file parser, normally this need not be called directly as the `gtk_rc_parse' function will handle this for you.  File: gtk.info, Node: Menu Factories, Next: Tree Factories, Prev: Customization, 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 ===================== Description -----------  File: gtk.info, Node: Resource Files, Next: Standard Macros, Prev: Tool Tips, Up: Miscellaneous Resource Files ==============  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* GTK_ (gpointer OBJ) Cast a generic pointer to `Gtk*'. 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: GtkClass* GTK__CLASS (gpointer CLASS) Cast a generic pointer to `GtkClass*'. Like `GTK_', this function is, in reality, a macro. - Function: gint GTK_IS_ (gpointer OBJ) Determine if a generic pointer refers to a `Gtk' 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 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 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 `GtkObject''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 ****************