docs/reference/glib/tmpl/completion.sgml

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