Commit 30cc1512 authored by Matthias Clasen's avatar Matthias Clasen

Docs: Use markdown for lists

This greatly reduces the amount of xml in the docs.
parent 09d1b282
......@@ -224,62 +224,24 @@ gdk_cursor_get_cursor_type (GdkCursor *cursor)
*
* Creates a new cursor from the set of builtin cursors.
* Some useful ones are:
* <itemizedlist>
* <listitem><para>
* <inlinegraphic format="PNG" fileref="right_ptr.png"></inlinegraphic> #GDK_RIGHT_PTR (right-facing arrow)
* </para></listitem>
* <listitem><para>
* <inlinegraphic format="PNG" fileref="crosshair.png"></inlinegraphic> #GDK_CROSSHAIR (crosshair)
* </para></listitem>
* <listitem><para>
* <inlinegraphic format="PNG" fileref="xterm.png"></inlinegraphic> #GDK_XTERM (I-beam)
* </para></listitem>
* <listitem><para>
* <inlinegraphic format="PNG" fileref="watch.png"></inlinegraphic> #GDK_WATCH (busy)
* </para></listitem>
* <listitem><para>
* <inlinegraphic format="PNG" fileref="fleur.png"></inlinegraphic> #GDK_FLEUR (for moving objects)
* </para></listitem>
* <listitem><para>
* <inlinegraphic format="PNG" fileref="hand1.png"></inlinegraphic> #GDK_HAND1 (a right-pointing hand)
* </para></listitem>
* <listitem><para>
* <inlinegraphic format="PNG" fileref="hand2.png"></inlinegraphic> #GDK_HAND2 (a left-pointing hand)
* </para></listitem>
* <listitem><para>
* <inlinegraphic format="PNG" fileref="left_side.png"></inlinegraphic> #GDK_LEFT_SIDE (resize left side)
* </para></listitem>
* <listitem><para>
* <inlinegraphic format="PNG" fileref="right_side.png"></inlinegraphic> #GDK_RIGHT_SIDE (resize right side)
* </para></listitem>
* <listitem><para>
* <inlinegraphic format="PNG" fileref="top_left_corner.png"></inlinegraphic> #GDK_TOP_LEFT_CORNER (resize northwest corner)
* </para></listitem>
* <listitem><para>
* <inlinegraphic format="PNG" fileref="top_right_corner.png"></inlinegraphic> #GDK_TOP_RIGHT_CORNER (resize northeast corner)
* </para></listitem>
* <listitem><para>
* <inlinegraphic format="PNG" fileref="bottom_left_corner.png"></inlinegraphic> #GDK_BOTTOM_LEFT_CORNER (resize southwest corner)
* </para></listitem>
* <listitem><para>
* <inlinegraphic format="PNG" fileref="bottom_right_corner.png"></inlinegraphic> #GDK_BOTTOM_RIGHT_CORNER (resize southeast corner)
* </para></listitem>
* <listitem><para>
* <inlinegraphic format="PNG" fileref="top_side.png"></inlinegraphic> #GDK_TOP_SIDE (resize top side)
* </para></listitem>
* <listitem><para>
* <inlinegraphic format="PNG" fileref="bottom_side.png"></inlinegraphic> #GDK_BOTTOM_SIDE (resize bottom side)
* </para></listitem>
* <listitem><para>
* <inlinegraphic format="PNG" fileref="sb_h_double_arrow.png"></inlinegraphic> #GDK_SB_H_DOUBLE_ARROW (move vertical splitter)
* </para></listitem>
* <listitem><para>
* <inlinegraphic format="PNG" fileref="sb_v_double_arrow.png"></inlinegraphic> #GDK_SB_V_DOUBLE_ARROW (move horizontal splitter)
* </para></listitem>
* <listitem><para>
* #GDK_BLANK_CURSOR (Blank cursor). Since 2.16
* </para></listitem>
* </itemizedlist>
* - <inlinegraphic format="PNG" fileref="right_ptr.png"></inlinegraphic> #GDK_RIGHT_PTR (right-facing arrow)
* - <inlinegraphic format="PNG" fileref="crosshair.png"></inlinegraphic> #GDK_CROSSHAIR (crosshair)
* - <inlinegraphic format="PNG" fileref="xterm.png"></inlinegraphic> #GDK_XTERM (I-beam)
* - <inlinegraphic format="PNG" fileref="watch.png"></inlinegraphic> #GDK_WATCH (busy)
* - <inlinegraphic format="PNG" fileref="fleur.png"></inlinegraphic> #GDK_FLEUR (for moving objects)
* - <inlinegraphic format="PNG" fileref="hand1.png"></inlinegraphic> #GDK_HAND1 (a right-pointing hand)
* - <inlinegraphic format="PNG" fileref="hand2.png"></inlinegraphic> #GDK_HAND2 (a left-pointing hand)
* - <inlinegraphic format="PNG" fileref="left_side.png"></inlinegraphic> #GDK_LEFT_SIDE (resize left side)
* - <inlinegraphic format="PNG" fileref="right_side.png"></inlinegraphic> #GDK_RIGHT_SIDE (resize right side)
* - <inlinegraphic format="PNG" fileref="top_left_corner.png"></inlinegraphic> #GDK_TOP_LEFT_CORNER (resize northwest corner)
* - <inlinegraphic format="PNG" fileref="top_right_corner.png"></inlinegraphic> #GDK_TOP_RIGHT_CORNER (resize northeast corner)
* - <inlinegraphic format="PNG" fileref="bottom_left_corner.png"></inlinegraphic> #GDK_BOTTOM_LEFT_CORNER (resize southwest corner)
* - <inlinegraphic format="PNG" fileref="bottom_right_corner.png"></inlinegraphic> #GDK_BOTTOM_RIGHT_CORNER (resize southeast corner)
* - <inlinegraphic format="PNG" fileref="top_side.png"></inlinegraphic> #GDK_TOP_SIDE (resize top side)
* - <inlinegraphic format="PNG" fileref="bottom_side.png"></inlinegraphic> #GDK_BOTTOM_SIDE (resize bottom side)
* - <inlinegraphic format="PNG" fileref="sb_h_double_arrow.png"></inlinegraphic> #GDK_SB_H_DOUBLE_ARROW (move vertical splitter)
* - <inlinegraphic format="PNG" fileref="sb_v_double_arrow.png"></inlinegraphic> #GDK_SB_V_DOUBLE_ARROW (move horizontal splitter)
* - #GDK_BLANK_CURSOR (Blank cursor). Since 2.16
*
* Return value: a new #GdkCursor
*
......
......@@ -44,15 +44,10 @@
* @Title: GdkDisplay
*
* #GdkDisplay objects purpose are two fold:
* <itemizedlist>
* <listitem>
* To manage and provide information about input devices (pointers
* and keyboards)
* </listitem>
* <listitem>
* To manage and provide information about the available #GdkScreens
* </listitem>
* </itemizedlist>
*
* - To manage and provide information about input devices (pointers and keyboards)
*
* - To manage and provide information about the available #GdkScreens
*
* GdkDisplay objects are the GDK representation of an X Display,
* which can be described as a workstation consisting of
......
......@@ -141,22 +141,12 @@ parse_rgb_value (const gchar *str,
* the @red, @green, @blue and @alpha fields of the @rgba #GdkRGBA.
*
* The string can be either one of:
* <itemizedlist>
* <listitem>
* A standard name (Taken from the X11 rgb.txt file).
* </listitem>
* <listitem>
* A hex value in the form '&num;rgb' '&num;rrggbb' '&num;rrrgggbbb'
* or '&num;rrrrggggbbbb'
* </listitem>
* <listitem>
* A RGB color in the form 'rgb(r,g,b)' (In this case the color will
* have full opacity)
* </listitem>
* <listitem>
* A RGBA color in the form 'rgba(r,g,b,a)'
* </listitem>
* </itemizedlist>
* - A standard name (Taken from the X11 rgb.txt file).
* - A hex value in the form '&num;rgb' '&num;rrggbb' '&num;rrrgggbbb'
* or '&num;rrrrggggbbbb'
* - A RGB color in the form 'rgb(r,g,b)' (In this case the color will
* have full opacity)
* - A RGBA color in the form 'rgba(r,g,b,a)'
*
* Where 'r', 'g', 'b' and 'a' are respectively the red, green, blue and
* alpha color values. In the last two cases, r g and b are either integers
......
......@@ -38,34 +38,19 @@
* elements. It's essentially a blank widget; you can draw on it. After
* creating a drawing area, the application may want to connect to:
*
* <itemizedlist>
* <listitem>
* <para>
* Mouse and button press signals to respond to input from
* the user. (Use gtk_widget_add_events() to enable events
* you wish to receive.)
* </para>
* </listitem>
* <listitem>
* <para>
* The #GtkWidget::realize signal to take any necessary actions
* when the widget is instantiated on a particular display.
* (Create GDK resources in response to this signal.)
* </para>
* </listitem>
* <listitem>
* <para>
* The #GtkWidget::configure-event signal to take any necessary
* actions when the widget changes size.
* </para>
* </listitem>
* <listitem>
* <para>
* The #GtkWidget::draw signal to handle redrawing the
* contents of the widget.
* </para>
* </listitem>
* </itemizedlist>
* - Mouse and button press signals to respond to input from
* the user. (Use gtk_widget_add_events() to enable events
* you wish to receive.)
*
* - The #GtkWidget::realize signal to take any necessary actions
* when the widget is instantiated on a particular display.
* (Create GDK resources in response to this signal.)
*
* - The #GtkWidget::configure-event signal to take any necessary
* actions when the widget changes size.
*
* - The #GtkWidget::draw signal to handle redrawing the
* contents of the widget.
*
* The following code portion demonstrates using a drawing
* area to display a circle in the normal widget foreground
......
......@@ -1599,11 +1599,9 @@ gtk_entry_class_init (GtkEntryClass *class)
* the variant with the Shift modifier extends the selection,
* the variant without the Shift modifer does not.
* There are too many key combinations to list them all here.
* <itemizedlist>
* <listitem>Arrow keys move by individual characters/lines</listitem>
* <listitem>Ctrl-arrow key combinations move by words/paragraphs</listitem>
* <listitem>Home/End keys move to the ends of the buffer</listitem>
* </itemizedlist>
* - Arrow keys move by individual characters/lines
* - Ctrl-arrow key combinations move by words/paragraphs
* - Home/End keys move to the ends of the buffer
*/
signals[MOVE_CURSOR] =
g_signal_new (I_("move-cursor"),
......
......@@ -110,26 +110,23 @@
* ]|
* </para>
* </example>
* <section id="gtkfilechooserdialog-setting-up">
* <title>Setting up a file chooser dialog</title>
*
* ## Setting up a file chooser dialog
*
* <para id="gtkfilechooserdialog-setting-up">
* There are various cases in which you may need to use a #GtkFileChooserDialog:
* <itemizedlist><listitem>To select a file for opening. Use
* #GTK_FILE_CHOOSER_ACTION_OPEN.
* </listitem>
* <listitem>To save a file for the first time. Use
* #GTK_FILE_CHOOSER_ACTION_SAVE, and suggest a name such as
* "Untitled" with gtk_file_chooser_set_current_name().
* </listitem>
* <listitem>To save a file under a different name. Use
* #GTK_FILE_CHOOSER_ACTION_SAVE, and set the existing filename
* with gtk_file_chooser_set_filename().
* </listitem>
* <listitem>To choose a folder instead of a file. Use
* #GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER.
* </listitem></itemizedlist>
* <note>
* <para>
* Old versions of the file chooser's documentation suggested
*
* - To select a file for opening. Use #GTK_FILE_CHOOSER_ACTION_OPEN.
*
* - To save a file for the first time. Use #GTK_FILE_CHOOSER_ACTION_SAVE,
* and suggest a name such as "Untitled" with gtk_file_chooser_set_current_name().
*
* - To save a file under a different name. Use #GTK_FILE_CHOOSER_ACTION_SAVE,
* and set the existing filename with gtk_file_chooser_set_filename().
*
* - To choose a folder instead of a file. Use #GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER.
*
* Note that old versions of the file chooser's documentation suggested
* using gtk_file_chooser_set_current_folder() in various
* situations, with the intention of letting the application
* suggest a reasonable default folder. This is no longer
......@@ -139,16 +136,14 @@
* when it is appropriate to use gtk_file_chooser_set_filename(),
* i.e. when you are doing a Save As command and you already
* have a file saved somewhere.
* </para>
* </note>
* </section>
* <section id="gtkfilechooserdialog-response-codes">
* <title>Response Codes</title>
*
* ## Response Codes
*
* <para id="gtkfilechooserdialog-response-codes">
* #GtkFileChooserDialog inherits from #GtkDialog, so buttons that
* go in its action area have response codes such as
* #GTK_RESPONSE_ACCEPT and #GTK_RESPONSE_CANCEL. For example, you
* could call gtk_file_chooser_dialog_new() as follows:
* <para>
* |[
* GtkWidget *dialog;
*
......@@ -160,6 +155,8 @@
* NULL);
* ]|
* </para>
*
* <para id="gtkfilechooserdialog-responses">
* This will create buttons for "Cancel" and "Open" that use stock
* response identifiers from #GtkResponseType. For most dialog
* boxes you can use your own custom response codes rather than the
......@@ -167,27 +164,21 @@
* its "accept"-type action, e.g. an "Open" or "Save" button,
* will have one of the following response
* codes:
* <para>
* <simplelist id="gtkfilechooserdialog-responses">
* <member>#GTK_RESPONSE_ACCEPT</member>
* <member>#GTK_RESPONSE_OK</member>
* <member>#GTK_RESPONSE_YES</member>
* <member>#GTK_RESPONSE_APPLY</member>
* </simplelist>
* - #GTK_RESPONSE_ACCEPT
* - #GTK_RESPONSE_OK
* - #GTK_RESPONSE_YES
* - #GTK_RESPONSE_APPLY
* </para>
*
* This is because #GtkFileChooserDialog must intercept responses
* and switch to folders if appropriate, rather than letting the
* dialog terminate &mdash; the implementation uses these known
* response codes to know which responses can be blocked if
* appropriate.
* <para>
* <note>
*
* To summarize, make sure you use a
* <link linkend="gtkfilechooserdialog-responses">stock response code</link>
* when you use #GtkFileChooserDialog to ensure proper operation.
* </note>
* </para>
* </section>
*/
......
......@@ -37,23 +37,18 @@
* results in broken applications. With #GtkFixed, the following
* things will result in truncated text, overlapping widgets, and
* other display bugs:
* <itemizedlist>
* <listitem><para>
* Themes, which may change widget sizes.
* </para></listitem>
* <listitem><para>
* Fonts other than the one you used to write the app will of course
*
* - Themes, which may change widget sizes.
*
* - Fonts other than the one you used to write the app will of course
* change the size of widgets containing text; keep in mind that
* users may use a larger font because of difficulty reading the
* default, or they may be using Windows or the framebuffer port of
* GTK+, where different fonts are available.
* </para></listitem>
* <listitem><para>
* Translation of text into other languages changes its size. Also,
*
* - Translation of text into other languages changes its size. Also,
* display of non-English text will use a different font in many
* cases.
* </para></listitem>
* </itemizedlist>
*
* In addition, the fixed widget can't properly be mirrored in
* right-to-left languages such as Hebrew and Arabic. i.e. normally
......
......@@ -3841,11 +3841,9 @@ gtk_flow_box_class_init (GtkFlowBoxClass *class)
* the variant with the Shift modifier extends the selection,
* the variant without the Shift modifer does not.
* There are too many key combinations to list them all here.
* <itemizedlist>
* <listitem>Arrow keys move by individual children</listitem>
* <listitem>Home/End keys move to the ends of the box</listitem>
* <listitem>PageUp/PageDown keys move vertically by pages</listitem>
* </itemizedlist>
* - Arrow keys move by individual children
* - Home/End keys move to the ends of the box
* - PageUp/PageDown keys move vertically by pages
*/
signals[MOVE_CURSOR] = g_signal_new ("move-cursor",
GTK_TYPE_FLOW_BOX,
......
......@@ -80,27 +80,23 @@
* Named icons are similar to the <xref linkend="gtk3-Themeable-Stock-Images"/>
* facility, and the distinction between the two may be a bit confusing.
* A few things to keep in mind:
* <itemizedlist>
* <listitem>
* Stock images usually are used in conjunction with
* <xref linkend="gtk3-Stock-Items"/>, such as %GTK_STOCK_OK or
* %GTK_STOCK_OPEN. Named icons are easier to set up and therefore
* are more useful for new icons that an application wants to
* add, such as application icons or window icons.
* </listitem>
* <listitem>
* Stock images can only be loaded at the symbolic sizes defined
* by the #GtkIconSize enumeration, or by custom sizes defined
* by gtk_icon_size_register(), while named icons are more flexible
* and any pixel size can be specified.
* </listitem>
* <listitem>
* Because stock images are closely tied to stock items, and thus
* to actions in the user interface, stock images may come in
* multiple variants for different widget states or writing
* directions.
* </listitem>
* </itemizedlist>
*
* - Stock images usually are used in conjunction with
* <xref linkend="gtk3-Stock-Items"/>, such as %GTK_STOCK_OK or
* %GTK_STOCK_OPEN. Named icons are easier to set up and therefore
* are more useful for new icons that an application wants to
* add, such as application icons or window icons.
*
* - Stock images can only be loaded at the symbolic sizes defined
* by the #GtkIconSize enumeration, or by custom sizes defined
* by gtk_icon_size_register(), while named icons are more flexible
* and any pixel size can be specified.
*
* - Because stock images are closely tied to stock items, and thus
* to actions in the user interface, stock images may come in
* multiple variants for different widget states or writing
* directions.
*
* A good rule of thumb is that if there is a stock image for what
* you want to use, use it, otherwise use a named icon. It turns
* out that internally stock images are generally defined in
......
......@@ -849,12 +849,9 @@ gtk_icon_view_class_init (GtkIconViewClass *klass)
* programmatically.
*
* The default bindings for this signal include
* <itemizedlist>
* <listitem>Arrow keys which move by individual steps</listitem>
* <listitem>Home/End keys which move to the first/last item</listitem>
* <listitem>PageUp/PageDown which move by "pages"</listitem>
* </itemizedlist>
*
* - Arrow keys which move by individual steps
* - Home/End keys which move to the first/last item
* - PageUp/PageDown which move by "pages"
* All of these will extend the selection when combined with
* the Shift modifier.
*/
......
......@@ -593,10 +593,9 @@ gtk_label_class_init (GtkLabelClass *class)
* the variant with the Shift modifier extends the selection,
* the variant without the Shift modifer does not.
* There are too many key combinations to list them all here.
* <itemizedlist>
* <listitem>Arrow keys move by individual characters/lines</listitem>
* <listitem>Ctrl-arrow key combinations move by words/paragraphs</listitem>
* <listitem>Home/End keys move to the ends of the buffer</listitem>
* - Arrow keys move by individual characters/lines
* - Ctrl-arrow key combinations move by words/paragraphs
* - Home/End keys move to the ends of the buffer
* </itemizedlist>
*/
signals[MOVE_CURSOR] =
......
......@@ -1467,51 +1467,33 @@ rewrite_event_for_grabs (GdkEvent *event)
* know how exactly events are handled. So here is what this function
* does with the event:
*
* <orderedlist>
* <listitem><para>
* Compress enter/leave notify events. If the event passed build an
* enter/leave pair together with the next event (peeked from GDK), both
* events are thrown away. This is to avoid a backlog of (de-)highlighting
* widgets crossed by the pointer.
* </para></listitem>
* <listitem><para>
* Find the widget which got the event. If the widget can't be determined
* the event is thrown away unless it belongs to a INCR transaction.
* </para></listitem>
* <listitem><para>
* Then the event is pushed onto a stack so you can query the currently
* handled event with gtk_get_current_event().
* </para></listitem>
* <listitem><para>
* The event is sent to a widget. If a grab is active all events for widgets
* that are not in the contained in the grab widget are sent to the latter
* with a few exceptions:
* <itemizedlist>
* <listitem><para>
* Deletion and destruction events are still sent to the event widget for
* obvious reasons.
* </para></listitem>
* <listitem><para>
* Events which directly relate to the visual representation of the event
* widget.
* </para></listitem>
* <listitem><para>
* Leave events are delivered to the event widget if there was an enter
* event delivered to it before without the paired leave event.
* </para></listitem>
* <listitem><para>
* Drag events are not redirected because it is unclear what the semantics
* of that would be.
* </para></listitem>
* </itemizedlist>
* Another point of interest might be that all key events are first passed
* through the key snooper functions if there are any. Read the description
* of gtk_key_snooper_install() if you need this feature.
* </para></listitem>
* <listitem><para>
* After finishing the delivery the event is popped from the event stack.
* </para></listitem>
* </orderedlist>
* 1. Compress enter/leave notify events. If the event passed build an
* enter/leave pair together with the next event (peeked from GDK), both
* events are thrown away. This is to avoid a backlog of (de-)highlighting
* widgets crossed by the pointer.
*
* 2. Find the widget which got the event. If the widget can't be determined
* the event is thrown away unless it belongs to a INCR transaction.
*
* 3. Then the event is pushed onto a stack so you can query the currently
* handled event with gtk_get_current_event().
*
* 4. The event is sent to a widget. If a grab is active all events for widgets
* that are not in the contained in the grab widget are sent to the latter
* with a few exceptions:
* - Deletion and destruction events are still sent to the event widget for
* obvious reasons.
* - Events which directly relate to the visual representation of the event
* widget.
* - Leave events are delivered to the event widget if there was an enter
* event delivered to it before without the paired leave event.
* - Drag events are not redirected because it is unclear what the semantics
* of that would be.
* Another point of interest might be that all key events are first passed
* through the key snooper functions if there are any. Read the description
* of gtk_key_snooper_install() if you need this feature.
*
* 5. After finishing the delivery the event is popped from the event stack.
*/
void
gtk_main_do_event (GdkEvent *event)
......
......@@ -37,11 +37,9 @@
* need to install gvfs to get support for uri schemes such as http://
* or ftp://, as only local files are handled by GIO itself).
* Typical examples are
* <simplelist>
* <member><filename>file:///home/gnome/pict.jpg</filename></member>
* <member><filename>http://www.gnome.org</filename></member>
* <member><filename>mailto:me&commat;gnome.org</filename></member>
* </simplelist>
* - <filename>file:///home/gnome/pict.jpg</filename>
* - <filename>http://www.gnome.org</filename>
* - <filename>mailto:me&commat;gnome.org</filename>
* Ideally the timestamp is taken from the event triggering
* the gtk_show_uri() call. If timestamp is not known you can take
* %GDK_CURRENT_TIME.
......
......@@ -940,13 +940,11 @@ gtk_text_view_class_init (GtkTextViewClass *klass)
* the variant with the Shift modifier extends the selection,
* the variant without the Shift modifer does not.
* There are too many key combinations to list them all here.
* <itemizedlist>
* <listitem>Arrow keys move by individual characters/lines</listitem>
* <listitem>Ctrl-arrow key combinations move by words/paragraphs</listitem>
* <listitem>Home/End keys move to the ends of the buffer</listitem>
* <listitem>PageUp/PageDown keys move vertically by pages</listitem>
* <listitem>Ctrl-PageUp/PageDown keys move horizontally by pages</listitem>
* </itemizedlist>
* - Arrow keys move by individual characters/lines
* - Ctrl-arrow key combinations move by words/paragraphs
* - Home/End keys move to the ends of the buffer
* - PageUp/PageDown keys move vertically by pages
* - Ctrl-PageUp/PageDown keys move horizontally by pages
*/
signals[MOVE_CURSOR] =
g_signal_new (I_("move-cursor"),
......
......@@ -37,22 +37,7 @@
* SECTION:gtktoolitem
* @short_description: The base class of widgets that can be added to GtkToolShell
* @Title: GtkToolItem
* @see_also: <variablelist>
* <varlistentry>
* <term>#GtkToolbar</term>
* <listitem><para>The toolbar widget</para></listitem>
* </varlistentry>
* <varlistentry>
* <term>#GtkToolButton</term>
* <listitem><para>A subclass of #GtkToolItem that displays buttons on
* the toolbar</para></listitem>
* </varlistentry>
* <varlistentry>
* <term>#GtkSeparatorToolItem</term>
* <listitem><para>A subclass of #GtkToolItem that separates groups of
* items on a toolbar</para></listitem>
* </varlistentry>
* </variablelist>
* @see_also: #GtkToolbar, #GtkToolButton, #GtkSeparatorToolItem
*
* #GtkToolItem<!-- -->s are widgets that can appear on a toolbar. To
* create a toolbar item that contain something else than a button, use
......@@ -221,20 +206,17 @@ gtk_tool_item_class_init (GtkToolItemClass *klass)
* This signal is emitted when the toolbar needs information from @tool_item
* about whether the item should appear in the toolbar overflow menu. In
* response the tool item should either
* <itemizedlist>
* <listitem>call gtk_tool_item_set_proxy_menu_item() with a %NULL
* pointer and return %TRUE to indicate that the item should not appear
* in the overflow menu
* </listitem>
* <listitem> call gtk_tool_item_set_proxy_menu_item() with a new menu
* item and return %TRUE, or
* </listitem>
* <listitem> return %FALSE to indicate that the signal was not
* handled by the item. This means that
* the item will not appear in the overflow menu unless a later handler
* installs a menu item.
* </listitem>
* </itemizedlist>
*
* - call gtk_tool_item_set_proxy_menu_item() with a %NULL
* pointer and return %TRUE to indicate that the item should not appear
* in the overflow menu
*
* - call gtk_tool_item_set_proxy_menu_item() with a new menu
* item and return %TRUE, or
*
* - return %FALSE to indicate that the signal was not handled by the item.
* This means that the item will not appear in the overflow menu unless
* a later handler installs a menu item.
*
* The toolbar may cache the result of this signal. When the tool item changes
* how it will respond to this signal it must call gtk_tool_item_rebuild_menu()
......@@ -259,12 +241,10 @@ gtk_tool_item_class_init (GtkToolItemClass *klass)
* This signal is emitted when some property of the toolbar that the
* item is a child of changes. For custom subclasses of #GtkToolItem,
* the default handler of this signal use the functions
* <itemizedlist>
* <listitem>gtk_tool_shell_get_orientation()</listitem>
* <listitem>gtk_tool_shell_get_style()</listitem>
* <listitem>gtk_tool_shell_get_icon_size()</listitem>
* <listitem>gtk_tool_shell_get_relief_style()</listitem>
* </itemizedlist>
* - gtk_tool_shell_get_orientation()
* - gtk_tool_shell_get_style()
* - gtk_tool_shell_get_icon_size()
* - gtk_tool_shell_get_relief_style()
* to find out what the toolbar should look like and change
* themselves accordingly.
**/
......@@ -796,16 +776,12 @@ gtk_tool_item_get_orientation (GtkToolItem *tool_item)
* the toolbar is displayed and change themselves accordingly
*
* Possibilities are:
* <itemizedlist>
* <listitem> GTK_TOOLBAR_BOTH, meaning the tool item should show
* both an icon and a label, stacked vertically </listitem>
* <listitem> GTK_TOOLBAR_ICONS, meaning the toolbar shows
* only icons </listitem>
* <listitem> GTK_TOOLBAR_TEXT, meaning the tool item should only
* show text</listitem>
* <listitem> GTK_TOOLBAR_BOTH_HORIZ, meaning the tool item should show
* both an icon and a label, arranged horizontally</listitem>
* </itemizedlist>
* - %GTK_TOOLBAR_BOTH, meaning the tool item should show
* both an icon and a label, stacked vertically
* - %GTK_TOOLBAR_ICONS, meaning the toolbar shows only icons
* - %GTK_TOOLBAR_TEXT, meaning the tool item should only show text
* - %GTK_TOOLBAR_BOTH_HORIZ, meaning the tool item should show
* both an icon and a label, arranged horizontally
*
* Return value: A #GtkToolbarStyle indicating the toolbar style used
* for @tool_item.
......
......@@ -52,58 +52,34 @@
* When you need a tooltip with a little more fancy contents, like adding an
* image, or you want the tooltip to have different contents per #GtkTreeView
* row or cell, you will have to do a little more work:
* <itemizedlist>
* <listitem>
* <para>
* Set the #GtkWidget:has-tooltip property to %TRUE, this will make GTK+
* monitor the widget for motion and related events which are needed to
* determine when and where to show a tooltip.
* </para>
* </listitem>
* <listitem>
* <para>
* Connect to the #GtkWidget::query-tooltip signal. This signal will be
* emitted when a tooltip is supposed to be shown. One of the arguments passed
* to the signal handler is a GtkTooltip object. This is the object that we
* are about to display as a tooltip, and can be manipulated in your callback
* using functions like gtk_tooltip_set_icon(). There are functions for setting
* the tooltip's markup, setting an image from a named icon, or even putting in
* a custom widget.
* </para>
* </listitem>
* <listitem>
* <para>
* Return %TRUE from your query-tooltip handler. This causes the tooltip to be
* show. If you return %FALSE, it will not be shown.
* </para>
* </listitem>
* </itemizedlist>
*
* - Set the #GtkWidget:has-tooltip property to %TRUE, this will make GTK+
* monitor the widget for motion and related events which are needed to
* determine when and where to show a tooltip.
*
* - Connect to the #GtkWidget::query-tooltip signal. This signal will be
* emitted when a tooltip is supposed to be shown. One of the arguments passed
* to the signal handler is a GtkTooltip object. This is the object that we
* are about to display as a tooltip, and can be manipulated in your callback
* using functions like gtk_tooltip_set_icon(). There are functions for setting
* the tooltip's markup, setting an image from a named icon, or even putting in
* a custom widget.
*
* Return %TRUE from your query-tooltip handler. This causes the tooltip to be
* show. If you return %FALSE, it will not be shown.
*
* In the probably rare case where you want to have even more control over the
* tooltip that is about to be shown, you can set your own #GtkWindow which
* will be used as tooltip window. This works as follows:
* <itemizedlist>
* <listitem>
* <para>
* Set #GtkWidget:has-tooltip and connect to #GtkWidget::query-tooltip as
* before.
* </para>
* </listitem>
* <listitem>
* <para>
* Use gtk_widget_set_tooltip_window() to set a #GtkWindow created by you as
* tooltip window.
* </para>
* </listitem>
* <listitem>
* <para>
* In the #GtkWidget::query-tooltip callback you can access your window using
* gtk_widget_get_tooltip_window() and manipulate as you wish. The semantics of
* the return value are exactly as before, return %TRUE to show the window,
* %FALSE to not show it.
* </para>
* </listitem>
* </itemizedlist>
*
* - Set #GtkWidget:has-tooltip and connect to #GtkWidget::query-tooltip as before.
* Use gtk_widget_set_tooltip_window() to set a #GtkWindow created by you as
* tooltip window.
*
* - In the #GtkWidget::query-tooltip callback you can access your window using
* gtk_widget_get_tooltip_window() and manipulate as you wish. The semantics of
* the return value are exactly as before, return %TRUE to show the window,
* %FALSE to not show it.
*/
......
......@@ -209,21 +209,20 @@
*
* When working with reference counting, the following rules must be taken
* into account:
* <itemizedlist>
* <listitem><para>Never take a reference on a node without owning a
* reference on its parent. This means that all parent nodes of a referenced
* node must be referenced as well.</para></listitem>
* <listitem><para>Outstanding references on a deleted node are not released.
* This is not possible because the node has already been deleted by the
* time the row-deleted signal is received.
* </para></listitem>
* <listitem><para>Models are not obligated to emit a signal on rows of
* which none of its siblings are referenced. To phrase this differently,
* signals are only required for levels in which nodes are referenced. For
* the root level however, signals must be emitted at all times (however the
* root level is always referenced when any view is attached).
* </para></listitem>
* </itemizedlist>
*
* - Never take a reference on a node without owning a reference on its parent.
* This means that all parent nodes of a referenced node must be referenced
* as well.
*
* - Outstanding references on a deleted node are not released. This is not
* possible because the node has already been deleted by the time the
* row-deleted signal is received.
*
* - Models are not obligated to emit a signal on rows of which none of its
* siblings are referenced. To phrase this differently, signals are only
* required for levels in which nodes are referenced. For the root level
* however, signals must be emitted at all times (however the root level
* is always referenced when any view is attached).
*/
#define INITIALIZE_TREE_ITER(Iter) \
......
......@@ -32,25 +32,21 @@
*
* A #GtkTreeModelFilter is a tree model which wraps another tree model,
* and can do the following things:
* <itemizedlist>
* <listitem><para>
* Filter specific rows, based on data from a "visible column", a column
* storing booleans indicating whether the row should be filtered or not,
* or based on the return value of a "visible function", which gets a
* model, iter and user_data and returns a boolean indicating whether the
* row should be filtered or not.
* </para></listitem>