A profile on a device consists of a set of button functions and, where applicable, a range of resolution settings, one of which is currently active. More...
Data Structures | |
struct | ratbag_profile |
A handle to a profile context on devices with the RATBAG_DEVICE_CAP_SWITCHABLE_PROFILE capability. More... | |
Functions | |
struct ratbag_profile * | ratbag_profile_ref (struct ratbag_profile *profile) |
Add a reference to the profile. More... | |
struct ratbag_profile * | ratbag_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_profile * | ratbag_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_resolution * | ratbag_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_button * | ratbag_profile_get_button (struct ratbag_profile *profile, unsigned int index) |
Return a reference to the button given by the index. More... | |
Detailed Description
A profile on a device consists of a set of button functions and, where applicable, a range of resolution settings, one of which is currently active.
Function Documentation
§ ratbag_device_get_profile()
struct ratbag_profile* ratbag_device_get_profile | ( | struct ratbag_device * | device, |
unsigned int | index | ||
) |
This function creates if necessary and returns a profile for the given index.
The index must be less than the number returned by ratbag_get_num_profiles().
The profile is refcounted with an initial value of at least 1. Use ratbag_profile_unref() to release the profile.
- Parameters
-
device A previously initialized ratbag device index The index of the profile
- Returns
- The profile at the given index, or NULL if the profile does not exist.
- See also
- ratbag_get_num_profiles
§ ratbag_profile_get_button()
struct ratbag_button* ratbag_profile_get_button | ( | struct ratbag_profile * | profile, |
unsigned int | index | ||
) |
Return a reference to the button given by the index.
The order of the buttons is device-specific though indices 0, 1 and 2 should always refer to left, middle, right buttons. Use ratbag_button_get_type() to get the physical type of the button.
The button is refcounted with an initial value of at least 1. Use ratbag_button_unref() to release the button.
- Parameters
-
profile A previously initialized ratbag profile index The index of the button
- Returns
- A button context, or NULL if the button does not exist.
- See also
- ratbag_device_get_num_buttons
§ ratbag_profile_get_num_resolutions()
unsigned int ratbag_profile_get_num_resolutions | ( | struct ratbag_profile * | profile | ) |
Get the number of ratbag_resolution available in this profile.
A resolution mode is a tuple of (resolution, report rate), each mode can be fetched with ratbag_profile_get_resolution_by_idx().
The returned value is the maximum number of modes available and thus identical for all profiles. However, some of the modes may not be configured.
- Parameters
-
profile A previously initialized ratbag profile
- Returns
- The number of profiles available.
§ ratbag_profile_get_resolution()
struct ratbag_resolution* ratbag_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.
The index must be between 0 and ratbag_profile_get_num_resolution_modes().
See ratbag_profile_get_num_resolution_modes() for a description of resolution_modes.
Profiles available but not currently configured on the device return success but set dpi and hz to 0.
The returned struct has a refcount of at least 1, use ratbag_resolution_unref() to release the resources associated.
- Parameters
-
profile A previously initialized ratbag profile idx The index of the resolution mode to get
- Returns
- zero on success, non-zero otherwise. On error, dpi and hz are unmodified.
§ ratbag_profile_get_user_data()
void* ratbag_profile_get_user_data | ( | const struct ratbag_profile * | profile | ) |
Get the caller-specific data associated with this profile, if any.
- Parameters
-
profile A previously initialized ratbag profile
- Returns
- The caller-specific data previously assigned in ratbag_profile_set_user_data().
§ ratbag_profile_is_active()
int ratbag_profile_is_active | ( | struct ratbag_profile * | profile | ) |
Check if the given profile is the currently active one.
Note that some devices allow switching profiles with hardware buttons thus making the use of this function racy.
- Parameters
-
profile A previously initialized ratbag profile
- Returns
- non-zero if the profile is currently active, zero otherwise
§ ratbag_profile_ref()
struct ratbag_profile* ratbag_profile_ref | ( | struct ratbag_profile * | profile | ) |
Add a reference to the profile.
A profile is destroyed whenever the reference count reaches 0. See ratbag_profile_unref.
- Parameters
-
profile A previously initialized valid ratbag profile
- Returns
- The passed ratbag profile
§ ratbag_profile_set_active()
enum ratbag_error_code ratbag_profile_set_active | ( | struct ratbag_profile * | profile | ) |
Make the given profile the currently active profile.
- Parameters
-
profile The profile to make the active profile.
- Returns
- 0 on success or an error code otherwise
§ ratbag_profile_set_user_data()
void ratbag_profile_set_user_data | ( | struct ratbag_profile * | profile, |
void * | userdata | ||
) |
Set caller-specific data associated with this profile.
libratbag does not manage, look at, or modify this data. The caller must ensure the data is valid.
- Parameters
-
profile A previously initialized profile userdata Caller-specific data passed to the various callback interfaces.
§ ratbag_profile_unref()
struct ratbag_profile* ratbag_profile_unref | ( | struct ratbag_profile * | profile | ) |
Dereference the ratbag profile.
When the internal refcount reaches zero, all resources associated with this object are released. The object must be considered invalid once unref is called.
- Parameters
-
profile A previously initialized ratbag profile
- Returns
- Always NULL