[PREVIOUS] [NEXT] [UP]

Annotations and commands

In this chapter you will learn how to augment your visual programs with explanatory annotations and commands.

How to create annotations

The Neo "Add Note" command allows you to attach descriptive annotations to a circuit. After "Add Note" you must select an "anchor point" in the circuit window where to attach the annotation. Then, you can fill a dialog box with the text for the annotation.

The text consists of two parts. The first part, the Note, is the part of the text that will become visible in the circuit. It is restricted to maximally three lines.

The second part, the annotation Comment, is provided for additional and longer text material that only pops up when the annotation later is selected with the mouse pointer.

The first two buttons at the bottom of the annotation dialog box allow you to specify the position of the annotation text w.r.t the annotation anchor point. If the position is given as "center" and "horiz", the anchor point will be "under" the center of the first line of the annotation text and, therefore, not accessible for "dragging" the annotation around. I.e., to drag such annotations to a different place, you must temporarily change on of these settings.

The next two buttons allow you to choose the length and the shape of the little "pointer" than connects the annotation Note with its anchor point.

The "C-comment" button is only important when you generate C-source code from a circuit ("MakeCode" command). If it is on, the annotation Comment will be embedded as a C-comment in the generated code.

The "Small-Tall" button sets the size of the annotation dialog window.

How to use annotations for container connectors

When an annotation inside a container that has connectors is placed in such a way that its "leg" extends into the rectangle that indicates a connector, the corresponding connector will inherit the text in the annotation Note as a description that is displayed in Neo's "info" mode when the mouse pointer visits the connector from outside (cf. this paragraph). This is useful to document the meaning of connectors of more complex containers to facilitate their use. Here is a small example#1.

Special Annotations

There are a few keywords that, when they are the first token in the annotation Note, give rise to a special interpretation of the entire annotation. Such special annotations are rendered on a raised button-like rectangle to make them visually stand out.

MANPAGE: the presence of this keyword indicates that the annotation comment should be considered as a manual page for the subcircuit in which the annotation appears. When a subcircuit containing a MANPAGE annotation is stored in a loadable folder, the icon will carry a little '?' that, when selected, will bring up the manual page in a viewer.

NAME: the presence of this keyword, followed by a token Token, will enforce Token as the name of the circuit that contains the annotation. This is redundant, if the name of a circuit is fixed (in this case, use the "Name" command and and everything is fine). However, sometimes one would like a name to be given as a local or global variable @i or $i (See Section Variables). In this case, a corresponding annotation with NAME @i can achieve the desired effect.

@COMMAND: the presence of this keyword will make the annotation into a "Command annotation". In this case, only the part of the Note after "@COMMAND" will be shown in the circuit window, and the annotation comment will be expected to be a list of commands which will be executed, when the annotation rectangle in the circuit window is clicked at with the mouse pointer. Currently, the only "official" command is "@LOADNEXT circuitfile", which loads circuitfile (if it exists) into the next buffer and switches to that buffer (any previous contents of that buffer will be lost).

How to attach a menu of commands to a unit

Each icon can be bound to an extensible set of commands that can be displayed and invoked via a pulldown menu accessible from the c-field on the icon symbol. Commands can invoke method subunits or NST control calls, as well as a set of predefined operations (cf. below).

The set of available commands for an icon can be edited with the Define command. Each command is a group of tokens, with different groups separated by commas. Only the first token of each group determines the associated command; the remaining tokens are just additional text to appear on the command's pulldown menu line. The command name can also be hidden by prefixing it with a tilde character; this allows to choose a command name that is different from what is visible in the pulldown menu.

Invoking a command in the menu starts the following three-stage search:

1. if the command name identifies a named subicon of the command's icon, the effect of the command is to execute that subicon.
2. If no such subicon exists and the command name is one of the NST control calls (with the optional prefix NST_ omitted and either lower or upper case letters), the effect of the command is to apply the corresponding control operation to the icon.
3. If also this fails, Neo finally checks if the command is among the following set of built-in commands: ``define'', ``load'', ``save'', ``misc''.  If this fails, too, then an error message is given.

If the definition of a command contains the special directives %i or %o, these will be substituted by the current value of input or output pin 0 of field 0 of the named icon that belongs to the command.

To select a different pin or to control formatting, use the extended form %a:b:c:di and %a:b:c:do, resp. This will display the b-th pin of field a using a display field width of c characters and a precision of d characters. The rear part of the specification can be omitted, in which case defaults are used. This allows to display in the pulldown menu also state information and parameters of the current icon (including text strings).

New commands can added just by editing the list in the Define window. In most cases, this will be used to make the operations of particular subunits of an icon conveniently accessible from the 'c'-menu (including, e.g., public routines of prog_unit instances), or to offer a (possibly hierarchical, cf. below) ``mini-browser'' of important internal parameters of the icon.

A long menu with very many entries can be hierarchically organized by grouping commands with curly brackets (e.g.,  ini,exe,{foo,sub1,sub2},more,less). Any such group will then appear only with its first entry (e.g., foo) in the top-level menu, the remaining entries (sub1,sub2) are ``hidden'' in a cascading submenu (this can be extended recursively to more than one nesting level). If an entry in the ``leaf'' of a chain of cascaded submenus is selected (e.g., sub2), the actual command is built by concatenating the selected command the actual command is built by concatenating the selected command names of all the submenues in the chain, with colons in between (producing the command foo:sub2 in the present example). In this way, it is possible to call named units deep down in the container hierarchy of an icon.


[PREVIOUS] [NEXT] [UP]