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.

Classic Paste Structure

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 Clipping Dialog

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.)

Helix uses two terms to describe structural elements:

• Icons are the eleven visible object types that you create in the collection and relation windows. {relation, sequence, user, field, abacus, template, view, index, form query, power query, post}
• Objects are the underlying components of a Helix collection structure. This group includes the icons, but also includes elements such as rectangles on a template, menus in a user, or tiles in an abacus. The number of objects in a collection will always be greater that the number of icons, as all icons types require additional support objects.

A structure contains two types of data: Icons and References:

• Icons are those that were selected when the structure was acquired. Icons contain all of the underlying objects necessary to recreate them exactly as they were in the source collection.
• References are icons that were not part of the selection, but are required to complete the definition of the selected icons. For example, copying just a template copies the entirety of the template — including all of its internal rectangle objects — as an icon, but includes only references to the fields, abaci, sequences, etc. that are inside the template rectangles.

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:

• Field: data type and inert properties
• Abacus: data type property
• Template: has repeat property (list or entry view)
• All others: None

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.

The 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:

1. Object Counts: The number of each type of object in the source structure
2. Source Icon Tree: The icons being applied to the open collection.
3. Target Icon Tree: The icons in the open collection. Source icons can be designated as replacements for existing icons, or can be used to create new structure in the collection.
4. Additional Controls: Buttons and checkboxes that give the user more options during the process.

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).

• The Link column shows the number of icons that were matched to existing structure in the target collection.
• The Create column shows the number of icons that were not matched and will be created as new structure.
• The Skip column shows the number of references that were not matched and for which placeholders will not be created.

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

• Icons (contained in the incoming structure) must replace an existing icon or be used to create a new icon; they can not be skipped.
• References are never created automatically. If no matching icon is found, the reference is skipped by default. This has the effect of modifying the incoming icon by virtue of removing links to the unmatched icons. This may produce unexpected results, for example when a field is skipped, and a source abacus uses that field as a key in a lookup tile. The hole in the tile where that field would appear is left empty (a ‘black hole’) and the abacus will not be able to look up the expected values. A skipped reference may also result in disabled icons, for example when a template is skipped that is used by a source view. Without a template, the view will open in ‘Quick Entry’ mode.
• Placeholders: To avoid modifying the incoming icons, as happens when icon references are skipped, the user has the option to create a ‘placeholder’ icon as a stand-in. (See notes on references above.) These placeholders are incomplete, but they allow the incoming structure to be created without the issues that arise when references are skipped. (See above.)
• Checkboxes around each row and column control which icons are displayed in the Source Icon Tree. Unchecking a row or column removes those icons from the Source Icon Tree, which can be helpful in identifying icons that will be created or skipped, or in general when applying a large structure.
• Counts for each icon state are updated as the Source to Target icon matches are changed.

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.

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:

• Normal: This icon is available for linking to the icon selected in the Source tree.
• Dim: This icon is already linked to an icon in the Source tree.
• Plus: This icon is being created as a new icon, based on the information from the source.

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.

Create a New 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.

• Copy To Clipboard: This button places the name of each icon in the source on the clipboard. The result can be pasted into any text editor to show the icons and references contained in the incoming structure. (There is no real significance to this feature: it was something we used while debugging the code, and decided to leave it active, on the chance that somebody would find it useful.)
• Delete Non-Replaced Icons: This option is only available when pasting relations at the collection level. When checked, icons that exist in the target relations, but are not present in the source relations, are deleted from the relation. If a field that contains data is to be deleted, a warning dialog appears so that data is not accidentally lost. This option is off by default.
• Cancel: Exit the dialog and do not apply the source structure to the target collection.
• OK: Apply the source structure to the target collection, according to the mapping defined in the Source and Target icon trees.

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:

• Link a matched icon to a different icon
• Create a new icon instead of linking to an existing icon
• Link an unmatched icon to an existing icon instead of creating a new icon
• Link a reference to a different icon
• Create a placeholder icon instead of linking to an existing icon
• Create a placeholder icon instead of skipping a reference
• Skip a reference

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:

1. The targets for incoming icons must be selected.
2. Icons in the source are matched to (selected) target icons with the exact same name.
3. Icons in the source are matched to (selected) target icons with the same internal Object ID.
4. References in the source are matched to target icons with the exact same name.
5. References in the source are matched to target icons with the same internal Object ID.

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.

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:

