1 <!-- ##### SECTION Title ##### -->
2 Automatic String Completion
4 <!-- ##### SECTION Short_Description ##### -->
5 support for automatic completion using a group of target strings.
7 <!-- ##### SECTION Long_Description ##### -->
9 #GCompletion provides support for automatic completion of a string using
10 any group of target strings. It is typically used for file name completion
11 as is common in many Unix shells.
14 A #GCompletion is created using g_completion_new().
15 Target items are added and removed with
16 g_completion_add_items(), g_completion_remove_items() and
17 g_completion_clear_items().
18 A completion attempt is requested with g_completion_complete().
19 When no longer needed, the #GCompletion is freed with g_completion_free().
22 Items in the completion can be simple strings (e.g. file names),
23 or pointers to arbitrary data structures. If data structures are used
24 you must provide a #GCompletionFunc in g_completion_new(),
25 which retrieves the item's string from the data structure.
28 <!-- ##### SECTION See_Also ##### -->
33 <!-- ##### STRUCT GCompletion ##### -->
35 The data structure used for automatic completion.
36 <structfield>items</structfield> is the list of target items (strings
38 <structfield>func</structfield> is the function called to get the string
39 associated with a target item. It is NULL if the target items are strings.
40 <structfield>prefix</structfield> is the last prefix passed to
41 g_completion_complete().
42 <structfield>cache</structfield> is the list of items which begin with
43 <structfield>prefix</structfield>.
51 <!-- ##### FUNCTION g_completion_new ##### -->
53 Creates a new #GCompletion.
56 @func: the function to be called to return the string representing an item
57 in the #GCompletion, or NULL if strings are going to be used as the
59 @Returns: the new #GCompletion.
62 <!-- ##### USER_FUNCTION GCompletionFunc ##### -->
64 Specifies the type of the function passed to g_completion_new().
65 It should return the string corresponding to the given target item.
66 This is used when you use data structures as #GCompletion items.
69 @Param1: the completion item.
70 @Returns: the string corresponding to the item.
73 <!-- ##### FUNCTION g_completion_add_items ##### -->
75 Adds items to the #GCompletion.
78 @cmp: the #GCompletion.
79 @items: the list of items to add.
82 <!-- ##### FUNCTION g_completion_remove_items ##### -->
84 Removes items from a #GCompletion.
87 @cmp: the #GCompletion.
88 @items: the items to remove.
91 <!-- ##### FUNCTION g_completion_clear_items ##### -->
93 Removes all items from the #GCompletion.
96 @cmp: the #GCompletion.
99 <!-- ##### FUNCTION g_completion_complete ##### -->
101 Attempts to complete the string @prefix using the #GCompletion target items.
104 @cmp: the #GCompletion.
105 @prefix: the prefix string, typically typed by the user, which is compared
106 with each of the items.
107 @new_prefix: if non-NULL, returns the longest prefix which is common to all
108 items that matched @prefix, or NULL if no items matched @prefix.
109 This string should be freed when no longer needed.
110 @Returns: the list of items whose strings begin with @prefix. This should
114 <!-- ##### FUNCTION g_completion_free ##### -->
116 Frees all memory used by the #GCompletion.
119 @cmp: the #GCompletion.