ARIF_SET_ENGINE(3)

📦 version 0.3.0, in alpine 3.24

🌸 ARIF_SET_ENGINE(3) 🌸

okay bestie, welcome to the arif_set_engine page from the ARIF User Manual 💖 this is the function that swaps out an input context’s input method engine — like a full outfit change, but for your IME. let’s get into it.

✨ NAME ✨

arif_set_engine — set input method engine. periodt.

💅 SYNOPSIS 💅

#include <arif.h>

void
arif_set_engine (
    struct arif_ctx          *ctx,
    struct arif_engine const *engine,
    void                     *engine_data
);

🌟 DESCRIPTION 🌟

The arif_set_engine() function changes the input context ctx’s current input method engine and its associated data pointer to engine and engine_data. It also resets the internal state of ctx. so yes, it’s giving full refresh energy for ctx ✨

Passing NULL to engine is allowed. See the "Input context without engine" subsection in NOTES for details.

🧚 Input method engines

The struct arif_engine type defines a few functions for ARIF to communicate with an input method engine.

struct arif_engine {
    arif_engine_init_func     *init;
    arif_engine_finalize_func *finalize;
    arif_engine_info_func     *info;
    arif_engine_query_func    *query;
};

Only the query function is used by the ARIF library. It’s up to the library user to call the other functions when needed. no cap 🫶

🌱 Engine initialization

If an input method engine needs to be initialized before use, the init function must be implemented. Otherwise, it should be NULL.

typedef int (arif_engine_init_func) (
    void const  *args,
    void       **engine_data_ptr
);

Extra info can be passed into the initializer function through args.

If initialization is successful, the function must return 0. Optionally, it can store a pointer to engine_data_ptr, which will be passed as an argument on subsequent engine function calls.

If initialization fails, the function must return a non-zero value. bestie, that’s the vibe check: 0 means slay, non-zero means nope 💀

🦋 Engine finalization

If not NULL, the finalize function is used for cleaning up resources for an engine, when the engine is no longer in use.

typedef void (arif_engine_finalize_func) (
    void *engine_data
);

The engine_data argument is the pointer stored to engine_data_ptr during initialization.

⭐ Engine info

If not NULL, the info function is used for retrieving information of an engine.

typedef void (arif_engine_info_func) (
    void        *engine_data,
    char const **name_ptr,
    char const **description_ptr
);

The engine_data argument is the pointer stored to engine_data_ptr during initialization.

The function can store a NUL-terminated string that identifies an engine to name_ptr. It’s preferably a short and memorable word (like "pinyin" and "rime").

The function can store another NUL-terminated string to description_ptr, to provide additional information of the engine, such as version, copyright notice, homepage URL, etc.

🔥 Query engine for candidates

The query function is used for asking the engine for candidates of an input text. It must not be NULL.

typedef int (arif_engine_query_func) (
    void                    *engine_data,
    char const              *line,
    int                      offset,
    int                      len,
    int                      num_candidates,
    struct arif_cand const **candidates_ptr
);

The engine_data argument is the pointer stored to engine_data_ptr during initialization.

The line, offset and len arguments correspond to the arguments of function arif_query(3) with the same name. If line is NULL, it means that the caller is asking for more candidates for the previous input text.

The num_candidates argument is the minimum number of candidates required from the engine. The engine should store the pointer of an array containing at least that many candidates to candidates_ptr, and return the number of candidates. If returning less than num_candidates, it indicates that the entire list of candidates is exhausted. The engine should ensure that the memory location referenced by those candidates are valid until the next query call with non-NULL line.

The engine is not responsible for specifying the display text for a candidate, however, it may reuse the display and display_len members to store descriptive information regarding the candidate. This information will be passed to the display function of the input context through the comment and comment_len arguments (see arif_ctx_create(3)).

Both line and candidates_ptr can be NULL, in which case the caller is indicating that a candidate at offset is selected with inlined candidate selection (see arif_query(3)), and the return value is ignored. The engine may make use of this information for purposes like analytics.

💀 NOTES 💀

🫶 Input context without engine

For an input context, when arif_set_engine() is not yet called, or last called with a NULL engine argument, the input context does not have an associated input method engine.

In such input contexts, functions other than arif_set_engine() or arif_ctx_destroy(3) must not be called. fr fr, don’t do it 🙈
Copyright (C) 2023  CismonX <admin@cismon.net>

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.

🌈 SEE ALSO 🌈

arif_ctx_create(3), arif_ctx_destroy(3), arif_fetch(3), arif_query(3)

This page is from the ARIF User Manual, version 0.1.0, dated Jan 02, 2023 — bye bestie 💖

📦 where this page comes from