Show in Frame No Frame
Up Previous Next Title Page Index Contents Search

Creating templates
Editing templates
Template subobject settings
Template subsymbol settings
Template layout settings

3.2.9 Template

Template symbol elements offer a powerful way to construct symbols using pre-defined subsymbols that are fetched dynamically and displayed as part of the hosting symbol. These subsymbols can also act as dynamic ports for more precise role-and-object connection semantics, in a similar fashion to the existing static ports.

Basically, templates provide a set of subsymbol slots that are distributed along a template path in a user-definable order and intervals. When filling the slots, the template will first retrieve a set of objects to be allocated to the template. There are several possible sources for these subobjects: a single property, a collection property, a subgraph or a generator. Each subobject will provide a subsymbol to be displayed in its slot. A subsymbol can be the subobject type’s symbol or it can be retrieved from the symbol library. In addition to being represented within the slots by their subsymbols, the subobjects can be also revealed as dynamics ports that roles can connect to according to the binding rules.

Creating templates

A template is created by drawing the template path first and then defining the other settings from how and where the subsymbols are to be fetched and distributed along the path.

To create a template:
1)Press the Template button in the toolbar.
2)Click the cursor in the drawing area where you want the template path to begin. This places the first point for the path. You can cancel the creation at any time by pressing the right mouse button.
3)Add new breakpoints by clicking in the desired positions.
4)Complete the creation by double-clicking the left mouse button for the end of the last line segment. If you double-click on or near the first point, the path will be closed; otherwise it will be open.

Once the path definition has been completed, the template will appear as blue dotted line and have the subsymbol slots positioned according to the default distribution as in Figure 3–12.

Symbol Editor with Template

Figure 3–12. Newly created template.

Editing templates

A template path’s breakpoint operations are the same as for a polyline, so for information about them, please refer to Chapter 3–11. To edit the layout (i.e. the slot geometry and how they are distributed along the path) select Edit Layout from the template’s popup menu. Enabling the editing mode will bring the focus on the first subsymbol slot with selection handles and two additional tool handles as shown in Figure 3–13.

Template layout editing mode

Figure 3–13. Template layout editing mode.

The white selection handles manipulate the size and geometry of the subsymbol slot, and the yellow distance handles control the distance before the first slot, and the interval between the slots (if a mid-out allocation has been chose, the start distance handle will be inactive). By default the slot is center aligned: centered around the allocation points, the first two of which are shown by the distance handles. You can change the alignment by placing the cursor within the slot box, pressing and holding down the left mouse button and dragging the slot around then allocation point. By default the slot alignment snaps so either an edge or the center is on the allocation point; hold down the Ctrl-key to move the alignment more freely..
->Please note that subsymbol slot’s offset from the allocation point is relative to the direction of the template path. As the layout remains the same for all path segments, this means that the absolute position of the slot may be different on different segments, as shown in Figure 3–14. Rather than all being absolutely to the left of the line, as on the first segment, the slots in the figure are aligned to the ‘outside’ of the line – actually to the right of the line as we imagine moving along it in the direction of the arrows.

Template slot offset

Figure 3–14. Subsymbol slot offsets.

It is worth noting that the template layout shown in the Symbol Editor is only a preview based on the assumption that a maximum number of subobjects have been found. It is possible that that not all previewed slots are filled or that there are not enough slots for all subobjects in the Diagram Editor. If the symbol’s and subsymbol slot’s scalability settings allow, it is possible to reveal more slots by scaling the object in Diagram Editor.

Templates can also cover area and grid-like layouts by cloning the template path. Basically this means that the entire path is cloned and repeated multiple times. The position and spacing of each clone is specified along a cloning path, in a similar fashion as the subsymbol slots are distributed along the template path. The cloning can be activated by selecting Cloning from the template’s popup menu. This will toggle on the clone path, shown as green path segment, and initially created perpendicular to the template path (as in Figure 3–15).

Template clone path

Figure 3–15. Clone path.

The clone path can be edited in the same way as the template path by selecting popup menu command Edit Points for breakpoint editing or Edit Layout for layout editing. Breakpoint editing follows the same procedures as with polylines, but handles are shown both for the cloning path and for the template path. For the layout editing, the control handles for the template path remains the same as previously but there are now two new yellow control handles for the clone path: distance from the start and interval (as shown in Figure 3–16).

Template clone path editing

Figure 3–16. Editing clone path.

The layout specific settings are also available in the template’s Format dialog’s Template Layout Settings tab.

Template subobject settings

