libratbag.h File Reference
#include <stdlib.h>
#include <stdarg.h>
#include <libudev.h>
Include dependency graph for libratbag.h:

Go to the source code of this file.

Data Structures

struct  ratbag_interface
 libratbag does not open file descriptors to devices directly, instead open_restricted() and close_restricted() are called for each path that must be opened. More...
 

Macros

#define LIBRATBAG_ATTRIBUTE_PRINTF(_format, _args)
 
#define LIBRATBAG_ATTRIBUTE_DEPRECATED
 

Typedefs

typedef void(* ratbag_log_handler) (struct ratbag *ratbag, enum ratbag_log_priority priority, const char *format, va_list args) LIBRATBAG_ATTRIBUTE_PRINTF(3
 Log handler type for custom logging. More...
 
typedef void(*) voi ratbag_log_set_priority) (struct ratbag *ratbag, enum ratbag_log_priority priority)
 Set the log priority for the ratbag context. More...
 

Enumerations

enum  ratbag_error_code {
  RATBAG_SUCCESS, RATBAG_ERROR_DEVICE, RATBAG_ERROR_CAPABILITY, RATBAG_ERROR_VALUE,
  RATBAG_ERROR_SYSTEM, RATBAG_ERROR_IMPLEMENTATION
}
 Error codes used by libratbag. More...
 
enum  ratbag_log_priority { RATBAG_LOG_PRIORITY_RAW, RATBAG_LOG_PRIORITY_DEBUG, RATBAG_LOG_PRIORITY_INFO, RATBAG_LOG_PRIORITY_ERROR }
 Log priority for internal logging messages. More...
 
enum  ratbag_device_capability {
  RATBAG_DEVICE_CAP_NONE, RATBAG_DEVICE_CAP_SWITCHABLE_RESOLUTION, RATBAG_DEVICE_CAP_SWITCHABLE_PROFILE, RATBAG_DEVICE_CAP_BUTTON_KEY,
  RATBAG_DEVICE_CAP_BUTTON_MACROS, RATBAG_DEVICE_CAP_DEFAULT_PROFILE, RATBAG_DEVICE_CAP_QUERY_CONFIGURATION
}
 
enum  ratbag_resolution_capability { RATBAG_RESOLUTION_CAP_INDIVIDUAL_REPORT_RATE, RATBAG_RESOLUTION_CAP_SEPARATE_XY_RESOLUTION }
 
enum  ratbag_button_type {
  RATBAG_BUTTON_TYPE_UNKNOWN, RATBAG_BUTTON_TYPE_LEFT, RATBAG_BUTTON_TYPE_MIDDLE, RATBAG_BUTTON_TYPE_RIGHT,
  RATBAG_BUTTON_TYPE_THUMB, RATBAG_BUTTON_TYPE_THUMB2, RATBAG_BUTTON_TYPE_THUMB3, RATBAG_BUTTON_TYPE_THUMB4,
  RATBAG_BUTTON_TYPE_WHEEL_LEFT, RATBAG_BUTTON_TYPE_WHEEL_RIGHT, RATBAG_BUTTON_TYPE_WHEEL_CLICK, RATBAG_BUTTON_TYPE_WHEEL_UP,
  RATBAG_BUTTON_TYPE_WHEEL_DOWN, RATBAG_BUTTON_TYPE_WHEEL_RATCHET_MODE_SHIFT, RATBAG_BUTTON_TYPE_EXTRA, RATBAG_BUTTON_TYPE_SIDE,
  RATBAG_BUTTON_TYPE_PINKIE, RATBAG_BUTTON_TYPE_PINKIE2, RATBAG_BUTTON_TYPE_RESOLUTION_CYCLE_UP, RATBAG_BUTTON_TYPE_RESOLUTION_UP,
  RATBAG_BUTTON_TYPE_RESOLUTION_DOWN, RATBAG_BUTTON_TYPE_PROFILE_CYCLE_UP, RATBAG_BUTTON_TYPE_PROFILE_UP, RATBAG_BUTTON_TYPE_PROFILE_DOWN
}
 Button types describing the physical button. More...
 
enum  ratbag_button_action_type {
  RATBAG_BUTTON_ACTION_TYPE_UNKNOWN, RATBAG_BUTTON_ACTION_TYPE_NONE, RATBAG_BUTTON_ACTION_TYPE_BUTTON, RATBAG_BUTTON_ACTION_TYPE_SPECIAL,
  RATBAG_BUTTON_ACTION_TYPE_KEY, RATBAG_BUTTON_ACTION_TYPE_MACRO
}
 The type assigned to a button. More...
 
