AuroraMiddleware/gtk
1
0
Fork 1
mirror of https://gitlab.gnome.org/GNOME/gtk.git synced 2024-11-10 19:00:08 +00:00
Code Issues Projects Releases Wiki Activity

Merge docs inline

Browse Source 
svn path=/trunk/; revision=21955
This commit is contained in:
Matthias Clasen 2008-12-28 18:57:44 +00:00
parent b7935e5e78
commit a07dea8803
4 changed files with 151 additions and 179 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
ChangeLog
View File

@ -1,3 +1,7 @@
2008-12-28 Matthias Clasen <mclasen@redhat.com>
* gtk/gtkeditable.c: Merge docs inline.
2008-12-28 Matthias Clasen <mclasen@redhat.com>
* gtk/gtkhsv.c:

4
docs/reference/ChangeLog
View File

@ -1,3 +1,7 @@
2008-12-28 Matthias Clasen <mclasen@redhat.com>
* gtk/tmpl/gtkeditable.sgml: Merge docs inline.
2008-12-27 Matthias Clasen <mclasen@redhat.com>
* gtk/tmpl/gtkmessagedialog.sgml:

192
docs/reference/gtk/tmpl/gtkeditable.sgml
View File

@ -57,230 +57,142 @@ insert_text_handler (GtkEditable *editable,
<!-- ##### STRUCT GtkEditable ##### -->
<para>
The #GtkEditable structure 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>#guint selection_start;</entry>
<entry>the starting position of the selected characters
in the widget.</entry>
</row>
<row>
<entry>#guint selection_end;</entry>
<entry>the end position of the selected characters
in the widget.</entry>
</row>
<row>
<entry>#guint editable;</entry>
<entry>a flag indicating whether or not the widget is
editable by the user.</entry>
</row>
</tbody></tgroup></informaltable>
</para>
<!-- ##### SIGNAL GtkEditable::changed ##### -->
<para>
Indicates that the user has changed the contents
of the widget.
The #GtkEditable structure is an opaque structure whose members
cannot be directly accessed.
</para>
@editable: the object which received the signal.
<!-- ##### SIGNAL GtkEditable::delete-text ##### -->
<para>
This signal is emitted when text is deleted from
the widget by the user. The default handler for
this signal will normally be responsible for deleting
the text, so by connecting to this signal and then
stopping the signal with gtk_signal_emit_stop(), it
is possible to modify the range of deleted text, or
prevent it from being deleted entirely. The @start_pos
and @end_pos parameters are interpreted as for
gtk_editable_delete_text()
</para>
@editable: the object which received the signal.
@start_pos: the starting position.
@end_pos: the end position.
@editable:
@start_pos:
@end_pos:
<!-- ##### SIGNAL GtkEditable::insert-text ##### -->
<para>
This signal is emitted when text is inserted into
the widget by the user. The default handler for
this signal will normally be responsible for inserting
the text, so by connecting to this signal and then
stopping the signal with gtk_signal_emit_stop(), it
is possible to modify the inserted text, or prevent
it from being inserted entirely.
</para>
@editable: the object which received the signal.
@new_text: the new text to insert.
@new_text_length: the length of the new text, in bytes,
or -1 if new_text is nul-terminated
@position: the position, in characters, at which to insert
the new text. this is an in-out parameter.
After the signal emission is finished, it should
point after the newly inserted text.
@editable:
@new_text:
@new_text_length:
@position:
<!-- ##### FUNCTION gtk_editable_select_region ##### -->
<para>
Selects a region of text. The characters that
are selected are those characters at positions from
@start_pos up to, but not including @end_pos. If
@end_pos is negative, then the the characters selected
will be those characters from @start_pos to the end
of the text.
</para>
@editable: a #GtkEditable widget.
@start: the starting position.
@end: the end position.
@editable:
@start:
@end:
<!-- ##### FUNCTION gtk_editable_get_selection_bounds ##### -->
<para>
Gets the current selection bounds, if there is a selection.
</para>
@editable: a #GtkEditable widget.
@start: location to store the starting position, or %NULL.
@end: location to store the end position, or %NULL.
@Returns: %TRUE if there is a selection.
@editable:
@start:
@end:
@Returns:
<!-- ##### FUNCTION gtk_editable_insert_text ##### -->
<para>
Inserts text at a given position.
</para>
@editable: a #GtkEditable widget.
@new_text: the text to insert.
@new_text_length: the length of the text to insert, in bytes
@position: an inout parameter. The caller initializes it to
the position at which to insert the text. After the
call it points at the position after the newly
inserted text.
@editable:
@new_text:
@new_text_length:
@position:
<!-- ##### FUNCTION gtk_editable_delete_text ##### -->
<para>
Deletes a sequence of characters. The characters that
are deleted are those characters at positions from
@start_pos up to, but not including @end_pos. If
@end_pos is negative, then the the characters deleted
will be those characters from @start_pos to the end
of the text.
</para>
@editable: a #GtkEditable widget.
@start_pos: the starting position.
@end_pos: the end position.
@editable:
@start_pos:
@end_pos:
<!-- ##### FUNCTION gtk_editable_get_chars ##### -->
<para>
Retrieves a sequence of characters. The characters that
are retrieved are those characters at positions from
@start_pos up to, but not including @end_pos. If
@end_pos is negative, then the the characters retrieved
will be those characters from @start_pos to the end
of the text.
</para>
@editable: a #GtkEditable widget.
@start_pos: the starting position.
@end_pos: the end position.
@Returns: the characters in the indicated region.
The result must be freed with g_free() when
the application is finished with it.
@editable:
@start_pos:
@end_pos:
@Returns:
<!-- ##### FUNCTION gtk_editable_cut_clipboard ##### -->
<para>
Causes the characters in the current selection to
be copied to the clipboard and then deleted from
the widget.
</para>
@editable: a #GtkEditable widget.
@editable:
<!-- ##### FUNCTION gtk_editable_copy_clipboard ##### -->
<para>
Causes the characters in the current selection to
be copied to the clipboard.
</para>
@editable: a #GtkEditable widget.
@editable:
<!-- ##### FUNCTION gtk_editable_paste_clipboard ##### -->
<para>
Causes the contents of the clipboard to be pasted into
the given widget at the current cursor position.
</para>
@editable: a #GtkEditable widget.
@editable:
<!-- ##### FUNCTION gtk_editable_delete_selection ##### -->
<para>
Deletes the current contents of the widgets selection and
disclaims the selection.
</para>
@editable: a #GtkEditable widget.
@editable:
<!-- ##### FUNCTION gtk_editable_set_position ##### -->
<para>
Sets the cursor position.
</para>
@editable: a #GtkEditable widget.
@position: the position of the cursor. The cursor is displayed
before the character with the given (base 0) index
in the widget. The value must be less than or
equal to the number of characters in the widget.
A value of -1 indicates that the position should
be set after the last character in the entry.
Note that this position is in characters, not in
bytes.
@editable:
@position:
<!-- ##### FUNCTION gtk_editable_get_position ##### -->
<para>
Retrieves the current cursor position.
</para>
@editable: a #GtkEditable widget.
@Returns: the position of the cursor. The cursor is displayed
before the character with the given (base 0) index
in the widget. The value will be less than or
equal to the number of characters in the widget.
Note that this position is in characters, not in
bytes.
@editable:
@Returns:
<!-- ##### FUNCTION gtk_editable_set_editable ##### -->
<para>
Determines if the user can edit the text in the editable
widget or not.
</para>
@editable: a #GtkEditable widget.
@is_editable: %TRUE if the user is allowed to edit the text
in the widget.
@editable:
@is_editable:
<!-- ##### FUNCTION gtk_editable_get_editable ##### -->

130
gtk/gtkeditable.c
View File

@ -64,6 +64,25 @@ gtk_editable_base_init (gpointer g_class)
if (! initialized)
{
/**
* GtkEditable::insert-text:
* @editable: the object which received the signal
* @new_text: the new text to insert
* @new_text_length: the length of the new text, in bytes,
* or -1 if new_text is nul-terminated
* @position: the position, in characters, at which to insert
* the new text. this is an in-out parameter.
* After the signal emission is finished, it should
* point after the newly inserted text.
*
* This signal is emitted when text is inserted into
* the widget by the user. The default handler for
* this signal will normally be responsible for inserting
* the text, so by connecting to this signal and then
* stopping the signal with g_signal_stop_emission(), it
* is possible to modify the inserted text, or prevent
* it from being inserted entirely.
*/
g_signal_new (I_("insert-text"),
GTK_TYPE_EDITABLE,
G_SIGNAL_RUN_LAST,
@ -74,6 +93,23 @@ gtk_editable_base_init (gpointer g_class)
G_TYPE_STRING,
G_TYPE_INT,
G_TYPE_POINTER);
/**
* GtkEditable::delete-text:
* @editable: the object which received the signal
* @start_pos: the starting position
* @end_pos: the end position
*
* This signal is emitted when text is deleted from
* the widget by the user. The default handler for
* this signal will normally be responsible for deleting
* the text, so by connecting to this signal and then
* stopping the signal with g_signal_stop_emission(), it
* is possible to modify the range of deleted text, or
* prevent it from being deleted entirely. The @start_pos
* and @end_pos parameters are interpreted as for
* gtk_editable_delete_text().
*/
g_signal_new (I_("delete-text"),
GTK_TYPE_EDITABLE,
G_SIGNAL_RUN_LAST,
@ -100,11 +136,14 @@ gtk_editable_base_init (gpointer g_class)
* @editable: a #GtkEditable
* @new_text: the text to append
* @new_text_length: the length of the text in bytes, or -1
* @position: position text will be inserted at
* @position: location of the position text will be inserted at
*
* Appends @new_text_length bytes of @new_text to the contents of the widget,
* at position @position. Note that this position is in characters, not in bytes.
**/
* Inserts @new_text_length bytes of @new_text into the contents of the
* widget, at position @position.
*
* Note that the position is in characters, not in bytes.
* The function updates @position to point after the newly inserted text.
*/
void
gtk_editable_insert_text (GtkEditable *editable,
const gchar *new_text,
@ -126,9 +165,13 @@ gtk_editable_insert_text (GtkEditable *editable,
* @start_pos: start position
* @end_pos: end position
*
* Deletes the content of the editable between @start_pos and @end_pos.
* Note that positions are specified in characters, not bytes.
**/
* Deletes a sequence of characters. The characters that are deleted are
* those characters at positions from @start_pos up to, but not including
* @end_pos. If @end_pos is negative, then the the characters deleted
* are those from @start_pos to the end of the text.
*
* Note that the positions are specified in characters, not bytes.
*/
void
gtk_editable_delete_text (GtkEditable *editable,
gint start_pos,
@ -145,13 +188,17 @@ gtk_editable_delete_text (GtkEditable *editable,
* @start_pos: start of text
* @end_pos: end of text
*
* Retreives the content of the editable between @start_pos and @end_pos.
* Retrieves a sequence of characters. The characters that are retrieved
* are those characters at positions from @start_pos up to, but not
* including @end_pos. If @end_pos is negative, then the the characters
* retrieved are those characters from @start_pos to the end of the text.
*
* Note that positions are specified in characters, not bytes.
*
* Return value: a pointer to the contents of the widget as a
* string. This string is allocated by the #GtkEditable
* implementation and should be freed by the caller.
**/
*/
gchar *
gtk_editable_get_chars (GtkEditable *editable,
gint start_pos,
@ -165,15 +212,16 @@ gtk_editable_get_chars (GtkEditable *editable,
/**
* gtk_editable_set_position:
* @editable: a #GtkEditable
* @position: the position of the cursor. The cursor is displayed
* before the character with the given (base 0) index in the editable.
* The value must be less than or equal to the number of characters
* in the editable. A value of -1 indicates that the position should
* be set after the last character of the editable. Note that this
* position is in characters, not in bytes.
* @position: the position of the cursor
*
* Sets the cursor position in the editable to the given value.
**/
*
* The cursor is displayed before the character with the given (base 0)
* index in the contents of the editable. The value must be less than or
* equal to the number of characters in the editable. A value of -1
* indicates that the position should be set after the last character
* of the editable. Note that @position is in characters, not in bytes.
*/
void
gtk_editable_set_position (GtkEditable *editable,
gint position)
@ -188,11 +236,12 @@ gtk_editable_set_position (GtkEditable *editable,
* @editable: a #GtkEditable
*
* Retrieves the current position of the cursor relative to the start
* of the content of the editable. Note that this position is in characters,
* not in bytes.
* of the content of the editable.
*
* Note that this position is in characters, not in bytes.
*
* Return value: the cursor position
**/
*/
gint
gtk_editable_get_position (GtkEditable *editable)
{
@ -204,17 +253,17 @@ gtk_editable_get_position (GtkEditable *editable)
/**
* gtk_editable_get_selection_bounds:
* @editable: a #GtkEditable
* @start_pos: beginning of selection
* @end_pos: end of selection
* @start_pos: location to store the starting position, or %NULL
* @end_pos: location to store the end position, or %NULL
*
* Retrieves the selection bound of the editable. @start_pos will be filled
* with the start of the selection and @end_pos with end. If no text was selected
* both will be identical and %FALSE will be returned. Note that positions are
* specified in characters, not bytes.
* Retrieves the selection bound of the editable. start_pos will be filled
* with the start of the selection and @end_pos with end. If no text was
* selected both will be identical and %FALSE will be returned.
*
* Note that positions are specified in characters, not bytes.
*
* Return value: %TRUE if an area is selected, %FALSE otherwise
*
**/
*/
gboolean
gtk_editable_get_selection_bounds (GtkEditable *editable,
gint *start_pos,
@ -240,8 +289,8 @@ gtk_editable_get_selection_bounds (GtkEditable *editable,
* @editable: a #GtkEditable
*
* Deletes the currently selected text of the editable.
* This call will not do anything if there is no selected text.
**/
* This call doesn't do anything if there is no selected text.
*/
void
gtk_editable_delete_selection (GtkEditable *editable)
{
@ -259,10 +308,14 @@ gtk_editable_delete_selection (GtkEditable *editable)
* @start_pos: start of region
* @end_pos: end of region
*
* Selects the text between @start_pos and @end_pos. Both @start_pos and
* @end_pos are relative to the start of the content. Note that positions
* are specified in characters, not bytes.
**/
* Selects a region of text. The characters that are selected are
* those characters at positions from @start_pos up to, but not
* including @end_pos. If @end_pos is negative, then the the
* characters selected are those characters from @start_pos to
* the end of the text.
*
* Note that positions are specified in characters, not bytes.
*/
void
gtk_editable_select_region (GtkEditable *editable,
gint start_pos,
@ -279,7 +332,7 @@ gtk_editable_select_region (GtkEditable *editable,
*
* Removes the contents of the currently selected content in the editable and
* puts it on the clipboard.
**/
*/
void
gtk_editable_cut_clipboard (GtkEditable *editable)
{
@ -294,7 +347,7 @@ gtk_editable_cut_clipboard (GtkEditable *editable)
*
* Copies the contents of the currently selected content in the editable and
* puts it on the clipboard.
**/
*/
void
gtk_editable_copy_clipboard (GtkEditable *editable)
{
@ -309,7 +362,7 @@ gtk_editable_copy_clipboard (GtkEditable *editable)
*
* Pastes the content of the clipboard to the current position of the
* cursor in the editable.
**/
*/
void
gtk_editable_paste_clipboard (GtkEditable *editable)
{
@ -326,8 +379,7 @@ gtk_editable_paste_clipboard (GtkEditable *editable)
*
* Determines if the user can edit the text in the editable
* widget or not.
*
**/
*/
void
gtk_editable_set_editable (GtkEditable *editable,
gboolean is_editable)
@ -347,7 +399,7 @@ gtk_editable_set_editable (GtkEditable *editable,
* gtk_editable_set_editable().
*
* Return value: %TRUE if @editable is editable.
**/
*/
gboolean
gtk_editable_get_editable (GtkEditable *editable)
{