|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-D8D30C70-C6ED-4E4C-9815-BF7993262ABF" xml:lang="en"><title>Using <codeph>GCompletion</codeph></title><shortdesc><codeph>GCompletion</codeph> provides a method for automatic string |
|
13 completion using a group of target strings. This is typically used for file |
|
14 name completion as is common in many UNIX shells. A possible use of such APIs |
|
15 in a mobile device application is the contacts application. For example, if |
|
16 all the names that begin with a particular prefix, say "abc", are to be displayed, |
|
17 these APIs can be used to get and display all the names that begin with "abc".</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
18 <p>A <codeph>GCompletion</codeph> is created using <codeph>g_completion_new()</codeph>. |
|
19 Target items are added using <codeph>g_completion_add_items()</codeph>. This |
|
20 API takes a doubly-linked list item, <codeph>GList</codeph>, as a parameter. |
|
21 Items are removed using <codeph>g_completion_clear_items()</codeph> and <codeph>g_completion_remove_items()</codeph>. |
|
22 A completion attempt is requested using <codeph>g_completion_complete()</codeph> or <codeph>g_completion_complete_utf8()</codeph>. |
|
23 A <codeph>GCompletion</codeph> is freed using <codeph>g_completion_free()</codeph>.</p> |
|
24 <p>Generally a <codeph>GCompletion</codeph> item is a string. The default |
|
25 function used to compare a string is <codeph>strncmp()</codeph>. If a function |
|
26 other than it is desired, then it can be set using the function <codeph>g_completion_set_compare()</codeph>. |
|
27 If an arbitrary data structure is to be compared, a <codeph>GCompletionFunc</codeph> is |
|
28 to be provided to <codeph>g_completion_new()</codeph>.</p> |
|
29 <p>The following code demonstrates the usage of <codeph>GCompletion</codeph> APIs.</p> |
|
30 <p>In the code a <codeph>GCompletion</codeph> is created using <codeph>g_completion_new()</codeph>. |
|
31 Target strings are added using <codeph>g_completion_add_items()</codeph>. |
|
32 The comparison function is changed to <codeph>g_ascii_strncasecmp()</codeph> to |
|
33 allow matches without the consideration of case. A completion attempt for |
|
34 the string “aB” and the same is printed using <codeph>g_print()</codeph>. |
|
35 Finally the <codeph>GCompletion</codeph> is freed using <codeph>g_completion_free()</codeph>.</p> |
|
36 <codeblock xml:space="preserve">#include <glib.h> |
|
37 |
|
38 int main () |
|
39 { |
|
40 GCompletion *cmp; |
|
41 GList *items; |
|
42 gchar *prefix; |
|
43 |
|
44 //create a new GCompletion |
|
45 cmp = g_completion_new (NULL); |
|
46 |
|
47 //create a new GList to create a set of target strings. |
|
48 items = NULL; |
|
49 items = g_list_append (items, "AbcDEF"); |
|
50 items = g_list_append (items, "bc"); |
|
51 items = g_list_append (items, "bd"); |
|
52 |
|
53 //add the target strings |
|
54 g_completion_add_items (cmp, items); |
|
55 |
|
56 //change the comparison API to g_ascii_strncasecmp |
|
57 g_completion_set_compare(cmp,g_ascii_strncasecmp); |
|
58 |
|
59 //find the first match |
|
60 items = g_completion_complete (cmp, "aB", &prefix); |
|
61 |
|
62 g_print("The match for aB is %s",prefix); |
|
63 getchar(); |
|
64 |
|
65 g_free (prefix); |
|
66 |
|
67 g_completion_free(cmp); |
|
68 return 0; |
|
69 } |
|
70 </codeblock> |
|
71 </conbody></concept> |