.TH ARIF_CTX_CREATE 3 "Jan 02, 2023" 0.1.0 "ARIF User Manual"
.
.SH NAME
arif_ctx_create - create input context
.
.SH SYNOPSIS
.EX
.B #include <arif.h>
.PP
.B struct arif_ctx *
.B arif_ctx_create (
.BI "    struct arif_opts const *" options
.B );
.EE
.
.SH DESCRIPTION
The
.BR arif_ctx_create ()
function creates an input context with
.IR options .
Operations on separate input contexts do not affect each other.
.PP
If the input context is no longer in use, it should be destroyed with
.BR \%arif_ctx_destroy ().
.SS Options
The
.B struct arif_opts
type is defined as:
.PP
.in +4n
.EX
struct arif_opts {
    arif_cand_disp_func *disp_cand;
    int                  page_size;
};
.EE
.in
.PP
Member
.I disp_cand
is the function to generate the text to display for a given candidate.
If NULL, a default function (which prepends a bracket-enclosed index number
to the text) will be used.
.PP
Member
.I page_size
is the number of candidates per page.
.SS Candidate display function
The
.B arif_cand_disp_func
type is defined as:
.PP
.in +4n
.EX
typedef char *(arif_cand_disp_func) (
    char const *text,
    int         text_len,
    char const *comment,
    int         comment_len,
    int         idx,
    int        *display_len_ptr
);
.EE
.in
.PP
Argument
.I text
is the candidate's text to replace the original text, and
.I len
is its length in bytes.
.PP
If
.I comment
is not NULL, it contains descriptive text regarding the candidate.
Argument
.I comment_len
is its length in bytes.
.PP
Argument
.I idx
is the candidate's index for the current page, starting at 1.
.PP
The function should return a
.BR malloc ()'ed
pointer to the text to display for the candidate, and store
its length (in bytes) to
.IR display_len_ptr .
.
.SH RETURN VALUES
Returns an opaque pointer to the new input context.
On failure, returns NULL.
.
.SH COPYRIGHT
Copyright (C) 2023  CismonX <admin@cismon.net>
.PP
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.
.PP
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>.
.
.SH SEE ALSO
.BR arif_ctx_destroy (3)