+2002-01-01 Havoc Pennington <hp@pobox.com>
+
+ * docs/README.linux-fb: note that this file is obsolete
+
+ * docs/Changes-2.0.txt, docs/Changes-1.2.txt: Add notes to these
+ files that they should not be edited and look in the reference
+ manual instead. Probably these files should just be replaced by
+ the note, and their main contents deleted.
+
+ * gtk/gtktextview.c: docs
+
+ * gtk/gtktextmark.c: docs
+
+ * gtk/gtktextchild.c: docs
+
+ * gtk/gtktextbuffer.c: docs stuff
+
+ * gtk/gtkclipboard.c (gtk_clipboard_get): fool with docs to maybe
+ give people more leads in sorting out PRIMARY vs. CLIPBOARD
+
2002-01-01 Tor Lillqvist <tml@iki.fi>
* demos/Makefile.am (test-inline-pixbufs.h): Append EXEEXT to
+2002-01-01 Havoc Pennington <hp@pobox.com>
+
+ * docs/README.linux-fb: note that this file is obsolete
+
+ * docs/Changes-2.0.txt, docs/Changes-1.2.txt: Add notes to these
+ files that they should not be edited and look in the reference
+ manual instead. Probably these files should just be replaced by
+ the note, and their main contents deleted.
+
+ * gtk/gtktextview.c: docs
+
+ * gtk/gtktextmark.c: docs
+
+ * gtk/gtktextchild.c: docs
+
+ * gtk/gtktextbuffer.c: docs stuff
+
+ * gtk/gtkclipboard.c (gtk_clipboard_get): fool with docs to maybe
+ give people more leads in sorting out PRIMARY vs. CLIPBOARD
+
2002-01-01 Tor Lillqvist <tml@iki.fi>
* demos/Makefile.am (test-inline-pixbufs.h): Append EXEEXT to
+2002-01-01 Havoc Pennington <hp@pobox.com>
+
+ * docs/README.linux-fb: note that this file is obsolete
+
+ * docs/Changes-2.0.txt, docs/Changes-1.2.txt: Add notes to these
+ files that they should not be edited and look in the reference
+ manual instead. Probably these files should just be replaced by
+ the note, and their main contents deleted.
+
+ * gtk/gtktextview.c: docs
+
+ * gtk/gtktextmark.c: docs
+
+ * gtk/gtktextchild.c: docs
+
+ * gtk/gtktextbuffer.c: docs stuff
+
+ * gtk/gtkclipboard.c (gtk_clipboard_get): fool with docs to maybe
+ give people more leads in sorting out PRIMARY vs. CLIPBOARD
+
2002-01-01 Tor Lillqvist <tml@iki.fi>
* demos/Makefile.am (test-inline-pixbufs.h): Append EXEEXT to
+2002-01-01 Havoc Pennington <hp@pobox.com>
+
+ * docs/README.linux-fb: note that this file is obsolete
+
+ * docs/Changes-2.0.txt, docs/Changes-1.2.txt: Add notes to these
+ files that they should not be edited and look in the reference
+ manual instead. Probably these files should just be replaced by
+ the note, and their main contents deleted.
+
+ * gtk/gtktextview.c: docs
+
+ * gtk/gtktextmark.c: docs
+
+ * gtk/gtktextchild.c: docs
+
+ * gtk/gtktextbuffer.c: docs stuff
+
+ * gtk/gtkclipboard.c (gtk_clipboard_get): fool with docs to maybe
+ give people more leads in sorting out PRIMARY vs. CLIPBOARD
+
2002-01-01 Tor Lillqvist <tml@iki.fi>
* demos/Makefile.am (test-inline-pixbufs.h): Append EXEEXT to
+2002-01-01 Havoc Pennington <hp@pobox.com>
+
+ * docs/README.linux-fb: note that this file is obsolete
+
+ * docs/Changes-2.0.txt, docs/Changes-1.2.txt: Add notes to these
+ files that they should not be edited and look in the reference
+ manual instead. Probably these files should just be replaced by
+ the note, and their main contents deleted.
+
+ * gtk/gtktextview.c: docs
+
+ * gtk/gtktextmark.c: docs
+
+ * gtk/gtktextchild.c: docs
+
+ * gtk/gtktextbuffer.c: docs stuff
+
+ * gtk/gtkclipboard.c (gtk_clipboard_get): fool with docs to maybe
+ give people more leads in sorting out PRIMARY vs. CLIPBOARD
+
2002-01-01 Tor Lillqvist <tml@iki.fi>
* demos/Makefile.am (test-inline-pixbufs.h): Append EXEEXT to
+2002-01-01 Havoc Pennington <hp@pobox.com>
+
+ * docs/README.linux-fb: note that this file is obsolete
+
+ * docs/Changes-2.0.txt, docs/Changes-1.2.txt: Add notes to these
+ files that they should not be edited and look in the reference
+ manual instead. Probably these files should just be replaced by
+ the note, and their main contents deleted.
+
+ * gtk/gtktextview.c: docs
+
+ * gtk/gtktextmark.c: docs
+
+ * gtk/gtktextchild.c: docs
+
+ * gtk/gtktextbuffer.c: docs stuff
+
+ * gtk/gtkclipboard.c (gtk_clipboard_get): fool with docs to maybe
+ give people more leads in sorting out PRIMARY vs. CLIPBOARD
+
2002-01-01 Tor Lillqvist <tml@iki.fi>
* demos/Makefile.am (test-inline-pixbufs.h): Append EXEEXT to
+2002-01-01 Havoc Pennington <hp@pobox.com>
+
+ * docs/README.linux-fb: note that this file is obsolete
+
+ * docs/Changes-2.0.txt, docs/Changes-1.2.txt: Add notes to these
+ files that they should not be edited and look in the reference
+ manual instead. Probably these files should just be replaced by
+ the note, and their main contents deleted.
+
+ * gtk/gtktextview.c: docs
+
+ * gtk/gtktextmark.c: docs
+
+ * gtk/gtktextchild.c: docs
+
+ * gtk/gtktextbuffer.c: docs stuff
+
+ * gtk/gtkclipboard.c (gtk_clipboard_get): fool with docs to maybe
+ give people more leads in sorting out PRIMARY vs. CLIPBOARD
+
2002-01-01 Tor Lillqvist <tml@iki.fi>
* demos/Makefile.am (test-inline-pixbufs.h): Append EXEEXT to
+
+
+DON'T EDIT THIS FILE - changes are now maintained in the reference
+manual, see docs/reference/gtk/changes-*.sgml. Also, when adding a
+change to the manual, you should amend the docs for all
+newly-deprecated features to point to the replacement for that
+feature, and be sure the GTK_DISABLE_DEPRECATED guards are in place in
+the header files. Be sure to add a note to the docs for EACH
+deprecated function; don't just do the changes-*.sgml change.
+
+
+
Incompatible Changes from GTK+-1.0 to GTK+-1.2:
* GtkAcceleratorTable has been replaced with GtkAccelGroup
which returns the requisition of the given widget, modified
by calls to gtk_widget_set_usize().
+
+
+DON'T EDIT THIS FILE - changes are now maintained in the reference
+manual, see docs/reference/gtk/changes-*.sgml. Also, when adding a
+change to the manual, you should amend the docs for all
+newly-deprecated features to point to the replacement for that
+feature, and be sure the GTK_DISABLE_DEPRECATED guards are in place in
+the header files. Be sure to add a note to the docs for EACH
+deprecated function; don't just do the changes-*.sgml change.
+
+
+
+DON'T EDIT THIS FILE - changes are now maintained in the reference
+manual, see docs/reference/gtk/changes-*.sgml. Also, when adding a
+change to the manual, you should amend the docs for all
+newly-deprecated features to point to the replacement for that
+feature, and be sure the GTK_DISABLE_DEPRECATED guards are in place in
+the header files. Be sure to add a note to the docs for EACH
+deprecated function; don't just do the changes-*.sgml change.
+
+
+
+
+
Incompatible Changes from GTK+-1.2 to GTK+-2.0:
* gtk_container_get_toplevels() was removed and replaced with
- The rectangle passed in is the bounding box, instead of
the rectangle used in the gdk_draw_rectangle() call, so it is
no longer necessary to subtract 1 from the width and height.
+
+
+
+DON'T EDIT THIS FILE - changes are now maintained in the reference
+manual, see docs/reference/gtk/changes-*.sgml. Also, when adding a
+change to the manual, you should amend the docs for all
+newly-deprecated features to point to the replacement for that
+feature, and be sure the GTK_DISABLE_DEPRECATED guards are in place in
+the header files. Be sure to add a note to the docs for EACH
+deprecated function; don't just do the changes-*.sgml change.
+
+
+
+
+THIS FILE IS OBSOLETE - use docs/reference/gtk/framebuffer.sgml
+
+
+
+
+
+
+
About GtkFB:
------------
The linux-fb port of Gtk+, also known as GtkFB is an implementation of
+2002-01-01 Havoc Pennington <hp@pobox.com>
+
+ * gtk/framebuffer.sgml: move README.linux-fb in here
+
+ * gtk/tmpl/gtkpreview.sgml: explain what to use instead
+
+ * gtk/tmpl/gtkseparator.sgml: typo fix
+
+ * gtk/tmpl/gtkstock.sgml: add some overview docs
+
+ * gtk/Makefile.am (content_files): add new files
+
+ * gtk/changes-1.2.sgml: move Changes-1.2.txt in here
+
+ * gtk/changes-2.0.sgml: move Changes-2.0.txt in here
+
+ * gdk/tmpl/threads.sgml: mention gdk_threads_init() in the
+ overview docs, copy in the examples from the FAQ
+
+ * gtk/gtk-docs.sgml: change DTD to 3.1, and add
+ question_index.sgml and changes-1.2, changes-2.0
+
+ * gtk/tmpl/gtkdrawingarea.sgml: fixups to reflect 2.0 changes
+
+ * gtk/question_index.sgml: new section with question-based
+ index of the manual
+
+ * gtk/text_widget.sgml: fix some cross-references
+
2002-01-01 Havoc Pennington <hp@pobox.com>
* gtk/tmpl/gtktexttag.sgml: docs updates, mention that invisible
and on the thread-safe GLib main loop.
</para>
<para>
-You must call g_thread_init() before executing any other GTK+ or GDK
-functions in a threaded GTK+ program.
+GLib is completely thread safe (all global data is automatically
+locked), but individual data structure instances are not automatically
+locked for performance reasons. So e.g. you must coordinate
+accesses to the same #GHashTable from multiple threads.
+</para>
+<para>
+GTK+ is "thread aware" but not thread safe — it provides a
+global lock controlled by gdk_threads_enter()/gdk_threads_leave()
+which protects all use of GTK+. That is, only one thread can use GTK+
+at any given time.
+</para>
+<para>
+You must call g_thread_init() and gdk_threads_init() before executing
+any other GTK+ or GDK functions in a threaded GTK+ program.
</para>
<para>
Idles, timeouts, and input functions are executed outside
a signal handler with a gdk_threads_enter()/gdk_threads_leave() pair.
</para>
+<para>A minimal main program for a threaded GTK+ application
+looks like:</para>
+
+<para>
+<programlisting role="C">
+int
+main (int argc, char *argv[])
+{
+ GtkWidget *window;
+
+ g_thread_init (NULL);
+ gdk_threads_init ();
+ gtk_init (&argc, &argv);
+
+ window = create_window ();
+ gtk_widget_show (window);
+
+ gdk_threads_enter ();
+ gtk_main ();
+ gdk_threads_leave ();
+
+ return 0;
+}
+</programlisting>
+</para>
+
+<para>
+Callbacks require a bit of attention. Callbacks from GTK+ signals
+are made within the GTK+ lock. However callbacks from GLib (timeouts,
+IO callbacks, and idle functions) are made outside of the GTK+
+lock. So, within a signal handler you do not need to call
+gdk_threads_enter(), but within the other types of callbacks, you
+do.
+</para>
+
+<para>Erik Mouw contributed the following code example to
+illustrate how to use threads within GTK+ programs.
+</para>
+
+<para>
+<programlisting role="C">
+/*-------------------------------------------------------------------------
+ * Filename: gtk-thread.c
+ * Version: 0.99.1
+ * Copyright: Copyright (C) 1999, Erik Mouw
+ * Author: Erik Mouw <J.A.K.Mouw@its.tudelft.nl>
+ * Description: GTK threads example.
+ * Created at: Sun Oct 17 21:27:09 1999
+ * Modified by: Erik Mouw <J.A.K.Mouw@its.tudelft.nl>
+ * Modified at: Sun Oct 24 17:21:41 1999
+ *-----------------------------------------------------------------------*/
+/*
+ * Compile with:
+ *
+ * cc -o gtk-thread gtk-thread.c `gtk-config --cflags --libs gthread`
+ *
+ * Thanks to Sebastian Wilhelmi and Owen Taylor for pointing out some
+ * bugs.
+ *
+ */
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <unistd.h>
+#include <time.h>
+#include <gtk/gtk.h>
+#include <glib.h>
+#include <pthread.h>
+
+#define YES_IT_IS (1)
+#define NO_IT_IS_NOT (0)
+
+typedef struct
+{
+ GtkWidget *label;
+ int what;
+} yes_or_no_args;
+
+G_LOCK_DEFINE_STATIC (yes_or_no);
+static volatile int yes_or_no = YES_IT_IS;
+
+void destroy(GtkWidget *widget, gpointer data)
+{
+ gtk_main_quit();
+}
+
+void *argument_thread(void *args)
+{
+ yes_or_no_args *data = (yes_or_no_args *)args;
+ gboolean say_something;
+
+ for(;;)
+ {
+ /* sleep a while */
+ sleep(rand() / (RAND_MAX / 3) + 1);
+
+ /* lock the yes_or_no_variable */
+ G_LOCK(yes_or_no);
+
+ /* do we have to say something? */
+ say_something = (yes_or_no != data->what);
+
+ if(say_something)
+ {
+ /* set the variable */
+ yes_or_no = data->what;
+ }
+
+ /* Unlock the yes_or_no variable */
+ G_UNLOCK(yes_or_no);
+
+ if(say_something)
+ {
+ /* get GTK thread lock */
+ gdk_threads_enter();
+
+ /* set label text */
+ if(data->what == YES_IT_IS)
+ gtk_label_set_text(GTK_LABEL(data->label), "O yes, it is!");
+ else
+ gtk_label_set_text(GTK_LABEL(data->label), "O no, it isn't!");
+
+ /* release GTK thread lock */
+ gdk_threads_leave();
+ }
+ }
+
+ return(NULL);
+}
+
+int main(int argc, char *argv[])
+{
+ GtkWidget *window;
+ GtkWidget *label;
+ yes_or_no_args yes_args, no_args;
+ pthread_t no_tid, yes_tid;
+
+ /* init threads */
+ g_thread_init(NULL);
+ gdk_threads_init ();
+
+ /* init gtk */
+ gtk_init(&argc, &argv);
+
+ /* init random number generator */
+ srand((unsigned int)time(NULL));
+
+ /* create a window */
+ window = gtk_window_new(GTK_WINDOW_TOPLEVEL);
+
+ gtk_signal_connect(GTK_OBJECT (window), "destroy",
+ GTK_SIGNAL_FUNC(destroy), NULL);
+
+ gtk_container_set_border_width(GTK_CONTAINER (window), 10);
+
+ /* create a label */
+ label = gtk_label_new("And now for something completely different ...");
+ gtk_container_add(GTK_CONTAINER(window), label);
+
+ /* show everything */
+ gtk_widget_show(label);
+ gtk_widget_show (window);
+
+ /* create the threads */
+ yes_args.label = label;
+ yes_args.what = YES_IT_IS;
+ pthread_create(&yes_tid, NULL, argument_thread, &yes_args);
+
+ no_args.label = label;
+ no_args.what = NO_IT_IS_NOT;
+ pthread_create(&no_tid, NULL, argument_thread, &no_args);
+
+ /* enter the GTK main loop */
+ gdk_threads_enter();
+ gtk_main();
+ gdk_threads_leave();
+
+ return(0);
+}
+</programlisting>
+</para>
+
<!-- ##### SECTION See_Also ##### -->
<para>
<!-- ##### MACRO GDK_THREADS_ENTER ##### -->
<para>
-This macro marks the begin of a critical section
-in which GDK and GTK+ functions can be called.
-Only one thread at a time can be in such a critial
-section.
+This macro marks the beginning of a critical section in which GDK and GTK+
+functions can be called. Only one thread at a time can be in such a
+critial section. The macro expands to a no-op if #G_THREADS_ENABLED
+has not been defined. Typically gdk_threads_enter() should be used
+instead of this macro.
</para>
<!-- ##### FUNCTION gdk_threads_enter ##### -->
<para>
-Enters a critical region like #GDK_THREADS_ENTER.
+This macro marks the beginning of a critical section
+in which GDK and GTK+ functions can be called.
+Only one thread at a time can be in such a critial
+section.
</para>
-
<!-- ##### FUNCTION gdk_threads_leave ##### -->
<para>
Leaves a critical region begun with gdk_threads_enter().
</para>
-
-
<!-- ##### VARIABLE gdk_threads_mutex ##### -->
<para>
The #GMutex used to implement the critical region for
-gdk_threads_enter()/gdk_threads_leave().
+gdk_threads_enter()/gdk_threads_leave(). This variable should not be
+used directly — consider it private.
</para>
# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE)
content_files = \
building.sgml \
+ changes-1.2.sgml \
+ changes-2.0.sgml \
compiling.sgml \
framebuffer.sgml \
objects_grouped.sgml \
+ question_index.sgml \
resources.sgml \
text_widget.sgml \
tree_widget.sgml \
--- /dev/null
+<refentry id="gtk-changes-1-2" revision="1 Jan 2002">
+<refmeta>
+<refentrytitle>Changes from 1.0 to 1.2</refentrytitle>
+<manvolnum>3</manvolnum>
+<refmiscinfo>Changes from 1.0 to 1.2</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+<refname>Changes from 1.0 to 1.2</refname>
+<refpurpose>
+Incompatible changes made between version 1.0 and version 1.2
+</refpurpose>
+</refnamediv>
+
+
+<refsect1>
+<title>Incompatible changes from 1.0 to 1.2</title>
+
+<itemizedlist>
+
+<listitem>
+<para>
+GtkAcceleratorTable has been replaced with GtkAccelGroup.
+</para>
+</listitem>
+
+<listitem>
+<para>
+GtkMenuFactory has been replaced with GtkItemFactory, although
+a version of GtkMenuFactory is currently still provided to ease
+the migration phase.
+</para>
+</listitem>
+
+<listitem>
+<para>
+The GtkTypeInfo structures used in the gtk_*_type_init() functions have
+changed a bit, the old format:
+<programlisting>
+ GtkTypeInfo bin_info =
+ {
+ "GtkBin",
+ sizeof (GtkBin),
+ sizeof (GtkBinClass),
+ (GtkClassInitFunc) gtk_bin_class_init,
+ (GtkObjectInitFunc) gtk_bin_init,
+ (GtkArgSetFunc) NULL,
+ (GtkArgGetFunc) NULL,
+ };
+</programlisting>
+
+ needs to be converted to:
+
+<programlisting>
+ static const GtkTypeInfo bin_info =
+ {
+ "GtkBin",
+ sizeof (GtkBin),
+ sizeof (GtkBinClass),
+ (GtkClassInitFunc) gtk_bin_class_init,
+ (GtkObjectInitFunc) gtk_bin_init,
+ /* reserved_1 */ NULL,
+ /* reserved_2 */ NULL,
+ (GtkClassInitFunc) NULL,
+ };
+</programlisting>
+
+ the GtkArgSetFunc and GtkArgGetFunc functions are not supported from the
+ type system anymore, and you should make sure that your code only fills
+ in these fields with NULL and doesn't use the deprecated function typedefs
+ (GtkArgSetFunc) and (GtkArgGetFunc) anymore.
+</para>
+</listitem>
+
+<listitem>
+<para>
+A number of Gtk functions were renamed. For compatibility, gtkcompat.h
+ #define's the old 1.0.x function names in terms of the new names.
+ To assure your Gtk program doesn't rely on outdated function
+ variants, compile your program with -DGTK_DISABLE_COMPAT_H to disable
+ the compatibility aliases.
+
+ Here is the list of the old names and replacements:
+
+<programlisting>
+ Old: Replacement:
+
+ gtk_accel_label_accelerator_width gtk_accel_label_get_accel_width
+ gtk_check_menu_item_set_state gtk_check_menu_item_set_active
+ gtk_container_border_width gtk_container_set_border_width
+ gtk_label_set gtk_label_set_text
+ gtk_notebook_current_page gtk_notebook_get_current_page
+ gtk_packer_configure gtk_packer_set_child_packing
+ gtk_paned_gutter_size gtk_paned_set_gutter_size
+ gtk_paned_handle_size gtk_paned_set_handle_size
+ gtk_scale_value_width gtk_scale_get_value_width
+ gtk_style_apply_default_pixmap gtk_style_apply_default_background (1)
+ gtk_toggle_button_set_state gtk_toggle_button_set_active
+ gtk_window_position gtk_window_set_position
+
+ (1) gtk_style_apply_default_background() has an additional
+ argument, gboolean set_bg. This parameter should be FALSE if
+ the background is being set for a NO_WINDOW widget, otherwise
+ true.
+</programlisting>
+</para>
+</listitem>
+
+<listitem>
+<para>
+During the development phase of the 1.1.x line of Gtk certain functions
+ were deprecated and later removed. Functions affected are:
+
+<programlisting>
+ Removed: Replacement:
+ gtk_clist_set_border gtk_clist_set_shadow_type
+ gtk_container_block_resize gtk_container_set_resize_mode
+ gtk_container_unblock_resize gtk_container_set_resize_mode
+ gtk_container_need_resize gtk_container_check_resize
+ gtk_ctree_show_stub gtk_ctree_set_show_stub
+ gtk_ctree_set_reorderable gtk_clist_set_reorderable
+ gtk_ctree_set_use_drag_icons gtk_clist_set_use_drag_icons
+ gtk_entry_adjust_scroll (1)
+ gtk_object_class_add_user_signal gtk_object_class_user_signal_new
+ gtk_preview_put_row gtk_preview_put
+ gtk_progress_bar_construct gtk_progress_set_adjustment
+ gtk_scrolled_window_construct gtk_scrolled_window_set_{h|v}adjustment
+ gtk_spin_button_construct gtk_spin_button_configure
+ gtk_widget_thaw_accelerators gtk_widget_unlock_accelerators
+ gtk_widget_freeze_accelerators gtk_widget_lock_accelerators
+
+(1) This function is no longer needed as GtkEntry should automatically
+ keep the scroll adjusted properly.
+</programlisting>
+</para>
+</listitem>
+
+
+<listitem>
+<para>
+Additionally, all gtk_*_interp functions were removed.
+ gtk_*_full versions were provided as of GTK+-1.0 and should
+ be used instead.
+</para>
+</listitem>
+
+<listitem>
+<para>
+GtkButton has been changed to derive from GtkBin.
+ To access a button's child, use GTK_BIN (button)->child, instead
+ of the old GTK_BUTTON (button)->child.
+</para>
+</listitem>
+
+<listitem>
+<para>
+The selection API has been slightly modified:
+
+ gtk_selection_add_handler() and gtk_selection_add_handler_full()
+ have been removed. To supply the selection, one now register
+ the targets one is interested in with:
+
+<programlisting>
+ void gtk_selection_add_target (GtkWidget *widget,
+ GdkAtom selection,
+ GdkAtom target,
+ guint info);
+</programlisting>
+
+ or:
+
+<programlisting>
+ void gtk_selection_add_targets (GtkWidget *widget,
+ GdkAtom selection,
+ GtkTargetEntry *targets,
+ guint ntargets);
+</programlisting>
+
+ When a request for a selection is received, the new "selection_get"
+ signal will be called:
+
+<programlisting>
+ void "selection_get" (GtkWidget *widget,
+ GtkSelectionData *selection_data,
+ guint info,
+ guint time);
+</programlisting>
+
+ A "time" parameter has also been added to the "selection_received"
+ signal.
+
+<programlisting>
+ void "selection_received" (GtkWidget *widget,
+ GtkSelectionData *selection_data,
+ guint time);
+</programlisting>
+</para>
+</listitem>
+
+<listitem>
+<para>
+The old drag and drop API has been completely removed and replaced.
+ See the reference documentation for details on the new API.
+</para>
+</listitem>
+
+<listitem>
+<para>
+Support for Themes has been added. In general, this does
+ not affect application code, however, a few new rules should
+ be observed:
+
+<programlisting>
+ - To set a shape for a window, you must use
+ gtk_widget_shape_combine_mask() instead of
+ gdk_window_shape_combine_mask(), or the shape will be
+ reset when switching themes.
+
+ - It is no longer permissable to draw directly on an arbitrary
+ widget, or to set an arbitrary widget's background pixmap.
+ If you need to do that, use a GtkDrawingArea or (for a
+ toplevel) a GtkWindow where gtk_widget_set_app_paintable()
+ has been called.
+</programlisting>
+</para>
+</listitem>
+
+<listitem>
+<para>
+The ScrolledWindow widget no longer creates a Viewport
+ automatically. Instead, it has been generalized to accept
+ any "self-scrolling" widget.
+</para>
+
+<para>
+ The self-scrolling widgets in the Gtk+ core are GtkViewport,
+ GtkCList, GtkCTree, GtkText, and GtkLayout. All of these widgets can
+ be added to a scrolled window as normal children with
+ gtk_container_add() and scrollbars will be set up automatically.
+</para>
+
+<para>
+ To add scrollbars to a non self-scrolling widget, (such as a GtkList),
+ first add it to a viewport, then add the viewport to a scrolled window.
+ The scrolled window code provides a convenience function to do this:
+
+<programlisting>
+ void gtk_scrolled_window_add_with_viewport (GtkScrolledWindow *scrollwin,
+ GtkWidget *child);
+</programlisting>
+
+ This does exactly what it says - it creates a Viewport, adds the child
+ widget to it, then adds the Viewport to the scrolled window.
+</para>
+
+<para>
+ The scrollbars have been removed from the GtkCList and GtkCTree,
+ because they are now scrolled by simply adding them to a Scrolled
+ Window. The scrollbar policy is set on the scrolled window with
+ gtk_scrolled_window_set_policy() and not on the child widgets
+ (e.g. GtkCList's gtk_clist_set_policy() was removed).
+</para>
+</listitem>
+
+<listitem>
+<para>
+The "main loop" of GTK+ has been moved to GLib. This should not
+ affect existing programs, since compatibility functions have
+ been provided. However, you may want to consider migrating
+ your code to use the GLib main loop directly.
+</para>
+</listitem>
+
+<listitem>
+<para>
+the GTK_BASIC flag was removed, and with it the corresponding
+ macro and function GTK_WIDGET_BASIC() and gtk_widget_basic().
+</para>
+</listitem>
+
+<listitem>
+<para>
+All freeze/thaw methods are now recursive - that is, if you
+ freeze a widget n times, you must also thaw it n times.
+
+ Therefore, if you have code like:
+
+<programlisting>
+ gboolean frozen;
+ frozen = GTK_CLIST_FROZEN (clist);
+ gtk_clist_freeze (clist);
+ [...]
+ if (!frozen)
+ gtk_clist_thaw (clist);
+
+ it will not work anymore. It must be, simply:
+
+ gtk_clist_freeze (clist);
+ [...]
+ gtk_clist_thaw (clist);
+</programlisting>
+</para>
+</listitem>
+
+<listitem>
+<para>
+The thread safety in GTK+ 1.2 is slightly different than
+ that which appeared in early versions in the 1.1
+ development track. The main difference is that it relies on
+ the thread primitives in GLib, and on the thread-safe
+ GLib main loop.
+</para>
+
+<para>
+ This means:
+
+<programlisting>
+ - You must call g_thread_init() before executing any
+ other GTK+ or GDK functions in a threaded GTK+ program.
+
+ - Idles, timeouts, and input functions are executed outside
+ of the main GTK+ lock. So, if you need to call GTK+
+ inside of such a callback, you must surround the callback
+ with a gdk_threads_enter()/gdk_threads_leave() pair.
+
+ [ However, signals are still executed within the main
+ GTK+ lock ]
+
+ In particular, this means, if you are writing widgets
+ that might be used in threaded programs, you _must_
+ surround timeouts and idle functions in this matter.
+
+ As always, you must also surround any calls to GTK+
+ not made within a signal handler with a
+ gdk_threads_enter()/gdk_threads_leave() pair.
+
+ - There is no longer a special --with-threads configure
+ option for GTK+. To use threads in a GTK+ program, you
+ must:
+
+ a) If you want to use the native thread implementation,
+ make sure GLib found this in configuration, otherwise,
+ call you must provide a thread implementation to
+ g_thread_init().
+
+ b) Link with the libraries returned by:
+
+ gtk-config --libs gthread
+
+ and use the cflags from:
+
+ gtk-config --cflags gthread
+
+ You can get these CFLAGS and LIBS by passing gthread
+ as the fourth parameter to the AM_PATH_GTK automake
+ macro.
+</programlisting>
+</para>
+</listitem>
+
+<listitem>
+<para>
+Prior to GTK+-1.2, there were two conflicting interpretations
+ of widget->requistion. It was either taken to be
+ the size that the widget requested, or that size
+ modified by calls to gtk_widget_set_usize(). In GTK+-1.2,
+ it is always interpreted the first way.
+</para>
+
+<para>
+ Container widgets are affected in two ways by this:
+
+<programlisting>
+ 1) Container widgets should not pass widget->requisition
+ as the second parameter to gtk_widget_size_request().
+ Instead they should call it like:
+
+ GtkRequisition child_requisition;
+ gtk_widget_size_request (widget, &child_requisition);
+
+ 2) Container widgets should not access child->requisition
+ directly. Either they should use the values returned
+ by gtk_widget_size_request(), or they should call
+ the new function:
+
+ void gtk_widget_get_child_requisition (GtkWidget *widget,
+ GtkRequisition *requisition);
+
+ which returns the requisition of the given widget, modified
+ by calls to gtk_widget_set_usize().
+</programlisting>
+</para>
+</listitem>
+
+
+</itemizedlist>
+
+</refsect1>
+
+</refentry>
+
--- /dev/null
+<refentry id="gtk-changes-2-0" revision="1 Jan 2002">
+<refmeta>
+<refentrytitle>Changes from 1.2 to 2.0</refentrytitle>
+<manvolnum>3</manvolnum>
+<refmiscinfo>Changes from 1.2 to 2.0</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+<refname>Changes from 1.2 to 2.0</refname>
+<refpurpose>
+Incompatible changes made between version 1.2 and version 2.0
+</refpurpose>
+</refnamediv>
+
+
+<refsect1>
+<title>Incompatible changes from 1.2 to 2.0</title>
+
+<para>
+The <ulink url="http://developer.gnome.org/dotplan/porting/">GNOME 2.0
+porting guide</ulink> on <ulink
+url="http://developer.gnome.org">http://developer.gnome.org</ulink>
+has some more detailed discussion of porting from 1.2 to 2.0.
+See the sections on GLib and GTK+.
+</para>
+
+<para>
+GTK+ changed fairly substantially from version 1.2 to 2.0, much more
+so than from 1.0 to 1.2. Subsequent updates (possibilities are 2.0 to
+2.2, 2.2 to 2.4, then to 3.0) will almost certainly be much, much
+smaller. Nonetheless, most programs written for 1.2 compile against
+2.0 with few changes. The bulk of changes listed below are to obscure
+features or very specialized features, and compatibility interfaces
+exist whenever possible.
+</para>
+
+<itemizedlist>
+
+<listitem>
+<para>
+gtk_container_get_toplevels() was removed and replaced with
+ gtk_window_list_toplevels(), which has different memory management
+ on the return value (gtk_window_list_toplevels() copies the GList
+ and also references each widget in the list, so you have to
+ g_list_free() the list after first unref'ing each list member).
+</para>
+</listitem>
+
+<listitem>
+<para>
+The gdk_time* functions have been removed. This functionality
+ has been unused since the main loop was moved into GLib
+ prior to 1.2.
+</para>
+</listitem>
+
+<listitem>
+<para>
+The signature for GtkPrintFunc (used for gtk_item_factory_dump_items)
+ has been changed to take a 'const gchar *' instead of 'gchar *', to
+ match what we do for glib, and other similar cases.
+</para>
+</listitem>
+
+<listitem>
+<para>
+The detail arguments in the GtkStyleClass structure are now 'const gchar *'.
+</para>
+</listitem>
+
+<listitem>
+<para>
+gtk_paned_set_gutter_size() has been removed, since the small handle tab
+ has been changed to include the entire area previously occupied by
+ the gutter.
+</para>
+</listitem>
+
+<listitem>
+<para>
+gtk_paned_set_handle_size() has been removed, in favor of a style property,
+ since this is an option that only makes sense for themes to adjust.
+</para>
+</listitem>
+
+<listitem>
+<para>
+GDK no longer selects OwnerGrabButtonMask for button presses. This means
+ that the automatic grab that occurs when the user presses a button
+ will have owner_events = FALSE, so all events are redirected to the
+ grab window, even events that would normally go to other windows of the
+ window's owner.
+</para>
+</listitem>
+
+<listitem>
+<para>
+GtkColorSelectionDialog has now been moved into it's own set of files,
+ gtkcolorseldialog.c and gtkcolorseldialog.h.
+</para>
+</listitem>
+
+<listitem>
+<para>
+gtk_widget_shape_combine_mask() now keeps a reference count on the
+ mask pixmap that is passed in.
+</para>
+</listitem>
+
+<listitem>
+<para>
+The GtkPatternSpec has been moved to glib as GPatternSpec, the pattern
+ arguments to gtk_item_factory_dump_items() and gtk_item_factory_dump_rc()
+ have thusly been changed to take a GPatternSpec instead of GtkPatternSpec.
+</para>
+</listitem>
+
+<listitem>
+<para>
+Type system changes:
+<itemizedlist>
+<listitem>
+<para>
+ GTK_TYPE_OBJECT is not a fundamental type anymore. Type checks of the
+ style (GTK_FUNDAMENTAL_TYPE (some_type) == GTK_TYPE_OBJECT)
+ will not work anymore. As a replacement, (GTK_TYPE_IS_OBJECT (some_type))
+ can be used now.
+</para>
+</listitem>
+<listitem>
+<para>
+The following types vanished: GTK_TYPE_ARGS, GTK_TYPE_CALLBACK,
+ GTK_TYPE_C_CALLBACK, GTK_TYPE_FOREIGN. The corresponding GtkArg
+ fields and field access macros are also gone.
+</para>
+</listitem>
+<listitem>
+<para>
+The following type aliases vanished: GTK_TYPE_FLAT_FIRST,
+ GTK_TYPE_FLAT_LAST, GTK_TYPE_STRUCTURED_FIRST,
+ GTK_TYPE_STRUCTURED_LAST.
+</para>
+</listitem>
+<listitem>
+<para>
+The type macros GTK_TYPE_MAKE() and GTK_TYPE_SEQNO() vanished, use of
+ GTK_FUNDAMENTAL_TYPE() is discouraged. Instead, the corresponding GType
+ API should be used: G_TYPE_FUNDAMENTAL(), G_TYPE_DERIVE_ID(),
+ G_TYPE_BRANCH_SEQNO(). Note that the GLib type system doesn't build new
+ type ids based on a global incremental sequential number anymore, but
+ numbers new type ids sequentially per fundamental type branch.
+</para>
+</listitem>
+<listitem>
+<para>
+The following type functions vanished/were replaced:
+<programlisting>
+ Old Function Replacement
+ gtk_type_query() - being investigated -
+ gtk_type_set_varargs_type() -
+ gtk_type_get_varargs_type() -
+ gtk_type_check_object_cast() g_type_check_instance_cast()
+ gtk_type_check_class_cast() g_type_check_class_cast()
+ gtk_type_describe_tree() -
+ gtk_type_describe_heritage() -
+ gtk_type_free() -
+ gtk_type_children_types() g_type_children()
+ gtk_type_set_chunk_alloc() GTypeInfo.n_preallocs
+ gtk_type_register_enum() g_enum_register_static()
+ gtk_type_register_flags() g_flags_register_static()
+ gtk_type_parent_class() g_type_parent() /
+ g_type_class_peek_parent()
+</programlisting>
+ Use of g_type_class_ref() / g_type_class_unref() and g_type_class_peek()
+ is recommended over usage of gtk_type_class().
+ Use of g_type_register_static() / g_type_register_dynamic() is recommended
+ over usage of gtk_type_unique().
+</para>
+</listitem>
+</itemizedlist>
+</para>
+</listitem>
+
+<listitem>
+<para>
+Object system changes:
+ GtkObject derives from GObject, so is not the basic object type anymore.
+ This imposes the following source incompatible changes:
+<itemizedlist>
+
+<listitem>
+<para>
+GtkObject has no klass field anymore, an object's class can be retrived
+ with the object's coresponding GTK_<OBJECT>_GET_CLASS (object)
+ macro.
+</para>
+</listitem>
+<listitem>
+<para>
+GtkObjectClass has no type field anymore, a class's type can be retrived
+ with the GTK_CLASS_TYPE (class) macro.
+</para>
+</listitem>
+<listitem>
+<para>
+GtkObjectClass does not introduce the finalize() and shutdown() methods
+ anymore. While shutdown() is intended for GTK+ internal use only, finalize()
+ is required by a variety of object implementations. GObjectClass.finalize
+ should be overriden here, e.g.:
+<programlisting>
+ static void gtk_label_finalize (GObject *gobject)
+ {
+ GtkLabel *label = GTK_LABEL (gobject);
+
+ G_OBJECT_CLASS (parent_class)->finalize (object);
+ }
+ static void gtk_label_class_init (GtkLabelClass *class)
+ {
+ GObjectClass *gobject_class = G_OBJECT_CLASS (class);
+
+ gobject_class->finalize = gtk_label_finalize;
+ }
+</programlisting>
+</para>
+</listitem>
+
+</itemizedlist>
+</para>
+</listitem>
+
+<listitem>
+<para>
+The GtkObject::destroy signal can now be emitted multiple times on an object.
+ ::destroy implementations should check that make sure that they take this
+ into account, by checking to make sure that resources are there before
+ freeing them. For example:
+<programlisting>
+ if (object->foo_data)
+ {
+ g_free (object->foo_data);
+ object->foo_data = NULL;
+ }
+</programlisting>
+
+ Also, ::destroy implementations have to release object references that
+ the object holds. Code in finalize implementations such as:
+<programlisting>
+ if (object->adjustment)
+ {
+ gtk_object_unref (object->adjustment);
+ object->adjustment = NULL;
+ }
+</programlisting>
+ have to be moved into the ::destroy implementations. The reason for doing
+ this is that all object reference cycles should be broken at destruction
+ time.
+
+ Because the ::destroy signal can be emitted multiple times, it no longer
+ makes sense to check if a widget has been destroyed using the
+ GTK_OBJECT_DESTROYED() macro, and this macro has been removed. If
+ catching destruction is still needed, it can be done with a signal
+ connection to ::destroy.
+</para>
+</listitem>
+
+<listitem>
+<para>
+Signal system changes:
+ The Gtk 2.0 signal merly proxies the GSignal system now.
+ For future usage, direct use of the GSignal API is recommended,
+ this avoids significant performance hits where GtkArg structures
+ have to be converted into GValues. For language bindings,
+ GSignal+GClosure provide a much more flexible and convenient
+ mechanism to hook into signal emissions or install class default
+ handlers, so the old GtkSignal API for language bindings is not
+ supported anymore.
+</para>
+<para>
+ Functions that got removed in the Gtk signal API:
+ gtk_signal_n_emissions(), gtk_signal_n_emissions_by_name(),
+ gtk_signal_set_funcs(), gtk_signal_handler_pending_by_id(),
+ gtk_signal_add_emission_hook(), gtk_signal_add_emission_hook_full(),
+ gtk_signal_remove_emission_hook(), gtk_signal_query().
+ Also, the GtkCallbackMarshal argument to gtk_signal_connect_full() is
+ not supported anymore.
+ For many of the removed functions, similar variants are available
+ in the g_signal_* namespace.
+ The GSignal system perfomrs emissions in a slightly different manner than
+ the old GtkSignal code. Signal handlers that are connected to signal "foo"
+ on object "bar" while "foo" is being emitted, will not be called anymore
+ during the emission they were connected within.
+</para>
+</listitem>
+
+<listitem>
+<para>
+Inserting and deleting text in GtkEntry though functions such
+ as gtk_entry_insert_text() now leave the cursor at its original
+ position in the text instead of moving it to the location of
+ the insertion/deletion.
+</para>
+</listitem>
+
+<listitem>
+<para>
+The ->label field of GtkFrame widgets has been removed. (As part of
+ a change to allow the arbitrary widgets in the title position.) The
+ text can now be retrieved with the new function gtk_frame_get_text().
+</para>
+</listitem>
+
+<listitem>
+<para>
+The 'font' and 'font_set' declarations in RC files are now ignored. There
+ is a new 'font_name' field that holds the string form of a Pango font
+</para>
+</listitem>
+
+<listitem>
+<para>
+A number of types in GDK have become subclasses of GObject. For the
+ most part, this should not break anyone's code. However, it's now
+ possible/encouraged to use g_object_ref()/g_object_unref() and other
+ GObject features with these GDK types. The converted types are:
+ GdkWindow, GdkDrawable, GdkPixmap, GdkImage, GdkGC, GdkDragContext,
+ GdkColormap
+</para>
+</listitem>
+
+<listitem>
+<para>
+All drawables including pixmaps used to have a type tag, the
+ GdkWindowType enumeration, which included GDK_WINDOW_PIXMAP.
+ GdkWindowType is now a property of GdkWindow
+ <emphasis>only</emphasis>, and there is no GDK_WINDOW_PIXMAP. You
+ can use the GDK_IS_PIXMAP() macro to see if you have a pixmap, if
+ you need to know that.
+</para>
+</listitem>
+
+<listitem>
+<para>
+GtkStyle and GtkRcStyle are now subclasses of GObject as well. This
+ requires fairly extensive changes to theme engines, but
+ shouldn't affect most other code.
+</para>
+</listitem>
+
+<listitem>
+<para>
+xthickness/ythickness have moved from GtkStyleClass to GtkStyle
+ (from class to instance). This gives themes a bit more flexibility
+ and is generally more of the Right Thing. You can trivially fix
+ your code with s/style->klass->xthickness/style->xthickness/g and
+ same for ythickness.
+</para>
+</listitem>
+
+<listitem>
+<para>
+Some GtkStyle draw_ methods have been removed (cross, oval, ramp)
+ and others have been added (expander, layout). This will require
+ changes to theme engines.
+</para>
+</listitem>
+
+<listitem>
+<para>
+If you were using private GDK types, they have been rearranged
+ significantly. You shouldn't use private types. ;-)
+</para>
+</listitem>
+
+<listitem>
+<para>
+The visual for a widget, and also the default visual is now derived
+ from the colormap for the widget and the default colormap.
+ gtk_widget_set_visual(), gtk_widget_set_default_visual(),
+ gtk_widget_push_visual() and gtk_widget_pop_visual() now do
+ nothing. Since the visual always had to match that of the colormap,
+ it is safe to simply delete all references to these functions.
+</para>
+</listitem>
+
+
+<listitem>
+<para>
+A number of functions in GDK have been renamed for consistency and
+ clarity. #defines to provide backwards compatibility have been
+ included, but can be disabled by defining GDK_DISABLE_DEPRECATED.
+
+<programlisting>
+ #define gdk_draw_pixmap gdk_draw_drawable
+ #define gdk_draw_bitmap gdk_draw_drawable
+
+ #define gdk_window_get_size gdk_drawable_get_size
+ #define gdk_window_get_type gdk_window_get_window_type
+ #define gdk_window_get_colormap gdk_drawable_get_colormap
+ #define gdk_window_set_colormap gdk_drawable_set_colormap
+ #define gdk_window_get_visual gdk_drawable_get_visual
+
+ #define gdk_window_ref gdk_drawable_ref
+ #define gdk_window_unref gdk_drawable_unref
+ #define gdk_bitmap_ref gdk_drawable_ref
+ #define gdk_bitmap_unref gdk_drawable_unref
+ #define gdk_pixmap_ref gdk_drawable_ref
+ #define gdk_pixmap_unref gdk_drawable_unref
+
+ #define gdk_gc_destroy gdk_gc_unref
+ #define gdk_image_destroy gdk_image_unref
+ #define gdk_cursor_destroy gdk_cursor_unref
+
+ (Note that g_object_ref() and g_object_unref() may be used for all of
+ the above _ref and _unref functions.)
+
+ #define gdk_window_copy_area(drawable,gc,x,y,source_drawable,source_x,source_y,width,height) \
+ gdk_draw_pixmap(drawable,gc,source_drawable,source_x,source_y,x,y,width,height)
+
+ #define gdk_rgb_get_cmap gdk_rgb_get_colormap
+</programlisting>
+
+ gtk_widget_popup() was removed, it was only usable for GtkWindows, and
+ there the same effect can be achieved by gtk_window_move() and
+ gtk_widget_show().
+</para>
+</listitem>
+
+<listitem>
+<para>
+gdk_pixmap_foreign_new() no longer calls XFreePixmap() on the
+ pixmap when the GdkPixmap is finalized. This change corresponds
+ to the behavior of gdk_window_foreign_new(), and fixes a lot
+ of problems with code where the pixmap wasn't supposed to be
+ freed. If XFreePixmap() is needed, it can be done using the
+ destroy-notification facilities of g_object_set_data().
+</para>
+</listitem>
+
+<listitem>
+<para>
+GtkProgress/GtkProgressBar had serious problems in GTK 1.2.
+<itemizedlist>
+<listitem>
+<para>
+Only 3 or 4 functions are really needed for 95% of progress
+ interfaces; GtkProgress[Bar] had about 25 functions, and
+ didn't even include these 3 or 4.
+</para>
+</listitem>
+
+<listitem>
+<para>
+In activity mode, the API involves setting the adjustment
+ to any random value, just to have the side effect of
+ calling the progress bar update function - the adjustment
+ is totally ignored in activity mode
+</para>
+</listitem>
+
+<listitem>
+<para>
+You set the activity step as a pixel value, which means to
+ set the activity step you basically need to connect to
+ size_allocate
+</para>
+</listitem>
+
+<listitem>
+<para>
+There are ctree_set_expander_style()-functions, to randomly
+ change look-and-feel for no good reason
+</para>
+</listitem>
+
+<listitem>
+<para>
+The split between GtkProgress and GtkProgressBar makes no sense
+ to me whatsoever.
+</para>
+</listitem>
+
+</itemizedlist>
+
+ This was a big wart on GTK and made people waste lots of time,
+ both learning and using the interface.
+ So, we have added what we feel is the correct API, and marked all the
+ rest deprecated. However, the changes are 100% backward-compatible and
+ should break no existing code.
+ The following 5 functions are the new programming interface and you
+ should consider changing your code to use them:
+<programlisting>
+ void gtk_progress_bar_pulse (GtkProgressBar *pbar);
+ void gtk_progress_bar_set_text (GtkProgressBar *pbar,
+ const gchar *text);
+ void gtk_progress_bar_set_fraction (GtkProgressBar *pbar,
+ gfloat fraction);
+
+ void gtk_progress_bar_set_pulse_step (GtkProgressBar *pbar,
+ gfloat fraction);
+ void gtk_progress_bar_set_orientation (GtkProgressBar *pbar,
+ GtkProgressBarOrientation orientation);
+</programlisting>
+</para>
+</listitem>
+
+<listitem>
+<para>
+The GtkNotebookPage structure has been removed from the public header files;
+ this was never meant to be a public structure, and all functionality that
+ could be done by accessing the struct fields of this structure should be
+ accesible otherwise.
+</para>
+</listitem>
+
+<listitem>
+<para>
+GtkMenuPositionFunc has a new parameter push_in which controls how
+ menus placed outside the screen is handled. If this is set to true and
+ part of the menu is outside the screen then Gtk+ pushes it into the visible
+ area. Otherwise the menu is cut of at the end of the visible screen area.
+</para>
+<para>
+ Regardles of what happens to the size of the menu, the result is always
+ that the items are placed in the same place as if the menu was placed
+ outside the screen, using menu scrolling if necessary.
+</para>
+</listitem>
+
+<listitem>
+<para>
+The "draw" signal and virtual method on GtkWidget has been removed.
+ All drawing should now occur by invalidating a region of the widget
+ (call gdk_window_invalidate_rect() or gtk_widget_queue_draw() for
+ example to invalidate a region). GTK+ merges all invalid regions,
+ and sends expose events to the widget in an idle handler for the
+ invalid regions. gtk_widget_draw() is deprecated but still works; it
+ adds the passed-in area to the invalid region and immediately sends
+ expose events for the current invalid region.
+ Most widgets will work fine if you just delete their "draw"
+ implementation, since they will already have working expose_event
+ implementations. The draw method was rarely called in practice
+ anyway.
+</para>
+</listitem>
+
+<listitem>
+<para>
+The GdkExposeEvent has a new region field. This can be used instead
+ of the area field if you want a more exact representation of the
+ area to update.
+</para>
+</listitem>
+
+<listitem>
+<para>
+Sending synthetic exposes using gtk_widget_event is no longer allowed.
+ If you just need an expose call you should use gdk_window_invalidate_rect()
+ or gdk_window_invalidate_region() instead. For the case of container
+ widgets that need to propagate expose events to NO_WINDOW children
+ you can either use gtk_container_propagate_expose(), or chain to the
+ default container expose handler.
+</para>
+</listitem>
+
+<listitem>
+<para>
+The draw_default and draw_focus methods/signals on GtkWidget are
+ gone; simply draw things in your expose handler.
+ gtk_widget_draw_focus() and gtk_widget_draw_default() wrapper
+ functions are also gone; just queue a draw on the widget,
+ or the part affected by the focus/default anyway.
+ Also, GtkWidget now has default implementations for focus_in_event
+ and focus_out_event. These set/unset GTK_HAS_FOCUS, and queue a
+ draw. So if your focus in/out handler just does that, you can delete
+ it.
+</para>
+</listitem>
+
+<listitem>
+<para>
+GtkText and GtkTree are buggy and broken. We don't recommend using
+ them, and changing old code to avoid them is a good idea. The
+ recommended alternatives are GtkTextView and GtkTreeView. The
+ broken widgets are not declared in the headers by default; to use
+ them, define the symbol GTK_ENABLE_BROKEN during compilation. In
+ some future release, these widgets will be removed from GTK+.
+</para>
+</listitem>
+
+<listitem>
+<para>
+GdkColorContext is gone; you probably weren't using it anyway.
+ Use GdkColormap and the gdk_rgb_* functions instead.
+</para>
+</listitem>
+
+<listitem>
+<para>
+GtkMenuBar now draws the GtkContainer::border_width space outside
+ the frame, not inside the frame
+</para>
+</listitem>
+
+
+<listitem>
+<para>
+In GTK 1.2, if an event handler returned TRUE it prevented
+ propagation of that event to parent widgets. That is, the
+ event signal would not be emitted on parent widgets. In
+ GTK 2.0, if an event handler returns TRUE, the current signal
+ emission on the current widget is immediately stopped. That is,
+ other callbacks connected to the signal will not be invoked.
+</para>
+</listitem>
+
+<listitem>
+<para>
+gtk_toolbar_new() no longer has arguments. This function
+ was broken because the default GtkToolbarStyle (icons, text, both)
+ is now a user preference, which is overridden when you call
+ gtk_toolbar_set_style(). The constructor forced everyone to
+ override the preference, which was undesirable. So to port
+ your app, decide if you want to force the toolbar style
+ or conform to the user's global defaults; if you want to force
+ it, call gtk_toolbar_set_style().
+</para>
+
+<para>
+ The orientation arg was removed from toolbar_new() as well, just
+ because it wasn't very useful and we were breaking the function
+ anyway so had an opportunity to lose it. Call
+ gtk_toolbar_set_orientation() to set toolbar orientation.
+</para>
+</listitem>
+
+
+<listitem>
+<para>
+GtkRange/GtkScrollbar/GtkScale were rewritten; this means that most
+ theme engines won't draw them properly, and any custom subclasses of
+ these widgets will need a rewrite (though if you could figure out
+ how to subclass the old version of GtkRange, you have our
+ respect). Also, GtkTroughType is gone.
+</para>
+</listitem>
+
+<listitem>
+<para>
+The GtkContainer::focus signal/virtualfunction and
+ gtk_container_focus() call were replaced by
+ GtkWidget::focus and gtk_widget_child_focus().
+ The semantics are the same, so you should be able to just
+ replace "container_class->focus = mywidget_focus" with
+ "widget_class->focus = mywidget_focus" and replace
+ gtk_container_focus() calls with gtk_widget_child_focus() calls.
+</para>
+<para>
+ The purpose of this change was to allow non-containers to have
+ focusable elements.
+</para>
+</listitem>
+
+<listitem>
+<para>
+gtk_rc_set_image_loader() and gtk_rc_load_image() has been removed, now
+ that GTK+ includes decent image loading capabilities itself.
+</para>
+</listitem>
+
+<listitem>
+<para>
+An extra GtkSettings argument has been added to
+ gtk_rc_find_pixmap_in_path(). This function is only actually useful
+ from a theme engine during parsing, at which point the GtkSettings
+ is provided.
+</para>
+</listitem>
+
+<listitem>
+<para>
+The child argument facility in gtkcontainer.c has been converted
+ to a child property facility using GParamSpec and other facilities
+ for GObject.
+</para>
+</listitem>
+
+ <listitem>
+<para>
+The set_child_arg and get_child_arg virtual methods have been
+ replaced with set_child_property / get_child_property, which
+ work similar to GObject->set_property/get_property.
+</para>
+</listitem>
+
+
+ <listitem>
+<para>
+Other removed GtkContainer unctions with the replacements:
+
+<programlisting>
+ gtk_container_add_child_arg_type => gtk_container_class_install_child_property
+ gtk_container_query_child_args => gtk_container_class_list_child_properties
+ gtk_container_child_getv => gtk_container_child_set_property
+ gtk_container_child_setv => gtk_container_child_get_property
+ gtk_container_add_with_args => gtk_container_add_with_properties
+ gtk_container_addv => gtk_container_add / gtk_container_child_set_property
+</programlisting>
+</para>
+</listitem>
+
+
+<listitem>
+<para>
+gdk_image_get() (or rather its replacement,
+ gdk_drawable_get_image()) now handles errors properly by returning
+ NULL, previously it would crash. Also, a window being offscreen is
+ no longer considered an error; instead, the area being contains
+ undefined contents for the offscreen areas. In most cases, code
+ using gdk_image_get() should really be ported to
+ gdk_pixbuf_get_from_drawable().
+</para>
+</listitem>
+
+<listitem>
+<para>
+gtk_widget_set_usize() has been renamed to
+ gtk_widget_set_size_request(), however the old name still exists
+ unless you define GTK_DISABLE_DEPRECATED.
+</para>
+</listitem>
+
+<listitem>
+<para>
+gtk_widget_set_uposition() is deprecated; use gtk_window_move(),
+ gtk_fixed_put(), or gtk_layout_put() instead.
+</para>
+</listitem>
+
+<listitem>
+<para>
+gtk_window_set_policy() is deprecated. To get the effect of
+ "allow_shrink", call gtk_widget_set_size_request(window, 0, 0). To
+ get the effect of "allow_grow", call
+ gtk_window_set_resizable(window, TRUE). You didn't want the effect
+ of auto_shrink, it made no sense. But maybe if you were using it you
+ want to use gtk_window_resize (window, 1, 1) to snap a window back
+ to its minimum size (the 1, 1 will be rounded up to the minimum
+ window size).
+</para>
+</listitem>
+
+<listitem>
+<para>
+The core GTK+ now takes care of handling mapping, unmapping and
+ realizing the child widgets of containers in
+ gtk_widget_set_parent(). In most cases, this allows container
+ implementations to be simplifid by removing the code in add()
+ methods to map and realize children. However, there are
+ a couple of things to watch out for here:
+</para>
+</listitem>
+
+
+ <listitem>
+<para>
+If the parent is realized before the add() happens,
+ gtk_widget_set_parent_window() must be called before
+ gtk_widget_set_parent(), since gtk_widget_set_parent()
+ will realize the child.
+</para>
+</listitem>
+
+ <listitem>
+<para>
+If a container depended on its children not being mapped
+ unless it did so itself (for example, GtkNotebook only
+ mapped the current page), then the new function
+ gtk_widget_set_child_visible() must be called to keep
+ widgets that should not be mapped not mapped.
+</para>
+
+<para>
+ As part of this change, most containers also will no longer need
+ custom implementations of the map() and unmap() virtual
+ functions. The only cases where this is necessary are:
+
+<itemizedlist>
+ <listitem>
+<para>
+For !NO_WINDOW widgets, if you create children of widget->window
+ and don't map them in realize() then you must map them
+ in map(). [ In almost all cases, you can simply map the
+ windows in realize() ]
+</para>
+</listitem>
+
+ <listitem>
+<para>
+For NO_WINDOW widgets, if you create windows in your realize()
+ method, you must map then in map() and unmap them in unmap().
+</para>
+</listitem>
+</itemizedlist>
+</para>
+</listitem>
+
+<listitem>
+<para>
+gtk_widget_set_default_style (), gtk_widget_push_style (),
+ and gtk_widget_pop_style () have been removed, since they
+ did not work properly with themes and there were better
+ alternatives for modifying the appearance of widgets.
+
+ You should generally use gtk_widget_modify_fg/bg/base/text/font
+ instead.
+</para>
+</listitem>
+
+
+<listitem>
+<para>
+gtk_image_new() now takes no arguments and creates an empty GtkImage
+ widget. To create a GtkImage widget from a GdkImage (the least
+ common usage of GdkImage), use gtk_image_new_from_image.
+</para>
+</listitem>
+
+<listitem>
+<para>
+GTK_SELECTION_EXTENDED is now deprecated, and neither the
+ GtkList/GtkTree nor the GtkCList/GtkCTree support
+ GTK_SELECTION_EXTENDED anymore. However, the old extended behavior
+ replaces MULTIPLE behavior.
+</para>
+</listitem>
+
+<listitem>
+<para>
+The following variables are no longer exported from GDK. (Other variables
+ are also no longer exported; the following are the ones found used
+ externally in a large sample of GTK+ code.)
+
+<programlisting>
+ Variable Replacement
+ ======== ===========
+ gdk_null_window_warnings None - did nothing in GTK+-1.2.
+ gdk_leader_window None - private variable
+ gdk_screen gdk_x11_get_default_screen ()
+ gdk_root_window gdk_x11_get_default_root_xwindow ()
+ gdk_root_parent gdk_get_default_root_window ()
+ gdk_error_code/gdk_error_warnings gdk_error_trap_push()/pop()
+ gdk_display_name gdk_get_display ()
+ gdk_wm_delete_window gdk_atom_intern ("WM_DELETE_WINDOW", FALSE)
+ gdk_wm_take_focus gdk_atom_intern ("WM_TAKE_FOCUS", FALSE)
+ gdk_wm_protocols gdk_atom_intern ("WM_PROTOCOLS", FALSE)
+</programlisting>
+</para>
+</listitem>
+
+
+<listitem>
+<para>
+The handling of Colormaps and widgets has been changed:
+
+<itemizedlist>
+ <listitem>
+<para>
+The default colormap for widgets is now the GdkRGB colormap, not
+ the system default colormap. If you try to use resources created for
+ a widget (e.g., widget->style) with a window using the system
+ colormap, errors will result on some machines.
+</para>
+</listitem>
+
+
+ <listitem>
+<para>
+gtk_widget_push/pop_colormap() only cause the colormap to be
+ explicitely set on toplevel widgets not on all widgets. The
+ colormap for other widgets (when not set using
+ gtk_widget_set_colormap()), is determined by finding the nearest
+ ancestor with a colormap set on it explicitely, or if that
+ fails, the default colormap.
+</para>
+</listitem>
+
+</itemizedlist>
+
+</para>
+</listitem>
+
+
+<listitem>
+<para>
+The default selected day for GtkCalendar is now the current day in the
+ month, not the first day in the month. The current month and year
+ were already used.
+</para>
+</listitem>
+
+
+<listitem>
+<para>
+GDK is no longer put into threaded mode automatically when
+ g_thread_init() has been called. In order to use the
+ global GDK thread mutex with gdk_threads_enter() and
+ gdk_threads_leave(), you must call gdk_threads_init() explicitely.
+
+ If you aren't using GDK and GTK+ functions from multiple threads,
+ there is no reason to call gdk_threads_init().
+</para>
+</listitem>
+
+<listitem>
+<para>
+The GtkPreviewInfo struct has had its visual and colormap fields
+ removed. Also, gtk_preview_get_cmap() and gtk_preview_get_visual()
+ are deprecated, as GdkRgb works on any colormap and visual. You no
+ longer need to gtk_widget_push_cmap (gtk_preview_get_cmap ()) in
+ your code.
+</para>
+</listitem>
+
+
+<listitem>
+<para>
+The GtkBox, GtkTable, and GtkAlignment widgets now call
+ gtk_widget_set_redraw_on_allocate (widget, FALSE); on themselves.
+ If you want to actually draw contents in a widget derived from
+ one of these widgets, you'll probably want to change this
+ in your init() function.
+</para>
+</listitem>
+
+
+<listitem>
+<para>
+A number of widgets are now NO_WINDOW widgets (most importantly
+ GtkButton, but also GtkRange and GtkNotebook)
+
+ This has a couple of effects:
+
+<itemizedlist>
+ <listitem>
+<para>
+If you are deriving from one of these widgets, you need to
+ adapt your code appropriately -- for instance, drawing coordinates
+ start from widget->allocation.x, widget->allocation.y.
+</para>
+</listitem>
+
+
+ <listitem>
+<para>
+If you are embedding one of these widgets in a custom widget,
+ you must make sure you call gtk_container_propagate_expose()
+ correctly, as you must for any NO_WINDOW widgets.
+</para>
+</listitem>
+</itemizedlist>
+</para>
+
+<para>
+ GtkFixed is a little special; it is now created by default as
+ a NO_WINDOW widget, but if you do
+
+<programlisting>
+ gtk_fixed_set_has_window (fixed, TRUE);
+</programlisting>
+
+ after creating a fixed widget, it will create a window and
+ handle it properly.
+</para>
+</listitem>
+
+<listitem>
+<para>
+GtkLayout no longer has the xoffset, yoffset fields, which used
+ to store the difference between world and window coordinates for
+ layout->bin_window. These coordinate systems are now always
+ the same.
+</para>
+</listitem>
+
+<listitem>
+<para>
+gtk_paint_focus(), gtk_draw_focus() and GtkStyle::draw_focus()
+ have been changed a bit:
+
+<itemizedlist>
+ <listitem>
+<para>
+A GtkStateType argument has been added to gtk_paint_focus()
+</para>
+</listitem>
+
+ <listitem>
+<para>
+The default implementation of GtkStyle::draw_focus virtual
+ function now draws a focus rectangle whose width is
+ determinted by the GtkWidget::focus-width style property.
+</para>
+</listitem>
+
+ <listitem>
+<para>
+The rectangle passed in is the bounding box, instead of
+ the rectangle used in the gdk_draw_rectangle() call, so it is
+ no longer necessary to subtract 1 from the width and height.
+</para>
+</listitem>
+
+</itemizedlist>
+
+</para>
+</listitem>
+
+
+</itemizedlist>
+
+</refsect1>
+
+</refentry>
-<refentry id="gtk-framebuffer" revision="4 Feb 2001">
+<refentry id="gtk-framebuffer" revision="1 Jan 2002">
<refmeta>
<refentrytitle>Framebuffer</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>
-<refname>Framebuffer</refname>
+<refname>Using GTK+ on the Framebuffer</refname>
<refpurpose>
Using embedded GTK+ on the Linux framebuffer
</refpurpose>
</refnamediv>
<refsect1>
-<title>Framebuffer</title>
+<title>GTK+ for the Linux Framebuffer</title>
<para>
+The linux-fb port of GTK+, also known as GtkFB is an implementation of
+GDK (and therefore GTK+) that runs on the linux framebuffer. It runs in
+a single process that doesn't need X. It should run most GTK+ programs
+without any changes to the source.
+</para>
+
+<refsect2><title>Build requirements</title>
+<para>
+You need GTK+ 2.0; the 1.2.x series does not have framebuffer support.
+To compile GTK+ with framebuffer support you will need freetype 2, we
+recommend FreeType 2.0.1 or later, as there was some problems with
+freetype-config in 2.0. Make sure that you install freetype before
+Pango, since Pango also needs it. Freetype can be found at
+ftp://ftp.freetype.org
+</para>
+</refsect2>
+
+<refsect2><title>Hardware requirements</title>
+<para>
+You need a graphics card with an availible framebuffer driver that can
+run in 8, 16, 24 or 32 bpp, such as matroxfb or vesafb. You also need
+a supported mouse. GTK+ currently supports the ps2 mouse, ms serial
+mouse and fidmour touchscreen. Additional hardware support should
+be simple to add.
+</para>
+</refsect2>
+
+<refsect2><title>Building and installing</title>
+<para>
+First build and install glib and pango as usual, in that order.
+
+Then configure Gtk by running configure (or autogen.sh if running from
+CVS) with <literal>--with-gdktarget=linux-fb</literal>.
+</para>
+
+<para>Then compile as ususal: make; make install</para>
+</refsect2>
+<refsect2><title>Fonts</title>
+<para>
+Since GtkFB uses freetype 2 to render fonts it can render truetype and
+postscript type 1 antialiased fonts.
+</para>
+
+<para>At startup it scans some directories looking for fonts. By default
+it looks in $prefix/lib/ft2fonts, and if you want to change this you
+must add something like:
+
+<programlisting>
+[PangoFT2]
+FontPath = /usr/share/fonts/default/Type1:/usr/share/fonts/default/TrueType
+</programlisting>
+
+To your <filename>$prefix/etc/pango/pangorc</filename> or <filename>~/.pangorc</filename>.
+</para>
+
+<para>
+You must also set up font aliases for the fonts Sans, Serif and
+Monotype. This is done by creating a
+<filename>$prefix/etc/pango/pangoft2.aliases</filename> or
+<filename>~/.pangoft2_aliases</filename> file. You can also set the name of this file using
+the key AliasFiles in the PangoFT2 section in pangorc.
+</para>
+
+<para>
+An example of a font alias file for the urw fontset is:
+<programlisting>
+sans normal normal normal normal "urw gothic l"
+serif normal normal normal normal "urw palladio l"
+monospace normal normal normal normal "nimbus mono l"
+</programlisting>
</para>
+<para>
+And one using the Windows truetype fonts is:
+<programlisting>
+sans normal normal normal normal "arial"
+serif normal normal normal normal "times new roman"
+monospace normal normal normal normal "courier new"
+</programlisting>
+
+A more detailed example can be found in examples/pangoft2.aliases in the
+pango distribution.
+</para>
+</refsect2>
+
+<refsect2><title>Running</title>
+<para>
+To run a program you should only need to start it, but there are some
+things that can cause problems, and some things that can be controlled
+by environment variables. Try testgtk distributed with GTK+ to test
+if things work.
+</para>
+
+<para>
+If you use a ps2 mouse, make sure that /dev/psaux is readable and
+writable.
+</para>
+
+<para>Make sure gpm is not running.</para>
+
+<para>If you don't specify anything GtkFB will start up in the current
+virtual console in the current resolution and bit-depth. This can be
+changed by specifying environment variables:
+</para>
+
+<para>
+<programlisting>
+GDK_VT:
+ unset means open on the current VT.
+ 0-9: open on the specified VT. Make sure you have read/write rights
+ there.
+ new: Allocate a new VT after the last currently used one.
+
+GDK_DISPLAY_MODE:
+ Specifies the name of a mode in /etc/fb.modes that you want to use.
+
+GDK_DISPLAY_DEPTH:
+ Specify the desired bit depth of the framebuffer.
+
+GDK_DISPLAY_WIDTH:
+ Specify the desired width of the framebuffer.
+
+GDK_DISPLAY_HEIGHT:
+ Specify the desired height of the framebuffer.
+
+GDK_DISPLAY:
+ Specify the framebuffer device to use. Default is /dev/fb0
+
+GDK_MOUSE_TYPE:
+ Specify mouse type. Currently supported is:
+ ps2 - PS/2 mouse
+ imps2 - PS/2 intellimouse (wheelmouse)
+ ms - Microsoft serial mouse
+ fidmour - touch screen
+ Default is ps2.
+
+GDK_KEYBOARD_TYPE:
+ Specify keyboard type. Currently supported is
+ xlate - normal tty mode keyboard.
+ Quite limited, cannot detect key up/key down events. Doesn't
+ handle ctrl/alt/shift for all keys. This is the default driver,
+ but should not be used in "production" use.
+ raw - read from the tty in RAW mode.
+ Sets the keyboard in RAW mode and handles all the keycodes. This
+ gives correct handling of modifiers and key up/down events. You
+ must be root to use this. If you use this for development or
+ debugging it is recommended to enable magic sysrq handling in the
+ kernel. Then you can use ALT-SysRQ-r to turn the keyboard back to
+ normal mode.
+ Default is xlate.
+</programlisting>
+</para>
+</refsect2>
+
+<refsect2><title>Debug features</title>
+<para>Pressing Ctrl-Alt-Return repaints the whole screen.
+Unfortunately this cannot be pressed when using the xlate keyboard
+driver, so instead you can use shift-F1 instead when using this
+driver.
+</para>
+
+<para>Pressing Ctrl-Alt-BackSpace kills the GtkFB program. (Can't be pressed
+in the xlate driver.)</para>
+</refsect2>
+
</refsect1>
</refentry>
-<!doctype book PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
+<!doctype book PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
<!notation PNG system "PNG">
<!entity % local.notation.class "| PNG">
<!entity gtk-Resources SYSTEM "resources.sgml">
<!entity gtk-Windows SYSTEM "windows.sgml">
<!entity gtk-Framebuffer SYSTEM "framebuffer.sgml">
+<!entity gtk-Questions SYSTEM "question_index.sgml">
+<!entity gtk-Changes-1-2 SYSTEM "changes-1.2.sgml">
+<!entity gtk-Changes-2-0 SYSTEM "changes-2.0.sgml">
+
]>
<book id="index">
<bookinfo>
>k-Building;
>k-Compiling;
- >k-Resources;
>k-Windows;
>k-Framebuffer;
+ >k-Changes-1-2;
+ >k-Changes-2-0;
+ >k-Resources;
+ >k-Questions;
</chapter>
--- /dev/null
+<refentry id="gtk-question-index" revision="1 Jan 2002">
+<refmeta>
+<refentrytitle>Common Questions</refentrytitle>
+<manvolnum>3</manvolnum>
+<refmiscinfo>Common Questions</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+<refname>Common Questions</refname>
+<refpurpose>
+Find answers to common questions in the GTK+ manual
+</refpurpose>
+</refnamediv>
+
+<refsect1>
+<title>Questions and Answers</title>
+
+<para>
+This is an "index" of the reference manual organized by common "How do
+I..." questions. If you aren't sure which documentation to read for
+the question you have, this list is a good place to start.
+</para>
+
+<qandaset>
+
+<qandadiv><title>General</title>
+
+<qandaentry>
+<question><para>
+Where can I get help with GTK+, submit a bug report, or make a feature
+request?
+</para></question>
+
+<answer>
+
+<para>
+See the <link linkend="gtk-resources">documentation on this topic</link>.
+</para>
+
+</answer>
+
+</qandaentry>
+
+
+<qandaentry>
+<question><para>How do I port from one GTK+
+version to another?</para></question>
+
+<answer>
+
+<para>
+See the <link linkend="gtk-changes-2-0">list of incompatible changes
+from 1.2 to 2.0</link>. Also, the <ulink
+url="http://developer.gnome.org/dotplan/porting/">GNOME 2.0 porting
+guide</ulink> on <ulink
+url="http://developer.gnome.org">http://developer.gnome.org</ulink>
+has some more detailed discussion of porting from 1.2 to 2.0.
+You may also find useful information in the documentation for
+specific widgets and functions.
+</para>
+
+<para>
+If you have a question not covered in the manual, feel free to
+ask on the mailing lists and please <ulink
+url="http://bugzilla.gnome.org">file a bug report</ulink> against the
+documentation.
+</para>
+
+</answer>
+
+</qandaentry>
+
+
+<qandaentry>
+<question><para>
+How does memory management work in GTK+? Should I free data returned
+from functions?
+</para></question>
+
+<answer>
+
+<para>
+See the documentation for <link linkend="GObject">GObject</link> and
+<link linkend="GtkObject">GtkObject</link>. For <link
+linkend="GObject">GObject</link> note specifically <link
+linkend="g-object-ref">g_object_ref()</link> and <link
+linkend="g-object-unref">g_object_unref()</link>. <link
+linkend="GtkObject">GtkObject</link> is a subclass of <link
+linkend="GObject">GObject</link> so the same points apply, except that
+it has a "floating" state (explained in its documentation).
+</para>
+
+<para>
+For strings returned from functions, they will be declared "const"
+(using <link linkend="G-CONST-RETURN-CAPS">G_CONST_RETURN</link>) if they
+should not be freed. Non-const strings should be freed with <link
+linkend="g-free">g_free()</link>. Arrays follow the same rule. (If
+you find an exception to the rules, please report a bug to <ulink
+url="http://bugzilla.gnome.org">http://bugzilla.gnome.org</ulink>.)
+</para>
+
+</answer>
+
+</qandaentry>
+
+
+<qandaentry>
+<question><para>
+How do I use GTK+ with threads?
+</para></question>
+
+<answer>
+
+<para>
+This is covered in the
+<link linkend="gdk-Threads">GDK threads documentation</link>.
+See also the <link linkend="glib-Threads">GThread</link> documentation for portable
+threading primitives.
+</para>
+
+</answer>
+
+</qandaentry>
+
+</qandadiv>
+
+
+<qandadiv><title><link linkend="GtkWidget">GtkWidget</link></title>
+
+<qandaentry>
+<question><para>
+How do I change the color of a widget?
+</para></question>
+
+<answer><para>
+See <link linkend="gtk-widget-modify-fg">gtk_widget_modify_fg()</link>,
+<link linkend="gtk-widget-modify-bg">gtk_widget_modify_bg()</link>,
+<link linkend="gtk-widget-modify-base">gtk_widget_modify_base()</link>,
+and <link
+linkend="gtk-widget-modify-text">gtk_widget_modify_text()</link>. See
+<link linkend="gtk-Resource-Files">GTK+ resource files</link> for more
+discussion. You can also change widget color by installing a resource
+file and parsing it with <link
+linkend="gtk-rc-add-default-file">gtk_rc_add_default_file()</link>.
+The advantage of a resource file is that users can then override the
+color you've chosen.
+</para>
+
+<para>To change the background color for widgets such as <link
+linkend="GtkLabel">GtkLabel</link> that have no background, place them
+in a <link linkend="GtkEventBox">GtkEventBox</link> and set the
+background of the event box.
+</para></answer>
+</qandaentry>
+
+</qandadiv>
+
+
+<qandadiv><title><link linkend="GtkTextView">GtkTextView</link></title>
+
+<qandaentry>
+<question><para>
+How do I get the contents of the entire text widget as a string?
+</para></question>
+
+<answer><para>
+
+See <link
+ linkend="gtk-text-buffer-get-bounds">gtk_text_buffer_get_bounds()</link>
+ and <link
+ linkend="gtk-text-buffer-get-text">gtk_text_buffer_get_text()</link>
+or <link
+ linkend="gtk-text-iter-get-text">gtk_text_iter_get_text()</link>.
+</para>
+<para>
+<programlisting>
+ GtkTextIter start, end;
+ GtkTextBuffer *buffer;
+ char *text;
+
+ buffer = gtk_text_view_get_buffer (GTK_TEXT_VIEW (text_view));
+ gtk_text_buffer_get_bounds (buffer, &start, &end);
+ text = gtk_text_iter_get_text (&start, &end);
+ /* use text */
+ g_free (text);
+</programlisting>
+</para></answer>
+</qandaentry>
+
+</qandadiv>
+
+
+</qandaset>
+
+</refsect1>
+
+</refentry>
font and foreground color &mdash use standard
<link linkend="GtkWidget">GtkWidget</link>
functions such as
-<link linkend="gtk_widget_modify_font">gtk_widget_modify_font()</link>
+<link linkend="gtk-widget-modify-font">gtk_widget_modify_font()</link>
or
-<link linkend="gtk_widget_modify_fg">gtk_widget_modify_fg()</link>.
+<link linkend="gtk-widget-modify-fg">gtk_widget_modify_fg()</link>.
For other attributes there are dedicated methods on
<link linkend="GtkTextView">GtkTextView</link> such as
-<link linkend="gtk_text_view_set_tabs">gtk_text_view_set_tabs()</link>.
+<link linkend="gtk-text-view-set-tabs">gtk_text_view_set_tabs()</link>.
<programlisting>
GtkWidget *view;
the same process. Each clipboard is identified by a name encoded as a
#GdkAtom. (Conversion to and from strings can be done with
gdk_atom_intern() and gdk_atom_name().) The default clipboard
- corresponds to the CLIPBOARD atom; another commonly used clipboard
- is the PRIMARY clipboard, which, in X, traditionally contains
- the currently selected text.
+ corresponds to the "CLIPBOARD" atom; another commonly used clipboard
+ is the "PRIMARY" clipboard, which, in X, traditionally contains
+ the currently selected text.
</para>
<para>
To support having a number of different formats on the clipboard
<!-- ##### SECTION Long_Description ##### -->
<para>
-The #GtkDrawingArea widget is used for creating custom
-user interface elements. After creating a drawing
-area, the application may want to connect to:
+
+The #GtkDrawingArea widget is used for creating custom user interface
+elements. It's essentially a blank widget; you can draw on
+<literal>widget->window</literal>. After creating a drawing area,
+the application may want to connect to:
+
<itemizedlist>
<listitem>
<para>
<listitem>
<para>
The "realize" signal to take any necessary actions
- when the widget
+ when the widget is instantiated on a particular display.
+ (Create GDK resources in response to this signal.)
</para>
</listitem>
<listitem>
<para>
- The "size_allocate" signal to take any necessary actions
+ The "configure_event" signal to take any necessary actions
when the widget changes size.
</para>
</listitem>
</para>
</listitem>
</itemizedlist>
-As a convenience, the #GtkDrawingArea widget synthesizes
-a "configure_event" when the widget is realized
-and any time the size of a widget changes when it
-is realized. It often suffices to connect to this
-signal instead of "realize" and "size_allocate".
</para>
<para>
The following code portion demonstrates using a drawing
-area to implement a widget that draws a circle.
-As this example demonstrates, an expose handler should
-draw only the pixels within the requested area and
-should draw or clear all these pixels.
+area to display a circle in the normal widget foreground
+color.
+Note that GDK automatically clears the exposed area
+to the background color before sending the expose event, and
+that drawing is implicitly clipped to the exposed area.
</para>
<example>
<title>Simple <structname>GtkDrawingArea</structname> usage.</title>
<programlisting>
gboolean
-expose_event (GdkWidget *widget, GdkEventExpose *event, gpointer data)
+expose_event_callback (GdkWidget *widget, GdkEventExpose *event, gpointer data)
{
- gdk_window_clear_area (widget->window,
- event->area.x, event->area.y,
- event->area.width, event->area.height);
- gdk_gc_set_clip_rectangle (widget->style->fg_gc[widget->state],
- &event->area);
gdk_draw_arc (widget->window,
- widget->style->fg_gc[widget->state],
+ widget->style->fg_gc[GTK_WIDGET_STATE (widget)],
TRUE,
0, 0, widget->allocation.width, widget->allocation.height,
0, 64 * 360);
- gdk_gc_set_clip_rectangle (widget->style->fg_gc[widget->state],
- NULL);
-
+
return TRUE;
}
[...]
GtkWidget *drawing_area = gtk_drawing_area_new (<!>);
- gtk_signal_connect (GTK_OBJECT (drawing_area),
+ gtk_widget_set_size_request (drawing_area, 100, 100);
+ g_signal_connect (G_OBJECT (drawing_area), "expose_event",
+ G_CALLBACK (expose_event_callback), NULL);
</programlisting>
</example>
+<para>
+Expose events are normally delivered when a drawing area first comes
+onscreen, or when it's covered by another window and then uncovered
+(exposed). You can also force an expose event by adding to the "damage
+region" of the drawing area's window; gtk_widget_queue_draw_area() and
+gdk_window_invalidate_rect() are equally good ways to do this. You'll
+then get an expose event for the invalid region.
+</para>
+
<!-- ##### SECTION See_Also ##### -->
<para>
Manipulating stock icons
<!-- ##### SECTION Long_Description ##### -->
+
+
+<para>
+Browse the available stock icons in the list of stock IDs found <link
+linkend="gtk-Stock-Items">here</link>. You can also use
+the <application>gtk-demo</application> application for this purpose.
+</para>
+
<para>
An icon factory manages a collection of #GtkIconSet; a #GtkIconSet manages a
set of variants of a particular icon (i.e. a #GtkIconSet contains variants for
before delivering them normally.
</para>
-@snooper: a #GtkKeySnoopFunc.
+@snooper: a #GtkKeySnoopFunc.
@func_data: data to pass to @snooper.
@Returns: a unique id for this key snooper for use with gtk_key_snooper_remove().
They can be used to implement custom key event handling.
</para>
-@grab_widget: the widget to which the event will be delivered.
+@grab_widget: the widget to which the event will be delivered.
@event: the key event.
@func_data: the @func_data supplied to gtk_key_snooper_install().
@Returns: %TRUE to stop further processing of @event, %FALSE to continue.
<para>
</para>
-@menu:
+@menu:
@title:
GtkPreview
<!-- ##### SECTION Short_Description ##### -->
-a widget to display RGB or grayscale data.
+deprecated widget to display RGB or grayscale data.
<!-- ##### SECTION Long_Description ##### -->
<para>
The #GtkPreview widget provides a simple interface
used to display images as RGB or grayscale data.
+It's deprecated; just use a #GdkPixbuf displayed by a #GtkImage, or
+perhaps a #GtkDrawingArea. #GtkPreview has no advantage over those
+approaches.
</para>
<!-- ##### SECTION See_Also ##### -->
</para>
@scale: a #GtkScale.
-@draw_value: a boolean.
+@draw_value: a boolean.
<!-- ##### FUNCTION gtk_scale_set_value_pos ##### -->
GtkSeparator
<!-- ##### SECTION Short_Description ##### -->
-a base class for #GtkHSeparator and #GtkVseparator.
+a base class for #GtkHSeparator and #GtkVSeparator.
<!-- ##### SECTION Long_Description ##### -->
<para>
<!-- ##### SECTION Short_Description ##### -->
+Prebuilt common menu/toolbar items and corresponding icons
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+Stock items represent commonly-used menu or toolbar items such as
+"Open" or "Exit". Each stock item is identified by a stock ID;
+stock IDs are just strings, but macros such as #GTK_STOCK_OPEN are
+provided to avoid typing mistakes in the strings.
+Applications can register their own stock items in addition to those
+built-in to GTK+.
+</para>
+<para>
+Each stock ID can be associated with a #GtkStockItem, which contains
+the user-visible label, keyboard accelerator, and translation domain
+of the menu or toolbar item; and/or with an icon stored in a
+#GtkIconFactory. See <link
+linkend="gtk-Themeable-Stock-Images">GtkIconFactory</link> for
+more information on stock icons. The connection between a
+#GtkStockItem and stock icons is purely conventional (by virtue of
+using the same stock ID); it's possible to register a stock item but
+no icon, and vice versa.
</para>
<!-- ##### SECTION See_Also ##### -->
/**
* gtk_clipboard_get:
* @selection: a #GdkAtom which identifies the clipboard
- * to use. A value of %GDK_NONE here is the
- * same as <literal>gdk_atom_intern ("CLIPBOARD", FALSE)</literal>,
- * and provides the default clipboard. Another
- * common value is %GDK_SELECTION_PRIMARY, which
- * identifies the primary X selection.
+ * to use.
*
* Returns the clipboard object for the given selection.
+ * Cut/copy/paste menu items and keyboard shortcuts should use
+ * the default clipboard, returned by passing #GDK_NONE for @selection.
+ * The currently-selected object or text should be provided on the clipboard
+ * identified by #GDK_SELECTION_PRIMARY. Cut/copy/paste menu items
+ * conceptually copy the contents of the #GDK_SELECTION_PRIMARY clipboard
+ * to the default clipboard, i.e. they copy the selection to what the
+ * user sees as the clipboard.
+ *
+ * (Passing #GDK_NONE is the same as using <literal>gdk_atom_intern
+ * ("CLIPBOARD", FALSE)</literal>. See
+ * <ulink url="http://www.freedesktop.org/standards/clipboards.txt">
+ * http://www.freedesktop.org/standards/clipboards.txt</ulink>
+ * for a detailed discussion of the "CLIPBOARD" vs. "PRIMARY" selections
+ * under the X window system. On Win32 the #GDK_SELECTION_PRIMARY
+ * clipboard is essentially ignored.)
+ *
+ * It's possible to have arbitrary named clipboards; if you do invent
+ * new clipboards, you should prefix the selection name with an
+ * underscore (because the ICCCM requires that nonstandard atoms are
+ * underscore-prefixed), and namespace it as well. For example,
+ * if your application called "Foo" has a special-purpose
+ * clipboard, you might call it "_FOO_SPECIAL_CLIPBOARD".
*
* Return value: the appropriate clipboard object. If no
* clipboard already exists, a new one will
* be created. Once a clipboard object has
- * been created, it is persistent for all time.
+ * been created, it is persistent for all time and
+ * cannot be freed.
**/
GtkClipboard *
gtk_clipboard_get (GdkAtom selection)
* when obtaining the buffer contents as a string, will be represented
* by the Unicode "object replacement character" 0xFFFC. Note that the
* "slice" variants for obtaining portions of the buffer as a string
- * include this character for pixbufs, but the "text" variants do
+ * include this character for child anchors, but the "text" variants do
* not. e.g. see gtk_text_buffer_get_slice() and
* gtk_text_buffer_get_text(). Consider
* gtk_text_buffer_create_child_anchor() as a more convenient
*
* This is a convenience function which simply creates a child anchor
* with gtk_text_child_anchor_new() and inserts it into the buffer
- * with gtk_text_buffer_insert_child_anchor().
+ * with gtk_text_buffer_insert_child_anchor(). The new anchor is
+ * owned by the buffer; no reference count is returned to
+ * the caller of gtk_text_buffer_create_child_anchor().
*
* Return value: the created child anchor
**/
return gtk_text_buffer_get_mark (buffer, "selection_bound");
}
+/**
+ * gtk_text_buffer_get_iter_at_child_anchor:
+ * @buffer: a #GtkTextBuffer
+ * @iter: an iterator to be initialized
+ * @anchor: a child anchor that appears in @buffer
+ *
+ * Obtains the location of @anchor within @buffer.
+ *
+ **/
void
gtk_text_buffer_get_iter_at_child_anchor (GtkTextBuffer *buffer,
GtkTextIter *iter,
object_class->finalize = gtk_text_child_anchor_finalize;
}
+/**
+ * gtk_text_child_anchor_new:
+ *
+ * Creates a new #GtkTextChildAnchor. Usually you would then insert
+ * it into a #GtkTextBuffer with gtk_text_buffer_insert_child_anchor().
+ * To perform the creation and insertion in one step, use the
+ * convenience function gtk_text_buffer_create_child_anchor().
+ *
+ * Return value: a new #GtkTextChildAnchor
+ **/
GtkTextChildAnchor*
gtk_text_child_anchor_new (void)
{
anchor->segment = NULL;
}
+/**
+ * gtk_text_child_anchor_get_widgets:
+ * @anchor: a #GtkTextChildAnchor
+ *
+ * Gets a list of all widgets anchored at this child anchor.
+ * The returned list should be freed with g_list_free().
+ *
+ *
+ * Return value: list of widgets anchored at @anchor
+ **/
GList*
gtk_text_child_anchor_get_widgets (GtkTextChildAnchor *anchor)
{
return list;
}
+/**
+ * gtk_text_child_anchor_get_deleted:
+ * @anchor: a #GtkTextChildAnchor
+ *
+ * Determines whether a child anchor has been deleted from
+ * the buffer. Keep in mind that the child anchor will be
+ * unreferenced when removed from the buffer, so you need to
+ * hold your own reference (with g_object_ref()) if you plan
+ * to use this function — otherwise all deleted child anchors
+ * will also be finalized.
+ *
+ * Return value: %TRUE if the child anchor has been deleted from its buffer
+ **/
gboolean
gtk_text_child_anchor_get_deleted (GtkTextChildAnchor *anchor)
{
* gtk_text_mark_get_left_gravity:
* @mark: a #GtkTextMark
*
- *
+ * Determines whether the mark has left gravity.
*
* Return value: %TRUE if the mark has left gravity, %FALSE otherwise
**/
gtk_text_view_flush_scroll (text_view);
}
+/**
+ * gtk_text_view_scroll_mark_onscreen:
+ * @text_view: a #GtkTextView
+ * @mark: a mark in the buffer for @text_view
+ *
+ * Scrolls @text_view the minimum distance such that @mark is contained
+ * within the visible area of the widget.
+ *
+ **/
void
gtk_text_view_scroll_mark_onscreen (GtkTextView *text_view,
GtkTextMark *mark)
return text_view->editable;
}
+/**
+ * gtk_text_view_set_pixels_above_lines:
+ * @text_view: a #GtkTextView
+ * @pixels_above_lines: pixels above paragraphs
+ *
+ * Sets the default number of blank pixels above paragraphs in @text_view.
+ * Tags in the buffer for @text_view may override the defaults.
+ *
+ **/
void
gtk_text_view_set_pixels_above_lines (GtkTextView *text_view,
gint pixels_above_lines)
g_object_notify (G_OBJECT (text_view), "pixels_above_lines");
}
+/**
+ * gtk_text_view_get_pixels_above_lines:
+ * @text_view: a #GtkTextView
+ *
+ * Gets the default number of pixels to put above paragraphs.
+ *
+ * Return value: default number of pixels above paragraphs
+ **/
gint
gtk_text_view_get_pixels_above_lines (GtkTextView *text_view)
{
return text_view->pixels_above_lines;
}
+/**
+ * gtk_text_view_set_pixels_below_lines:
+ * @text_view: a #GtkTextView
+ * @pixels_below_lines: pixels below paragraphs
+ *
+ * Sets the default number of pixels of blank space
+ * to put below paragraphs in @text_view. May be overridden
+ * by tags applied to @text_view's buffer.
+ *
+ **/
void
gtk_text_view_set_pixels_below_lines (GtkTextView *text_view,
gint pixels_below_lines)
g_object_notify (G_OBJECT (text_view), "pixels_below_lines");
}
+/**
+ * gtk_text_view_get_pixels_below_lines:
+ * @text_view: a #GtkTextView
+ *
+ * Gets the value set by gtk_text_view_set_pixels_below_lines().
+ *
+ * Return value: default number of blank pixels below paragraphs
+ **/
gint
gtk_text_view_get_pixels_below_lines (GtkTextView *text_view)
{
return text_view->pixels_below_lines;
}
+/**
+ * gtk_text_view_set_pixels_inside_wrap:
+ * @text_view: a #GtkTextView
+ * @pixels_inside_wrap: default number of pixels between wrapped lines
+ *
+ * Sets the default number of pixels of blank space to leave between
+ * display/wrapped lines within a paragraph. May be overridden by
+ * tags in @text_view's buffer.
+ *
+ **/
void
gtk_text_view_set_pixels_inside_wrap (GtkTextView *text_view,
gint pixels_inside_wrap)
g_object_notify (G_OBJECT (text_view), "pixels_inside_wrap");
}
+/**
+ * gtk_text_view_get_pixels_inside_wrap:
+ * @text_view: a #GtkTextView
+ *
+ * Gets the value set by gtk_text_view_set_pixels_inside_wrap().
+ *
+ * Return value: default number of pixels of blank space between wrapped lines
+ **/
gint
gtk_text_view_get_pixels_inside_wrap (GtkTextView *text_view)
{
return text_view->pixels_inside_wrap;
}
+/**
+ * gtk_text_view_set_justification:
+ * @text_view: a #GtkTextView
+ * @justification: justification
+ *
+ * Sets the default justification of text in @text_view.
+ * Tags in the view's buffer may override the default.
+ *
+ **/
void
gtk_text_view_set_justification (GtkTextView *text_view,
- GtkJustification justify)
+ GtkJustification justification)
{
g_return_if_fail (GTK_IS_TEXT_VIEW (text_view));
- if (text_view->justify != justify)
+ if (text_view->justify != justification)
{
- text_view->justify = justify;
+ text_view->justify = justification;
if (text_view->layout)
{
- text_view->layout->default_style->justification = justify;
+ text_view->layout->default_style->justification = justification;
gtk_text_layout_default_style_changed (text_view->layout);
}
}
g_object_notify (G_OBJECT (text_view), "justification");
}
+/**
+ * gtk_text_view_get_justification:
+ * @text_view: a #GtkTextView
+ *
+ * Gets the default justification of paragraphs in @text_view.
+ * Tags in the buffer may override the default.
+ *
+ * Return value: default justification
+ **/
GtkJustification
gtk_text_view_get_justification (GtkTextView *text_view)
{
return text_view->justify;
}
+/**
+ * gtk_text_view_set_left_margin:
+ * @text_view: a #GtkTextView
+ * @left_margin: left margin in pixels
+ *
+ * Sets the default left margin for text in @text_view.
+ * Tags in the buffer may override the default.
+ *
+ **/
void
gtk_text_view_set_left_margin (GtkTextView *text_view,
gint left_margin)
g_object_notify (G_OBJECT (text_view), "left_margin");
}
+/**
+ * gtk_text_view_get_left_margin:
+ * @text_view: a #GtkTextView
+ *
+ * Gets the default left margin size of paragraphs in the @text_view.
+ * Tags in the buffer may override the default.
+ *
+ * Return value: left margin in pixels
+ **/
gint
gtk_text_view_get_left_margin (GtkTextView *text_view)
{
return text_view->left_margin;
}
+/**
+ * gtk_text_view_set_right_margin:
+ * @text_view: a #GtkTextView
+ * @right_margin: right margin in pixels
+ *
+ * Sets the default right margin for text in the text view.
+ * Tags in the buffer may override the default.
+ *
+ **/
void
gtk_text_view_set_right_margin (GtkTextView *text_view,
gint right_margin)
g_object_notify (G_OBJECT (text_view), "right_margin");
}
+/**
+ * gtk_text_view_get_right_margin:
+ * @text_view: a #GtkTextView
+ *
+ * Gets the default right margin for text in @text_view. Tags
+ * in the buffer may override the default.
+ *
+ * Return value: right margin in pixels
+ **/
gint
gtk_text_view_get_right_margin (GtkTextView *text_view)
{
return text_view->right_margin;
}
+/**
+ * gtk_text_view_set_indent:
+ * @text_view: a #GtkTextView
+ * @indent: indentation in pixels
+ *
+ * Sets the default indentation for paragraphs in @text_view.
+ * Tags in the buffer may override the default.
+ *
+ **/
void
gtk_text_view_set_indent (GtkTextView *text_view,
gint indent)
g_object_notify (G_OBJECT (text_view), "indent");
}
+/**
+ * gtk_text_view_get_indent:
+ * @text_view: a #GtkTextView
+ *
+ * Gets the default indentation of paragraphs in @text_view.
+ * Tags in the view's buffer may override the default.
+ * The indentation may be negative.
+ *
+ * Return value: number of pixels of indentation
+ **/
gint
gtk_text_view_get_indent (GtkTextView *text_view)
{
return text_view->indent;
}
+/**
+ * gtk_text_view_set_tabs:
+ * @text_view: a #GtkTextView
+ * @tabs: tabs as a #PangoTabArray
+ *
+ * Sets the default tab stops for paragraphs in @text_view.
+ * Tags in the buffer may override the default.
+ *
+ **/
void
gtk_text_view_set_tabs (GtkTextView *text_view,
PangoTabArray *tabs)
g_object_notify (G_OBJECT (text_view), "tabs");
}
+/**
+ * gtk_text_view_get_tabs:
+ * @text_view: a #GtkTextView
+ *
+ * Gets the default tabs for @text_view. Tags in the buffer may
+ * override the defaults. The returned array will be %NULL if
+ * "standard" (8-space) tabs are used. Free the return value
+ * with pango_tab_array_free().
+ *
+ * Return value: copy of default tab array, or %NULL if "standard" tabs are used; must be freed with pango_tab_array_free().
+ **/
PangoTabArray*
gtk_text_view_get_tabs (GtkTextView *text_view)
{
gtk_widget_set_parent (vc->widget, GTK_WIDGET (text_view));
}
+/**
+ * gtk_text_view_add_child_at_anchor:
+ * @text_view: a #GtkTextView
+ * @child: a #GtkWidget
+ * @anchor: a #GtkTextChildAnchor in the #GtkTextBuffer for @text_view
+ *
+ * Adds a child widget in the text buffer, at the given @anchor.
+ *
+ **/
void
gtk_text_view_add_child_at_anchor (GtkTextView *text_view,
GtkWidget *child,
/* Iterator operations */
+/**
+ * gtk_text_view_forward_display_line:
+ * @text_view: a #GtkTextView
+ * @iter: a #GtkTextIter
+ *
+ * Moves the given @iter forward by one display (wrapped) line. A
+ * display line is different from a paragraph. Paragraphs are
+ * separated by newlines or other paragraph separator characters.
+ * Display lines are created by line-wrapping a paragraph. If
+ * wrapping is turned off, display lines and paragraphs will be the
+ * same. Display lines are divided differently for each view, since
+ * they depend on the view's width; paragraphs are the same in all
+ * views, since they depend on the contents of the #GtkTextBuffer.
+ *
+ * Return value: %TRUE if @iter was moved and is not on the end iterator
+ **/
gboolean
gtk_text_view_forward_display_line (GtkTextView *text_view,
GtkTextIter *iter)
return gtk_text_layout_move_iter_to_next_line (text_view->layout, iter);
}
+/**
+ * gtk_text_view_backward_display_line:
+ * @text_view: a #GtkTextView
+ * @iter: a #GtkTextIter
+ *
+ * Moves the given @iter backward by one display (wrapped) line. A
+ * display line is different from a paragraph. Paragraphs are
+ * separated by newlines or other paragraph separator characters.
+ * Display lines are created by line-wrapping a paragraph. If
+ * wrapping is turned off, display lines and paragraphs will be the
+ * same. Display lines are divided differently for each view, since
+ * they depend on the view's width; paragraphs are the same in all
+ * views, since they depend on the contents of the #GtkTextBuffer.
+ *
+ * Return value: %TRUE if @iter was moved and is not on the end iterator
+ **/
gboolean
gtk_text_view_backward_display_line (GtkTextView *text_view,
GtkTextIter *iter)
return gtk_text_layout_move_iter_to_previous_line (text_view->layout, iter);
}
+/**
+ * gtk_text_view_forward_display_line_end:
+ * @text_view: a #GtkTextView
+ * @iter: a #GtkTextIter
+ *
+ * Moves the given @iter forward to the next display line end. A
+ * display line is different from a paragraph. Paragraphs are
+ * separated by newlines or other paragraph separator characters.
+ * Display lines are created by line-wrapping a paragraph. If
+ * wrapping is turned off, display lines and paragraphs will be the
+ * same. Display lines are divided differently for each view, since
+ * they depend on the view's width; paragraphs are the same in all
+ * views, since they depend on the contents of the #GtkTextBuffer.
+ *
+ * Return value: %TRUE if @iter was moved and is not on the end iterator
+ **/
gboolean
gtk_text_view_forward_display_line_end (GtkTextView *text_view,
GtkTextIter *iter)
return gtk_text_layout_move_iter_to_line_end (text_view->layout, iter, 1);
}
+/**
+ * gtk_text_view_backward_display_line_start:
+ * @text_view: a #GtkTextView
+ * @iter: a #GtkTextIter
+ *
+ * Moves the given @iter backward to the next display line start. A
+ * display line is different from a paragraph. Paragraphs are
+ * separated by newlines or other paragraph separator characters.
+ * Display lines are created by line-wrapping a paragraph. If
+ * wrapping is turned off, display lines and paragraphs will be the
+ * same. Display lines are divided differently for each view, since
+ * they depend on the view's width; paragraphs are the same in all
+ * views, since they depend on the contents of the #GtkTextBuffer.
+ *
+ * Return value: %TRUE if @iter was moved and is not on the end iterator
+ **/
gboolean
gtk_text_view_backward_display_line_start (GtkTextView *text_view,
GtkTextIter *iter)
return gtk_text_layout_move_iter_to_line_end (text_view->layout, iter, -1);
}
+/**
+ * gtk_text_view_starts_display_line:
+ * @text_view: a #GtkTextView
+ * @iter: a #GtkTextIter
+ *
+ * Determines whether @iter is at the start of a display line.
+ * See gtk_text_view_forward_display_line() for an explanation of
+ * display lines vs. paragraphs.
+ *
+ * Return value: %TRUE if @iter begins a wrapped line
+ **/
gboolean
gtk_text_view_starts_display_line (GtkTextView *text_view,
const GtkTextIter *iter)
return gtk_text_layout_iter_starts_line (text_view->layout, iter);
}
+/**
+ * gtk_text_view_move_visually:
+ * @text_view: a #GtkTextView
+ * @iter: a #GtkTextIter
+ * @count: number of lines to move
+ *
+ * Moves @iter up or down by @count display (wrapped) lines.
+ * See gtk_text_view_forward_display_line() for an explanation of
+ * display lines vs. paragraphs.
+ *
+ * Return value: %TRUE if @iter moved and is not on the end iterator
+ **/
gboolean
gtk_text_view_move_visually (GtkTextView *text_view,
GtkTextIter *iter,
projects / ~andy / gtk / commitdiff