AuroraMiddleware/gtk2
1
0
Fork 0
forked from AuroraMiddleware/gtk
Code Issues Pull Requests Projects Releases Wiki Activity

fixed minor error - using <em>.

Browse Source 
1999-11-16  Damon Chaplin  <damon@karuna.freeserve.co.uk>

	* gtk/tmpl/gtkmenubar.sgml: fixed minor error - using <em>.

	* gtk/tmpl/gtknotebook.sgml:
	* gtk/tmpl/gtklist.sgml: new sections from
	Nicolas George <george@clipper.ens.fr>, with help from
	"Bob Springett"	<bobspringett@claranet.fr>.

	* gtk/tmpl/gtkobject.sgml:
	* gtk/tmpl/gtkarg.sgml: new sections from
	David Benson <daveb@idealab.com>.

	* gtk/tmpl/gtkvbox.sgml:
	* gtk/tmpl/gtkhbox.sgml: fixed line endings.

	* gtk/tmpl/gtkvbbox.sgml: update from Lee Mallabone
	<lee0@callnetuk.com>

	* gdk/tmpl/drawing.sgml: fixed error in gdk_draw_arc() @angle2 param
	- it is relative to @angle1 rather than from the 3 o'clock position.

	* gtk/tmpl/gtkfontseldlg.sgml: changed enums to use @ fields.

	* gtk/tmpl/gtkcolorsel.sgml:
	* gtk/tmpl/gtkcolorseldlg.sgml:
	* gtk/tmpl/gtkprogress.sgml:
	* gtk/tmpl/gtkprogressbar.sgml: new sections from Tom Martone
	<tom@martoneconsulting.com>

	* gtk/tmpl/gtkclist.sgml: partially written documentation from
	Paul Schifferer <isengard@geocities.com> who won't be able to finish it
This commit is contained in:
Damon Chaplin 1999-11-16 00:33:10 +00:00 committed by Damon Chaplin
parent f3fcdb4e0e
commit 3a202479a8
15 changed files with 2017 additions and 1201 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

33
docs/reference/ChangeLog
View File

@ -1,3 +1,36 @@
1999-11-16 Damon Chaplin <damon@karuna.freeserve.co.uk>
* gtk/tmpl/gtkmenubar.sgml: fixed minor error - using <em>.
* gtk/tmpl/gtknotebook.sgml:
* gtk/tmpl/gtklist.sgml: new sections from
Nicolas George <george@clipper.ens.fr>, with help from
"Bob Springett" <bobspringett@claranet.fr>.
* gtk/tmpl/gtkobject.sgml:
* gtk/tmpl/gtkarg.sgml: new sections from
David Benson <daveb@idealab.com>.
* gtk/tmpl/gtkvbox.sgml:
* gtk/tmpl/gtkhbox.sgml: fixed line endings.
* gtk/tmpl/gtkvbbox.sgml: update from Lee Mallabone
<lee0@callnetuk.com>
* gdk/tmpl/drawing.sgml: fixed error in gdk_draw_arc() @angle2 param
- it is relative to @angle1 rather than from the 3 o'clock position.
* gtk/tmpl/gtkfontseldlg.sgml: changed enums to use @ fields.
* gtk/tmpl/gtkcolorsel.sgml:
* gtk/tmpl/gtkcolorseldlg.sgml:
* gtk/tmpl/gtkprogress.sgml:
* gtk/tmpl/gtkprogressbar.sgml: new sections from Tom Martone
<tom@martoneconsulting.com>
* gtk/tmpl/gtkclist.sgml: partially written documentation from
Paul Schifferer <isengard@geocities.com> who won't be able to finish it
1999-09-22 Martin Norbäck <d95mback@dtek.chalmers.se>
* gtk/tmpl/gtkclist.sgml: Added information about the sorting functions

2
docs/reference/gdk/tmpl/drawing.sgml
View File

@ -160,7 +160,7 @@ the ellipse to be drawn.
@height: the height of the bounding rectangle.
@angle1: the start angle of the arc, relative to the 3 o'clock position,
counter-clockwise, in 1/64ths of a degree.
@angle2: the end angle of the arc, in the same units as @angle1.
@angle2: the end angle of the arc, relative to @angle1, in 1/64ths of a degree.
<!-- ##### FUNCTION gdk_draw_polygon ##### -->

349
docs/reference/gtk/tmpl/gtkarg.sgml
View File

