Commit 3aabcd28 authored by Matthias Clasen's avatar Matthias Clasen

More precise documentation about underscores and mnemonics. (#66380)

        * gtk/gtklabel.c (gtk_label_new_with_mnemonic),
        gtk/gtkbutton.c (gtk_button_new_with_mnemonic): More precise
        documentation about underscores and mnemonics. (#66380)

        * gtk/gtktextiter.c (gtk_text_iter_backward_word_starts): Fix
        cyclic reference in docs.

        * gtk/gtklabel.c (gtk_label_set_justify): Correct documentation
        of default value. (#65402)

        * gtk/gtkmain.c (gtk_set_locale, gtk_disable_set_locale):
        Markup fixes.

        * gdk-pixbuf-io.c, gdk-pixbuf-animation.c, gdk-pixbuf-data.c,
        gdk-pixbuf-loader.c, gdk-pixbuf-scale.c, gdk-pixbuf-util.c,
        gdk-pixdata.c: Markup fixes.

        * gtk/text_widget.sgml: More precise wording. (#63388)

        * gtk/tmpl/gtksignal.sgml (GTK_SIGNAL_OFFSET): Add docs.

        * gtk/resources.sgml: Fix markup of mail URLs.

        * gtk/tmpl/gtkpaned.sgml, gtk/tmpl/gtkobject.sgml: Markup fixes.

        * gtk/tmpl/gtktoolbar.sgml (gtk_toolbar_{prepend,append}_element):
        Expand documentation. (#60471)

        * gtk/tmpl/gtkmain.sgml: Remove misleading information about
        gtk_set_locale().  (#65758)
parent ecfd1aff
2001-12-21 Matthias Clasen <matthiasc@poet.de>
* gtk/gtklabel.c (gtk_label_new_with_mnemonic),
gtk/gtkbutton.c (gtk_button_new_with_mnemonic): More precise
documentation about underscores and mnemonics. (#66380)
* gtk/gtktextiter.c (gtk_text_iter_backward_word_starts): Fix
cyclic reference in docs.
* gtk/gtklabel.c (gtk_label_set_justify): Correct documentation
of default value. (#65402)
* gtk/gtkmain.c (gtk_set_locale, gtk_disable_set_locale):
Markup fixes.
2001-12-20 Anders Carlsson <andersca@gnu.org>
* gtk/gtktreeview.c (gtk_tree_view_realize): Don't call
......
2001-12-21 Matthias Clasen <matthiasc@poet.de>
* gtk/gtklabel.c (gtk_label_new_with_mnemonic),
gtk/gtkbutton.c (gtk_button_new_with_mnemonic): More precise
documentation about underscores and mnemonics. (#66380)
* gtk/gtktextiter.c (gtk_text_iter_backward_word_starts): Fix
cyclic reference in docs.
* gtk/gtklabel.c (gtk_label_set_justify): Correct documentation
of default value. (#65402)
* gtk/gtkmain.c (gtk_set_locale, gtk_disable_set_locale):
Markup fixes.
2001-12-20 Anders Carlsson <andersca@gnu.org>
* gtk/gtktreeview.c (gtk_tree_view_realize): Don't call
......
2001-12-21 Matthias Clasen <matthiasc@poet.de>
* gtk/gtklabel.c (gtk_label_new_with_mnemonic),
gtk/gtkbutton.c (gtk_button_new_with_mnemonic): More precise
documentation about underscores and mnemonics. (#66380)
* gtk/gtktextiter.c (gtk_text_iter_backward_word_starts): Fix
cyclic reference in docs.
* gtk/gtklabel.c (gtk_label_set_justify): Correct documentation
of default value. (#65402)
* gtk/gtkmain.c (gtk_set_locale, gtk_disable_set_locale):
Markup fixes.
2001-12-20 Anders Carlsson <andersca@gnu.org>
* gtk/gtktreeview.c (gtk_tree_view_realize): Don't call
......
2001-12-21 Matthias Clasen <matthiasc@poet.de>
* gtk/gtklabel.c (gtk_label_new_with_mnemonic),
gtk/gtkbutton.c (gtk_button_new_with_mnemonic): More precise
documentation about underscores and mnemonics. (#66380)
* gtk/gtktextiter.c (gtk_text_iter_backward_word_starts): Fix
cyclic reference in docs.
* gtk/gtklabel.c (gtk_label_set_justify): Correct documentation
of default value. (#65402)
* gtk/gtkmain.c (gtk_set_locale, gtk_disable_set_locale):
Markup fixes.
2001-12-20 Anders Carlsson <andersca@gnu.org>
* gtk/gtktreeview.c (gtk_tree_view_realize): Don't call
......
2001-12-21 Matthias Clasen <matthiasc@poet.de>
* gtk/gtklabel.c (gtk_label_new_with_mnemonic),
gtk/gtkbutton.c (gtk_button_new_with_mnemonic): More precise
documentation about underscores and mnemonics. (#66380)
* gtk/gtktextiter.c (gtk_text_iter_backward_word_starts): Fix
cyclic reference in docs.
* gtk/gtklabel.c (gtk_label_set_justify): Correct documentation
of default value. (#65402)
* gtk/gtkmain.c (gtk_set_locale, gtk_disable_set_locale):
Markup fixes.
2001-12-20 Anders Carlsson <andersca@gnu.org>
* gtk/gtktreeview.c (gtk_tree_view_realize): Don't call
......
2001-12-21 Matthias Clasen <matthiasc@poet.de>
* gtk/gtklabel.c (gtk_label_new_with_mnemonic),
gtk/gtkbutton.c (gtk_button_new_with_mnemonic): More precise
documentation about underscores and mnemonics. (#66380)
* gtk/gtktextiter.c (gtk_text_iter_backward_word_starts): Fix
cyclic reference in docs.
* gtk/gtklabel.c (gtk_label_set_justify): Correct documentation
of default value. (#65402)
* gtk/gtkmain.c (gtk_set_locale, gtk_disable_set_locale):
Markup fixes.
2001-12-20 Anders Carlsson <andersca@gnu.org>
* gtk/gtktreeview.c (gtk_tree_view_realize): Don't call
......
2001-12-21 Matthias Clasen <matthiasc@poet.de>
* gtk/gtklabel.c (gtk_label_new_with_mnemonic),
gtk/gtkbutton.c (gtk_button_new_with_mnemonic): More precise
documentation about underscores and mnemonics. (#66380)
* gtk/gtktextiter.c (gtk_text_iter_backward_word_starts): Fix
cyclic reference in docs.
* gtk/gtklabel.c (gtk_label_set_justify): Correct documentation
of default value. (#65402)
* gtk/gtkmain.c (gtk_set_locale, gtk_disable_set_locale):
Markup fixes.
2001-12-20 Anders Carlsson <andersca@gnu.org>
* gtk/gtktreeview.c (gtk_tree_view_realize): Don't call
......
2001-12-21 Matthias Clasen <matthiasc@poet.de>
* gtk/text_widget.sgml: More precise wording. (#63388)
* gtk/tmpl/gtksignal.sgml (GTK_SIGNAL_OFFSET): Add docs.
* gtk/resources.sgml: Fix markup of mail URLs.
* gtk/tmpl/gtkpaned.sgml, gtk/tmpl/gtkobject.sgml: Markup fixes.
* gtk/tmpl/gtktoolbar.sgml (gtk_toolbar_{prepend,append}_element):
Expand documentation. (#60471)
* gtk/tmpl/gtkmain.sgml: Remove misleading information about
gtk_set_locale(). (#65758)
2001-12-18 Anders Carlsson <andersca@gnu.org>
* gtk/tmpl/gtkdrawingarea.sgml: Change GdkWidget to
......
......@@ -53,7 +53,7 @@ are authorized to give us the patch under those terms.
<para>
If you want to discuss your patch before or after developing it, mail
<ulink url="mail:gtk-devel-list@gnome.org">gtk-devel-list@gnome.org</ulink>.
<ulink url="mailto:gtk-devel-list@gnome.org">gtk-devel-list@gnome.org</ulink>.
But be sure to file the Bugzilla report as well; if the patch is only on the
list and not in Bugzilla, it's likely to slip through the cracks.
</para>
......@@ -75,7 +75,7 @@ archives of these lists on
<variablelist>
<varlistentry>
<term>gtk-list@gnome.org</term>
<term><ulink url="mailto:gtk-list@gnome.org">gtk-list@gnome.org</ulink></term>
<listitem><para>
gtk-list covers general GTK+ topics; questions about using GTK+ in programs,
GTK+ from a user standpoint, announcements of GTK+-related projects
......@@ -85,7 +85,8 @@ traffic consists of GTK+ programming questions.
</varlistentry>
<varlistentry>
<term>gtk-app-devel-list@gnome.org</term> <listitem><para>
<term><ulink url="mailto:gtk-app-devel-list@gnome.org">gtk-app-devel-list@gnome.org</ulink></term>
<listitem><para>
gtk-app-devel-list covers writing applications in GTK+. It's narrower
in scope than gtk-list, but the two lists overlap quite a
bit. gtk-app-devel-list is a good place to ask questions about GTK+
......@@ -93,7 +94,7 @@ programming. </para></listitem>
</varlistentry>
<varlistentry>
<term>gtk-devel-list@gnome.org</term>
<term><ulink url="mailto:gtk-devel-list@gnome.org">gtk-devel-list@gnome.org</ulink></term>
<listitem><para>
gtk-devel-list is for discussion of work on GTK+ itself, it is NOT for
asking questions about how to use GTK+ in applications. gtk-devel-list
......@@ -103,7 +104,7 @@ and so on.
</varlistentry>
<varlistentry>
<term>gtk-i18n-list@gnome.org</term>
<term><ulink url="mailto:gtk-i18n-list@gnome.org">gtk-i18n-list@gnome.org</ulink></term>
<listitem><para>
gtk-i18n-list is for discussion of internationalization in GTK+;
Pango is the main focus of the list. Questions about the details of
......@@ -113,7 +114,7 @@ all on topic.
</varlistentry>
<varlistentry>
<term>gtk-doc-list@gnome.org</term>
<term><ulink url="mailto:gtk-doc-list@gnome.org">gtk-doc-list@gnome.org</ulink></term>
<listitem><para>
gtk-doc-list is for discussion of the <application>gtk-doc</application>
documentation system (used to document GTK+), and for work on the GTK+
......
......@@ -15,11 +15,6 @@ gtk_init_check() allows you to recover from a failed GTK+
initialization - you might start up your application in text mode instead.
</para>
<para>
If your application supports internationalization, gtk_set_locale()
should be called prior to gtk_init().
</para>
<para>
Like all GUI toolkits, GTK+ uses an event-driven programming
model. When the user is doing nothing, GTK+ sits in the
......
......@@ -386,12 +386,8 @@ For convenience, every object offers a generic user data
pointer. This function sets it.
</para>
<para>
This function is equivalent to:
<informalexample>
<programlisting>
gtk_object_set_data (object, "user_data", data);
</programlisting>
</informalexample>
This function is equivalent to
<literal>gtk_object_set_data (object, "user_data", data)</literal>.
</para>
@object: the object whose user data should be set.
......
......@@ -88,7 +88,7 @@ to <literal>gtk_paned_pack1 (paned, child, FALSE, TRUE)</literal>.
<para>
Adds a child to the bottom or right pane with default
parameters. This is equivalent to
<literal>gtk_paned_pack2(paned, child, TRUE, TRUE)</literal>.
<literal>gtk_paned_pack2 (paned, child, TRUE, TRUE)</literal>.
</para>
@paned: a paned widget
......
......@@ -154,10 +154,16 @@ Inserts a new space in the toolbar at the specified position.
<para>
Adds a new element to the end of a toolbar.
</para>
<para>
If @type == %GTK_TOOLBAR_CHILD_WIDGET, @widget is used as the new element.
If @type == %GTK_TOOLBAR_CHILD_RADIOBUTTON, @widget is used to determine
the radio group for the new element. In all other cases, @widget must
be %NULL.
</para>
@toolbar: a #GtkToolbar.
@type: a value of type #GtkToolbarChildType that determines what @widget will be.
@widget: a #GtkWidget to add to the toolbar. (FIXME: double check this).
@widget: a #GtkWidget, or %NULL.
@text: the element's label.
@tooltip_text: the element's tooltip.
@tooltip_private_text: used for context-sensitive help about this toolbar element.
......@@ -171,10 +177,16 @@ Adds a new element to the end of a toolbar.
<para>
Adds a new element to the beginning of a toolbar.
</para>
<para>
If @type == %GTK_TOOLBAR_CHILD_WIDGET, @widget is used as the new element.
If @type == %GTK_TOOLBAR_CHILD_RADIOBUTTON, @widget is used to determine
the radio group for the new element. In all other cases, @widget must
be %NULL.
</para>
@toolbar: a #GtkToolbar.
@type: a value of type #GtkToolbarChildType that determines what @widget will be.
@widget: a #GtkWidget to add to the toolbar. (FIXME: double check this).
@widget: a #GtkWidget, or %NULL
@text: the element's label.
@tooltip_text: the element's tooltip.
@tooltip_private_text: used for context-sensitive help about this toolbar element.
......@@ -189,17 +201,17 @@ Adds a new element to the beginning of a toolbar.
</para>
@toolbar: a #GtkToolbar.
@type: a value of type #GtkToolbarChildType that determines what @widget will be.
@widget: a #GtkWidget to add to the toolbar. (FIXME: double check this).
@text: the element's label.
@tooltip_text: the element's tooltip.
@tooltip_private_text: used for context-sensitive help about this toolbar element.
@icon: a #GtkWidget that provides pictorial representation of the element's function.
@callback: the function to be executed when the button is pressed.
@user_data: any data you wish to pass to the callback.
@position: the number of widgets to insert this element after.
@Returns: the new toolbar element as a #GtkWidget.
@toolbar:
@type:
@widget:
@text:
@tooltip_text:
@tooltip_private_text:
@icon:
@callback:
@user_data:
@position:
@Returns:
<!-- ##### FUNCTION gtk_toolbar_append_widget ##### -->
......
......@@ -119,7 +119,7 @@ gdk_pixbuf_animation_get_type (void)
* images, then an animation with a single frame will be created. Possible errors
* are in the #GDK_PIXBUF_ERROR and #G_FILE_ERROR domains.
*
* Return value: A newly created animation with a reference count of 1, or NULL
* Return value: A newly-created animation with a reference count of 1, or %NULL
* if any of several error conditions ocurred: the file could not be opened,
* there was no loader for the file's format, there was not enough memory to
* allocate the image buffer, or the image file contained invalid data.
......
......@@ -39,7 +39,7 @@
* @height: Height of the image in pixels.
* @rowstride: Distance in bytes between rows.
* @destroy_fn: Function used to free the data when the pixbuf's reference count
* drops to zero, or NULL if the data should not be freed.
* drops to zero, or %NULL if the data should not be freed.
* @destroy_fn_data: Closure data to pass to the destroy notification function.
*
* Creates a new #GdkPixbuf out of in-memory image data. Currently only RGB
......@@ -51,7 +51,7 @@
GdkPixbuf *
gdk_pixbuf_new_from_data (const guchar *data, GdkColorspace colorspace, gboolean has_alpha,
int bits_per_sample, int width, int height, int rowstride,
GdkPixbufDestroyNotify destroy_fn, gpointer destroy_fn_data)
GdkPixbufDestroyNotify destroy_fn, gpointer destroy_fn_data)
{
GdkPixbuf *pixbuf;
......
......@@ -732,10 +732,10 @@ gdk_pixbuf_real_save (GdkPixbuf *pixbuf,
/**
* gdk_pixbuf_save:
* @pixbuf: pointer to GdkPixbuf.
* @filename: Name of file to save.
* @pixbuf: a #GdkPixbuf.
* @filename: name of file to save.
* @type: name of file format.
* @error: return location for error, or NULL
* @error: return location for error, or %NULL
* @Varargs: list of key-value save options
*
* Saves pixbuf to a file in @type, which is currently "jpeg" or
......@@ -746,7 +746,7 @@ gdk_pixbuf_real_save (GdkPixbuf *pixbuf,
* it should contain pairs of strings that modify the save
* parameters. For example:
* <informalexample><programlisting>
* gdk_pixbuf_save (pixbuf, handle, "jpeg", &error,
* gdk_pixbuf_save (pixbuf, handle, "jpeg", &amp;error,
* "quality", "100", NULL);
* </programlisting></informalexample>
*
......@@ -791,8 +791,8 @@ gdk_pixbuf_save (GdkPixbuf *pixbuf,
/**
* gdk_pixbuf_savev:
* @pixbuf: pointer to GdkPixbuf.
* @filename: Name of file to save.
* @pixbuf: a #GdkPixbuf.
* @filename: name of file to save.
* @type: name of file format.
* @option_keys: name of options to set, %NULL-terminated
* @option_values: values for named options
......
......@@ -471,7 +471,7 @@ gdk_pixbuf_loader_get_pixbuf (GdkPixbufLoader *loader)
* @loader: A pixbuf loader
*
* Queries the #GdkPixbufAnimation that a pixbuf loader is currently creating.
* In general it only makes sense to call this function afer the "area_prepared"
* In general it only makes sense to call this function after the "area_prepared"
* signal has been emitted by the loader. If the loader doesn't have enough
* bytes yet (hasn't emitted the "area_prepared" signal) this function will
* return %NULL.
......
......@@ -221,7 +221,7 @@ gdk_pixbuf_composite_color (const GdkPixbuf *src,
* For more complicated scaling/compositing see gdk_pixbuf_scale()
* and gdk_pixbuf_composite().
*
* Return value: the new #GdkPixbuf, or NULL if not enough memory could be
* Return value: the new #GdkPixbuf, or %NULL if not enough memory could be
* allocated for it.
**/
GdkPixbuf *
......@@ -263,7 +263,7 @@ gdk_pixbuf_scale_simple (const GdkPixbuf *src,
* @dest_height and compositing the result with a checkboard of colors
* @color1 and @color2.
*
* Return value: the new #GdkPixbuf, or NULL if not enough memory could be
* Return value: the new #GdkPixbuf, or %NULL if not enough memory could be
* allocated for it.
**/
GdkPixbuf *
......
......@@ -29,7 +29,7 @@
/**
* gdk_pixbuf_add_alpha:
* @pixbuf: A pixbuf.
* @pixbuf: A #GdkPixbuf.
* @substitute_color: Whether to set a color to zero opacity. If this
* is %FALSE, then the (@r, @g, @b) arguments will be ignored.
* @r: Red value to substitute.
......
......@@ -578,8 +578,8 @@ save_rle_decoder (GString *gstring,
* Generates C source code suitable for compiling images directly
* into programs.
*
* Gtk+ ships with a program called gdk-pixbuf-csource which offers
* a cmdline interface to this functions.
* GTK+ ships with a program called <command>gdk-pixbuf-csource</command>
* which offers a cmdline interface to this functions.
*
* Returns: a newly-allocated string containing the C source form
* of @pixdata.
......@@ -820,28 +820,31 @@ gdk_pixdata_to_csource (GdkPixdata *pixdata,
/**
* gdk_pixbuf_new_from_inline:
* @data_length: Length in bytes of the @data argument
* @data: Byte data containing a serialized GdkPixdata structure
* @data: Byte data containing a serialized #GdkPixdata structure
* @copy_pixels: Whether to copy the pixel data, or use direct pointers
* @data for the resulting pixbuf
* @error: GError return location, may be %NULL to ignore errors
* @error: #GError return location, may be %NULL to ignore errors
*
* Create a #GdkPixbuf from a flat representation that is suitable for
* storing as inline data in a program. This is useful if you want to
* ship a program with images, but don't want to depend on any
* external files.
*
* Gtk+ ships with a program called gdk-pixbuf-csource which allows
* for conversion of #GdkPixbufs into such a inline representation.
* In almost all cases, you should pass the --raw flag to
* gdk-pixbuf-csource. A sample invocation would be:
* GTK+ ships with a program called <command>gdk-pixbuf-csource</command>
* which allows for conversion of #GdkPixbufs into such a inline representation.
* In almost all cases, you should pass the <option>--raw</option> flag to
* <command>gdk-pixbuf-csource</command>. A sample invocation would be:
*
* <informalexample><programlisting>
* gdk-pixbuf-csource --raw --name=myimage_inline myimage.png
* </programlisting></informalexample>
*
* For the typical case where the inline pixbuf is read-only static data,
* you don't need to copy the pixel data unless you intend to write to
* it, so you can pass %FALSE for @copy_pixels. (If you pass --rle to
* gdk-pixbuf-csource, a copy will be made even if @copy_pixels is
* %FALSE, so using this option is generally a bad idea.)
* it, so you can pass %FALSE for @copy_pixels. (If you pass
* <option>--rle</option> to <command>gdk-pixbuf-csource</command>, a copy
* will be made even if @copy_pixels is %FALSE, so using this option is
* generally a bad idea.)
*
* If you create a pixbuf from const inline data compiled into your
* program, it's probably safe to ignore errors, since things will
......
......@@ -512,8 +512,10 @@ gtk_button_new_from_stock (const gchar *stock_id)
* @returns: a new #GtkButton
*
* Creates a new #GtkButton containing a label.
* If characters in @label are preceded by an underscore, they are underlined
* indicating that they represent a keyboard accelerator called a mnemonic.
* If characters in @label are preceded by an underscore, they are underlined.
* If you need a literal underscore character in a label, use '__' (two
* underscores). The first underlined character represents a keyboard
* accelerator called a mnemonic.
* Pressing Alt and that key activates the button.
**/
GtkWidget*
......
......@@ -626,9 +626,10 @@ gtk_label_new (const gchar *str)
* Creates a new #GtkLabel, containing the text in @str.
*
* If characters in @str are preceded by an underscore, they are
* underlined indicating that they represent a keyboard accelerator
* called a mnemonic. The mnemonic key can be used to activate
* another widget, chosen automatically, or explicitly using
* underlined. If you need a literal underscore character in a label, use
* '__' (two underscores). The first underlined character represents a
* keyboard accelerator called a mnemonic. The mnemonic key can be used
* to activate another widget, chosen automatically, or explicitly using
* gtk_label_set_mnemonic_widget().
*
* If gtk_label_set_mnemonic_widget()
......@@ -1190,7 +1191,7 @@ gtk_label_set_pattern (GtkLabel *label,
* @jtype: a #GtkJustification
*
* Sets the alignment of the lines in the text of the label relative to
* each other. %GTK_JUSTIFY_CENTER is the default value when the
* each other. %GTK_JUSTIFY_LEFT is the default value when the
* widget is first created with gtk_label_new().
**/
void
......
......@@ -420,10 +420,10 @@ static gboolean do_setlocale = TRUE;
* gtk_disable_setlocale:
*
* Prevents gtk_init() and gtk_init_check() from automatically
* calling setlocale (LC_ALL, ""). You would want to use this
* function if you wanted to set the locale for your program
* to something other than the user's locale, or if you wanted
* to set different values for different locale categories.
* calling <literal>setlocale (LC_ALL, "")</literal>. You would
* want to use this function if you wanted to set the locale for
* your program to something other than the user's locale, or if
* you wanted to set different values for different locale categories.
*
* Most programs should not need to call this function.
**/
......@@ -734,12 +734,12 @@ gtk_exit (gint errorcode)
* is not really supported.)
*
* In detail - sets the current locale according to the
* program environment. This is the same as calling the libc function
* setlocale (LC_ALL, "") but also takes care of the locale specific
* setup of the windowing system used by GDK.
* program environment. This is the same as calling the C library function
* <literal>setlocale (LC_ALL, "")</literal> but also takes care of the
* locale specific setup of the windowing system used by GDK.
*
* Return value: a string corresponding to the locale set, as with the
* C library function setlocale()
* C library function <function>setlocale()</function>.
**/
gchar*
gtk_set_locale (void)
......
......@@ -3056,7 +3056,7 @@ gtk_text_iter_forward_word_ends (GtkTextIter *iter,
* @iter: a #GtkTextIter
* @count: number of times to move
*
* Calls gtk_text_iter_backward_word_starts() up to @count times.
* Calls gtk_text_iter_backward_word_start() up to @count times.
*
* Return value: %TRUE if @iter moved and is not the end iterator
**/
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment