GCompletion provides a method for automatic string completion using a group of target strings. This is typically used for file name completion as is common in many UNIX shells. A possible use of such APIs in a mobile device application is the contacts application. For example, if all the names that begin with a particular prefix, say "abc", are to be displayed, these APIs can be used to get and display all the names that begin with "abc".

A GCompletion is created using g_completion_new(). Target items are added using g_completion_add_items(). This API takes a doubly-linked list item, GList, as a parameter. Items are removed using g_completion_clear_items() and g_completion_remove_items(). A completion attempt is requested using g_completion_complete() or g_completion_complete_utf8(). A GCompletion is freed using g_completion_free().

Generally a GCompletion item is a string. The default function used to compare a string is strncmp(). If a function other than it is desired, then it can be set using the function g_completion_set_compare(). If an arbitrary data structure is to be compared, a GCompletionFunc is to be provided to g_completion_new().

The following code demonstrates the usage of GCompletion APIs.

In the code a GCompletion is created using g_completion_new(). Target strings are added using g_completion_add_items(). The comparison function is changed to g_ascii_strncasecmp() to allow matches without the consideration of case. A completion attempt for the string “aB” and the same is printed using g_print(). Finally the GCompletion is freed using g_completion_free().

#include <glib.h>

int main ()
{
	GCompletion *cmp;
	GList *items;
	gchar *prefix;

	//create a new GCompletion
	cmp = g_completion_new (NULL);

	//create a new GList to create a set of target strings.
	items = NULL;
	items = g_list_append (items, "AbcDEF");
	items = g_list_append (items, "bc");
	items = g_list_append (items, "bd");
			
	//add the target strings			
	g_completion_add_items (cmp, items);
	
	//change the comparison API to g_ascii_strncasecmp
	g_completion_set_compare(cmp,g_ascii_strncasecmp);
	
	//find the first match
	items = g_completion_complete (cmp, "aB", &prefix);
	
	g_print("The match for aB is %s",prefix);
	getchar();
	
	g_free (prefix);
	
	g_completion_free(cmp);
	return 0;
}

Give feedback of this section