CreateBorder.py

Description
This script makes creating borders easier. The one script is run again and again, stepping through the process of creating a border. It keeps track of what is going on by creating variables in the current document. [Note: this requires functionality first introduced in PageStream 5.0.3.4]

WARNING: This script is still under development and may contain bugs, allow actions or create situations which cause PageStream to crash.

Installing this Script

There are three files: this help file, the actual script and a resource file. The script and resource files can be put most anywhere as long as they are in the same directory, but the recommended location is in the scripts directory. By default this is PageStream5/Scripts. This help file should go in the Scripts directory of the PageStream Help. This is normally PageStream5/Help/Scripts. If it is placed incorrectly the script will not be able to find it.

Creating Borders

To create a border requires vector graphics: bitmap graphics cannot be used. There are three basic elements to any border: corners, middles and dashes. A border does not need all of these elements. For example, a basic border can be constructed using just dashes. Each of the corners and middle elements used in a border can be a different graphic and there are eight potential dash elements. This is illustrated below.

Corner Dash(es) Middle Dash(es) Corner
Dash(es)       Dash(es)
Middle       Middle
Dash(es)       Dash(es)
Corner Dash(es) Middle Dash(es) Corner

When you save a border PageStream actually saves a bundle of all borders that it knows about. Therefore it is strongly recommended that you remove all other borders before creating a new one. The script will prompt you to remove all existing borders (which will become available again the next time PageStream is run), but if you want to do this manually you can do so by:

  1. Close PageStream if it is running
  2. Move all files in SoftLogik/Engines/Borders to a different directory (e.g., SoftLogik/Engines/Borders/disabled)

Creating a separate document for each border and doing all graphics in that before hand is also recommended. If you need to save changes to the document after running this script first delete all variables created by the script to avoid later problems. This script uses variables named 'bordername', 'pathindex', 'designsize' and 'defaultsize'. To delete variables go to the menu Edit/Define/Variables....

Design Bounding Box

The design bounding box is the space which a border element is desired to occupy. This may be smaller or larger than the path which will comprise the border element. When adding a path to the border it is always considered relative to the required placement of the design bounding box.

Using this script

To use this script requires that a document window be open. Not only do you need a document to place the graphics in, the script uses PageStream variables to maintain state and these are tied to a document. Note, you can have other documents open as the state of this script is saved in the working document. You can create multiple borders at the same time in different documents as long as their names do not overlap. If you create more than one border in a document you can only do so sequentially and will need to delete the variables before starting each new border after the first. The script automatically deletes the variables when you save the border. Note: it may work to develop each border in its own chapter but this is untested and unsupported.

Create New Border

When the script is first run it prompts you to name the border. This name must be unique. If you plan on allowing others to use your border consider giving it a name that starts with your name or something else unique to you. This helps users rapidly find the desired border. For example, Doty-Aztec Serpent or Celtic-Domnach Airgid.

The script defaults to deleting all existing borders, but prompts for confirmation of this action. This only removes borders from the running program: the next time PageStream starts it will load all the borders again. Let the script remove the borders unless you are designing a family of borders to be distributed as a bundle. In that case delete all borders when defining the first one, then uncheck that box for the remaining borders in the family.

Adding Elements

Whether you are drawing the elements now, they are already in the document or you are loading them make sure that one is selected with the object tool and run the script again. Only single objects can be added at a time: grouped objects cannot be used. In a future version the script may ask if you want it to ungroup the objects and make a single path object for you.

If the object is not already a path you will be asked if you want PageStream to convert it to a path. If the conversion fails an error is displayed, otherwise a new dialog is presented, Add Path to Border. There are three buttons, one for each type of element: Corner, Middle and Dash. Click on the button for the type of element the selected path will be. A new dialog will appear. Elements common to all dialogs are as follows:

Checkboxes
Scale
When checked the path will be scaled with the border when the border is resized.
Flip
When checked the path will be rotated when used in any position other than the upper left corner or top side middle or top side dash. This allows the same path to be used for all sides which are identical.
Two Tone
When checked the path will be set to use the second border color.
Auto Move
When checked the path will be automatically aligned on the page before adding to the border. If unchecked the border is added using the page alignment of its current position. The design bounding box of a corner path is aligned with the upper left corner of the page—the path should be placed relative to this. If the corner path is a ½" circle with a design bounding box of 1" square then the circle's center should be placed at ½", ½". Middle and dash paths are aligned centered on the top left corner of the page.
Alignment
Only affects Auto Move, this allows control over how the automatically moved path is aligned with respect to the bounding box. If the path size is identical to the defined bounding box this setting has no affect. There are four options: none, Center, Inner Edge and Outer Edge.
None
No alignment is done. This option only makes sense if Auto Move is desired, the path is smaller than the bounding box, and no alignment is desired.
Center
This is the default alignment setting and centers the path within the bounding box.
Inner Edge
This aligns the path to the lower right corner of the bounding box—the inner edge for the upper left corner.
Outer Edge
This aligns the path to the upper left corner of the bounding box—the outer edge for the upper left corner.
Path Size Considerations
Width
the width of the path. There is no need to change this.
Height
the height of the path. There is no need to change this.
Adjust Width
the width to assign the path's design bounding box, the path's defined size is relative to this
Adjust Height
the height to assign the path's design bounding box, the path's defined size is relative to this
Path Width
superfluous? if this is used to redefine the path's design bounding box it is unnecessary
Path Height
superfluous? if this is used to redefine the path's design bounding box it is unnecessary

