Menus

Iron Resource Files

Iron menu resource files are text files that are compiled and used by Iron to define menus and menu items and their shortcut key bindings.

The iron.menu file can be loaded using the Tools|Menus|Load Menu File menu option or via the Command Palette (press F8) and type iron.menu and Enter.

This document will describe the Zinc menu file format, it’s grammar, content and uses.

Refer to the Iron Resource Files: Customizing documentation on how to compile (press F7) and debug (press F4) Zinc files in more detail.

If it doesn’t taste good it doesn’t go on the menu.

Heston Blumenthal

Chef, The Fat Duck, voted #1 in The World’s 50 Best Restaurants in 2005

Menu Description & Organization

Iron’s menu system currently defines a single main menu with a series of drop-down submenus. User-defined favorites and context menus will be supported in the near future. 

The menu system interaction is mapped through the left-mouse button. Keyboard-only interaction with the menu system is not yet available.

One menu feature worth knowing as you explore Iron is Menu Recall. Hold the Ctrl key down and click with the left mouse button (Ctrl+Mouse_Left) anywhere in Iron and this will re-open the menu drop-downs and place the mouse cursor over the menu item you last picked. Iron will open up all the necessary drop-down menus without you having to drill-down through layers of submenus. How often have you gotten lost just trying to find the last option you changed?

Once the menu item is re-displayed, then click with the left mouse button (without the Ctrl key) to pick that item again or to pick some other nearby menu item.

The main menu is organized into functional groups and labeled with terms you’ll mostly be familiar with from other software applications e.g. File, Edit, View, Help. There’s is a philosophy and rationale to Iron’s menu and submenu organization that works well. The next dozen paragraphs will explain the rationale for each grouping:

Beta Menu:  The Beta menu is your entry into Iron as a beta tester. We’d like to Welcome you and then get you started editing as quickly as possible. There are links to online documentation for the Beta test cycle and one to a short Survey we’d appreciate you filling out after exploring Iron. Your feedback, bug reports, praise and ideas can all be shared through our Forum. Iron’s ultimate design and success depends on real programmers’ experience and input.

File Menu:  The File menu provides file manipulation utilities and settings. Many of the menu items are active or relevant only to the file opened in the current pane. There are menu options and shortcuts for opening, saving, closing and creating files. Files can also be loaded via the Command Palette or drag-and-dropped onto a “text” pane. Folders can be drag-and-dropped onto a text pane but use with caution, Iron doesn’t yet filter out or deal well with binary files.

In Iron’s menu organization, settings generally accompany functionality rather being placed elsewhere e.g. under a Preference, Tools or Options drop-down as done in other software. Iron’s File|Read/Write Option submenu provides settings to handle whitespace and horizontal tabs when reading and writing files. There will be more file options in the future dealing line endings, encoding formats and more.

Edit menu:  The Edit menu provides bulk editing utilities and settings such as those for defining traditional single stream selections for Copying, Cutting and Pasting text. Most of these menu items will become second nature very quickly and are included in this group so you can see Iron’s default key bindings for such common needs as Undo (Ctrl+Z) and Redo (Ctrl+Y or Ctrl+Shift+Z).

In Iron, fine editing generally refers to deleting and inserting text without the use of selections. The Edit|Fine Editing submenu spells out most of the fine editing features such as deleting to the end-of-line, inserting blank lines, working with horizontal tabs, whitespace and changing case.

Multi-Select menu:  The Multi-Selection menu enumerates Iron’s premiere power-editing features and key bindings. Multi-Selection allows the proficient programmer to create multiple carets or select multiple regions of text for simultaneous editing.

In Iron, Multi-Selection is how programmers Find-and-Replace text. It is also used to alphabetically sort selections. The Multi-Selection functionality is key mapped with the Ctrl+Shift modifier pair.

Multi-Selection uses a latch which, when on, applies edits to all selections at the same time and, when off, only to the primary selection or caret while preserving the other selections. Read more about Multi-Selection in the Multi-Selection: The Latch documentation.

Navigate menu:  The Navigate menu provides utilities to move quickly within a file and amongst the files in a project (as reachable via the Directory Search Path). This is includes Find, Find-in-File(s), seek and loading files via the Command Palette, Goto a file:line:column location, fine-manipulation of the caret (e.g. jump to end-of-line), using bookmarks and navigating the Iron search results file (iron.result).

View menu:  The View menu provides controls on the pane layouts and settings. Iron does yet have a docking system allowing you to stretch panes, define and save your own layouts, that’s coming.

