Merge pull request #1 from brentru/cursor-control

Cursor Control!

Author: ladyada

.gitignore

@@ -0,0 +1,12 @@
+*.mpy
+.idea
+__pycache__
+_build
+*.pyc
+.env
+build*
+bundles
+*.DS_Store
+.eggs
+dist
+**/*.egg-info

.pylintrc

@@ -0,0 +1,3 @@
+python:
+    version: 3
+requirements_file: requirements.txt

.readthedocs.yml

@@ -0,0 +1,48 @@
+# This is a common .travis.yml for generating library release zip files for
+# CircuitPython library releases using circuitpython-build-tools.
+# See https://github.com/adafruit/circuitpython-build-tools for detailed setup
+# instructions.
+
+dist: xenial
+language: python
+python:
+  - "3.6"
+
+cache:
+  pip: true
+
+# TODO: if deployment to PyPi is desired, change 'DEPLOY_PYPI' to "true",
+#       or remove the env block entirely and remove the condition in the
+#       deploy block.
+env:
+  - DEPLOY_PYPI="false"
+
+deploy:
+  - provider: releases
+    api_key: "$GITHUB_TOKEN"
+    file_glob: true
+    file: "$TRAVIS_BUILD_DIR/bundles/*"
+    skip_cleanup: true
+    overwrite: true
+    on:
+      tags: true
+  # TODO: Use 'travis encrypt --com -r adafruit/<repo slug>' to generate
+  #       the encrypted password for adafruit-travis. Paste result below.
+  - provider: pypi
+    user: adafruit-travis
+    password:
+      secure: #-- PASTE ENCRYPTED PASSWORD HERE --#
+    on:
+      tags: true
+      condition: $DEPLOY_PYPI = "true"
+
+install:
+  - pip install -r requirements.txt
+  - pip install circuitpython-build-tools Sphinx sphinx-rtd-theme
+  - pip install --force-reinstall pylint==1.9.2
+
+script:
+  - pylint adafruit_cursorcontrol/*.py
+  - ([[ ! -d "examples" ]] || pylint --disable=missing-docstring,invalid-name,bad-whitespace examples/*.py)
+  - circuitpython-build-bundles --filename_prefix adafruit-circuitpython-cursorcontrol --library_location .
+  - cd docs && sphinx-build -E -W -b html . _build/html && cd ..

.travis.yml

@@ -0,0 +1,127 @@
+# Adafruit Community Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and leaders pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level or type of
+experience, education, socio-economic status, nationality, personal appearance,
+race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+We are committed to providing a friendly, safe and welcoming environment for
+all.
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Be kind and courteous to others
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Collaborating with other community members
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and sexual attention or advances
+* The use of inappropriate images, including in a community member's avatar
+* The use of inappropriate language, including in a community member's nickname
+* Any spamming, flaming, baiting or other attention-stealing behavior
+* Excessive or unwelcome helping; answering outside the scope of the question
+  asked
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate
+
+The goal of the standards and moderation guidelines outlined here is to build
+and maintain a respectful community. We ask that you don’t just aim to be
+"technically unimpeachable", but rather try to be your best self.
+
+We value many things beyond technical expertise, including collaboration and
+supporting others within our community. Providing a positive experience for
+other community members can have a much more significant impact than simply
+providing the correct answer.
+
+## Our Responsibilities
+
+Project leaders are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project leaders have the right and responsibility to remove, edit, or
+reject messages, comments, commits, code, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any community member for other behaviors that they deem
+inappropriate, threatening, offensive, or harmful.
+
+## Moderation
+
+Instances of behaviors that violate the Adafruit Community Code of Conduct
+may be reported by any member of the community. Community members are
+encouraged to report these situations, including situations they witness
+involving other community members.
+
+You may report in the following ways:
+
+In any situation, you may send an email to <support@adafruit.com>.
+
+On the Adafruit Discord, you may send an open message from any channel
+to all Community Helpers by tagging @community moderators. You may also send an
+open message from any channel, or a direct message to @kattni#1507,
+@tannewt#4653, @Dan Halbert#1614, @cater#2442, @sommersoft#0222, or
+@Andon#8175.
+
+Email and direct message reports will be kept confidential.
+
+In situations on Discord where the issue is particularly egregious, possibly
+illegal, requires immediate action, or violates the Discord terms of service,
+you should also report the message directly to Discord.
+
+These are the steps for upholding our community’s standards of conduct.
+
+1. Any member of the community may report any situation that violates the
+Adafruit Community Code of Conduct. All reports will be reviewed and
+investigated.
+2. If the behavior is an egregious violation, the community member who
+committed the violation may be banned immediately, without warning.
+3. Otherwise, moderators will first respond to such behavior with a warning.
+4. Moderators follow a soft "three strikes" policy - the community member may
+be given another chance, if they are receptive to the warning and change their
+behavior.
+5. If the community member is unreceptive or unreasonable when warned by a
+moderator, or the warning goes unheeded, they may be banned for a first or
+second offense. Repeated offenses will result in the community member being
+banned.
+
+## Scope
+
+This Code of Conduct and the enforcement policies listed above apply to all
+Adafruit Community venues. This includes but is not limited to any community
+spaces (both public and private), the entire Adafruit Discord server, and
+Adafruit GitHub repositories. Examples of Adafruit Community spaces include
+but are not limited to meet-ups, audio chats on the Adafruit Discord, or
+interaction at a conference.
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. As a community
+member, you are representing our community, and are expected to behave
+accordingly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 1.4, available at
+<https://www.contributor-covenant.org/version/1/4/code-of-conduct.html>,
+and the [Rust Code of Conduct](https://www.rust-lang.org/en-US/conduct.html).
+
+For other projects adopting the Adafruit Community Code of
+Conduct, please contact the maintainers of those projects for enforcement.
+If you wish to use this code of conduct for your own project, consider
+explicitly mentioning your moderation policy or making a copy with your
+own moderation policy so as to avoid confusion.

CODE_OF_CONDUCT.md

@@ -1,6 +1,6 @@
-MIT License
+The MIT License (MIT)
 
-Copyright (c) 2019 Adafruit Industries
+Copyright (c) 2019 Brent Rubell for Adafruit Industries
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

LICENSE

@@ -0,0 +1,116 @@
+Introduction
+============
+
+.. image:: https://readthedocs.org/projects/adafruit-circuitpython-cursorcontrol/badge/?version=latest
+    :target: https://circuitpython.readthedocs.io/projects/cursorcontrol/en/latest/
+    :alt: Documentation Status
+
+.. image:: https://img.shields.io/discord/327254708534116352.svg
+    :target: https://discord.gg/nBQh6qu
+    :alt: Discord
+
+.. image:: https://travis-ci.com/adafruit/Adafruit_CircuitPython_CursorControl.svg?branch=master
+    :target: https://travis-ci.com/adafruit/Adafruit_CircuitPython_CursorControl
+    :alt: Build Status
+
+Mouse cursor for interaction with CircuitPython UI elements such as
+`buttons <https://github.com/adafruit/Adafruit_CircuitPython_Display_Button>`_.
+
+Dependencies
+=============
+This driver depends on:
+
+* `Adafruit CircuitPython <https://github.com/adafruit/circuitpython>`_
+
+Please ensure all dependencies are available on the CircuitPython filesystem.
+This is easily achieved by downloading
+`the Adafruit library and driver bundle <https://github.com/adafruit/Adafruit_CircuitPython_Bundle>`_.
+
+Installing from PyPI
+=====================
+.. note:: This library is not available on PyPI yet. Install documentation is included
+   as a standard element. Stay tuned for PyPI availability!
+
+On supported GNU/Linux systems like the Raspberry Pi, you can install the driver locally `from
+PyPI <https://pypi.org/project/adafruit-circuitpython-cursorcontrol/>`_. To install for current user:
+
+.. code-block:: shell
+
+    pip3 install adafruit-circuitpython-cursorcontrol
+
+To install system-wide (this may be required in some cases):
+
+.. code-block:: shell
+
+    sudo pip3 install adafruit-circuitpython-cursorcontrol
+
+To install in a virtual environment in your current project:
+
+.. code-block:: shell
+
+    mkdir project-name && cd project-name
+    python3 -m venv .env
+    source .env/bin/activate
+    pip3 install adafruit-circuitpython-cursorcontrol
+
+Usage Example
+=============
+
+See examples in examples/ folder.
+
+Contributing
+============
+
+Contributions are welcome! Please read our `Code of Conduct
+<https://github.com/adafruit/Adafruit_CircuitPython_CursorControl/blob/master/CODE_OF_CONDUCT.md>`_
+before contributing to help this project stay welcoming.
+
+Building locally
+================
+
+Zip release files
+-----------------
+
+To build this library locally you'll need to install the
+`circuitpython-build-tools <https://github.com/adafruit/circuitpython-build-tools>`_ package.
+
+.. code-block:: shell
+
+    python3 -m venv .env
+    source .env/bin/activate
+    pip install circuitpython-build-tools
+
+Once installed, make sure you are in the virtual environment:
+
+.. code-block:: shell
+
+    source .env/bin/activate
+
+Then run the build:
+
+.. code-block:: shell
+
+    circuitpython-build-bundles --filename_prefix adafruit-circuitpython-cursorcontrol --library_location .
+
+Sphinx documentation
+-----------------------
+
+Sphinx is used to build the documentation based on rST files and comments in the code. First,
+install dependencies (feel free to reuse the virtual environment from above):
+
+.. code-block:: shell
+
+    python3 -m venv .env
+    source .env/bin/activate
+    pip install Sphinx sphinx-rtd-theme
+
+Now, once you have the virtual environment activated:
+
+.. code-block:: shell
+
+    cd docs
+    sphinx-build -E -W -b html . _build/html
+
+This will output the documentation to ``docs/_build/html``. Open the index.html in your browser to
+view them. It will also (due to -W) error out on any warning like Travis will. This is a good way to
+locally verify it will pass.

README.md

@@ -0,0 +1,206 @@
+# The MIT License (MIT)
+#
+# Copyright (c) 2019 Brent Rubell for Adafruit Industries
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+"""
+`adafruit_cursorcontrol`
+================================================================================
+
+Mouse cursor for interaction with CircuitPython UI elements.
+
+
+* Author(s): Brent Rubell
+
+Implementation Notes
+--------------------
+
+**Software and Dependencies:**
+
+* Adafruit CircuitPython firmware for the supported boards:
+  https://github.com/adafruit/circuitpython/releases
+
+"""
+import displayio
+
+__version__ = "0.0.0-auto.0"
+__repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_Cursor.git"
+
+class Cursor:
+    """Mouse cursor interaction for CircuitPython.
+
+    :param ~displayio.Display display: CircuitPython display object.
+    :param ~displayio.Group display_group: CircuitPython group object to append the cursor to.
+    :param int cursor_speed: Speed of the cursor, in pixels.
+    :param int scale: Scale amount for the cursor in both directions.
+    :param bool is_hidden: Cursor is hidden on init.
+
+    Example for creating a cursor layer
+
+    .. code-block:: python
+
+        from adafruit_cursorcontrol import Cursor
+        # Create the display
+        display = board.DISPLAY
+
+        # Create the display context
+        splash = displayio.Group(max_size=22)
+
+        # initialize the mouse cursor object
+        mouse_cursor = Cursor(display, display_group=splash)
+    """
+    # pylint: disable=too-many-arguments
+    def __init__(self, display=None, display_group=None, is_hidden=False, cursor_speed=5, scale=1):
+        self._display = display
+        self._scale = scale
+        self._speed = cursor_speed
+        self._is_hidden = is_hidden
+        self._display_grp = display_group
+        self._disp_sz = display.height - 1, display.width - 1
+        self.generate_cursor()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exception_type, exception_value, traceback):
+        self.deinit()
+
+    def deinit(self):
+        """deinitializes the cursor object."""
+        self._is_deinited()
+        self._scale = None
+        self._display_grp.remove(self._cursor_grp)
+
+    def _is_deinited(self):
+        """checks cursor deinitialization"""
+        if self._scale is None:
+            raise ValueError("Cursor object has been deinitialized and can no longer "
+                             "be used. Create a new cursor object.")
+
+    @property
+    def scale(self):
+        """Returns the cursor's scale amount as an integer."""
+        return self._scale
+
+    @scale.setter
+    def scale(self, scale_value):
+        """Scales the cursor by scale_value in both directions.
+        :param int scale_value: Amount to scale the cursor by.
+        """
+        self._is_deinited()
+        if scale_value > 0:
+            self._scale = scale_value
+            self._cursor_grp.scale = scale_value
+
+    @property
+    def speed(self):
+        """Returns the cursor's speed, in pixels."""
+        return self._speed
+
+    @speed.setter
+    def speed(self, speed):
+        """Sets the speed of the cursor.
+        :param int speed: Cursor movement speed, in pixels.
+        """
+        self._is_deinited()
+        if speed > 0:
+            self._speed = speed
+
+    @property
+    def x(self):
+        """Returns the cursor's x-coordinate."""
+        return self._cursor_grp.x
+
+    @x.setter
+    def x(self, x_val):
+        """Sets the x-value of the cursor.
+        :param int x_val: cursor x-position, in pixels.
+        """
+        self._is_deinited()
+        if x_val < 0 and not self._is_hidden:
+            self._cursor_grp.x = self._cursor_grp.x
+        elif x_val > self._disp_sz[1] and not self._is_hidden:
+            self._cursor_grp.x = self._cursor_grp.x
+        elif not self._is_hidden:
+            self._cursor_grp.x = x_val
+
+    @property
+    def y(self):
+        """Returns the cursor's y-coordinate."""
+        return self._cursor_grp.y
+
+    @y.setter
+    def y(self, y_val):
+        """Sets the y-value of the cursor.
+        :param int y_val: cursor y-position, in pixels.
+        """
+        self._is_deinited()
+        if y_val < 0 and not self._is_hidden:
+            self._cursor_grp.y = self._cursor_grp.y
+        elif y_val > self._disp_sz[0] and not self._is_hidden:
+            self._cursor_grp.y = self._cursor_grp.y
+        elif not self._is_hidden:
+            self._cursor_grp.y = y_val
+
+    @property
+    def hide(self):
+        """Returns True if the cursor is hidden or visible on the display."""
+        return self._is_hidden
+
+    @hide.setter
+    def hide(self, is_hidden):
+        self._is_deinited()
+        if is_hidden:
+            self._is_hidden = True
+            self._display_grp.remove(self._cursor_grp)
+        else:
+            self._is_hidden = False
+            self._display_grp.append(self._cursor_grp)
+
+    def generate_cursor(self):
+        """Generates a cursor icon"""
+        self._is_deinited()
+        self._cursor_grp = displayio.Group(max_size=1, scale=self._scale)
+        self._cur_bmp = displayio.Bitmap(20, 20, 3)
+        self._cur_palette = displayio.Palette(3)
+        self._cur_palette.make_transparent(0)
+        self._cur_palette[1] = 0xFFFFFF
+        self._cur_palette[2] = 0x0000
+        # left edge, outline
+        for i in range(0, self._cur_bmp.height):
+            self._cur_bmp[0, i] = 2
+        # right diag outline, inside fill
+        for j in range(1, 15):
+            self._cur_bmp[j, j] = 2
+            for i in range(j+1, self._cur_bmp.height - j):
+                self._cur_bmp[j, i] = 1
+        # bottom diag., outline
+        for i in range(1, 5):
+            self._cur_bmp[i, self._cur_bmp.height-i] = 2
+        # bottom flat line, right side fill
+        for i in range(5, 15):
+            self._cur_bmp[i, 15] = 2
+            self._cur_bmp[i-1, 14] = 1
+            self._cur_bmp[i-2, 13] = 1
+            self._cur_bmp[i-3, 12] = 1
+            self._cur_bmp[i-4, 11] = 1
+        self._cur_sprite = displayio.TileGrid(self._cur_bmp,
+                                              pixel_shader=self._cur_palette)
+        self._cursor_grp.append(self._cur_sprite)
+        self._display_grp.append(self._cursor_grp)

README.rst

@@ -0,0 +1,161 @@
+# The MIT License (MIT)
+#
+# Copyright (c) 2019 Brent Rubell for Adafruit Industries
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+"""
+`adafruit_cursorcontrol_cursormanager`
+================================================================================
+Simple interaction user interface interaction for Adafruit_CursorControl.
+* Author(s): Brent Rubell
+"""
+import board
+import digitalio
+from micropython import const
+import analogio
+from gamepadshift import GamePadShift
+
+# PyBadge
+PYBADGE_BUTTON_LEFT = const(128)
+PYBADGE_BUTTON_UP = const(64)
+PYBADGE_BUTTON_DOWN = const(32)
+PYBADGE_BUTTON_RIGHT = const(16)
+# PyBadge & PyGamer
+PYBADGE_BUTTON_A = const(2)
+
+JOY_X_CTR = 32767.5
+JOY_Y_CTR = 32767.5
+
+class CursorManager:
+    """Simple interaction user interface interaction for Adafruit_CursorControl.
+
+    :param adafruit_cursorcontrol cursor: The cursor object we are using.
+    """
+    def __init__(self, cursor):
+        self._cursor = cursor
+        self._is_clicked = False
+        self._init_hardware()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exception_type, exception_value, traceback):
+        self.deinit()
+
+    def deinit(self):
+        """Deinitializes a CursorManager object."""
+        self._is_deinited()
+        self._pad.deinit()
+        self._cursor.deinit()
+        self._cursor = None
+
+    def _is_deinited(self):
+        """Checks if CursorManager object has been deinitd."""
+        if self._cursor is None:
+            raise ValueError("CursorManager object has been deinitialized and can no longer "
+                             "be used. Create a new CursorManager object.")
+
+    def _init_hardware(self):
+        """Initializes PyBadge or PyGamer hardware."""
+        if hasattr(board, 'BUTTON_CLOCK') and not hasattr(board, 'JOYSTICK_X'):
+            self._pad_btns = {'btn_left' : PYBADGE_BUTTON_LEFT,
+                              'btn_right' : PYBADGE_BUTTON_RIGHT,
+                              'btn_up' : PYBADGE_BUTTON_UP,
+                              'btn_down' : PYBADGE_BUTTON_DOWN,
+                              'btn_a' : PYBADGE_BUTTON_A}
+        elif hasattr(board, 'JOYSTICK_X'):
+            self._joystick_x = analogio.AnalogIn(board.JOYSTICK_X)
+            self._joystick_y = analogio.AnalogIn(board.JOYSTICK_Y)
+            self._pad_btns = {'btn_a' : PYBADGE_BUTTON_A}
+        else:
+            raise AttributeError('Board must have a D-Pad or Joystick for use with CursorManager!')
+        self._pad = GamePadShift(digitalio.DigitalInOut(board.BUTTON_CLOCK),
+                                 digitalio.DigitalInOut(board.BUTTON_OUT),
+                                 digitalio.DigitalInOut(board.BUTTON_LATCH))
+
+    @property
+    def is_clicked(self):
+        """Returns True if the cursor button was pressed
+        during previous call to update()
+        """
+        return self._is_clicked
+
+    def update(self):
+        """Updates the cursor object."""
+        pressed = self._pad.get_pressed()
+        self._check_cursor_movement(pressed)
+        if self._is_clicked:
+            self._is_clicked = False
+        elif pressed & self._pad_btns['btn_a']:
+            self._is_clicked = True
+
+    def _read_joystick_x(self, samples=3):
+        """Read the X analog joystick on the PyGamer.
+        :param int samples: How many samples to read and average.
+        """
+        reading = 0
+        # pylint: disable=unused-variable
+        if hasattr(board, 'JOYSTICK_X'):
+            for sample in range(0, samples):
+                reading += self._joystick_x.value
+            reading /= samples
+            reading -= JOY_X_CTR
+        return reading
+
+    def _read_joystick_y(self, samples=3):
+        """Read the Y analog joystick on the PyGamer.
+        :param int samples: How many samples to read and average.
+        """
+        reading = 0
+        # pylint: disable=unused-variable
+        if hasattr(board, 'JOYSTICK_Y'):
+            for sample in range(0, samples):
+                reading += self._joystick_y.value
+            reading /= samples
+            reading -= JOY_Y_CTR
+        return reading
+
+    def _check_cursor_movement(self, pressed=None):
+        """Checks the PyBadge D-Pad or the PyGamer's Joystick for movement.
+        :param int pressed: 8-bit number with bits that correspond to buttons
+            which have been pressed down since the last call to get_pressed().
+        """
+        if hasattr(board, 'BUTTON_CLOCK') and not hasattr(board, 'JOYSTICK_X'):
+            if pressed & self._pad_btns['btn_right']:
+                self._cursor.x += self._cursor.speed
+            elif pressed & self._pad_btns['btn_left']:
+                self._cursor.x -= self._cursor.speed
+            if pressed & self._pad_btns['btn_up']:
+                self._cursor.y -= self._cursor.speed
+            elif pressed & self._pad_btns['btn_down']:
+                self._cursor.y += self._cursor.speed
+        elif hasattr(board, 'JOYSTICK_X'):
+            joy_x = self._read_joystick_x()
+            joy_y = self._read_joystick_y()
+            if joy_x > 700:
+                self._cursor.x += self._cursor.speed
+            elif joy_x < -700:
+                self._cursor.x -= self._cursor.speed
+            if joy_y > 700:
+                self._cursor.y += self._cursor.speed
+            elif joy_y < -700:
+                self._cursor.y -= self._cursor.speed
+        else:
+            raise AttributeError('Board must have a D-Pad or Joystick for use with CursorManager!')

adafruit_cursorcontrol/__init__.py

@@ -0,0 +1,4 @@
+API
+====
+.. automodule:: adafruit_cursorcontrol
+   :members:

adafruit_cursorcontrol/cursorcontrol.py

@@ -0,0 +1,160 @@
+# -*- coding: utf-8 -*-
+
+import os
+import sys
+sys.path.insert(0, os.path.abspath('..'))
+
+# -- General configuration ------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.todo',
+]
+
+# TODO: Please Read!
+# Uncomment the below if you use native CircuitPython modules such as
+# digitalio, micropython and busio. List the modules you use. Without it, the
+# autodoc module docs will fail to generate with a warning.
+autodoc_mock_imports = ["displayio"]
+
+
+intersphinx_mapping = {'python': ('https://docs.python.org/3.4', None),'CircuitPython': ('https://circuitpython.readthedocs.io/en/latest/', None)}
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'Adafruit CursorControl Library'
+copyright = u'2019 Brent Rubell'
+author = u'Brent Rubell'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = u'1.0'
+# The full version, including alpha/beta/rc tags.
+release = u'1.0'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This patterns also effect to html_static_path and html_extra_path
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', '.env', 'CODE_OF_CONDUCT.md']
+
+# The reST default role (used for this markup: `text`) to use for all
+# documents.
+#
+default_role = "any"
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#
+add_function_parentheses = True
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = False
+
+# If this is True, todo emits a warning for each TODO entries. The default is False.
+todo_emit_warnings = True
+
+napoleon_numpy_docstring = False
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
+
+if not on_rtd:  # only import and set the theme if we're building docs locally
+    try:
+        import sphinx_rtd_theme
+        html_theme = 'sphinx_rtd_theme'
+        html_theme_path = [sphinx_rtd_theme.get_html_theme_path(), '.']
+    except:
+        html_theme = 'default'
+        html_theme_path = ['.']
+else:
+    html_theme_path = ['.']
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# The name of an image file (relative to this directory) to use as a favicon of
+# the docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#
+html_favicon = '_static/favicon.ico'
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'AdafruitCursorcontrolLibrarydoc'
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+     # The paper size ('letterpaper' or 'a4paper').
+     #
+     # 'papersize': 'letterpaper',
+
+     # The font size ('10pt', '11pt' or '12pt').
+     #
+     # 'pointsize': '10pt',
+
+     # Additional stuff for the LaTeX preamble.
+     #
+     # 'preamble': '',
+
+     # Latex figure (float) alignment
+     #
+     # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc, 'AdafruitCursorControlLibrary.tex', u'AdafruitCursorControl Library Documentation',
+     author, 'manual'),
+]
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, 'AdafruitCursorControllibrary', u'Adafruit CursorControl Library Documentation',
+     [author], 1)
+]
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (master_doc, 'AdafruitCursorControlLibrary', u'Adafruit CursorControl Library Documentation',
+     author, 'AdafruitCursorControlLibrary', 'One line description of project.',
+     'Miscellaneous'),
+]

adafruit_cursorcontrol/cursorcontrol_cursormanager.py

@@ -0,0 +1,8 @@
+Simple test
+------------
+
+Ensure your device works with this simple test.
+
+.. literalinclude:: ../examples/cursorcontrol_simpletest.py
+    :caption: examples/cursorcontrol_simpletest.py
+    :linenos:

docs/_static/favicon.ico

@@ -0,0 +1,45 @@
+.. include:: ../README.rst
+
+Table of Contents
+=================
+
+.. toctree::
+    :maxdepth: 4
+    :hidden:
+
+    self
+
+.. toctree::
+    :caption: Examples
+
+    examples
+
+.. toctree::
+    :caption: API Reference
+    :maxdepth: 3
+
+    api
+
+.. toctree::
+    :caption: Tutorials
+
+.. toctree::
+    :caption: Related Products
+
+.. toctree::
+    :caption: Other Links
+
+    Download <https://github.com/adafruit/Adafruit_CircuitPython_CursorControl/releases/latest>
+    CircuitPython Reference Documentation <https://circuitpython.readthedocs.io>
+    CircuitPython Support Forum <https://forums.adafruit.com/viewforum.php?f=60>
+    Discord Chat <https://adafru.it/discord>
+    Adafruit Learning System <https://learn.adafruit.com>
+    Adafruit Blog <https://blog.adafruit.com>
+    Adafruit Store <https://www.adafruit.com>
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/api.rst

@@ -0,0 +1,119 @@
+import time
+import board
+import displayio
+from adafruit_button import Button
+from adafruit_cursorcontrol.cursorcontrol import Cursor
+from adafruit_cursorcontrol.cursorcontrol_cursormanager import CursorManager
+from adafruit_display_text import label
+import terminalio
+
+# Create the display
+display = board.DISPLAY
+
+# Create the display context
+splash = displayio.Group(max_size=22)
+
+# Use the built-in system font
+font = terminalio.FONT
+
+##########################################################################
+# Make a background color fill
+
+color_bitmap = displayio.Bitmap(display.width, display.height, 1)
+color_palette = displayio.Palette(1)
+color_palette[0] = 0x404040
+bg_sprite = displayio.TileGrid(color_bitmap,
+                               pixel_shader=color_palette,
+                               x=0, y=0)
+splash.append(bg_sprite)
+
+##########################################################################
+
+# Set up button/label properties
+BUTTON_WIDTH = 80
+BUTTON_HEIGHT = 40
+BUTTON_MARGIN = 20
+LBL_HEADER = [100, 20]
+LBL_TEXT = [120, 40]
+
+# Resize buttons for small display (PyGamer)
+if display.width < 240:
+    BUTTON_WIDTH = int(BUTTON_WIDTH / 2)
+    BUTTON_HEIGHT = int(BUTTON_HEIGHT / 2)
+    BUTTON_MARGIN = int(BUTTON_MARGIN / 2)
+    LBL_HEADER[0] -= 75
+    LBL_HEADER[1] -= 10
+    LBL_TEXT[0] -= 70
+    LBL_TEXT[1] += 55
+
+# Create the buttons
+buttons = []
+
+button_speed_inc = Button(x=BUTTON_MARGIN, y=BUTTON_MARGIN+BUTTON_HEIGHT,
+                          width=BUTTON_WIDTH, height=BUTTON_HEIGHT,
+                          label="Speed+", label_font=font)
+buttons.append(button_speed_inc)
+
+button_speed_dec = Button(x=BUTTON_MARGIN, y=BUTTON_MARGIN*4+BUTTON_HEIGHT,
+                          width=BUTTON_WIDTH, height=BUTTON_HEIGHT,
+                          label="Speed-", label_font=font)
+buttons.append(button_speed_dec)
+
+button_scale_pos = Button(x=BUTTON_MARGIN*3+2*BUTTON_WIDTH, y=BUTTON_MARGIN+BUTTON_HEIGHT,
+                          width=BUTTON_WIDTH, height=BUTTON_HEIGHT,
+                          label="Scale+", label_font=font, style=Button.SHADOWRECT)
+buttons.append(button_scale_pos)
+
+button_scale_neg = Button(x=BUTTON_MARGIN*3+2*BUTTON_WIDTH, y=BUTTON_MARGIN*4+BUTTON_HEIGHT,
+                          width=BUTTON_WIDTH, height=BUTTON_HEIGHT,
+                          label="Scale-", label_font=font, style=Button.SHADOWRECT)
+buttons.append(button_scale_neg)
+
+# Show the button
+for b in buttons:
+    splash.append(b.group)
+
+# Create a text label
+text_label = label.Label(font, text="CircuitPython Cursor!", color=0x00FF00,
+                         x = LBL_HEADER[0], y = LBL_HEADER[1])
+splash.append(text_label)
+
+text_speed = label.Label(font, max_glyphs = 15, color=0x00FF00,
+                         x = LBL_TEXT[0], y = LBL_TEXT[1])
+splash.append(text_speed)
+
+text_scale = label.Label(font, max_glyphs = 15, color=0x00FF00,
+                         x = LBL_TEXT[0], y = LBL_TEXT[1]+20)
+splash.append(text_scale)
+
+# initialize the mouse cursor object
+mouse_cursor = Cursor(display, display_group=splash)
+
+# initialize the cursormanager
+cursor = CursorManager(mouse_cursor)
+
+# show displayio group
+display.show(splash)
+
+prev_btn = None
+while True:
+    cursor.update()
+    if cursor.is_clicked is True:
+        for i, b in enumerate(buttons):
+            if b.contains((mouse_cursor.x, mouse_cursor.y)):
+                b.selected=True
+                print("Button %d pressed"%i)
+                if i == 0: # Increase the cursor speed
+                    mouse_cursor.speed += 1
+                elif i == 1: # Decrease the cursor speed
+                    mouse_cursor.speed -= 1
+                if i == 2: # Increase the cursor scale
+                    mouse_cursor.scale += 1
+                elif i == 3: # Decrease the cursor scale
+                    mouse_cursor.scale -= 1
+                prev_btn = b
+    elif prev_btn is not None:
+        prev_btn.selected = False
+    text_speed.text = 'Speed: {0}px'.format(mouse_cursor.speed)
+    text_scale.text = 'Scale: {0}px'.format(mouse_cursor.scale)
+    time.sleep(0.1)

docs/conf.py

@@ -0,0 +1,29 @@
+import time
+import board
+import displayio
+from adafruit_cursorcontrol.cursorcontrol import Cursor
+from adafruit_cursorcontrol.cursorcontrol_cursormanager import CursorManager
+
+# Create the display
+display = board.DISPLAY
+
+# Create the display context
+splash = displayio.Group(max_size=5)
+
+# initialize the mouse cursor object
+mouse_cursor = Cursor(display, display_group=splash)
+
+# initialize the cursormanager
+cursor = CursorManager(mouse_cursor)
+
+# show displayio group
+display.show(splash)
+
+while True:
+    cursor.update()
+    if cursor.is_clicked:
+        if mouse_cursor.hide:
+            mouse_cursor.hide = False
+        else:
+            mouse_cursor.hide = True
+    time.sleep(0.01)

docs/examples.rst

@@ -0,0 +1 @@
+Adafruit-Blinka

docs/index.rst

@@ -0,0 +1,64 @@
+"""A setuptools based setup module.
+
+See:
+https://packaging.python.org/en/latest/distributing.html
+https://github.com/pypa/sampleproject
+"""
+
+from setuptools import setup, find_packages
+# To use a consistent encoding
+from codecs import open
+from os import path
+
+here = path.abspath(path.dirname(__file__))
+
+# Get the long description from the README file
+with open(path.join(here, 'README.rst'), encoding='utf-8') as f:
+    long_description = f.read()
+
+setup(
+    name='adafruit-circuitpython-cursorcontrol',
+
+    use_scm_version=True,
+    setup_requires=['setuptools_scm'],
+
+    description='Mouse cursor for interaction with CircuitPython UI elements.',
+    long_description=long_description,
+    long_description_content_type='text/x-rst',
+
+    # The project's main homepage.
+    url='https://github.com/adafruit/Adafruit_CircuitPython_CursorControl',
+
+    # Author details
+    author='Adafruit Industries',
+    author_email='circuitpython@adafruit.com',
+
+    install_requires=[
+        'Adafruit-Blinka',
+        'no'
+    ],
+
+    # Choose your license
+    license='MIT',
+
+    # See https://pypi.python.org/pypi?%3Aaction=list_classifiers
+    classifiers=[
+        'Development Status :: 3 - Alpha',
+        'Intended Audience :: Developers',
+        'Topic :: Software Development :: Libraries',
+        'Topic :: System :: Hardware',
+        'License :: OSI Approved :: MIT License',
+        'Programming Language :: Python :: 3',
+        'Programming Language :: Python :: 3.4',
+        'Programming Language :: Python :: 3.5',
+    ],
+
+    # What does your project relate to?
+    keywords='adafruit blinka circuitpython micropython cursorcontrol mouse, cursor, ui',
+
+    # You can just specify the packages manually here if your project is
+    # simple. Or you can use find_packages().
+    # TODO: IF LIBRARY FILES ARE A PACKAGE FOLDER,
+    #       CHANGE `py_modules=['...']` TO `packages=['...']`
+    py_modules=['adafruit_cursorcontrol'],
+)