Name
PathToBrush -- convert path(s) to vector brush (V7.0)
Synopsis
[id] = PathToBrush(id, table)
Function
This function can be used to convert one or more path(s) into a vector brush. PathToBrush() will create a new brush with the identifier specified in id or if you pass Nil in the id argument, PathToBrush() will automatically choose a vacant identifier for the new brush and return it to you.

Converting paths into vector brushes has the advantage that you can assign different colors to the individual paths combined inside a single vector brush, allowing you to easily manage multi-colored paths inside just a single brush object. Furthermore, the paths combined inside the vector brush can also use different drawing styles.

You have to pass a table in the table argument that contains a number of subtables specifying information about the individual paths to be embedded inside the vector brush. The paths are drawn into the vector brush in exactly the same order as they appear in that table.

Note that each path to be embedded inside the vector brush will be normalized first. Thus, by default all paths will be drawn in the top-left corner of the vector brush. You can change this behaviour by specifying the X and Y arguments in the individual subtables for each path to be added to the vector brush (see below).

The following subtable fields can be specified:

ID:
This must be set to the identifier of the path object to be embedded inside the vector brush that shall be created. This must always be provided. Note that PathToBrush() will make a copy of this path so subsequent modifications of the path won't affect the new vector brush in any way. You may also free this path after adding it to the vector brush.

X:
The x position where this path should be drawn inside the vector brush. This position must be relative to the left corner of the vector brush. Note that PathToBrush() will internally normalize the path before adding it to the vector brush so you will usually have to use this field to position the path correctly inside the vector brush. Defaults to 0.

Y:
The y position where this path should be drawn inside the vector brush. This position must be relative to the top corner of the vector brush. Note that PathToBrush() will internally normalize the path before adding it to the vector brush so you will usually have to use this field to position the path correctly inside the vector brush. Defaults to 0.

Color:
The path will be drawn in this ARGB color. This color can also contain a transparency setting. Defaults to #BLACK.

Note that the form and fill styles to be used by the individual paths are the ones that were active at the time the path was created using StartPath(). This is different to the way form and fill styles work when drawing paths using DrawPath(). DrawPath() will use the form and fill styles that are active when DrawPath() is called whereas PathToBrush() will use the form and fill styles that were active when StartPath() was called on the individual paths. This allows you to use different form and fill styles for the individual paths to be embedded inside the vector brush.

Inputs
id
id for the new brush or Nil for auto id selection
table
table containing paths to combine into the vector brush (see above)
Results
id
optional: identifier of the brush; will only be returned when you pass Nil as argument 1 (see above)
Example
PathToBrush(1, {{ID=1, Color=#RED}, {ID=2, Color=#BLUE, X=100}})
The code above combines paths 1 and 2 inside a new vector brush which will use the identifier 1. Path 1 is drawn in red and path 2 is drawn in blue. Additionally, path 2 is drawn at x position 100 whereas path 1 is drawn at 0,0.

Show TOC