NAME

arif_query - query for candidates

SYNOPSYS

#include <arif/arif.h>

int
arif_query (
    struct arif_ctx *ctx,
    char const      *line,
    int              offset,
    int              len
);

DESCRIPTION

The arif_query() function queries the input method engine associated with input context ctx for candidates to replace the given input text line. Candidates can be later obtained using the arif_fetch() function.

The actual text to query for candidates starts at offset byte offset, and has a length of len bytes. The IME may look at the text before offset, so it should be valid (instead of garbage data).

The caller is free to modify or deallocate line after the arif_query() call, as the function keeps its copy inside ctx.

If the text referred to by line and len is empty, or identical to the previous text, this function has no effect.

Trailing digits

If the input text contains trailing ASCII digits, the function removes them (by modifying len) before sending the text to IME. Meanwhile, if the remaining text is identical to the text from the last query, the aforementioned digits are converted into an integer and then used as an index to select a candidate from the current page.

When a candidate is selected, candidates from the previous query are replaced by a single candidate page containing only the selected candidate. If the integer cannot be used to select a valid candidate, it is ignored.

See the "Inlined candidate selection" subsection in NOTES for the rationale behind this.

RETURN VALUES

Returns the byte length of the input text after removing the trailing digits.

NOTES

Inlined candidate selection

In a typical input method framework, numeric keys are used for candidate selection. The ARIF library, however, is designed to work with line editors like GNU Readline, where numeric keys serve the same purpose as alphabet keys.

In an arif_query() function call, a candidate selection request can be inlined into the input text. This approach works well with Readline's completion API, and eliminates the need to hack the keymap.

COPYRIGHT

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.

You should have received a copy of the license along with this document. If not, see <https://www.gnu.org/licenses/fdl-1.3.html>.