Documentation for the Code

The eInkDraw Module

Eink Draw is a simple drawing library for use with eInk displays.

eInkDraw Layout Classes

This module contains classes that deal with the relative layout of drawable elements to each other. Drawable elements can be laid out in several forms of rows, or columns, they can be stacked on top of each other or they can be embedded in others (like in a Frame).

These layouts can also be nested to create more complex arrangements.

class einkdraw.layout.Background(width=100, height=100, pattern=None, draw_outline=False)

A uniformally filled rectangle, generally used as a background underneath other Drawable instances.

Args:

width (int): Width of object

height (int): Height of object)

pattern: Any of the Background.PATTERN_XXX constants.

PATTERN_BLACK = <cairo.SurfacePattern object>

A black background

PATTERN_DARK_GREY = <cairo.SurfacePattern object>

A tightly dithered grey background.

PATTERN_LIGHT_GREY = <cairo.SurfacePattern object>

A lightly dithered grey background

PATTERN_MEDIUM_GREY = <cairo.SurfacePattern object>

A 50% dithered background.

PATTERN_TRANSPARENT = None

A transparent background

PATTERN_WHITE = <cairo.SurfacePattern object>

A white background

draw(ctx)

Draw the content of this object to a pycairo Drawing context.

Args:

self (pycairo.Context): The drawing context to draw on.

get_bbox()

Return the size of the bounding box for this drawable.

Returns:

(int, int) Width and height of the bounding box.

class einkdraw.layout.Column(items=[])

A layout object that aligns Drawable objects vertically.

The width of the resulting Column object is the maximum width of all its children.

The height of the resulting Column object is determined by the sum of the sizes of all the vertically stacked Drawable instances.

Args:

items (Drawable or [Drawable]): List of child objects

to arrange, listed from top to bottom.

draw(ctx)

Draw the content of this object to a pycairo Drawing context.

Args:

self (pycairo.Context): The drawing context to draw on.

get_bbox()

Return the size of the bounding box for this drawable.

Returns:

(int, int) Width and height of the bounding box.

class einkdraw.layout.Drawable

Drawable is the base class for all graphical elements defined by einkdraw. This is a base class and not meaningful to instantiate.

draw(ctx)

Draw the content of this object to a pycairo Drawing context.

Args:

self (pycairo.Context): The drawing context to draw on.

get_bbox()

Return the size of the bounding box for this drawable.

Returns:

(int, int) Width and height of the bounding box.

class einkdraw.layout.FixedColumn(width, height, stack)

A layout object that aligns elements vertically.

See FixedLinear

class einkdraw.layout.FixedLinear(width, height, stack, orientation='column')

Base class for horizontal or vertical layouts of Drawable instances where the size of the layout container is fixed, and the list of objects in it are resized accordingly, to fill the container either horizontally or vertically.

Args:

width (int): Width of object.

height (int): Height of object.

stack ([(int, Drawable, Background)]): A list of tuples, where the first

element is an integer specifying the number of proportional shares within the FixedLinear that are taken up by the Drawable that is the second element of each tuple in this list. The third elemetn is an of the Background.PATTERN_XX constants, for backgrount patterns. (Note that None means transparent background).

orientation (str): Either “row” or “column”, specifying whether

the elements should be lined up horizontally or vertically.

class einkdraw.layout.FixedRow(width, height, stack)

A layout object that aligns elements vertically.

See FixedLinear

class einkdraw.layout.Frame(drawable, outer=1, middle=1, inner=1)

Puts a frame around an embedded Drawable. There is an outer (white) frame, a middle (black) and an inner(white) rectangle that the frame is comprised of.

Args:

drawable (Drawable): Object to frame.

outer (int): Width of the outer (white) rectangle of the frame.

middle (int): Width of the middle (black) rectangle of the frame.

inner (int): Width of the inner (white) rectangle of the fame.

draw(ctx)

Draw the content of this object to a pycairo Drawing context.

Args:

self (pycairo.Context): The drawing context to draw on.

get_bbox()

Return the size of the bounding box for this drawable.

Returns:

