Commit 63e887e1 authored by William Jon McCann's avatar William Jon McCann

docs: replace all <examples> with markdown headings

parent 28376c26
......@@ -34,8 +34,9 @@
* handles launching an application in a graphical context. It provides
* startup notification and allows to launch applications on a specific
* screen or workspace.
* <example>
* <title>Launching an application</title>
*
* ## Launching an application
*
* |[<!-- language="C" -->
* GdkAppLaunchContext *context;
*
......@@ -49,7 +50,6 @@
*
* g_object_unref (context);
* ]|
* </example>
*/
......
......@@ -77,7 +77,8 @@
* be controlling each of these virtual devices. Physical devices may also
* be "floating", which means they are not attached to any virtual device.
*
* <example><title>Master and slave devices</title>
* ## Master and slave devices
*
* <screen>
* carlos@sacarino:~$ xinput list
* ⎡ Virtual core pointer id=2 [master pointer (3)]
......@@ -96,7 +97,6 @@
* ↳ AT Translated Set 2 keyboard id=12 [slave keyboard (3)]
* ↳ ThinkPad Extra Buttons id=15 [slave keyboard (3)]
* </screen>
* </example>
*
* By default, GDK will automatically listen for events coming from all
* master devices, setting the #GdkDevice for all events coming from input
......
......@@ -2107,8 +2107,8 @@ static GQueue gdk_error_traps = G_QUEUE_INIT;
* You can use gdk_x11_display_error_trap_push() to ignore errors
* on only a single display.
*
* <example>
* <title>Trapping an X error</title>
* ## Trapping an X error
*
* |[<!-- language="C" -->
* gdk_error_trap_push (<!-- -->);
*
......@@ -2120,7 +2120,6 @@ static GQueue gdk_error_traps = G_QUEUE_INIT;
* // ... Handle the error here ...
* }
* ]|
* </example>
*/
void
gdk_error_trap_push (void)
......
......@@ -85,8 +85,8 @@
* you are building your application against. At runtime, use type-check
* macros like GDK_IS_X11_DISPLAY() to find out which backend is in use:
*
* <example id="backend-specific">
* <title>Backend-specific code</title>
* ## Backend-specific code ## {#backend-specific}
*
* |[<!-- language="C" -->
* #ifdef GDK_WINDOWING_X11
* if (GDK_IS_X11_DISPLAY (display))
......@@ -104,7 +104,6 @@
* #endif
* g_error ("Unsupported GDK backend");
* ]|
* </example>
*/
......
......@@ -49,8 +49,9 @@
*
* Rendering a Pango layout is done most simply with pango_cairo_show_layout();
* you can also draw pieces of the layout with pango_cairo_show_layout_line().
* <example id="rotated-example">
* <title>Draw transformed text with Pango and cairo</title>
*
* ## Draw transformed text with Pango and cairo ## {#rotated-example}
*
* <!-- Note that this example is basically the same as
* demos/gtk-demo/rotated_text.c -->
* |[<!-- language="C" -->
......@@ -117,7 +118,7 @@
* g_object_unref (layout);
* g_object_unref (context);
* ]|
* </example>
*
* <figure>
* <title>Output of <xref linkend="rotated-example"/></title>
* <graphic fileref="rotated-text.png" format="PNG"/>
......
......@@ -65,8 +65,9 @@
* set (see #GtkAccelFlags).
* A #GtkAccelLabel can display multiple accelerators and even signal names,
* though it is almost always used to display just one accelerator key.
* <example>
* <title>Creating a simple menu item with an accelerator key.</title>
*
* ## Creating a simple menu item with an accelerator key.
*
* |[<!-- language="C" -->
* GtkWidget *save_item;
* GtkAccelGroup *accel_group;
......@@ -87,7 +88,6 @@
* gtk_widget_add_accelerator (save_item, "activate", accel_group,
* GDK_KEY_s, GDK_CONTROL_MASK, GTK_ACCEL_VISIBLE);
* ]|
* </example>
*/
enum {
......
......@@ -93,13 +93,13 @@
* <graphic fileref="bloatpad-xfce.png" format="PNG"/>
* </figure>
*
* <example id="gtkapplication"><title>A simple application</title>
* ## A simple application ## {#gtkapplication}
*
* |[<!-- language="C" -->
* <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>
* ]|
* </example>
*
* GtkApplication optionally registers with a session manager
* of the users session (if you set the #GtkApplication:register-session
......
......@@ -78,7 +78,8 @@
* also be shown as part of client-side window decorations, e.g. by
* using gtk_header_bar_set_show_close_button().
*
* <example><title>A GtkApplicationWindow with a menubar</title>
* ## A GtkApplicationWindow with a menubar
*
* |[<!-- language="C" -->
* app = gtk_application_new ();
*
......@@ -100,9 +101,9 @@
*
* window = gtk_application_window_new (app);
* ]|
* </example>
*
* <example><title>Handling fallback yourself</title>
* ## Handling fallback yourself
*
* |[<!-- language="C" -->
* <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../examples/sunny.c">
* <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
......
......@@ -60,8 +60,8 @@
* background color before sending the expose event, and that
* drawing is implicitly clipped to the exposed area.
*
* <example>
* <title>Simple GtkDrawingArea usage</title>
* ## Simple GtkDrawingArea usage
*
* |[<!-- language="C" -->
* gboolean
* draw_callback (GtkWidget *widget, cairo_t *cr, gpointer data)
......@@ -91,7 +91,6 @@
* g_signal_connect (G_OBJECT (drawing_area), "draw",
* G_CALLBACK (draw_callback), NULL);
* ]|
* </example>
*
* Draw signals are normally delivered when a drawing area first comes
* onscreen, or when it's covered by another window and then uncovered.
......
......@@ -37,8 +37,8 @@
* the following handler to #GtkEditable::insert-text, an application
* can convert all entry into a widget into uppercase.
*
* <example>
* <title>Forcing entry to uppercase.</title>
* ## Forcing entry to uppercase.
*
* |[<!-- language="C" -->
* #include <ctype.h>;
*
......@@ -62,7 +62,6 @@
* g_free (result);
* }
* ]|
* </example>
*/
#include "config.h"
......
......@@ -321,8 +321,9 @@ gtk_file_chooser_default_init (GtkFileChooserInterface *iface)
* dialog should be used, it should return
* %GTK_FILE_CHOOSER_CONFIRMATION_CONFIRM. The following example
* illustrates this.
* <example id="gtkfilechooser-confirmation">
* <title>Custom confirmation</title>
*
* ## Custom confirmation ## {#gtkfilechooser-confirmation}
*
* |[<!-- language="C" -->
* static GtkFileChooserConfirmation
* confirm_overwrite_callback (GtkFileChooser *chooser, gpointer data)
......@@ -354,7 +355,6 @@ gtk_file_chooser_default_init (GtkFileChooserInterface *iface)
*
* gtk_widget_destroy (chooser);
* ]|
* </example>
*
* Returns: a #GtkFileChooserConfirmation value that indicates which
* action to take after emitting the signal.
......
......@@ -70,8 +70,8 @@
* that button. This widget does not support setting the
* #GtkFileChooser:select-multiple property to %TRUE.
*
* <example>
* <title>Create a button to let the user select a file in /etc</title>
* ## Create a button to let the user select a file in /etc
*
* |[<!-- language="C" -->
* {
* GtkWidget *button;
......@@ -82,7 +82,6 @@
* "/etc");
* }
* ]|
* </example>
*
* The #GtkFileChooserButton supports the #GtkFileChooserAction<!-- -->s
* %GTK_FILE_CHOOSER_ACTION_OPEN and %GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER.
......
......@@ -52,11 +52,11 @@
* own. Instead, you should use the functions that work on a
* #GtkFileChooser.
*
* <example id="gtkfilechooser-typical-usage">
* <title>Typical usage</title>
* ## Typical usage ## {#gtkfilechooser-typical-usage}
*
* In the simplest of cases, you can the following code to use
* #GtkFileChooserDialog to select a file for opening:
* <para>
*
* |[
* GtkWidget *dialog;
*
......@@ -78,9 +78,9 @@
*
* gtk_widget_destroy (dialog);
* ]|
* </para>
*
* To use a dialog for saving, you can use this:
* <para>
*
* |[
* GtkWidget *dialog;
*
......@@ -108,14 +108,10 @@
*
* gtk_widget_destroy (dialog);
* ]|
* </para>
* </example>
*
* ## Setting up a file chooser dialog
* ## Setting up a file chooser dialog ## {#gtkfilechooserdialog-setting-up}
*
* <para id="gtkfilechooserdialog-setting-up">
* There are various cases in which you may need to use a #GtkFileChooserDialog:
* </para>
*
* - To select a file for opening. Use #GTK_FILE_CHOOSER_ACTION_OPEN.
*
......@@ -138,13 +134,13 @@
* i.e. when you are doing a Save As command and you already
* have a file saved somewhere.
* ## Response Codes
* ## Response Codes ## {#gtkfilechooserdialog-responses}
*
* <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:
*
* |[
* GtkWidget *dialog;
*
......@@ -155,16 +151,14 @@
* _("_Open"), GTK_RESPONSE_ACCEPT,
* 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
* ones in #GtkResponseType, but #GtkFileChooserDialog assumes that
* its "accept"-type action, e.g. an "Open" or "Save" button,
* will have one of the following response codes:
* </para>
*
* - #GTK_RESPONSE_ACCEPT
* - #GTK_RESPONSE_OK
* - #GTK_RESPONSE_YES
......
......@@ -74,8 +74,9 @@
* so by default does not receive events. If you want to receive events
* on the image, such as button clicks, place the image inside a
* #GtkEventBox, then connect to the event signals on the event box.
* <example>
* <title>Handling button press events on a #GtkImage.</title>
*
* ## Handling button press events on a #GtkImage.
*
* |[<!-- language="C" -->
* static gboolean
* button_press_callback (GtkWidget *event_box,
......@@ -113,7 +114,6 @@
* return image;
* }
* ]|
* </example>
*
* When handling events on the event box, keep in mind that coordinates
* in the image may be different from event box coordinates due to
......
......@@ -33,8 +33,8 @@
* by default on the level bar: #GTK_LEVEL_BAR_OFFSET_LOW and
* #GTK_LEVEL_BAR_OFFSET_HIGH, with values 0.25 and 0.75 respectively.
*
* <example>
* <title>Adding a custom offset on the bar</title>
* ## Adding a custom offset on the bar
*
* |[<!-- language="C" -->
*
* static GtkWidget *
......@@ -66,7 +66,6 @@
* return level_bar;
* }
* ]|
* </example>
*
* The default interval of values is between zero and one, but it's possible to
* modify the interval using gtk_level_bar_set_min_value() and
......
......@@ -53,8 +53,8 @@
* #GtkFileChooserDialog. After a callback finishes, GTK+ will return to the
* main loop and await more user input.
*
* <example>
* <title>Typical main() function for a GTK+ application</title>
* ## Typical main() function for a GTK+ application
*
* |[<!-- language="C" -->
* int
* main (int argc, char **argv)
......@@ -81,7 +81,6 @@
* return 0;
* }
* ]|
* </example>
*
* It's OK to use the GLib main loop directly instead of gtk_main(), though it
* involves slightly more typing. See #GMainLoop in the GLib documentation.
......@@ -1247,8 +1246,8 @@ gtk_main_quit (void)
* This can be used to update the UI and invoke timeouts etc.
* while doing some time intensive computation.
*
* <example>
* <title>Updating the UI during a long computation</title>
* ## Updating the UI during a long computation
*
* |[<!-- language="C" -->
* /&ast; computation going on... &ast;/
*
......@@ -1257,7 +1256,6 @@ gtk_main_quit (void)
*
* /&ast; ...computation continued &ast;/
* ]|
* </example>
*
* Returns: %TRUE if any events are pending, %FALSE otherwise
*/
......@@ -1804,8 +1802,8 @@ gtk_main_do_event (GdkEvent *event)
* of a window. Of course you should not do this as the user expects
* a reaction from clicking the close icon of the window...
*
* <example>
* <title>A persistent window</title>
* ## A persistent window
*
* |[<!-- language="C" -->
* #include <gtk/gtk.h>
*
......@@ -1834,7 +1832,6 @@ gtk_main_do_event (GdkEvent *event)
* return 0;
* }
* ]|
* </example>
*
* Returns: %TRUE
*/
......
......@@ -43,17 +43,16 @@
* gtk_menu_popup() function. The example below shows how an application
* can pop up a menu when the 3rd mouse button is pressed.
*
* <example>
* <title>Connecting the popup signal handler.</title>
* ## Connecting the popup signal handler.
*
* |[<!-- language="C" -->
* /<!---->* connect our handler which will popup the menu *<!---->/
* g_signal_connect_swapped (window, "button_press_event",
* G_CALLBACK (my_popup_handler), menu);
* ]|
* </example>
*
* <example>
* <title>Signal handler which displays a popup menu.</title>
* ## Signal handler which displays a popup menu.
*
* |[<!-- language="C" -->
* static gint
* my_popup_handler (GtkWidget *widget, GdkEvent *event)
......@@ -80,11 +79,10 @@
* return TRUE;
* }
* }
*
*
* return FALSE;
* }
* ]|
* </example>
*/
#include "config.h"
......
......@@ -48,8 +48,8 @@
* or use gtk_print_run_page_setup_dialog() to show the page setup dialog
* and receive the resulting page setup.
*
* <example>
* <title>A page setup dialog</title>
* ## A page setup dialog
*
* |[<!-- language="C" -->
* static GtkPrintSettings *settings = NULL;
* static GtkPageSetup *page_setup = NULL;
......@@ -71,7 +71,6 @@
* page_setup = new_page_setup;
* }
* ]|
* </example>
*
* Printing support was added in GTK+ 2.10.
*/
......
......@@ -73,8 +73,8 @@
* The application can set the position of the slider as if it were set
* by the user, by calling gtk_paned_set_position().
*
* <example>
* <title>Creating a paned widget with minimum sizes.</title>
* ## Creating a paned widget with minimum sizes.
*
* |[<!-- language="C" -->
* GtkWidget *hpaned = gtk_paned_new (GTK_ORIENTATION_HORIZONTAL);
* GtkWidget *frame1 = gtk_frame_new (NULL);
......@@ -90,7 +90,6 @@
* gtk_paned_pack2 (GTK_PANED (hpaned), frame2, FALSE, FALSE);
* gtk_widget_set_size_request (frame2, 50, -1);
* ]|
* </example>
*/
enum {
......
......@@ -35,8 +35,8 @@
* #GtkPrintOperation::end-print, #GtkPrintOperation::request-page-setup and
* #GtkPrintOperation::draw-page signals on the #GtkPrintOperation.
*
* <example>
* <title>Using GtkPrintContext in a #GtkPrintOperation::draw-page callback</title>
* ## Using GtkPrintContext in a #GtkPrintOperation::draw-page callback
*
* |[<!-- language="C" -->
* static void
* draw_page (GtkPrintOperation *operation,
......@@ -90,7 +90,6 @@
* g_object_unref (layout);
* }
* ]|
* </example>
*
* Printing support was added in GTK+ 2.10.
*/
......
......@@ -59,8 +59,8 @@
* #GtkPrintOperation::draw-page, which you are supposed to catch
* and render the page on the provided #GtkPrintContext using Cairo.
*
* <example>
* <title>The high-level printing API</title>
* ## The high-level printing API
*
* |[<!-- language="C" -->
* static GtkPrintSettings *settings = NULL;
*
......@@ -91,7 +91,6 @@
* g_object_unref (print);
* }
* ]|
* </example>
*
* By default GtkPrintOperation uses an external application to do
* print preview. To implement a custom print preview, an application
......
......@@ -68,8 +68,8 @@
* The group list does not need to be freed, as each #GtkRadioButton will remove
* itself and its list item when it is destroyed.
*
* <example>
* <title>How to create a group of two radio buttons.</title>
* ## How to create a group of two radio buttons.
*
* |[<!-- language="C" -->
* void create_radio_buttons (void) {
*
......@@ -96,7 +96,6 @@
* return;
* }
* ]|
* </example>
*
* When an unselected button in the group is clicked the clicked button
* receives the #GtkToggleButton::toggled signal, as does the previously
......
......@@ -46,8 +46,8 @@
* The correct way to create a group of radio menu items is approximatively
* this:
*
* <example>
* <title>How to create a group of radio menu items.</title>
* ## How to create a group of radio menu items.
*
* |[<!-- language="C" -->
* GSList *group = NULL;
* GtkWidget *item;
......@@ -61,10 +61,8 @@
* gtk_check_menu_item_set_active (GTK_CHECK_MENU_ITEM (item), TRUE);
* }
* ]|
* </example>
*/
struct _GtkRadioMenuItemPrivate
{
GSList *group;
......
......@@ -44,10 +44,11 @@
* Note that #GtkRecentChooserDialog does not have any methods of its own.
* Instead, you should use the functions that work on a #GtkRecentChooser.
*
* <example id="gtkrecentchooser-typical-usage">
* <title>Typical usage</title>
* ## Typical usage ## {#gtkrecentchooser-typical-usage}
*
* In the simplest of cases, you can use the following code to use
* a #GtkRecentChooserDialog to select a recently used file:
*
* |[<!-- language="C" -->
* GtkWidget *dialog;
*
......@@ -68,7 +69,6 @@
*
* gtk_widget_destroy (dialog);
* ]|
* </example>
*
* Recently used files are supported since GTK+ 2.10.
*/
......
......@@ -54,14 +54,13 @@
* The following example shows you how to create a more complex search
* entry.
*
* <example>
* <title>Creating a search bar</title>
* ## Creating a search bar
*
* |[<!-- language="C" -->
* <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../examples/search-bar.c">
* <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
* </xi:include>
* ]|
* </example>
*
* Since: 3.10
*/
......@@ -166,8 +165,8 @@ preedit_changed_cb (GtkEntry *entry,
* gtk_search_bar_connect_entry(), this function will return
* immediately with a warning.
*
* <example>
* <title>Showing the search bar on key presses</title>
* ## Showing the search bar on key presses
*
* |[<!-- language="C" -->
* static gboolean
* window_key_press_event_cb (GtkWidget *widget,
......@@ -180,7 +179,6 @@ preedit_changed_cb (GtkEntry *entry,
* g_signal_connect (window, "key-press-event",
* G_CALLBACK (window_key_press_event_cb), search_bar);
* ]|
* </example>
*
* Return value: %GDK_EVENT_STOP if the key press event resulted
* in text being entered in the search entry (and revealing
......
......@@ -68,8 +68,8 @@
* Before using this function, the socket must have been realized,
* and for hence, have been added to its parent.
*
* <example>
* <title>Obtaining the window ID of a socket.</title>
* ## Obtaining the window ID of a socket.
*
* |[<!-- language="C" -->
* GtkWidget *socket = gtk_socket_new (<!-- -->);
* gtk_widget_show (socket);
......@@ -82,7 +82,6 @@
* g_print ("The ID of the sockets window is %#x\n",
* gtk_socket_get_id (socket));
* ]|
* </example>
*
* Note that if you pass the window ID of the socket to another
* process that will create a plug in the socket, you must make
......
......@@ -78,8 +78,8 @@
* See the #GtkAdjustment section for more details about an adjustment's
* properties.
*
* <example>
* <title>Using a GtkSpinButton to get an integer</title>
* ## Using a GtkSpinButton to get an integer
*
* |[<!-- language="C" -->
* /&ast; Provides a function to retrieve an integer value from a
* &ast; GtkSpinButton and creates a spin button to model percentage
......@@ -112,10 +112,9 @@
* gtk_widget_show_all (window);
* }
* ]|
* </example>
*
* <example>
* <title>Using a GtkSpinButton to get a floating point value</title>
* ## Using a GtkSpinButton to get a floating point value
*
* |[<!-- language="C" -->
* /&ast; Provides a function to retrieve a floating point value from a
* &ast; GtkSpinButton, and creates a high precision spin button.
......@@ -146,7 +145,6 @@
* gtk_widget_show_all (window);
* }
* ]|
* </example>
*/
struct _GtkSpinButtonPrivate
......
......@@ -3706,10 +3706,9 @@ _gtk_style_context_get_cursor_color (GtkStyleContext *context,
* on or off, and %GTK_STATE_FLAG_INCONSISTENT determines whether it
* should be marked as undefined.
*
* <example>
* <title>Typical checkmark rendering</title>
* Typical checkmark rendering:
*
* ![](checks.png)
* </example>
*
* Since: 3.0
**/
......@@ -3757,10 +3756,9 @@ gtk_render_check (GtkStyleContext *context,
* state will determine whether the option is on or off, and
* %GTK_STATE_FLAG_INCONSISTENT whether it should be marked as undefined.
*
* <example>
* <title>Typical option mark rendering</title>
* Typical option mark rendering:
*
* ![](options.png)
* </example>
*
* Since: 3.0
**/
......@@ -3805,10 +3803,9 @@ gtk_render_option (GtkStyleContext *context,
*
* Renders an arrow pointing to @angle.
*
* <example>
* <title>Typical arrow rendering at 0, 1&solidus;2 &pi;, &pi; and 3&solidus;2 &pi;</title>
* Typical arrow rendering at 0, 1&solidus;2 &pi;, &pi; and 3&solidus;2 &pi;:
*
* ![](arrows.png)
* </example>
*
* Since: 3.0
**/
......@@ -3857,13 +3854,12 @@ gtk_render_arrow (GtkStyleContext *context,
*
* Renders the background of an element.
*
* <example>
* <title>Typical background rendering, showing the effect of
* Typical background rendering, showing the effect of
* <parameter>background-image</parameter>,
* <parameter>border-width</parameter> and
* <parameter>border-radius</parameter></title>
* <parameter>border-radius</parameter>:
*
* ![](background.png)
* </example>
*
* Since: 3.0.
**/
......@@ -3907,15 +3903,13 @@ gtk_render_background (GtkStyleContext *context,
*
* Renders a frame around the rectangle defined by @x, @y, @width, @height.
*
* <example>
* <title>Examples of frame rendering, showing the effect of
* Examples of frame rendering, showing the effect of
* <parameter>border-image</parameter>,
* <parameter>border-color</parameter>,
* <parameter>border-width</parameter>,
* <parameter>border-radius</parameter> and
* junctions</title>
* <parameter>border-radius</parameter> and junctions:
*
* ![](frames.png)
* </example>
*
* Since: 3.0
**/
......@@ -3961,10 +3955,9 @@ gtk_render_frame (GtkStyleContext *context,
* defined by @x, @y, @width, @height. The state %GTK_STATE_FLAG_ACTIVE
* determines whether the expander is collapsed or expanded.
*
* <example>
* <title>Typical expander rendering</title>
* Typical expander rendering:
*
* ![](expanders.png)
* </example>
*
* Since: 3.0
**/
......@@ -4007,10 +4000,10 @@ gtk_render_expander (GtkStyleContext *context,
* @height: rectangle height
*
* Renders a focus indicator on the rectangle determined by @x, @y, @width, @height.
* <example>
* <title>Typical focus rendering</title>
*
* Typical focus rendering:
*
* ![](focus.png)
* </example>
*
* Since: 3.0
**/
......@@ -4134,10 +4127,9 @@ gtk_render_line (GtkStyleContext *context,
* @width, @height. @orientation defines whether the slider is vertical
* or horizontal.
*
* <example>
* <title>Typical slider rendering</title>
* Typical slider rendering:
*
* ![](sliders.png)
* </example>
*
* Since: 3.0
**/
......@@ -4188,10 +4180,9 @@ gtk_render_slider (GtkStyleContext *cont