The Surface Composition Module

Easy Image Composition

The purpose of this module is to make it easy to compose the frames that are displayed in a paradigm. For an introduction, please refer to the tutorial

class pyparadigm.surface_composition.Border(width=3, color=0)

Draws a border around the contained area. Can have a single child.

Parameters:

• width (int) – width of the border in pixels
• color (pygame.Color) – color of the border

class pyparadigm.surface_composition.Circle(color, width=0)

Draws a Circle in the assigned space.

The circle will always be centered, and the radius will be half of the shorter side of the assigned space.

Parameters:

• color (pygame.Color or int) – The color of the circle
• width (int) – width of the circle (in pixels). If 0 the circle will be filled

pyparadigm.surface_composition.Cross(width=3, color=0)

Draws a cross centered in the target area

Parameters:

• width (int) – width of the lines of the cross in pixels
• color (pygame.Color) – color of the lines of the cross

class pyparadigm.surface_composition.FRect(x, y, w, h)

A wrapper Item for children of the FreeFloatLayout, see description of FreeFloatLayout

class pyparadigm.surface_composition.Fill(color)

Fills the assigned area. Afterwards, the children are rendered

Parameters:color (pygame.Color or int) – the color with which the area is filled

pyparadigm.surface_composition.Font

Unifies loading of fonts.

Parameters:

• name (str) – name of system-font or filepath, if None is passed the default system-font is loaded
• source (str) – “sys” for system font, or “file” to load a file

class pyparadigm.surface_composition.FreeFloatLayout

A “Layout” that allows for free positioning of its elements. All children must be Wrapped in an FRect, which takes a rects arguments (x, y, w, h), and determines the childs rect. All values can either be floats, and must then be between 0 and 1 and are relative to the rect-size of the layout, positive integers, in which case the values are interpreded as pixel offsets from the layout rect origin, or negative integers, in which case the absolute value is the available width or height minus the value

pyparadigm.surface_composition.GridLayout(row_proportions=None, col_proportions=None, line_width=0, color=0)

Layout that arranges its children on a grid.

Proportions are given as lists of integers, where the nth element represents the proportion of the nth row or column.

Children are added in lists, every list represents one row, if row or column proportions are provided, the number of rows or columns in the children must match the provided proportions. To define an empty cell use None as child.

If no column proportions are provided, rows can have different lengths. In this case the width of the layout will be the length of the longest row, and the other rows will be filled with Nones

class pyparadigm.surface_composition.LLItem(relative_size)

Defines the relative size of an element in a LinLayout

All Elements that are passed to a linear layout are automatically wrapped into an LLItem with relative_size=1. Therefore by default all elements within a layout will be of the same size. To change the proportions a LLItem can be used explicitely with another relative size.

It is also possible to use an LLItem as placeholde in a layout, to generate an empty space like this:

Example:

LinLayout(“h”)(

LLItem(1), LLItem(1)(Circle(0xFFFF00)))

class pyparadigm.surface_composition.LinLayout(orientation)

A linear layout to order items horizontally or vertically.

Every element in the layout is automatically wrapped within a LLItem with relative_size=1, i.e. all elements get assigned an equal amount of space, to change that elements can be wrappend in LLItems manually to get desired proportions

Parameters:orientation (str) – orientation of the layout, either ‘v’ for vertica, or ‘h’ for horizontal.

class pyparadigm.surface_composition.Line(orientation, width=3, color=0)

Draws a line.

Parameters:

• width – width of the line in pixels
• orientation (str) – “v” or “h”. Indicates whether the line should be horizontal or vertical.

class pyparadigm.surface_composition.Margin(left=1, right=1, top=1, bottom=1)

Defines the relative position of an item within a Surface. For details see Surface.

class pyparadigm.surface_composition.Overlay(*children)

Draws all its children on top of each other in the same rect

class pyparadigm.surface_composition.Padding(left, right, top, bottom)

Pads a child element

Each argument refers to a percentage of the axis it belongs to. A padding of (0.25, 0.25, 0.25, 0.25) would generate blocked area a quater of the available height in size above and below the child, and a quarter of the available width left and right of the child.

If left and right or top and bottom sum up to one that would mean no space for the child is remaining

static from_scale(scale_w, scale_h=None)

Creates a padding by the remaining space after scaling the content.

E.g. Padding.from_scale(0.5) would produce Padding(0.25, 0.25, 0.25, 0.25) and Padding.from_scale(0.5, 1) would produce Padding(0.25, 0.25, 0, 0) because the content would not be scaled (since scale_h=1) and therefore there would be no vertical padding.

If scale_h is not specified scale_h=scale_w is used as default

Parameters:

• scale_w (float) – horizontal scaling factors
• scale_h (float) – vertical scaling factor

class pyparadigm.surface_composition.RectangleShaper(width=1, height=1)

Creates a padding, defined by a target Shape.

Width and height are the relative proportions of the target rectangle. E.g RectangleShaper(1, 1) would create a square. and RectangleShaper(2, 1) would create a rectangle which is twice as wide as it is high. The rectangle always has the maximal possible size within the parent area.

class pyparadigm.surface_composition.Surface(margin=<pyparadigm.surface_composition.Margin object>, scale=0, smooth=True, keep_aspect_ratio=True)

Wraps a pygame surface.

The Surface is the connection between the absolute world of pygame.Surfaces and the relative world of the composition functions. A pygame.Surfaces can be bigger than the space that is available to the Surface, or smaller. The Surface does the actual blitting, and determines the concrete position, and if necessary (or desired) scales the input surface.

Warning: When images are scaled with smoothing, colors will change decently, which makes it inappropriate to use in combination with colorkeys.

Parameters:

• margin (Margin object) – used to determine the exact location of the pygame.Surfaces within the available space. The margin value represents the proportion of the free space, along an axis, i.e. Margin(1, 1, 1, 1) is centered, Margin(0, 1, 1, 2) is as far left as possible and one/third on the way down.
• scale (float) – If 0 < scale <= 1 the longer side of the surface is scaled to to the given fraction of the available space, the aspect ratio is will be preserved. If scale is 0 the will be no scaling if the image is smaller than the available space. It will still be scaled down if it is too big.
• smooth (float) – if True the result of the scaling will be smoothed

pyparadigm.surface_composition.Text(text, font, color=(0, 0, 0, 255), antialias=False, align='center')

Renders a text. Supports multiline text, the background will be transparent.

Parameters:align (str) – text-alignment must be “center”, “left”, or “righ” Returns:the input text Return type:pygame.Surface

pyparadigm.surface_composition.compose(target, root=None)

Top level function to create a surface.

Parameters:target – the pygame.Surface to blit on. Or a (width, height) tuple in which case a new surface will be created