buttons

The “buttons” type handles buttons mapping on device that supports it.

Buttons syntax example:

default
buttons(button1=button1; button2=button2; button3=button3; button4=button4; button5=button5; button6=dpi; layout=qwerty)
buttons(Button6=DPI)  # all other buttons will be reset to their default values

Buttons values

Buttons can be mapped to different kind of values:

  • default (to explicitly set the button to its default value)

  • Special actions,

  • Mouse buttons,

  • Multimedia keys,

  • Keyboard keys.

Special actions

  • disabled: disable this button,

  • dpi: use this button to switch between DPI presets,

  • ScrollUp (not available on all devices)

  • ScrollDown (not available on all devices)

Example:

buttons(button6=dpi; button5=disabled)

Mouse buttons

Mouse buttons can be remapped using an other mouse button.

For example, this swap the button 1 and 2 of the mouse:

buttons(button1=button2; button2=button1)

Warning

Be careful to map the button1 somewhere, else you will not be able to click! ;)

Multimedia keys

Example:

buttons(button8=PlayPause)

List of the available multimedia keys:

Keyboard keys

Keyboard keys depends on the selected layout.

Examples:

buttons(layout=QWERTY; button2=A)

Note

Due to some syntax limitation, some keys cannot be mapped used their own symbols. For example, if you want to bind ; to the third button, you will have to use an alias:

buttons(layout=QWERTY; button3=semicolon)

More examples:

buttons(layout=QWERTY; button3=semi; button4=equal)

Layouts

The layout used for mapping keyboard keys can be specified using the layout parameter:

buttons(layout=QWERTY)

Currently, the following layouts are supported:

If not specified, the QWERTY layout is used.

Device Profile

Example of a buttons value type in a device profile:

profile = {

    # ...

    "settings": {

    "buttons_mapping": {
        "label": "Buttons mapping",
        "description": "Set the mapping of the buttons",
        "cli": ["-b", "--buttons"],
        "report_type": usbhid.HID_REPORT_TYPE_OUTPUT,
        "command": [0x31, 0x00],
        "value_type": "buttons",

        "buttons": {
            "Button1": {"id": 0x01, "offset": 0x00, "default": "button1"},
            "Button2": {"id": 0x02, "offset": 0x05, "default": "button2"},
            "Button3": {"id": 0x03, "offset": 0x0A, "default": "button3"},
            "Button4": {"id": 0x04, "offset": 0x0F, "default": "button4"},
            "Button5": {"id": 0x05, "offset": 0x14, "default": "button5"},
            "Button6": {"id": 0x06, "offset": 0x19, "default": "dpi"},
        },

        "button_field_length": 5,

        "button_disable":     0x00,
        "button_keyboard":    0x51,
        "button_multimedia":  0x61,
        "button_dpi_switch":  0x30,
        "button_scroll_up":   0x31,
        "button_scroll_down": 0x32,

        "default": "buttons(button1=button1; button2=button2; button3=button3; button4=button4; button5=button5; button6=dpi; layout=qwerty)",
    },

    # ...

}

CLI

Example of CLI option generated with this handler:

-b BUTTONS_MAPPING, --buttons BUTTONS_MAPPING
                      Set the mapping of the buttons (default: buttons(button1=button1;
                      button2=button2; button3=button3; button4=button4; button5=button5;
                      button6=dpi; layout=qwerty))

Example of CLI usage:

rivalcfg --buttons="buttons(layout=qwerty; button1=button1; button6=DPI)"

Functions

rivalcfg.handlers.buttons.buttons.LAYOUTS = {'qwerty': <module 'rivalcfg.handlers.buttons.layout_qwerty' from '/home/runner/work/rivalcfg/rivalcfg/rivalcfg/handlers/buttons/layout_qwerty.py'>}

Available layouts

rivalcfg.handlers.buttons.buttons.add_cli_option(cli_parser, setting_name, setting_info)

Add the given “buttons” type setting to the given CLI arguments parser.

Parameters:
  • cli_parser (ArgumentParser) – An ArgumentParser instance.

  • setting_name (str) – The name of the setting.

  • setting_info (dict) – The information dict of the setting from the device profile.

rivalcfg.handlers.buttons.buttons.build_layout(layout)

Generates an usable layout from a layout module containing key mapping and aliases.

Parameters:

layout (module) – The layour (e.g. rivalcfg.handler.buttons.layout_qwerty)

Rtype dict:

rivalcfg.handlers.buttons.buttons.is_buttons(string, setting_info)

Checks if the regbradient expression is valid.

Parameters:
  • string (str) – The string to validate.

  • setting_info (dict) – the settings info from the mouse profile.

Return type:

(bool, str)

rivalcfg.handlers.buttons.buttons.process_value(setting_info, mapping)

Called by the rivalcfg.mouse.Mouse class when processing a “buttons” type setting.

Parameters:
  • setting_info (dict) – The information dict of the setting from the device profile.

  • mapping (str,dict) – The mapping of the mouse buttons.

Return type:

[int]