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>.
52 <!-- ##### FUNCTION g_completion_new ##### -->
54 Creates a new #GCompletion.
57 @func: the function to be called to return the string representing an item
58 in the #GCompletion, or NULL if strings are going to be used as the
60 @Returns: the new #GCompletion.
63 <!-- ##### USER_FUNCTION GCompletionFunc ##### -->
65 Specifies the type of the function passed to g_completion_new().
66 It should return the string corresponding to the given target item.
67 This is used when you use data structures as #GCompletion items.
70 @Param1: the completion item.
71 @Returns: the string corresponding to the item.
74 <!-- ##### USER_FUNCTION GCompletionStrcmpFunc ##### -->
84 <!-- ##### FUNCTION g_completion_add_items ##### -->
86 Adds items to the #GCompletion.
89 @cmp: the #GCompletion.
90 @items: the list of items to add.
93 <!-- ##### FUNCTION g_completion_remove_items ##### -->
95 Removes items from a #GCompletion.
98 @cmp: the #GCompletion.
99 @items: the items to remove.
102 <!-- ##### FUNCTION g_completion_clear_items ##### -->
104 Removes all items from the #GCompletion.
107 @cmp: the #GCompletion.
110 <!-- ##### FUNCTION g_completion_complete ##### -->
112 Attempts to complete the string @prefix using the #GCompletion target items.
115 @cmp: the #GCompletion.
116 @prefix: the prefix string, typically typed by the user, which is compared
117 with each of the items.
118 @new_prefix: if non-NULL, returns the longest prefix which is common to all
119 items that matched @prefix, or NULL if no items matched @prefix.
120 This string should be freed when no longer needed.
121 @Returns: the list of items whose strings begin with @prefix. This should
125 <!-- ##### FUNCTION g_completion_free ##### -->
127 Frees all memory used by the #GCompletion.
130 @cmp: the #GCompletion.