# Welcome

This documentation will guide you through the methods available in the Button SHIM python library.

Button SHIM is a tiny Raspberry Pi add-on with 5 tactile buttons and one teeny RGB LED.

- More information - https://shop.pimoroni.com/products/button-shim
- Get the code - https://github.com/pimoroni/buttom-shim
- Get help - http://forums.pimoroni.com/c/support

# At A Glance

`buttonshim.``BUTTON_A` = 0

  Button A

`buttonshim.``BUTTON_B` = 1

  Button B

`buttonshim.``BUTTON_C` = 2

  Button C

`buttonshim.``BUTTON_D` = 3

  Button D

`buttonshim.``BUTTON_E` = 4

  Button E

`buttonshim.``NAMES` = ['A', 'B', 'C', 'D', 'E']

  Sometimes you want to print the plain text name of the button that’s triggered.

  You can use:

      buttonshim.NAMES[button_index]

  To accomplish this.

`buttonshim.``on_hold`(buttons, handler=None, hold_time=2)

`buttonshim.``on_press`(buttons, handler=None, repeat=False, repeat_time=0.5)

`buttonshim.``on_release`(buttons=None, handler=None)

`buttonshim.``set_pixel`(r, g, b)

# Set The Pixel

`buttonshim.``set_pixel`(r, g, b)

  Set the Button SHIM RGB pixel

  Display an RGB colour on the Button SHIM pixel.

  Parameters: | r – Amount of red, from 0 to 255 g – Amount of green, from 0 to 255 b – Amount of blue, from 0 to 255

  You can use HTML colours directly with hexadecimal notation in Python. EG:

      buttonshim.set_pixel(0xFF, 0x00, 0xFF)

# Handle A Button Press

`buttonshim.``on_press`(buttons, handler=None, repeat=False, repeat_time=0.5)

  Attach a press handler to one or more buttons.

  This handler is fired when you press a button.

  It will be passed two arguments, the button index and a boolean indicating whether the button has been pressed/released:

      @buttonshim.on_press(buttonshim.BUTTON_A)
      def handler(button, pressed):
          # Your code here

  Parameters: | buttons – A single button, or a list of buttons handler – Optional: a function to bind as the handler repeat – Optional: Repeat the handler if the button is held repeat_time – Optional: Time, in seconds, after which to repeat

# Handle A Button Release

`buttonshim.``on_release`(buttons=None, handler=None)

  Attach a release handler to one or more buttons.

  This handler is fired when you let go of a button.

  It will be passed two arguments, the button index and a boolean indicating whether the button has been pressed/released:

      @buttonshim.on_release(buttonshim.BUTTON_A)
      def handler(button, pressed):
          # Your code here

  Parameters: | buttons – A single button, or a list of buttons handler – Optional: a function to bind as the handler

# Handle A Button Hold

`buttonshim.``on_hold`(buttons, handler=None, hold_time=2)

  Attach a hold handler to one or more buttons.

  This handler is fired when you hold a button for hold_time seconds.

  It will be passed one argument, the button index:

      @buttonshim.on_press(buttonshim.BUTTON_A)
      def handler(button):
          # Your code here

  Parameters: | buttons – A single button, or a list of buttons handler – Optional: a function to bind as the handler hold_time – Optional: the hold time in seconds (default 2)

# Get The Name Of A Button

`buttonshim.``NAMES` = ['A', 'B', 'C', 'D', 'E']

  Sometimes you want to print the plain text name of the button that’s triggered.

  You can use:

      buttonshim.NAMES[button_index]

  To accomplish this.