(int, int) Width and height of the bounding box.

class einkdraw.layout.Linear(items=[])

Base class for all vertical or horizontal alignment classes that derive their overall size from the bounding box of the Drawables that they contain.

add(obj)

Add a drawable or a list of drawables.

Args:

obj (Drawable or list thereof): Object(s) to add.

class einkdraw.layout.Row(items=[])

A layout object that aligns Drawable objects horizontally.

The width of the resulting Column object is determined by the sum of the widths of all the vertically stacked Drawable instances.

The height of the resulting Column object is the maximum height of all its children.

Args:

items (Drawable or [Drawable]): List of child objects

to arrange, listed from left to right.

draw(ctx)

Draw the content of this object to a pycairo Drawing context.

Args:

self (pycairo.Context): The drawing context to draw on.

get_bbox()

Return the size of the bounding box for this drawable.

Returns:

(int, int) Width and height of the bounding box.

class einkdraw.layout.Spacer(amount=10)

A layout helper class that inserts space between drawables in containers derived from Linear or FixedLinear.

Args:

amount (int): Amount of space to insert both horizontally and vertically.

get_bbox()

Return the size of the bounding box for this drawable.

Returns:

(int, int) Width and height of the bounding box.

resize(width=None, height=None)

Changes the size of a spacer after its creation.

Args:

width (int): If not None, set the horizontal size to the value specified.

height (int): If not None, set the vertical size to the value specified.

class einkdraw.layout.Stack(items=[])

A layout object that aligns Drawable objects from front to back, drawing them over each other.

The width and height of a Stack is the maximum of the widths and heights of its children.

Args:

items (Drawable or [Drawable]): List of child objects

to arrange, listed from back to front.

draw(ctx)

Draw the content of this object to a pycairo Drawing context.

Args:

self (pycairo.Context): The drawing context to draw on.

get_bbox()

Return the size of the bounding box for this drawable.

Returns:

(int, int) Width and height of the bounding box.

class einkdraw.layout.Wrapper(toplevel_object)

A base class to derive objects from that wrap Drawable instances. This saves you from having to implement trival draw and get_bbox methods.

Args:

toplevel_object (Drawable) Toplevel ekinkdraw drawable to wrap.

draw(ctx)

Draw the content of this object to a pycairo Drawing context.

Args:

self (pycairo.Context): The drawing context to draw on.

get_bbox()

Return the size of the bounding box for this drawable.

Returns:

(int, int) Width and height of the bounding box.

class einkdraw.layout.drawing_on(ctx)

A helper for saving and restoring a pycairo.Context within a draw function of an einkdraw Drawable.

This makes sure that pycairo.Context save and restore calls always match up.

Example:

>>> def draw(self, ctx):
>>>    with drawing_on(ctx):
>>>           my_drawing_code_manipulating_ctx(ctx)

einkdraw.layout.dummy()

Args:

name (str): The name to use.

Kwxxxargs:

state (bool): Current state to be in.

Returns:

int. The return code:

0 -- Success!
1 -- No good.
2 -- Try again.

Raises:

AttributeError, KeyError

A really great idea. A way you might use me is

>>> print public_fn_with_googley_docstring(name='foo', state=None)
0

BTW, this always returns 0. NEVER use with MyPublicClass.

eInkDraw Glyph Classes

Glyphs are simple graphic primitives that display text or graphics.

class einkdraw.glyphs.Icon(width, height, icon=None)

Draw an icon from a cairo.SurfaceObject.

Args:

width (int): Width of the object.

height (int): Height of the object.

icon (cairo.SurfaceObject): Image to draw.

Note

Currently this performs no clipping. If an image is passed in that is larger, it will overwrite objects outside the Icon’s bounding box.

draw(ctx)

Draw the content of this object to a pycairo Drawing context.

Args:

self (pycairo.Context): The drawing context to draw on.

get_bbox()

Return the size of the bounding box for this drawable.

Returns:

(int, int) Width and height of the bounding box.

set_value(icon)

Set the image to draw.

Args:

icon (cairo.SurfaceObject): Image to draw.

