Automatic String Completion

Automatic String Completion — support for automatic completion using a group of target strings

Synopsis

#include <glib.h>

struct              GCompletion;
GCompletion *       g_completion_new                    (GCompletionFunc func);
gchar *             (*GCompletionFunc)                  (gpointer Param1);
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);

Description

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().

GCompletion has been marked as deprecated, since this API is rarely used and not very actively maintained.

Details

struct GCompletion

struct GCompletion {
  GList* items;
  GCompletionFunc func;
 
  gchar* prefix;
  GList* cache;
  GCompletionStrncmpFunc strncmp_func;
};

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.

g_completion_new ()

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.

GCompletionFunc ()

gchar *             (*GCompletionFunc)                  (gpointer Param1);

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.

g_completion_add_items ()

void                g_completion_add_items              (GCompletion *cmp,
                                                         GList *items);

Warning

g_completion_add_items has been deprecated since version 2.26 and should not be used in newly-written code. Rarely used API

Adds items to the GCompletion.

cmp :

 the GCompletion.

items :

 the list of items to add. [transfer none]

g_completion_remove_items ()

void                g_completion_remove_items           (GCompletion *cmp,
                                                         GList *items);

Warning

g_completion_remove_items has been deprecated since version 2.26 and should not be used in newly-written code. Rarely used API

Removes items from a GCompletion. The items are not freed, so if the memory was dynamically allocated, free items with g_list_free_full() after calling this function.

cmp :

 the GCompletion.

items :

 the items to remove. [transfer none]

g_completion_clear_items ()

void                g_completion_clear_items            (GCompletion *cmp);

Warning

g_completion_clear_items has been deprecated since version 2.26 and should not be used in newly-written code. Rarely used API

Removes all items from the GCompletion. The items are not freed, so if the memory was dynamically allocated, it should be freed after calling this function.

cmp :

 the GCompletion.

g_completion_complete ()

GList *             g_completion_complete               (GCompletion *cmp,
                                                         const gchar *prefix,
                                                         gchar **new_prefix);

Warning

g_completion_complete has been deprecated since version 2.26 and should not be used in newly-written code. Rarely used API

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. [transfer none]

g_completion_complete_utf8 ()

GList *             g_completion_complete_utf8          (GCompletion *cmp,
                                                         const gchar *prefix,
                                                         gchar **new_prefix);

Warning

g_completion_complete_utf8 has been deprecated since version 2.26 and should not be used in newly-written code. Rarely used API

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. [element-type utf8][transfer none]

Since 2.4

g_completion_set_compare ()

void                g_completion_set_compare            (GCompletion *cmp,
                                                         GCompletionStrncmpFunc strncmp_func);

Warning

g_completion_set_compare has been deprecated since version 2.26 and should not be used in newly-written code. Rarely used API

Sets the function to use for string comparisons. The default string comparison function is strncmp().

cmp :

 a GCompletion.

strncmp_func :

 the string comparison function.

GCompletionStrncmpFunc ()

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.

g_completion_free ()

void                g_completion_free                   (GCompletion *cmp);

Warning

g_completion_free has been deprecated since version 2.26 and should not be used in newly-written code. Rarely used API

Frees all memory used by the GCompletion. The items are not freed, so if the memory was dynamically allocated, it should be freed after calling this function.

cmp :

 the GCompletion.
Generated by GTK-Doc V1.18.1