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 shell script Arranger.sh in a Linux environment or the batch file Arranger.bat in a Windows environment, respectively. You fid both files in the Structorizer folder (i.e. where you unpacked the downloaded Structorizer package). Alternatively you might start the following command from the command line, 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 "Arranger tool button 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 into 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 an already open 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 => Arranger tool button 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).
  6. Import source code containing several subprograms (see import options).
Of course, a large number of diagrams in Arranger have their price: the many synchronisation dependencies will reduce responsiveness to user interaction. So, having gathered many diagrams on the Arranger surface, the contrary aim might get interesting, too: How to get rid of them. You may simply click on a diagram and then press the "Drop diagram" button. If the diagram is "dirty" (i.e. has unsaved changes) then you will next be asked whether to save or discard the pending changes. Via Escape you may cancel the removal attempt. For larger numbers of diagrams, this method tends to suck. So version 3.28-05 introduced a button mode "Remove All": Just press the shift key and the "Drop diagram" button will immediately change its caption and symbol (as does the zoom button next to it, see next subsection) and now allows you to remove all diagrams at once:
Arranger toolbar with shift button
Of course, if several "dirty" diagrams are held in Arranger, you will be asked for each of them whether and possibly where to save them. The message box coming up in this case allows you to apply your decision to all remaining diagrams (versions ≥ 3.28-05 only):

Serial decision opportunity

Zooming

Traditionally (i.e. before version 3.27-08) the diagrams had the sime size in Arranger as in Structorizer. This tended to get impractical when there are many or large diagrams (or both) parked in the Arranger. To gain an overview of the numerous arranged diagrams, to see a preview how the exported bitmap would look like, or e.g. visually to follow the control flow through an algorithm with deeply nested subroutine calls on execution, you may now simply zoom out as far as necessary by clicking on the zoom button  zoom out button in Arranger  or by pressing the "-" key on the number pad of your keyboard repeatedly:

Arranger after zooming out

Each click reduces the size by about 10 % of its former dimensions.

If you want to zoom in again, simply press the "+" key on the number pad or hold the shift key pressed and click on the zoom button, which will change its icon and effect while the shift key is held down:

Arranger with large number of diagrams and pushed shift key

Alternatively, you may also zoom in or out by means of the mouse wheel while the <Ctrl> key is pressed, in the way known from many other applications (you may even configure the reverse zooming effect in the "Preferences > Mouse wheel" submenu).

The maximum zoom is 100 %, i.e. you cannot magnify the diagrams larger than they currently are in the Structorizer editing environment (as controlled by the font size).

Btw, the last zoom factor of your session is retained in your configuration file (structorizer.ini), so you will automatically start with the same Arranger zoom factor the next time you use Structorizer.

Due to rounding effects, the element text may be a little too small for the element size with some zoom factors.

Note that the PNG image export (leftmost button in the menu bar) will compensate the zoom lest the exported picture should suffer from detail losses or degraded resolution. The exported image will always contain the diagrams in original size (i. e. the size they appear in the Structorizer work view). The dimensions on the PNG image may get fairly large with an abundantly filled Arranger, but you may scale or decompose the image file with practically all usual image viewers.

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, at last includables) and signature (lexicographically among the diagrams of same type). 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. (This will not modify the zoom factor in Arranger.) So you can identify the diagrams even in case the zoom factor doesn't allow to make out the names of the diagrams.

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 Structorizer work area before. If the diagram to be replaced has got pending unsaved changes then you will be asked whether to save the changes first. (Provided the diagram is also present in Arranger, the changes wouldn't get lost if you decline, but the risk of inadvertent losses may increase.)

By pressing the <del> key you may remove the selected diagram from the Arranger surface (and from the index, of course). The diagram may still be held by some dependent Structorizer instance though. If the diagram had unsaved changes then you will again be asked whether you want to save them first. This may really be the last chance not to lose them.

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

Since version 3.28-05, a fifth popup menu item ("Remove All") allows you to clean Arranger by dropping (removing) all the diagrams gathered there.

Arranger index with context menu

From version 3.28-08 on, you may also open the Attribute Inspector for the selected diagram via the popup menu:

Attribute inspector item in contect 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 all involved diagrams at 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.

Hint: you might replace the file name extension of an ".arrz" file by ".zip" in order to "unzip" it with some standard compressor tool (or you could temporarily associate the .arrz file extension with a standard compressor tool as default program). 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.

The file types ".arr" and ".arrz" are not automatically associated to Structorizer as default application if you download the locally installable product by now. With the WebStart installation it should be done since version 3.28-05, but sometimes the attempt fails, which may even cause WebStart to fail entirely on a Windows system. You might establish such an association manually, however, by means of the respective operation system. Typically you will be offered such an opportunity on double-clicking an existing file of the respective type. (Once such an association is established, the WebSart failure will also be gone.)

PNG Export

Via the button Picture export icon "PNG Export" you can create a PNG file comprising the current diagram arrangement. As stated in section Zooming above, the current zoom factor is neutralised. The dimensions of the exported image are determined by the maximum of the Arranger window size and the actual bounding box around all arranged diagrams, i.e. you cannot export images that contain only subsets of the arranged diagrams. You may of course cut the obtained image with external tools afterwards.

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 Runtime Analysis. (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 Runtime Analysis) 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.