Automatic String Completion

Name

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);
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);

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

Details

struct GCompletion

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.


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);

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);

Adds items to the GCompletion.

cmp :the GCompletion.
items :the list of items to add.


g_completion_remove_items ()

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

Removes items from a GCompletion.

cmp :the GCompletion.
items :the items to remove.


g_completion_clear_items ()

void        g_completion_clear_items        (GCompletion *cmp);

Removes all items from the GCompletion.

cmp :the GCompletion.


g_completion_complete ()

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.


g_completion_free ()

void        g_completion_free               (GCompletion *cmp);

Frees all memory used by the GCompletion.

cmp :the GCompletion.