|  |  |  | GLib Reference Manual |  | 
|---|
| Automatic String CompletionAutomatic String Completion — support for automatic completion using a group of target strings. | 
#include <glib.h>
            GCompletion;
GCompletion* g_completion_new               (GCompletionFunc func);
gchar*      (*GCompletionFunc)              (gpointer);
void        g_completion_add_items          (GCompletion *cmp,
                                             GList *items);
void        g_completion_remove_items       (GCompletion *cmp,
                                             GList *items);
void        g_completion_clear_items        (GCompletion *cmp);
GList*      g_completion_complete           (GCompletion *cmp,
                                             const gchar *prefix,
                                             gchar **new_prefix);
GList*      g_completion_complete_utf8      (GCompletion *cmp,
                                             const gchar *prefix,
                                             gchar **new_prefix);
void        g_completion_set_compare        (GCompletion *cmp,
                                             GCompletionStrncmpFunc strncmp_func);
gint        (*GCompletionStrncmpFunc)       (const gchar *s1,
                                             const gchar *s2,
                                             gsize n);
void        g_completion_free               (GCompletion *cmp);
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().
typedef struct {
  GList* items;
  GCompletionFunc func;
 
  gchar* prefix;
  GList* cache;
  GCompletionStrncmpFunc strncmp_func;
} GCompletion;
The data structure used for automatic completion.
| GList * items; | list of target items (strings or data structures). | 
| GCompletionFunc func; | function which is called to get the string associated with a target 
  item. It is NULLif the target items are strings. | 
| gchar * prefix; | the last prefix passed to g_completion_complete()org_completion_complete_utf8(). | 
| GList * cache; | the list of items which begin with prefix. | 
| GCompletionStrncmpFunc strncmp_func; | 
GCompletion* g_completion_new (GCompletionFunc func);
Creates a new GCompletion.
| func: | the function to be called to return the string representing an item
in the GCompletion, or NULLif strings are going to be used as the
GCompletion items. | 
| Returns : | the new GCompletion. | 
gchar* (*GCompletionFunc) (gpointer);
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.
| Param1: | the completion item. | 
| Returns : | the string corresponding to the item. | 
void g_completion_add_items (GCompletion *cmp, GList *items);
Adds items to the GCompletion.
| cmp: | the GCompletion. | 
| items: | the list of items to add. | 
void g_completion_remove_items (GCompletion *cmp, GList *items);
Removes items from a GCompletion.
| cmp: | the GCompletion. | 
| items: | the items to remove. | 
void g_completion_clear_items (GCompletion *cmp);
Removes all items from the GCompletion.
| cmp: | the GCompletion. | 
GList* g_completion_complete (GCompletion *cmp, const gchar *prefix, gchar **new_prefix);
Attempts to complete the string prefix using the GCompletion target items.
| 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 matchedprefix, orNULLif no items matchedprefix.
This string should be freed when no longer needed. | 
| Returns : | the list of items whose strings begin with prefix. This should
not be changed. | 
GList* g_completion_complete_utf8 (GCompletion *cmp, const gchar *prefix, gchar **new_prefix);
Attempts to complete the string prefix using the GCompletion target items.
In contrast to g_completion_complete(), this function returns the largest common
prefix that is a valid UTF-8 string, omitting a possible common partial 
character.
You should use this function instead of g_completion_complete() if your 
items are UTF-8 strings.
| cmp: | the GCompletion | 
| prefix: | the prefix string, typically used 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 matchedprefix, orNULLif no items matchedprefix.
   This string should be freed when no longer needed. | 
| Returns : | the list of items whose strings begin with prefix. This should
not be changed. | 
Since 2.4
void g_completion_set_compare (GCompletion *cmp, GCompletionStrncmpFunc strncmp_func);
Sets the function to use for string comparisons. The default
string comparison function is strncmp()
| cmp: | a GCompletion. | 
| strncmp_func: | the string comparison function. | 
gint (*GCompletionStrncmpFunc) (const gchar *s1, const gchar *s2, gsize n);
Specifies the type of the function passed to g_completion_set_compare().
This is used when you use strings as GCompletion items.
| 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 nbytes ofs1is found, respectively, to be less than, to match, 
or to be greater than the firstnbytes ofs2. | 
void g_completion_free (GCompletion *cmp);
Frees all memory used by the GCompletion.
| cmp: | the GCompletion. | 
| << Lexical Scanner | Timers >> |