enum  ratbag_button_action_special {
  RATBAG_BUTTON_ACTION_SPECIAL_INVALID, RATBAG_BUTTON_ACTION_SPECIAL_UNKNOWN, RATBAG_BUTTON_ACTION_SPECIAL_DOUBLECLICK, RATBAG_BUTTON_ACTION_SPECIAL_WHEEL_LEFT,
  RATBAG_BUTTON_ACTION_SPECIAL_WHEEL_RIGHT, RATBAG_BUTTON_ACTION_SPECIAL_WHEEL_UP, RATBAG_BUTTON_ACTION_SPECIAL_WHEEL_DOWN, RATBAG_BUTTON_ACTION_SPECIAL_RATCHET_MODE_SWITCH,
  RATBAG_BUTTON_ACTION_SPECIAL_RESOLUTION_CYCLE_UP, RATBAG_BUTTON_ACTION_SPECIAL_RESOLUTION_UP, RATBAG_BUTTON_ACTION_SPECIAL_RESOLUTION_DOWN, RATBAG_BUTTON_ACTION_SPECIAL_RESOLUTION_ALTERNATE,
  RATBAG_BUTTON_ACTION_SPECIAL_RESOLUTION_DEFAULT, RATBAG_BUTTON_ACTION_SPECIAL_PROFILE_CYCLE_UP, RATBAG_BUTTON_ACTION_SPECIAL_PROFILE_UP, RATBAG_BUTTON_ACTION_SPECIAL_PROFILE_DOWN,
  RATBAG_BUTTON_ACTION_SPECIAL_SECOND_MODE, RATBAG_BUTTON_ACTION_SPECIAL_BATTERY_LEVEL
}
 
enum  ratbag_macro_event_type {
  RATBAG_MACRO_EVENT_INVALID, RATBAG_MACRO_EVENT_NONE, RATBAG_MACRO_EVENT_KEY_PRESSED, RATBAG_MACRO_EVENT_KEY_RELEASED,
  RATBAG_MACRO_EVENT_WAIT
}
 Macro event types describing the event. More...
 

Functions

enum ratbag_log_priority ratbag_log_get_priority (const struct ratbag *ratbag)
 Get the context's log priority. More...
 
void ratbag_log_set_handler (struct ratbag *ratbag, ratbag_log_handler log_handler)
 Set the context's log handler. More...
 
struct ratbagratbag_create_context (const struct ratbag_interface *interface, void *userdata)
 Create a new ratbag context. More...
 
void ratbag_set_user_data (struct ratbag *ratbag, void *userdata)
 Set caller-specific data associated with this context. More...
 
void * ratbag_get_user_data (const struct ratbag *ratbag)
 Get the caller-specific data associated with this context, if any. More...
 
struct ratbagratbag_ref (struct ratbag *ratbag)
 Add a reference to the context. More...
 
struct ratbagratbag_unref (struct ratbag *ratbag)
 Dereference the ratbag context. More...
 
enum ratbag_error_code ratbag_device_new_from_udev_device (struct ratbag *ratbag, struct udev_device *udev_device, struct ratbag_device **device)
 Create a new ratbag context from the given udev device. More...
 
struct ratbag_deviceratbag_device_ref (struct ratbag_device *device)
 Add a reference to the device. More...
 
struct ratbag_deviceratbag_device_unref (struct ratbag_device *device)
 Dereference the ratbag device. More...
 
void ratbag_device_set_user_data (struct ratbag_device *device, void *userdata)
 Set caller-specific data associated with this device. More...
 
void * ratbag_device_get_user_data (const struct ratbag_device *device)
 Get the caller-specific data associated with this device, if any. More...
 
const char * ratbag_device_get_name (const struct ratbag_device *device)
 
const char * ratbag_device_get_svg_name (const struct ratbag_device *device)
 
int ratbag_device_has_capability (const struct ratbag_device *device, enum ratbag_device_capability cap)
 Note that a device may not support any of the capabilities but still initialize fine otherwise. More...
 
unsigned int ratbag_device_get_num_profiles (struct ratbag_device *device)
 Return the number of profiles supported by this device. More...
 
unsigned int ratbag_device_get_num_buttons (struct ratbag_device *device)
 Return the number of buttons available on this device. More...
 