Modes menu:  There are two major editing modes in Iron. The first is Modes|Virtual Space Editing which allows the caret to be placed beyond the end-of-the-line into areas of the pane where there are no characters. We recommend you turn Virtual Space Editing (VSE) on and learn its advantages for working with source code — the learning curve is very low.

The second editing mode is a choice between Modes|Traditional Mode and  Modes|Iron Professional Mode. Iron Profession Mode uses “sticky selections” which are new thinking and a significant departure from how other text editors function. First, to extend selections, you do not hold down the Shift key which is used only for starting or changing selection styles. Moving the caret with the arrow keys extends the selection, it does not cancel the selection — that’s what makes them “sticky.”  Canceling selections is done only via the Escape key ESC. Also, typing text does not delete selected text, this is done only through the Ctrl+X Cut command.

The learning curve is small, the unlearning curve is steep. Editing in Iron Professional Mode using sticky selections is less error prone, involves fewer key bindings, relies heavily on block column and line selections, feathers well with Multi-Selection and handles the repetitive nature and content of source code better than prose-style editing and traditional stream selections used by most editors. For the professional programmer, Iron Professional Mode will reduce fatigue and increase your coding proficiency.

Tools menu:  The Tools menu provides tools, functionality and settings that you can customize to match your programming needs. Iron’s text-based resource files provide the means to customize key bindings, macros, menus and scopes (colors and themes). Tools like the magnifying glass, the minimap, audio cues, syntax highlighting, menu auto-hide and line numbers can be turned on or off.

Themes menu:  The Themes menu provides controls to tailor font sizes, color schemes, caret shapes and blink duty cycles, animation and more. Iron’s initial theme is Steampunk with plans for other engaging themes and ones less so like a Distraction Free theme.

The themes engine and supporting Zinc file format are under construction. Our goal with themes is to be much more immersive than just tailoring colors and switching skins. Iron will theme its menus and dialogs and audio prompts much like a videogame, heavily employing 3D graphics.

Fun menu: Important about Iron and one of DarkViking Software’s mantras is that programming should be fun and enjoyable. The Fun menu (not known to exist in other text editors) will grow with time offering more interesting, entertaining tidbits that are more about livening up your day than serious work. If Iron can make you chuckle randomly, keep you awake and engaged longer, we believe (backed by research and common sense) that being happy instead of bored will boost your output, creativity and software quality.

Help menu:  The Help menu provides links to Iron’s documentation, forum, blog and social sites (YouTube, Facebook, Twitter, Instagram). You can search topics and words with popular industry websites like Stack Overflow, MSDN, Wikipedia, Google and with an online dictionary and thesaurus by selecting them in your source code and picking the menu item in the Help drop-down.

Zinc Menu File Format

The Zinc grammar provides menu declarations which are composed of menu item and section statements. Menu items can reference other menus (called submenus or drop-down menus), include macro references, keymap bindings (shortcuts) and an optional checkbox indicator which can double as a radio button. Section statements are used to group and label sets of related menu items.

Like keymap bindings, each menu item includes a context expression and a command expression. Expressions are used to determine Iron’s current state (a context) and execute commands (calling built-in actions, user-defined macros and changing internal settings).

For a discussion on context and command expressions, macros and built-in actions, refer to the Iron Resource Files: Keymaps and Iron Resource Files: Macros documentation.

A menu declaration consists of the keyword menu, a menu name, the parenthesized parameter list (consisting of only an orientation value) and the menu body enclosed in curly braces {}.

menu iron_menu_main( orient = horizontal )
{
                [<sections>]*
                [<items>]*
}

Zinc files do not require forward declarations, so the ordering of menu declarations in the iron.menu file is not important beyond its organizational value. We’ve organized Iron’s default menu file so the main menu appears first, then each submenu, in order, afterwards.

Menu Section Statements

Menu sections are named (unique per menu) and can have an optional caption. Without a caption, the section’s rendering is thinner. Sections are used to group or label related sets of menu items when rendering. They don’t technically declare a hierarchy between sections and items. Here’s a few example section statements:

section( undo_redo, “Undo System” );
section( workspaces, “Workspaces…” );
section( grouping );        //  No caption, renders thin
section( stuff, “ ” );           //  Blank caption, renders thick

Menu Item Statements

Menu items define functionality via actions, macros or state changes to internal variables that can be picked using the mouse (and with the keyboard in the future). Menu items render a caption, a key combo (shortcut), an optional checkbox and optionally specifies a submenu.

The first parameter of a menu_item() statement is the menu item’s caption. Menu item captions are double-quoted strings that must be unique per menu.

