Symbol

Symbol is a layer that displays an image that always remains at the same size no matter what sublayer transformation is applied at the Container level. Symbols should be used when visually identical shapes need to be displayed multiple times within a view. For example, if displaying the points of a glyph as squares, instead of creating Rectangle sublayers, Symbol layers with the same image settings should be created. The images are not created directly and inserted into the Symbol. The images is created by image factories based on the layer’s image settings. This allows for the reuse of images which greatly increases rendering speed.

Discussion

Properties

Refer to the properties concepts section for an overview of properties.

`setPropertiesByName`(properties, **kwargs)	Set the value of multiple properties by name.
`setPropertyByName`(name, value, **kwargs)	Set property `name` with `value`.
`propertyGroup`([name, duration, timing, …])	Create a context manager that allows setting multiple properties in an efficient way.

Identification

`getName`([makeIfNeeded])	Get the name assigned to this layer during `__init__`.
`setInfoValue`(key, value)	Set `key : value` in this layer’s info dictionary.
`getInfoValue`(key[, fallback])	Set `key` from the arbitrary info dictionary.

Geometry

Refer to the geometry concepts section for an overview of geometry.

`getAnchor`()	Get the anchor of the layer.
`setAnchor`(value)	Set the anchor of the layer.
`getPosition`()	Get the position of this layer.
`setPosition`(position)	Set the position of this layer.
`getSize`()	Get the size of this layer.
`setSize`(size)	Set the Size of this layer.

Transformations

`getTransformations`()	Get a list of all transformations.
`addTransformation`(transformation, name[, center])	Add a transformation with `name` that applies to this layer and all of its sublayers.
`removeTransformation`(name)	Remove the transformation with `name`.
`addTranslationTransformation`(value[, name])	Add a translate transformation with `name`.
`addScaleTransformation`(value[, name, center])	Add a scale transformation with `name` and `center`.
`addRotationTransformation`(value[, name, center])	Add a rotation transformation with `name` and `center`.
`addSkewTransformation`(value[, name, center])	Add a skew transformation with `name` and `center`.
`addSublayerTransformation`(transformation, name)	Add a transformation with `name` that applies to all of this layer’s sublayers.
`removeSublayerTransformation`(name)	Remove the transformation with `name`.
`addSublayerTranslationTransformation`(value)	Add a sublayer translate transformation with `name`.
`addSublayerScaleTransformation`(value[, …])	Add a sublayer scale transformation with `name` and `center`.
`addSublayerRotationTransformation`(value[, …])	Add a sublayer scale transformation with `name` and `center`.
`addSublayerSkewTransformation`(value[, name, …])	Add a sublayer skew transformation with `name` and `center`.

Frame

`getVisible`()	Get if the layer is visible.
`setVisible`(value)	Set if the layer is visible.
`getMaskToFrame`()	Get if the layer hides any sublayer data outside of its frame.
`setMaskToFrame`(value)	set if the layer hides any sublayer data outside of its frame.
`getOpacity`()	Get the opacity of this layer.
`setOpacity`(value)	Set the opacity of this layer,
`getBackgroundColor`()	Get the background color for this layer.
`setBackgroundColor`(color)	Set the background color for this layer.
`getBorderColor`()	Get the border color for this layer.
`setBorderColor`(color)	Set the border color for this layer.
`getBorderWidth`()	Get the border width for this layer.
`setBorderWidth`(value)	Set the border width for this layer.
`getCornerRadius`()	Get this corner radius of this layer.
`setCornerRadius`(value)	Set the corner radius of this layer.

Shadow

`getShadowColor`()	Get the shadow color for this layer.
`setShadowColor`(color)	Set the shadow color for this layer.
`getShadowOpacity`()	Get the shadow opacity for this layer.
`setShadowOpacity`(value)	Set the shadow opacity for this layer.
`getShadowOffset`()	Get the shadow offset for this layer.
`setShadowOffset`(offset)	Set the shadow offset for this layer.
`getShadowBlurRadius`()	Get the shadow blur radius for this layer.
`setShadowBlurRadius`(value)	Set the shadow blur radius for this layer.

Filters

Refer the filter documentation in Base for complete details.

