S T R U C T O R I Z E R - User Guide
Features > Arranger

Purposes

The Arranger is a component chiefly serving three purposes:

  • Its original task is to offer an opportunity to arrange (therefore the name) several logically related Nassi-Shneiderman diagrams on a common canvas and to produce PNG files of such a prepared arrangement.
  • In addition, it may now serve as a pool of callable subroutine diagrams for the executor, i.e. as soon as diagram execution arrives at a Call element, a subroutine diagram with matching signature will be looked for among the diagrams parked in the Arranger (provided it is associated with the Structorizer).
  • Closely related with the previous purpose, it may also serve to find and involve called subroutines on code export (also see export options).

How to open the Arranger?

There are three different ways to open the Arranger:

  1. By executing the following command from the system shell (or by starting a shell script with this content), providing the Structorizer directory is the working directory:
    java -cp Structorizer.app/Contents/Resources/Java/Structorizer.jar lu.fisch.structorizer.arranger.Arranger
    In this case, the Arranger will start with an empty drawing area (see below how to push diagrams into the Arranger) and will play the role of the master of all Strucorizer instances initiated from here.
  2. By pressing the Arranger button (Arranger tool button) in the toolbox or the "Arrange" item in the "File" menu of Structorizer. In this case, the currently edited diagram will be pushed to the Arranger. As a side effect, the Arranger will be associated with the Structorizer. The Structorizer remains the master of the Arranger and of further instances of Structorizer possibly launched from the Arranger in turn.
  3. By loading (or dragging) an arrangement file within Structorizer. In this case, too, the loaded diagrams will be associated to the Structorizer instance and be pinned.

Arranger with two diagrams

How to put diagrams into the Arranger?

There are several possible ways to put a diagram to the Arranger:

  1. Press the "New Diagram" button in the Arranger toolbar (see image above) to add an empty new diagram to the drawing area. To fill in content, just open a new Structorizer instance by double-clicking the diagram. Now you can edit the diagram in the usual way. All changes you perform will immediately be reflected within the Arranger canvas.
  2. Select one or more NSD files (e.g. in the respective GUI file manager of your operating system), drag the selection into the Arranger area, and drop it here.
  3. While working on a diagram with Structorizer, press the Arranger tool button tool button or menu item "File => Arrange". This way, Structorizer and Arranger will nearby be associated, and all manipulations with the diagram will be synchronized to the Arranger. The diagram will automatically be "pinned" (see image), which protects it against replacement in the Arranger when the diagram is replaced in the Structorizer.
  4. Press <Ctrl><C> in an open Structorizer instance while the entire diagram is selected in order to copy it to the clipboard and then press <Ctrl><V> in the Arranger window to paste it here (cf. Copy Element).
  5. Load a stored arrangement (see next subsection).

Arranger Index

As soon as diagrams are placed in the Arranger, the Structorizer GUI (of all associated Structorizer instances, to be more precise) will show a scrollable index of the diagrams currently held by the Arranger just right of the work area (see green box in the screenshot below):

Arranger index shown for the Eliza project

The list presents the signatures (name + number of arguments) and file paths of all diagrams arranged in the Arranger pool, ordered by type (main programs first, then subroutines) and signature. Diagrams with unsaved changes are marked with an asterisk before their names (see "conjugateStrings(4)" in the screenshot above).

By clicking on one of the lines (or by pressing the <space> key), the Arranger will scroll to the referred diagram, bring it to top drawing level (if partially eclipsed by others) and highlight it.

Double-clicking one of the lines (or pressing the <Enter> key) will fetch the related diagram and let it replace the one that had resided in the work area before. If the diagram to be replaced has unsaved changes then you will be asked whether to save the changes first.

By pressing the <del> key you may remove the selected diagram from the Arranger surface (and from the index, of course). If the diagram was held by some dependent Structorizer instance then this Structorizer instance may close.

A context menu (see screenshot below) offers the three actions described above as well. In addition, you may switch on or off the "test-covered" flag of the selected diagram, if the Run Data Tracker is active and the diagram is a subroutine (also see Setting Diagrams Test-covered). The icon border of diagrams marked as test-covered will turn green in that mode (see screenshot above).

Arranger index with context menu