@ -1,147 +1,202 @@
<!-- ##### SECTION Title ##### -->
Object Properties
<!-- ##### SECTION Short_Description ##### -->
<!-- ##### SECTION Long_Description ##### -->
<para>
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
<!-- ##### STRUCT GtkArgInfo ##### -->
<para>
</para>
@class_type:
@name:
@type:
@arg_flags:
@full_name:
@arg_id:
@seq_id:
<!-- ##### FUNCTION gtk_arg_new ##### -->
<para>
</para>
@arg_type:
@Returns:
<!-- ##### FUNCTION gtk_arg_copy ##### -->
<para>
</para>
@src_arg:
@dest_arg:
@Returns:
<!-- ##### FUNCTION gtk_arg_free ##### -->
<para>
</para>
@arg:
@free_contents:
<!-- ##### FUNCTION gtk_args_collect ##### -->
<para>
</para>
@object_type:
@arg_info_hash_table:
@arg_list_p:
@info_list_p:
@first_arg_name:
@var_args:
@Returns:
<!-- ##### FUNCTION gtk_args_collect_cleanup ##### -->
<para>
</para>
@arg_list:
@info_list:
<!-- ##### FUNCTION gtk_arg_get_info ##### -->
<para>
</para>
@object_type:
@arg_info_hash_table:
@arg_name:
@info_p:
@Returns:
<!-- ##### FUNCTION gtk_arg_type_new_static ##### -->
<para>
</para>
@base_class_type:
@arg_name:
@class_n_args_offset:
@arg_info_hash_table:
@arg_type:
@arg_flags:
@arg_id:
@Returns:
<!-- ##### FUNCTION gtk_args_query ##### -->
<para>
</para>
@class_type:
@arg_info_hash_table:
@arg_flags:
@n_args_p:
@Returns:
<!-- ##### FUNCTION gtk_arg_name_strip_type ##### -->
<para>
</para>
@arg_name:
@Returns:
<!-- ##### FUNCTION gtk_arg_info_equal ##### -->
<para>
</para>
@arg_info_1:
@arg_info_2:
@Returns:
<!-- ##### FUNCTION gtk_arg_info_hash ##### -->
<para>
</para>
@arg_info:
@Returns:
<!-- ##### SECTION Title ##### -->
Implementation of Object Properties
<!-- ##### SECTION Short_Description ##### -->
Utility function to manipulate lists of named, typed arguments.
<!-- ##### SECTION Long_Description ##### -->
<para>
All the functions in here are marked a Non-public.
We describe it anyway because it is occasionally useful
to understand how the work is done.
</para>
<para>
Arguments are a way of describing a named parameter to a function.
They have two important roles within gtk+:
<itemizedlist>
<listitem>
<para>
they describe <wordasword>object properties</wordasword>.
This means that they present an interface to get and set a named-type
for any type of object in a consistent way.
(All the relevant functions to do this start with gtk_object_set
or gtk_object_get).
</para>
</listitem>
<listitem>
<para>
they describe <wordasword>signal arguments</wordasword>.
This is a lot less often needed but still useful.
Usually if you are just emitting or creating a particular signal
it is more convenient to just use gtk_signal_emit() or gtk_signal_new().
However if you are writing a function to emit or create an arbitrary
signal, you must use gtk_signal_emitv() or gtk_signal_newv().
</para>
</listitem>
</itemizedlist>
<!-- ##### SECTION See_Also ##### -->
<para>
#GtkObject.
</para>
<!-- ##### STRUCT GtkArgInfo ##### -->
<para>
A structure containing information about the argument.
Returned by gtk_arg_get_info().
</para>
@class_type: if the argument is an object, this is the object class type.
@name: the name of the argument.
@type: the type of the argument; it may be an object's type
or a fundamental type.
@arg_flags: flags applicable to the argument (i.e. readable, writable,
and whether it needs to be constructed).
@full_name: the object name and argument name separated by ::,
e.g. "GtkObject::user_data" or "GtkButton::label".
@arg_id: the unique argument identified.
@seq_id: ???
<!-- ##### FUNCTION gtk_arg_new ##### -->
<para>
Creates a new argument of a certain type, set to 0 or NULL.
</para>
@arg_type: the type of the argument.
@Returns: the newly created #GtkArg.
<!-- ##### FUNCTION gtk_arg_copy ##### -->
<para>
It will either copy data into an existing argument or allocate a new argument
and copy the data. Strings are duplicated. All other pointers and
values are copied (shallowly-- that is the pointers themselves are
copied, not the data they point to.)
</para>
<para>
You should call gtk_arg_reset() on dest_arg before calling this
if the argument may contain string data that you want freed.
</para>
@src_arg: the argument to duplicate.
@dest_arg: the argument to copy over (or NULL to create a new #GtkArg).
@Returns: the new #GtkArg (or dest_arg, if it was not NULL).
<!-- ##### FUNCTION gtk_arg_free ##### -->
<para>
Frees the argument, and optionally its contents.
</para>
@arg: the argument to free.
@free_contents: whether to free the string, if it is a string.
<!-- ##### FUNCTION gtk_args_collect ##### -->
<para>
Private: given a hashtable of argument information it takes a vararg
list and parses it into arguments (in the form of lists of #GtkArgs
and lists of #GtkArgInfos.
</para>
<para>
The list of arguments starts with first_arg_name then the first argument's
value. Followed by any number of additional name/argument pairs,
terminated with NULL.
</para>
@object_type: the type of object we are collecting arguments for.
@arg_info_hash_table: a hashtable mapping from names of arguments
to their #GtkArgInfos.
@arg_list_p: a returned list of arguments obtained from parsing the
varargs.
@info_list_p: a returned list of the #GtkArgInfos.
@first_arg_name: the name of the first argument.
@var_args: a va_list containing the value of the first argument,
followed by name/value pairs, followed by NULL.
@Returns: an error message on failure, or NULL otherwise.
<!-- ##### FUNCTION gtk_args_collect_cleanup ##### -->
<para>
Private: erase lists of arguments returned from gtk_args_collect().
</para>
@arg_list: arg_list_p returned from gtk_args_collect().
@info_list: info_list_p returned from gtk_args_collect().
<!-- ##### FUNCTION gtk_arg_get_info ##### -->
<para>
Private: get information about an argument.
</para>
@object_type: the type of object.
@arg_info_hash_table: the hashtable of #GtkArgInfos.
@arg_name: the name of the argument to lookup.
@info_p: the argument info.
@Returns: an error message on failure, or NULL otherwise.
<!-- ##### FUNCTION gtk_arg_type_new_static ##### -->
<para>
Create a new argument registered with a class.
</para>
@base_class_type: the basic type having the arguments, almost alway
GTK_TYPE_OBJECT, except if your defining a different type argument
that gets a different namespace. #GtkContainer does this to define
per-child arguments of the container.
@arg_name: name of the argument to create. (must be a static constant string)
@class_n_args_offset: offset into the base class structure that tells
the number of arguments.
@arg_info_hash_table: hashtable of #GtkArgInfos.
@arg_type: type of the argument.
@arg_flags: flags of the argument.
@arg_id: ???
@Returns: the new #GtkArgInfo.
<!-- ##### FUNCTION gtk_args_query ##### -->
<para>
Private: from a class type and its arginfo hashtable,
get an array of #GtkArgs that this object accepts.
</para>
@class_type: the class type.
@arg_info_hash_table: the hashtable of #GtkArgInfos.
@arg_flags: returned array of argument flags.
@n_args_p: the number of arguments this object accepts.
@Returns: the array of arguments (or NULL on error).
<!-- ##### FUNCTION gtk_arg_name_strip_type ##### -->
<para>
Given a fully qualified argument name (e.g. "GtkButton::label")
it returns just the argument name (e.g. "label") unless
the argument name was invalid, in which case it returns NULL.
</para>
@arg_name: the fully-qualified argument name.
@Returns: the base argument name.
<!-- ##### FUNCTION gtk_arg_info_equal ##### -->
<para>
A #GCompareFunc for hashing #GtkArgInfos.
</para>
@arg_info_1: a #GtkArgInfo.
@arg_info_2: a #GtkArgInfo.
@Returns: whether the arguments are the same.
<!-- ##### FUNCTION gtk_arg_info_hash ##### -->
<para>
A #GHashFunc for hashing #GtkArgInfos.
</para>
@arg_info: a #GtkArgInfo.
@Returns: a hash value for that #GtkArgInfo.

69
docs/reference/gtk/tmpl/gtkcolorsel.sgml
View File

@ -2,11 +2,15 @@
GtkColorSelection
<!-- ##### SECTION Short_Description ##### -->
a widget used to select a color.
<!-- ##### SECTION Long_Description ##### -->
<para>
The #GtkColorSelection is a widget that is used to select
a color. It consists of a color wheel and number of sliders
and entry boxes for color parameters such as hue, saturation,
value, red, green, blue, and opacity. It is found on the standard
color selection dialog box #GtkColorSelectionDialog.
</para>
<!-- ##### SECTION See_Also ##### -->
@ -16,57 +20,86 @@ GtkColorSelection
<!-- ##### STRUCT GtkColorSelection ##### -->
<para>
The #GtkColorSelection-struct struct contains private data only,
and should be accessed using the functions below.
</para>
<!-- ##### FUNCTION gtk_color_selection_new ##### -->
<para>
Create a new #GtkColorSelection.
</para>
@Returns:
@Returns: a #GtkColorSelection.
<!-- ##### FUNCTION gtk_color_selection_set_update_policy ##### -->
<para>
Sets the policy controlling when the color_changed signals are emitted.
The available policies are:
<itemizedlist>
<listitem>
<para>
%GTK_UPDATE_CONTINUOUS - signals are sent continuously as the color
selection changes.
</para>
<listitem>
<para>
%GTK_UPDATE_DISCONTINUOUS - signals are sent only when the mouse
button is released.
</para>
<listitem>
<para>
%GTK_UPDATE_DELAYED - signals are sent when the mouse button is
released or when the mouse has been motionless for a period of
time.
</para>
</itemizedlist>
</para>
@colorsel:
@policy:
@colorsel: a #GtkColorSelection.
@policy: a #GtkUpdateType value indicating the desired policy.
<!-- ##### FUNCTION gtk_color_selection_set_opacity ##### -->
<para>
Controls whether opacity can be set with the #GtkColorSelection.
If this functionality is enabled, the necessary additional widgets
are added to the #GtkColorSelection and the opacity value can be
retrieved via the fourth value in the color array returned by
the gtk_color_selection_get_color() function.
</para>
@colorsel:
@use_opacity:
@colorsel: a #GtkColorSelection.
@use_opacity: a boolean indicating whether the opacity selection
is enabled.
<!-- ##### FUNCTION gtk_color_selection_set_color ##### -->
<para>
Sets the color in the #GtkColorSelection. The widgets are updated
to reflect the new color.
</para>
@colorsel:
@color:
@colorsel: a #GtkColorSelection.
@color: a color array consisting of 4 gfloat values for red, green,
blue, and opacity.
<!-- ##### FUNCTION gtk_color_selection_get_color ##### -->
<para>
Retrieve the currently selected color value.
</para>
@colorsel:
@color:
@colorsel: a #GtkColorSelection
@color: a color array consisting of 4 gfloat values for red, green,
blue, and opacity.
<!-- ##### SIGNAL GtkColorSelection::color-changed ##### -->
<para>
This signal is emitted when the color changes in the #GtkColorSelection
according to its update policy.
</para>
@colorselection: the object which received the signal.

53
docs/reference/gtk/tmpl/gtkcolorseldlg.sgml
View File

@ -2,11 +2,13 @@
GtkColorSelectionDialog
<!-- ##### SECTION Short_Description ##### -->
a standard dialog box for selecting a color.
<!-- ##### SECTION Long_Description ##### -->
<para>
The #GtkColorSelectionDialog provides a standard dialog which
allows the user to select a color much like the #GtkFileSelection
provides a standard dialog for file selection.
</para>
<!-- ##### SECTION See_Also ##### -->
@ -16,16 +18,53 @@ GtkColorSelectionDialog
<!-- ##### STRUCT GtkColorSelectionDialog ##### -->
<para>
The #GtkColorSelectionDialog-struct struct contains the following fields.
(These fields should be considered read-only. They should never be set by
an application.)
<informaltable pgwide=1 frame="none" role="struct">
<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
<tbody>
<row>
<entry>#GtkWidget *colorsel;</entry>
<entry>The #GtkColorSelection widget contained within the
dialog. Use this widget and its gtk_color_selection_get_color()
function to gain access to the selected color. Connect a handler
for this widget's color_changed signal to be notified when the
color changes.
</entry>
</row>
<row>
<entry>#GtkWidget *ok_button;</entry>
<entry>The OK button widget contained within the dialog.
Connect a handler for the clicked event.
</entry>
</row>
<row>
<entry>#GtkWidget *cancel_button;</entry>
<entry>The cancel button widget contained within the dialog.
Connect a handler for the clicked event.
</entry>
</row>
<row>
<entry>#GtkWidget *help_button;</entry>
<entry>The help button widget contained within the dialog.
Connect a handler for the clicked event.
</entry>
</row>
</tbody></tgroup></informaltable>
</para>
<!-- ##### FUNCTION gtk_color_selection_dialog_new ##### -->
<para>
Creates a new #GtkColorSelectionDialog.
</para>
@title:
@Returns:
@title: a string containing the title text for the dialog.
@Returns: a #GtkColorSelectionDialog.

56
docs/reference/gtk/tmpl/gtkfontseldlg.sgml
View File

@ -158,63 +158,21 @@ will be shown, or NULL to show all charsets.
A set of bit flags used to specify the type of fonts shown
when calling gtk_font_selection_dialog_set_filter() or
gtk_font_selection_set_filter().
<informaltable pgwide=1 frame="none" role="enum">
<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
<tbody>
<row>
<entry>GTK_FONT_BITMAP</entry>
<entry>bitmap fonts.</entry>
</row>
<row>
<entry>GTK_FONT_SCALABLE</entry>
<entry>scalable fonts.</entry>
</row>
<row>
<entry>GTK_FONT_SCALED_BITMAP</entry>
<entry>scaled bitmap fonts.</entry>
</row>
<row>
<entry>GTK_FONT_ALL</entry>
<entry>a bitwise combination of all of the above.</entry>
</row>
</tbody></tgroup></informaltable>
</para>
@GTK_FONT_BITMAP:
@GTK_FONT_SCALABLE:
@GTK_FONT_SCALABLE_BITMAP:
@GTK_FONT_ALL:
@GTK_FONT_BITMAP: bitmap fonts.
@GTK_FONT_SCALABLE: scalable fonts.
@GTK_FONT_SCALABLE_BITMAP: scaled bitmap fonts.
@GTK_FONT_ALL: a bitwise combination of all of the above.
<!-- ##### ENUM GtkFontFilterType ##### -->
<para>
A set of bit flags used to specify the filter being set
when calling gtk_font_selection_dialog_set_filter() or
gtk_font_selection_set_filter().
<informaltable pgwide=1 frame="none" role="enum">
<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
<tbody>
<row>
<entry>GTK_FONT_FILTER_BASE</entry>
<entry>the base filter, which can't be changed by the user.</entry>
</row>
<row>
<entry>GTK_FONT_FILTER_USER</entry>
<entry>the user filter, which can be changed from within the 'Filter' page
of the #GtkFontSelection widget.</entry>
</row>
</tbody></tgroup></informaltable>
</para>
@GTK_FONT_FILTER_BASE:
@GTK_FONT_FILTER_USER:
@GTK_FONT_FILTER_BASE: the base filter, which can't be changed by the user.
@GTK_FONT_FILTER_USER: the user filter, which can be changed from within the
'Filter' page of the #GtkFontSelection widget.

44
docs/reference/gtk/tmpl/gtkhbox.sgml
View File

@ -5,29 +5,29 @@ GtkHBox
horizontal container box
<!-- ##### SECTION Long_Description ##### -->
<para>
GtkHBox is a container that organizes child widgets into a single row.
</para>
<para>
Use the #GtkBox packing interface to determine the arrangement,
spacing, width, and alignment of GtkHBox children.
</para>
<para>
All children are allocated the same height.
<para>
GtkHBox is a container that organizes child widgets into a single row.
</para>
<para>
Use the #GtkBox packing interface to determine the arrangement,
spacing, width, and alignment of GtkHBox children.
</para>
<para>
All children are allocated the same height.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
<variablelist>
<varlistentry>
<term>#GtkVBox</term>
<listitem><para>a sister class that organizes widgets into a column.</para></listitem>
</varlistentry>
</variablelist>
<para>
<variablelist>
<varlistentry>
<term>#GtkVBox</term>
<listitem><para>a sister class that organizes widgets into a column.</para></listitem>
</varlistentry>
</variablelist>
</para>
<!-- ##### STRUCT GtkHBox ##### -->
@ -35,8 +35,8 @@ All children are allocated the same height.
<!-- ##### FUNCTION gtk_hbox_new ##### -->
<para>
Creates a new GtkHBox.
<para>
Creates a new GtkHBox.
</para>
@homogeneous: %TRUE if all children are to be given equal space allotments.

260
docs/reference/gtk/tmpl/gtklist.sgml
View File

@ -2,16 +2,31 @@
GtkList
<!-- ##### SECTION Short_Description ##### -->
Widget for packing a list of selectable items.
<!-- ##### SECTION Long_Description ##### -->
<para>
The GtkList widget is a container whose children are displayed
vertically in order, and can be selected.
The list has many selection modes, which are programmer selective and
depend on how many elements are able to be selected at the same time.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
<variablelist>
<varlistentry>
<term>#GtkContainer</term>
<listitem><para>For functions that apply to every #GtkContainer
(like #GtkList).</para></listitem>
</varlistentry>
<varlistentry>
<term>#GtkListitem</term>
<listitem><para>Children of a #GtkList widget must be of this
type.</para></listitem>
</varlistentry>
</variablelist>
</para>
<!-- ##### STRUCT GtkList ##### -->
@ -19,148 +34,212 @@ GtkList
</para>
@container: the parent class object
@children: a GList with the children of the list; belonging to #GtkListitem
@selection: a GList with selected items of the list
@undo_selection:
@undo_unselection:
@last_focus_child:
@undo_focus_child:
@htimer:
@vtimer:
@anchor:
@drag_pos:
@anchor_state:
@selection_mode: the selection mode of the list
@drag_selection:
@add_mode:
<!-- ##### FUNCTION gtk_list_new ##### -->
<para>
Creates a new #GtkList.
</para>
@Returns:
@Returns: the newly created #GtkList
<!-- ##### FUNCTION gtk_list_insert_items ##### -->
<para>
Inserts @items into the @list at the position @position. The @GList items
must not be freed after.
</para>
@list:
@items:
@position:
@list: the list widget.
@items: the items.
@position: the position to insert @items, starting at 0.
<!-- ##### FUNCTION gtk_list_append_items ##### -->
<para>
Adds @items to the end of the @list.
</para>
@list:
@items:
@list: the list widget.
@items: the items.
<!-- ##### FUNCTION gtk_list_prepend_items ##### -->
<para>
Inserts @items at the beginning of the @list.
</para>
@list:
@items:
@list: the list widget.
@items: the items.
<!-- ##### FUNCTION gtk_list_remove_items ##### -->
<para>
Removes the @items from the @list.
</para>
@list:
@items:
@list: the list widget.
@items: the items to remove.
<!-- ##### FUNCTION gtk_list_remove_items_no_unref ##### -->
<para>
Removes the @items from the @list, without unreferencing them. It
may be useful if you want to move the items from one list to another.
</para>
@list:
@items:
@list: the list widget.
@items: the items.
<!-- ##### FUNCTION gtk_list_clear_items ##### -->
<para>
Removes the items between index @start (included) and @end (excluded)
from the @list. If @end is negative, or greater than the number of
children of @list, it's assumed to be exactly the number of
elements. If @start is greater than or equal to @end, nothing is
done.
</para>
@list:
@start:
@end:
@list: the list widget.
@start: the index of the first item to remove.
@end: the index of the lest item to remove plus one.
<!-- ##### FUNCTION gtk_list_select_item ##### -->
<para>
Selects the child number @item of the @list. Nothing happens if @item
is out of bounds. The signal GtkList::select-child will be emitted.
</para>
@list:
@item:
@list: the list widget.
@item: the index of the child to select.
<!-- ##### FUNCTION gtk_list_unselect_item ##### -->
<para>
Unselects the child number @item of the @list. Nothing happens if
@item is out of bounds. The signal GtkList::unselect-child will be
emitted.
</para>
@list:
@item:
@list: the list widget.
@item: the index of the child to unselect.
<!-- ##### FUNCTION gtk_list_select_child ##### -->
<para>
Selects the given @child. The signal GtkList::select-child will be
emitted.
</para>
@list:
@child:
@list: the list widget
@child: the child to select.
<!-- ##### FUNCTION gtk_list_unselect_child ##### -->
<para>
Unselects the given @child. The signal GtkList::unselect-child will be
emitted.
</para>
@list:
@child:
@list: the list widget.
@child: the child to unselect.
<!-- ##### FUNCTION gtk_list_child_position ##### -->
<para>
Searches the children of @list for the index of @child.
</para>
@list:
@child:
@Returns:
@list: the list widget.
@child: the child to look for.
@Returns: the index of the child, -1 if not found.
<!-- ##### FUNCTION gtk_list_set_selection_mode ##### -->
<para>
Set the list selection mode. The selection mode can be any value in
#GtkSelectionMode:
<variablelist>
<varlistentry>
<term>#GTK_SELECTION_SINGLE</term>
<listitem><para>
Zero or one element may be selected.
</para></listitem>
</varlistentry>
<varlistentry>
<term>#GTK_SELECTION_BROWSE</term>
<listitem><para>
Exactly one element is always selected (this can be false after you have
changed the selection mode).
</para></listitem>
</varlistentry>
<varlistentry>
<term>#GTK_SELECTION_MULTIPLE</term>
<listitem><para>
Any number of elements may be selected. Clicks toggle the state of an
item.
</para></listitem>
</varlistentry>
<varlistentry>
<term>#GTK_SELECTION_EXTENDED</term>
<listitem><para>
Any number of elements may be selected. Click-drag selects a range of
elements; the Ctrl key may be used to enlarge the selection, and
Shift key to select between the focus and the child pointed to.
</para></listitem>
</varlistentry>
</variablelist>
</para>
@list:
@mode:
@list: the list widget.
@mode: the new selection mode.
<!-- ##### FUNCTION gtk_list_extend_selection ##### -->
<para>
Extends the selection by moving the anchor according to @scroll_type. Only
in #GTK_SELECTION_EXTENDED.
</para>
@list:
@scroll_type:
@position:
@auto_start_selection:
@list: the list widget.
@scroll_type: the direction and length.
@position: the position if @scroll_type is #GTK_SCROLL_JUMP.
@auto_start_selection: if #TRUE, gtk_list_start_selection is automatically
carried out before extending the selection.
<!-- ##### FUNCTION gtk_list_start_selection ##### -->
<para>
Starts a selection (or part of selection) at the focused child. Only in
#GTK_SELECTION_EXTENDED mode.
</para>
@list:
@list: the list widget.
<!-- ##### FUNCTION gtk_list_end_selection ##### -->
<para>
Ends the selection. Used with #gtk_list_extend_selection and
#gtk_list_start_selection. Only in #GTK_SELECTION_EXTENDED.
</para>
@list:
@ -168,101 +247,126 @@ GtkList
<!-- ##### FUNCTION gtk_list_select_all ##### -->
<para>
Selects all children of @list. A signal will be emitted for each
newly selected child.
</para>
@list:
@list: the list widget.
<!-- ##### FUNCTION gtk_list_unselect_all ##### -->
<para>
Unselects all children of @list. A signal will be emitted for each
newly unselected child.
</para>
@list:
@list: the list widget.
<!-- ##### FUNCTION gtk_list_scroll_horizontal ##### -->
<para>
Scrolls @list horizontaly. This supposes that the list is packed into a
scrolled window or something similar, and adjustments are well
set. Step and page increment are those from the horizontal adjustment
of @list. Backward means to the left, and forward to the
right. Out of bounds values are truncated.
@scroll_type may be any valid #GtkScrollType. If @scroll_type is
#GTK_SCROLL_NONE, nothing is done. If it's #GTK_SCROLL_JUMP, the list
scrolls to the ratio @position: 0 is full left, 1 is full right.
</para>
@list:
@scroll_type:
@position:
@list: the list widget.
@scroll_type: the scrolling type.
@position: the position if @scroll_type is #GTK_SCROLL_JUMP
<!-- ##### FUNCTION gtk_list_scroll_vertical ##### -->
<para>
Scrolls @list vertically. This supposes that the list is packed into a
scrolled window or something similar, and adjustments are well
set. Step and page increment are those from the vertical adjustment
of @list. Backward means up, and forward down. Out of bounds values are
truncated.
@scroll_type may be any valid #GtkScrollType. If @scroll_type is
#GTK_SCROLL_NONE, nothing is done. If it's #GTK_SCROLL_JUMP, the list
scrolls to the ratio @position: 0 is top, 1 is bottom.
</para>
@list:
@scroll_type:
@position:
@list: the list widget.
@scroll_type: the scrolling type.
@position: the position if @scroll_type is #GTK_SCROLL_JUMP
<!-- ##### FUNCTION gtk_list_toggle_add_mode ##### -->
<para>
Toggles between adding to the selection and beginning a new selection. Only
in #GTK_SELECTION_EXTENDED. Useful with #gtk_list_extend_selection.
</para>
@list:
@list: the list widget.
<!-- ##### FUNCTION gtk_list_toggle_focus_row ##### -->
<para>
Toggles the focus row. If the focus row is selected, it's
unselected. If the focus row is unselected, it's selected. If the
selection mode of @list is #GTK_SELECTION_BROWSE, this has no effect,
as the selection is always at the focus row.
</para>
@list:
@list: the list widget.
<!-- ##### FUNCTION gtk_list_toggle_row ##### -->
<para>
Toggles the child @item of list. If the selection mode of @list is
#GTK_SELECTION_BROWSE, the item is selected, and the others are
unselected.
</para>
@list:
@item:
@list: the list widget.
@item: the child to toggle.
<!-- ##### FUNCTION gtk_list_undo_selection ##### -->
<para>
Restores the selection in the last state, only if selection mode is
#GTK_SELECTION_EXTENDED. If this function is called twice, the selection is
cleared. This function sometimes gives stranges "last states".
</para>
@list:
@list: the list widget.
<!-- ##### FUNCTION gtk_list_end_drag_selection ##### -->
<para>
Stops the drag selection mode and ungrabs the pointer. This has no
effect if a drag selection is not active.
</para>
@list:
@list: the list widget.
<!-- ##### SIGNAL GtkList::selection-changed ##### -->
<para>
The selection of the widget has just changed.
</para>
@list: the object which received the signal.
<!-- ##### SIGNAL GtkList::select-child ##### -->
<para>
The child @widget has just been selected.
</para>
@list: the object which received the signal.
@widget:
@widget: the newly selected child.
<!-- ##### SIGNAL GtkList::unselect-child ##### -->
<para>
The child @widget has just been unselected.
</para>
@list: the object which received the signal.
@widget:
@widget: the newly unselected child.

6
docs/reference/gtk/tmpl/gtkmenubar.sgml
View File

@ -42,7 +42,7 @@ Adds a new #GtkMenuItem to the end of the GtkMenuBar
Adds a new #GtkMenuItem to the beginning of the GtkMenuBar
</para>
@menu_bar: a #GtkMenuBa
@menu_bar: a #GtkMenuBar
@child: the #GtkMenuItem to add
@ -53,7 +53,7 @@ Adds a new #GtkMenuItem to the GtkMenuBar at the position defined by @position
@menu_bar: a #GtkMenuBar
@child: the #GtkMenuItem to add
@position: the position in the item list where the <em>child</em> is added.
@position: the position in the item list where the @child is added.
<!-- ##### FUNCTION gtk_menu_bar_set_shadow_type ##### -->
@ -62,7 +62,7 @@ Sets the shadow type to use on the GtkMenuBar. The shadow types to use are:
GTK_SHADOW_NONE, GTK_SHADOW_IN, GTK_SHADOW_OUT, GTK_SHADOW_ETCHED_IN, and GTK_SHADOW_ETCHED_OUT
</para>
@menu_bar: a #GtkMenuBa
@menu_bar: a #GtkMenuBar
@type: the GtkShadowtype

495
docs/reference/gtk/tmpl/gtknotebook.sgml
View File

@ -2,16 +2,24 @@
GtkNotebook
<!-- ##### SECTION Short_Description ##### -->
Set of pages with bookmarks.
<!-- ##### SECTION Long_Description ##### -->
<para>
The #GtkNotebook widget is a #GtkContainer whose children are pages that
can be accessed through bookmarks. The pages are displayed all at the same
place. <!-- TODO: talk about the menu -->
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
<variablelist>
<varlistentry>
<term>#GtkContainer</term>
<listitem><para>For functions that apply to every #GtkContainer
(like #GtkList).</para></listitem>
</varlistentry>
</variablelist>
</para>
<!-- ##### STRUCT GtkNotebook ##### -->
@ -19,10 +27,33 @@ GtkNotebook
</para>
@container: the parent class object
@cur_page: the currently displayed page
@children: a GList with the children of the notebook; belonging to
#GtkNotebookPage
@first_tab:
@focus_tab:
@menu:
@panel:
@timer:
@tab_hborder:
@tab_vborder:
@show_tabs:
@homogeneous:
@show_border:
@tab_pos:
@scrollable:
@in_child:
@click_child:
@button:
@need_timer:
@child_has_focus:
@have_visible_child:
<!-- ##### MACRO GTK_NOTEBOOK_PAGE ##### -->
<para>
Extracts the contents of the current element of #GList @_glist_ as a
#GtkNotebookPage.
</para>
@_glist_:
@ -30,12 +61,13 @@ GtkNotebook
<!-- ##### STRUCT GtkNotebookPage ##### -->
<para>
The #GtkNotebookPage structure is used to store the pages of a notebook. It
is not an object.
</para>
@child:
@tab_label:
@menu_label:
@child: the contents of the page
@tab_label: the label shown in the bookmark
@menu_label: the label shown in the popup menu
@default_menu:
@default_tab:
@expand:
@ -46,380 +78,405 @@ GtkNotebook
<!-- ##### FUNCTION gtk_notebook_new ##### -->
<para>
Creates a new #GtkNotebook widget
</para>
@Returns:
@Returns: the newly created G=#GtkNotebook
<!-- ##### FUNCTION gtk_notebook_append_page ##### -->
<para>
Appends to @notebook a page whose content is @child, and whose bookmark is
@tab_label.
</para>
@notebook:
@child:
@tab_label:
@notebook: the notebook widget
@child: the content of the new page
@tab_label: the bookmark for the page
<!-- ##### FUNCTION gtk_notebook_append_page_menu ##### -->
<para>
Appends to @notebook a page whose content is @child, whose bookmark is
@tab_label, and whose menu label is @menu_label.
</para>
@notebook:
@child:
@tab_label:
@menu_label:
@notebook: the notebook widget
@child: the content of the new page
@tab_label: the bookmark of the page
@menu_label: the menu label of the page
<!-- ##### FUNCTION gtk_notebook_prepend_page ##### -->
<para>
Prepends to @notebook a page whose content is @child, whose bookmark is
@tab_label, and whose menu label is @menu_label.
</para>
@notebook:
@child:
@tab_label:
@notebook: the notebook widget
@child: the content of the new page
@tab_label: the bookmark of the page
<!-- ##### FUNCTION gtk_notebook_prepend_page_menu ##### -->
<para>
Appends to @notebook a page whose content is @child, whose bookmark is
@tab_label, and whose menu label is @menu_label.
</para>
@notebook:
@child:
@tab_label:
@menu_label:
@notebook: the notebook widget
@child: the content of the new page
@tab_label: the bookmark of the page
@menu_label: the menu label of the page
<!-- ##### FUNCTION gtk_notebook_insert_page ##### -->
<para>
Inserts in @notebook a new page whose content is @child, and whose
bookmark is @tab_label. The page is inserted just
before the page number @position, starting with 0. If @position is out of
bounds, it is assumed to be the current number of pages.
</para>
@notebook:
@child:
@tab_label:
@position:
@notebook: the notebook widget
@child: the content of the new page
@tab_label: the bookmark of the page
@position: the position to insert the page
<!-- ##### FUNCTION gtk_notebook_insert_page_menu ##### -->
<para>
Inserts in @notebook a new page whose content is @child, whose bookmark is
@tab_label, and whose menu label is @menu_label. The page is inserted just
before the page number @position, starting with 0. If @position is out of
bounds, it is assumed to be the current number of pages.
</para>
@notebook:
@child:
@tab_label:
@menu_label:
@position:
@notebook: the notebook widget
@child: the content of the new page
@tab_label: the bookmark of the page
@menu_label: the menu label of the page
@position: the position to insert the page
<!-- ##### FUNCTION gtk_notebook_remove_page ##### -->
<para>
Removes the page @page_num form @notebook. Pages are numbered starting at
zero. Negative values stand for the last page; too large values are
ignored.
</para>
@notebook:
@page_num:
@notebook: the notebook widget
@page_num: the page number
<!-- ##### MACRO gtk_notebook_current_page ##### -->
<para>
??? I don't see such a macro in gtknotebook.h (v1.2.3).
</para>
<!-- ##### FUNCTION gtk_notebook_page_num ##### -->
<para>
Returns the page number of @child in @notebook.
</para>
@notebook:
@child:
@Returns:
@notebook: the notebook widget
@child: the child
@Returns: the page number, or -1 if @child is not in @notebook
<!-- ##### FUNCTION gtk_notebook_set_page ##### -->
<para>
Switches to the page number @page_num. Negative values stand for the last
page; too large values are ignored.
</para>
@notebook:
@page_num:
@notebook: the notebook widget
@page_num: the page number
<!-- ##### FUNCTION gtk_notebook_next_page ##### -->
<para>
Switches to the next page. Nothing happens if the current page is the last
page.
</para>
@notebook:
@notebook: the notebook widget.
<!-- ##### FUNCTION gtk_notebook_prev_page ##### -->
<para>
Switches to the previous page. Nothing happens if the current page is the
first page.
</para>
@notebook:
@notebook: the notebook widget
<!-- ##### FUNCTION gtk_notebook_reorder_child ##### -->
<para>
Moves the page @child, so that it appears in position @position. Out of
bounds @position will be clamped.
</para>
@notebook:
@child:
@position:
@notebook: the notebook widget
@child: the child to deplace
@position: the new position
<!-- ##### FUNCTION gtk_notebook_set_tab_pos ##### -->
<para>
Sets the position of the bookmarks.
</para>
@notebook:
@pos:
@notebook: the notebook widget
@pos: the position
<!-- ##### FUNCTION gtk_notebook_set_show_tabs ##### -->
<para>
Sets whether to show the bookmarks or not.
</para>
@notebook:
@show_tabs:
@notebook: the notebook widget
@show_tabs: a boolean value
<!-- ##### FUNCTION gtk_notebook_set_show_border ##### -->
<para>
Sets whether to show the border of the notebook or not. Bookmarks are in the
border.
</para>
@notebook:
@show_border:
@notebook: the notebook widget
@show_border: a boolean value
<!-- ##### FUNCTION gtk_notebook_set_scrollable ##### -->
<para>
Sets whether the bookmarks area may be scrollable or not if there are too
many bookmarks to fit in the allocated area.
</para>
@notebook:
@scrollable:
@notebook: the notebook widget
@scrollable: a boolean value
<!-- ##### FUNCTION gtk_notebook_set_tab_border ##### -->
<para>
Sets whether there should be a border around the bookmarks or not.
</para>
@notebook:
@border_width:
<!-- ##### FUNCTION gtk_notebook_popup_enable ##### -->
<para>
</para>
@notebook:
<!-- ##### FUNCTION gtk_notebook_popup_disable ##### -->
<para>
</para>
@notebook:
<!-- ##### FUNCTION gtk_notebook_get_current_page ##### -->
<para>
</para>
@notebook:
@Returns:
<!-- ##### FUNCTION gtk_notebook_get_menu_label ##### -->
<para>
</para>
@notebook:
@child:
@Returns:
<!-- ##### FUNCTION gtk_notebook_get_nth_page ##### -->
<para>
</para>
@notebook:
@page_num:
@Returns:
<!-- ##### FUNCTION gtk_notebook_get_tab_label ##### -->
<para>
</para>
@notebook:
@child:
@Returns:
<!-- ##### FUNCTION gtk_notebook_query_tab_label_packing ##### -->
<para>
</para>
@notebook:
@child:
@expand:
@fill:
@pack_type:
<!-- ##### FUNCTION gtk_notebook_set_homogeneous_tabs ##### -->
<para>
</para>
@notebook:
@homogeneous:
<!-- ##### FUNCTION gtk_notebook_set_menu_label ##### -->
<para>
</para>
@notebook:
@child:
@menu_label:
<!-- ##### FUNCTION gtk_notebook_set_menu_label_text ##### -->
<para>
</para>
@notebook:
@child:
@menu_text:
@notebook: the notebook widget
@border_width: a boolean value
<!-- ##### FUNCTION gtk_notebook_set_tab_hborder ##### -->
<para>
Sets whether the tabs should have a horizontal border.
</para>
@notebook:
@tab_hborder:
<!-- ##### FUNCTION gtk_notebook_set_tab_label ##### -->
<para>
</para>
@notebook:
@child:
@tab_label:
<!-- ##### FUNCTION gtk_notebook_set_tab_label_packing ##### -->
<para>
</para>
@notebook:
@child:
@expand:
@fill:
@pack_type:
<!-- ##### FUNCTION gtk_notebook_set_tab_label_text ##### -->
<para>
</para>
@notebook:
@child:
@tab_text:
@notebook: the notebook widget
@tab_hborder: a boolean value
<!-- ##### FUNCTION gtk_notebook_set_tab_vborder ##### -->
<para>
Sets whether the tabs should have a vertical border.
</para>
@notebook:
@tab_vborder:
@notebook: the notebook widget
@tab_vborder: a boolean value
<!-- ##### FUNCTION gtk_notebook_popup_enable ##### -->
<para>
Enables the popup menu: if the user clicks with the right mouse button on
the bookmarks, a menu with all the pages will be popped up.
</para>
@notebook: the notebook widget
<!-- ##### FUNCTION gtk_notebook_popup_disable ##### -->
<para>
Disables the popup menu
</para>
@notebook: the notebook widget
<!-- ##### FUNCTION gtk_notebook_get_current_page ##### -->
<para>
Returns the page number of the current page.
</para>
@notebook: the notebook widget
@Returns: the page number
<!-- ##### FUNCTION gtk_notebook_get_menu_label ##### -->
<para>
Returns the menu label of the page @child. NULL is returned if @child is not
in @notebook or NULL if it has the default menu label.
</para>
@notebook: the notebook widget
@child: the page
@Returns: the menu label
<!-- ##### FUNCTION gtk_notebook_get_nth_page ##### -->
<para>
Returns the content of the page number @page_num, or NULL if @page_num is
out of bounds.
</para>
@notebook: the notebook widget
@page_num: the page number
@Returns: the content of the page
<!-- ##### FUNCTION gtk_notebook_get_tab_label ##### -->
<para>
Returns the menu tab of the page @child. NULL is returned if @child is not
in @notebook or NULL if it has the default tab label.
</para>
@notebook: the notebook widget
@child: the page
@Returns: the tab label
<!-- ##### FUNCTION gtk_notebook_query_tab_label_packing ##### -->
<para>
Looks for the packing attributes of the bookmarks of @child.
</para>
@notebook: the notebook widget
@child: the page
@expand: a pointer to return the expand value (or NULL)
@fill: a pointer to return the fill value (or NULL)
@pack_type: a pointer to return the pack_type (or NULL)
<!-- ##### FUNCTION gtk_notebook_set_homogeneous_tabs ##### -->
<para>
Sets whether the tabs must have all the same size or not.
</para>
@notebook: the notebook widget
@homogeneous: a boolean value
<!-- ##### FUNCTION gtk_notebook_set_menu_label ##### -->
<para>
Changes the menu label of @child. Nothing happens if @child is not in
@notebook.
</para>
@notebook: the notebook widget
@child: the page
@menu_label: the menu label, or NULL for default
<!-- ##### FUNCTION gtk_notebook_set_menu_label_text ##### -->
<para>
Creates a new label and sets it as the menu label of @child.
</para>
@notebook: the notebook widget
@child: the page
@menu_text: the label text
<!-- ##### FUNCTION gtk_notebook_set_tab_label ##### -->
<para>
Changes the bookmark label of @child. Nothing happens if @child is not in
@notebook.
</para>
@notebook: the notebook widget
@child: the page
@tab_label: the bookmark label, or NULL for default
<!-- ##### FUNCTION gtk_notebook_set_tab_label_packing ##### -->
<para>
Sets the packing parameters for the bookmark of @child. See
#GtkBoxPackStart for the exact meanings.
</para>
@notebook: the notebook widget
@child: the child widget
@expand: whether to expand the bookmark or not
@fill: whether the bookmark should fill the allocated area or not
@pack_type: the position of the bookmark
<!-- ##### FUNCTION gtk_notebook_set_tab_label_text ##### -->
<para>
Creates a new label and sets it as the bookmark label of @child.
</para>
@notebook: the notebook widget
@child: the page
@tab_text: the label text
<!-- ##### SIGNAL GtkNotebook::switch-page ##### -->
<para>
Emitted when the user or a function changes the current page.
</para>
@notebook: the object which received the signal.
@page:
@page_num:
@page: the new current page
@page_num: the index of the page
<!-- ##### ARG GtkNotebook:page ##### -->
<para>
The current page
</para>
<!-- ##### ARG GtkNotebook:tab_pos ##### -->
<para>
The position of the bookmarks
</para>
<!-- ##### ARG GtkNotebook:tab_border ##### -->
<para>
Whether the bookmarks have a border or not
</para>
<!-- ##### ARG GtkNotebook:tab_hborder ##### -->
<para>
Whether the bookmarks have a horizontal border or not
</para>
<!-- ##### ARG GtkNotebook:tab_vborder ##### -->
<para>
Whether the bookmarks have a vertical border or not
</para>
<!-- ##### ARG GtkNotebook:show_tabs ##### -->
<para>
Whether to show the bookmarks or not
</para>
<!-- ##### ARG GtkNotebook:show_border ##### -->
<para>
Whether to show the border or not
</para>
<!-- ##### ARG GtkNotebook:scrollable ##### -->
<para>
Whether the bookmarks should be scrollable or not
</para>
<!-- ##### ARG GtkNotebook:enable_popup ##### -->
<para>
Whether the popup menu is enabled or not
</para>

1444
docs/reference/gtk/tmpl/gtkobject.sgml
View File

File diff suppressed because it is too large Load Diff

144
docs/reference/gtk/tmpl/gtkprogress.sgml
View File

@ -2,13 +2,14 @@
GtkProgress
<!-- ##### SECTION Short_Description ##### -->
the base class for #GtkProgressBar.
<!-- ##### SECTION Long_Description ##### -->
<para>
A #GtkProgress is the abstract base class used to derive
a #GtkProgressBar which provides a visual representation of
the progress of a long running operation.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
@ -16,149 +17,184 @@ GtkProgress
<!-- ##### STRUCT GtkProgress ##### -->
<para>
The #GtkProgress-struct struct contains private data only.
and should be accessed using the functions below.
</para>
<!-- ##### FUNCTION gtk_progress_set_show_text ##### -->
<para>
Controls whether progress text is shown.
</para>
@progress:
@show_text:
@progress: a #GtkProgress.
@show_text: a boolean indicating whether the progress text
is shown.
<!-- ##### FUNCTION gtk_progress_set_text_alignment ##### -->
<para>
Controls the alignment of the text within the progress bar area.
</para>
@progress:
@x_align:
@y_align:
@progress: a #GtkProgress.
@x_align: a number between 0.0 and 1.0 indicating the horizontal
alignment of the progress text within the #GtkProgress.
@y_align: a number between 0.0 and 1.0 indicating the vertical
alignment of the progress text within the #GtkProgress.
<!-- ##### FUNCTION gtk_progress_set_format_string ##### -->
<para>
Sets a format string used to display text indicating the
current progress. The string can contain the following substitution characters:
<itemizedlist>
<listitem>
<para>
%%v - the current progress value.
</para>
<listitem>
<para>
%%l - the lower bound for the progress value.
</para>
<listitem>
<para>
%%u - the upper bound for the progress value.
</para>
<listitem>
<para>
%%p - the current progress percentage.
</para>
</itemizedlist>
</para>
@progress:
@format:
@progress: a #GtkProgress.
@format: a string used to display progress text.
<!-- ##### FUNCTION gtk_progress_set_adjustment ##### -->
<para>
Associates a #GtkAdjustment with the #GtkProgress. A #GtkAdjustment
is used to represent the upper and lower bounds and the step interval
of the underlying value for which progress is shown.
</para>
@progress:
@adjustment:
@progress: a #GtkProgress.
@adjustment: the #GtkAdjustment to be associated with the #GtkProgress.
<!-- ##### FUNCTION gtk_progress_set_percentage ##### -->
<para>
Sets the current percentage completion for the #GtkProgress.
</para>
@progress:
@percentage:
@progress: a #GtkProgress.
@percentage: the percentage complete which must be between 0.0
and 1.0.
<!-- ##### FUNCTION gtk_progress_set_value ##### -->
<para>
Sets the value within the #GtkProgress to an absolute value.
The value must be within the valid range of values for the
underlying #GtkAdjustment.
</para>
@progress:
@value:
@progress: a #GtkProgress.
@value: the value indicating the current completed amount.
<!-- ##### FUNCTION gtk_progress_get_value ##### -->
<para>
Returns the current progress complete value.
</para>
@progress:
@Returns:
@progress: a #GtkProgress.
@Returns: the current progress complete value.
<!-- ##### FUNCTION gtk_progress_set_activity_mode ##### -->
<para>
A #GtkProgress can be in one of two different modes: percentage
mode (the default) and activity mode. In activity mode, the
progress is simply indicated as activity rather than as a percentage
complete.
</para>
@progress:
@activity_mode:
@progress: a #GtkProgress.
@activity_mode: a boolean, TRUE for activity mode.
<!-- ##### FUNCTION gtk_progress_get_current_text ##### -->
<para>
Returns the current text associated with the #GtkProgress. This
text is the based on the underlying format string after any substitutions
are made.
</para>
@progress:
@Returns:
@progress: a #GtkProgress.
@Returns: the text indicating the current progress.
<!-- ##### FUNCTION gtk_progress_get_text_from_value ##### -->
<para>
Returns the text indicating the progress based on the supplied value.
The current value for the #GtkProgress remains unchanged.
</para>
@progress:
@value:
@Returns:
@progress: a #GtkProgress.
@value: an absolute progress value to use when formatting the progress text.
@Returns: a string indicating the progress.
<!-- ##### FUNCTION gtk_progress_get_current_percentage ##### -->
<para>
Returns the current progress as a percentage.
</para>
@progress:
@Returns:
@progress: a #GtkProgress.
@Returns: a number between 0.0 and 1.0 indicating the percentage complete.
<!-- ##### FUNCTION gtk_progress_get_percentage_from_value ##### -->
<para>
Returns the progress as a percentage calculated from the supplied
absolute progress value.
</para>
@progress:
@value:
@Returns:
@progress: a #GtkProgress.
@value: an absolute progress value.
@Returns: a number between 0.0 and 1.0 indicating the percentage complete
represented by @value.
<!-- ##### FUNCTION gtk_progress_configure ##### -->
<para>
Allows the configuration of the minimum, maximum, and current values for
the #GtkProgress.
</para>
@progress:
@value:
@min:
@max:
@progress: a #GtkProgress.
@value: the current progress value.
@min: the minimum progress value.
@max: the maximum progress value.
<!-- ##### ARG GtkProgress:activity_mode ##### -->
<para>
A boolean indicating whether activity mode is enabled.
</para>
<!-- ##### ARG GtkProgress:show_text ##### -->
<para>
A boolean indicating whether the progress is shown as text.
</para>
<!-- ##### ARG GtkProgress:text_xalign ##### -->
<para>
A number between 0.0 and 1.0 specifying the horizontal alignment.
</para>
<!-- ##### ARG GtkProgress:text_yalign ##### -->
<para>
A number between 0.0 and 1.0 specifying the vertical alignment.
</para>

155
docs/reference/gtk/tmpl/gtkprogressbar.sgml
View File

@ -2,11 +2,38 @@
GtkProgressBar
<!-- ##### SECTION Short_Description ##### -->
a widget which indicates progress visually.
<!-- ##### SECTION Long_Description ##### -->
<para>
The #GtkProgressBar is typically used to display the progress of a long
running operation. It provides a visual clue that processing
is underway. The #GtkProgressBar can be used in two different
modes: percentage mode and activity mode.
</para>
<para>
When an application can determine how much work needs to take place
(e.g. read a fixed number of bytes from a file) and can monitor its
progress, it can use the #GtkProgressBar in percentage mode and the user
sees a growing bar indicating the percentage of the work that has
been completed. In this mode, the application is required to call
either the gtk_progress_set_percentage() or gtk_progress_set_value()
functions periodically to update the progress bar.
</para>
<para>
When an application has no accurate way of knowing the amount of work
to do, it can use the #GtkProgressBar in activity mode. In this mode
the progress bar shows activity by a block moving back and forth within
the progress area.
</para>
<para>
There is quite a bit of flexibility provided to control the appearance
of the #GtkProgressBar. Functions are provided to control the
orientation of the bar, optional text which can be displayed along with
the bar, and the style in which the bar grows.
</para>
<!-- ##### SECTION See_Also ##### -->
@ -16,126 +43,176 @@ GtkProgressBar
<!-- ##### STRUCT GtkProgressBar ##### -->
<para>
The #GtkProgressBar-struct struct contains private data only,
and should be accessed using the functions below.
</para>
<!-- ##### ENUM GtkProgressBarStyle ##### -->
<para>
An enumeration representing the styles for drawing the progress bar.
<informaltable pgwide=1 frame="none" role="enum">
<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
<tbody>
<row>
<entry>GTK_PROGRESS_CONTINUOUS</entry>
<entry>The progress bar grows in a smooth, continuous manner.</entry>
</row>
<row>
<entry>GTK_PROGRESS_DISCRETE</entry>
<entry>The progress bar grows in discrete, visible blocks.</entry>
</row>
</tbody></tgroup></informaltable>
</para>
@GTK_PROGRESS_CONTINUOUS:
@GTK_PROGRESS_DISCRETE:
<!-- ##### ENUM GtkProgressBarOrientation ##### -->
<para>
An enumeration representing possible orientations and growth
directions for the visible progress bar.
<informaltable pgwide=1 frame="none" role="enum">
<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
<tbody>
<row>
<entry>GTK_PROGRESS_LEFT_TO_RIGHT</entry>
<entry>A horizontal progress bar growing from left to right.</entry>
</row>
<row>
<entry>GTK_PROGRESS_RIGHT_TO_LEFT</entry>
<entry>A horizontal progress bar growing from right to left.</entry>
</row>
<row>
<entry>GTK_PROGRESS_BOTTOM_TO_TOP</entry>
<entry>A vertical progress bar growing from bottom to top.</entry>
</row>
<row>
<entry>GTK_PROGRESS_TOP_TO_BOTTOM</entry>
<entry>A vertical progress bar growing from top to bottom.</entry>
</row>
</tbody></tgroup></informaltable>
</para>
@GTK_PROGRESS_LEFT_TO_RIGHT:
@GTK_PROGRESS_RIGHT_TO_LEFT:
@GTK_PROGRESS_BOTTOM_TO_TOP:
@GTK_PROGRESS_TOP_TO_BOTTOM:
<!-- ##### FUNCTION gtk_progress_bar_new ##### -->
<para>
Creates a new #GtkProgressBar.
</para>
@Returns:
@Returns: a #GtkProgressBar.
<!-- ##### FUNCTION gtk_progress_bar_new_with_adjustment ##### -->
<para>
Creates a new #GtkProgressBar with an associated #GtkAdjustment.
</para>
@adjustment:
@Returns:
@adjustment: a #GtkAdjustment.
@Returns: a #GtkProgressBar.
<!-- ##### FUNCTION gtk_progress_bar_set_bar_style ##### -->
<para>
Sets the style of the #GtkProgressBar. The default style is
%GTK_PROGRESS_CONTINUOUS.
</para>
@pbar:
@style:
@pbar: a #GtkProgressBar.
@style: a #GtkProgressBarStyle value indicating the desired style.
<!-- ##### FUNCTION gtk_progress_bar_set_discrete_blocks ##### -->
<para>
Sets the number of blocks that the progress bar is divided into
when the style is %GTK_PROGRESS_DISCRETE.
</para>
@pbar:
@blocks:
@pbar: a #GtkProgressBar.
@blocks: number of individual blocks making up the bar.
<!-- ##### FUNCTION gtk_progress_bar_set_activity_step ##### -->
<para>
Sets the step value used when the progress bar is in activity
mode. The step is the amount by which the progress is incremented
each iteration.
</para>
@pbar:
@step:
@pbar: a #GtkProgressBar.
@step: the amount which the progress is incremented in activity
mode.
<!-- ##### FUNCTION gtk_progress_bar_set_activity_blocks ##### -->
<para>
Sets the number of blocks used when the progress bar is in activity
mode. Larger numbers make the visible block smaller.
</para>
@pbar:
@blocks:
@pbar: a #GtkProgressBar.
@blocks: number of blocks which can fit within the progress bar area.
<!-- ##### FUNCTION gtk_progress_bar_set_orientation ##### -->
<para>
Sets the orientation of the progress bar. This controls whether
the bar is horizontal or vertical and the direction in which it
grows.
</para>
@pbar:
@orientation:
@pbar: a #GtkProgressBar.
@orientation: a #GtkProgressBarOrientation value which specifies the
orientation and growth direction of the bar.
<!-- ##### FUNCTION gtk_progress_bar_update ##### -->
<para>
This function is deprecated. Please use gtk_progress_set_value() or
gtk_progress_set_percentage() instead.
</para>
@pbar:
@percentage:
@pbar: a #GtkProgressBar.
@percentage: the new percent complete value.
<!-- ##### ARG GtkProgressBar:adjustment ##### -->
<para>
a #GtkAdjustment to be used with the #GtkProgressBar.
</para>
<!-- ##### ARG GtkProgressBar:orientation ##### -->
<para>
a #GtkProgressBarOrientation value which specifies the
orientation and growth direction of the bar.
</para>
<!-- ##### ARG GtkProgressBar:bar_style ##### -->
<para>
a #GtkProgressBarStyle value which specifies the
visual style of the bar in percentage mode.
</para>
<!-- ##### ARG GtkProgressBar:activity_step ##### -->
<para>
The increment used for each iteration in activity mode.
</para>
<!-- ##### ARG GtkProgressBar:activity_blocks ##### -->
<para>
The number of blocks which can fit in the progress bar
area in activity mode.
</para>
<!-- ##### ARG GtkProgressBar:discrete_blocks ##### -->
<para>
The number of blocks which which make up progress bar
when it is shown in %GTK_PROGRESS_DISCRETE style.
</para>

64
docs/reference/gtk/tmpl/gtkvbbox.sgml
View File

@ -2,16 +2,49 @@
GtkVButtonBox
<!-- ##### SECTION Short_Description ##### -->
a container for arranging buttons vertically.
<!-- ##### SECTION Long_Description ##### -->
<para>
A button box should be used to provide a consistent layout of buttons
throughout your application. There is one default layout and a default
spacing value that are persistant across all #VButtonBox widgets.
</para>
<para>
The layout/spacing can then be altered by the programmer, or if desired, by
the user to alter the 'feel' of a program to a small degree.
</para>
<para>
A #VButtonBox is created with gtk_vbutton_box_new(). Buttons are packed into
a button box the same way as any other box, using gtk_box_pack_start() or
gtk_box_pack_end().
</para>
<para>
The default spacing between buttons can be set with
gtk_vbutton_box_set_spacing_default() and queried with
gtk_vbutton_box_get_spacing_default().
</para>
<para>
The arrangement and layout of the buttons can be changed using
gtk_vbutton_box_set_layout_default() and queried with
gtk_vbutton_box_get_layout_default().
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
<variablelist>
<varlistentry>
<term>#GtkBox</term>
<listitem><para>Used to pack widgets into button boxes.</para></listitem>
</varlistentry><varlistentry>
<term>#GtkButtonBox</term>
<listitem><para>Provides functions for controlling button boxes.</para></listitem>
</varlistentry>
<varlistentry>
<term>#GtkHButtonBox</term>
<listitem><para>Pack buttons horizontally.</para></listitem>
</varlistentry>
</variablelist>
</para>
<!-- ##### STRUCT GtkVButtonBox ##### -->
@ -19,44 +52,45 @@ GtkVButtonBox
</para>
@button_box: the #GtkButtonBox that this class is derived from.
<!-- ##### FUNCTION gtk_vbutton_box_new ##### -->
<para>
Creates a new vertical button box.
</para>
@Returns:
@Returns: a new button box #GtkWidget.
<!-- ##### FUNCTION gtk_vbutton_box_get_spacing_default ##### -->
<para>
Retrieves the current default spacing for vertical button boxes. This is the number of pixels
to be placed between the buttons when they are arranged.
</para>
@Returns:
@Returns: the default number of pixels between buttons.
<!-- ##### FUNCTION gtk_vbutton_box_set_spacing_default ##### -->
<para>
Changes the default spacing that is placed between widgets in an
vertical button box.
</para>
@spacing:
@spacing: an integer value.
<!-- ##### FUNCTION gtk_vbutton_box_get_layout_default ##### -->
<para>
Retrieves the current layout used to arrange buttons in button box widgets.
</para>
@Returns:
@Returns: the current #GtkButtonBoxStyle.
<!-- ##### FUNCTION gtk_vbutton_box_set_layout_default ##### -->
<para>
Sets a new layout mode that will be used by all button boxes.
</para>
@layout:
@layout: a new #GtkButtonBoxStyle.

44
docs/reference/gtk/tmpl/gtkvbox.sgml
View File

@ -5,29 +5,29 @@ GtkVBox
vertical container box
<!-- ##### SECTION Long_Description ##### -->
<para>
GtkVBox is a container that organizes child widgets into a single column.
</para>
<para>
Use the #GtkBox packing interface to determine the arrangement,
spacing, height, and alignment of GtkVBox children.
</para>
<para>
All children are allocated the same width.
<para>
GtkVBox is a container that organizes child widgets into a single column.
</para>
<para>
Use the #GtkBox packing interface to determine the arrangement,
spacing, height, and alignment of GtkVBox children.
</para>
<para>
All children are allocated the same width.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
<variablelist>
<varlistentry>
<term>#GtkHBox</term>
<listitem><para>a sister class that organizes widgets into a row.</para></listitem>
</varlistentry>
</variablelist>
<para>
<variablelist>
<varlistentry>
<term>#GtkHBox</term>
<listitem><para>a sister class that organizes widgets into a row.</para></listitem>
</varlistentry>
</variablelist>
</para>
<!-- ##### STRUCT GtkVBox ##### -->
@ -35,8 +35,8 @@ All children are allocated the same width.
<!-- ##### FUNCTION gtk_vbox_new ##### -->
<para>
Creates a new GtkVBox.
<para>
Creates a new GtkVBox.
</para>
@homogeneous: %TRUE if all children are to be given equal space allotments.