Auto-complete typed user input.

Modules
	Account Names

Files
file	QuickFill.h
	QuickFill is used to auto-complete typed user entries.

Typedefs
typedef struct _QuickFill	QuickFill

Enumerations
enum	QuickFillSort { QUICKFILL_LIFO, QUICKFILL_ALPHA }

Functions
QuickFill *	gnc_get_shared_address_addr2_quickfill (QofBook *book, const char *key)
QuickFill *	gnc_get_shared_address_addr3_quickfill (QofBook *book, const char *key)
QuickFill *	gnc_get_shared_address_addr4_quickfill (QofBook *book, const char *key)
QuickFill *	gnc_get_shared_entry_desc_quickfill (QofBook *book, const char *key, gboolean use_invoices)
QuickFill *	gnc_quickfill_new (void)
void	gnc_quickfill_destroy (QuickFill *qf)
void	gnc_quickfill_purge (QuickFill *qf)
const char *	gnc_quickfill_string (QuickFill *qf)
QuickFill *	gnc_quickfill_get_char_match (QuickFill *qf, gunichar c)
QuickFill *	gnc_quickfill_get_string_match (QuickFill *qf, const char *str)
QuickFill *	gnc_quickfill_get_string_len_match (QuickFill *qf, const char *str, int len)
QuickFill *	gnc_quickfill_get_unique_len_match (QuickFill *qf, int *len)
void	gnc_quickfill_insert (QuickFill *root, const char *text, QuickFillSort sort_code)
void	gnc_quickfill_remove (QuickFill *root, const gchar *text, QuickFillSort sort_code)

Detailed Description

QuickFill is meant to be used by the GUI to auto-complete (e.g. tab-complete) typed user input. QuickFill is implemented as a hierarchical tree of partial matching strings. The root of the tree contains all of the strings that user input should be matched to. Then, given a short string segment, QuickFill will return a subtree containing only those strings that start with desired substring. As additional letters are added to the substring, QuickFill will thus narrow down to the unique matching string (or to nothing if no match).

QuickFill works with national-language i18n'ed/l10n'ed multi-byte and wide-char strings, as well as plain-old C-locale strings.

Function Documentation

QuickFill* gnc_get_shared_address_addr2_quickfill	(	QofBook *	book,
		const char *	key
	)

Similar to the Account Names account name quickfill, we create a cached quickfill with the address lines of all GncAddress. Create/fetch a quickfill GncAddress description strings on the Addr2 part.

Multiple, distinct quickfills, for different uses, are allowed. Each is identified with the 'key'. Be sure to use distinct, unique keys that don't conflict with other users of QofBook.

This code listens to GncAddress creation events, and automatically adds new items to the quickfill list. This code also listens to the item deletion events and removes those entries from the quickfill; however, this does not yet seem to fully remove them from the GUI.

Parameters

book	The book
key	The identifier to look up the shared object in the book

Returns

The shared QuickFill object which is created on first calling of this function and subsequently looked up in the book by using the key.

Definition at line 177 of file gnc-addr-quickfill.c.

{
    AddressQF *qfb;

    g_assert(book);
    g_assert(key);

    qfb = qof_book_get_data (book, key);

    if (!qfb)
    {
        qfb = build_shared_quickfill(book, key);
    }

    return qfb->qf_addr2;
}

QuickFill* gnc_get_shared_address_addr3_quickfill	(	QofBook *	book,
		const char *	key
	)

Create/fetch a quickfill GncAddress description strings on the Addr3 part.

Identical to gnc_get_shared_address_addr2_quickfill(). You should also use the same key as for the other function because the internal quickfills are updated simultaneously.

Definition at line 194 of file gnc-addr-quickfill.c.

{
    AddressQF *qfb;

    g_assert(book);
    g_assert(key);

    qfb = qof_book_get_data (book, key);

    if (!qfb)
    {
        qfb = build_shared_quickfill(book, key);
    }

    return qfb->qf_addr3;
}

QuickFill* gnc_get_shared_address_addr4_quickfill	(	QofBook *	book,
		const char *	key
	)

Create/fetch a quickfill GncAddress description strings on the Addr4 part.

Identical to gnc_get_shared_address_addr2_quickfill(). You should also use the same key as for the other function because the internal quickfills are updated simultaneously.

Definition at line 211 of file gnc-addr-quickfill.c.

{
    AddressQF *qfb;

    g_assert(book);
    g_assert(key);

    qfb = qof_book_get_data (book, key);

    if (!qfb)
    {
        qfb = build_shared_quickfill(book, key);
    }

    return qfb->qf_addr4;
}

QuickFill* gnc_get_shared_entry_desc_quickfill	(	QofBook *	book,
		const char *	key,
		gboolean	use_invoices
	)

Similar to the Account Names account name quickfill, we create a cached quickfill with the description of all entries. Create/fetch a quickfill GncEntry description strings.

Multiple, distinct quickfills, for different uses, are allowed. Each is identified with the 'key'. Be sure to use distinct, unique keys that don't conflict with other users of QofBook.

