+2001-09-07 Havoc Pennington <hp@pobox.com>
+
+ * gtk/gtkmain.c: move some docs inline
+
2001-09-07 Havoc Pennington <hp@pobox.com>
* gtk/gtk.h: tsk tsk, jrb broke the build
+2001-09-07 Havoc Pennington <hp@pobox.com>
+
+ * gtk/gtkmain.c: move some docs inline
+
2001-09-07 Havoc Pennington <hp@pobox.com>
* gtk/gtk.h: tsk tsk, jrb broke the build
+2001-09-07 Havoc Pennington <hp@pobox.com>
+
+ * gtk/gtkmain.c: move some docs inline
+
2001-09-07 Havoc Pennington <hp@pobox.com>
* gtk/gtk.h: tsk tsk, jrb broke the build
+2001-09-07 Havoc Pennington <hp@pobox.com>
+
+ * gtk/gtkmain.c: move some docs inline
+
2001-09-07 Havoc Pennington <hp@pobox.com>
* gtk/gtk.h: tsk tsk, jrb broke the build
+2001-09-07 Havoc Pennington <hp@pobox.com>
+
+ * gtk/gtkmain.c: move some docs inline
+
2001-09-07 Havoc Pennington <hp@pobox.com>
* gtk/gtk.h: tsk tsk, jrb broke the build
+2001-09-07 Havoc Pennington <hp@pobox.com>
+
+ * gtk/gtkmain.c: move some docs inline
+
2001-09-07 Havoc Pennington <hp@pobox.com>
* gtk/gtk.h: tsk tsk, jrb broke the build
+2001-09-07 Havoc Pennington <hp@pobox.com>
+
+ * gtk/gtkmain.c: move some docs inline
+
2001-09-07 Havoc Pennington <hp@pobox.com>
* gtk/gtk.h: tsk tsk, jrb broke the build
+2001-09-08 Havoc Pennington <hp@pobox.com>
+
+ * gtk/gtk-docs.sgml: remove CellRendererTextPixbuf
+
+ * gtk/resources.sgml: add section on mailing lists, bugzilla, etc.
+
+ * gtk/tmpl/gtkaccelgroup.sgml: add long description
+
+ * gtk/gtk-sections.txt: reorder accel group section; probably need
+ to delete most of it
+
+ * gtk/tmpl/gtkmain.sgml: Clean it up a little bit
+
+ * gtk/gtk-docs.sgml: rearrange the list of "core/misc" sections so
+ that useful things are near the top and stupid junk is near the
+ bottom.
+
+ * gtk/tmpl/gtkfeatures.sgml: fix/finish this section
+
+ * gtk/gtk-docs.sgml: create a separate section for
+ overview/tutorial material and special notes, and put the
+ reference docs for the "misc non-widget" stuff into its own
+ section.
+
+ * gtk/compiling.sgml: write this section
+
+ * gtk/gtk-docs.sgml: The intro section weirdly had two paragraphs
+ that said the same thing. Delete one of them.
+
Tue Sep 4 01:33:51 2001 Owen Taylor <otaylor@redhat.com>
* gtk/gtk-docs.sgml: Remove references to a couple
</refnamediv>
<refsect1>
-<title>Compiling GTK+ Applications</title>
+<title>Compiling GTK+ Applications on UNIX</title>
<para>
+To compile a GTK+ application, you need to tell the compiler where to
+find the GTK+ header files and libraries. This is done with the
+<literal>pkg-config</literal> utility.
+</para>
+<para>
+The following interactive shell session demonstrates how
+<literal>pkg-config</literal> is used:
+<programlisting>
+$ pkg-config --cflags gtk+-2.0
+ -I/usr/include/gtk-2.0 -I/usr/lib/gtk-2.0/include -I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include -I/usr/include/pango-1.0 -I/usr/X11R6/include -I/usr/include/freetype2 -I/usr/include/atk-1.0
+$ pkg-config --libs gtk+-2.0
+ -L/usr/lib -L/usr/X11R6/lib -lgtk-x11-1.3 -lgdk-x11-1.3 -lXi -lgdk_pixbuf-1.3 -lm -lpangox -lpangoxft -lXft -lXrender -lXext -lX11 -lfreetype -lpango -latk -lgobject-1.3 -lgmodule-1.3 -ldl -lglib-1.3
+</programlisting>
+</para>
+<para>
+The simplest way to compile a program is to use the "backticks"
+feature of the shell. If you enclose a command in backticks
+(<emphasis>not single quotes</emphasis>), then its output will be
+substituted into the command line before execution. So to compile
+a GTK+ Hello, World, you would type the following:
+<programlisting>
+$ cc `pkg-config --cflags --libs gtk+-2.0` hello.c -o hello
+</programlisting>
+</para>
+<para>
+To compile a GTK+ program for the framebuffer, use the
+"gtk+-linux-fb-2.0" package name instead of "gtk+-2.0":
+<programlisting>
+$ cc `pkg-config --cflags --libs gtk+-linux-fb-2.0` hello.c -o hello
+</programlisting>
</para>
</refsect1>
<!entity gtk-GtkCellRenderer SYSTEM "sgml/gtkcellrenderer.sgml">
<!entity gtk-GtkCellRendererPixbuf SYSTEM "sgml/gtkcellrendererpixbuf.sgml">
<!entity gtk-GtkCellRendererText SYSTEM "sgml/gtkcellrenderertext.sgml">
-<!entity gtk-GtkCellRendererTextPixbuf SYSTEM "sgml/gtkcellrenderertextpixbuf.sgml">
<!entity gtk-GtkCellRendererToggle SYSTEM "sgml/gtkcellrenderertoggle.sgml">
<!entity gtk-GtkListStore SYSTEM "sgml/gtkliststore.sgml">
<!entity GtkVButtonBox SYSTEM "sgml/gtkvbbox.sgml">
<!entity gtk-TextWidget SYSTEM "text_widget.sgml">
<!entity gtk-TreeWidget SYSTEM "tree_widget.sgml">
<!entity gtk-Compiling SYSTEM "compiling.sgml">
+<!entity gtk-Resources SYSTEM "resources.sgml">
<!entity gtk-Windows SYSTEM "windows.sgml">
<!entity gtk-Framebuffer SYSTEM "framebuffer.sgml">
]>
</bookinfo>
<chapter id="gtk">
- <title>GTK+ </title>
+ <title>GTK+ Overview</title>
<para>
-GTK+ is a multi-platform open source GUI Toolkit. Everything about
-GTK+ from the object-oriented design to the Free Software LGPL
-licensing allows you to code your project with the most freedom
-possible. You can develop open software, free software, or even
-commercial non-free software without having to spend a dime for
-licenses or royalties.
- </para>
- <para>
-GTK+ is a set of libraries to create graphical user interfaces. It
-works on many Unix-like platforms, Windows, and on framebuffer
+GTK+ is a library for creating graphical user interfaces. It
+works on many UNIX-like platforms, Windows, and on framebuffer
devices. GTK+ is released under the GNU Library General Public License
(GNU LGPL), which allows for flexible licensing of client
applications. GTK+ has a C-based object-oriented architecture that
TOM, Ada95, Free Pascal, and Eiffel.
</para>
<para>
-GTK+ consists of the following component libraries:
+GTK+ depends on the following libraries:
<variablelist>
<varlistentry>
<term>GLib</term>
<listitem><para>
-Provides many useful data types, macros, type conversions,
-string utilities and a lexical scanner. Includes Win32 support.
+A general-purpose utility library, not specific to graphical user interfaces.
+GLib provides many useful data types, macros, type conversions,
+string utilities, file utilities, a main loop abstraction, and so on.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>Pango</term>
+<listitem><para>
+
+Pango is a library for internationalized text handling. It centers
+around the #PangoLayout object, representing a paragraph of text.
+Pango provides the engine for #GtkTextView, #GtkLabel, #GtkEntry, and
+other widgets that display text.
+
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>ATK</term>
+<listitem><para>
+
+ATK is the Accessibility Toolkit. It provides a set of generic
+interfaces allowing accessibility technologies to interact with a
+graphical user interface. For example, a screen reader uses ATK to
+discover the text in an interface and read it to blind users. GTK+
+widgets have built-in support for accessibility using the ATK
+framework.
+
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>GdkPixbuf</term>
+<listitem><para>
+This is a small library which allows you to create #GdkPixbuf
+("pixel buffer") objects from image data or image files.
+Use a #GdkPixbuf in combination with #GtkImage to display images.
</para></listitem>
</varlistentry>
<varlistentry>
<term>GDK</term>
<listitem><para>
-A wrapper for low-level windowing functions.
+GDK is the abstraction layer that allows GTK+ to support multiple
+windowing systems. GDK provides drawing and window system facilities
+on X11, Windows, and the Linux framebuffer device.
</para></listitem>
</varlistentry>
<varlistentry>
<term>GTK+</term>
<listitem><para>
-An advanced widget set.
+
+The GTK+ library itself contains <firstterm>widgets</firstterm>,
+that is, GUI components such as #GtkButton or #GtkTextView.
+
</para></listitem>
</varlistentry>
</variablelist>
</para>
>k-Compiling;
+ >k-Resources;
>k-Windows;
>k-Framebuffer;
+
+ </chapter>
+
+
+ <chapter id="gtkbase" role="no-toc">
+ <title>GTK+ Core Reference</title>
+
>k-General;
- >k-Feature-Test-Macros;
- >k-Graphics-Contexts;
- >k-Styles;
-<!-- >k-Themes; -->
- >k-Resource-Files;
>k-Keyboard-Accelerators;
- >k-Selections;
>k-Clipboards;
>k-Drag-and-Drop;
- >k-Signals;
>k-Stock-Items;
>k-Themeable-Stock-Images;
- >k-Types;
+ >k-Resource-Files;
>k-Bindings;
>k-Standard-Enumerations;
+ >k-Graphics-Contexts;
+ >k-Styles;
+ >k-Selections;
+ >k-Feature-Test-Macros;
+ >k-Signals;
+ >k-Types;
+<!-- >k-Themes; -->
</chapter>
>k-GtkCellRenderer;
>k-GtkCellRendererPixbuf;
>k-GtkCellRendererText;
- >k-GtkCellRendererTextPixbuf;
>k-GtkCellRendererToggle;
>k-GtkListStore;
</sect1>
GTK_IS_CELL_RENDERER_TEXT_CLASS
</SECTION>
-<SECTION>
-<FILE>gtkcellrenderertextpixbuf</FILE>
-<TITLE>GtkCellRendererTextPixbuf</TITLE>
-GtkCellRendererTextPixbuf
-gtk_cell_renderer_text_pixbuf_new
-<SUBSECTION Standard>
-GTK_CELL_RENDERER_TEXT_PIXBUF
-GTK_IS_CELL_RENDERER_TEXT_PIXBUF
-GTK_TYPE_CELL_RENDERER_TEXT_PIXBUF
-gtk_cell_renderer_text_pixbuf_get_type
-GTK_CELL_RENDERER_TEXT_PIXBUF_CLASS
-GTK_IS_CELL_RENDERER_TEXT_PIXBUF_CLASS
-</SECTION>
-
<SECTION>
<FILE>gtkcellrenderertoggle</FILE>
<TITLE>GtkCellRendererToggle</TITLE>
<FILE>gtkaccelgroup</FILE>
<TITLE>Keyboard Accelerators</TITLE>
GtkAccelGroup
-GtkAccelEntry
gtk_accel_group_new
gtk_accel_group_get_default
gtk_accel_group_ref
gtk_accel_group_unref
gtk_accel_group_activate
gtk_accel_groups_activate
-gtk_accel_group_attach
-gtk_accel_group_detach
gtk_accel_group_lock
gtk_accel_group_unlock
+gtk_accelerator_valid
+gtk_accelerator_parse
+gtk_accelerator_name
+gtk_accelerator_set_default_mod_mask
+gtk_accelerator_get_default_mod_mask
+gtk_accel_group_attach
+gtk_accel_group_detach
gtk_accel_group_get_entry
gtk_accel_group_lock_entry
gtk_accel_group_unlock_entry
gtk_accel_group_create_remove
gtk_accel_groups_from_object
gtk_accel_group_entries_from_object
-gtk_accelerator_valid
-gtk_accelerator_parse
-gtk_accelerator_name
-gtk_accelerator_set_default_mod_mask
-gtk_accelerator_get_default_mod_mask
</SECTION>
<SECTION>
--- /dev/null
+<refentry id="gtk-resources" revision="5 Sept 2001">
+<refmeta>
+<refentrytitle>Mailing lists and bug reports</refentrytitle>
+<manvolnum>3</manvolnum>
+<refmiscinfo>Mailing lists and bug reports</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+<refname>Mailing lists and bug reports</refname>
+<refpurpose>
+Getting help with GTK+
+</refpurpose>
+</refnamediv>
+
+<refsect1>
+<title>Filing a bug report or feature request</title>
+
+<para>
+If you encounter a bug, misfeature, or missing feature in GTK+, please
+file a bug report on http://bugzilla.gnome.org. We'd also appreciate
+reports of incomplete or misleading information in the GTK+
+documentation; file those against the "docs" component of the "gtk+"
+product in Bugzilla.
+</para>
+
+<para>
+Don't hesitate to file a bug report, even if you think we may know
+about it already, or aren't sure of the details. Just give us as much
+information as you have, and if it's already fixed or has already been
+discussed, we'll add a note to that effect in the report.
+</para>
+
+<para>
+The bug tracker should definitely be used for feature requests, it's
+not only for bugs. We track all GTK+ development in bugzilla, so it's
+the way to be sure the GTK+ developers won't forget about an issue.
+</para>
+
+</refsect1>
+
+<refsect1>
+<title>Submitting Patches</title>
+
+<para>
+If you develop a bugfix or enhancement for GTK+, please file that in
+Bugzilla as well. Bugzilla allows you to attach files; please attach a
+patch generated by the "diff" utility, using the "-u" option to make
+the patch more readable. All patches must be offered under the terms
+of the GNU LGPL license, so be sure you are authorized to give us the
+patch under those terms.
+</para>
+
+<para>
+If you want to discuss your patch before or after developing it, mail
+gtk-devel-list@gnome.org. But be sure to file the Bugzilla report as
+well; if the patch is only on the list and not in Bugzilla, it's
+likely to slip through the cracks.
+</para>
+
+</refsect1>
+
+<refsect1>
+<title>Mailing lists</title>
+
+<para>
+There are several mailing lists dedicated to GTK+ and related
+libraries. Discussion of GLib, Pango, and ATK in addition to GTK+
+proper is welcome on these lists. You can subscribe or view the
+archives of these lists on http://mail.gnome.org.
+</para>
+
+<para>
+<variablelist>
+
+<varlistentry>
+<term>gtk-list@gnome.org</term>
+<listitem><para>
+gtk-list covers general GTK+ topics; questions about using GTK+ in programs,
+GTK+ from a user standpoint, announcements of GTK+-related projects
+such as themes or GTK+ modules would all be on-topic. The bulk of the
+traffic consists of GTK+ programming questions.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>gtk-app-devel-list@gnome.org</term> <listitem><para>
+gtk-app-devel-list covers writing applications in GTK+. It's narrower
+in scope than gtk-list, but the two lists overlap quite a
+bit. gtk-app-devel-list is a good place to ask questions about GTK+
+programming. </para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>gtk-devel-list@gnome.org</term>
+<listitem><para>
+gtk-devel-list is for discussion of work on GTK+ itself, it is NOT for
+asking questions about how to use GTK+ in applications. gtk-devel-list
+is appropriate for discussion of patches, bugs, proposed features,
+and so on.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>gtk-i18n-list@gnome.org</term>
+<listitem><para>
+gtk-i18n-list is for discussion of internationalization in GTK+;
+Pango is the main focus of the list. Questions about the details of
+using Pango, and discussion of proposed Pango patches or features, are
+all on topic.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>gtk-doc-list@gnome.org</term>
+<listitem><para>
+gtk-doc-list is for discussion of the gtk-doc documentation system
+(used to document GTK+), and for work on the GTK+ documentation.
+</para></listitem>
+</varlistentry>
+
+</variablelist>
+</para>
+
+</refsect1>
+
+
+</refentry>
@b:
@Returns:
+<!-- ##### STRUCT GtkAccelEntry ##### -->
+<para>
+This is a private struct used by GTK+ internally, don't worry about it.
+</para>
+
+@accel_group:
+@accelerator_key:
+@accelerator_mods:
+@accel_flags:
+@object:
+@signal_id:
+
<!-- ##### ARG GtkAccelLabel:accel-widget ##### -->
<para>
The widget whose accelerators are to be shown by the #GtkAccelLabel.
@arg:
@arg_id:
+<!-- ##### STRUCT GtkCellRendererTextPixbuf ##### -->
+<para>
+
+</para>
+
+@parent:
+
<!-- ##### ARG GtkColorSelection:previous-alpha ##### -->
<para>
@accel_group:
@Returns:
+<!-- ##### FUNCTION gtk_cell_renderer_text_pixbuf_new ##### -->
+<para>
+
+</para>
+
+@Returns:
+
<!-- ##### FUNCTION gtk_clist_construct ##### -->
<para>
Initializes a previously allocated #GtkCList widget for use. This should not
@tree_model:
@iter:
+<!-- ##### FUNCTION gtk_tree_view_column_set_width ##### -->
+<para>
+
+</para>
+
+@tree_column:
+@width:
+@size:
+
<!-- ##### FUNCTION gtk_type_check_class_cast ##### -->
<para>
Given a GtkTypeClass pointer @klass, and a GtkType @cast_type, make
@window:
@Returns:
+<!-- ##### FUNCTION gtk_window_get_resizeable ##### -->
+<para>
+
+</para>
+
+@window:
+@Returns:
+
<!-- ##### FUNCTION gtk_window_set_decorations_hint ##### -->
<para>
@window:
@functions:
+<!-- ##### FUNCTION gtk_window_set_resizeable ##### -->
+<para>
+
+</para>
+
+@window:
+@setting:
+@resizeable:
+
<!-- ##### SECTION Short_Description ##### -->
+global keyboard accelerators (for an entire #GtkWindow)
<!-- ##### SECTION Long_Description ##### -->
<para>
+A #GtkAccelGroup represents a group of keyboard accelerators, attached
+to a toplevel #GtkWindow (with gtk_window_add_accel_group()). Usually
+you won't need to create a #GtkAccelGroup directly; instead, when
+using #GtkItemFactory, GTK+ automatically sets up the accelerators for
+your menus.
+</para>
+<para>
+Note that <firstterm>accelerators</firstterm> are different from
+<firstterm>mnemonics</firstterm>. Accelerators are shortcuts for
+activating a menu item; they appear alongside the menu item they're a
+shortcut for, for example "Ctrl+Q" might appear alongside the "Quit"
+menu item. Mnemonics are shortcuts for GUI elements such as text
+entries or buttons; they appear as underlined characters. See
+gtk_label_new_with_mnemonic(). Menu items can have both accelerators
+and mnemonics, of course.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
-
+gtk_label_new_with_mnemonic(), gtk_window_add_accel_group()
</para>
<!-- ##### STRUCT GtkAccelGroup ##### -->
<para>
-
+On opaque data type representing a group of accelerators.
</para>
-<!-- ##### STRUCT GtkAccelEntry ##### -->
-<para>
-
-</para>
-
-@accel_group:
-@accelerator_key:
-@accelerator_mods:
-@accel_flags:
-@object:
-@signal_id:
-
<!-- ##### FUNCTION gtk_accel_group_new ##### -->
<para>
@Returns:
-<!-- ##### FUNCTION gtk_accel_group_attach ##### -->
+<!-- ##### FUNCTION gtk_accel_group_lock ##### -->
<para>
</para>
@accel_group:
-@object:
-<!-- ##### FUNCTION gtk_accel_group_detach ##### -->
+<!-- ##### FUNCTION gtk_accel_group_unlock ##### -->
<para>
</para>
@accel_group:
-@object:
-<!-- ##### FUNCTION gtk_accel_group_lock ##### -->
+<!-- ##### FUNCTION gtk_accelerator_valid ##### -->
+<para>
+
+</para>
+
+@keyval:
+@modifiers:
+@Returns:
+
+
+<!-- ##### FUNCTION gtk_accelerator_parse ##### -->
+<para>
+
+</para>
+
+@accelerator:
+@accelerator_key:
+@accelerator_mods:
+
+
+<!-- ##### FUNCTION gtk_accelerator_name ##### -->
+<para>
+
+</para>
+
+@accelerator_key:
+@accelerator_mods:
+@Returns:
+
+
+<!-- ##### FUNCTION gtk_accelerator_set_default_mod_mask ##### -->
+<para>
+
+</para>
+
+@default_mod_mask:
+
+
+<!-- ##### FUNCTION gtk_accelerator_get_default_mod_mask ##### -->
+<para>
+
+</para>
+
+@Returns:
+
+
+<!-- ##### FUNCTION gtk_accel_group_attach ##### -->
<para>
</para>
@accel_group:
+@object:
-<!-- ##### FUNCTION gtk_accel_group_unlock ##### -->
+<!-- ##### FUNCTION gtk_accel_group_detach ##### -->
<para>
</para>
@accel_group:
+@object:
<!-- ##### FUNCTION gtk_accel_group_get_entry ##### -->
@Returns:
-<!-- ##### FUNCTION gtk_accelerator_valid ##### -->
-<para>
-
-</para>
-
-@keyval:
-@modifiers:
-@Returns:
-
-
-<!-- ##### FUNCTION gtk_accelerator_parse ##### -->
-<para>
-
-</para>
-
-@accelerator:
-@accelerator_key:
-@accelerator_mods:
-
-
-<!-- ##### FUNCTION gtk_accelerator_name ##### -->
-<para>
-
-</para>
-
-@accelerator_key:
-@accelerator_mods:
-@Returns:
-
-
-<!-- ##### FUNCTION gtk_accelerator_set_default_mod_mask ##### -->
-<para>
-
-</para>
-
-@default_mod_mask:
-
-
-<!-- ##### FUNCTION gtk_accelerator_get_default_mod_mask ##### -->
-<para>
-
-</para>
-
-@Returns:
-
-
</para>
-<!-- ##### STRUCT GtkCellRendererTextPixbuf ##### -->
-<para>
-
-</para>
-
-@parent:
-
-<!-- ##### FUNCTION gtk_cell_renderer_text_pixbuf_new ##### -->
-<para>
-
-</para>
-
-@Returns:
-
-
<!-- ##### SECTION Long_Description ##### -->
<para>
-This section describes the variables and functions available to test the
-version of the GTK+ library in use.
-FIXME: probably merge with other general stuff.
+GTK+ provides version information, primarily useful in configure checks
+for builds that have a configure script. Applications will not
+typically use the features described here.
</para>
<!-- ##### SECTION See_Also ##### -->
<!-- ##### VARIABLE gtk_major_version ##### -->
<para>
-The major version number of the GTK+ library.
-(e.g. in GTK+ version 1.2.5 this is 1.)
+The major version number of the GTK+ library. (e.g. in GTK+ version
+1.2.5 this is 1.)
+</para>
+
+<para>
+This variable is in the library, so represents the
+GTK+ library you have linked against. Contrast with the
+#GTK_MAJOR_VERSION macro, which represents the major version of the
+GTK+ headers you have included.
</para>
(e.g. in GTK+ version 1.2.5 this is 2.)
</para>
+<para>
+This variable is in the library, so represents the
+GTK+ library you have linked against. Contrast with the
+#GTK_MINOR_VERSION macro, which represents the minor version of the
+GTK+ headers you have included.
+</para>
+
<!-- ##### VARIABLE gtk_micro_version ##### -->
<para>
</para>
-<!-- ##### VARIABLE gtk_binary_age ##### -->
<para>
+This variable is in the library, so represents the GTK+ library you
+have linked against. Contrast with the #GTK_MICRO_VERSION macro, which
+represents the micro version of the GTK+ headers you have included.
+</para>
+
+<!-- ##### VARIABLE gtk_binary_age ##### -->
+<para>
+This is the binary age passed to libtool. If "libtool" means nothing
+to you, don't worry about it. ;-)
</para>
<!-- ##### VARIABLE gtk_interface_age ##### -->
<para>
-
+This is the interface age passed to libtool. If "libtool" means nothing
+to you, don't worry about it. ;-)
</para>
<!-- ##### FUNCTION gtk_check_version ##### -->
<para>
-Checks that the GTK+ library in use is compatable with the given version.
+Checks that the GTK+ library in use is equal to the given
+version. Primarily useful to compare the header file version
+(from #GTK_MAJOR_VERSION, #GTK_MINOR_VERSION, #GTK_MICRO_VERSION)
+the the runtime library version. This should only be done
+in the build for your application, to check that the user's libraries
+and header files are the same. Applications should not do this
+when deployed, because it's OK for applications to use a different
+micro version of GTK+ than the one they were compiled against.
</para>
@required_major: the required major version.
@required_minor: the required major version.
@required_micro: the required major version.
-@Returns: NULL if the GTK+ library is compatable with the given version, or
+@Returns: NULL if the GTK+ library is compatible with the given version, or
a string describing the version mismatch.
<!-- ##### MACRO GTK_MAJOR_VERSION ##### -->
<para>
-
+Like #gtk_major_version, but from the headers used at
+application compile time, rather than from the library linked against
+at application run time.
</para>
<!-- ##### MACRO GTK_MINOR_VERSION ##### -->
<para>
-
+Like #gtk_minor_version, but from the headers used at
+application compile time, rather than from the library linked against
+at application run time.
</para>
<!-- ##### MACRO GTK_MICRO_VERSION ##### -->
<para>
-
+Like #gtk_micro_version, but from the headers used at
+application compile time, rather than from the library linked against
+at application run time.
</para>
<!-- ##### MACRO GTK_BINARY_AGE ##### -->
<para>
-
+Like #gtk_binary_age, but from the headers used at
+application compile time, rather than from the library linked against
+at application run time.
</para>
<!-- ##### MACRO GTK_INTERFACE_AGE ##### -->
<para>
-
+Like #gtk_interface_age, but from the headers used at
+application compile time, rather than from the library linked against
+at application run time.
</para>
<!-- ##### MACRO GTK_CHECK_VERSION ##### -->
<para>
-
+Returns %TRUE if the version of the GTK+ header files is the same
+as the passed-in version.
</para>
-@major:
-@minor:
-@micro:
+@major: major version (first number in 1.2.5)
+@minor: minor version (second number in 1.2.5)
+@micro: micro version (third number in 1.2.5)
<!-- ##### SECTION Title ##### -->
-General
+Main loop and Events
<!-- ##### SECTION Short_Description ##### -->
-Mainloop and event handling
+Library initialization, main event loop, and events
<!-- ##### SECTION Long_Description ##### -->
+
+<para>
+Before using GTK+, you need to initialize it; initialization connects
+to the window system display, and parses some standard command line
+arguments. The gtk_init() function initializes GTK+. gtk_init() exits
+the application if errors occur; to avoid this, use gtk_init_check().
+gtk_init_check() allows you to recover from a failed GTK+
+initialization - you might start up your application in text mode instead.
+</para>
+
<para>
-GTK uses an event oriented programming model. While conventional C programs
-have control over the program flow all the time this does not apply to
-applications written using GTK. Instead you set up some objects and
-register some functions (<quote>callbacks</quote>) to be called whenever
-some event occurs and give control to the GTK mainloop (e.g. by calling
-gtk_main).
+If your application supports internationalization, gtk_set_locale()
+should be called prior to gtk_init().
+</para>
+
+<para>
+Like all GUI toolkits, GTK+ uses an event-driven programming
+model. When the user is doing nothing, GTK+ sits in the
+<firstterm>main loop</firstterm> and waits for input. If the user
+performs some action - say, a mouse click - then the main loop "wakes
+up" and delivers an event to GTK+. GTK+ forwards the event to one or
+more widgets.
+</para>
+
+<para>
+When widgets receive an event, they frequently emit one or more
+<firstterm>signals</firstterm>. Signals notify your program that
+"something interesting happened" by invoking functions you've
+connected to the signal with g_signal_connect(). Functions connected
+to a signal are often termed <firstterm>callbacks</firstterm>.
+</para>
+
+<para>
+When your callbacks are invoked, you would typically take some action
+- for example, when an Open button is clicked you might display a
+#GtkFileSelectionDialog. After a callback finishes, GTK+ will return
+to the main loop and await more user input.
</para>
<example>
...
/* Show the application window */
- gtk_widget_showall (mainwin);
+ gtk_widget_show_all (mainwin);
- /* Let the user interact with our application */
+ /* Enter the main event loop, and wait for user interaction */
gtk_main ();
/* The user lost interest */
- gtk_exit (0);
+ return 0;
}
</programlisting>
</example>
-<!-- ##### SECTION See_Also ##### -->
<para>
+It's OK to use the GLib main loop directly instead of gtk_main(),
+though it involves slightly more typing. See #GMainLoop in the GLib
+documentation.
</para>
-<!-- ##### FUNCTION gtk_set_locale ##### -->
+<!-- ##### SECTION See_Also ##### -->
<para>
-Sets the current locale according to the program environment. This is the
-same as calling the libc function setlocale(LC_ALL, "") but also takes
-care of the locale specific setup of the windowing system used by GDK.
+See the GLib manual, especially #GMainLoop and signal-related
+functions such as g_signal_connect().
</para>
-<para>
-You should call this function before <function>gtk_init</function> to
-support internationalization of your GTK+ applications.
+<!-- ##### FUNCTION gtk_set_locale ##### -->
+
+<para>
</para>
-@Returns: A string corresponding to the locale set.
+@Returns:
<!-- ##### FUNCTION gtk_get_default_language ##### -->
Adds a new #GtkMenuItem to the end of the menu's item list.
</para>
-<!-- # Unused Parameters # -->
@menu: a #GtkMenu.
@child: The #GtkMenuItem to add.
+<!-- # Unused Parameters # -->
@m:
@c:
Adds a new #GtkMenuItem to the beginning of the menu's item list.
</para>
-<!-- # Unused Parameters # -->
@menu_child:
+<!-- # Unused Parameters # -->
@m:
@c:
@menu: a #GtkMenu.
indicated by @position.
</para>
-<!-- # Unused Parameters # -->
@menu: a #GtkMenu.
@child: The #GtkMenuItem to add.
@pos:
+<!-- # Unused Parameters # -->
@position: The position in the item list where @child is added.
Positions are numbered from 0 to n-1.
@xalign:
@property_changed_signal:
@spacing:
+@fixed_width:
@width:
@requested_width:
@min_width:
@max_width:
-@displayed_width:
@drag_x:
@drag_y:
@title:
</para>
+@GTK_TREE_VIEW_COLUMN_GROW_ONLY:
@GTK_TREE_VIEW_COLUMN_RESIZABLE:
@GTK_TREE_VIEW_COLUMN_AUTOSIZE:
@GTK_TREE_VIEW_COLUMN_FIXED:
@Returns:
-<!-- ##### FUNCTION gtk_tree_view_column_set_width ##### -->
-<para>
-
-</para>
-
-@tree_column:
-@width:
-<!-- # Unused Parameters # -->
-@size:
-
-
<!-- ##### FUNCTION gtk_tree_view_column_set_min_width ##### -->
<para>
it's larger
-<!-- ##### FUNCTION gtk_window_set_resizeable ##### -->
-<para>
-
-</para>
-
-@window:
-@setting:
-<!-- # Unused Parameters # -->
-@resizeable:
-
-
-<!-- ##### FUNCTION gtk_window_get_resizeable ##### -->
-<para>
-
-</para>
-
-@window:
-@Returns:
-
-
<!-- ##### FUNCTION gtk_window_add_accel_group ##### -->
<para>
gdk_exit (errorcode);
}
+
+/**
+ * gtk_set_locale:
+ *
+ *
+ * Initializes internationalization support for GTK+. You
+ * should call this function before gtk_init() if your application
+ * supports internationalization.
+ *
+ * (In gory detail - sets the current locale according to the
+ * program environment. This is the same as calling the libc function
+ * setlocale (LC_ALL, "") but also takes care of the locale specific
+ * setup of the windowing system used by GDK.)
+ *
+ * Return value: a string corresponding to the locale set, as with the C library function setlocale()
+ **/
gchar*
gtk_set_locale (void)
{
projects / ~andy / gtk / commitdiff