• Heloise typically modifies an abacus by duplicating the original, modifying the duplicate, using ‘Get Info’ to locate all of the places the original is used, and then opening each one, replacing the original abacus with the modified version, and eventually discarding the original. (This is a useful technique that avoids having the abacus ‘kicked out’ of other objects when the data type temporarily changes.)
  An alternative method of updating the abacus is to copy the modified abacus and apply it to the original. This eliminates the need to manually replace the references to the old abacus with references to the new one. But in this situation, the duplicate abacus has a different name and a different Object ID, and Helix will not be able to match it to the original abacus it is intended to replace. (It will simply match to itself.) The user must manually specify the target abacus before applying the modifications to it.
• Helmuth has developed an accounting module that he sells to various Helix users. His customers add his code (saved as a clipping) to their RADE clippings folder, then open their collections and apply the clipping. In this situation, name matching will fail, but icons in the clipping will certainly have internal Object IDs that match completely unrelated structure in the target collection. In this case matching by ID is useless, and even potentially dangerous.
  The danger is easily avoided by making sure that no icons are pre-selected in the target collection.
• Helen created a collection for tracking personal workout routines, which she sells as a stand-alone application. Based on user feedback, she discovers that she crossed the ‘start time’ and ‘stop time’ fields, so that when a user performs a query, the field name shown is incorrect. The solution would appear to be simple: swap the names of the fields and send out a clipping the users can apply to their copy of the collection, correcting the issue. However, when Helix performs the ‘match by name’ it will find the existing icons with those names and ‘flip’ the targets, resulting in no change to the target collection.
  One solution here would be to also slightly rename the icons, so that matching by name fails and Helix falls back to matching by ID, where it will properly link the fields. (A better solution would be to write a simple AppleScript to rename the two fields, but we digress.)
• Helgi owns a company, and he has built a large Helix collection to manage his business. During the week he responds to employee needs by adding and refining features in his collection. He starts with a copy of the active collection, makes changes through the week, then at the end of the week, he saves the modified collection as a clipping and then applies it en masse to the active collection.
  As long as he does not use the first technique described above, icon matching should be virtually automatic. A quick glance at the Object Count section of the dialog assures him that the numbers make sense, he applies the structure, and now has his weekend to relax.

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:

• When a source user icon is linked to a target user that has a password, the target’s password is preserved.
• When a source user icon is used to create a new user, the new user is created with no password. (The structure does not have a password to apply.)
• When a source user reference is linked to a target user, the target’s password is preserved.

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…

• Typing a single character selects the next icon that starts with the same character as the current selection. If no icon is selected, the search starts at the top of the tree.
• Typing one or more characters selects the next icon after the selection that starts with the typed characters. If no icon is selected, the search starts at the top of the tree.
• Type selecting wraps around: if no match is found after the current selection, the search continues from the top of the tree.
• If no icon starts with the character typed, no icon is selected. (That is, the ‘next higher name’ is not selected.)
• Type selection searches all icons, including those within closed icons.
• Characters starting with a period can not be type-selected. (This is a bug in wxWidgets.)
• The Up and Down arrow keys move to the next selectable line.
• The Right arrow key selects the next icon in the list, opening the tree if necessary to show the selection.
• When an icon within a relation is selected, the Left arrow key selects the relation.
• When an open relation is selected, the Left arrow key closes the relation.
• When a closes relation is selected, the Left arrow key selects the last icon of the relation above it, opening the tree if necessary to show the selection.
• Home, End, Page Up and Page Down scroll as expected. These keys have no effect on icon selection.
• See also: notes on opening and closing sections via the disclosure triangles, as described in the “… Icon Tree” sections above.

Additional facts about applying structure that do not neatly fit into any of the above sections.

• Data is not transferred from the source collection when structure is applied.
• About Color: Each collection has a ‘color table’ that is modified when a collection designer creates custom colors for use in template design, or a user creates a new color when entering styled text. That color table is included in the structure, and may modify the target collection’s color table. In some cases, this can cause color changes in other parts of the collection if the target also has custom colors defined. This is considered an anomalous behavior, and a planned enhancement will eliminate it.
• Classic RADE is unable to apply changes to open icons. That restriction is eliminated in macOS RADE.
• The Classic RADE dialog gave the appearance that you could skip an icon by deselecting it in the dialog, but it was not true: All icons in the clipping would be created, whether specified or not. (Only references can be skipped.)
• The macOS Resource Manager limits the size of a clipping to a maximum of 16MB. If you have many pictures (or a few large pictures) pasted into label rectangles, your structure might be too large for macOS to handle. If that happens, Helix will beep when you choose “Save Selection as Clipping" and the Why? message will inform you of the error. You can work around this by cutting the largest pictures out of the collection, saving/applying the structure without pictures, and then pasting the pictures back in afterwards.