106 lines
2.3 KiB
Groff
106 lines
2.3 KiB
Groff
.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)
|