GLib Reference Manual | |||
---|---|---|---|
<<< Previous Page | Home | Up | Next Page >>> |
#include <glib.h> struct 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, gchar *prefix, gchar **new_prefix); 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(). When no longer needed, the GCompletion is freed with g_completion_free().
Items in the completion can be simple strings (e.g. file names), 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.
struct GCompletion { GList* items; GCompletionFunc func; gchar* prefix; GList* cache; }; |
The data structure used for automatic completion. items is the list of target items (strings or data structures). func is the function called to get the string associated with a target item. It is NULL if the target items are strings. prefix is the last prefix passed to g_completion_complete(). cache is the list of items which begin with prefix.
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, 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. |
void g_completion_free (GCompletion *cmp); |
Frees all memory used by the GCompletion.
cmp : | the GCompletion. |