`getCompositingMode`()	Set the compositing filter for the layer.
`setCompositingMode`(filterType)	Set the compositing filter for the layer.
`getFilters`()	Get a list of the filters for this layer.
`setFilters`(allFilterSettings)	Set a list of the filters for this layer.
`appendFilter`(filterSettings)	Append a filter to this layer.
`getFilter`(name)	Get the filter with `name` from this layer.
`removeFilter`(name)	Remove the filter with `name` from this layer.
`clearFilters`()	Clear all background filters from this layer.
`getBackgroundFilters`()	Get a list of the background filters for this layer.
`setBackgroundFilters`(allFilterSettings)	Set a list of the background filters for this layer.
`appendBackgroundFilter`(filterSettings)	Append a background filter to this layer.
`getBackgroundFilter`(name)	Get the background filter with `name` from this layer.
`removeBackgroundFilter`(name)	Remove the background filter with `name` from this layer.

Image Settings

Symbol.getImageSettings(): Get the image settings for this layer.

Symbol.setImageSettings(settings)

Set the image settings for this layer. Image settings are defined as dictionaries of "settingName" : value pairs. Each settings dictionary must have a "name" key with a value matching a known image factory. Each image factory has it’s own settings. The built-in factories are:

"rectangle"

"size" : (width, height) tuple
"fillColor" : number (optional)
"strokeColor" : number (optional)
"strokeWidth" : number (optional)
"cornerRadius" : number (optional)

symbolLayer = container.appendSymbolSublayer(
    position=(250, 100)
)

symbolLayer.setImageSettings(
    dict(
        name="rectangle",
        size=(30, 30),
        fillColor=(1, 0, 0, 1)
    )
)

"oval"

"size" : (width, height) tuple
"fillColor" : color definition (optional)
"strokeColor" : color definition (optional)
"strokeWidth" : number (optional)

symbolLayer = container.appendSymbolSublayer(
    position=(250, 100)
)

symbolLayer.setImageSettings(
    dict(
        name="oval",
        size=(30, 30),
        fillColor=(1, 0, 0, 1)
    )
)

"triangle"

"size" : (width, height) tuple
"fillColor" : color definition (optional)
"strokeColor" : color definition (optional)
"strokeWidth" : number (optional)

symbolLayer = container.appendSymbolSublayer(
    position=(250, 100)
)

symbolLayer.setImageSettings(
    dict(
        name="triangle",
        size=(30, 30),
        fillColor=(1, 0, 0, 1)
    )
)

"star"

"size" : (width, height) tuple
"fillColor" : color definition (optional)
"strokeColor" : color definition (optional)
"strokeWidth" : number (optional)
"pointCount" : integer (optional)
"inner" : float (optional)
"outer" : float (optional)

symbolLayer = container.appendSymbolSublayer(
    position=(250, 100)
)

symbolLayer.setImageSettings(
    dict(
        name="star",
        size=(30, 30),
        fillColor=(1, 0, 0, 1),
        pointCount=8
    )
)

It is possible to create and register custom image factories.

Symbol.getImageSettingsValue(key): Get the value for key from the symbol’s image settings.

Symbol.setImageSettingsValue(key, value): Set the value for key in the symbol’s image settings.

Symbol.getRotation(): Get the rotation of the symbol.

Symbol.setRotation(angle)

Set the rotation of the symbol.

symbolLayer = container.appendSymbolSublayer(
    position=(250, 100),
    imageSettings=dict(
        name="triangle",
        size=(30, 30),
        fillColor=(1, 0, 0, 1)
    )
)

symbolLayer.setRotation(45)

Animation

Refer to the animation concepts section for an overview of animation.

`clearAnimation`()	Remove all animations from this layer.
`stopAnimation`(name)	Stop the animation with the `name` given when the animation was created with a property group.
`isAnimationPaused`()	Get if animation is currently paused for this layer.
`pauseAnimation`()	Pause the animation of this layer.
`resumeAnimation`()	Resume the animation of the layer.

Sublayers

Refer to the layer hierarchy concepts section for an overview of sublayers.

