luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-02-13 22:07:15 +01:00
Code Issues Packages Projects Releases Wiki Activity

GCompletion: move docs from tmpl to .c

Browse Source
This commit is contained in:
Ryan Lortie 2010-01-31 00:03:33 -05:00
parent 75b3bd99e1
commit 5ee096636b
3 changed files with 123 additions and 158 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/reference/glib/tmpl/.gitignore vendored
View File

@ -1,5 +1,6 @@
allocators.sgml allocators.sgml
base64.sgml base64.sgml
completion.sgml
datasets.sgml datasets.sgml
datalist.sgml datalist.sgml
ghostutils.sgml ghostutils.sgml

158
docs/reference/glib/tmpl/completion.sgml
View File

@ -1,158 +0,0 @@
<!-- ##### SECTION Title ##### -->
Automatic String Completion
<!-- ##### SECTION Short_Description ##### -->
support for automatic completion using a group of target strings
<!-- ##### SECTION Long_Description ##### -->
<para>
#GCompletion provides support for automatic completion of a string using
any group of target strings. It is typically used for file name completion
as is common in many UNIX shells.
</para>
<para>
A #GCompletion is created using g_completion_new().
Target items are added and removed with
g_completion_add_items(), g_completion_remove_items() and
g_completion_clear_items().
A completion attempt is requested with g_completion_complete() or
g_completion_complete_utf8().
When no longer needed, the #GCompletion is freed with g_completion_free().
</para>
<para>
Items in the completion can be simple strings (e.g. filenames),
or pointers to arbitrary data structures. If data structures are used
you must provide a #GCompletionFunc in g_completion_new(),
which retrieves the item's string from the data structure.
You can change the way in which strings are compared by setting
a different #GCompletionStrncmpFunc in g_completion_set_compare().
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
<!-- ##### SECTION Stability_Level ##### -->
<!-- ##### STRUCT GCompletion ##### -->
<para>
The data structure used for automatic completion.
</para>
@items: list of target items (strings or data structures).
@func: function which is called to get the string associated with a target
item. It is %NULL if the target items are strings.
@prefix: the last prefix passed to g_completion_complete() or
g_completion_complete_utf8().
@cache: the list of items which begin with @prefix.
@strncmp_func: The function to use when comparing strings.
Use g_completion_set_compare() to modify this function.
<!-- ##### FUNCTION g_completion_new ##### -->
<para>
Creates a new #GCompletion.
</para>
@func: the function to be called to return the string representing an item
in the #GCompletion, or %NULL if strings are going to be used as the
#GCompletion items.
@Returns: the new #GCompletion.
<!-- ##### USER_FUNCTION GCompletionFunc ##### -->
<para>
Specifies the type of the function passed to g_completion_new().
It should return the string corresponding to the given target item.
This is used when you use data structures as #GCompletion items.
</para>
@Param1: the completion item.
@Returns: the string corresponding to the item.
<!-- ##### FUNCTION g_completion_add_items ##### -->
<para>
Adds items to the #GCompletion.
</para>
@cmp: the #GCompletion.
@items: the list of items to add.
<!-- ##### FUNCTION g_completion_remove_items ##### -->
<para>
Removes items from a #GCompletion.
</para>
@cmp: the #GCompletion.
@items: the items to remove.
<!-- ##### FUNCTION g_completion_clear_items ##### -->
<para>
Removes all items from the #GCompletion.
</para>
@cmp: the #GCompletion.
<!-- ##### FUNCTION g_completion_complete ##### -->
<para>
Attempts to complete the string @prefix using the #GCompletion target items.
</para>
@cmp: the #GCompletion.
@prefix: the prefix string, typically typed by the user, which is compared
with each of the items.
@new_prefix: if non-%NULL, returns the longest prefix which is common to all
items that matched @prefix, or %NULL if no items matched @prefix.
This string should be freed when no longer needed.
@Returns: the list of items whose strings begin with @prefix. This should
not be changed.
<!-- ##### FUNCTION g_completion_complete_utf8 ##### -->
<para>
</para>
@cmp:
@prefix:
@new_prefix:
@Returns:
<!-- ##### FUNCTION g_completion_set_compare ##### -->
<para>
Sets the function to use for string comparisons. The default
string comparison function is strncmp().
</para>
@cmp: a #GCompletion.
@strncmp_func: the string comparison function.
<!-- ##### USER_FUNCTION GCompletionStrncmpFunc ##### -->
<para>
Specifies the type of the function passed to g_completion_set_compare().
This is used when you use strings as #GCompletion items.
</para>
@s1: string to compare with @s2.
@s2: string to compare with @s1.
@n: maximal number of bytes to compare.
@Returns: an integer less than, equal to, or greater than zero if the
first @n bytes of @s1 is found, respectively, to be less than, to match,
or to be greater than the first @n bytes of @s2.
<!-- ##### FUNCTION g_completion_free ##### -->
<para>
Frees all memory used by the #GCompletion.
</para>
@cmp: the #GCompletion.

122
glib/gcompletion.c
View File