struct ratbag_profileratbag_profile_ref (struct ratbag_profile *profile)
 Add a reference to the profile. More...
 
struct ratbag_profileratbag_profile_unref (struct ratbag_profile *profile)
 Dereference the ratbag profile. More...
 
void ratbag_profile_set_user_data (struct ratbag_profile *profile, void *userdata)
 Set caller-specific data associated with this profile. More...
 
void * ratbag_profile_get_user_data (const struct ratbag_profile *profile)
 Get the caller-specific data associated with this profile, if any. More...
 
struct ratbag_profileratbag_device_get_profile (struct ratbag_device *device, unsigned int index)
 This function creates if necessary and returns a profile for the given index. More...
 
int ratbag_profile_is_active (struct ratbag_profile *profile)
 Check if the given profile is the currently active one. More...
 
enum ratbag_error_code ratbag_profile_set_active (struct ratbag_profile *profile)
 Make the given profile the currently active profile. More...
 
unsigned int ratbag_profile_get_num_resolutions (struct ratbag_profile *profile)
 Get the number of ratbag_resolution available in this profile. More...
 
struct ratbag_resolutionratbag_profile_get_resolution (struct ratbag_profile *profile, unsigned int idx)
 Return the resolution in DPI and the report rate in Hz for the resolution mode identified by the given index. More...
 
struct ratbag_resolutionratbag_resolution_ref (struct ratbag_resolution *resolution)
 Add a reference to the resolution. More...
 
struct ratbag_resolutionratbag_resolution_unref (struct ratbag_resolution *resolution)
 Dereference the ratbag resolution. More...
 
void ratbag_resolution_set_user_data (struct ratbag_resolution *resolution, void *userdata)
 Set caller-specific data associated with this resolution. More...
 
void * ratbag_resolution_get_user_data (const struct ratbag_resolution *resolution)
 Get the caller-specific data associated with this resolution, if any. More...
 
int ratbag_resolution_has_capability (struct ratbag_resolution *resolution, enum ratbag_resolution_capability cap)
 Check if a resolution has a specific capability. More...
 
enum ratbag_error_code ratbag_resolution_set_dpi (struct ratbag_resolution *resolution, unsigned int dpi)
 Set the resolution in DPI for the resolution mode. More...
 
enum ratbag_error_code ratbag_resolution_set_dpi_xy (struct ratbag_resolution *resolution, unsigned int x, unsigned int y)
 Set the x and y resolution in DPI for the resolution mode. More...
 
int ratbag_resolution_get_dpi (struct ratbag_resolution *resolution)
 Get the resolution in DPI for the resolution mode. More...
 
int ratbag_resolution_get_dpi_x (struct ratbag_resolution *resolution)
 Get the x resolution in DPI for the resolution mode. More...
 
int ratbag_resolution_get_dpi_y (struct ratbag_resolution *resolution)
 Get the y resolution in DPI for the resolution mode. More...
 
enum ratbag_error_code ratbag_resolution_set_report_rate (struct ratbag_resolution *resolution, unsigned int hz)
 Set the the report rate in Hz for the resolution mode. More...
 
int ratbag_resolution_get_report_rate (struct ratbag_resolution *resolution)
 Get the the report rate in Hz for the resolution mode. More...
 
enum ratbag_error_code ratbag_resolution_set_active (struct ratbag_resolution *resolution)
 Activate the given resolution mode. More...
 
int ratbag_resolution_is_active (const struct ratbag_resolution *resolution)
 Check if the resolution mode is the currently active one. More...
 
enum ratbag_error_code ratbag_resolution_set_default (struct ratbag_resolution *resolution)
 Set the default resolution mode for the associated profile. More...
 
int ratbag_resolution_is_default (const struct ratbag_resolution *resolution)
 Check if the resolution mode is the default one in this profile. More...
 
struct ratbag_buttonratbag_profile_get_button (struct ratbag_profile *profile, unsigned int index)
 Return a reference to the button given by the index. More...
 
void ratbag_button_set_user_data (struct ratbag_button *button, void *userdata)
 Set caller-specific data associated with this button. More...
 
void * ratbag_button_get_user_data (const struct ratbag_button *button)
 Get the caller-specific data associated with this button, if any. More...
 
enum ratbag_button_type ratbag_button_get_type (struct ratbag_button *button)
 Return the type of the physical button. More...
 
enum ratbag_button_action_type ratbag_button_get_action_type (struct ratbag_button *button)
 