`sublayerGroup`([sublayers])	Place a hold on adding the sublayers to this layer’s CALayer until the context manager exits.
`getSublayers`()	Get all sublayers within this layer.
`getSublayer`(name)	Get the sublayer with `name`.
`clearSublayers`()	Remove all sublayers within this layer.
`removeSublayer`(sublayer)	Remove the given sublayer from the layer.
`appendSublayer`(sublayer)	Append an instantiated sublayer to this layer.
`appendSublayerOfClass`(layerClass, **kwargs)	Append a sublayer to this layer.
`appendBaseSublayer`(**kwargs)	Append a base layer.
`appendPathSublayer`(**kwargs)	Append a path layer.
`appendLineSublayer`(**kwargs)	Append a line layer.
`appendOvalSublayer`(**kwargs)	Append a oval layer.
`appendRectangleSublayer`(**kwargs)	Append a rectangle layer.
`appendImageSublayer`(**kwargs)	Append an image layer.
`appendTextBoxSublayer`(**kwargs)	Append a text box.
`appendTextLineSublayer`(**kwargs)	Append a text line.
`appendSymbolSublayer`(**kwargs)	Append a symbol.
`drawingTools`([clear])	This creates a context manager that provides a sublayer creation syntax that supports a subset of the DrawBot API.

Superlayers

Refer to the layer hierarchy concepts section for an overview of superlayers.

`getContainer`()	Get the Container that this layer belongs to.
`getSuperlayer`()	Get the layer that this layer belongs to.

Hit Testing

CoreAnimation Object

getCALayer()

Get the CALayer that this object wraps.

Custom Symbols

If you need a symbol that is not available from the built-in symbols, it’s possible to define your own. To do this, you create a function that will generate an image and register it with the Merz symbol vendor. Here’s an example:

import merz
from merz.tools.drawingTools import NSImageDrawingTools

def mySymbolImageFactory(
        size,
        color=(0, 0, 0, 1),
        backgroundColor=(1, 1, 1, 1),
        showDot=True,
        **kwargs
    ):
    if backgroundColor is None:
        backgroundColor = (0, 0, 0, 0)
    width, height = size
    bot = NSImageDrawingTools(size)
    bot.fill(*backgroundColor)
    bot.oval(0, 0, *size)
    bot.fill(None)
    bot.stroke(*color)
    bot.strokeWidth(2)
    bot.oval(1, 1, width-2, height-2)
    if showDot:
        dotWidth = width / 4
        dotHeight = height / 4
        dotX = (width - dotWidth) / 2
        dotY = (height - dotHeight) / 2
        bot.stroke(None)
        bot.fill(*color)
        bot.oval(dotX, dotY, dotWidth, dotHeight)
    image = bot.getImage()
    return image

merz.SymbolImageVendor.registerImageFactory("com.myDomain.mySymbol", mySymbolImageFactory)

Your function needs to take size as the first argument, any keyword arguments you need and then **kwargs at the end. (The **kwargs there is a fallback in case someone switches the name in their existing Symbol image settings and forget to remove unnecessary key value pairs.) A NSImage must be returned by your function. To make this easier, NSDrawingTools is a DrawBot inspired class that simplifies the drawing. These are the supported commands:

savedState()
fill(r=None, g=None, b=None, a=1)
stroke(r=None, g=None, b=None, a=1)
strokeWidth(value)
lineJoin(join)
lineCap(cap)
lineDash(*arg)
transform(transform, center=None)
translate(x=0, y=0)
rotate(angle, center=None)
scale(x=1, y=None, center=None)
skew(angle1, angle2=0, center=None)
rect(x, y, w, h)
roundedRect(x, y, w, h, radius)
oval(x, y, w, h)
newPath():
moveTo(pt)
lineTo(pt)
curveTo(h1, h2, pt)
arc(center, radius, startAngle, endAngle, clockwise)
closePath()
endPath()
BezierPath(glyphSet=None)
line(pt1, pt2)
polygon(xy, *args, **kwargs)
drawGlyph(glyph)
drawPath(path=None)

Once your factory is registered you can use your symbol in the same way as you use the built-in symbols:

container.appendSymbolSublayer(
    position=(100, 100),
    imageSettings=dict(
        name="com.myDomain.mySymbol",
        size=(20, 20),
        color=(1, 0, 0, 1),
        backgroundColor=None
    )
)
container.appendSymbolSublayer(
    position=(250, 100),
    imageSettings=dict(
        name="com.myDomain.mySymbol",
        size=(40, 40),
        color=(0, 1, 0, 1),
        backgroundColor=(1, 1, 0, 1)
    )
)
container.appendSymbolSublayer(
    position=(400, 100),
    imageSettings=dict(
        name="com.myDomain.mySymbol",
        size=(20, 20),
        color=(0, 0, 1, 1),
        backgroundColor=(1, 1, 0, 1),
        showDot=False
    )
)

The symbol will use the center of the image as its alignment point.