|
|
|
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; |
The function to use when comparing strings.
Use g_completion_set_compare() to modify this function.
|
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. |