Mercurial > circuitpython-badge

annotate docs/library.rst @ 4:7125a66d2f6d draft default tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Typo
author Radomir Dopieralski <sheep-devel@sheep.art.pl>
date Sun, 19 Aug 2018 13:49:10 +0200
parents 9fd73b085363
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
2
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
1 Library Reference
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
2 *****************
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
3
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
4 .. module:: badge
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
5
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
6 .. function:: init()
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
7
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
8 Initialize the module.
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
9
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
10 This function switches the display on and performs some basic setup.
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
11
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
12
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
13 .. function:: brightness(level)
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
14
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
15 Set the brightness of the display, from 0 to 15.
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
16
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
17
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
18 .. function:: show(pix)
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
19
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
20 Show the provided image on the display, starting at the top left corner.
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
21 You will want to call this once for every frame.
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
22
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
23
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
24 .. function:: keys()
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
25
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
26 Return a number telling which keys have been pressed since the last check.
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
27 The number can then be filtered with the ``&`` operator and the ``K_X``,
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
28 ``K_DOWN``, ``K_LEFT``, ``K_RIGHT``, ``K_UP``, ``K_O``, ``K_S``, and
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
29 ``K_Z`` constants to see whether any of the keys was pressed.
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
30
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
31
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
32 .. function:: tick(delay)
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
33
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
34 Wait until ``delay`` seconds have passed since the last call to this
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
35 function. You can call it every frame to ensure a constant frame rate.
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
36
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
37
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
38 .. class:: Pix(width=14, height=11, buffer=None)
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
39
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
40 Pix represents a drawing surface, ``width`` pixels wide and ``height``
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
41 pixels high.
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
42
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
43 If no ``buffer`` is specified for storing the data, a suitable one will
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
44 be automatically created.
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
45
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
46 .. classmethod:: from_string(cls, string)
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
47
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
48 Creates a new Pix and initialzes its contents from a provided string.
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
49 Each line corresponds to one line of the image, and each character
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
50 corresponds to a pixel on that line. The brightness of a pixel is
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
51 encoded as a single hexadecimal digit, `0` being black and `F` being
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
52 white. Characters that are not hex digits will cause an error.
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
53
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
54 .. classmethod:: from_text(cls, text, color=None, background=0, colors=None)
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
55
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
56 Creates a new Pix and renders the specified text on it. It is exactly
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
57 the size needed to fit the specified text. Newlines and other control
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
58 characters are rendered as spaces.
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
59
3
9fd73b085363 Fix text colors in docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents: 2
diff changeset
60 If ``color`` is not specified, it will use bright text on dark
4
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents: 3
diff changeset
61 background by default. Otherwise it will use the specified color, with
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents: 3
diff changeset
62 ``background`` color as the background.
2
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
63
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
64 Alternatively, ``colors`` may be specified as a 4-tuple of colors,
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
65 and then the ``color`` and ``background`` arguments are ignored, and
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
66 the four specified colors are used for rendering the text.
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
67
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
68 .. method:: pixel(self, x, y, color=None)
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
69
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
70 If ``color`` is specified, sets the pixel at location ``x``, ``y`` to
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
71 that color. If not, returns the color of the pixel at that location.
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
72
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
73 If the location is out of bounds of the drawing surface, returns 0.
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
74
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
75 .. method:: box(self, color, x=0, y=0, width=self.width, height=self.height)
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
76
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
77 Draws a filled box with the specified ``color`` with its top left
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
78 corner at the specified location and of the specified size. If no
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
79 location and size are specified, fills the whole drawing surface.
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
80
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
81 .. method:: blit(self, source, dx=0, dy=0, x=0, y=0, width=None, height=None, key=None)
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
82
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
83 Copied the ``source`` drawing surface onto this surface at location
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
84 specified with ``dx`` and ``dy``.
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
85
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
86 If ``x``, ``y``, ``widht`` and ``height`` are specified, only copies
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
87 that fragment of the ``source`` image, otherwise copies it whole.
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
88
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
89 If ``key`` color is specified, that color is considered transparent
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
90 on the source image, and is not copied onto this drawing surface.
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
91
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
92
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
93 .. function:: accel()
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
94
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
95 Return a triple ``(x, y, z)`` of acceleration values reported by the
eff707b7a302 Initial docs
Radomir Dopieralski <sheep-devel@sheep.art.pl>
parents:
diff changeset
96 on-board accelerometer.