Commit 768bc440 authored by William Jon McCann's avatar William Jon McCann

docs: use |[ ]| instead of <programlisting></programlisting>

https://bugzilla.gnome.org/show_bug.cgi?id=723119
parent a74ea077
......@@ -502,8 +502,7 @@ gdk_init (int *argc, char ***argv)
*
* A minimal main program for a threaded GTK+ application
* looks like:
* <informalexample>
* <programlisting role="C">
* |[
* int
* main (int argc, char *argv[])
* {
......@@ -522,8 +521,7 @@ gdk_init (int *argc, char ***argv)
*
* return 0;
* }
* </programlisting>
* </informalexample>
* ]|
*
* Callbacks require a bit of attention. Callbacks from GTK+ signals
* are made within the GTK+ lock. However callbacks from GLib (timeouts,
......@@ -534,8 +532,7 @@ gdk_init (int *argc, char ***argv)
*
* Erik Mouw contributed the following code example to
* illustrate how to use threads within GTK+ programs.
* <informalexample>
* <programlisting role="C">
* |[
* /<!---->*-------------------------------------------------------------------------
* * Filename: gtk-thread.c
* * Version: 0.99.1
......@@ -672,8 +669,7 @@ gdk_init (int *argc, char ***argv)
*
* return 0;
* }
* </programlisting>
* </informalexample>
* ]|
*
* Unfortunately, all of the above documentation holds with the X11
* backend only. With the Win32 or Quartz backends, GDK and GTK+ calls
......
......@@ -36,8 +36,7 @@
* screen or workspace.
* <example>
* <title>Launching an application</title>
* <informalexample>
* <programlisting>
* |[
* GdkAppLaunchContext *context;
*
* context = gdk_display_get_app_launch_context (display);
......@@ -49,8 +48,7 @@
* g_warning ("Launching failed: %s\n", error->message);
*
* g_object_unref (context);
* </programlisting>
* </informalexample>
* ]|
* </example>
*/
......
......@@ -2115,7 +2115,7 @@ static GQueue gdk_error_traps = G_QUEUE_INIT;
*
* <example>
* <title>Trapping an X error</title>
* <programlisting>
* |[
* gdk_error_trap_push (<!-- -->);
*
* // ... Call the X function which may cause an error here ...
......@@ -2125,7 +2125,7 @@ static GQueue gdk_error_traps = G_QUEUE_INIT;
* {
* // ... Handle the error here ...
* }
* </programlisting>
* ]|
* </example>
*/
void
......
......@@ -87,7 +87,7 @@
*
* <example id="backend-specific">
* <title>Backend-specific code</title>
* <programlisting>
* |[
* #ifdef GDK_WINDOWING_X11
* if (GDK_IS_X11_DISPLAY (display))
* {
......@@ -103,7 +103,7 @@
* else
* #endif
* g_error ("Unsupported GDK backend");
* </programlisting>
* ]|
* </example>
*/
......@@ -225,9 +225,9 @@ static const gchar *allowed_backends;
* By default, GDK tries all included backends.
*
* For example,
* <programlisting>
* |[
* gdk_set_allowed_backends ("wayland,quartz,*");
* </programlisting>
* ]|
* instructs GDK to try the Wayland backend first,
* followed by the Quartz backend, and then all
* others.
......
......@@ -1142,36 +1142,30 @@ struct _GdkEventDND {
* The event type is always the first field in all of the event types, and
* can always be accessed with the following code, no matter what type of
* event it is:
* <informalexample>
* <programlisting>
* |[
* GdkEvent *event;
* GdkEventType type;
*
* type = event->type;
* </programlisting>
* </informalexample>
* ]|
*
* To access other fields of the event, the pointer to the event
* can be cast to the appropriate event type, or the union member
* name can be used. For example if the event type is %GDK_BUTTON_PRESS
* then the x coordinate of the button press can be accessed with:
* <informalexample>
* <programlisting>
* |[
* GdkEvent *event;
* gdouble x;
*
* x = ((GdkEventButton*)event)->x;
* </programlisting>
* </informalexample>
* ]|
* or:
* <informalexample>
* <programlisting>
* |[
* GdkEvent *event;
* gdouble x;
*
* x = event->button.x;
* </programlisting>
* </informalexample>
* ]|
*/
union _GdkEvent
{
......
......@@ -503,7 +503,7 @@ gdk_keymap_lookup_key (GdkKeymap *keymap,
* <literal>&lt;Control&gt;plus</literal> accelerator &lt;Shift&gt; should
* be masked out.
* </para>
* <informalexample><programlisting>
* |[
* &sol;* We want to ignore irrelevant modifiers like ScrollLock *&sol;
* &num;define ALL_ACCELS_MASK (GDK_CONTROL_MASK | GDK_SHIFT_MASK | GDK_MOD1_MASK)
* gdk_keymap_translate_keyboard_state (keymap, event->hardware_keycode,
......@@ -512,18 +512,18 @@ gdk_keymap_lookup_key (GdkKeymap *keymap,
* if (keyval == GDK_PLUS &&
* (event->state &amp; ~consumed &amp; ALL_ACCELS_MASK) == GDK_CONTROL_MASK)
* &sol;* Control was pressed *&sol;
* </programlisting></informalexample>
* ]|
* <para>
* An older interpretation @consumed_modifiers was that it contained
* all modifiers that might affect the translation of the key;
* this allowed accelerators to be stored with irrelevant consumed
* modifiers, by doing:</para>
* <informalexample><programlisting>
* |[
* &sol;* XXX Don't do this XXX *&sol;
* if (keyval == accel_keyval &&
* (event->state &amp; ~consumed &amp; ALL_ACCELS_MASK) == (accel_mods &amp; ~consumed))
* &sol;* Accelerator was pressed *&sol;
* </programlisting></informalexample>
* ]|
* <para>
* However, this did not work if multi-modifier combinations were
* used in the keymap, since, for instance, <literal>&lt;Control&gt;</literal>
......
......@@ -53,7 +53,7 @@
* <title>Draw transformed text with Pango and cairo</title>
* <!-- Note that this example is basically the same as
* demos/gtk-demo/rotated_text.c -->
* <programlisting>
* |[
* #define RADIUS 100
* #define N_WORDS 10
* #define FONT "Sans Bold 18"
......@@ -116,7 +116,7 @@
*
* g_object_unref (layout);
* g_object_unref (context);
* </programlisting>
* ]|
* </example>
* <figure>
* <title>Output of <xref linkend="rotated-example"/></title>
......
......@@ -421,7 +421,7 @@ struct _GdkWindowAttr
* Here's an example of how the terminal example would be implemented, assuming
* a terminal area widget called "terminal" and a toplevel window "toplevel":
*
* <informalexample><programlisting><![CDATA[
* |[
* GdkGeometry hints;
*
* hints.base_width = terminal->char_width;
......@@ -437,7 +437,7 @@ struct _GdkWindowAttr
* GDK_HINT_RESIZE_INC |
* GDK_HINT_MIN_SIZE |
* GDK_HINT_BASE_SIZE);
* ]]></programlisting></informalexample>
* ]|
*
* The other useful fields are the @min_aspect and @max_aspect fields; these
* contain a width/height ratio as a floating point number. If a geometry widget
......
......@@ -2275,8 +2275,7 @@ gdk_wayland_window_get_wl_surface (GdkWindow *window)
* This function should be called before a #GdkWindow is shown. This is
* best done by connecting to the #GtkWidget::realize signal:
*
* <informalexample>
* <programlisting>
* |[
* static void
* widget_realize_cb (GtkWidget *widget)
* {
......@@ -2297,8 +2296,7 @@ gdk_wayland_window_get_wl_surface (GdkWindow *window)
* {
* g_signal_connect (window, "realize", G_CALLBACK (widget_realize_cb), NULL);
* }
* </programlisting>
* </informalexample>
* ]|
*
* Since: 3.10
*/
......
......@@ -70,7 +70,7 @@
* </para>
* <example>
* <title>A #GtkDialog UI definition fragment.</title>
* <programlisting><![CDATA[
* |[
* <object class="GtkActionGroup" id="actiongroup">
* <child>
* <object class="GtkAction" id="About">
......@@ -81,7 +81,7 @@
* <accelerator key="F1" modifiers="GDK_CONTROL_MASK | GDK_SHIFT_MASK"/>
* </child>
* </object>
* ]]></programlisting>
* ]|
* </example>
* </refsect2>
*/
......
......@@ -41,7 +41,7 @@
* </para>
* <example>
* <title>A class fragment implementing #GtkActivatable</title>
* <programlisting><![CDATA[
* |[
*
* enum {
* ...
......@@ -253,7 +253,7 @@
* foo_bar_set_label (button, gtk_action_get_label (action));
*
* ...
* }]]></programlisting>
* }]|
* </example>
* </refsect2>
*/
......
......@@ -122,7 +122,7 @@
* </variablelist>
* <example>
* <title>A #GtkIconFactory UI definition fragment.</title>
* <programlisting><![CDATA[
* |[
* <object class="GtkIconFactory" id="iconfactory1">
* <sources>
* <source stock-id="apple-red" filename="apple-red.png"/>
......@@ -136,8 +136,7 @@
* </object>
* </child>
* </object>
* ]]>
* </programlisting>
* ]|
* </example>
* </para>
* </refsect2>
......
......@@ -116,9 +116,9 @@
* and <literal>class</literal> declarations. As an example
* of such a statement:
*
* <informalexample><programlisting>
* |[
* widget "mywindow.*.GtkEntry" style "my-entry-class"
* </programlisting></informalexample>
* ]|
*
* attaches the style <literal>"my-entry-class"</literal> to all
* widgets whose <firstterm>widget path</firstterm> matches the
......@@ -141,9 +141,9 @@
* Since GTK+ 2.10, <literal>widget_class</literal> paths can also contain
* <literal>&lt;classname&gt;</literal> substrings, which are matching
* the class with the given name and any derived classes. For instance,
* <informalexample><programlisting>
* |[
* widget_class "*&lt;GtkMenuItem&gt;.GtkLabel" style "my-style"
* </programlisting></informalexample>
* ]|
* will match #GtkLabel widgets which are contained in any kind of menu item.
*
* So, if you have a #GtkEntry named <literal>"myentry"</literal>, inside of a
......@@ -154,9 +154,9 @@
* Matching against class is a little different. The pattern match is done
* against all class names in the widgets class hierarchy (not the layout
* hierarchy) in sequence, so the pattern:
* <informalexample><programlisting>
* |[
* class "GtkButton" style "my-style"
* </programlisting></informalexample>
* ]|
* will match not just #GtkButton widgets, but also #GtkToggleButton and
* #GtkCheckButton widgets, since those classes derive from #GtkButton.
*
......@@ -221,17 +221,17 @@
* </para></listitem>
* <listitem><para>
* Merge multiple styles which use the same matching rule, for instance:
* <informalexample><programlisting>
* |[
* style "Foo" { foo_content }
* class "X" style "Foo"
* style "Bar" { bar_content }
* class "X" style "Bar"
* </programlisting></informalexample>
* ]|
* is faster to match as:
* <informalexample><programlisting>
* |[
* style "FooBar" { foo_content bar_content }
* class "X" style "FooBar"
* </programlisting></informalexample>
* ]|
* </para></listitem>
* <listitem><para>
* Use of wildcards should be avoided, this can reduce the individual RC style
......@@ -589,11 +589,11 @@
*
* Here are some examples of color expressions:
*
* <informalexample><programlisting>
* |[
* mix (0.5, "red", "blue")
* shade (1.5, mix (0.3, "#0abbc0", { 0.3, 0.5, 0.9 }))
* lighter (@<!-- -->foreground)
* </programlisting></informalexample>
* ]|
*
* In a <literal>stock</literal> definition, icon sources are specified as a
* 4-tuple of image filename or icon name, text direction, widget state, and size, in that
......@@ -607,34 +607,34 @@
* <literal>*</literal>. So for example, the following specifies different icons to
* use for left-to-right and right-to-left languages:
*
* <informalexample><programlisting>
* |[
* stock["my-stock-item"] =
* {
* { "itemltr.png", LTR, *, * },
* { "itemrtl.png", RTL, *, * }
* }
* </programlisting></informalexample>
* ]|
*
* This could be abbreviated as follows:
*
* <informalexample><programlisting>
* |[
* stock["my-stock-item"] =
* {
* { "itemltr.png", LTR },
* { "itemrtl.png", RTL }
* }
* </programlisting></informalexample>
* ]|
*
* You can specify custom icons for specific sizes, as follows:
*
* <informalexample><programlisting>
* |[
* stock["my-stock-item"] =
* {
* { "itemmenusize.png", *, *, "gtk-menu" },
* { "itemtoolbarsize.png", *, *, "gtk-large-toolbar" }
* { "itemgeneric.png" } // implicit *, *, * as a fallback
* }
* </programlisting></informalexample>
* ]|
*
* The sizes that come with GTK+ itself are <literal>"gtk-menu"</literal>,
* <literal>"gtk-small-toolbar"</literal>, <literal>"gtk-large-toolbar"</literal>,
......@@ -643,14 +643,14 @@
*
* It's also possible to use custom icons for a given state, for example:
*
* <informalexample><programlisting>
* |[
* stock["my-stock-item"] =
* {
* { "itemprelight.png", *, PRELIGHT },
* { "iteminsensitive.png", *, INSENSITIVE },
* { "itemgeneric.png" } // implicit *, *, * as a fallback
* }
* </programlisting></informalexample>
* ]|
*
* When selecting an icon source to use, GTK+ will consider text direction most
* important, state second, and size third. It will select the best match based on
......@@ -667,7 +667,7 @@
* taken on particular key presses. The form of a binding
* set declaration is:
*
* <informalexample><programlisting>
* |[
* binding <replaceable>name</replaceable> {
* bind <replaceable>key</replaceable> {
* <replaceable>signalname</replaceable> (<replaceable>param</replaceable>, ...)
......@@ -675,7 +675,7 @@
* }
* ...
* }
* </programlisting></informalexample>
* ]|
*
* <replaceable>key</replaceable> is a string consisting of a
* series of modifiers followed by the name of a key. The
......
......@@ -4067,9 +4067,9 @@ gtk_widget_get_default_style (void)
* This function attaches the widget's #GtkStyle to the widget's
* #GdkWindow. It is a replacement for
*
* <programlisting>
* |[
* widget->style = gtk_style_attach (widget->style, widget->window);
* </programlisting>
* ]|
*
* and should only ever be called in a derived widget's "realize"
* implementation which does not chain up to its parent class'
......
......@@ -729,13 +729,13 @@ gtk_table_resize (GtkTable *table,
* and row numbers of the table. (Columns and rows are indexed from zero).
*
* To make a button occupy the lower right cell of a 2x2 table, use
* <informalexample><programlisting>
* |[
* gtk_table_attach (table, button,
* 1, 2, // left, right attach
* 1, 2, // top, bottom attach
* xoptions, yoptions,
* xpadding, ypadding);
* </programlisting></informalexample>
* ]|
* If you want to make the button span the entire bottom row, use @left_attach == 0 and @right_attach = 2 instead.
*
* Deprecated: 3.4: Use gtk_grid_attach() with #GtkGrid. Note that the attach
......
......@@ -72,8 +72,7 @@
* Definitions</link>.
* </para></note>
*
* <programlisting>
* <![CDATA[
* |[
* <!ELEMENT ui (menubar|toolbar|popup|accelerator)* >
* <!ELEMENT menubar (menuitem|separator|placeholder|menu)* >
* <!ELEMENT menu (menuitem|separator|placeholder|menu)* >
......@@ -108,8 +107,7 @@
* position (top|bot) #IMPLIED >
* <!ATTLIST accelerator name #IMPLIED
* action #REQUIRED >
* ]]>
* </programlisting>
* ]|
* There are some additional restrictions beyond those specified in the
* DTD, e.g. every toolitem must have a toolbar in its anchestry and
* every menuitem must have a menubar or popup in its anchestry. Since
......@@ -125,7 +123,7 @@
*
* <example>
* <title>A UI definition</title>
* <programlisting><![CDATA[
* |[
* <ui>
* <menubar>
* <menu name="FileMenu" action="FileMenuAction">
......@@ -150,7 +148,7 @@
* </placeholder>
* </toolbar>
* </ui>
* ]]></programlisting>
* ]|
* </example>
*
* The constructed widget hierarchy is very similar to the element tree
......@@ -273,7 +271,7 @@
*
* <example>
* <title>An embedded GtkUIManager UI definition</title>
* <programlisting><![CDATA[
* |[
* <object class="GtkUIManager" id="uiman">
* <child>
* <object class="GtkActionGroup" id="actiongroup">
......@@ -296,7 +294,7 @@
* <object class="GtkMenuBar" id="menubar1" constructor="uiman"/>
* </child>
* </object>
* ]]></programlisting>
* ]|
* </example>
* </para>
* </refsect2>
......
......@@ -84,13 +84,13 @@
* application, but in order to ensure proper translation of the title,
* applications should set the title property explicitly when constructing
* a GtkAboutDialog, as shown in the following example:
* <informalexample><programlisting>
* |[
* gtk_show_about_dialog (NULL,
* "program-name", "ExampleCode",
* "logo", example_logo,
* "title" _("About ExampleCode"),
* NULL);
* </programlisting></informalexample>
* ]|
*
* It is also possible to show a #GtkAboutDialog like any other #GtkDialog,
* e.g. using gtk_dialog_run(). In this case, you might need to know that
......
......@@ -67,7 +67,7 @@
* though it is almost always used to display just one accelerator key.
* <example>
* <title>Creating a simple menu item with an accelerator key.</title>
* <programlisting>
* |[
* GtkWidget *save_item;
* GtkAccelGroup *accel_group;
*
......@@ -86,7 +86,7 @@
* accelerators. We just need to make sure we use GTK_ACCEL_VISIBLE here. *<!---->/
* gtk_widget_add_accelerator (save_item, "activate", accel_group,
* GDK_KEY_s, GDK_CONTROL_MASK, GTK_ACCEL_VISIBLE);
* </programlisting>
* ]|
* </example>
*/
......
......@@ -94,11 +94,11 @@
* </figure>
*
* <example id="gtkapplication"><title>A simple application</title>
* <programlisting>
* |[
* <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../examples/bloatpad.c">
* <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
* </xi:include>
* </programlisting>
* ]|
* </example>
*
* GtkApplication optionally registers with a session manager
......
......@@ -79,7 +79,7 @@
* using gtk_header_bar_set_show_close_button().
*
* <example><title>A GtkApplicationWindow with a menubar</title>
* <programlisting><![CDATA[
* |[
* app = gtk_application_new ();
*
* builder = gtk_builder_new ();
......@@ -99,16 +99,15 @@
* ...
*
* window = gtk_application_window_new (app);
* ]]>
* </programlisting>
* ]|
* </example>
*
* <example><title>Handling fallback yourself</title>
* <programlisting>
* |[
* <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../examples/sunny.c">
* <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
* </xi:include>
* </programlisting>
* ]|
* </example>
*
* The XML format understood by #GtkBuilder for #GMenuModel consists
......
......@@ -68,7 +68,7 @@
* For example for binding Control and the left or right cursor keys
* of a #GtkEntry widget to the #GtkEntry::move-cursor signal (so movement
* occurs in 3-character steps), the following binding can be used:
* <informalexample><programlisting>
* |[
* @binding-set MoveCursor3
* {
* bind "&lt;Control&gt;Right" { "move-cursor" (visual-positions, 3, 0) };
......@@ -78,7 +78,7 @@
* {
* gtk-key-bindings: MoveCursor3;
* }
* </programlisting></informalexample>
* ]|
* </para>
* </refsect2>
* <refsect2 id="gtk-bindings-unbind">
......@@ -91,7 +91,7 @@
* <link linkend="gtk-bindings-install">Installing a key binding</link>
* works as expected. The same mechanism can not be used to "unbind"
* existing bindings, however.
* <informalexample><programlisting>
* |[
* @binding-set MoveCursor3
* {
* bind "&lt;Control&gt;Right" { };
......@@ -101,7 +101,7 @@
* {
* gtk-key-bindings: MoveCursor3;
* }
* </programlisting></informalexample>
* ]|
* The above example will not have the desired effect of causing
* "&lt;Control&gt;Right" and "&lt;Control&gt;Left" key presses to
* be ignored by GTK+. Instead, it just causes any existing bindings
......@@ -112,7 +112,7 @@
* eventually lookup and find the default GTK+ bindings for entries which
* implement word movement. To keep GTK+ from activating its default
* bindings, the "unbind" keyword can be used like this:
* <informalexample><programlisting>
* |[
* @binding-set MoveCursor3
* {
* unbind "&lt;Control&gt;Right";
......@@ -122,7 +122,7 @@
* {
* gtk-key-bindings: MoveCursor3;
* }
* </programlisting></informalexample>
* ]|
* Now, GTK+ will find a match when looking up "&lt;Control&gt;Right"
* and "&lt;Control&gt;Left" key presses before it resorts to its default
* bindings, and the match instructs it to abort ("unbind") the search,
......@@ -1357,17 +1357,17 @@ create_signal_scanner (void)
*
* Signal descriptions may either bind a key combination to
* one or more signals:
* <informalexample><programlisting>
* |[
* bind "key" {
* "signalname" (param, ...)
* ...
* }
* </programlisting></informalexample>
* ]|
*
* Or they may also unbind a key combination:
* <informalexample><programlisting>
* |[
* unbind "key"
* </programlisting></informalexample>
* ]|
*
* Key combinations must be in a format that can be parsed by
* gtk_accelerator_parse().
......
......@@ -67,11 +67,11 @@
* <link linkend="XML-UI">GtkUIManager UI Definitions</link>, which are more
* limited in scope. It is common to use <filename>.ui</filename> as the filename extension for files containing GtkBuilder UI definitions.
* </para>
* <programlisting>
* |[
* <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gtk/gtkbuilder.rnc">
* <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
* </xi:include>
* </programlisting>
* ]|
* <para>
* The toplevel element is &lt;interface&gt;. It optionally takes a "domain"
* attribute, which will make the builder look for translated strings using
......@@ -158,7 +158,7 @@
* </para>
* <example>
* <title>A GtkBuilder UI Definition</title>
* <programlisting><![CDATA[
* |[
* <interface>
* <object class="GtkDialog" id="dialog1">
* <child internal-child="vbox">
......@@ -180,7 +180,7 @@
* </child>
* </object>
* </interface>
* ]]></programlisting>
* ]|
* </example>
* <para>
* Beyond this general structure, several object classes define their own XML
......
......@@ -74,7 +74,7 @@
* of a #GtkTreeModel one would do the following:
* <example>
* <title>Requesting the width of a handful of GtkTreeModel rows</title>
* <programlisting>
* |[
* GtkTreeIter iter;
* gint minimum_width;
* gint natural_width;
......@@ -88,7 +88,7 @@
* valid = gtk_tree_model_iter_next (model, &iter);
* }
* gtk_cell_area_context_get_preferred_width (context, &minimum_width, &natural_width);
* </programlisting>
* ]|
* </example>
* Note that in this example it's not important to observe the
* returned minimum and natural width of the area for each row
......@@ -110,7 +110,7 @@
* take up the full width of the layouting widget would look like:
* <example>
* <title>A typical get_preferred_width(<!-- -->) implementation</title>
* <programlisting>
* |[
* static void
* foo_get_preferred_width (GtkWidget *widget,
* gint *minimum_size,
......@@ -123,7 +123,7 @@
*
* gtk_cell_area_context_get_preferred_width (priv->context, minimum_size, natural_size);
* }
* </programlisting>
* ]|
* </example>
* In the above example the Foo widget has to make sure that some
* row sizes have been calculated (the amount of rows that Foo judged
......@@ -142,7 +142,7 @@
* root level of a #GtkTreeModel one would do the following:
* <example>
* <title>Requesting the height for width of a handful of GtkTreeModel rows</title>
* <programlisting>
* |[
* GtkTreeIter iter;
* gint minimum_height;
* gint natural_height;
......@@ -164,7 +164,7 @@
*
* valid = gtk_tree_model_iter_next (model, &iter);
* }
* </programlisting>
* ]|
* </example>
* Note that in the above example we would need to cache the heights
* returned for each row so that we would know what sizes to render the
......@@ -199,7 +199,7 @@