completion.sgml

GLib是GTK+和GNOME工程的基础底层核心程序库

<refentry id="glib-Automatic-String-Completion">
<refmeta>
<refentrytitle>Automatic String Completion</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GLIB Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Automatic String Completion</refname><refpurpose>support for automatic completion using a group of target strings.</refpurpose>
</refnamediv>

<refsynopsisdiv><title>Synopsis</title>
<synopsis>

#include &lt;glib.h&gt;


struct      <link linkend="GCompletion">GCompletion</link>;
<link linkend="GCompletion">GCompletion</link>* <link linkend="g-completion-new">g_completion_new</link>               (<link linkend="GCompletionFunc">GCompletionFunc</link> func);
<link linkend="gchar">gchar</link>*      (<link linkend="GCompletionFunc">*GCompletionFunc</link>)              (<link linkend="gpointer">gpointer</link>);
void        <link linkend="g-completion-add-items">g_completion_add_items</link>          (<link linkend="GCompletion">GCompletion</link> *cmp,
                                             <link linkend="GList">GList</link> *items);
void        <link linkend="g-completion-remove-items">g_completion_remove_items</link>       (<link linkend="GCompletion">GCompletion</link> *cmp,
                                             <link linkend="GList">GList</link> *items);
void        <link linkend="g-completion-clear-items">g_completion_clear_items</link>        (<link linkend="GCompletion">GCompletion</link> *cmp);
<link linkend="GList">GList</link>*      <link linkend="g-completion-complete">g_completion_complete</link>           (<link linkend="GCompletion">GCompletion</link> *cmp,
                                             <link linkend="gchar">gchar</link> *prefix,
                                             <link linkend="gchar">gchar</link> **new_prefix);
void        <link linkend="g-completion-set-compare">g_completion_set_compare</link>        (<link linkend="GCompletion">GCompletion</link> *cmp,
                                             <link linkend="GCompletionStrncmpFunc">GCompletionStrncmpFunc</link> strncmp_func);
<link linkend="gint">gint</link>        (<link linkend="GCompletionStrncmpFunc">*GCompletionStrncmpFunc</link>)       (const <link linkend="gchar">gchar</link> *s1,
                                             const <link linkend="gchar">gchar</link> *s2,
                                             <link linkend="gsize">gsize</link> n);
void        <link linkend="g-completion-free">g_completion_free</link>               (<link linkend="GCompletion">GCompletion</link> *cmp);
</synopsis>
</refsynopsisdiv>





<refsect1>
<title>Description</title>
<para>
<link linkend="GCompletion">GCompletion</link> provides support for automatic completion of a string using
any group of target strings. It is typically used for file name completion
as is common in many UNIX shells.
</para>
<para>
A <link linkend="GCompletion">GCompletion</link> is created using <link linkend="g-completion-new">g_completion_new</link>().
Target items are added and removed with
<link linkend="g-completion-add-items">g_completion_add_items</link>(), <link linkend="g-completion-remove-items">g_completion_remove_items</link>() and
<link linkend="g-completion-clear-items">g_completion_clear_items</link>().
A completion attempt is requested with <link linkend="g-completion-complete">g_completion_complete</link>().
When no longer needed, the <link linkend="GCompletion">GCompletion</link> is freed with <link linkend="g-completion-free">g_completion_free</link>().
</para>
<para>
Items in the completion can be simple strings (e.g. filenames),
or pointers to arbitrary data structures. If data structures are used
you must provide a <link linkend="GCompletionFunc">GCompletionFunc</link> in <link linkend="g-completion-new">g_completion_new</link>(),
which retrieves the item's string from the data structure.
You can change the way in which strings are compared by setting
a different <link linkend="GCompletionStrncmpFunc">GCompletionStrncmpFunc</link> in <link linkend="g-completion-set-compare">g_completion_set_compare</link>().
</para>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="GCompletion">struct GCompletion</title>
<programlisting>struct GCompletion
{
  GList* items;
  GCompletionFunc func;
 
  gchar* prefix;
  GList* cache;
  GCompletionStrncmpFunc strncmp_func;
};
</programlisting>
<para>
The data structure used for automatic completion.
</para><informaltable pgwide="1" frame="none" role="struct">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row>
<entry><link linkend="GList">GList</link> *<structfield>items</structfield></entry>
<entry>list of target items (strings or data structures).
</entry>
</row>
<row>
<entry><link linkend="GCompletionFunc">GCompletionFunc</link> <structfield>func</structfield></entry>
<entry>function which is called to get the string associated with a target 
  item. It is <literal>NULL</literal> if the target items are strings.
</entry>
</row>
<row>
<entry><link linkend="gchar">gchar</link> *<structfield>prefix</structfield></entry>
<entry>the last prefix passed to <link linkend="g-completion-complete">g_completion_complete</link>().
</entry>
</row>
<row>
<entry><link linkend="GList">GList</link> *<structfield>cache</structfield></entry>
<entry>the list of items which begin with <parameter>prefix</parameter>.
</entry>
</row>
<row>
<entry><link linkend="GCompletionStrncmpFunc">GCompletionStrncmpFunc</link> <structfield>strncmp_func</structfield></entry>
<entry>

