Permalink
Fetching contributors…
Cannot retrieve contributors at this time
381 lines (277 sloc) 13.4 KB

🌈 Graphics

Drawing

.. py:function:: screen.fill(color)

    Fills the screen with the specified ``color``.

    :ref:`color-option` can be specified using a name (e.g. 'white', 'black'), or an RGB triple.

    .. code-block:: python
       :caption: Example: fill the screen with white

       screen.fill(color='white')

    .. code-block:: python
        :caption: Example: fill the screen with red

        screen.fill(color=(255, 0, 0))

.. py:function:: screen.text(string…, xy=…, color=…, align=…, font=…, font_size=…, max_width=…, max_lines=…, max_height=…)

    Draws text ``string``.

    ``xy`` is the position that the text will be drawn.

    :ref:`align-option` is one of:

        topleft, left, bottomleft, top, center, bottom, topright, right, bottomright

    If a custom font is used, it must be included in the tingapp bundle.

    .. code-block:: python
        :caption: Example: Write 'Hello world' in black on the screen

        screen.text('Hello world!', color='black')

    .. code-block:: python
        :caption: Example: changing the alignment

        screen.text('Hello world!', xy=(20,20), color='black', align='topleft')

    .. code-block:: python
        :caption: Example: Using a custom font

        screen.text('Hello world!', color='black', font='Helvetica.ttf')

    .. code-block:: python
        :caption: Example: Changing the text size

        screen.text('Hello world!', color='black', font_size=50)

    .. code-block:: python
        :caption: Example: Confining text to a single line

        screen.text('Lorem ipsum dolor sit amet, consectetur adipiscing elit!', color='black', max_lines=1)

    .. code-block:: python
        :caption: Example: Confining text to two lines

        screen.text('Lorem ipsum dolor sit amet, consectetur adipiscing elit!', color='black', max_width=300, max_lines=2)


.. py:function:: screen.rectangle(xy=…, size=…, color=…, align=…)

    Draws a rectangle at position xy, with the specified size and color.

    Align is one of

        topleft, left, bottomleft, top, center, bottom, topright, right, bottomright,

    .. code-block:: python
        :caption: Example: Drawing a red square

        screen.rectangle(xy=(25,25), size=(100,100), color=(255,0,0))

    .. code-block:: python
        :caption: Example: Drawing centered

        screen.rectangle(xy=(160,120), size=(100,100), color=(255,0,0), align='center')