The source for subobjects is defined on the Subobjects page in the template’s Format dialog (shown in Figure 3–17).

Template subobject settings

Figure 3–17. Template subobject settings.

There are five different source options:
*Self: use the hosting object itself as a subobject (useful for showing a library symbol as part of several symbols).
*Single Property: use the object from a single property in the host object.
*Collection Property: use the objects from a collection property in the host object.
*Subgraph of type and Object type: from the host object’s subgraph of the specified type, use the objects of the specified type.
*Generator: use a set of objects retrieved by a generator. The generator must output the objects one per line, and the template will pick up the first Live Code hyperlinked object on each line. For more information about defining generators, please refer to Chapter 5.
In addition to the subobject source it is also possible to define here whether the subobjects will be used as dynamic ports when creating bindings, with the Use subobjects as ports check-box. Checking the box will allow each subobject’s default connectable to be revealed as a port, which will behave in accordance with that connectable’s Sticky targetpoint and Grid sensitive settings. If the check box is left unchecked, plain subobjects will be displayed without the port behavior. By default, the dynamic ports are unmovable. Checking the Allow moving of ports box will allow the user to drag the ports along the template line.

Template subsymbol settings

In order to be able to be displayed, the subobject needs to have visualization – either its own symbol or one from the Symbol Library. The subsymbol source can be defined on the Subsymbol page in the template’s Format dialog (shown in Figure 3–18).

Template subsymbol settings

Figure 3–18. Template subsymbol settings.

To use an object’s own default symbol, select Subobject’s symbol (or default). To use a subsymbol from the Symbol Library you can either select it directly or provide the name of the symbol to be fetched. To select the symbol from the library, select the Selection radio button and press the ... button to open the Symbol Browser for choosing the subsymbol. Alternatively, the name for the library symbol can be provided from a property (select the Property radio button and choose the property from the pull-down list) or a generator (select the Generator radio button and define the generator that outputs the name).
->For more information about the Symbol Library and Symbol Browser, refer to Section 3.6.

Template layout settings

The Layout page in the template’s Format dialog (as shown in Figure 3–19) gathers the settings needed for defining the actual layout for the subsymbol distribution along the template path.

Template layout settings

Figure 3–19. Template layout settings.

In the Layout page, the topmost section, Allocation settings, defines how subsymbol slots are positioned on the path:
*Where to Allocate from, i.e. shall we start distribution from the beginning, middle or end of the template path (in the mid-point case we spread from the middle outwards)
*Interval, i.e. the distance between the slots, measured along the path
*Before first, i.e. the distance from allocation start to the first slot
The middle section contains the settings for the subsymbol slot:
*Max. width and Max. height: the width and height of the slot area. This must be big enough to contain the largest subsymbol one of these slots will display, placed according to the alignment settings. Parts of the subsymbol outside the slot will be clipped from display. Note that the template’s Weight may be used to prevent clipping of wide lines along the outer edges of the subsymbol slot. E.g. if a subsymbol is a 20x20 rectangle with a weight of 10, the outer half of the line widths would be clipped by a 20x20 subsymbol slot; increasing the template weight to 10, to match the subsymbol rectangle, will allow the subsymbol to display fully, and remain correct even if the subsymbol scales.
*Before point and Left of path: the alignment of the subsymbol slot. The value is the fraction of the subsymbol slot that is respectively before or to the left of its allocated point, from the perspective of one moving along the template path segment in the direction of its arrowhead.
*Allow X and Y scaling: whether the subsymbol slot is allowed to scale with the hosting object. If the subsymbol slot allows X scaling, then as the parent symbol is scaled horizontally, the number of slots shown there remains constant and each slot grows horizontally — as does the subsymbol displayed in it (unless its symbol forbids scaling). If the subsymbol slot disallows X scaling, then as the parent symbol is scaled horizontally, the number of slots shown there increases, and each slot stays the same size.
*Targetpoint alignment: when this is set, the subsymbol will be aligned so that its default connectable’s target point will be in that point around which the subsymbol slot is aligned (i.e. the first yellow handle)
The final section at the bottom of the dialog is reserved for the clone path settings:
*Use clone path: toggles cloning on or off.
*Allocate from: the starting point for the distribution (the options – beginning, middle, end – and the behavior are the same as layout’s general Allocation settings).
*Interval and Before first: similarly to the Allocation settings, the distance between clones, and the distance from the allocation starting point to the first clone.
The clone path allocation settings will be turned off when the clone path is inactive.

Show in Frame No Frame
Up Previous Next Title Page Index Contents Search