• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1<!-- ##### SECTION Title ##### -->
2Automatic String Completion
3
4<!-- ##### SECTION Short_Description ##### -->
5support for automatic completion using a group of target strings
6
7<!-- ##### SECTION Long_Description ##### -->
8<para>
9#GCompletion provides support for automatic completion of a string using
10any group of target strings. It is typically used for file name completion
11as is common in many UNIX shells.
12</para>
13<para>
14A #GCompletion is created using g_completion_new().
15Target items are added and removed with
16g_completion_add_items(), g_completion_remove_items() and
17g_completion_clear_items().
18A completion attempt is requested with g_completion_complete() or
19g_completion_complete_utf8().
20When no longer needed, the #GCompletion is freed with g_completion_free().
21</para>
22<para>
23Items in the completion can be simple strings (e.g. filenames),
24or pointers to arbitrary data structures. If data structures are used
25you must provide a #GCompletionFunc in g_completion_new(),
26which retrieves the item's string from the data structure.
27You can change the way in which strings are compared by setting
28a different #GCompletionStrncmpFunc in g_completion_set_compare().
29</para>
30
31<!-- ##### SECTION See_Also ##### -->
32<para>
33
34</para>
35
36<!-- ##### SECTION Stability_Level ##### -->
37
38
39<!-- ##### STRUCT GCompletion ##### -->
40<para>
41The data structure used for automatic completion.
42</para>
43
44@items: list of target items (strings or data structures).
45@func: function which is called to get the string associated with a target
46  item. It is %NULL if the target items are strings.
47@prefix: the last prefix passed to g_completion_complete() or
48  g_completion_complete_utf8().
49@cache: the list of items which begin with @prefix.
50@strncmp_func: The function to use when comparing strings.
51  Use g_completion_set_compare() to modify this function.
52
53<!-- ##### FUNCTION g_completion_new ##### -->
54<para>
55Creates a new #GCompletion.
56</para>
57
58@func: the function to be called to return the string representing an item
59in the #GCompletion, or %NULL if strings are going to be used as the
60#GCompletion items.
61@Returns: the new #GCompletion.
62
63
64<!-- ##### USER_FUNCTION GCompletionFunc ##### -->
65<para>
66Specifies the type of the function passed to g_completion_new().
67It should return the string corresponding to the given target item.
68This is used when you use data structures as #GCompletion items.
69</para>
70
71@Param1: the completion item.
72@Returns: the string corresponding to the item.
73
74
75<!-- ##### FUNCTION g_completion_add_items ##### -->
76<para>
77Adds items to the #GCompletion.
78</para>
79
80@cmp: the #GCompletion.
81@items: the list of items to add.
82
83
84<!-- ##### FUNCTION g_completion_remove_items ##### -->
85<para>
86Removes items from a #GCompletion.
87</para>
88
89@cmp: the #GCompletion.
90@items: the items to remove.
91
92
93<!-- ##### FUNCTION g_completion_clear_items ##### -->
94<para>
95Removes all items from the #GCompletion.
96</para>
97
98@cmp: the #GCompletion.
99
100
101<!-- ##### FUNCTION g_completion_complete ##### -->
102<para>
103Attempts to complete the string @prefix using the #GCompletion target items.
104</para>
105
106@cmp: the #GCompletion.
107@prefix: the prefix string, typically typed by the user, which is compared
108with each of the items.
109@new_prefix: if non-%NULL, returns the longest prefix which is common to all
110items that matched @prefix, or %NULL if no items matched @prefix.
111This string should be freed when no longer needed.
112@Returns: the list of items whose strings begin with @prefix. This should
113not be changed.
114
115
116<!-- ##### FUNCTION g_completion_complete_utf8 ##### -->
117<para>
118
119</para>
120
121@cmp:
122@prefix:
123@new_prefix:
124@Returns:
125
126
127<!-- ##### FUNCTION g_completion_set_compare ##### -->
128<para>
129Sets the function to use for string comparisons. The default
130string comparison function is strncmp().
131</para>
132
133@cmp: a #GCompletion.
134@strncmp_func: the string comparison function.
135
136
137<!-- ##### USER_FUNCTION GCompletionStrncmpFunc ##### -->
138<para>
139Specifies the type of the function passed to g_completion_set_compare().
140This is used when you use strings as #GCompletion items.
141</para>
142
143@s1: string to compare with @s2.
144@s2: string to compare with @s1.
145@n: maximal number of bytes to compare.
146@Returns: an integer less than, equal to, or greater than zero if the
147first @n bytes of @s1 is found, respectively, to be less than, to match,
148or to be greater than the first @n bytes of @s2.
149
150
151<!-- ##### FUNCTION g_completion_free ##### -->
152<para>
153Frees all memory used by the #GCompletion.
154</para>
155
156@cmp: the #GCompletion.
157
158
159