The Surface Composition module

Create pygame-surfaces in a declarative way

The purpose of this module is to make it easy to compose the frames that are displayed in a paradigm.

When you use simple pygame to write a paradigm, you will spend a lot of time writing code to compute the positions of the elemnts the surface is composed of. This module addresses this time-sink by offering a way to define these postions in a declarative way. E.g. the code

surface = Surface(screen.get_size(), LinLayout("h"))(
    LLItem(2)(red_ball),
    LinLayout("v")(
        green_ball,
        Box(scale=0.1)(green_ball), 
        green_ball),
    red_ball
) 

will create the following screen:

example

Of course there is code missing to create the balls and display the surface on screen.

The system works by returning context-objects, which all implement a draw-method. This basically creates a scene tree, where the Box-contexts are the leave-objects, and handle the actual drawing. The Layouts just call draw on their children with the correct rectangles

pyparadigm.surface_composition.Box(margin=Margin(left=1, right=1, top=1, bottom=1), scale=0, smooth=True, background=None)[source]

Wraps a pygame surface.

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

Parameters:
  • margin (Margin object) – used to determine the exact location of the surface within the box. 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
  • background (pygame.Color or compatible int) – if given the image will be filled with the color before the contents are rendered
pyparadigm.surface_composition.LLItem(relative_size)[source]

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

pyparadigm.surface_composition.LinLayout(orientation)[source]

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.Margin[source]

Defines the relative position of an item within a box, for details see Box.

pyparadigm.surface_composition.Surface(target, root=None)[source]

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