auto-complete typed user input.
[GUI]

---

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 heirarchical 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.

Files
file	QuickFill.h
	Quickfill is used to auto-complete typed user entries.
Modules
	Account Names
Typedefs
typedef _QuickFill	QuickFill
Enumerations
enum	QuickFillSort { QUICKFILL_LIFO, QUICKFILL_ALPHA }
Functions
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)

---

Enumeration Type Documentation

enum QuickFillSort

Enumerator:

QUICKFILL_LIFO
QUICKFILL_ALPHA

Definition at line 56 of file QuickFill.h.

{
  QUICKFILL_LIFO,
  QUICKFILL_ALPHA
} QuickFillSort;

---

Function Documentation

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 retreived with gnc_quickfill_string().

Definition at line 136 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 explicilty specified.

Definition at line 151 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 retreived with gnc_quickfill_string().

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

Definition at line 180 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 inital 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 200 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)
    {
      return qf;
    }

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

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

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 230 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 124 of file QuickFill.c.

{
  if (qf == NULL)
    return NULL;

  return qf->text;
}

---