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

File-based customization

Structorizer may be customized in several ways: You may modify the text font, the set of selectible element colours, the dialogue language, the default contents for the elements, redundant (or decisive) keywords for different elements, code export options, and the look and feel. See the subsections for details.

By default, preferences are user-speciifically held in a configuration file (structorizer.ini) in your profile (see bottom of this section).

Usually the settings of the Preferences menu are automatically saved when you leave (close) Structorizer. Modfifications to some preferences, however, may immediately trigger the saving of all preferences, e.g. whenever you commit changes in the export option dialog.

You may force immediate saving by menu item "Preferences › Save or load preferences › Save now":

Preferences sub menu All preferences...

Preferences export and import

In certain contexts it may be desirable to change entire configuration sets frequently or to distribute a set (or subset) of preferences to other users. To facilitate this, the following menu item allows you to save the current configuration (or, since version 3.29-12, also parts of it) to an ini file with name and location of your choice:

Preferences › Save or load preferences › Save to file...

(Before version 3.29-12, the middle menu item had been labelled "All preferences ...".)

Before you are asked for the target file path, a selection dialog will open, offering the opportunitiy to restrict the export to some preference categories (subsets):

Preference category selection dialog

Initially, the checkbox "All preferences" will be selected, such that the category checkboxes below the separator line are inactive and would be ignored for the export. In order to store a subset of preferences you have to unselect the checkbox "All preferences" and may then choose the categories you want to be exported.

Preference category selection dialog

