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. 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.
  26 </para>
  27
  28 <!-- ##### SECTION See_Also ##### -->
  29 <para>
  30
  31 </para>
  32
  33 <!-- ##### STRUCT GCompletion ##### -->
  34 <para>
  35 The data structure used for automatic completion.
  36 <structfield>items</structfield> is the list of target items (strings
  37 or data structures).
  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>.
  44 </para>
  45
  46 @items:
  47 @func:
  48 @prefix:
  49 @cache:
  50 @strncmp_func:
  51
  52 <!-- ##### FUNCTION g_completion_new ##### -->
  53 <para>
  54 Creates a new #GCompletion.
  55 </para>
  56
  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
  59 #GCompletion items.
  60 @Returns: the new #GCompletion.
  61
  62
  63 <!-- ##### USER_FUNCTION GCompletionFunc ##### -->
  64 <para>
  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.
  68 </para>
  69
  70 @Param1: the completion item.
  71 @Returns: the string corresponding to the item.
  72
  73
  74 <!-- ##### USER_FUNCTION GCompletionStrcmpFunc ##### -->
  75 <para>
  76
  77 </para>
  78
  79 @s1:
  80 @s2:
  81 @Returns:
  82
  83
  84 <!-- ##### FUNCTION g_completion_add_items ##### -->
  85 <para>
  86 Adds items to the #GCompletion.
  87 </para>
  88
  89 @cmp: the #GCompletion.
  90 @items: the list of items to add.
  91
  92
  93 <!-- ##### FUNCTION g_completion_remove_items ##### -->
  94 <para>
  95 Removes items from a #GCompletion.
  96 </para>
  97
  98 @cmp: the #GCompletion.
  99 @items: the items to remove.
 100
 101
 102 <!-- ##### FUNCTION g_completion_clear_items ##### -->
 103 <para>
 104 Removes all items from the #GCompletion.
 105 </para>
 106
 107 @cmp: the #GCompletion.
 108
 109
 110 <!-- ##### FUNCTION g_completion_complete ##### -->
 111 <para>
 112 Attempts to complete the string @prefix using the #GCompletion target items.
 113 </para>
 114
 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
 122 not be changed.
 123
 124
 125 <!-- ##### FUNCTION g_completion_free ##### -->
 126 <para>
 127 Frees all memory used by the #GCompletion.
 128 </para>
 129
 130 @cmp: the #GCompletion.
 131
 132