@ -35,9 +35,82 @@
#include "glib.h" #include "glib.h"
#include "galias.h" #include "galias.h"
/**
* SECTION: completion
* @title: Automatic String Completion
* @short_description: support for automatic completion using a group
* of target strings
*
* #GCompletion provides support for automatic completion of a string
* using any group of target strings. It is typically used for file
* name completion as is common in many UNIX shells.
*
* A #GCompletion is created using g_completion_new(). Target items are
* added and removed with g_completion_add_items(),
* g_completion_remove_items() and g_completion_clear_items(). A
* completion attempt is requested with g_completion_complete() or
* g_completion_complete_utf8(). When no longer needed, the
* #GCompletion is freed with g_completion_free().
*
* Items in the completion can be simple strings (e.g. filenames), or
* pointers to arbitrary data structures. If data structures are used
* you must provide a #GCompletionFunc in g_completion_new(), which
* retrieves the item's string from the data structure. You can change
* the way in which strings are compared by setting a different
* #GCompletionStrncmpFunc in g_completion_set_compare().
**/
/**
* GCompletion:
* @items: list of target items (strings or data structures).
* @func: function which is called to get the string associated with a
* target item. It is %NULL if the target items are strings.
* @prefix: the last prefix passed to g_completion_complete() or
* g_completion_complete_utf8().
* @cache: the list of items which begin with @prefix.
* @strncmp_func: The function to use when comparing strings. Use
* g_completion_set_compare() to modify this function.
*
* The data structure used for automatic completion.
**/
/**
* GCompletionFunc:
* @Param1: the completion item.
* @Returns: the string corresponding to the item.
*
* Specifies the type of the function passed to g_completion_new(). It
* should return the string corresponding to the given target item.
* This is used when you use data structures as #GCompletion items.
**/
/**
* GCompletionStrncmpFunc:
* @s1: string to compare with @s2.
* @s2: string to compare with @s1.
* @n: maximal number of bytes to compare.
* @Returns: an integer less than, equal to, or greater than zero if
* the first @n bytes of @s1 is found, respectively, to be
* less than, to match, or to be greater than the first @n
* bytes of @s2.
*
* Specifies the type of the function passed to
* g_completion_set_compare(). This is used when you use strings as
* #GCompletion items.
**/
static void completion_check_cache (GCompletion* cmp, static void completion_check_cache (GCompletion* cmp,
gchar** new_prefix); gchar** new_prefix);
/**
* g_completion_new:
* @func: the function to be called to return the string representing
* an item in the #GCompletion, or %NULL if strings are going to
* be used as the #GCompletion items.
* @Returns: the new #GCompletion.
*
* Creates a new #GCompletion.
**/
GCompletion* GCompletion*
g_completion_new (GCompletionFunc func) g_completion_new (GCompletionFunc func)
{ {
@ -53,6 +126,13 @@ g_completion_new (GCompletionFunc func)
return gcomp; return gcomp;
} }
/**
* g_completion_add_items:
* @cmp: the #GCompletion.
* @items: the list of items to add.
*
* Adds items to the #GCompletion.
**/
void void
g_completion_add_items (GCompletion* cmp, g_completion_add_items (GCompletion* cmp,
GList* items) GList* items)
@ -82,6 +162,13 @@ g_completion_add_items (GCompletion* cmp,
} }
} }
/**
* g_completion_remove_items:
* @cmp: the #GCompletion.
* @items: the items to remove.
*
* Removes items from a #GCompletion.
**/
void void
g_completion_remove_items (GCompletion* cmp, g_completion_remove_items (GCompletion* cmp,
GList* items) GList* items)
@ -105,6 +192,12 @@ g_completion_remove_items (GCompletion* cmp,
} }
} }
/**
* g_completion_clear_items:
* @cmp: the #GCompletion.
*
* Removes all items from the #GCompletion.
**/
void void
g_completion_clear_items (GCompletion* cmp) g_completion_clear_items (GCompletion* cmp)
{ {
@ -213,6 +306,21 @@ g_completion_complete_utf8 (GCompletion *cmp,
return list; return list;
} }
/**
* g_completion_complete:
* @cmp: the #GCompletion.
* @prefix: the prefix string, typically typed by the user, which is
* compared with each of the items.
* @new_prefix: if non-%NULL, returns the longest prefix which is
* common to all items that matched @prefix, or %NULL if
* no items matched @prefix. This string should be freed
* when no longer needed.
* @Returns: the list of items whose strings begin with @prefix. This
* should not be changed.
*
* Attempts to complete the string @prefix using the #GCompletion
* target items.
**/
GList* GList*
g_completion_complete (GCompletion* cmp, g_completion_complete (GCompletion* cmp,
const gchar* prefix, const gchar* prefix,
@ -275,6 +383,12 @@ g_completion_complete (GCompletion* cmp,
return *prefix ? cmp->cache : cmp->items; return *prefix ? cmp->cache : cmp->items;
} }
/**
* g_completion_free:
* @cmp: the #GCompletion.
*
* Frees all memory used by the #GCompletion.
**/
void void
g_completion_free (GCompletion* cmp) g_completion_free (GCompletion* cmp)
{ {
@ -284,6 +398,14 @@ g_completion_free (GCompletion* cmp)
g_free (cmp); g_free (cmp);
} }
/**
* g_completion_set_compare:
* @cmp: a #GCompletion.
* @strncmp_func: the string comparison function.
*
* Sets the function to use for string comparisons. The default string
* comparison function is strncmp().
**/
void void
g_completion_set_compare(GCompletion *cmp, g_completion_set_compare(GCompletion *cmp,
GCompletionStrncmpFunc strncmp_func) GCompletionStrncmpFunc strncmp_func)