</entry>
</row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-completion-new">g_completion_new ()</title>
<programlisting><link linkend="GCompletion">GCompletion</link>* g_completion_new               (<link linkend="GCompletionFunc">GCompletionFunc</link> func);</programlisting>
<para>
Creates a new <link linkend="GCompletion">GCompletion</link>.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>func</parameter>&nbsp;:</entry>
<entry>the function to be called to return the string representing an item
in the <link linkend="GCompletion">GCompletion</link>, or <literal>NULL</literal> if strings are going to be used as the
<link linkend="GCompletion">GCompletion</link> items.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the new <link linkend="GCompletion">GCompletion</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="GCompletionFunc">GCompletionFunc ()</title>
<programlisting><link linkend="gchar">gchar</link>*      (*GCompletionFunc)              (<link linkend="gpointer">gpointer</link>);</programlisting>
<para>
Specifies the type of the function passed to <link linkend="g-completion-new">g_completion_new</link>().
It should return the string corresponding to the given target item.
This is used when you use data structures as <link linkend="GCompletion">GCompletion</link> items.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>Param1</parameter>&nbsp;:</entry>
<entry>the completion item.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the string corresponding to the item.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-completion-add-items">g_completion_add_items ()</title>
<programlisting>void        g_completion_add_items          (<link linkend="GCompletion">GCompletion</link> *cmp,
                                             <link linkend="GList">GList</link> *items);</programlisting>
<para>
Adds items to the <link linkend="GCompletion">GCompletion</link>.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>cmp</parameter>&nbsp;:</entry>
<entry>the <link linkend="GCompletion">GCompletion</link>.
</entry></row>
<row><entry align="right"><parameter>items</parameter>&nbsp;:</entry>
<entry>the list of items to add.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-completion-remove-items">g_completion_remove_items ()</title>
<programlisting>void        g_completion_remove_items       (<link linkend="GCompletion">GCompletion</link> *cmp,
                                             <link linkend="GList">GList</link> *items);</programlisting>
<para>
Removes items from a <link linkend="GCompletion">GCompletion</link>.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>cmp</parameter>&nbsp;:</entry>
<entry>the <link linkend="GCompletion">GCompletion</link>.
</entry></row>
<row><entry align="right"><parameter>items</parameter>&nbsp;:</entry>
<entry>the items to remove.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-completion-clear-items">g_completion_clear_items ()</title>
<programlisting>void        g_completion_clear_items        (<link linkend="GCompletion">GCompletion</link> *cmp);</programlisting>
<para>
Removes all items from the <link linkend="GCompletion">GCompletion</link>.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>cmp</parameter>&nbsp;:</entry>
<entry>the <link linkend="GCompletion">GCompletion</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-completion-complete">g_completion_complete ()</title>
<programlisting><link linkend="GList">GList</link>*      g_completion_complete           (<link linkend="GCompletion">GCompletion</link> *cmp,
                                             <link linkend="gchar">gchar</link> *prefix,
                                             <link linkend="gchar">gchar</link> **new_prefix);</programlisting>
<para>
Attempts to complete the string <parameter>prefix</parameter> using the <link linkend="GCompletion">GCompletion</link> target items.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>cmp</parameter>&nbsp;:</entry>
<entry>the <link linkend="GCompletion">GCompletion</link>.
</entry></row>
<row><entry align="right"><parameter>prefix</parameter>&nbsp;:</entry>
<entry>the prefix string, typically typed by the user, which is compared
with each of the items.
</entry></row>
<row><entry align="right"><parameter>new_prefix</parameter>&nbsp;:</entry>
<entry>if non-<literal>NULL</literal>, returns the longest prefix which is common to all
items that matched <parameter>prefix</parameter>, or <literal>NULL</literal> if no items matched <parameter>prefix</parameter>.
This string should be freed when no longer needed.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the list of items whose strings begin with <parameter>prefix</parameter>. This should
not be changed.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-completion-set-compare">g_completion_set_compare ()</title>
<programlisting>void        g_completion_set_compare        (<link linkend="GCompletion">GCompletion</link> *cmp,
                                             <link linkend="GCompletionStrncmpFunc">GCompletionStrncmpFunc</link> strncmp_func);</programlisting>
<para>
Sets the function to use for string comparisons. The default
string comparison function is <function><link linkend="strncmp">strncmp</link>()</function>.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>cmp</parameter>&nbsp;:</entry>
<entry>a <link linkend="GCompletion">GCompletion</link>.
</entry></row>
<row><entry align="right"><parameter>strncmp_func</parameter>&nbsp;:</entry>
<entry>the string comparison function.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="GCompletionStrncmpFunc">GCompletionStrncmpFunc ()</title>
<programlisting><link linkend="gint">gint</link>        (*GCompletionStrncmpFunc)       (const <link linkend="gchar">gchar</link> *s1,
                                             const <link linkend="gchar">gchar</link> *s2,
                                             <link linkend="gsize">gsize</link> n);</programlisting>
<para>
Specifies the type of the function passed to <link linkend="g-completion-set-compare">g_completion_set_compare</link>().
This is used when you use strings as <link linkend="GCompletion">GCompletion</link> items.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>s1</parameter>&nbsp;:</entry>
<entry>string to compare with <parameter>s2</parameter>.
</entry></row>
<row><entry align="right"><parameter>s2</parameter>&nbsp;:</entry>
<entry>string to compare with <parameter>s1</parameter>.
</entry></row>
<row><entry align="right"><parameter>n</parameter>&nbsp;:</entry>
<entry>maximal number of bytes to compare.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>an integer less than, equal to, or greater than zero if the 
first <parameter>n</parameter> bytes of <parameter>s1</parameter> is found, respectively, to be less than, to match, 
or to be greater than the first <parameter>n</parameter> bytes of <parameter>s2</parameter>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-completion-free">g_completion_free ()</title>
<programlisting>void        g_completion_free               (<link linkend="GCompletion">GCompletion</link> *cmp);</programlisting>
<para>
Frees all memory used by the <link linkend="GCompletion">GCompletion</link>.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>cmp</parameter>&nbsp;:</entry>
<entry>the <link linkend="GCompletion">GCompletion</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>

</refsect1>




</refentry>