8. The module `svgcommmon`¶

(defined in svgcommon.py)

This section explains the contents of the module svgcommon, which is used by web app games to display and control the properties of SVG images, and, indirectly, any other graphical objects (e.g. raster images).

Note

If you only require a sequence or regular grid of graphical elements (including images) for your web app, without any overlapping images and without any animation, you do not need any functions from this module can instead just create a TextImageSeq object as described in section “The namedtuple TextImageSeq”.

8.1. The function `create_svg_instance()`¶

This function returns a new (blank) SVG object into which other SVG objects and images can be positioned, overlaid, and animated.

8.1.1. Parameters of `create_svg_instance()`¶

The parameters of create_svg_instance() are as follows.

id: A str: A str to be used as the DOM id of this SVG object.
x: An int, optional, default 0: The x coordinate of the top left corner of this SVG object, relative to its parent SVG (if any).
y: An int, optional, default 0: The y coordinate of the top left corner of this SVG object, relative to its parent SVG (if any).
width: An int, optional, default 200: The width of the SVG object.
height: An int, optional, default 200: The height of the SVG object.

8.1.2. Returned from `create_svg_instance()`¶

SVG: The function returns an empty SVG DOMNode object (with <svg> tag) into which other SVG elements can be added as children.

8.1.3. Examples¶

In file justreverse/webapp/__init__.py, the function format_problem_instance() creates a new blank SVG object that has a height equal to twice the height of IM_BLOCK_SIDE and width equal to IM_BLOCK_SIDE times the number of characters in string word:

word, animation_type = game_state.custom
parent_width = IM_BLOCK_SIDE * len(word)

svg_instance = create_svg_instance(
    id='svg_instance', width=parent_width, height=IM_BLOCK_SIDE * 2
    )

In file countfromzero/webapp/__init__.py, the function format_problem_instance() creates a new blank SVG object into which an animated train object will be inserted later. Since the dimensions of the train is not known at this point, only the id is specified initially. The height and width are updated later when the dimensions of the train are known:

# This parent SVG object will be static in the DOM and its child SVG
# will be animated.
svg_instance = create_svg_instance(id='main_svg')

# Construct the train as a regular SVG and add it to the DOM
train = _construct_train_svg()
svg_instance <= train

# Set the width and height of the parent SVG object to that of the train
svg_instance.setAttribute('width', train.getAttribute('width'))
svg_instance.setAttribute('height', train.getAttribute('height'))

8.2. The function `create_image_from_file()`¶

The function create_image_from_file() is used to create a SVG image element using the contents of an external file. This SVG image element is intended to be a child of a SVG instance.

Only JPEG, PNG, and SVG image files are supported.

The image will always preserve its original aspect ratio, and its dimensions will be determined by whichever of width and :py:attr:``height` constricts it the most.

By default (when inline is False) when rendered in a browser the SVG image will appear using tag <image> inside its parent SVG instance (which will have a <svg> tag). The contents of the image will be rendered in the browser but the programmer does not have access to the image, even if the image is a SVG image.

If inline is True, and href refers to a SVG image file then the contents of the SVG image file will appear in a <svg> tag within the parent <svg> tag. This has the advantage that the programmer has access to the contents of the SVG image and so can change/replace/animate individual parts of the image.

We use the Brython syntax <= to insert a DOMNode object as a child into an existing DOMNode object. Examples are given below.

8.2.1. Parameters of `create_image_from_file()`¶

The parameters of create_image_from_file() are as follows.

id: A str: A str to be used as the DOM id of this SVG image element.
x: An int: The horizontal position of the image from the origin of the parent SVG.
y: An int: The vertical position of the image from the origin of the parent SVG.
width: An int: The maximum width of the image (actual width will depend on the value specified for height).
height: An int: The maximum height of the image (actual height will depend on the value specified for width).
href: An str: The path and filename of the external file.
angle: An int, optional, default 0: The clockwise angle, in degrees, with which to rotate the SVG image before it is rendered.
inline: A bool, optional, default False: Whether to insert the image as a link to an external file or as an inline SVG document. If False, the DOM tree will consist of a href to the graphic. If True, the DOM tree will consist of the SVG text itself, which has the advantage of exposing the XML tags in the graphic for style changes or animation.
hidden: bool, optional, default False: Whether to hide the object or not. If True then the DOM object will not be visible.

These parameters are all stored as attributes of type str in the SVG image, as is standard for DOMNode objects. If one ever wants to access them later, one can use getAttribute(), for example:

>>> my_im = create_image_from_file(
        id='cat', x=10, y=20, width=30, height=40, href='my_cat.svg'
        )
>>> my_im.getAttribute('x')
10
>>> my_im.getAttribute('height')
40
>>> my_im.getAttribute('href')
my_cat.svg

8.2.2. Returned from `create_image_from_file()`¶

SVGImageElement: The function returns a SVGImageElement DOMNode object (with <image> tag). It allows images to be included inside a SVG DOM object. It can display raster image files (JPEG or PNG) or other SVG files.

8.2.3. Examples¶

In file password/webapp/__init__.py, the function format_problem_instance() creates a SVGImageElement object using file game_icon.svg and adds it to a SVG object previously created using create_svg_instance():

(encoded_password,) = game_state.custom

svg_instance = create_svg_instance(
    id='svg_instance',
    width=130 * len(encoded_password),
    height=320,
    )

# Some code is hidden for this example

box_name = 'game_icon'
fname = IM_PATH.format(box_name)
svg_instance <= create_image_from_file(
    id=box_name, x=0, y=0, width=250, height=250, href=fname
    )

In file justreverse/webapp/__init__.py, the function format_problem_instance() makes multiple calls to create_image_from_file() to create a list of length n of SVGImageElement objects (with id values of “block_0” through “block_ n-1”). Each SVGImageElement object has the same width, height, and y position, but has a different x position that ensures the objects appear side-by-side in the web app:

word, animation_type = game_state.custom
parent_width = IM_BLOCK_SIDE * len(word)

svg_instance = create_svg_instance(
    id='svg_instance', width=parent_width, height=IM_BLOCK_SIDE * 2
    )
blocks = [
    create_image_from_file(
        id=f'block_{index}',
        x=IM_BLOCK_SIDE * index,
        y=IM_BLOCK_SIDE // 2,
        width=IM_BLOCK_SIDE,
        height=IM_BLOCK_SIDE,
        href=IM_PATH.format(letter.lower()),
        )
    for index, letter in enumerate(word)
    ]
svg_instance <= blocks

# Animation code is hidden for this example

return TextImageSeq(dom_element_seq=[svg_instance])

8.3. The function `create_group()`¶

The function create_group() is used to … TODO

8. The module svgcommmon¶

8.1. The function create_svg_instance()¶

8.1.1. Parameters of create_svg_instance()¶

8.1.2. Returned from create_svg_instance()¶

8.1.3. Examples¶

8.2. The function create_image_from_file()¶

8.2.1. Parameters of create_image_from_file()¶

8.2.2. Returned from create_image_from_file()¶