sim.drawable module¶

Module drawable contains a supporting class Drawable that defines a drawable to be placed on the canvas of the scenario. This class provides the drawable specification which can be a shape, text or bitmap image. Adding and removing a drawable instance can be done using the methods specified in sim.scenario.BaseScenario.

There are two classes given in this module:

Draw: it provides constants for user simulation to use.

Drawable: it is a drawable object that the user simulation can create and define. After defining the object, the user simulation can add to the scenario using add drawable method specified in sim.scenario.BaseScenario. For example:

class MyScenario(BaseScenario):

    ## create a scenario
    def on_create(self, simworld) -> bool:

        ## add a persistent text on the scenario
        self.add_drawable(Drawable()
                .text(x,y,"My Landmark",position=Draw.XYCENTER)
                .set_font(wx.Font(16,   wx.FONTFAMILY_ROMAN, 
                                        wx.FONTSTYLE_NORMAL, 
                                        wx.FONTWEIGHT_NORMAL)))

Note

Created by: CH Foh (2021)

class sim.drawable.Draw¶

Bases: object

This is a static class containing drawable contants. It provide constants for the Drawable class of this module and some handy functions.

BEHIND = 0¶: Draw behind the nodes.

ABOVE = 1¶: Draw above the nodes.

XLEFT = 1¶: Position the left side of the drawable at the point x.

XRIGHT = 2¶: Position the right side of the drawable at the point x.

XCENTER = 4¶: Position the center the drawable at the point x.

YTOP = 8¶: Position the top side of the drawable at the point y.

YBOTTOM = 16¶: Position the bottom side of the drawable at the point y.

YCENTER = 32¶: Position the center the drawable at the point y.

XYCENTER = 36¶: Position the center of the drawable at the given (x,y). This is the same as applying XCENTER|YCENTER.

class sim.drawable.Drawable¶

Bases: object

Attributes

appearance: This property is used to describe whether the drawable should appear behind or above the nodes.
layer: This property is used to specify directly which screen layer should be used to put the drawable.

Methods

`circle`(x, y, radius)	Make this drawable to be a circle on the scenario background.
`line`(x1, y1, x2, y2)	Make this drawable to be a line on the scenario background.
`many_circles`(list_of_xy, radius)	Make this drawable to be a number of circles having the same radius on the scenario background.
`many_lines`(list_of_xy)	Make this drawable to be a series of lines on the scenario background.
`polygon`(list_of_xy)	Make this drawable to be a polygon on the scenario background.
`set_drawing`(pen[, brush, layer, appearance])	Set how a drawable shape is drawn on the screen.
`set_font`(font[, foreground, background])	Set how a drawable text is written on the screen.
`sim__draw`(dc)	Call this method to execute the drawing of this instance to the provided device context.
`text`(x, y, text, position)	Make this drawable to be a text on the scenario background.

__init__()¶: Initialize self. See help(type(self)) for accurate signature.

property layer¶: This property is used to specify directly which screen layer should be used to put the drawable. Drawables at the lower layer will be drawn first, and thus they will appear behind those drawables at the higher layer. Use this property to group and arrange the drawables.

property appearance¶: This property is used to describe whether the drawable should appear behind or above the nodes. See sim.drawable.Draw class which specifies the constants.

set_drawing(pen, brush=None, layer=0, appearance=0)¶

Set how a drawable shape is drawn on the screen. This method allows setting of a pen and a brush.

The pen is used to draw border of a shape, and the brush is used to fill the shape (for a closed shape). See wx.Pen and wx.Brush in wxPython to find out how to construct them.

Parameters

penwx.Pen: The pen object defined in wxPython.
brushwx.Brush, optional, default=None: The brush object defined in wxPython. If not provided, a transparent brush will be used.
layerint, optional, default=0: The logical screen layer to put this drawable. The class also exposes layer as a property, and thus the setting can be changed separately.
appearanceconstant int, optional, default=Draw.BEHIND: The appearance of the drawable, whether in front or at the back of nodes. The class also exposes appearance as a property, and thus the setting can be changed separately. See sim.drawable.Draw for the possible options. If not provided, Draw.BEHIND will apply.

Returns

sim.drawable.Drawable: It returns self, which can be useful when constructing it as an anonymous variable.

set_font(font, foreground=None, background=None)¶

Set how a drawable text is written on the screen. This method allows setting of a font type, foreground and background colors of the text.

See wx.Font in wxPython to find out how to set a font type. For foreground and background, see wx.Colour.

Parameters

fontwx.Font: The font object defined in wxPython.
foreground, backgroundwx.Colour, optional, default=None: The text color and the background color of text. If not provided, the method will use the color defined in the pen for the foreground text color, and set transparent for the background.

Returns

sim.drawable.Drawable: It returns self, which can be useful when constructing it as an anonymous variable.

circle(x, y, radius)¶

Make this drawable to be a circle on the scenario background. Use set_drawing() to pick a pen and brush for the drawing.

Parameters

x, yint: The location of the circle center.
radiusfloat: The radius of the circle.

Returns

sim.drawable.Drawable: It returns self, which can be useful when constructing it as an anonymous variable.

many_circles(list_of_xy, radius)¶

Make this drawable to be a number of circles having the same radius on the scenario background. Use set_drawing() to pick a pen and brush for the drawing.

Parameters

list_of_xyList[Tuple[int,int]]: A list of (x,y) tuples each describing the center of a circle.
radiusfloat: The radius of all the circles to draw.

Returns

sim.drawable.Drawable: It returns self, which can be useful when constructing it as an anonymous variable.

line(x1, y1, x2, y2)¶

Make this drawable to be a line on the scenario background. Use set_drawing() to pick a pen and brush for the drawing.

Parameters

list_of_xyList[Tuple[int,int]]: A list of (x,y) tuples describing a list of line segments.

Returns

sim.drawable.Drawable: It returns self, which can be useful when constructing it as an anonymous variable.

many_lines(list_of_xy)¶

Make this drawable to be a series of lines on the scenario background. Use set_drawing() to pick a pen and brush for the drawing.

Parameters

list_of_xyList[Tuple[int,int]]: A list of (x,y) tuples describing a list of line segments.

Returns

sim.drawable.Drawable: It returns self, which can be useful when constructing it as an anonymous variable.

polygon(list_of_xy)¶

Make this drawable to be a polygon on the scenario background. Use set_drawing() to pick a pen and brush for the drawing.

Parameters

list_of_xyList[Tuple[int,int]]: A list of (x,y) tuples describing vertices of the polygon.

Returns

sim.drawable.Drawable: It returns self, which can be useful when constructing it as an anonymous variable.

text(x, y, text, position)¶

Make this drawable to be a text on the scenario background. Use set_font() to pick a font type and colors for the writing.

Parameters

x, yint: The location of text.
textstr: The text to write onto the scenario background.
positioncontants defined in sim.drawable.Drawable: The position of text alignment. The alignment constants are defined in sim.drawable.Draw. To align the text so that its left-bottom position is at the given (x,y), provide the position as Draw.XLEFT|Draw.YBOTTOM.

Returns

sim.drawable.Drawable: It returns self, which can be useful when constructing it as an anonymous variable.

sim__draw(dc)¶

Call this method to execute the drawing of this instance to the provided device context. This method is used by the simulation engine to put a drawable onto the screen.

Note

There is no reason why user simulation needs to use this method. User simulation has no access to the dc of the scenario and therefore calling this method does not do anything to the scenario.

Parameters

dcwx.DC: The device context of the scenario currently showing on the screen.