|The ‘Apply Structure’ Dialog (New in Helix RADE 6.2)|
Helix RADE lets you save collection and relation level icons and their contents, (collectively known as “structure”) as ‘clippings’ — small files that can be copied to another computer, emailed to a customer, or otherwise stored for future use.
Clippings can be applied to the same collection or to a different collection. This makes it possible, for example, to update multiple copies of the same collection with changes made to one copy, or to reuse common components in multiple collections.
Helix RADE also lets you copy collection and relation level icons to the clipboard (pasteboard), applying them either to the same collection or to a different collection.
Whether you save changes as clippings or copy icons into memory, applying them uses the same underlying mechanism, which is referred to as Applying Structure. This technote applies to both features.
In Classic Helix, this feature could handle only a limited number of icons, and attempting to copy too many would result in an error or even a crash. Helix 6.2 and later can handle any size of structure, including entire collections containing thousands of icons. This greatly expanded power requires a totally redesigned ‘Apply Structure’ dialog. This technote describes the new dialog and how to use it.
|Save Structure (as Clipping)||
When you select one or more icons at the collection or relation level, the Save Selection as Clipping menu item (in the © menu) is enabled. Choosing this menu item “preflights” the selected structure — the progress dialog that appears during this phase is shown on the right — to make sure that a clipping can be made. Upon success, a standard ‘save file’ dialog appears, allowing you to name and save the clipping. (If the Clipping can not be made for any reason, Helix beeps, and a Why? message is available to explain what the problem is.)
Although clippings may be saved anywhere, clippings that are saved in Helix’s ‘Clippings Folder’ can then be selected from the © menu, applying the clipping’s contents to the current location of the currently open collection.
The Helix RADE clippings folder is found at ~/Library/Application Support/Helix/RADE/Clippings. You can create additional folders within this folder to organize clippings into logical groups.
See the Helix RADE 6.1 Release Notes for more information on the Clippings menu.
An alternative to the clippings, you can also copy icons to the clipboard using the Copy menu item. From there the structure can be pasted (using the Paste command) into the same collection, or into another as long as you do nothing that would cause the macOS clipboard to reset.
If the copy operation takes more than a few seconds, a dialog appears to mark the progress.
Because the Copy Structure command uses the clipboard, it uses memory, and copying a large collection can stress a computer with limited memory. Also, the copy is lost the next time the ‘Copy’ command is used, or the Mac is restarted. Also the previous contents of the clipboard are replaced when the copy is made. (To avoid this, QSA ToolWorks recommends PTHPasteboard, an excellent clipboard management solution.)
|Icons vs. Objects||
Helix uses two terms to describe structural elements:
|Icons vs. References||
A structure contains two types of data: Icons and References:
References do not include the internal objects that define them; they hold only a enough data to ensure correct data type matching in the target collection:
Creating a new icon from a reference creates a ‘placeholder’ icon, containing just enough to match the data type to the original. (Without that, referencing icons would reject it as being of the wrong data type.
|Apply Structure Dialog||
When structure is applied to a collection — by choosing a clipping from the ‘©’ menu or selecting ‘Paste’ from the ‘Edit’ menu when there is structure on the clipboard — a dialog allows you to control the process. This dialog gives the user control of each icon being applied to the collection. In particular, you can determine whether an incoming icon should create a new icon or replace an existing one.
The components of the dialog (shown at right) are:
Each of these components is described in detail below.
The first section of the dialog is the Object Counts section. It contains three columns of actions (Link, Create, Skip) and two rows of object types (Icons, References).
Each column (Link, Create, Skip) is combined with the two rows (Icons, References) to form a matrix of possible actions when the structure is applied. The effect on the target collection for each of these combinations is shown in this table:
Notes on Object Counts
|Source Icon Tree||
The Source Icon Tree is shown on the left side of the dialog. It is presented in ‘tree’ format, with icons that are contained within other icons shown as ‘indented’ from the parent icon.
Disclosure triangles next to the collection and relation icons allow the user to hide or reveal icons contained within them. Holding the Option key down while clicking on the disclosure triangle next to the collection icon (or double clicking on the collection icon or name) opens or closes the collection and all relations in the tree.
The Source Icon Tree is initially displayed in one of two states: complete structure or top-level icons only. RADE is capable of applying structure containing thousands of icons, and displaying a complete structure with many icons is simply too much information. By default, Helix switches to top-level icons only mode when there are more than 500 icons in the structure. This cut-off point can be changed by editing the HxPasteTreeMaxOnOpen preference. (See this technote for more information on editing preferences.) Displaying a large icon tree takes time, and the macOS ‘spinning wait cursor’ may be displayed when a large icon tree is being built.
Icons in the tree are shown in bold; References are shown in plain text.
When an icon is selected in the Source Icon Tree, the Target Icon Tree updates shows how that icon has been matched, along with other options. The options are explained in the ‘Target Icon Tree’ section below.
|Target Icon Tree||
The Target Icon Tree is shown on the right side of the dialog. It is presented in ‘tree’ format, with disclosure triangles on the collection and relation icons that allow the user to hide or reveal icons that are contained within them.
When an icon is selected in the Source Icon Tree, the Target Icon Tree shows how that icon has been matched, along with other options. Icons shown in the Target Icon Tree can be in one of three states:
When an icon is already linked to a target icon, the target icon appears as a ‘dimmed’ (disabled) icon. This is because this icon is already linked (to the one you selected on the left) and linking two source icons to one target is nonsense. The icons on the right are disabled to show that they can not be linked to anything else, unless the current link is broken.
To switch a link from one target to another, simply click on any ‘normal’ (enabled) icon. Only icons that are not already linked are enabled, because as mentioned above, linking two source icons to a single target is nonsense.
After you switch a link from one target to another, the original target icon becomes enabled. It can then be linked to another source icon.
Another option is to create a new icon from the source. Whenever an icon is selected in the Source Icon Tree, the Target Icon Tree shows the potential matches for that icon. At the top of this list is an icon with a ‘plus’ symbol superimposed over it. Linking to this icon creates new icon instead of replacing an existing one. (The original of the same name, if it exists and is not linked to any other source icon, is left untouched.)
The user can create new icons based on source icons and references. When a new icon is created from a source icon, the complete icon is recreated. When a new icon is created from a source reference, the icon is created with only enough structure to ensure data type matching. See the Icons vs. References section above.
A future enhancement is expected to allow the user to select a linked icon, revealing the incoming icon it is linked to in the Source Icon Tree.
Below the Source and Target icon trees is an area containing various buttons and checkboxes that can be used to adjust the result when structure is applied, or to provide other functions.
Applying Structure is simply a matter of matching the incoming structure (source icons) with the structure in the open collection (target icons) and clicking the “OK” button.
When a user applies structure to a collection, Helix attempts to determine which source icons are intended as replacements for target icons. Only pre-selected icons are considered as potential targets for source icons. (References do not have to be pre-selected.) Before the structure is applied, the user has the option of modifying the default matches. The user can:
Matches are changed by manipulating the Source and Target icon trees, as described above. As links are changed, new icons are created, references are broken, etc. the Object Counts update to indicate the current state of the matching process.
The user can accept the current matching at any time; when the OK button is clicked, the structure is updated according to the linking shown in the dialog.
If a target icon’s name is different from the one that is replacing it, the icon is renamed using the source icon name. A planned enhancement will allow the user to change this behavior.
Warning: The ‘locked’ property of target icons prohibits it from being replaced; locked icons are ineligible for replacement. A planned enhancement will allow the user to change this behavior. In the meantime, the Unlock All Icons script on our Public Scripts page provides a workaround by quickly unlocking all locked icons.
When a user applies structure to a collection, Helix first attempts to determine which incoming (source) icons are intended as replacements for existing (target) icons. These basic rules are applied in the following order:
If no icons are found that satisfy a rule, the next rule is checked. When one (and only one) icon is found that satisfies a rule, the search stops.
If multiple icons that satisfy a rule are found, the next rule is consulted as a ‘tie breaker.’ The final arbiter of all conflicts is the internal Object ID. Users familiar with the AppleScript implementation in Helix will understand and can examine the internal Object ID of icons and other structural elements of a collection.
Once a match has been found, it is ‘type checked’ to confirm that the replacement is logical. For example, a template can not replace a post, even if both the Name and Object ID are exact matches. Likewise, a field (or abacus) can not replace a field whose datatype or inert status has changed. Therefore, if an abacus’ output has been changed from, for example, number to fixed point, it can not be used to replace the existing (number type) abacus of the same Name/ID. In this case, you must create a new icon for the new datatype. If the changes being applied cover all references to that icon, the original will be left unused, and can be deleted after the fact, or by checking the Delete Unused Icons checkbox.
Icons that are part of the incoming structure must either replace an existing icon or create a new one. They can not be skipped, a fact that is subtly indicated by blank cell in the grid, rather than a 0. It is not-so-subtly indicated by the fact that the linkage simply won’t deselect.
References that can not be linked to existing icons are, by default, not created, and appear in the Skip column. The user has the option to create a ‘placeholder’ icon as a stand-in, which moves that icon into the Create column (as a reference). References that are matched can be unlinked, leaving icons that refer to it incomplete. (See notes on references above.)
Source icons only match to pre-selected target icons; source references match to any target icons, regardless of selection.
|Additional Notes on Icon Matching||
Application of structure to a collection can be tricky. The user must bring personal knowledge of the target collection and the structure being applied along with some common sense as to whether the matching ‘makes sense’ or not.
Matching by ID is considered a ‘fall back’ method, used when no match by name, or more than one match my name, is found. Matching by ID makes sense when the structure being applied is taken from a copy of the same collection as the target. It should not be relied on unless the user is intimately involved with the collection and understands how internal Object IDs are assigned, and how they can change. Consider these scenarios:
If you do not want to see the dialog, choosing to trust Helix to make all of the right decisions, hold down the Shift and Option keys while selecting the Paste command or the clipping. Helix will apply the structure using its default matching algorithm, just as if you had made no changes in the dialog before clicking OK.
For security reasons, passwords are not included in the clippings. Transporting a password in a clipping file would be a security breach.
When applying a structure that contains user icons, passwords are handled in the following ways:
Likewise, copying an entire collection does not bring the collection password along. If you apply that to an existing collection, the password present in the target is preserved; when applying it to a new collection, the collection is created with no password.
The Apply Structure dialog supports the following command key equivalents:
In addition, the Source and Target icon trees support keyboard navigation in a limited fashion. After clicking on a tree…
Additional facts about applying structure that do not neatly fit into any of the above sections.