The button "Invert selection" will toggle the selection state of all categories to facilitate both positive (some categories) or negative selections (all but some categories). Structorizer will cache the last category selection pattern used for export for repeated preference exports with same subset but possibly modified options (this cached selection won't be stored for further sessions, though).
Note: An export with all offered categories selected will not be exactly the same as with "All preferences" active: Some options (like author name or name of the license file among the "Saving" options or the recent file history) don't make sense to be exported or don't belong to any of the categories, a complete set of all preferences will only be saved  if "All preferences" is selected.
(Most categories simply correspond to the menu items of the "Preferences" menu. Category "Diagram", however, refers to the presentation settings held in the "Diagram" menu. "Arranger" comprises some Arranger-specific options like the zoom factor, "Find/Replace" conveyes e.g. the search mode settings and the list of recent search and replace patterns from the Find & Replace tool.)

Selective export of preferences can be particularly helpful if you want to set up a central start preferences file in the installation folder.

In order to restore saved settings from an individually saved ini file, use menu item

Preferences › Save or load preferences › Load from file...

Compensating unwanted impacts

If you decide to import preferences from some ini file then it will usually also comprise parser preferences, and these might of course differ from your recent settings. If some diagrams are being open (and relying on the current parser preferences) then they are likely to get stale. To avoid this, Structorizer identifies parser preference changes, shows you the replacement list, and offers you to refactor your diagrams i.e. to adapt them to the new set of parser strings. This might look like in the screenshot below:

Refactoring question after having loaded a preference file

The image shows the Analyser warnings in the report area of Structorizer, which are due to the lost correspondence between used and loaded keywords, and it shows the question box listing all parser preference changes. Obviously, you may select among the refactoring of:

  1. no diagram,
  2. just the currently edited diagram, and
  3. all open diagrams (i.e. including those parked in an associated Arranger, not of course all diagrams stored in your file system).

(The dialog will not pop up if the current diagram is empty and no other diagrams are in the Arranger pool or if no parser preference changes were detected.)

Having pressed one of the buttons "current diagram" or "all diagrams", the resulting diagram(s) would become fully functional again, e.g.:

Refactoring result after after having loaded a preference file

If you refactored diagrams by mistake or you happen not to be pleased with the outcome then you may simply press the "Undo" button to restore the original text. If you had opted to refactor all diagrams then the refactoring of every single diagram may be undone (and redone) independently. Just fetch the respective diagram from the Arranger into the Structorizer work area and press the "Undo" button or <Ctrl><Z>.

Standard location of the configuration file

In case of bugs or trouble it may be useful to know where the configuration file resides. As mentioned above, this will usually be some subfolder of the home directory associated with your local account. By default, the name of this subfolder will be ".structorizer" (such that it is hidden from a normal ls command in Linux), but under certain circumstances it may be a platform-dependent application data folder, e.g. "Library/Application/Structorizer" under Mac OS X.

Just consult the "Paths" tab in the "About" dialog, which is accessible via the "Help" menu or with key combination <Shift><F1>:

Paths tab on the About window

Command-line-specified preferences file (versions ≥ 3.29-13)

It is possible to specify an alternative ini file via commandline option on start, e.g. (where the underlined name is just a placeholder for the respective shell or batch script name or the path of the structorizer.exe file from the Windows installation directory):
Structorizer -s /usr/home/goofy/test/quirky.ini

Likewise, you might specify it in a Windows Desktop shortcut link as well:

settings file option in a command line

But beware! If you specify a writable ini file in a command script or shortcut, which is available to many (or even all) users, then all of them will share this very ini file and concurrently write to it, which is bound to cause trouble, inconsistencies, and frustration! If you specify a publicly accessible readonly (i.e. write-protected) ini file, in contrast, then the preferences will initially be read from there, but every user's preference changes will be cached in an automatically created idividiual temporary ini file throughout the session. On next start, all individual changes will be gone (as the temporary ini file will have been forgotten), again the readonly ini file as specified in the command line will define all initial settings, a new temporary ini file will be created and so on. Of course, you might look for the actual path and name of the temporary ini file during the session (on the "Paths" tab of the "About" dialog) and copy it on time (or simply save the preferences to some permanent file within your protected reach before closing Structorizer) in order to load the preferences from this file as soon as Structorizer got started the next time.

So, when makes it sense? Mostly, if you placed Structorizer on a mobile memory device (e.g. an USB stick) in order to work with it as guest on different computers, but want to keep your latest settings on the mobile memory. Then you may prepare the start script (or shortcut) of your mobile installation in this way (i.e. specifying a path on that very drive instead of using the guest home directory).

The specified path may contain system environment variables, of course, as it will be resolved by the operating system shell before starting Sructorizer. So something like %HOMEPATH%, %USERNAME%, %APPDATA% (for Windows) or $HOME, ${LOGNAME}, or $USER (for Linux) might be used to individualize the ini path (but why not use the standard location then?). Note that missing subdirectories along the specified path may automatically be created with this option, even if the creation of the ini file itself should fail! To establish the directory path may fail due to missing privileges. If the ini file redirection fails, however, then Structorizer will fall back to the user-sensitive standard ini file location.

If you want to impose some predominant start preferences for all users but allow them to keep all non-prescribed settings indiviually then the following mechanism is clearly preferrable. Moreover, it works on top of this!

Central predominant start preferences (versions ≥ 3.29-12)

You may place an adequately prepared "structorizer.ini" file (this name is mandatory in this case!) in the Structorizer installation directory (if you are in doubt then the "Paths" tab of the "About" dialog will reveal it); in a manual "installation" the ini file might alternatively be placed in the "Structorizer.app" folder. All preferences stored in this central ini file (it may contain a rather small subset of the available settings, see below) will override the respective individual settings held in the user's home directory (or an ini file specified in the command line, see above) every time the user starts a Structorizer session. None of the other individual settings will be touched. During the session, users may modify all preferences as they like, the preset ones inclusive. But as soon as they start Structorizer next time, the subset of preferences in the central ini file will again override the respective individual settings. This way, certain class-room start settings may be configured and be put to the installation directory in order to ensure some general standards (which can temporarily be changed by the students, though). Renaming or removing the central "structorizer.ini" file will avert the mechanism. Note that individual settings of the users will never be saved back to the central ini file (not even if it is writable) but always to the individual ini file (in the user's home directory). (In former versions, the presence of such a central ini file had the problematic effect that all users concurrently — and that means in a conflicting way! — wrote their settings, including the list of recent files and directories etc. to the common ini file, as it is the case with a command-line-specified ini file, see previous subsection.) So, all individual settings not being in conflict to the predominant central file will survive between sessions. It makes sense to limit the central predominant preferences to the necessary minimum. Note that this mechanism also overlays the one described in the previous subsection (i.e. it is still predominant over the command-line-specified ini file).

This mechanism is particularly helpful on PCs (e.g. in a computer pool) where a group of users logs in via the same local account (e.g. a common guest accont), in which case it might be cumbersome each time to get rid of some wanton or awkward preferences left by the preceding user. If you opt for such a central ini file, you may find it helpful that version 3.29-12 enabled Structorizer to export partial ini files, i.e. files with certain subsets of preference categories. See Preferences export and import above. This spares you an ardous manual modification of a full configuration file (which contains the numerous key-value pairs in random order).

A specific preference that only makes sense in a predominant ini file and may only manually be inserted is "noExportImport=1", as introduced by version 3.30-11. It suppresses all code export and code import features, i.e., removes them from all the menus and disables them. This mode cannot be switched off inidviually within the user's session. (It was introduced on customer request, for examination purposes.)

Note that the central predominant ini file may not prescribe the GUI Scaling factor ("scaleFactor") since this would prevent the user from effectively adapting the symbol sizes to her needs, because the impact of this preference is postponed to the next Structorizer start when it would already have been overridden again.

An obvious alternative way (and the only sensible way in versions before 3.29-12) to distribute certain settings is simply to export a template ini file from an appropriately configured Structorizer instance and to request all users to load this ini file into Structorizer via the "Preferences" menu at the beginning. In this case all subsequent individual modifications will last between sessions.