|
libxkbcommon 1.7.0
|
Data Structures | |
| struct | rxkb_context |
| struct | rxkb_model |
| struct | rxkb_layout |
| struct | rxkb_option_group |
| struct | rxkb_option |
| struct | rxkb_iso639_code |
| struct | rxkb_iso3166_code |
Enumerations | |
| enum | rxkb_popularity { RXKB_POPULARITY_STANDARD = 1 , RXKB_POPULARITY_EXOTIC } |
| enum | rxkb_context_flags { RXKB_CONTEXT_NO_FLAGS = 0 , RXKB_CONTEXT_NO_DEFAULT_INCLUDES = (1 << 0) , RXKB_CONTEXT_LOAD_EXOTIC_RULES = (1 << 1) , RXKB_CONTEXT_NO_SECURE_GETENV = (1 << 2) } |
| enum | rxkb_log_level { RXKB_LOG_LEVEL_CRITICAL = 10 , RXKB_LOG_LEVEL_ERROR = 20 , RXKB_LOG_LEVEL_WARNING = 30 , RXKB_LOG_LEVEL_INFO = 40 , RXKB_LOG_LEVEL_DEBUG = 50 } |
The libxkbregistry API to query for available rules, models, layouts, variants and options (RMLVO). libxkbregistry is a separate library to libxkbcommon.
This library is the replacement for clients currently parsing evdev.xml directly. The library is intended to provide easy access to the set of possible MLVO configurations for a given ruleset. It is not a library to apply these configurations, merely to enumerate them. The intended users of this library are the configuration UIs that allow a user to select their keyboard layout of choice.
| enum rxkb_popularity |
Describes the popularity of an item.
Historically, some highly specialized or experimental definitions are excluded from the default list and shipped in separate files. If these extra definitions are loaded (see RXKB_CONTEXT_LOAD_EXOTIC_RULES), the popularity of the item is set accordingly.
If the exotic items are not loaded, all items will have the standard popularity.
| enum rxkb_context_flags |
Flags for context creation.
| Enumerator | |
|---|---|
| RXKB_CONTEXT_NO_DEFAULT_INCLUDES | Skip the default include paths. This requires the caller to call rxkb_context_include_path_append() or rxkb_context_include_path_append_default(). |
| RXKB_CONTEXT_LOAD_EXOTIC_RULES | Load the extra items that are considered too exotic for the default list. For historical reasons, xkeyboard-config ships those exotic rules in a separate file (e.g. |
| RXKB_CONTEXT_NO_SECURE_GETENV | Disable the use of secure_getenv for this context, so that privileged processes can use environment variables. Client uses at their own risk.
|
| enum rxkb_log_level |
| struct rxkb_context * rxkb_context_new | ( | enum rxkb_context_flags | flags | ) |
Create a new xkb registry context.
The context has an initial refcount of 1. Use rxkb_context_unref() to release memory associated with this context.
Creating a context does not parse the files yet, use rxkb_context_parse().
| flags | Flags affecting context behavior |
| void rxkb_context_set_log_level | ( | struct rxkb_context * | ctx, |
| enum rxkb_log_level | level ) |
Set the current logging level.
| ctx | The context in which to set the logging level. |
| level | The logging level to use. Only messages from this level and below will be logged. |
The default level is RXKB_LOG_LEVEL_ERROR. The environment variable RXKB_LOG_LEVEL, if set at the time the context was created, overrides the default value. It may be specified as a level number or name.
| void rxkb_context_set_log_fn | ( | struct rxkb_context * | ctx, |
| void(*)(struct rxkb_context *ctx, enum rxkb_log_level level, const char *format, va_list args) | log_fn ) |
Set a custom function to handle logging messages.
| ctx | The context in which to use the set logging function. |
| log_fn | The function that will be called for logging messages. Passing NULL restores the default function, which logs to stderr. |
By default, log messages from this library are printed to stderr. This function allows you to replace the default behavior with a custom handler. The handler is only called with messages which match the current logging level and verbosity settings for the context. level is the logging level of the message. format and args are the same as in the vprintf(3) function.
You may use rxkb_context_set_user_data() on the context, and then call rxkb_context_get_user_data() from within the logging function to provide it with additional private context.
| bool rxkb_context_parse | ( | struct rxkb_context * | ctx, |
| const char * | ruleset ) |
Parse the given ruleset.
This can only be called once per context and once parsed the data in the context is considered constant and will never change.
This function parses all files with the given ruleset name. See rxkb_context_include_path_append() for details.
If this function returns false, libxkbregistry failed to parse the xml files. This is usually caused by invalid files on the host and should be debugged by the host's administrator using external tools. Callers should reduce the include paths to known good paths and/or fall back to a default RMLVO set.
If this function returns false, the context should be be considered dead and must be released with rxkb_context_unref().
| ctx | The xkb registry context |
| ruleset | The ruleset to parse, e.g. "evdev" |
| bool rxkb_context_parse_default_ruleset | ( | struct rxkb_context * | ctx | ) |
Parse the default ruleset as configured at build time.
See rxkb_context_parse() for details.
| struct rxkb_context * rxkb_context_ref | ( | struct rxkb_context * | ctx | ) |
Increases the refcount of this object by one and returns the object.
| ctx | The xkb registry context |
| struct rxkb_context * rxkb_context_unref | ( | struct rxkb_context * | ctx | ) |
Decreases the refcount of this object by one.
Where the refcount of an object hits zero, associated resources will be freed.
| ctx | The xkb registry context |
| void rxkb_context_set_user_data | ( | struct rxkb_context * | ctx, |
| void * | user_data ) |
Assign user-specific data.
libxkbregistry will not look at or modify the data, it will merely return the same pointer in rxkb_context_get_user_data().
| ctx | The xkb registry context |
| user_data | User-specific data pointer |
| void * rxkb_context_get_user_data | ( | struct rxkb_context * | ctx | ) |
Return the pointer passed into rxkb_context_get_user_data().
| ctx | The xkb registry context |
| bool rxkb_context_include_path_append | ( | struct rxkb_context * | ctx, |
| const char * | path ) |
Append a new entry to the context's include path.
The include path handling is optimized for the most common use-case: a set of system files that provide a complete set of MLVO and some custom MLVO provided by a user in addition to the system set.
The include paths should be given so that the least complete path is specified first and the most complete path is appended last. For example:
The above example reflects the default behavior unless RXKB_CONTEXT_NO_DEFAULT_INCLUDES is provided.
Loading of the files is in reverse order, i.e. the last path appended is loaded first - in this case the /usr/share/X11/xkb path. Any models, layouts, variants and options defined in the "evdev" ruleset are loaded into the context. Then, any RMLVO found in the "evdev" ruleset of the user's path (/home/user/.config/xkb in this example) are appended to the existing set.
Note that data from previously loaded include paths is never overwritten, only appended to. It is not not possible to change the system-provided data, only to append new models, layouts, variants and options to it.
In other words, to define a new variant of the "us" layout called "banana", the following XML is sufficient.
* <xkbConfigRegistry version="1.1"> * <layoutList> * <layout> * <configItem> * <name>us</name> * </configItem> * <variantList> * <variant> * <configItem> * <name>banana</name> * <description>English (Banana)</description> * </configItem> * </variant> * </layout> * </layoutList> * </xkbConfigRegistry> *
The list of models, options and all other layouts (including "us" and its variants) is taken from the system files. The resulting list of layouts will thus have a "us" keyboard layout with the variant "banana" and all other system-provided variants (dvorak, colemak, intl, etc.)
This function must be called before rxkb_context_parse() or rxkb_context_parse_default_ruleset().
| bool rxkb_context_include_path_append_default | ( | struct rxkb_context * | ctx | ) |
Append the default include paths to the context's include path.
See rxkb_context_include_path_append() for details about the merge order.
This function must be called before rxkb_context_parse() or rxkb_context_parse_default_ruleset().
| struct rxkb_model * rxkb_model_first | ( | struct rxkb_context * | ctx | ) |
Return the first model for this context.
Use this to start iterating over the models, followed by calls to rxkb_model_next(). Models are not sorted.
The refcount of the returned model is not increased. Use rxkb_model_ref() if you need to keep this struct outside the immediate scope.
| struct rxkb_model * rxkb_model_next | ( | struct rxkb_model * | m | ) |
Return the next model for this context.
Returns NULL when no more models are available.
The refcount of the returned model is not increased. Use rxkb_model_ref() if you need to keep this struct outside the immediate scope.
| struct rxkb_model * rxkb_model_ref | ( | struct rxkb_model * | m | ) |
Increase the refcount of the argument by one.
| struct rxkb_model * rxkb_model_unref | ( | struct rxkb_model * | m | ) |
Decrease the refcount of the argument by one.
When the refcount hits zero, all memory associated with this struct is freed.
| const char * rxkb_model_get_name | ( | struct rxkb_model * | m | ) |
Return the name of this model.
This is the value for M in RMLVO, to be used with libxkbcommon.
| const char * rxkb_model_get_description | ( | struct rxkb_model * | m | ) |
Return a human-readable description of this model.
This function may return NULL.
| const char * rxkb_model_get_vendor | ( | struct rxkb_model * | m | ) |
Return the vendor name for this model.
This function may return NULL.
| struct rxkb_layout * rxkb_layout_first | ( | struct rxkb_context * | ctx | ) |
Return the first layout for this context.
Use this to start iterating over the layouts, followed by calls to rxkb_layout_next(). Layouts are not sorted.
The refcount of the returned layout is not increased. Use rxkb_layout_ref() if you need to keep this struct outside the immediate scope.
| struct rxkb_layout * rxkb_layout_next | ( | struct rxkb_layout * | l | ) |
Return the next layout for this context.
Returns NULL when no more layouts are available.
The refcount of the returned layout is not increased. Use rxkb_layout_ref() if you need to keep this struct outside the immediate scope.
| struct rxkb_layout * rxkb_layout_ref | ( | struct rxkb_layout * | l | ) |
Increase the refcount of the argument by one.
| struct rxkb_layout * rxkb_layout_unref | ( | struct rxkb_layout * | l | ) |
Decrease the refcount of the argument by one.
When the refcount hits zero, all memory associated with this struct is freed.
| const char * rxkb_layout_get_name | ( | struct rxkb_layout * | l | ) |
Return the name of this layout.
This is the value for L in RMLVO, to be used with libxkbcommon.
| const char * rxkb_layout_get_variant | ( | struct rxkb_layout * | l | ) |
Return the variant of this layout.
This is the value for V in RMLVO, to be used with libxkbcommon.
A variant does not stand on its own, it always depends on the base layout. e.g. there may be multiple variants called "intl" but there is only one "us(intl)".
Where the variant is NULL, the layout is the base layout (e.g. "us").
| const char * rxkb_layout_get_brief | ( | struct rxkb_layout * | l | ) |
Return a short (one-word) description of this layout.
This function may return NULL.
| const char * rxkb_layout_get_description | ( | struct rxkb_layout * | l | ) |
Return a human-readable description of this layout.
This function may return NULL.
| struct rxkb_option_group * rxkb_option_group_first | ( | struct rxkb_context * | ctx | ) |
Return the first option group for this context.
Use this to start iterating over the option groups, followed by calls to rxkb_option_group_next(). Option groups are not sorted.
The refcount of the returned option group is not increased. Use rxkb_option_group_ref() if you need to keep this struct outside the immediate scope.
| struct rxkb_option_group * rxkb_option_group_next | ( | struct rxkb_option_group * | g | ) |
Return the next option group for this context.
Returns NULL when no more option groups are available.
The refcount of the returned option group is not increased. Use rxkb_option_group_ref() if you need to keep this struct outside the immediate scope.
| struct rxkb_option_group * rxkb_option_group_ref | ( | struct rxkb_option_group * | g | ) |
Increase the refcount of the argument by one.
| struct rxkb_option_group * rxkb_option_group_unref | ( | struct rxkb_option_group * | g | ) |
Decrease the refcount of the argument by one.
When the refcount hits zero, all memory associated with this struct is freed.
| const char * rxkb_option_group_get_name | ( | struct rxkb_option_group * | m | ) |
Return the name of this option group.
This is not the value for O in RMLVO, the name can be used for internal sorting in the caller. This function may return NULL.
| const char * rxkb_option_group_get_description | ( | struct rxkb_option_group * | m | ) |
Return a human-readable description of this option group.
This function may return NULL.
| bool rxkb_option_group_allows_multiple | ( | struct rxkb_option_group * | g | ) |
| struct rxkb_option * rxkb_option_first | ( | struct rxkb_option_group * | group | ) |
Return the first option for this option group.
Use this to start iterating over the options, followed by calls to rxkb_option_next(). Options are not sorted.
The refcount of the returned option is not increased. Use rxkb_option_ref() if you need to keep this struct outside the immediate scope.
| struct rxkb_option * rxkb_option_next | ( | struct rxkb_option * | o | ) |
Return the next option for this option group.
Returns NULL when no more options are available.
The refcount of the returned options is not increased. Use rxkb_option_ref() if you need to keep this struct outside the immediate scope.
| struct rxkb_option * rxkb_option_ref | ( | struct rxkb_option * | o | ) |
Increase the refcount of the argument by one.
| struct rxkb_option * rxkb_option_unref | ( | struct rxkb_option * | o | ) |
Decrease the refcount of the argument by one.
When the refcount hits zero, all memory associated with this struct is freed.
| const char * rxkb_option_get_name | ( | struct rxkb_option * | o | ) |
Return the name of this option.
This is the value for O in RMLVO, to be used with libxkbcommon.
| const char * rxkb_option_get_brief | ( | struct rxkb_option * | o | ) |
Return a short (one-word) description of this option.
This function may return NULL.
| const char * rxkb_option_get_description | ( | struct rxkb_option * | o | ) |
Return a human-readable description of this option.
This function may return NULL.
| struct rxkb_iso639_code * rxkb_iso639_code_ref | ( | struct rxkb_iso639_code * | iso639 | ) |
Increase the refcount of the argument by one.
| struct rxkb_iso639_code * rxkb_iso639_code_unref | ( | struct rxkb_iso639_code * | iso639 | ) |
Decrease the refcount of the argument by one.
When the refcount hits zero, all memory associated with this struct is freed.
| const char * rxkb_iso639_code_get_code | ( | struct rxkb_iso639_code * | iso639 | ) |
Return the ISO 639-3 code for this code (e.g.
"eng", "fra").
| struct rxkb_iso639_code * rxkb_layout_get_iso639_first | ( | struct rxkb_layout * | layout | ) |
Return the first ISO 639 for this layout.
Use this to start iterating over the codes, followed by calls to rxkb_iso639_code_next(). Codes are not sorted.
The refcount of the returned code is not increased. Use rxkb_iso639_code_ref() if you need to keep this struct outside the immediate scope.
| struct rxkb_iso639_code * rxkb_iso639_code_next | ( | struct rxkb_iso639_code * | iso639 | ) |
Return the next code in the list.
Returns NULL when no more codes are available.
The refcount of the returned codes is not increased. Use rxkb_iso639_code_ref() if you need to keep this struct outside the immediate scope.
| struct rxkb_iso3166_code * rxkb_iso3166_code_ref | ( | struct rxkb_iso3166_code * | iso3166 | ) |
Increase the refcount of the argument by one.
| struct rxkb_iso3166_code * rxkb_iso3166_code_unref | ( | struct rxkb_iso3166_code * | iso3166 | ) |
Decrease the refcount of the argument by one.
When the refcount hits zero, all memory associated with this struct is freed.
| const char * rxkb_iso3166_code_get_code | ( | struct rxkb_iso3166_code * | iso3166 | ) |
Return the ISO 3166 Alpha 2 code for this code (e.g.
"US", "FR").
| struct rxkb_iso3166_code * rxkb_layout_get_iso3166_first | ( | struct rxkb_layout * | layout | ) |
Return the first ISO 3166 for this layout.
Use this to start iterating over the codes, followed by calls to rxkb_iso3166_code_next(). Codes are not sorted.
The refcount of the returned code is not increased. Use rxkb_iso3166_code_ref() if you need to keep this struct outside the immediate scope.
| struct rxkb_iso3166_code * rxkb_iso3166_code_next | ( | struct rxkb_iso3166_code * | iso3166 | ) |
Return the next code in the list.
Returns NULL when no more codes are available.
The refcount of the returned codes is not increased. Use rxkb_iso3166_code_ref() if you need to keep this struct outside the immediate scope.
1.10.0