glib/docs/reference/glib/tmpl/completion.sgml

<!-- ##### 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().
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>

<!-- ##### 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().
@cache: the list of items which begin with @prefix.
@strncmp_func: 

<!-- ##### 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_set_compare ##### -->
<para>
Sets the function to use for string comparisons. The default
string comparison function is <function>strncmp()</function>.
</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.