int ratbag_button_has_action_type (struct ratbag_button *button, enum ratbag_button_action_type action_type)
 Check if a button supports a specific action type. More...
 
unsigned int ratbag_button_get_button (struct ratbag_button *button)
 If a button's action is RATBAG_BUTTON_ACTION_TYPE_BUTTON, this function returns the logical button number this button is mapped to, starting at 1. More...
 
enum ratbag_error_code ratbag_button_set_button (struct ratbag_button *button, unsigned int btn)
 See ratbag_button_get_button() for a description of the button number. More...
 
enum ratbag_button_action_special ratbag_button_get_special (struct ratbag_button *button)
 If a button's action is RATBAG_BUTTON_ACTION_TYPE_SPECIAL, this function returns the special function assigned to this button. More...
 
enum ratbag_error_code ratbag_button_set_special (struct ratbag_button *button, enum ratbag_button_action_special action)
 This function sets the special function assigned to this button. More...
 
unsigned int ratbag_button_get_key (struct ratbag_button *button, unsigned int *modifiers, size_t *sz)
 If a button's action is RATBAG_BUTTON_ACTION_TYPE_KEY, this function returns the key or button configured for this button. More...
 
enum ratbag_error_code ratbag_button_set_key (struct ratbag_button *button, unsigned int key, unsigned int *modifiers, size_t sz)
 
enum ratbag_error_code ratbag_button_disable (struct ratbag_button *button)
 
const char * ratbag_button_macro_get_name (struct ratbag_button_macro *macro)
 
unsigned int ratbag_button_macro_get_num_events (struct ratbag_button_macro *macro)
 
enum ratbag_macro_event_type ratbag_button_macro_get_event_type (struct ratbag_button_macro *macro, unsigned int index)
 Returns the macro event type configured for the event at the given index. More...
 
int ratbag_button_macro_get_event_key (struct ratbag_button_macro *macro, unsigned int index)
 If the event stored at the given index is RATBAG_MACRO_EVENT_KEY_PRESSED or RATBAG_MACRO_EVENT_KEY_RELEASED, this function returns the key code configured for the event at the given index. More...
 
int ratbag_button_macro_get_event_timeout (struct ratbag_button_macro *macro, unsigned int index)
 If the event stored at the given index is RATBAG_MACRO_EVENT_WAIT, this function returns the timeout configured for the event at the given index. More...
 
enum ratbag_error_code ratbag_button_set_macro (struct ratbag_button *button, const struct ratbag_button_macro *macro)
 Sets the button's action to RATBAG_BUTTON_ACTION_TYPE_MACRO and assigns the given macro to this button. More...
 
struct ratbag_button_macro * ratbag_button_macro_new (const char *name)
 Initialize a new button macro. More...
 
struct ratbag_button_macro * ratbag_button_get_macro (struct ratbag_button *button)
 If a button's action is RATBAG_BUTTON_ACTION_TYPE_MACRO, this function returns the current button macro. More...
 
enum ratbag_error_code ratbag_button_macro_set_event (struct ratbag_button_macro *macro, unsigned int index, enum ratbag_macro_event_type type, unsigned int data)
 Sets the macro's event at the given index to the given type with the key code or timeout given. More...
 
struct ratbag_button_macro * ratbag_button_macro_ref (struct ratbag_button_macro *macro)
 Add a reference to the macro. More...
 
struct ratbag_button_macro * ratbag_button_macro_unref (struct ratbag_button_macro *macro)
 Dereference the ratbag button macro. More...
 
struct ratbag_buttonratbag_button_ref (struct ratbag_button *button)
 Add a reference to the button. More...
 
struct ratbag_buttonratbag_button_unref (struct ratbag_button *button)
 Dereference the ratbag button. More...
 

Macro Definition Documentation

§ LIBRATBAG_ATTRIBUTE_DEPRECATED

#define LIBRATBAG_ATTRIBUTE_DEPRECATED

§ LIBRATBAG_ATTRIBUTE_PRINTF

#define LIBRATBAG_ATTRIBUTE_PRINTF (   _format,
  _args 
)

Enumeration Type Documentation

§ ratbag_resolution_capability

Enumerator
RATBAG_RESOLUTION_CAP_INDIVIDUAL_REPORT_RATE 

The report rate can be set per resolution mode.

If this property is not available, all resolutions within the same profile have the same report rate and changing one changes the others.

RATBAG_RESOLUTION_CAP_SEPARATE_XY_RESOLUTION 

The resolution can be set for x and y separately.