class einkdraw.glyphs.Label(text, width=100, height=16, face=<cairo.ToyFontFace object>, alignment='centered', inverse=False, text_color=None, clip_text=False, descenders=True)

A Label is a glyph that can show a line of text.

Args:

text (str):

Inital text to display. Can later be overriden with a call to set_value.

width (int):

Width of the label’s bounding box.

height (int):

Height of the label’s bounding box.

face (FontFace):

The font used to draw the text in the glyph.

alignment (one of “left”, “right”, “centered”):

Alignment of the text within the Label’s bounding box.

inverse (bool):

By default the text is drawn black on white. If this argument is set to true, it is drawn white on black.

text_color (any of Background.PATTERN_XXX constants):

Specifies the color to use to draw the text.

clip_text (bool):

If this is set to False, the font size of the text will be scaled such that it will fit within the bounding box.

descenders (bool):

If set to true, then text scaling will be done in a way such that the algorithm is aware of descenders that might be in the text. (Descenders are elements of letters in a font that extend below the base line). – Setting this to True will ensure that when displaying something like like “Text” (with no descenders), followed by another value like “quality” (with descenders) will not cause the text’s base line to jump around.

In some cases a Label might only show text without descenders (for example when it is only displaying numeric values. In this case descenders an be set to False, to force the base line of the text to be aligned with the lower boundary of the Label.

Note

When using clip_text=False or when specifying desceners=False and then specifying a text that has descenders might cause text to extend beyond the Label’s bounding box.

draw(ctx)

Draw the content of this object to a pycairo Drawing context.

Args:

self (pycairo.Context): The drawing context to draw on.

get_bbox()

Return the size of the bounding box for this drawable.

Returns:

(int, int) Width and height of the bounding box.

eInkDraw User Interface Elements

More complex user interface elements like windows, date/time related elements and various forms of charts.

class einkdraw.uielements.Barchart(height=None, width=None, bar_width=5, min_val=0, max_val=100, categories=(), mapping=<function linear_mapping>)

This class draws a bar chart from a series of values.

Bar charts can either be oriented horizontally, with bars growing from top to bottom, or vertically, with bars groing from left to right.

Args:

height (int):

Height of the barchart if the chart is a horizontal bar chart. (In this case width should be set to None, since it is computed by len(categories) * bar_width).

width (int):

Width of the barchart if the chart is a vertical bar chart (In this case height should be set to None, since it is computed by len(categories) * bar_width).

bar_width (int):

Width of each bar.

min_val (int):

Minimum value for the base line of the bar chart (zero height bar). Smaller values will be clipped to this.

max_val (int):

Maximum value for the bar chart (full height bar). Larger values will be clipped to this.

categories ([layout.Drawable]):

A list of Drawable instances that can be resized. Each entry in the list represents one bar. A bar will be drawn in the right size by resizing the Drawable corresponding to it, and drawing it.

mapping (f(x, x_min, x_max, y_min, y_max)):

A mapping function that maps values to display to drawable values. By default, a linear mapping function is used. Specifying other mapping functions would enable logarithmic charts, for example.

Note

The number of elements passed into “set_value” must match the number of categories specified when the object was constructed.

draw(ctx)

Draw the content of this object to a pycairo Drawing context.

Args:

self (pycairo.Context): The drawing context to draw on.

get_bbox()

Return the size of the bounding box for this drawable.

Returns:

(int, int) Width and height of the bounding box.

set_value(values)

Specify the values to display in the bar chart

Args:

values ([float]):

List of numbers, one for each category.

class einkdraw.uielements.BatteryIndicator(unit_size=4, num_ticks=4, foreground=<cairo.SurfacePattern object>, background=<cairo.SurfacePattern object>, bar=<cairo.SurfacePattern object>)

draw(ctx)

Draw the content of this object to a pycairo Drawing context.

Args:

self (pycairo.Context): The drawing context to draw on.

get_bbox()

Return the size of the bounding box for this drawable.

Returns:

(int, int) Width and height of the bounding box.

class einkdraw.uielements.Calendar(width, height, auto_time=True, day_face=<cairo.ToyFontFace object>, minor_face=<cairo.ToyFontFace object>, day_background=None, minor_background=None, offset=0)

A Calendar widget displaying the current month, day and weekday.

Args:

width (int):

Width of the widget.

height (int):

Height of the widget.

auto_time (bool):

If true, the current date is used to render the widget when its draw method is called.

day_face (FontFace):

Font to use to draw the current day of the month.

minor_face (FontFace):

Font to use to draw the month name and the weekday name.

day_background (any of Background.PATTERN_XXX):

Background pattern to use to draw the background for the day of month part of the widget.

minor_background (any of Background.PATTERN_XXX):

Background pattern to use to draw the background for the name of month and the weekday part of the widget.

offset (int):

Offset (in seconds) to add to the current time when auto_time is set to True. This can be used to compensate for rendering delays on slower platforms.

draw(ctx)

Draw the content of this object to a pycairo Drawing context.

Args:

self (pycairo.Context): The drawing context to draw on.

set_value(day=None, weekday=None)

Set the current day of month, month and weekday.

Args:

month (int):

Number of the month. Values from 1 to 12 are valid.

day (int):

Day of the month. Values from 1 to 31 are valid. There is no cross-check whether the date is actually valid. (You could set a Feb. 31st, for example).

weekday (int):

Weekday Values from 0 to 6 are valid, with 0 being Monday, 6 being Sunday.

Note

If auto_time was set to true when instantiating a Calendar object, then calling this function has no effect, since calling draw will cause any value specified to be overridden with the current date.

class einkdraw.uielements.Clock(width, background=None, major_ticks=10, minor_ticks=6, auto_time=True, offset=0)

Draw an analog clock.

Args:

width (int):

Width of the clock. Note that the clock is round, so height will be the same value.

background (any of layout.Background.PATTERN_XX):

Pattern to use to draw the background of the clock’s face. Note that None means transparent (PATTERN_TRANSPARENT).

major_ticks (int):

Size of the major tickmarks at the 12, 3, 6 and 9 o’clock position.

minor_ticks (int):

Size of all the other (minor) tickmarks.

auto_time (bool):

If true, the current time is always displayed. In this case set_value is basically ignored.

offset (int):

Offset (in seconds) to add to the current time when auto_time is set to True. This can be used to compensate for rendering delays on slower platforms.

draw(ctx)

Draw the content of this object to a pycairo Drawing context.

Args:

self (pycairo.Context): The drawing context to draw on.

get_bbox()

Return the size of the bounding box for this drawable.

Returns:

(int, int) Width and height of the bounding box.

set_value(hour, minute)

Unless auto_time was set to true, this adjusts the clock’s value.

Args:

hour (int):

Hour to display.

minute (int):

Minute to display.

Note

You can set the clock to values like “22:37” or even “54:87”: The value is in any case converted to “minutes since midnight”, and analog clocks imply a “modulo 12 hours” anyways.

class einkdraw.uielements.Gauge(width=None, height=None, chart_type='pie', gauge_thickness=20, min_val=0, max_val=100, mapping=<function linear_mapping>, face=None, value_format=None, units='', background=None, foreground=<cairo.SurfacePattern object>)

Draw a gauge-style element, to display a numeric value within a range.

Gauges can either be circular, semi-circular or a setting in between.

Args:

width (int):

Width of the gauge.

height (int):

Height of the gauge.

chart_type (str):

Any of “semicircular”, “pie” or “circular”.

gauge_thickness (int):

Thickness of the actual ring scale.

min_val (float):

Minimum value corresponding to the lower limit of the gauge.

max_val (float):

Maximum value corresponding to the upper limit of the gauge.

face (cairo.FontFace):

Font to sue for outputting the current value of the gauge. None for default font.

value_format (str):

Python string “format” specifier, to turn the current gauge value into a printable string. – For example to output a value as “XX.X”, use python’s float format string “2.1f”.

units (str):

If set, identifies the units to display for the gauge value (ie: “mph”, “mbar”, etc… – Units are displayed in slightly smaller font than the actual value.

background (any of layout.Background.PATTERN_XXX):

Pattern to use to draw the background of the actual gauge. None is equivalent to transparent.

foreground (any of layout.Background.PATTERN_XXX):

Pattern to use to draw the foreground of the gauge (ie: the graphical representation of the current value).

mapping (f(x, x_min, x_max, y_min, y_max)):

A mapping function that maps values to display to drawable values. By default, a linear mapping function is used. Specifying other mapping functions would enable logarithmic charts, for example.

Note

Only one of the “width” or the “height” properties should be set, since setting one also determines the other, because of the circular shape of a Gauge.

draw(ctx)

Draw the content of this object to a pycairo Drawing context.

Args:

self (pycairo.Context): The drawing context to draw on.

get_bbox()

Return the size of the bounding box for this drawable.

Returns:

(int, int) Width and height of the bounding box.

class einkdraw.uielements.Window(title, content, title_height=19, frame_width=1)

A window consists of a title bar, a frame around its content and an embedded Drawable instance, representing the content of the window.

Args:

title (str):

Name of window to appear in title bar.

content (layout.Drawable):

Content of the window.

title_height (int):

Height of the title bar.

frame_width (int):

Width of the window border.

einkdraw.uielements.linear_mapping(x, x_min, x_max, y_min, y_max)

A function performing a linear mappnig for a value x from the interval [x_min,x_max] to the interval [y_min,y_max].

eInkDraw Bitmap Fonts

Using vectorized fonts for small text on low-resolution monochrome displays gives poor results. Therefore einkdraw integrates bitmapped fonts from the Adafruit GFX Library.

The only class you need to worry about as a user of this library is the FontManager and the get_font method.

class einkdraw.fonts.FontManager(font_dir='/home/ceci/projects/pillow/modules/einkdraw/einkdraw/Fonts')

A class through which GfxFont instances can be located.

Given a family name, italic/bold settings and a max. size, the font manager finds the closest match for a bitmapped Adafruit font.

find_font(group='Mono', bold=False, italic=False, descend=True, max_size=99)

Find a font matching a description:

Args:

group (str)

Either an Adafruit font group (Mono/Sans/Serif) or one of the small font names (Orgdot/Picopixel/Tiny/TomThumb).

bold (bool)

True if looking for the bold version of a font.

italic (bool)

True if looking for the italic version of a font.

descend (bool)

If True, take descenders (characters descending BELOW the writing line) into account when finding a matching font size.

max_size (int)

Maximum font size allowed.

Result:

Returns a GfxFont class instances or None, if no matching font could be found.

static get()

Obtain the font manager instance.

class einkdraw.fonts.GfxFont(file_name)

This class represents an Adafruit bitmap font. A very naive code parses the corresponding Adafruit font header and initializes the font class.

draw_text(ctx, txt)

Render a text using a pycairo.Context

Params:

ctx (pycairo.Context)

Context on which to render a text.

get_dimensions(txt, normalize=False)

Get dimensions for a given text.

Params:

txt (str)

Text for which to return dimensions.

normalize (bool)

If False (default) the height, ascend and descend are calculated from the text specified ONLY. If True, height, ascend and descend are calculated using the maximum values for the font.

This is helpful for font layout, since it prevents text from “jumping up and down” on labels should the text change (“foobar” vs. “quilt”, for example).

Result:

Returns a typle equivaltent to pycairo’s Context.text_extent. (Top left corner offset for text bounding box from current position, width, height of bounding box around text, x and y amount by which the current position should be advanced after drawing the text.

class einkdraw.fonts.Glyph(parent, defs)

A Glyph represents a symbol in a font.

get_img()

Return a cairo.Imagesruface (FORMAT_A1) representing the Glyph.

einkdraw.fonts.run()

Test/Sample code.

eInkDraw Logging

Set the logging object to be used by the library.

einkdraw.logger.set_logger(log)

Set the logging object to be used by the library.

It is recommended to call this function before invoking any other library functions,

Params:

log (logging.Logger)

Logging object to use.

eInkDraw Constants

Module-wide constants used in eInkDraw.