Here are a few menu item examples:

item( “Undo”, macro_undo(), macro_undo() );
item( “Fine Editing”, true, true, sub_menu = iron_menu_fine_editing );
item( “Virtual Space Editing”, true, cpi.toggle( var_name = “vse_toggle” ), checkbox = cpi.is_true( var_name = “vse_toggle” ) );

The first menu item for “Undo” is an example where the context expression (2nd parameter) and the command expression (3rd parameter) both specify a single macro call. The menu item’s context validation is that of the macro and if true, the menu item can be picked. Once picked, the macro’s command expression is executed.

In the second menu item above, the context expression is true so it can always be picked. When picked, the command expression is simply true, it doesn’t actually do anything (a no-op) other than open the drop-down submenu called iron_menu_fine_editing. Whenever the mouse cursor hovers over a menu item with a valid (true) context, the submenu will be opened.

The third menu item example toggles the internal variable called vse_toggle, turning Virtual Space Editing mode on or off. The context expression is always true so the menu item can always be picked. The command expression is executed when the menu item is picked toggling the vse_toggle variable. The optional checkbox parameter references a third expression which, when true renders a checkbox icon (looks more like a green radio button by default). When false, the uncheckbox icon is rendered (which looks like a red radio button). Thus the menu item displays the state of the vse_toggle (green for on, red for off).

Checkbox icons can be changed via the Command Palette.

Note:  More menu item elements will become available for displaying icons, images, playing of audio clips and more.

Menu Item Key Combos (Shortcuts)

Menu items can be loosely coupled to a key binding and render the key combo (also known as a shortcut or hotkey) on the right side of the menu item.

The menu item itself does not specify the key combo directly, rather it makes reference to a macro in its command expression that is also referenced by a key binding that references that same macro in its command expression. Thus a menu item is loosely coupled to a key binding via a mutually referenced macro.

The rationale behind the loose coupling mechanism is that the key combo is specified and customized in only one place (with the key binding). By referencing the same macro in the menu item and the key binding, this ensures the menu renders the same key combo that the key binding will execute.

For the loose coupling to work, the command expressions of both the menu item and the key binding must consist of a single operand, a macro call to the same macro. The expression cannot have multiple AND’ed macro (or action) calls.

Not required, but of good form, is that the menu item and key binding use the same macro in their context expressions. Thus, the menu item and key combo are only available under the same circumstances or context. The context expressions aren’t directly involved in the loose coupling, so they can have multiple AND’ed operands for different or refined evaluations.

So, the coupling involves three elements in three different files:

A menu item (in the iron.menu file) must reference a macro (in the iron.macro file) in its command expression that is also referenced by a key binding (in the iron.keymap file) in its command expression.

To Menu or Not To Menu

As much as menus are useful for numerous reasons, especially for new programmers and those getting acquainted with Iron, we recognize that professional programmers tend to forego constant or heavy interaction with the menu system and the mouse. Instead, they tend favor keeping all ten fingers busy on the keyboard to achieve maximum editing efficiency.

We’ve made an effort in Iron’s menu system design and content (and that of the keymap system and Command Palette) to provide easy routes to high editing proficiency. Most of the menu items have pre-defined shortcuts (key bindings) that are familiar or quick to customize in the iron.keymap file. We’ve organized the menu system into what we think are logical, functional groupings though we recommend that you reorganize and change captions to meet your menu system ideals.

To keep menus light and compact, not all of Iron’s functionality is represented. The keymap and macro files expose a large number of Iron’s built-in utilities. The remainder of Iron’s internal settings are accessible via the Command Palette. Through macros and keymaps, anything in Iron can be manipulated and then exposed as a menu option.

Note:  Detailed descriptions of Iron’s settings and built-in actions will be available in other documentation or provided directly by Iron in the future.

Also coming in the future will be context menus that’ll offer finer interactivity and more information normally available by right clicking. You’ll be able to define your own favorites and context menus.

Yet, we still recommend assigning your most-used activities to key bindings for quick use and to rely on the menu system for your less common needs. Too many key bindings can become overwhelming and lead to accidental and erroneous use thus reducing over editing efficiency.

Menu systems can easily become too heavy in their own right. Just comment out unused or well-memorized menu items using a side comments // and then compile/commit with F7. The main menu can be hidden with the Tools|Menu Auto-Hide menu option.

Menus are great for discovery and rarely used actions but are low efficiency.  So remember our mantra:

More keyboard, less mousing around.

Stay tuned, more exciting 3D menus coming in the future.