You may reduce or enlarge the width of the Arranger index viewport simply by moving the divider rightwards or leftwards. You may hide the Arranger index entirely by unselecting the menu item "Diagram => Show Arranger index?". Alternatively, you may also toggle the index visibility with keystroke <Shift><F3>.

Diagram work area, Arranger index, and Analyser report list form a focus ring where you may navigate by the <Tab> key in clockwise and by <Shift><Tab> in counter-clockwise direction.

Saving / restoring Arrangements

Via the button "Save List" in the Arranger toolbar you may save the current diagram arrangement for later re-use. You have two options:

  1. To create a simple text file with name extension ".arr" containing just the file paths and window positions of the arranged diagrams (but no diagram content!) in CSV format. This is a lean output and intended for local use where the referenced nsd files stay in place. (Of course, the .arr file might be edited manually to adapt file paths of the referred diagrams if necessary.)
  2. To store a compressed archive with name extension ".arrz" comprising an ".arr" file as mentioned above plus copies of the ".nsd" files of all arranged diagrams. Such an archive is portable to another computer and will exactly conserve the state of the moment of saving. The paths inside the archive are relative such that it can be extracted anywhere (see below).

After having pressed the "Save List" button, a message box will pop up and ask you whether you want to "Save as portable compressed archive?" Press the "Yes" or "No" button if you opt for alternative 2 (for an .arrz file) or 1 (for a simple .arr file), respectivley.

To restore a diagram arrangement from such a saved file press the "Load List" button and select either an ".arr" file previously saved or an ".arrz" archive. The file load dialog offers file filters for both types. The ".arr" filter is pre-selected but you may switch the filter.

  • If you load an ".arr" file but some of the diagram file paths stored in it have become stale in the meantime then the respective diagrams cannot of course be loaded this way (the files not being loadable will be reported in a message box). If the diagrams will have been edited meanwhile, however, then obviously the new content will be displayed, not the one it had got when the list was saved.
  • If you select an ".arrz" file, however, the packed diagrams will always be accessible but they are copies of the original diagrams. If you change diagrams being part of the .arrz archive and save these changes then the .arrz file will be updated, not the original diagrams that had been arranged before the .arrz file was created.
  • Arrangement files of both kinds can simply be dragged into the Arranger window. Moreover, you may also load arrangements via the Structorizer itself - either by selecting such an arrangement in the file open dialog or by dragging such files into the Structorizer work area (though the referenced or contained diagrams will be placed in the Arranger, not in the Structorizer). To restore arrangements via the Structorizer has even the advantage that the imported diagrams will be associated with the active Structorizer instance and be pinned.

Note: you might replace the file name extension of an ".arrz" file by ".zip" in order to "unzip" it with some standard compressor tool. Thereafter you may load the extracted ".arr" file the way described above. This will work while the corresponding uncompressed .nsd files reside in the same directory.

Pinning Diagrams

As mentioned in section How to put diagrams into the Arranger, a diagram that had been pushed from a Structorizer instance into the Arranger will reflect all changes the moment it is edited, selected, executed etc. If the diagram is "unpinned" then this dependency even includes replacement, i.e. if you load a different diagram in Structorizer then the related diagram instance shown in Arranger would also be replaced synchronously. To avoid this, diagrams may be "pinned" in the Arranger (select the diagram and then press the "Pin Diagram" button). The pinned mode is indicated by a blue pin icon in the upper right corner of the diagram. For convenience, the pinning is automatically done on pushing diagrams from Structorizer to Arranger. Pinned diagrams still show all changes while shared but are not replaced when you start a new diagram or load another diagram in the related Structorizer instance. The "Pin Diagram" button actually toggles the pin status, i.e. to "unpin" a pinned diagram just press the same button.

Setting Diagrams Test-covered

There is a button Arranger button to mark subroutines as covered "Set Covered", introduced to support the feature Run Data Tracker. (The button is shown in disabled state in the screenshot at the top of this section.) While the test-coverage tracking mode is activated, you may flag a subroutine diagram parked here as "fully test-covered" such that routine calls to this diagram would immediately be marked as covered even in "deep test coverage" mode (see Run Data Tracker) whithout having to wait until the routine code will actually be covered completely by repeated tests. To withdraw the "test-covered" state just press the "Set Covered" button again - Arranger will simply ask you for confirmation to make sure you didn't touch it by mistake.

The Arranger index in the Structorizer main GUI also allows to toggle the test-covered status of selected diagrams.