A window is simply a representation of an underlying object within Helix. A window may display information about an icon, such as when a relation window displays the contents of that relation. A window may also display other information about the current Helix environment, such as the information displayed in the Collection Information window.

Windows are identified by their index number, which is the front-to-back order of all of the open windows. Using this index number, a window can be closed by specifying its current position, as in close window 1 to close the frontmost window. You can also close an icon’s window by specifying the icon as the direct parameter for the close command, as in close relation "Customers" or close relation 3. You should not attempt to close a window by name, as in close window "Customers" — to close an icon by name, specify the icon itself.

Additional notes:

• When the direct parameter is omitted, the window of the current target is closed.
• When an icon editor window is closed, changes made to that icon are automatically committed.
• Windows are managed by the Helix application, and are not technically part of the collection itself, so when working with windows, the target should be the application itself, not a specific icon within an open collection.
• If the close command is sent to an icon that is not open, no error is returned. (Sending the command to a non-existent window does return an error.)

The do menu command is a ‘menu driver’ with no real intelligence of its own. An example of usage: a system administrator can create a launchd task to run script that used ‘do menu’ to invoke a sequence that need to run during off-peak hours. (However, for this particular task, The run sequence command is a better choice.)

do menu searches for the specified menu item beginning in the left-most menu (the Apple menu) and working across to the right. Each menu is checked, and the first instance of a matching menu item found is processed.

If no error is encountered, no reply is returned by do menu. If no matching menu item is found, error 280 is returned; if a matching menu item is found, but is disabled, error 290 is returned.

In Helix RADE do menu works in both Design Mode and User Mode, and is also available in Helix Client and Helix Engine.

In the graphic interface, users are able to see the structure of the collection only when using Helix RADE in Design Mode. AppleScript also allows access to the collection design while using Helix RADE in User Mode, as well as in Helix Engine and Helix Server. To prevent unintended access to the design of a collection (whether for security purposes or to protect proprietary code) the login command is required when an AppleScript attempts to access the structure of the collection. The only exception to this is when the collection is open in Helix RADE Design Mode, as the user already has access to the structure in that situation.

The login command requires one direct parameter: a text string containing the Username of a user icon that has The Design Mode command somewhere within its menus. (You can quickly identify such users by checking the ‘Has Design Mode’ property in the Inspector.) Note that this parameter is a text string, not a reference to a user icon. That is, the proper syntax is login "Fred" and not login user "Fred". Of course, a variable or property may be used in place of a string.

If the user has a password, the password parameter must supply that password, just as you must supply it when logging in via the graphic interface.

The last parameter, modifying allowed, deserves special consideration. When this parameter is omitted (or set to false ) the script may read the structure, but modifications are prohibited. It is important to note that modifications are not allowed at the same time as data access: an error is returned if a script attempts to login with modifying allowed and any Clients are logged in (for Helix Server) or there are any open data access processes (for RADE, Engine, and Server).

When login with modifying allowed is successful, two important things happen:

1. External access is blocked. Helix Clients are not allowed to connect to a Server and Apple event processes may not be opened. For this reason, it is important that scripts that use login to modify structure also include a logout command to re-enable external access.
2. The ‘revision level’ of the collection is incremented. Helix Clients will be informed that the structure has been updated the next time they connect to the Server.

The login command, with no parameters at all, is the same as logout.

Command Syntax

Parameters

Command rectangle creates a clickable button on a view. When clicked, a command rectangle executes one or more sequences. There must be at least one sequence (the command property) in each command rectangle or the entire template is invalid.

The name of the button as it appears on the view is taken from the command label or calculated label property, depending on the value of The use calculated label property.

A button is disabled when there is a calculated label icon whose output is undefined, or when the first command in the primary sequence is invalid in the current environment, e.g. a copy command when no data is selected.

A disabled button is dimmed or made invisible, depending on the value of the hide when disabled property. For a dimmed button, the button name is taken from the first defined value found in these properties, in this order: 1) disabled label, 2) command or calculated label, 3) sequence name.

Only icons that output text are eligible for use as a calculated label.

See this technotefor more on button naming.

A menu item is an item that appears on the user menu it is part of. (For example: Undo is a menu item found in the Edit user menu.) Each menu item contains at the very least a command property, which is always one of the commands listed in The user menu commands enumeration. All user menu commands (with three exceptions, noted below) end with the word command to differentiate between them and the actual commands, some of which may be executed directly in AppleScript.

A menu item can also have a key binding (also known as a command key equivalent ), enabling the user to activate that menu item by pressing keys on the keyboard. When defining a key binding, both The modifier keys and key properties must be defined. Defining one without the other is illegal and results in an AppleScript runtime error.

The three exceptional user menu commands are: invoke icon, menu, and separator. These three user menu commands provide special capabilities and may require or prohibit additional properties to create a valid menu item:

• invoke icon : When the command property contains the invoke icon command, The icon property must also contain one of the valid menu item icons: view, sequence or user. The hierarchical menu property must not be defined, and the key binding properties (see above) are optional. When a view is stored in The icon property, three additional properties: location, open window and permissions, may also be defined. (Including any of these three properties with any other command or icon type is illegal and results in an AppleScript runtime error.)
• menu : When The command property contains the menu command, The hierarchical menu property is a read only property of that item. A hierarchical menu is a user menu inserted within a menu item, instead of in the menu bar. When creating a hierarchical menu, you first add menu items to (code: add {command:menu, name:"name"} ) (and remove menu items from) the menu item.
• separator : When The command property contains the separator command, a standard Macintosh menu item separator is inserted in the menu. Separators are provided for organizational or decorative purposes, and serve no other function. Separators have no additional properties, and specifying any of them for a separator is illegal and results in an AppleScript runtime error.

When working with existing menu items, always test the command property before assuming the presence of other properties. Determining which user menu command is present will identify which additional properties may be present and which are prohibited. For example, attempting to get the icon property of a separator results in an AppleScript runtime error, because no icon property exists for a separator menu item.

Permissions are separate from menu items because it is necessary to set permissions for views that are not present directly on the user menus, as is the case with views that are opened via sequences.

When a view is found on the user’s menu, the permissions can be found and modified by examining the properties of that menu item. However, there is a much simpler way:

tell user "User"
  set permissions elements to {icon: aView, permissions: {add record, replace record} } end tell

Using this syntax, Helix handles the permissions regardless of where they are stored for that view, and it is not necessary to retrieve the list of existing permissions elements in order to add or remove an entry for a specific view; only the view specified by the icon property is changed.

For a view where the user has no permissions restrictions (i.e: permissions = all ) there is no entry in the permissions element list, so setting the permissions for a view to all deletes that view from the list, if it exists.

The post icon lets application designers set up forms in which certain form operations make modifications to data not viewed on the screen. For example, a window that generates an invoice can automatically subtract the quantity of each item sold from the appropriate inventory records through the use of posting.

All data manipulation in Helix RADE is ultimately form-based. Ordinarily, when you put data onto a form and store it, Helix creates a record in the relation where the entry form resides. Posting, however, lets records other than the one being manipulated on the screen by a user be changed or created at the same time. The records affected by the post may be in the same relation, or in any other relation in the collection.