diff --git a/gdk/gdkwindow.c b/gdk/gdkwindow.c index 897f09787e..f5c4f421ac 100644 --- a/gdk/gdkwindow.c +++ b/gdk/gdkwindow.c @@ -56,40 +56,36 @@ * A #GdkWindow is a (usually) rectangular region on the screen. * It's a low-level object, used to implement high-level objects such as * #GtkWidget and #GtkWindow on the GTK+ level. A #GtkWindow is a toplevel - * window, the thing a user might think of as a "window" with a titlebar and - * so on; a #GtkWindow may contain many #GdkWindows. For example, each - * #GtkButton has a #GdkWindow associated with it. + * window, the thing a user might think of as a "window" with a titlebar + * and so on; a #GtkWindow may contain many #GdkWindows. For example, + * each #GtkButton has a #GdkWindow associated with it. * - * - * Composited Windows - * - * Normally, the windowing system takes care of rendering the contents of a - * child window onto its parent window. This mechanism can be intercepted by - * calling gdk_window_set_composited() on the child window. For a - * composited window it is the responsibility of the - * application to render the window contents at the right spot. - * - * - * - * Offscreen Windows - * - * Offscreen windows are more general than composited windows, since they allow - * not only to modify the rendering of the child window onto its parent, but - * also to apply coordinate transformations. + * ## Composited Windows * - * To integrate an offscreen window into a window hierarchy, one has to call - * gdk_offscreen_window_set_embedder() and handle a number of signals. The - * #GdkWindow::pick-embedded-child signal on the embedder window is used to - * select an offscreen child at given coordinates, and the - * #GdkWindow::to-embedder and #GdkWindow::from-embedder signals on the - * offscreen window are used to translate coordinates between the embedder and - * the offscreen window. + * Normally, the windowing system takes care of rendering the contents + * of a child window onto its parent window. This mechanism can be + * intercepted by calling gdk_window_set_composited() on the child + * window. For a composited window it is the + * responsibility of the application to render the window contents at + * the right spot. * - * For rendering an offscreen window onto its embedder, the contents of the - * offscreen window are available as a surface, via + * ## Offscreen Windows + * + * Offscreen windows are more general than composited windows, since + * they allow not only to modify the rendering of the child window onto + * its parent, but also to apply coordinate transformations. + * + * To integrate an offscreen window into a window hierarchy, one has + * to call gdk_offscreen_window_set_embedder() and handle a number of + * signals. The #GdkWindow::pick-embedded-child signal on the embedder + * window is used to select an offscreen child at given coordinates, + * and the #GdkWindow::to-embedder and #GdkWindow::from-embedder signals + * on the offscreen window are used to translate coordinates between + * the embedder and the offscreen window. + * + * For rendering an offscreen window onto its embedder, the contents + * of the offscreen window are available as a surface, via * gdk_offscreen_window_get_surface(). - * - * */ diff --git a/gtk/gtkaccelmap.c b/gtk/gtkaccelmap.c index f6baf08505..b7645331f8 100644 --- a/gtk/gtkaccelmap.c +++ b/gtk/gtkaccelmap.c @@ -48,61 +48,53 @@ * "low-level". You'll want to use them if you're manually creating menus that * should have user-configurable accelerators. * - * Accelerator is uniquely defined by: - * - * - * accelerator path - * accelerator key - * accelerator modifiers - * + * An accelerator is uniquely defined by: + * - accelerator path + * - accelerator key + * - accelerator modifiers * * The accelerator path must consist of * "<WINDOWTYPE>/Category1/Category2/.../Action", where WINDOWTYPE - * should be a unique application-specific identifier that corresponds to the - * kind of window the accelerator is being used in, e.g. "Gimp-Image", - * "Abiword-Document" or "Gnumeric-Settings". - * The "Category1/.../Action" portion is most appropriately chosen by the action - * the accelerator triggers, i.e. for accelerators on menu items, choose the - * item's menu path, e.g. "File/Save As", "Image/View/Zoom" or - * "Edit/Select All". So a full valid accelerator path may look like: - * "<Gimp-Toolbox>/File/Dialogs/Tool Options...". + * should be a unique application-specific identifier that corresponds + * to the kind of window the accelerator is being used in, e.g. + * "Gimp-Image", "Abiword-Document" or "Gnumeric-Settings". + * The "Category1/.../Action" portion is most appropriately chosen by + * the action the accelerator triggers, i.e. for accelerators on menu + * items, choose the item's menu path, e.g. "File/Save As", + * "Image/View/Zoom" or "Edit/Select All". So a full valid accelerator + * path may look like: "<Gimp-Toolbox>/File/Dialogs/Tool Options...". * - * All accelerators are stored inside one global #GtkAccelMap that can be - * obtained using gtk_accel_map_get(). See Monitoring changes for additional * details. * - * - * Manipulating accelerators - * - * New accelerators can be added using gtk_accel_map_add_entry(). To search for - * specific accelerator, use gtk_accel_map_lookup_entry(). Modifications of - * existing accelerators should be done using gtk_accel_map_change_entry(). + * ## Manipulating accelerators * - * In order to avoid having some accelerators changed, they can be locked using - * gtk_accel_map_lock_path(). Unlocking is done using + * New accelerators can be added using gtk_accel_map_add_entry(). + * To search for specific accelerator, use gtk_accel_map_lookup_entry(). + * Modifications of existing accelerators should be done using + * gtk_accel_map_change_entry(). + * + * In order to avoid having some accelerators changed, they can be + * locked using gtk_accel_map_lock_path(). Unlocking is done using * gtk_accel_map_unlock_path(). - * - * - * - * Saving and loading accelerator maps - * - * Accelerator maps can be saved to and loaded from some external resource. For - * simple saving and loading from file, gtk_accel_map_save() and - * gtk_accel_map_load() are provided. Saving and loading can also be done by - * providing file descriptor to gtk_accel_map_save_fd() and - * gtk_accel_map_load_fd(). - * - * - * - * Monitoring changes - * - * #GtkAccelMap object is only useful for monitoring changes of accelerators. By - * connecting to #GtkAccelMap::changed signal, one can monitor changes of all - * accelerators. It is also possible to monitor only single accelerator path by - * using it as a detail of the #GtkAccelMap::changed signal. - * - * + * + * ## Saving and loading accelerator maps + * + * Accelerator maps can be saved to and loaded from some external + * resource. For simple saving and loading from file, + * gtk_accel_map_save() and gtk_accel_map_load() are provided. + * Saving and loading can also be done by providing file descriptor + * to gtk_accel_map_save_fd() and gtk_accel_map_load_fd(). + * + * ## Monitoring changes + * + * #GtkAccelMap object is only useful for monitoring changes of + * accelerators. By connecting to #GtkAccelMap::changed signal, one + * can monitor changes of all accelerators. It is also possible to + * monitor only single accelerator path by using it as a detail of + * the #GtkAccelMap::changed signal. */ diff --git a/gtk/gtkassistant.c b/gtk/gtkassistant.c index 80cb1993d1..e0b3fe5472 100644 --- a/gtk/gtkassistant.c +++ b/gtk/gtkassistant.c @@ -27,31 +27,29 @@ * @Title: GtkAssistant * * A #GtkAssistant is a widget used to represent a generally complex - * operation splitted in several steps, guiding the user through its pages - * and controlling the page flow to collect the necessary data. + * operation splitted in several steps, guiding the user through its + * pages and controlling the page flow to collect the necessary data. * - * The design of GtkAssistant is that it controls what buttons to show and - * to make sensitive, based on what it knows about the page sequence and - * the type of each page, in - * addition to state information like the page - * completion and - * committed status. + * The design of GtkAssistant is that it controls what buttons to show + * and to make sensitive, based on what it knows about the page sequence + * and the type of each page, + * in addition to state information like the page + * completion + * and committed status. * * If you have a case that doesn't quite fit in #GtkAssistants way of - * handling buttons, you can use the #GTK_ASSISTANT_PAGE_CUSTOM page type - * and handle buttons yourself. + * handling buttons, you can use the #GTK_ASSISTANT_PAGE_CUSTOM page + * type and handle buttons yourself. * - * - * GtkAssistant as GtkBuildable - * - * The GtkAssistant implementation of the GtkBuildable interface exposes the - * @action_area as internal children with the name "action_area". + * ## GtkAssistant as GtkBuildable * - * To add pages to an assistant in GtkBuilder, simply add it as a - * <child> to the GtkAssistant object, and set its child properties + * The GtkAssistant implementation of the #GtkBuildable interface + * exposes the @action_area as internal children with the name + * "action_area". + * + * To add pages to an assistant in #GtkBuilder, simply add it as a + * child to the GtkAssistant object, and set its child properties * as necessary. - * - * */ #include "config.h" diff --git a/gtk/gtkbindings.c b/gtk/gtkbindings.c index 5dcc968bcb..53cb489854 100644 --- a/gtk/gtkbindings.c +++ b/gtk/gtkbindings.c @@ -47,27 +47,27 @@ * with high key binding configurability which requires no application * or toolkit side changes. * - * - * Installing a key binding - * + * ## Installing a key binding + * * A CSS file binding consists of a 'binding-set' definition and a match * statement to apply the binding set to specific widget types. Details * on the matching mechanism are described under * Selectors - * in the #GtkCssProvider documentation. Inside the binding set definition, - * key combinations are bound to one or more specific signal emissions on - * the target widget. Key combinations are strings consisting of an optional - * #GdkModifierType name and key names + * in the #GtkCssProvider documentation. Inside the binding set + * definition, key combinations are bound to one or more specific + * signal emissions on the target widget. Key combinations are strings + * consisting of an optional #GdkModifierType name and + * key names * such as those defined in <gdk/gdkkeysyms.h> * or returned from gdk_keyval_name(), they have to be parsable by * gtk_accelerator_parse(). Specifications of signal emissions consist * of a string identifying the signal name, and a list of signal specific * arguments in parenthesis. - * - * + * * 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: + * of a #GtkEntry widget to the #GtkEntry::move-cursor signal (so + * movement occurs in 3-character steps), the following binding can be + * used: * |[ * @binding-set MoveCursor3 * { @@ -79,11 +79,9 @@ * gtk-key-bindings: MoveCursor3; * } * ]| - * - * - * - * Unbinding existing key bindings - * + * + * ## Unbinding existing key bindings + * * GTK+ already defines a number of useful bindings for the widgets * it provides. Because custom bindings set up in CSS files take * precedence over the default bindings shipped with GTK+, overriding @@ -108,10 +106,10 @@ * from the bindings set "MoveCursor3" to be deleted, so when * "<Control>Right" or "<Control>Left" are pressed, no * binding for these keys is found in binding set "MoveCursor3". - * GTK+ will thus continue to search for matching key bindings, and will - * 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: + * GTK+ will thus continue to search for matching key bindings, and + * will 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: * |[ * @binding-set MoveCursor3 * { @@ -129,8 +127,6 @@ * so the key presses are not consumed by this widget. As usual, further * processing of the key presses, e.g. by an entry's parent widget, is * now possible. - * - * */ /* --- defines --- */ diff --git a/gtk/gtkbuilder.c b/gtk/gtkbuilder.c index f53f2103fc..e3b1fb4656 100644 --- a/gtk/gtkbuilder.c +++ b/gtk/gtkbuilder.c @@ -56,108 +56,115 @@ * The function gtk_builder_connect_signals() and variants thereof can be * used to connect handlers to the named signals in the description. * - * - * GtkBuilder UI Definitions - * - * GtkBuilder parses textual descriptions of user interfaces which are specified - * in an XML format which can be roughly described by the RELAX NG schema below. - * We refer to these descriptions as GtkBuilder UI definitions - * or just UI definitions if the context is clear. Do not - * confuse GtkBuilder UI Definitions with - * GtkUIManager UI Definitions, which are more - * limited in scope. It is common to use .ui as the filename extension for files containing GtkBuilder UI definitions. - * + * ## GtkBuilder UI Definitions + * + * GtkBuilder parses textual descriptions of user interfaces which are + * specified in an XML format which can be roughly described by the + * RELAX NG schema below. We refer to these descriptions as + * GtkBuilder UI definitions or just + * UI definitions if the context is clear. + * Do not confuse GtkBuilder UI Definitions with + * GtkUIManager UI Definitions, which + * are more limited in scope. It is common to use .ui + * as the filename extension for files containing GtkBuilder UI + * definitions. * |[ * * FIXME: MISSING XINCLUDE CONTENT * * ]| - * - * The toplevel element is <interface>. It optionally takes a "domain" - * attribute, which will make the builder look for translated strings using - * dgettext() in the domain specified. This can also be done by calling - * gtk_builder_set_translation_domain() on the builder. Objects are described by - * <object> elements, which can contain <property> elements to set - * properties, <signal> elements which connect signals to handlers, and - * <child> elements, which describe child objects (most often widgets - * inside a container, but also e.g. actions in an action group, or columns in a - * tree model). A <child> element contains an <object> element which - * describes the child object. The target toolkit version(s) are described by - * <requires> elements, the "lib" attribute specifies the widget library - * in question (currently the only supported value is "gtk+") and the "version" - * attribute specifies the target version in the form - * "<major>.<minor>". The builder will error out if the version - * requirements are not met. + * The toplevel element is <interface>. It optionally takes a + * "domain" attribute, which will make the builder look for translated + * strings using dgettext() in the domain specified. This can also be + * done by calling gtk_builder_set_translation_domain() on the builder. + * Objects are described by <object> elements, which can contain + * <property> elements to set properties, <signal> elements + * which connect signals to handlers, and <child> elements, which + * describe child objects (most often widgets inside a container, but + * also e.g. actions in an action group, or columns in a tree model). + * A <child> element contains an <object> element which + * describes the child object. The target toolkit version(s) are + * described by <requires> elements, the "lib" attribute specifies + * the widget library in question (currently the only supported value + * s "gtk+") and the "version" attribute specifies the target version + * in the form "<major>.<minor>". The builder will error + * out if the version requirements are not met. * * Typically, the specific kind of object represented by an <object> * element is specified by the "class" attribute. If the type has not been - * loaded yet, GTK+ tries to find the _get_type() from the - * class name by applying heuristics. This works in most cases, but if - * necessary, it is possible to specify the name of the - * _get_type() explictly with the "type-func" attribute. + * loaded yet, GTK+ tries to find the get_type() function from the + * class name by applying heuristics. This works in most cases, but + * if necessary, it is possible to specify the name of the + * get_type() function explictly with the "type-func" attribute. * As a special case, GtkBuilder allows to use an object that has been - * constructed by a #GtkUIManager in another part of the UI definition by - * specifying the id of the #GtkUIManager in the "constructor" attribute and the - * name of the object in the "id" attribute. + * constructed by a #GtkUIManager in another part of the UI definition + * by specifying the id of the #GtkUIManager in the "constructor" + * attribute and the name of the object in the "id" attribute. * * Objects may be given a name with the "id" attribute, which allows the * application to retrieve them from the builder with gtk_builder_get_object(). - * An id is also necessary to use the object as property value in other parts of - * the UI definition. GTK+ reserves ids starting and ending with ___ (3 underscores) - * for its own purposes. - * - * + * An id is also necessary to use the object as property value in other + * parts of the UI definition. GTK+ reserves ids starting and ending + * with ___ (3 underscores) for its own purposes. + * * Setting properties of objects is pretty straightforward with the - * <property> element: the "name" attribute specifies the name of the - * property, and the content of the element specifies the value. If the - * "translatable" attribute is set to a true value, GTK+ uses gettext() (or - * dgettext() if the builder has a translation domain set) to find a translation - * for the value. This happens before the value is parsed, so it can be used for - * properties of any type, but it is probably most useful for string properties. - * It is also possible to specify a context to disambiguate short strings, and - * comments which may help the translators. + * <property> element: the "name" attribute specifies the name + * of the property, and the content of the element specifies the value. + * If the "translatable" attribute is set to a true value, GTK+ uses + * gettext() (or dgettext() if the builder has a translation domain set) + * to find a translation for the value. This happens before the value + * is parsed, so it can be used for properties of any type, but it is + * probably most useful for string properties. It is also possible to + * specify a context to disambiguate short strings, and comments which + * may help the translators. * - * GtkBuilder can parse textual representations for the most common property - * types: characters, strings, integers, floating-point numbers, booleans - * (strings like "TRUE", "t", "yes", "y", "1" are interpreted as %TRUE, strings - * like "FALSE, "f", "no", "n", "0" are interpreted as %FALSE), enumerations - * (can be specified by their name, nick or integer value), flags (can be - * specified by their name, nick, integer value, optionally combined with "|", - * e.g. "GTK_VISIBLE|GTK_REALIZED") and colors (in a format understood by - * gdk_color_parse()). Pixbufs can be specified as a filename of an image file to load. - * Objects can be referred to by their name and by default refer to objects declared - * in the local xml fragment and objects exposed via gtk_builder_expose_object(). + * GtkBuilder can parse textual representations for the most common + * property types: characters, strings, integers, floating-point numbers, + * booleans (strings like "TRUE", "t", "yes", "y", "1" are interpreted + * as %TRUE, strings like "FALSE, "f", "no", "n", "0" are interpreted + * as %FALSE), enumerations (can be specified by their name, nick or + * integer value), flags (can be specified by their name, nick, integer + * value, optionally combined with "|", e.g. "GTK_VISIBLE|GTK_REALIZED") + * and colors (in a format understood by gdk_color_parse()). Pixbufs can + * be specified as a filename of an image file to load. Objects can be + * referred to by their name and by default refer to objects declared + * in the local xml fragment and objects exposed via + * gtk_builder_expose_object(). * - * In general, GtkBuilder allows forward references to objects &mdash declared - * in the local xml; an object doesn't have to be constructed before it can be referred to. - * The exception to this rule is that an object has to be constructed before - * it can be used as the value of a construct-only property. + * In general, GtkBuilder allows forward references to objects -- + * declared in the local xml; an object doesn't have to be constructed + * before it can be referred to. The exception to this rule is that an + * object has to be constructed before it can be used as the value of + * a construct-only property. * - * Signal handlers are set up with the <signal> element. The "name" - * attribute specifies the name of the signal, and the "handler" attribute - * specifies the function to connect to the signal. By default, GTK+ tries to - * find the handler using g_module_symbol(), but this can be changed by passing - * a custom #GtkBuilderConnectFunc to gtk_builder_connect_signals_full(). The - * remaining attributes, "after", "swapped" and "object", have the same meaning - * as the corresponding parameters of the g_signal_connect_object() or - * g_signal_connect_data() functions. A "last_modification_time" attribute - * is also allowed, but it does not have a meaning to the builder. + * Signal handlers are set up with the <signal> element. The + * "name" attribute specifies the name of the signal, and the "handler" + * attribute specifies the function to connect to the signal. By default, + * GTK+ tries to find the handler using g_module_symbol(), but this can + * be changed by passing a custom #GtkBuilderConnectFunc to + * gtk_builder_connect_signals_full(). The remaining attributes, "after", + * "swapped" and "object", have the same meaning as the corresponding + * parameters of the g_signal_connect_object() or + * g_signal_connect_data() functions. A "last_modification_time" + * attribute is also allowed, but it does not have a meaning to the + * builder. * - * Sometimes it is necessary to refer to widgets which have implicitly been - * constructed by GTK+ as part of a composite widget, to set properties on them - * or to add further children (e.g. the @vbox of a #GtkDialog). This can be - * achieved by setting the "internal-child" propery of the <child> element - * to a true value. Note that GtkBuilder still requires an <object> - * element for the internal child, even if it has already been constructed. + * Sometimes it is necessary to refer to widgets which have implicitly + * been constructed by GTK+ as part of a composite widget, to set + * properties on them or to add further children (e.g. the @vbox of + * a #GtkDialog). This can be achieved by setting the "internal-child" + * propery of the <child> element to a true value. Note that + * GtkBuilder still requires an <object> element for the internal + * child, even if it has already been constructed. + * + * A number of widgets have different places where a child can be added + * (e.g. tabs vs. page content in notebooks). This can be reflected in + * a UI definition by specifying the "type" attribute on a <child>. + * The possible values for the "type" attribute are described in the + * sections describing the widget-specific portions of UI definitions. + * + * ## A GtkBuilder UI Definition * - * A number of widgets have different places where a child can be added (e.g. - * tabs vs. page content in notebooks). This can be reflected in a UI definition - * by specifying the "type" attribute on a <child>. The possible values - * for the "type" attribute are described in the sections describing the - * widget-specific portions of UI definitions. - * - * - * A GtkBuilder UI Definition * |[ * * @@ -181,47 +188,19 @@ * * * ]| - * - * - * Beyond this general structure, several object classes define their own XML - * DTD fragments for filling in the ANY placeholders in the DTD above. Note that - * a custom element in a <child> element gets parsed by the custom tag - * handler of the parent object, while a custom element in an <object> - * element gets parsed by the custom tag handler of the object. * - * These XML fragments are explained in the documentation of the respective - * objects, see - * GtkWidget, - * GtkLabel, - * GtkWindow, - * GtkContainer, - * GtkDialog, - * GtkCellLayout, - * GtkColorSelectionDialog, - * GtkFontSelectionDialog, - * GtkExpander, - * GtkFrame, - * GtkListStore, - * GtkTreeStore, - * GtkNotebook, - * GtkSizeGroup, - * GtkTreeView, - * GtkUIManager, - * GtkActionGroup. - * GtkMenuItem, - * GtkMenuToolButton, - * GtkAssistant, - * GtkScale, - * GtkComboBoxText, - * GtkRecentFilter, - * GtkFileFilter, - * GtkTextTagTable. - * - * - * Additionally, since 3.10 a special <template> tag has been added to the format - * allowing one to define a widget class's components. - * - * + * Beyond this general structure, several object classes define their + * own XML DTD fragments for filling in the ANY placeholders in the DTD + * above. Note that a custom element in a <child> element gets + * parsed by the custom tag handler of the parent object, while a custom + * element in an <object> element gets parsed by the custom tag + * handler of the object. + * + * These XML fragments are explained in the documentation of the + * respective objects. + * + * Additionally, since 3.10 a special <template> tag has been + * added to the format allowing one to define a widget class's components. */ #include "config.h" diff --git a/gtk/gtkcellarea.c b/gtk/gtkcellarea.c index ae19c18020..8ae91ebc75 100644 --- a/gtk/gtkcellarea.c +++ b/gtk/gtkcellarea.c @@ -35,9 +35,8 @@ * Usually users dont have to interact with the #GtkCellArea directly * unless they are implementing a cell-layouting widget themselves. * - * - * Requesting area sizes - * + * ## Requesting area sizes + * * As outlined in GtkWidget's * geometry management section, GTK+ uses a height-for-width * geometry management system to compute the sizes of widgets and user @@ -72,9 +71,7 @@ * * In order to request the width of all the rows at the root level * of a #GtkTreeModel one would do the following: - * - * Requesting the width of a handful of GtkTreeModel rows - * |[ + * |[ * GtkTreeIter iter; * gint minimum_width; * gint natural_width; @@ -88,8 +85,7 @@ * valid = gtk_tree_model_iter_next (model, &iter); * } * gtk_cell_area_context_get_preferred_width (context, &minimum_width, &natural_width); - * ]| - * + * ]| * Note that in this example it's not important to observe the * returned minimum and natural width of the area for each row * unless the cell-layouting object is actually interested in the @@ -102,15 +98,13 @@ * exceedingly large amount of rows. The #GtkCellLayout widget in * that case would calculate the required width of the rows in an * idle or timeout source (see g_timeout_add()) and when the widget - * is requested its actual width in #GtkWidgetClass.get_preferred_width() + * is requested its actual width in #GtkWidgetClass.get_preferred_width() * it can simply consult the width accumulated so far in the * #GtkCellAreaContext object. * * A simple example where rows are rendered from top to bottom and * take up the full width of the layouting widget would look like: - * - * A typical get_preferred_width(<!-- -->) implementation - * |[ + * |[ * static void * foo_get_preferred_width (GtkWidget *widget, * gint *minimum_size, @@ -123,8 +117,7 @@ * * gtk_cell_area_context_get_preferred_width (priv->context, minimum_size, natural_size); * } - * ]| - * + * ]| * 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 * was appropriate to request space for in a single timeout iteration) @@ -140,9 +133,7 @@ * * In order to request the height for width of all the rows at the * root level of a #GtkTreeModel one would do the following: - * - * Requesting the height for width of a handful of GtkTreeModel rows - * |[ + * |[ * GtkTreeIter iter; * gint minimum_height; * gint natural_height; @@ -164,8 +155,7 @@ * * valid = gtk_tree_model_iter_next (model, &iter); * } - * ]| - * + * ]| * 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 * areas for each row. However we would only want to really cache the @@ -180,26 +170,22 @@ * synchronously. The reasoning here is that any layouting widget is * at least capable of synchronously calculating enough height to fill * the screen height (or scrolled window height) in response to a single - * call to #GtkWidgetClass.get_preferred_height_for_width(). Returning + * call to #GtkWidgetClass.get_preferred_height_for_width(). Returning * a perfect height for width that is larger than the screen area is * inconsequential since after the layouting receives an allocation * from a scrolled window it simply continues to drive the scrollbar * values while more and more height is required for the row heights * that are calculated in the background. - * - * - * - * Rendering Areas - * + * + * ## Rendering Areas + * * Once area sizes have been aquired at least for the rows in the * visible area of the layouting widget they can be rendered at * #GtkWidgetClass.draw() time. * * A crude example of how to render all the rows at the root level * runs as follows: - * - * Requesting the width of a handful of GtkTreeModel rows - * |[ + * |[ * GtkAllocation allocation; * GdkRectangle cell_area = { 0, }; * GtkTreeIter iter; @@ -222,19 +208,16 @@ * * valid = gtk_tree_model_iter_next (model, &iter); * } - * ]| - * + * ]| * Note that the cached height in this example really depends on how * the layouting widget works. The layouting widget might decide to * give every row its minimum or natural height or, if the model content * is expected to fit inside the layouting widget without scrolling, it * would make sense to calculate the allocation for each row at * #GtkWidget::size-allocate time using gtk_distribute_natural_allocation(). - * - * - * - * Handling Events and Driving Keyboard Focus - * + * + * ## Handling Events and Driving Keyboard Focus + * * Passing events to the area is as simple as handling events on any * normal widget and then passing them to the gtk_cell_area_event() * API as they come in. Usually #GtkCellArea is only interested in @@ -262,9 +245,7 @@ * * A basic example of how the #GtkWidgetClass.focus() virtual method * should be implemented: - * - * Implementing keyboard focus navigation - * |[ + * |[ * static gboolean * foo_focus (GtkWidget *widget, * GtkDirectionType direction) @@ -320,18 +301,15 @@ * } * return have_focus; * } - * ]| - * + * ]| * Note that the layouting widget is responsible for matching the * GtkDirectionType values to the way it lays out its cells. - * - * - * - * Cell Properties - * - * The #GtkCellArea introduces cell properties - * for #GtkCellRenderers in very much the same way that #GtkContainer - * introduces child properties + * + * ## Cell Properties + * + * The #GtkCellArea introduces cell properties for #GtkCellRenderers + * in very much the same way that #GtkContainer introduces + * child properties * for #GtkWidgets. This provides some general interfaces for defining * the relationship cell areas have with their cells. For instance in a * #GtkCellAreaBox a cell might "expand" and receive extra space when @@ -348,8 +326,6 @@ * gtk_cell_area_cell_set() or gtk_cell_area_cell_set_valist(). To obtain * the value of a cell property, use gtk_cell_area_cell_get_property(), * gtk_cell_area_cell_get() or gtk_cell_area_cell_get_valist(). - * - * */ #include "config.h" diff --git a/gtk/gtkcelllayout.c b/gtk/gtkcelllayout.c index 1bd5070f48..777a32cd38 100644 --- a/gtk/gtkcelllayout.c +++ b/gtk/gtkcelllayout.c @@ -21,22 +21,21 @@ * @Title: GtkCellLayout * * #GtkCellLayout is an interface to be implemented by all objects which - * want to provide a #GtkTreeViewColumn-like API for packing cells, setting - * attributes and data funcs. + * want to provide a #GtkTreeViewColumn like API for packing cells, + * setting attributes and data funcs. * - * One of the notable features provided by implementations of GtkCellLayout - * are attributes. Attributes let you set the properties + * One of the notable features provided by implementations of + * GtkCellLayout are attributes. Attributes let you set the properties * in flexible ways. They can just be set to constant values like regular * properties. But they can also be mapped to a column of the underlying * tree model with gtk_cell_layout_set_attributes(), which means that the value - * of the attribute can change from cell to cell as they are rendered by the - * cell renderer. Finally, it is possible to specify a function with - * gtk_cell_layout_set_cell_data_func() that is called to determine the value - * of the attribute for each cell that is rendered. + * of the attribute can change from cell to cell as they are rendered by + * the cell renderer. Finally, it is possible to specify a function with + * gtk_cell_layout_set_cell_data_func() that is called to determine the + * value of the attribute for each cell that is rendered. + * + * ## GtkCellLayouts as GtkBuildable * - * - * GtkCellLayouts as GtkBuildable - * * Implementations of GtkCellLayout which also implement the GtkBuildable * interface (#GtkCellView, #GtkIconView, #GtkComboBox, * #GtkEntryCompletion, #GtkTreeViewColumn) accept GtkCellRenderer objects @@ -46,8 +45,7 @@ * a name attribute which specifies a property of the cell renderer; the * content of the element is the attribute value. * - * - * A UI definition fragment specifying attributes + * This is an example of a UI definition fragment specifying attributes: * |[ * * @@ -58,15 +56,15 @@ * " * * ]| - * * - * Furthermore for implementations of GtkCellLayout that use a #GtkCellArea - * to lay out cells (all GtkCellLayouts in GTK+ use a GtkCellArea) - * cell properties can also be defined - * in the format by specifying the custom <cell-packing> attribute which - * can contain multiple <property> elements defined in the normal way. - * - * A UI definition fragment specifying cell properties + * Furthermore for implementations of GtkCellLayout that use a + * #GtkCellArea to lay out cells (all GtkCellLayouts in GTK+ use + * a GtkCellArea) cell properties + * can also be defined in the format by specifying the custom + * <cell-packing> attribute which can contain multiple + * <property> elements defined in the normal way. + * + * Here is a UI definition fragment specifying cell properties: * |[ * * @@ -78,13 +76,9 @@ * " * * ]| - * - * - * * - * - * Subclassing GtkCellLayout implementations - * + * ## Subclassing GtkCellLayout implementations + * * When subclassing a widget that implements #GtkCellLayout like * #GtkIconView or #GtkComboBox, there are some considerations related * to the fact that these widgets internally use a #GtkCellArea. @@ -128,8 +122,6 @@ * to support alternative cell areas, you can do so by moving the * problematic calls out of init() and into a constructor() * for your class. - * - * */ #include "config.h" diff --git a/gtk/gtkcomboboxtext.c b/gtk/gtkcomboboxtext.c index 80325b64c3..3fecdc9497 100644 --- a/gtk/gtkcomboboxtext.c +++ b/gtk/gtkcomboboxtext.c @@ -52,9 +52,8 @@ * You should not call gtk_combo_box_set_model() or attempt to pack more cells * into this combo box via its GtkCellLayout interface. * - * - * GtkComboBoxText as GtkBuildable - * + * ## GtkComboBoxText as GtkBuildable + * * The GtkComboBoxText implementation of the GtkBuildable interface * supports adding items directly using the <items> element * and specifying <item> elements for each item. Each <item> @@ -62,8 +61,7 @@ * also supports the regular translation attributes "translatable", * "context" and "comments". * - * - * A UI definition fragment specifying GtkComboBoxText items + * Here is a a UI definition fragment specifying GtkComboBoxText items: * |[ * * @@ -73,9 +71,6 @@ * * * ]| - * - * - * */ static void gtk_combo_box_text_buildable_interface_init (GtkBuildableIface *iface); diff --git a/gtk/gtkcontainer.c b/gtk/gtkcontainer.c index bd8d059210..805fbb2a20 100644 --- a/gtk/gtkcontainer.c +++ b/gtk/gtkcontainer.c @@ -78,9 +78,8 @@ * children in a horizontal row, and a #GtkGrid arranges the widgets it contains * in a two-dimensional grid. * - * - * Height for width geometry management - * + * ## Height for width geometry management + * * GTK+ uses a height-for-width (and width-for-height) geometry management system. * Height-for-width means that a widget can change how much vertical space it needs, * depending on the amount of horizontal space that it is given (and similar for @@ -151,7 +150,7 @@ * * Height for width requests are generally implemented in terms of a virtual allocation * of widgets in the input orientation. Assuming an height-for-width request mode, a container - * would implement the get_preferred_height_for_width() virtual function by first calling + * would implement the get_preferred_height_for_width() virtual function by first calling * gtk_widget_get_preferred_width() for each of its children. * * For each potential group of children that are lined up horizontally, the values returned by @@ -180,11 +179,9 @@ * * See GtkWidget's geometry management section * to learn more about implementing height-for-width geometry management for widgets. - * - * - * - * Child properties - * + * + * ## Child properties + * * GtkContainer introduces child properties. * These are object properties that are not specific * to either the container or the contained widget, but rather to their relation. @@ -202,17 +199,15 @@ * gtk_container_child_get_property(), gtk_container_child_get() or * gtk_container_child_get_valist(). To emit notification about child property * changes, use gtk_widget_child_notify(). - * - * - * - * GtkContainer as GtkBuildable - * + * + * ## GtkContainer as GtkBuildable + * * The GtkContainer implementation of the GtkBuildable interface * supports a <packing> element for children, which can * contain multiple <property> elements that specify * child properties for the child. - * - * Child properties in UI definitions + * + * An example of child properties in UI definitions: * |[ * * @@ -223,12 +218,10 @@ * * * ]| - * + * * Since 2.16, child properties can also be marked as translatable using * the same "translatable", "comments" and "context" attributes that are used * for regular properties. - * - * */ diff --git a/gtk/gtkcssprovider.c b/gtk/gtkcssprovider.c index cfccb9e883..28484382ce 100644 --- a/gtk/gtkcssprovider.c +++ b/gtk/gtkcssprovider.c @@ -55,9 +55,8 @@ * It is able to parse CSS-like * input in order to style widgets. * - * - * Default files - * + * ## Default files + * * An application can cause GTK+ to parse a specific CSS style sheet by * calling gtk_css_provider_load_from_file() and adding the provider with * gtk_style_context_add_provider() or gtk_style_context_add_provider_for_screen(). @@ -71,61 +70,52 @@ * (see the #GtkSettings:gtk-theme-name setting) and datadir * is the prefix configured when GTK+ was compiled, unless overridden by the * GTK_DATA_PREFIX environment variable. - * - * - * - * Style sheets - * + * + * ## Style sheets + * * The basic structure of the style sheets understood by this provider is * a series of statements, which are either rule sets or '@-rules', separated * by whitespace. - * - * + * * A rule set consists of a selector and a declaration block, which is * a series of declarations enclosed in curly braces ({ and }). The * declarations are separated by semicolons (;). Multiple selectors can * share the same declaration block, by putting all the separators in * front of the block, separated by commas. - * - * A rule set with two selectors + * + * An example of a rule set with two selectors: * |[ * GtkButton, GtkEntry { * color: #ff00ea; * font: Comic Sans 12 * } * ]| - * - * - * - * Selectors - * - * Selectors work very similar to the way they do in CSS, with widget class + * + * ## Selectors + * + * Selectors work very similar to the way they do in CSS, with widget class * names taking the role of element names, and widget names taking the role * of IDs. When used in a selector, widget names must be prefixed with a * '#' character. The '*' character represents the so-called universal - * selector, which matches any widget. - * - * + * selector, which matches any widget. + * * To express more complicated situations, selectors can be combined in * various ways: - * - * To require that a widget satisfies several conditions, + * - To require that a widget satisfies several conditions, * combine several selectors into one by concatenating them. E.g. * GtkButton#button1 matches a GtkButton widget - * with the name button1. - * To only match a widget when it occurs inside some other + * with the name button1. + * - To only match a widget when it occurs inside some other * widget, write the two selectors after each other, separated by whitespace. * E.g. GtkToolBar GtkButton matches GtkButton widgets - * that occur inside a GtkToolBar. - * In the previous example, the GtkButton is matched even + * that occur inside a GtkToolBar. + * - In the previous example, the GtkButton is matched even * if it occurs deeply nested inside the toolbar. To restrict the match * to direct children of the parent widget, insert a '>' character between * the two selectors. E.g. GtkNotebook > GtkLabel matches - * GtkLabel widgets that are direct children of a GtkNotebook. - * - * - * - * Widget classes and names in selectors + * GtkLabel widgets that are direct children of a GtkNotebook. + * + * An example of widget classes and names in selectors: * |[ * /* Theme labels that are descendants of a window */ * GtkWindow GtkLabel { @@ -160,25 +150,21 @@ * background-color: #f0a810 * } * ]| - * - * + * * Widgets may also define style classes, which can be used for matching. * When used in a selector, style classes must be prefixed with a '.' * character. - * - * + * * Refer to the documentation of individual widgets to learn which * style classes they define and see * for a list of all style classes used by GTK+ widgets. - * - * + * * Note that there is some ambiguity in the selector syntax when it comes * to differentiation widget class names from regions. GTK+ currently treats * a string as a widget class name if it contains any uppercase characters * (which should work for more widgets with names like GtkLabel). - * - * - * Style classes in selectors + * + * An example for style classes in selectors: * |[ * /* Theme all widgets defining the class entry */ * .entry { @@ -190,29 +176,25 @@ * color: #900185 * } * ]| - * - * + * * In complicated widgets like e.g. a GtkNotebook, it may be desirable * to style different parts of the widget differently. To make this * possible, container widgets may define regions, whose names * may be used for matching in selectors. - * - * + * * Some containers allow to further differentiate between regions by * applying so-called pseudo-classes to the region. For example, the * tab region in GtkNotebook allows to single out the first or last * tab by using the :first-child or :last-child pseudo-class. * When used in selectors, pseudo-classes must be prefixed with a * ':' character. - * - * + * * Refer to the documentation of individual widgets to learn which * regions and pseudo-classes they define and see * for a list of all regions * used by GTK+ widgets. - * - * - * Regions in selectors + * + * An example for regions in selectors: * |[ * /* Theme any label within a notebook */ * GtkNotebook GtkLabel { @@ -231,16 +213,14 @@ * color: #89d012; * } * ]| - * - * + * * Another use of pseudo-classes is to match widgets depending on their * state. This is conceptually similar to the :hover, :active or :focus * pseudo-classes in CSS. The available pseudo-classes for widget states * are :active, :prelight (or :hover), :insensitive, :selected, :focused * and :inconsistent. - * - * - * Styling specific widget states + * + * And example for styling specific widget states: * |[ * /* Theme active (pressed) buttons */ * GtkButton:active { @@ -275,45 +255,37 @@ * background-color: #20395a; * } * ]| - * - * + * * Widget state pseudoclasses may only apply to the last element * in a selector. - * - * + * * To determine the effective style for a widget, all the matching rule * sets are merged. As in CSS, rules apply by specificity, so the rules * whose selectors more closely match a widget path will take precedence * over the others. - * - * - * - * @ Rules - * + * + * ## @ Rules + * * GTK+'s CSS supports the @import rule, in order to load another * CSS style sheet in addition to the currently parsed one. - * - * - * Using the @import rule + * + * An example for using the @import rule: * |[ * @import url ("path/to/common.css"); * ]| - * - * + * * In order to extend key bindings affecting different widgets, GTK+ * supports the @binding-set rule to parse a set of bind/unbind * directives, see #GtkBindingSet for the supported syntax. Note that * the binding sets defined in this way must be associated with rule sets * by setting the gtk-key-bindings style property. - * - * + * * Customized key bindings are typically defined in a separate * gtk-keys.css CSS file and GTK+ loads this file * according to the current key theme, which is defined by the * #GtkSettings:gtk-key-theme-name setting. - * - * - * Using the @binding rule + * + * An example for using the @binding rule: * |[ * @binding-set binding-set1 { * bind "Left" { "move-cursor" (visual-positions, -3, 0) }; @@ -330,15 +302,13 @@ * gtk-key-bindings: binding-set1, binding-set2; * } * ]| - * - * + * * GTK+ also supports an additional @define-color rule, in order * to define a color name which may be used instead of color numeric * representations. Also see the #GtkSettings:gtk-color-scheme setting * for a way to override the values of these named colors. - * - * - * Defining colors + * + * An example for defining colors: * |[ * @define-color bg_color #f9a039; * @@ -346,18 +316,15 @@ * background-color: @bg_color; * } * ]| - * - * - * - * Symbolic colors - * + * + * ## Symbolic colors + * * Besides being able to define color names, the CSS parser is also able * to read different color expressions, which can also be nested, providing * a rich language to define colors which are derived from a set of base * colors. - * - * - * Using symbolic colors + * + * An example for using symbolic colors: * |[ * @define-color entry-color shade (@bg_color, 0.7); * @@ -371,10 +338,8 @@ * 0.8); * } * ]| - * - * - * The various ways to express colors in GTK+ CSS are: - * + * + * The various ways to express colors in GTK+ CSS are: * * * @@ -445,13 +410,11 @@ * * * - * - * - * Gradients - * + * + * ## Gradients + * * Linear or radial Gradients can be used as background images. - * - * + * * A linear gradient along the line from (@start_x, @start_y) to * (@end_x, @end_y) is specified using the syntax * -gtk-gradient (linear, @@ -466,26 +429,23 @@ * The color-stop can be repeated multiple times to add more than one color * stop. 'from (@color)' and 'to (@color)' can be used as abbreviations for * color stops with position 0 and 1, respectively. - * - * - * A linear gradient + * + * An example for a linear gradient: * - * This gradient was specified with + * This gradient was specified with * -gtk-gradient (linear, * left top, right bottom, - * from(@yellow), to(@blue)) - * - * - * Another linear gradient + * from(@yellow), to(@blue)) + * + * Another example for a linear gradient: * - * This gradient was specified with + * This gradient was specified with * -gtk-gradient (linear, * 0 0, 0 1, * color-stop(0, @yellow), * color-stop(0.2, @blue), - * color-stop(1, #0f0)) - * - * + * color-stop(1, #0f0)) + * * A radial gradient along the two circles defined by (@start_x, @start_y, * @start_radius) and (@end_x, @end_y, @end_radius) is specified using the * syntax @@ -496,63 +456,53 @@ * ...) * where @start_radius and @end_radius are floating point numbers and * the other parameters are as before. - * - * - * A radial gradient + * + * An example of a radial gradient: * - * This gradient was specified with + * This gradient was specified with * -gtk-gradient (radial, * center center, 0, * center center, 1, - * from(@yellow), to(@green)) - * - * - * Another radial gradient + * from(@yellow), to(@green)) + * + * Another example of a radial gradient: * - * This gradient was specified with + * This gradient was specified with * -gtk-gradient (radial, * 0.4 0.4, 0.1, * 0.6 0.6, 0.7, * color-stop (0, #f00), * color-stop (0.1, #a0f), * color-stop (0.2, @yellow), - * color-stop (1, @green)) - * - * - * - * Text shadow - * + * color-stop (1, @green)) + * + * ## Text shadow + * * A shadow list can be applied to text or symbolic icons, using the CSS3 * text-shadow syntax, as defined in * the CSS3 specification. - * - * + * * A text shadow is specified using the syntax * text-shadow: @horizontal_offset @vertical_offset [ @blur_radius ] @color * The offset of the shadow is specified with the @horizontal_offset and @vertical_offset * parameters. The optional blur radius is parsed, but it is currently not rendered by * the GTK+ theming engine. - * - * + * * To set a shadow on an icon, use the icon-shadow property instead, * with the same syntax. - * - * + * * To set multiple shadows on an element, you can specify a comma-separated list * of shadow elements in the text-shadow or icon-shadow property. Shadows are * always rendered front-back, i.e. the first shadow specified is on top of the * others. Shadows can thus overlay each other, but they can never overlay the * text or icon itself, which is always rendered on top of the shadow layer. - * - * - * - * Box shadow - * + * + * ## Box shadow + * * Themes can apply shadows on framed elements using the CSS3 box-shadow syntax, * as defined in * the CSS3 specification. - * - * + * * A box shadow is specified using the syntax * box-shadow: [ @inset ] @horizontal_offset @vertical_offset [ @blur_radius ] [ @spread ] @color * A positive offset will draw a shadow that is offset to the right (down) of the box, @@ -562,51 +512,44 @@ * the GTK+ theming engine. * The inset parameter defines whether the drop shadow should be rendered inside or outside * the box canvas. - * - * + * * To set multiple box-shadows on an element, you can specify a comma-separated list * of shadow elements in the box-shadow property. Shadows are always rendered * front-back, i.e. the first shadow specified is on top of the others, so they may * overlap other boxes or other shadows. - * - * - * - * Border images - * + * + * ## Border images + * * Images and gradients can also be used in slices for the purpose of creating * scalable borders. * For more information, see the CSS3 documentation for the border-image property, * which can be found here. - * + * * - * + * * The parameters of the slicing process are controlled by * four separate properties. Note that you can use the * border-image shorthand property * to set values for the three properties at the same time. - * - * + * * border-image-source: url(@path) * (or border-image-source: -gtk-gradient(...)): * Specifies the source of the border image, and it can either * be an URL or a gradient (see above). - * - * + * * border-image-slice: @top @right @bottom @left * The sizes specified by the @top, @right, @bottom and @left parameters * are the offsets, in pixels, from the relevant edge where the image * should be "cut off" to build the slices used for the rendering * of the border. - * - * + * * border-image-width: @top @right @bottom @left * The sizes specified by the @top, @right, @bottom and @left parameters * are inward distances from the border box edge, used to specify the * rendered size of each slice determined by border-image-slice. * If this property is not specified, the values of border-width will * be used as a fallback. - * - * + * * border-image-repeat: [stretch|repeat|round|space] ? * [stretch|repeat|round|space] * Specifies how the image slices should be rendered in the area @@ -625,31 +568,25 @@ * If two options are specified, the first one affects * the horizontal behaviour and the second one the vertical behaviour. * If only one option is specified, it affects both. - * - * - * A border image + * + * An example of a border image: * - * This border image was specified with + * This border image was specified with * url("gradient1.png") 10 10 10 10 - * - * - * - * A repeating border image + * + * An example of a repeating border image: * - * This border image was specified with + * This border image was specified with * url("gradient1.png") 10 10 10 10 repeat - * - * - * - * A stretched border image + * + * An example of a stretched border image: * - * This border image was specified with + * This border image was specified with * url("gradient1.png") 10 10 10 10 stretch - * - * - * - * - * Styles can specify transitions that will be used to create a gradual + * + * ## Transitions + * + * Styles can specify transitions that will be used to create a gradual * change in the appearance when a widget state changes. The following * syntax is used to specify transitions: * @duration [s|ms] [linear|ease|ease-in|ease-out|ease-in-out] [loop]? @@ -673,19 +610,15 @@ *
Ease-out transition * *
- * - * - * - * Supported properties - * + * + * ## Supported properties + * * Properties are the part that differ the most to common CSS, * not all properties are supported (some are planned to be * supported eventually, some others are meaningless or don't * map intuitively in a widget based environment). - * - * + * * The currently supported properties are: - * * * * @@ -953,7 +886,7 @@ * * * - * + * * GtkThemingEngines can register their own, engine-specific style properties * with the function gtk_theming_engine_register_property(). These properties * can be set in CSS like other properties, using a name of the form @@ -962,9 +895,8 @@ * name of the property. Style properties that have been registered by widgets * using gtk_widget_class_install_style_property() can also be set in this * way, using the widget class name for namespace. - * - * - * Using engine-specific style properties + * + * An example for using engine-specific style properties: * |[ * * { * engine: clearlooks; @@ -973,8 +905,6 @@ * -clearlooks-colorize-scrollbar: false; * } * ]| - * - * */ typedef struct GtkCssRuleset GtkCssRuleset; diff --git a/gtk/gtkdialog.c b/gtk/gtkdialog.c index 7c638189e8..51a5d94046 100644 --- a/gtk/gtkdialog.c +++ b/gtk/gtkdialog.c @@ -63,8 +63,8 @@ * * #GtkDialog boxes are created with a call to gtk_dialog_new() or * gtk_dialog_new_with_buttons(). gtk_dialog_new_with_buttons() is - * recommended; it allows you to set the dialog title, some convenient flags, - * and add simple buttons. + * recommended; it allows you to set the dialog title, some convenient + * flags, and add simple buttons. * * If 'dialog' is a newly created dialog, the two primary areas of the * window can be accessed through gtk_dialog_get_content_area() and @@ -96,8 +96,8 @@ * use #GtkMessageDialog to save yourself some effort. But you'd need to * create the dialog contents manually if you had more than a simple message * in the dialog. - * - * Simple GtkDialog usage + * + * An example for simple GtkDialog usage: * |[ * /* Function to open a dialog box displaying the message provided. */ * void @@ -127,22 +127,19 @@ * gtk_widget_show_all (dialog); * } * ]| - * * - * GtkDialog as GtkBuildable - * + * ## GtkDialog as GtkBuildable + * * The GtkDialog implementation of the #GtkBuildable interface exposes the * @vbox and @action_area as internal children with the names "vbox" and * "action_area". - * - * + * * GtkDialog supports a custom <action-widgets> element, which * can contain multiple <action-widget> elements. The "response" * attribute specifies a numeric response, and the content of the element * is the id of widget (which should be a child of the dialogs @action_area). - * - * - * A #GtkDialog UI definition fragment. + * + * An example of a #GtkDialog UI definition fragment: * |[ * * @@ -165,8 +162,6 @@ * * * ]| - * - * */ struct _GtkDialogPrivate diff --git a/gtk/gtkexpander.c b/gtk/gtkexpander.c index c8b15664a7..41c6979095 100644 --- a/gtk/gtkexpander.c +++ b/gtk/gtkexpander.c @@ -32,9 +32,8 @@ * to add it to the expander. When the expander is toggled, it will take * care of showing and hiding the child automatically. * - * - * Special Usage - * + * ## Special Usage + * * There are situations in which you may prefer to show and hide the * expanded widget yourself, such as when you want to actually create * the widget at expansion time. In this case, create a #GtkExpander @@ -42,7 +41,7 @@ * #GtkExpander:expanded property which can be used to monitor * its expansion state. You should watch this property with a signal * connection as follows: - * + * * |[ * expander = gtk_expander_new_with_mnemonic ("_More Options"); * g_signal_connect (expander, "notify::expanded", @@ -69,18 +68,16 @@ * } * } * ]| - * - * - * GtkExpander as GtkBuildable - * + * + * ## GtkExpander as GtkBuildable + * * The GtkExpander implementation of the GtkBuildable interface * supports placing a child in the label position by specifying * "label" as the "type" attribute of a <child> element. * A normal content child can be specified without specifying * a <child> type attribute. - * - * - * A UI definition fragment with GtkExpander + * + * An example of a UI definition fragment with GtkExpander: * |[ * * @@ -91,9 +88,6 @@ * * * ]| - * - * - * */ #include "config.h" diff --git a/gtk/gtkfilechooser.c b/gtk/gtkfilechooser.c index eee7976659..68aa4c4e18 100644 --- a/gtk/gtkfilechooser.c +++ b/gtk/gtkfilechooser.c @@ -43,34 +43,20 @@ * In the default implementation these are displayed in the left pane. It * may be a bit confusing at first that these shortcuts come from various * sources and in various flavours, so lets explain the terminology here: - * - * - * Bookmarks - * - * are created by the user, by dragging folders from the - * right pane to the left pane, or by using the "Add". Bookmarks - * can be renamed and deleted by the user. - * - * - * - * Shortcuts - * - * can be provided by the application. For example, a Paint program may - * want to add a shortcut for a Clipart folder. Shortcuts cannot be modified by the - * user. - * - * - * - * Volumes - * - * are provided by the underlying filesystem abstraction. They are - * the "roots" of the filesystem. - * - * - * * - * - * File Names and Encodings + * - Bookmarks: are created by the user, by dragging folders from the + * right pane to the left pane, or by using the "Add". Bookmarks + * can be renamed and deleted by the user. + * + * - Shortcuts: can be provided by the application. For example, a Paint + * program may want to add a shortcut for a Clipart folder. Shortcuts + * cannot be modified by the user. + * + * - Volumes: are provided by the underlying filesystem abstraction. They are + * the "roots" of the filesystem. + * + * ## File Names and Encodings + * * When the user is finished selecting files in a * #GtkFileChooser, your program can get the selected names * either as filenames or as URIs. For URIs, the normal escaping @@ -80,27 +66,24 @@ * G_FILENAME_ENCODING environment variable. * Please see the GLib documentation for more details about this * variable. - * - * This means that while you can pass the result of - * gtk_file_chooser_get_filename() to - * open(2) or fopen(3), you may not be able to - * directly set it as the text of a #GtkLabel widget unless you - * convert it first to UTF-8, which all GTK+ widgets expect. - * You should use g_filename_to_utf8() to convert filenames - * into strings that can be passed to GTK+ widgets. - * - * - * - * Adding a Preview Widget - * + * + * This means that while you can pass the result of + * gtk_file_chooser_get_filename() to open() or fopen(), + * you may not be able to directly set it as the text of a + * #GtkLabel widget unless you convert it first to UTF-8, + * which all GTK+ widgets expect. You should use g_filename_to_utf8() + * to convert filenames into strings that can be passed to GTK+ + * widgets. + * + * ## Adding a Preview Widget + * * You can add a custom preview widget to a file chooser and then * get notification about when the preview needs to be updated. * To install a preview widget, use * gtk_file_chooser_set_preview_widget(). Then, connect to the * #GtkFileChooser::update-preview signal to get notified when * you need to update the contents of the preview. - * - * + * * Your callback should use * gtk_file_chooser_get_preview_filename() to see what needs * previewing. Once you have generated the preview for the @@ -108,9 +91,8 @@ * gtk_file_chooser_set_preview_widget_active() with a boolean * flag that indicates whether your callback could successfully * generate a preview. - * - * - * Sample Usage + * + * An example for using a preview widget: * |[ * { * GtkImage *preview; @@ -146,20 +128,17 @@ * gtk_file_chooser_set_preview_widget_active (file_chooser, have_preview); * } * ]| - * - * - * - * Adding Extra Widgets - * + * + * ## Adding Extra Widgets + * * You can add extra widgets to a file chooser to provide options * that are not present in the default design. For example, you * can add a toggle button to give the user the option to open a * file in read-only mode. You can use * gtk_file_chooser_set_extra_widget() to insert additional * widgets in a file chooser. - * - * - * Sample Usage + * + * An example for adding extra widgets: * |[ * * GtkWidget *toggle; @@ -171,14 +150,11 @@ * gtk_file_chooser_set_extra_widget (my_file_chooser, toggle); * } * ]| - * - * - * If you want to set more than one extra widget in the file - * chooser, you can a container such as a #GtkBox or a #GtkGrid - * and include your widgets in it. Then, set the container as - * the whole extra widget. - * - * + * + * If you want to set more than one extra widget in the file + * chooser, you can a container such as a #GtkBox or a #GtkGrid + * and include your widgets in it. Then, set the container as + * the whole extra widget. */ diff --git a/gtk/gtkfilefilter.c b/gtk/gtkfilefilter.c index fb4fc66bd7..cf57597e06 100644 --- a/gtk/gtkfilefilter.c +++ b/gtk/gtkfilefilter.c @@ -38,18 +38,17 @@ * see gtk_file_chooser_add_filter(), but it is also possible * to manually use a filter on a file with gtk_file_filter_filter(). * - * - * GtkFileFilter as GtkBuildable - * + * ## GtkFileFilter as GtkBuildable + * * The GtkFileFilter implementation of the GtkBuildable interface - * supports adding rules using the <mime-types>, <patterns> and - * <applications> elements and listing the rules within. Specifying - * a <mime-type> or <pattern> is the same + * supports adding rules using the <mime-types>, <patterns> + * and <applications> elements and listing the rules within. + * Specifying a <mime-type> or <pattern> is the same * as calling gtk_recent_filter_add_mime_type() * or gtk_recent_filter_add_pattern(). * - * - * A UI definition fragment specifying GtkFileFilter rules + * An example of a UI definition fragment specifying GtkFileFilter + * rules: * |[ * * @@ -62,9 +61,6 @@ * * * ]| - * - * - * */ #include "config.h" diff --git a/gtk/gtkfontchooserdialog.c b/gtk/gtkfontchooserdialog.c index 7400a5fba9..17c575e978 100644 --- a/gtk/gtkfontchooserdialog.c +++ b/gtk/gtkfontchooserdialog.c @@ -54,12 +54,11 @@ struct _GtkFontChooserDialogPrivate * The #GtkFontChooserDialog widget is a dialog for selecting a font. * It implements the #GtkFontChooser interface. * - * - * GtkFontChooserDialog as GtkBuildable - * The GtkFontChooserDialog implementation of the GtkBuildable interface - * exposes the buttons with the names - * "select_button" and "cancel_button". - * + * ## GtkFontChooserDialog as GtkBuildable + * + * The GtkFontChooserDialog implementation of the #GtkBuildable + * interface exposes the buttons with the names "select_button" + * and "cancel_button". * * Since: 3.2 */ diff --git a/gtk/gtkframe.c b/gtk/gtkframe.c index 3e302c32a5..32b35a6c5a 100644 --- a/gtk/gtkframe.c +++ b/gtk/gtkframe.c @@ -45,17 +45,15 @@ * top side of the frame. The position of the * label can be controlled with gtk_frame_set_label_align(). * - * - * GtkFrame as GtkBuildable - * + * ## GtkFrame as GtkBuildable + * * The GtkFrame implementation of the GtkBuildable interface * supports placing a child in the label position by specifying * "label" as the "type" attribute of a <child> element. * A normal content child can be specified without specifying * a <child> type attribute. - * - * - * A UI definition fragment with GtkFrame + * + * An example of a UI definition fragment with GtkFrame: * |[ * * @@ -66,8 +64,6 @@ * * * ]| - * - * */ diff --git a/gtk/gtkinfobar.c b/gtk/gtkinfobar.c index 5d6dee4f34..07fa6d4722 100644 --- a/gtk/gtkinfobar.c +++ b/gtk/gtkinfobar.c @@ -72,8 +72,7 @@ * by using gtk_info_bar_set_message_type(). GTK+ may use the message type * to determine how the message is displayed. * - * - * Simple GtkInfoBar usage. + * A simple example for using a GtkInfoBar: * |[ * /* set up info bar */ * info_bar = gtk_info_bar_new (); @@ -98,22 +97,17 @@ * GTK_MESSAGE_ERROR); * gtk_widget_show (info_bar); * ]| - * * - * - * GtkInfoBar as GtkBuildable - * + * ## GtkInfoBar as GtkBuildable + * * The GtkInfoBar implementation of the GtkBuildable interface exposes * the content area and action area as internal children with the names * "content_area" and "action_area". - * - * + * * GtkInfoBar supports a custom <action-widgets> element, which * can contain multiple <action-widget> elements. The "response" * attribute specifies a numeric response, and the content of the element * is the id of widget (which should be a child of the dialogs @action_area). - * - * */ enum diff --git a/gtk/gtklabel.c b/gtk/gtklabel.c index 91e8b533ef..acff4b5263 100644 --- a/gtk/gtklabel.c +++ b/gtk/gtklabel.c @@ -67,16 +67,14 @@ * implies, most labels are used to label another widget such as a * #GtkButton, a #GtkMenuItem, or a #GtkComboBox. * - * - * GtkLabel as GtkBuildable - * + * ## GtkLabel as GtkBuildable + * * The GtkLabel implementation of the GtkBuildable interface supports a * custom <attributes> element, which supports any number of <attribute> * elements. the <attribute> element has attributes named name, value, * start and end and allows you to specify #PangoAttribute values for this label. * - * - * A UI definition fragment specifying Pango attributes + * An example of a UI definition fragment specifying Pango attributes: * |[ * * @@ -85,17 +83,15 @@ * * * ]| - * + * * The start and end attributes specify the range of characters to which the * Pango attribute applies. If start and end are not specified, the attribute is * applied to the whole text. Note that specifying ranges does not make much * sense with translatable attributes. Use markup embedded in the translatable * content instead. - * - * - * - * Mnemonics - * + * + * ## Mnemonics + * * Labels may contain mnemonics. Mnemonics are * underlined characters in the label, used for keyboard navigation. * Mnemonics are created by providing a string with an underscore before @@ -110,8 +106,8 @@ * the label is inside a button: * * |[ - * // Pressing Alt+H will activate this button - * button = gtk_button_new (); + * /* Pressing Alt+H will activate this button */ + * button = gtk_button_new (); * label = gtk_label_new_with_mnemonic ("_Hello"); * gtk_container_add (GTK_CONTAINER (button), label); * ]| @@ -120,7 +116,7 @@ * already inside: * * |[ - * // Pressing Alt+H will activate this button + * /* Pressing Alt+H will activate this button */ * button = gtk_button_new_with_mnemonic ("_Hello"); * ]| * @@ -129,21 +125,19 @@ * gtk_label_set_mnemonic_widget(): * * |[ - * // Pressing Alt+H will focus the entry - * entry = gtk_entry_new (); + * /* Pressing Alt+H will focus the entry */ + * entry = gtk_entry_new (); * label = gtk_label_new_with_mnemonic ("_Hello"); * gtk_label_set_mnemonic_widget (GTK_LABEL (label), entry); * ]| - * - * - * - * Markup (styled text) - * - * To make it easy to format text in a label (changing colors, fonts, - * etc.), label text can be provided in a simple markup format. - * Here's how to create a label with a small font: * + * ## Markup (styled text) + * + * To make it easy to format text in a label (changing colors, + * fonts, etc.), label text can be provided in a simple markup format. + * + * Here's how to create a label with a small font: * |[ * label = gtk_label_new (NULL); * gtk_label_set_markup (GTK_LABEL (label), "Small text"); @@ -167,18 +161,16 @@ * to [0, %G_MAXINT)). The reason is that specifying the start_index and * end_index for a #PangoAttribute requires knowledge of the exact string * being displayed, so translations will cause problems. - * - * - * - * Selectable labels + * + * ## Selectable labels + * * Labels can be made selectable with gtk_label_set_selectable(). * Selectable labels allow the user to copy the label contents to * the clipboard. Only labels that contain useful-to-copy information * — such as error messages — should be made selectable. - * - * - * Text layout - * + * + * ## Text layout + * * A label can contain any number of paragraphs, but will have * performance problems if it contains more than a small number. * Paragraphs are separated by newlines or other paragraph separators @@ -200,30 +192,25 @@ * is used as the natural width. Even if max-width-chars specified, wrapping * labels will be rewrapped to use all of the available width. * - * * Note that the interpretation of #GtkLabel:width-chars and * #GtkLabel:max-width-chars has changed a bit with the introduction of * width-for-height geometry management. - * - * - * - * - * Links - * + * + * ## Links + * * Since 2.18, GTK+ supports markup for clickable hyperlinks in addition * to regular Pango markup. The markup for links is borrowed from HTML, using the * a with href and title attributes. GTK+ renders links similar to the * way they appear in web browsers, with colored, underlined text. The title - * attribute is displayed as a tooltip on the link. An example looks like this: + * attribute is displayed as a tooltip on the link. * + * An example looks like this: * |[ * gtk_label_set_markup (label, "Go to the GTK+ website for more..."); * ]| * * It is possible to implement custom handling for links and their tooltips with * the #GtkLabel::activate-link signal and the gtk_label_get_current_uri() function. - * - * */ struct _GtkLabelPrivate diff --git a/gtk/gtkliststore.c b/gtk/gtkliststore.c index 09891e7cd5..5465eb1334 100644 --- a/gtk/gtkliststore.c +++ b/gtk/gtkliststore.c @@ -46,15 +46,14 @@ * The #GtkListStore can accept most GObject types as a column type, though * it can't accept all custom types. Internally, it will keep a copy of * data passed in (such as a string or a boxed pointer). Columns that - * accept #GObjects are handled a little differently. The + * accept #GObjects are handled a little differently. The * #GtkListStore will keep a reference to the object instead of copying the * value. As a result, if the object is modified, it is up to the * application writer to call gtk_tree_model_row_changed() to emit the * #GtkTreeModel::row_changed signal. This most commonly affects lists with - * #GdkPixbufs stored. + * #GdkPixbufs stored. * - * - * Creating a simple list store. + * An example for creating a simple list store: * |[ * enum { * COLUMN_STRING, @@ -80,7 +79,7 @@ * * some_data = get_some_data (i); * - * // Add a new row to the model + * /* Add a new row to the model */ * gtk_list_store_append (list_store, &iter); * gtk_list_store_set (list_store, &iter, * COLUMN_STRING, some_data, @@ -88,13 +87,13 @@ * COLUMN_BOOLEAN, FALSE, * -1); * - * /* As the store will keep a copy of the string internally, we - * * free some_data. - * */ + * /* As the store will keep a copy of the string internally, + * * we free some_data. + * */ * g_free (some_data); * } * - * // Modify a particular row + * /* Modify a particular row */ * path = gtk_tree_path_new_from_string ("4"); * gtk_tree_model_get_iter (GTK_TREE_MODEL (list_store), * &iter, @@ -105,20 +104,19 @@ * -1); * } * ]| - * * - * - * Performance Considerations - * Internally, the #GtkListStore was implemented with a linked list with a - * tail pointer prior to GTK+ 2.6. As a result, it was fast at data + * ## Performance Considerations + * + * Internally, the #GtkListStore was implemented with a linked list with + * a tail pointer prior to GTK+ 2.6. As a result, it was fast at data * insertion and deletion, and not fast at random data access. The * #GtkListStore sets the #GTK_TREE_MODEL_ITERS_PERSIST flag, which means * that #GtkTreeIters can be cached while the row exists. Thus, if * access to a particular row is needed often and your code is expected to * run on older versions of GTK+, it is worth keeping the iter around. - * - * - * Atomic Operations + * + * ## Atomic Operations + * * It is important to note that only the methods * gtk_list_store_insert_with_values() and gtk_list_store_insert_with_valuesv() * are atomic, in the sense that the row is being appended to the store and the @@ -133,10 +131,9 @@ * to append rows to the #GtkListStore will cause the * #GtkTreeModelFilterVisibleFunc to be visited with an empty row first; the * function must be prepared for that. - * - * - * GtkListStore as GtkBuildable - * + * + * ## GtkListStore as GtkBuildable + * * The GtkListStore implementation of the GtkBuildable interface allows * to specify the model columns with a <columns> element that may * contain multiple <column> elements, each specifying one model @@ -155,8 +152,7 @@ * and common wisdom is to separate the two, as far as possible. * * - * - * A UI Definition fragment for a list store + * An example of a UI Definition fragment for a list store: * |[ * * @@ -178,9 +174,6 @@ * * * ]| - * - * - * */ diff --git a/gtk/gtkmenuitem.c b/gtk/gtkmenuitem.c index 4740f40ee5..6d365c161d 100644 --- a/gtk/gtkmenuitem.c +++ b/gtk/gtkmenuitem.c @@ -64,22 +64,20 @@ * GtkMenuItem has direct functions to set the label and its mnemonic. * For more advanced label settings, you can fetch the child widget from the GtkBin. * - * - * Setting markup and accelerator on a MenuItem + * An example for setting markup and accelerator on a MenuItem: * |[ * GtkWidget *child = gtk_bin_get_child (GTK_BIN (menu_item)); * gtk_label_set_markup (GTK_LABEL (child), "new label with markup"); * gtk_accel_label_set_accel (GTK_ACCEL_LABEL (child), GDK_KEY_1, 0); * ]| - * * - * - * GtkMenuItem as GtkBuildable + * ## GtkMenuItem as GtkBuildable + * * The GtkMenuItem implementation of the #GtkBuildable interface * supports adding a submenu by specifying "submenu" as the "type" * attribute of a <child> element. - * - * A UI definition fragment with submenus + * + * An example of UI definition fragment with submenus: * |[ * * @@ -87,8 +85,6 @@ * * * ]| - * - * */ diff --git a/gtk/gtkmenushell.c b/gtk/gtkmenushell.c index 113bb4acf0..e1eb806334 100644 --- a/gtk/gtkmenushell.c +++ b/gtk/gtkmenushell.c @@ -35,9 +35,8 @@ * user to perform application functions. A #GtkMenuItem can have a * submenu associated with it, allowing for nested hierarchical menus. * - * - * Terminology - * + * ## Terminology + * * A menu item can be "selected", this means that it is displayed * in the prelight state, and if it has a submenu, that submenu * will be popped up. @@ -55,8 +54,6 @@ * a selected menu item.) The current menu is the menu that * contains the current menu item. It will always have a GTK * grab and receive all key presses. - * - * */ #include "config.h" diff --git a/gtk/gtkmenutoolbutton.c b/gtk/gtkmenutoolbutton.c index 7d9eae47d2..6269a83a38 100644 --- a/gtk/gtkmenutoolbutton.c +++ b/gtk/gtkmenutoolbutton.c @@ -48,15 +48,13 @@ * Use gtk_menu_tool_button_new() to create a new * #GtkMenuToolButton. * - * - * GtkMenuToolButton as GtkBuildable - * + * ## GtkMenuToolButton as GtkBuildable + * * The GtkMenuToolButton implementation of the GtkBuildable interface * supports adding a menu by specifying "menu" as the "type" * attribute of a <child> element. * - * - * A UI definition fragment with menus + * An example for a UI definition fragment with menus: * |[ * * @@ -64,9 +62,6 @@ * * * ]| - * - * - * */ diff --git a/gtk/gtkmessagedialog.c b/gtk/gtkmessagedialog.c index 5fe172461f..2c96334955 100644 --- a/gtk/gtkmessagedialog.c +++ b/gtk/gtkmessagedialog.c @@ -57,28 +57,28 @@ * you can also pass in the %GTK_DIALOG_MODAL flag, gtk_dialog_run() automatically * makes the dialog modal and waits for the user to respond to it. gtk_dialog_run() * returns when any dialog button is clicked. - * - * A modal dialog. + * + * An example for using a modal dialog: * |[ * dialog = gtk_message_dialog_new (main_application_window, * GTK_DIALOG_DESTROY_WITH_PARENT, * GTK_MESSAGE_ERROR, * GTK_BUTTONS_CLOSE, - * "Error loading file '%s': %s", + * "Error loading file '%s': %s", * filename, g_strerror (errno)); * gtk_dialog_run (GTK_DIALOG (dialog)); * gtk_widget_destroy (dialog); * ]| - * + * * You might do a non-modal #GtkMessageDialog as follows: - * - * A non-modal dialog. + * + * An example for a non-modal dialog: * |[ * dialog = gtk_message_dialog_new (main_application_window, * GTK_DIALOG_DESTROY_WITH_PARENT, * GTK_MESSAGE_ERROR, * GTK_BUTTONS_CLOSE, - * "Error loading file '%s': %s", + * "Error loading file '%s': %s", * filename, g_strerror (errno)); * * /* Destroy the dialog when the user responds to it (e.g. clicks a button) */ @@ -86,15 +86,11 @@ * G_CALLBACK (gtk_widget_destroy), * dialog); * ]| - * * - * - * GtkMessageDialog as GtkBuildable - * + * ## GtkMessageDialog as GtkBuildable + * * The GtkMessageDialog implementation of the GtkBuildable interface exposes * the message area as an internal child with the name "message_area". - * - * */ struct _GtkMessageDialogPrivate diff --git a/gtk/gtknotebook.c b/gtk/gtknotebook.c index 8e431a4736..1092ab0d2b 100644 --- a/gtk/gtknotebook.c +++ b/gtk/gtknotebook.c @@ -64,9 +64,8 @@ * will be a popup menu allowing the users to switch pages. * (see gtk_notebook_popup_enable(), gtk_notebook_popup_disable()) * - * - * GtkNotebook as GtkBuildable - * + * ## GtkNotebook as GtkBuildable + * * The GtkNotebook implementation of the #GtkBuildable interface * supports placing children into tabs by specifying "tab" as the * "type" attribute of a <child> element. Note that the content @@ -77,9 +76,8 @@ * To add a child widget in the notebooks action area, specify * "action-start" or "action-end" as the "type" attribute of the <child> * element. - * - * - * A UI definition fragment with GtkNotebook + * + * An example of a UI definition fragment with GtkNotebook: * |[ * * @@ -94,8 +92,6 @@ * * * ]| - * - * */ diff --git a/gtk/gtkoverlay.c b/gtk/gtkoverlay.c index 3fae8a187d..4205153095 100644 --- a/gtk/gtkoverlay.c +++ b/gtk/gtkoverlay.c @@ -46,14 +46,11 @@ * More complicated placement of overlays is possible by connecting * to the #GtkOverlay::get-child-position signal. * - * - * GtkOverlay as GtkBuildable - * + * ## GtkOverlay as GtkBuildable + * * The GtkOverlay implementation of the GtkBuildable interface * supports placing a child as an overlay by specifying "overlay" as * the "type" attribute of a child element. - * - * */ struct _GtkOverlayPrivate diff --git a/gtk/gtkprintunixdialog.c b/gtk/gtkprintunixdialog.c index 4891cd4f0b..a9b115c293 100644 --- a/gtk/gtkprintunixdialog.c +++ b/gtk/gtkprintunixdialog.c @@ -76,30 +76,18 @@ * gtk_print_job_new(). * * #GtkPrintUnixDialog uses the following response values: - * - * %GTK_RESPONSE_OK - * for the "Print" button - * - * %GTK_RESPONSE_APPLY - * for the "Preview" button - * - * %GTK_RESPONSE_CANCEL - * for the "Cancel" button - * - * - * - * + * - %GTK_RESPONSE_OK: for the "Print" button + * - %GTK_RESPONSE_APPLY: for the "Preview" button + * - %GTK_RESPONSE_CANCEL: for the "Cancel" button * * Printing support was added in GTK+ 2.10. * - * - * GtkPrintUnixDialog as GtkBuildable - * + * ## GtkPrintUnixDialog as GtkBuildable + * * The GtkPrintUnixDialog implementation of the GtkBuildable interface exposes its * @notebook internal children with the name "notebook". * - * - * A #GtkPrintUnixDialog UI definition fragment. + * An example of a #GtkPrintUnixDialog UI definition fragment: * |[ * * @@ -122,9 +110,6 @@ * * * ]| - * - * - * */ diff --git a/gtk/gtkrecentfilter.c b/gtk/gtkrecentfilter.c index a62b0fc901..e5077eb93b 100644 --- a/gtk/gtkrecentfilter.c +++ b/gtk/gtkrecentfilter.c @@ -40,9 +40,8 @@ * * Recently used files are supported since GTK+ 2.10. * - * - * GtkRecentFilter as GtkBuildable - * + * ## GtkRecentFilter as GtkBuildable + * * The GtkRecentFilter implementation of the GtkBuildable interface * supports adding rules using the <mime-types>, <patterns> and * <applications> elements and listing the rules within. Specifying @@ -50,8 +49,7 @@ * as calling gtk_recent_filter_add_mime_type(), gtk_recent_filter_add_pattern() * or gtk_recent_filter_add_application(). * - * - * A UI definition fragment specifying GtkRecentFilter rules + * An example of a UI definition fragment specifying GtkRecentFilter rules: * |[ * * @@ -69,9 +67,6 @@ * * * ]| - * - * - * */ #include "config.h" diff --git a/gtk/gtkscale.c b/gtk/gtkscale.c index 3f2c5932ef..589b106ee0 100644 --- a/gtk/gtkscale.c +++ b/gtk/gtkscale.c @@ -61,14 +61,14 @@ * applications that want to show an undeterminate value on the scale, without * changing the layout of the application (such as movie or music players). * - * GtkScale as GtkBuildable + * ## GtkScale as GtkBuildable + * * GtkScale supports a custom <marks> element, which * can contain multiple <mark> elements. The "value" and "position" * attributes have the same meaning as gtk_scale_add_mark() parameters of the * same name. If the element is not empty, its content is taken as the markup * to show at the mark. It can be translated with the usual "translatable and * "context" attributes. - * */ diff --git a/gtk/gtkscrollable.c b/gtk/gtkscrollable.c index 3c7c76fcc6..0ed52e785f 100644 --- a/gtk/gtkscrollable.c +++ b/gtk/gtkscrollable.c @@ -26,44 +26,27 @@ * To implement this interface you should override the * #GtkScrollable:hadjustment and #GtkScrollable:vadjustment properties. * - * - * Creating a scrollable widget - * + * ## Creating a scrollable widget + * * All scrollable widgets should do the following. * - * - * - * - * When a parent widget sets the scrollable child widget's adjustments, the widget should populate the adjustments' - * #GtkAdjustment:lower, #GtkAdjustment:upper, - * #GtkAdjustment:step-increment, #GtkAdjustment:page-increment and - * #GtkAdjustment:page-size properties and connect to the - * #GtkAdjustment::value-changed signal. - * - * - * - * - * Because its preferred size is the size for a fully expanded widget, - * the scrollable widget must be able to cope with underallocations. - * This means that it must accept any value passed to its - * #GtkWidgetClass.size_allocate() function. - * - * - * - * - * When the parent allocates space to the scrollable child widget, the widget should update - * the adjustments' properties with new values. - * - * - * - * - * When any of the adjustments emits the #GtkAdjustment::value-changed signal, - * the scrollable widget should scroll its contents. - * - * - * - * - * + * - When a parent widget sets the scrollable child widget's adjustments, + * the widget should populate the adjustments' + * #GtkAdjustment:lower, #GtkAdjustment:upper, + * #GtkAdjustment:step-increment, #GtkAdjustment:page-increment and + * #GtkAdjustment:page-size properties and connect to the + * #GtkAdjustment::value-changed signal. + * + * - Because its preferred size is the size for a fully expanded widget, + * the scrollable widget must be able to cope with underallocations. + * This means that it must accept any value passed to its + * #GtkWidgetClass.size_allocate() function. + * + * - When the parent allocates space to the scrollable child widget, + * the widget should update the adjustments' properties with new values. + * + * - When any of the adjustments emits the #GtkAdjustment::value-changed signal, + * the scrollable widget should scroll its contents. */ #include "config.h" diff --git a/gtk/gtksizegroup.c b/gtk/gtksizegroup.c index e98cfef43c..0d495fee8f 100644 --- a/gtk/gtksizegroup.c +++ b/gtk/gtksizegroup.c @@ -82,9 +82,8 @@ * by way of #GtkLabel:width-chars for instance. Widgets with static sizes as well * as widgets that grow (such as ellipsizing text) need no such considerations. * - * - * GtkSizeGroup as GtkBuildable - * + * ## GtkSizeGroup as GtkBuildable + * * Size groups can be specified in a UI definition by placing an * <object> element with class="GtkSizeGroup" * somewhere in the UI definition. The widgets that belong to the @@ -92,8 +91,7 @@ * contain multiple <widget> elements, one for each member * of the size group. The name attribute gives the id of the widget. * - * - * A UI definition fragment with GtkSizeGroup + * An example of a UI definition fragment with GtkSizeGroup: * |[ * * GTK_SIZE_GROUP_HORIZONTAL @@ -103,9 +101,6 @@ * * * ]| - * - * - * */ diff --git a/gtk/gtkstylecontext.c b/gtk/gtkstylecontext.c index 859a007c20..249a50575d 100644 --- a/gtk/gtkstylecontext.c +++ b/gtk/gtkstylecontext.c @@ -75,21 +75,18 @@ * #GtkSettings:gtk-theme-name setting or a hierarchy change in the rendered * widget. * - * - * Transition animations - * + * ## Transition animations + * * #GtkStyleContext has built-in support for state change transitions. * Note that these animations respect the #GtkSettings:gtk-enable-animations * setting. - * - * + * * For simple widgets where state changes affect the whole widget area, * calling gtk_style_context_notify_state_change() with a %NULL region * is sufficient to trigger the transition animation. And GTK+ already * does that when gtk_widget_set_state() or gtk_widget_set_state_flags() * are called. - * - * + * * If a widget needs to declare several animatable regions (i.e. not * affecting the whole widget area), its #GtkWidget::draw signal handler * needs to wrap the render operations for the different regions with @@ -98,9 +95,8 @@ * identifier for the region which must be unique within the style context. * For simple widgets with a fixed set of animatable regions, using an * enumeration works well: - * - * - * Using an enumeration to identify animatable regions + * + * An example for Using an enumeration to identify animatable regions: * |[ * enum { * REGION_ENTRY, @@ -129,15 +125,13 @@ * ... * } * ]| - * - * + * * For complex widgets with an arbitrary number of animatable regions, it * is up to the implementation to come up with a way to uniquely identify * each animatable region. Using pointers to internal structs is one way * to achieve this: - * - * - * Using struct pointers to identify animatable regions + * + * An example for using struct pointers to identify animatable regions: * |[ * void * notebook_draw_tab (GtkWidget *widget, @@ -149,13 +143,11 @@ * gtk_style_context_pop_animatable_region (context); * } * ]| - * - * + * * The widget also needs to notify the style context about a state change * for a given animatable region so the animation is triggered. - * - * - * Triggering a state change animation on a region + * + * An example for triggering a state change animation on a region: * |[ * gboolean * notebook_motion_notify (GtkWidget *widget, @@ -174,70 +166,17 @@ * ... * } * ]| - * - * + * * gtk_style_context_notify_state_change() accepts %NULL region IDs as a * special value, in this case, the whole widget area will be updated * by the animation. - * - * - * - * Style classes and regions - * - * Widgets can add style classes to their context, which can be used - * to associate different styles by class (see ). Theme engines can also use style classes to vary their - * rendering. GTK+ has a number of predefined style classes: - * #GTK_STYLE_CLASS_CELL, - * #GTK_STYLE_CLASS_ENTRY, - * #GTK_STYLE_CLASS_BUTTON, - * #GTK_STYLE_CLASS_COMBOBOX_ENTRY, - * #GTK_STYLE_CLASS_CALENDAR, - * #GTK_STYLE_CLASS_SLIDER, - * #GTK_STYLE_CLASS_BACKGROUND, - * #GTK_STYLE_CLASS_RUBBERBAND, - * #GTK_STYLE_CLASS_TOOLTIP, - * #GTK_STYLE_CLASS_MENU, - * #GTK_STYLE_CLASS_MENUBAR, - * #GTK_STYLE_CLASS_MENUITEM, - * #GTK_STYLE_CLASS_TOOLBAR, - * #GTK_STYLE_CLASS_PRIMARY_TOOLBAR, - * #GTK_STYLE_CLASS_INLINE_TOOLBAR, - * #GTK_STYLE_CLASS_RADIO, - * #GTK_STYLE_CLASS_CHECK, - * #GTK_STYLE_CLASS_TROUGH, - * #GTK_STYLE_CLASS_SCROLLBAR, - * #GTK_STYLE_CLASS_SCALE, - * #GTK_STYLE_CLASS_SCALE_HAS_MARKS_ABOVE, - * #GTK_STYLE_CLASS_SCALE_HAS_MARKS_BELOW, - * #GTK_STYLE_CLASS_HEADER, - * #GTK_STYLE_CLASS_ACCELERATOR, - * #GTK_STYLE_CLASS_GRIP, - * #GTK_STYLE_CLASS_DOCK, - * #GTK_STYLE_CLASS_PROGRESSBAR, - * #GTK_STYLE_CLASS_SPINNER, - * #GTK_STYLE_CLASS_EXPANDER, - * #GTK_STYLE_CLASS_SPINBUTTON, - * #GTK_STYLE_CLASS_NOTEBOOK, - * #GTK_STYLE_CLASS_VIEW, - * #GTK_STYLE_CLASS_SIDEBAR, - * #GTK_STYLE_CLASS_IMAGE, - * #GTK_STYLE_CLASS_HIGHLIGHT, - * #GTK_STYLE_CLASS_FRAME, - * #GTK_STYLE_CLASS_DND, - * #GTK_STYLE_CLASS_PANE_SEPARATOR, - * #GTK_STYLE_CLASS_SEPARATOR, - * #GTK_STYLE_CLASS_INFO, - * #GTK_STYLE_CLASS_WARNING, - * #GTK_STYLE_CLASS_QUESTION, - * #GTK_STYLE_CLASS_ERROR, - * #GTK_STYLE_CLASS_HORIZONTAL, - * #GTK_STYLE_CLASS_VERTICAL, - * #GTK_STYLE_CLASS_TOP, - * #GTK_STYLE_CLASS_BOTTOM, - * #GTK_STYLE_CLASS_LEFT, - * #GTK_STYLE_CLASS_RIGHT, - * - * + * + * ## Style classes and regions + * + * Widgets can add style classes to their context, which can be used + * to associate different styles by class (see ). + * Theme engines can also use style classes to vary their rendering. + * * Widgets can also add regions with flags to their context. * The regions used by GTK+ widgets are: * @@ -278,19 +217,16 @@ * * * - * - * - * - * Custom styling in UI libraries and applications - * + * + * ## Custom styling in UI libraries and applications + * * If you are developing a library with custom #GtkWidgets that * render differently than standard components, you may need to add a * #GtkStyleProvider yourself with the %GTK_STYLE_PROVIDER_PRIORITY_FALLBACK * priority, either a #GtkCssProvider or a custom object implementing the * #GtkStyleProvider interface. This way theming engines may still attempt * to style your UI elements in a different way if needed so. - * - * + * * If you are using custom styling on an applications, you probably want then * to make your style information prevail to the theme's, so you must use * a #GtkStyleProvider with the %GTK_STYLE_PROVIDER_PRIORITY_APPLICATION @@ -298,14 +234,11 @@ * XDG_CONFIG_HOME/gtk-3.0/gtk.css will * still take precedence over your changes, as it uses the * %GTK_STYLE_PROVIDER_PRIORITY_USER priority. - * - * + * * If a custom theming engine is needed, you probably want to implement a * #GtkStyleProvider yourself so it points to your #GtkThemingEngine * implementation, as #GtkCssProvider uses gtk_theming_engine_load() * which loads the theming engine module from the standard paths. - * - * */ /* When these change we do a full restyling. Otherwise we try to figure out diff --git a/gtk/gtktexttagtable.c b/gtk/gtktexttagtable.c index ee1907b832..4032af04c2 100644 --- a/gtk/gtktexttagtable.c +++ b/gtk/gtktexttagtable.c @@ -44,15 +44,13 @@ * conceptual overview which gives an overview of all the objects and * data types related to the text widget and how they work together. * - * - * GtkTextTagTables as GtkBuildable - * + * ## GtkTextTagTables as GtkBuildable + * * The GtkTextTagTable implementation of the GtkBuildable interface * supports adding tags by specifying "tag" as the "type" * attribute of a <child> element. * - * - * A UI definition fragment specifying tags + * An example of a UI definition fragment specifying tags: * |[ * * @@ -60,9 +58,6 @@ * * * ]| - * - * - * */ struct _GtkTextTagTablePrivate diff --git a/gtk/gtktreestore.c b/gtk/gtktreestore.c index 6f25ca0626..5f02731d82 100644 --- a/gtk/gtktreestore.c +++ b/gtk/gtktreestore.c @@ -41,14 +41,14 @@ * drag and drop * interfaces. * - * - * GtkTreeStore as GtkBuildable + * ## GtkTreeStore as GtkBuildable + * * The GtkTreeStore implementation of the #GtkBuildable interface allows * to specify the model columns with a <columns> element that may * contain multiple <column> elements, each specifying one model * column. The "type" attribute specifies the data type for the column. - * - * A UI Definition fragment for a tree store + * + * An example of a UI Definition fragment for a tree store: * |[ * * @@ -58,8 +58,6 @@ * * * ]| - * - * */ struct _GtkTreeStorePrivate diff --git a/gtk/gtktreeview.c b/gtk/gtktreeview.c index 43956f1f44..653330894a 100644 --- a/gtk/gtktreeview.c +++ b/gtk/gtktreeview.c @@ -78,30 +78,15 @@ * These are: * * - * Coordinate systems in GtkTreeView API - * Widget coordinates - * - * - * Coordinates relative to the widget (usually widget->window). - * - * - * - * Bin window coordinates - * - * - * Coordinates relative to the window that GtkTreeView renders to. - * - * - * - * Tree coordinates - * - * - * Coordinates relative to the entire scrollable area of GtkTreeView. These - * coordinates start at (0, 0) for row 0 of the tree. - * - * - * - * + * + * Coordinate systems in GtkTreeView API: + * + * - Widget coordinates: Coordinates relative to the widget (usually widget->window). + * + * - Bin window coordinates: Coordinates relative to the window that GtkTreeView renders to. + * + * - Tree coordinates: Coordinates relative to the entire scrollable area of GtkTreeView. These + * coordinates start at (0, 0) for row 0 of the tree. * * Several functions are available for converting between the different * coordinate systems. The most common translations are between widget and bin @@ -110,13 +95,13 @@ * (and vice versa), for the latter gtk_tree_view_convert_bin_window_to_tree_coords() * (and vice versa). * - * - * GtkTreeView as GtkBuildable + * ## GtkTreeView as GtkBuildable + * * The GtkTreeView implementation of the GtkBuildable interface accepts * #GtkTreeViewColumn objects as <child> elements and exposes the * internal #GtkTreeSelection in UI definitions. - * - * A UI definition fragment with GtkTreeView + * + * An example of a UI definition fragment with GtkTreeView: * |[ * * liststore1 @@ -138,8 +123,6 @@ * * * ]| - * - * */ enum diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c index d4bb18b2d4..b817dc7031 100644 --- a/gtk/gtkwidget.c +++ b/gtk/gtkwidget.c @@ -77,26 +77,23 @@ * GtkWidget is the base class all widgets in GTK+ derive from. It manages the * widget lifecycle, states and style. * - * - * Height-for-width Geometry Management - * - * GTK+ uses a height-for-width (and width-for-height) geometry management + * ## Height-for-width Geometry Management + * + * GTK+ uses a height-for-width (and width-for-height) geometry management * system. Height-for-width means that a widget can change how much * vertical space it needs, depending on the amount of horizontal space * that it is given (and similar for width-for-height). The most common * example is a label that reflows to fill up the available width, wraps - * to fewer lines, and therefore needs less height. + * to fewer lines, and therefore needs less height. * * Height-for-width geometry management is implemented in GTK+ by way * of five virtual methods: - * - * #GtkWidgetClass.get_request_mode() - * #GtkWidgetClass.get_preferred_width() - * #GtkWidgetClass.get_preferred_height() - * #GtkWidgetClass.get_preferred_height_for_width() - * #GtkWidgetClass.get_preferred_width_for_height() - * #GtkWidgetClass.get_preferred_height_and_baseline_for_width() - * + * - #GtkWidgetClass.get_request_mode() + * - #GtkWidgetClass.get_preferred_width() + * - #GtkWidgetClass.get_preferred_height() + * - #GtkWidgetClass.get_preferred_height_for_width() + * - #GtkWidgetClass.get_preferred_width_for_height() + * - #GtkWidgetClass.get_preferred_height_and_baseline_for_width() * * There are some important things to keep in mind when implementing * height-for-width and when using it in container implementations. @@ -177,7 +174,6 @@ * * And in #GtkWidgetClass.get_preferred_width_for_height() it will simply return * the minimum and natural width: - * * |[ * static void * foo_widget_get_preferred_width_for_height (GtkWidget *widget, gint for_height, @@ -201,13 +197,10 @@ * compute width. Or when deciding how to use an allocation, the widget * may need to know its natural size. In these cases, the widget should * be careful to call its virtual methods directly, like this: - * - * Widget calling its own size request method. - * |[ + * |[ * GTK_WIDGET_GET_CLASS(widget)->get_preferred_width (widget), * &min, &natural); - * ]| - * + * ]| * * It will not work to use the wrapper functions, such as * gtk_widget_get_preferred_width() inside your own size request @@ -243,11 +236,8 @@ * If this has a value other than -1 you need to align the widget such that the baseline * appears at the position. * - * - * - * - * Style Properties - * + * ## Style Properties + * * #GtkWidget introduces style * properties - these are basically object properties that are stored * not on the object, but in the style object associated to the widget. Style @@ -255,38 +245,32 @@ * This mechanism is used for configuring such things as the location of the * scrollbar arrows through the theme, giving theme authors more control over the * look of applications without the need to write a theme engine in C. - * - * + * * Use gtk_widget_class_install_style_property() to install style properties for * a widget class, gtk_widget_class_find_style_property() or * gtk_widget_class_list_style_properties() to get information about existing * style properties and gtk_widget_style_get_property(), gtk_widget_style_get() or * gtk_widget_style_get_valist() to obtain the value of a style property. - * - * - * - * GtkWidget as GtkBuildable - * + * + * ## GtkWidget as GtkBuildable + * * The GtkWidget implementation of the GtkBuildable interface supports a * custom <accelerator> element, which has attributes named key, * modifiers and signal and allows to specify accelerators. - * - * - * A UI definition fragment specifying an accelerator + * + * An example of a UI definition fragment specifying an accelerator: * |[ * * * * ]| - * - * + * * In addition to accelerators, #GtkWidget also support a * custom <accessible> element, which supports actions and relations. * Properties on the accessible implementation of an object can be set by accessing the * internal child "accessible" of a #GtkWidget. - * - * - * A UI definition fragment specifying an accessible + * + * An example of a UI definition fragment specifying an accessible: * |[ * * I am a Label for a Button @@ -303,12 +287,9 @@ * * * ]| - * - * + * * Finally, GtkWidget allows style information such as style classes to * be associated with widgets, using the custom <style> element: - * - * A UI definition fragment specifying an style class * |[ * * * * ]| - * - * - * - * - * Building composite widgets from template XML - * + * + * ## Building composite widgets from template XML + * * GtkWidget exposes some facilities to automate the proceedure * of creating composite widgets using #GtkBuilder interface description * language. - * - * + * * To create composite widgets with #GtkBuilder XML, one must associate * the interface description with the widget class at class initialization * time using gtk_widget_class_set_template(). - * - * + * * The interface description semantics expected in composite template descriptions * is slightly different from regulare #GtkBuilder XML. - * - * + * * Unlike regular interface descriptions, gtk_widget_class_set_template() will expect a * <template> tag as a direct child of the toplevel <interface> * tag. The <template> tag must specify the "class" attribute which @@ -345,23 +320,19 @@ * is ignored by the GtkBuilder but required for Glade to introspect what kind * of properties and internal children exist for a given type when the actual * type does not exist. - * - * + * * The XML which is contained inside the <template> tag behaves as if * it were added to the <object> tag defining @widget itself. You may set * properties on @widget by inserting <property> tags into the <template> * tag, and also add <child> tags to add children and extend @widget in the * normal way you would with <object> tags. - * - * + * * Additionally, <object> tags can also be added before and * after the initial <template> tag in the normal way, allowing * one to define auxilary objects which might be referenced by other * widgets declared as children of the <template> tag. - * - * - * - * A GtkBuilder Template Definition + * + * An example of a GtkBuilder Template Definition: * |[ * * * * ]| - * - * - * */ #define GTK_STATE_FLAGS_DO_PROPAGATE (GTK_STATE_FLAG_INSENSITIVE|GTK_STATE_FLAG_BACKDROP) diff --git a/gtk/gtkwindow.c b/gtk/gtkwindow.c index dd756deaf2..132617ae44 100644 --- a/gtk/gtkwindow.c +++ b/gtk/gtkwindow.c @@ -89,35 +89,30 @@ * control whether a window has a resize grip, use * gtk_window_set_has_resize_grip(). * - * - * GtkWindow as GtkBuildable - * + * ## GtkWindow as GtkBuildable + * * The GtkWindow implementation of the GtkBuildable interface supports a * custom accel-groups element, which supports * any number of group elements representing the * #GtkAccelGroup objects you want to add to your window (synonymous with * gtk_window_add_accel_group(). - * - * - * A UI definition fragment with accel groups + * + * An example of a UI definition fragment with accel groups: * |[ * * * * * - * + * * ... - * + * * * ]| - * - * + * * The GtkWindow implementation of the GtkBuildable interface * supports setting a child as the titlebar by specifying "titlebar" as * the "type" attribute of a child element. - * - * */ #define MNEMONICS_DELAY 300 /* ms */