This code listens to entry creation events, and automatically adds new entry's descriptions to the quickfill list. This code also listens to the entry's deletion events and removes those descriptions from the quickfill; however, this does not yet seem to fully remove them from the GUI.

Parameters

book	The book
key	The identifier to look up the shared object in the book
use_invoices	If TRUE, this quickfill considers only the entries from GncInvoice objects. If FALSE, this quickfill considers only the entries from bills/expense vouchers. Watch out: This parameter must be identical each time the same key is used for lookup, or otherwise an assertion will fail.

Returns

The shared QuickFill object which is created on first calling of this function and subsequently looked up in the book by using the key.

Definition at line 150 of file gnc-entry-quickfill.c.

{
    EntryQF *qfb;

    g_assert(book);
    g_assert(key);

    qfb = qof_book_get_data (book, key);

    if (!qfb)
    {
        qfb = build_shared_quickfill(book, key, use_invoices);
    }

    g_assert(use_invoices == qfb->using_invoices);
    return qfb->qf;
}

QuickFill* gnc_quickfill_get_char_match	(	QuickFill *	qf,
		gunichar	c
	)

Return the subnode of the tree whose strings all hold 'wc' as the next letter. That is, if 'qf' holds all strings starting with the letter 'a', and we ask for the letter 'b', then this routine will return the node holding all strings that start with "ab".

The best-guess matching string can be retrieved with gnc_quickfill_string().

Definition at line 135 of file QuickFill.c.

{
    guint key = g_unichar_toupper (uc);

    if (NULL == qf) return NULL;

    DEBUG ("xaccGetQuickFill(): index = %u\n", key);

    return g_hash_table_lookup (qf->matches, GUINT_TO_POINTER (key));
}

QuickFill* gnc_quickfill_get_string_len_match	(	QuickFill *	qf,
		const char *	str,
		int	len
	)

Same as gnc_quickfill_get_string_match(), except that the string length is explicitly specified.

Definition at line 150 of file QuickFill.c.

{
    const char *c;
    gunichar uc;

    if (NULL == qf) return NULL;
    if (NULL == str) return NULL;

    c = str;
    while (*c && (len > 0))
    {
        if (qf == NULL)
            return NULL;

        uc = g_utf8_get_char (c);
        qf = gnc_quickfill_get_char_match (qf, uc);

        c = g_utf8_next_char (c);
        len--;
    }

    return qf;
}

QuickFill* gnc_quickfill_get_string_match	(	QuickFill *	qf,
		const char *	str
	)

Return a subnode in the tree whose strings all match the string 'str' as the next substring. Thus, for example, if the argument 'qf' holds strings that start with "abc", and this routine is called with "def", then the returned node will hold strings that start with "abcdef".

The best-guess matching string can be retrieved with gnc_quickfill_string().

To convert a plain C-locale char * string to GdkWChar *, use the gnc_mbstowcs() routine.

Definition at line 179 of file QuickFill.c.

{
    if (NULL == qf) return NULL;
    if (NULL == str) return NULL;

    return gnc_quickfill_get_string_len_match (qf, str, g_utf8_strlen (str, -1));
}

QuickFill* gnc_quickfill_get_unique_len_match	(	QuickFill *	qf,
		int *	len
	)

Walk a 'unique' part of the QuickFill tree. This routine is typically used to assist in the tab-completion of strings. If the initial portion of the string is unique, but some later portion is not, this routine will advance to the first non-unique part of the string. If len is non-NULL, then *len will be set to the length of the unique portion of the string.

Thus, for example, if the root node contains the strings "The Book" and "The Movie", then the returned len will be 4, and the returned node will distinguish "Book" and "Movie". Thus, for example, gnc_quickfill_get_char_match(.., 'B') on the result will identify "The Book".

Definition at line 199 of file QuickFill.c.

{
    if (length != NULL)
        *length = 0;

    if (qf == NULL)
        return NULL;

    while (1)
    {
        guint count;

        count = g_hash_table_size (qf->matches);

        if (count != 1)
            break;

        g_hash_table_foreach (qf->matches, unique_len_helper, &qf);

        if (length != NULL)
            (*length)++;
    }

    return qf;
}

void gnc_quickfill_insert	(	QuickFill *	root,
		const char *	text,
		QuickFillSort	sort_code
	)

Add the string "text" to the collection of searchable strings.

Definition at line 229 of file QuickFill.c.

{
    gchar *normalized_str;

    if (NULL == qf) return;
    if (NULL == text) return;


    normalized_str = g_utf8_normalize (text, -1, G_NORMALIZE_NFC);
    quickfill_insert_recursive (qf, normalized_str, 0, sort);
    g_free (normalized_str);
}

const char* gnc_quickfill_string

(

QuickFill *

qf

)

For the given node 'qf', return the best-guess matching string.

Definition at line 123 of file QuickFill.c.

{
    if (qf == NULL)
        return NULL;

    return qf->text;
}