| <!-- ##### 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: |
| |
| <!-- ##### 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 <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. |
| |
| |