Device profiles

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_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...
 
enum ratbag_error_code ratbag_profile_set_enabled (struct ratbag_profile *profile, bool enabled)
 Enable/disable the ratbag profile. More...
 
bool ratbag_profile_is_enabled (const struct ratbag_profile *profile)
 Check whether the ratbag profile is enabled or not. 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_buttonratbag_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
deviceA previously initialized ratbag device
indexThe 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
profileA previously initialized ratbag profile
indexThe 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
profileA previously initialized ratbag profile
Returns
The number of resolutions 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
profileA previously initialized ratbag profile
idxThe 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
profileA 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
profileA previously initialized ratbag profile
Returns
non-zero if the profile is currently active, zero otherwise

◆ ratbag_profile_is_enabled()

bool ratbag_profile_is_enabled ( const struct ratbag_profile profile)

Check whether the ratbag profile is enabled or not.

For devices that don't support RATBAG_DEVICE_CAP_DISABLE_PROFILE the profile will always be set to enabled.

Parameters
profileA previously initialized ratbag profile
Returns
Whether the profile is enabled or not.

◆ 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
profileA 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
profileThe profile to make the active profile.
Returns
0 on success or an error code otherwise

◆ ratbag_profile_set_enabled()

enum ratbag_error_code ratbag_profile_set_enabled ( struct ratbag_profile profile,
bool  enabled 
)

Enable/disable the ratbag profile.

For this to work, the device must support RATBAG_DEVICE_CAP_DISABLE_PROFILE.

Parameters
profileA previously initialized ratbag profile
enabledWhether to enable or disable the 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
profileA previously initialized profile
userdataCaller-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
profileA previously initialized ratbag profile
Returns
Always NULL