| 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 NULL if the target items are strings. |
| gchar *prefix; | the last prefix passed to g_completion_complete() or g_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 NULL if 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 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. |
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 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. |
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 n bytes of s1 is found, respectively, to be less than, to match, or to be greater than the first n bytes of s2. |
void g_completion_free (GCompletion *cmp);
Frees all memory used by the GCompletion.
| cmp : | the GCompletion. |
| << Lexical Scanner | Timers >> |