.. function:: screen.image(filename…, xy=…, scale=…, align=…, max_width=…, max_height=…, raise_error=True)

    Draws an image with name filename at position xy. If filename is a URL (e.g. http://example.com/cats.png) then
    it will attempt to download this and display it.

    Images can be animated GIFs. Make sure to draw them in a loop() function to see them animate.

    Scale is a number that changes the size of the image e.g. scale=2 makes the image bigger, scale=0.5 makes the image smaller. There are also special values 'fit' and 'fill', which will fit or fill the image according to ``max_width`` and ``max_height``.

    Align is one of

        topleft, left, bottomleft, top, center, bottom, topright, right, bottomright

    If raise_error is True then any errors encountered while opening or retrieving the image will cause
    an `exception <https://docs.python.org/2/tutorial/errors.html>`_. If it is False, then if there is an error a "file not found" icon will be displayed instead

    .. code-block:: python
        :caption: Example: Drawing an Image

        screen.image('tingbot.png', xy=(25,25))

    .. code-block:: python
        :caption: Example: Drawing an Image from a URL

        screen.image('http://i.imgur.com/xbT92Gm.png')

.. py:function:: screen.line(start_xy=…, end_xy=…, color=…, width=…)

    Draws a line between ``start_xy`` and ``end_xy``.

Screen

The screen supports all the methods above, and some extras below.

.. py:function:: screen.update()

    After drawing, this method should to be called to refresh the screen. When drawing in a
    ``draw()`` or ``loop()`` function, this is called automatically, but when drawing in a tight
    loop, e.g. during a calculation, it can called manually.

    .. code-block:: python
        :caption: Example: An app without a run loop - calling ``screen.update()`` manually

        import tingbot
        from tingbot import *

        screen.fill(color='black')

        # pump the main run loop just once to make sure the app starts
        tingbot.input.EventHandler().poll()

        frame_count = 0

        while True:
            screen.fill(color='black')
            screen.text(frame_count)
            screen.update()
            frame_count += 1

.. py:attribute:: screen.brightness

    The brightness of the screen, between 0 and 100.

    .. code-block:: python
        :caption: Example: Dimming the screen

        screen.brightness = 25

    .. code-block:: python
        :caption: Example: Brightness test app

        import tingbot
        from tingbot import *

        state = {'brightness': 0}

        def loop():
            screen.brightness = state['brightness']

            screen.fill(color='black')
            screen.text('Brightness\n %i' % state['brightness'])

            state['brightness'] += 1

            if state['brightness'] > 100:
                state['brightness'] = 0

        tingbot.run(loop)

The align option

When used without the xy parameter, the item is positioned relative to the screen/drawing surface.

Setting Screenshot Code
topleft images/align/topleft.png screen.rectangle(color='green', align='topleft')
top images/align/top.png screen.rectangle(color='green', align='top')
topright images/align/topright.png screen.rectangle(color='green', align='topright')
left images/align/left.png screen.rectangle(color='green', align='left')
center images/align/center.png screen.rectangle(color='green', align='center')
right images/align/right.png screen.rectangle(color='green', align='right')
bottomleft images/align/bottomleft.png screen.rectangle(color='green', align='bottomleft')
bottom images/align/bottom.png screen.rectangle(color='green', align='bottom')
bottomright images/align/bottomright.png screen.rectangle(color='green', align='bottomright')

When used with the xy parameter, it positions the item relative to the xy point.

Setting Screenshot Code
topleft images/alignxy/topleft.png screen.rectangle(xy=(160, 120), align='topleft')
top images/alignxy/top.png screen.rectangle(xy=(160, 120), align='top')
topright images/alignxy/topright.png screen.rectangle(xy=(160, 120), align='topright')
left images/alignxy/left.png screen.rectangle(xy=(160, 120), align='left')
center images/alignxy/center.png screen.rectangle(xy=(160, 120), align='center')
right images/alignxy/right.png screen.rectangle(xy=(160, 120), align='right')
bottomleft images/alignxy/bottomleft.png screen.rectangle(xy=(160, 120), align='bottomleft')
bottom images/alignxy/bottom.png screen.rectangle(xy=(160, 120), align='bottom')
bottomright images/alignxy/bottomright.png screen.rectangle(xy=(160, 120), align='bottomright')

The color option

The color option can be either an RGB value, or predefined color name.

RGB values

RGB values (as a tuple), like (255, 128, 0).

Predefined colors

We also have a set of default colors, referred to by their name, as a string.

.color-swatches { margin-bottom: 30px; } .color-swatch { float: left; width: 25%; text-align: center; padding-top: 12px; padding-bottom: 15px; } .color-swatch.big { width: 100%; box-sizing: border-box; } .color-swatch span { display: block; margin-bottom: 3px; } .color-swatch code { background-color: transparent; color: inherit; border-color: currentColor; border-width: 0; } .bg-navy { background-color: #001F3F; } .bg-blue { background-color: #0074D9; } .bg-aqua { background-color: #7FDBFF; } .bg-teal { background-color: #39CCCC; } .bg-olive { background-color: #3D9970; } .bg-green { background-color: #2ECC40; } .bg-lime { background-color: #01FF70; } .bg-yellow { background-color: #FFDC00; } .bg-orange { background-color: #FF851B; } .bg-red { background-color: #FF4136; } .bg-fuchsia { background-color: #F012BE; } .bg-purple { background-color: #B10DC9; } .bg-maroon { background-color: #85144B; } .bg-white { background-color: #FFFFFF; } .bg-gray { background-color: #AAAAAA; } .bg-silver { background-color: #DDDDDD; } .bg-black { background-color: #000000; }
'navy' (0, 116, 217)
'blue' (0, 116, 217)
'aqua' (127, 219, 255)
'teal' (57, 204, 204)
'olive' (61, 153, 112)
'green' (46, 204, 64)
'lime' (1, 255, 112)
'yellow' (255, 220, 0)
'orange' (255, 133, 27)
'red' (255, 65, 54)
'maroon' (133, 20, 75)
'fuchsia' (240, 18, 190)
'purple' (177, 13, 201)
'black' (0, 0, 0)
'gray' (170, 170, 170)
'silver' (221, 221, 221)
'white' (255, 255, 255)

Thanks to http://clrs.cc for the color scheme!