Adding Corners

There are four checkboxes, a dropdown menu, and six string gadgets. In many cases the default settings can be used.
Placement
There are eleven options for placement of the corner path.
All
The path will be used in all four corners
Top Side
The path will be used for the upper left and upper right corners
Left Side
The path will be used for the upper left and lower left corners
Bottom Side
The path will be used for the lower left and lower right corners
Right Side
The path will be used for the upper right and lower right corners
Top Left
The path will be used for the upper left corner
Top Right
The path will be used for the upper right corner
Bottom Right
The path will be used for the lower right corner
Bottom Left
The path will be used for the lower left corner
Top Left and Bottom Right
The path will be used for the upper left and lower right corners
Top Right and Bottom Left
The path will be used for the upper right and lower left corners

Adding Middles

There are four checkboxes, a dropdown menu, and six string gadgets. In many cases the default settings can be used.
Placement
There are seven options for placement of the middle path.
All
The path will be used as the middle for all four sides
Top and Bottom
The path will be used as the middle for the top and bottom sides
Left and Right
The path will be used as the middle for the left and right sides
Top
The path will be used as the middle for the top side
Right
The path will be used as the middle for the right side
Bottom
The path will be used as the middle for the bottom side
Left
The path will be used as the middle for the left side

Adding Dashes

There are five checkboxes, two dropdown menus, and six string gadgets. In many cases the default settings can be used.
Checkboxes
Many
When checked the path will be replicated as many times as necessary to fill the space alloted for the dash considering the border's current size and width.
Placement
There are seven options for placement of the dash path.
All
The path will be used as the dash for all four sides
Top and Bottom
The path will be used as the dash for the top and bottom sides
Left and Right
The path will be used as the dash for the left and right sides
Top
The path will be used as the dash for the top side
Right
The path will be used as the dash for the right side
Bottom
The path will be used as the dash for the bottom side
Left
The path will be used as the dash for the left side
Dash
There are three options for how the dash should be used.
Normal
The path will be used on the counterclockwise side of a middle element
Mirror
The path will be used on the clockwise side of a middle element
Both
The path will be used on both sides of a middle element (this option is unnecessary in the absence of a middle element)

Finishing the Border

When you are done adding paths to the border run the script with no object selected and it will ask if you want to finish the border. There are two parameters: design size and default size. The design size tells PageStream what the "100%" size is that the paths should be scaled against. For many borders this should be the width of the largest "dash" path, but there is no rule. If a path was subject to Auto Move then the script will prefill design size with a best guess.

The default size is the width at which the border will be drawn when first set. There is nothing magical about this number and the only recommendation is to make it small enough to not be overwhelming and still large enough to show all the detail.

There are several buttons to choose from. Delete will delete the variables used by this script from the document and the border.

WARNING: do not delete any border that is in use or PageStream will crash when displaying it.

Use will set the default and design sizes as specified. Save will set the default and design sizes as specified and save out all loaded borders. The resulting border bundle will be SoftLogik/Engines/Borders.library. This file should be renamed appropriately and moved to SoftLogik/Engines/Borders. In a future version this script may prompt for a name and do the rename and move for you.

It is recommended to Use and test the border before saving it. By running this script again new values for Design Size can be entered to test the results. In a future version this script may allow adjusting the design parameters of paths, in the meantime this can be done by creating appropriate macros with the Script palette and executing them. The first path added has index 0, the second path index 1, and so on.

Making Two-Tone Borders

A border can be created in such a fashion that some parts are colored in a second color. This is done by adding paths for the second color. If the first color path and the second color path intersect one will be drawn on top of the other. Although it is possible to carefully monitor the order in which PageStream layers the paths it is recommended to avoid any overlap to ensure consistent appearance. Judicious use of the Exclude and Subtract path commands are very effective for generating the necessary cutouts. Manual editing of the resulting path may be required as artifacts occassionally occur.

To add a path as a second color check the Two Tone option when adding the path. If the second color path is not as large as the first color make sure to set the path height and width appropriately. It may also be necessary to manually place the path to insure correct alignment.

If the border only uses a Two Tone corner then that path will not display. To overcome this problem add a null path as the non-Two Tone corner. In a future version this script may automatically add a null path corner to match the Two Tone corner.

Notes

The script maintains four variables in the document to keep track of certain information between runs.
bordername
holds the name of the border being currently created
pathindex
holds the number of paths already defined in the border (and is also the index to be used for the next path added)
designsize
the width of the design bounding box
defaultsize
the border width to be set when the border is first selected in PageStream