CrosswordEditor 2.0 : Manual

Table of contents

You must have JavaScript enabled in your browser to generate the table of contents.

1  Introduction

CrosswordEditor is a Java application for creating, editing and solving crosswords.

It is distributed under version 3 of the GNU General Public License; for details, see the file license.txt that is included in the CrosswordEditor distribution.

The website of the CrosswordEditor project is at http://crosswordeditor.sourceforge.net/ .

1.1  Features

CrosswordEditor has the following features:

A glossary of some of the terms used in CrosswordEditor and in this manual can be found in an appendix.

1.2  Acknowledgements

The author of CrosswordEditor is grateful to Alberich for permitting two of his crosswords (number 15 and number 76) to be used as examples.

2  Requirements

CrosswordEditor is a Java application that requires a Java runtime environment that supports Java SE 8 (Java 1.8), such as Oracle's Java Runtime Environment (JRE), version 8 or later.

3  Contents of the distribution

The following files are included in the distribution:

crosswordEditor.jar The executable JAR (Java archive) file of the CrosswordEditor application.
crosswordEditor-config.xml The configuration file for CrosswordEditor, which contains default values for the configuration properties.
license.txt A copy of the licence under which CrosswordEditor is distributed (GNU General Public License, version 3).
examples/alberich15.xword
examples/alberich76.xword
examples/captureParams.xml
Examples of crossword documents: two cryptic crosswords compiled by Alberich; one has a blocked grid, the other has a barred grid.
Sets of capture parameters for some cryptic crosswords published by British newspapers.
images/crosswordEditor.png
images/crosswordEditor.ico
A 48×48-pixel PNG image and a 48×48-pixel Windows-format icon that can be used to customise a desktop icon for the CrosswordEditor application.
manual/manual.html
manual/images/*.png
manual/scripts/*.js
manual/style/*.css
This manual, its image files, scripts and stylesheets. Any modifications to the manual for the latest version of CrosswordEditor will appear in the online version of the document, to which there is a link on the CrosswordEditor website.

4  Installing and running CrosswordEditor

CrosswordEditor consists of a single JAR (executable Java archive) file, crosswordEditor.jar and a configuration file, crosswordEditor-config.xml, which contains user preferences. The use of the configuration file is optional but recommended. The application can be installed in two ways: with the CrosswordEditorInstaller program or by copying files from the .zip or .tar.gz archive of the CrosswordEditor executable distribution.

4.1  Executing a JAR file

Both the CrosswordEditor application and the installer are executable JAR (Java archive) files that require a Java runtime environment, which includes a program named java for running JAR files — a Java launcher. When you install a Java runtime environment, it may create an association on your system between JAR files and its Java launcher. (Oracle's Java runtime environment on Windows associates JAR files with an additional Java launcher named javaw that runs without a console window.) If so, or if you have created the association yourself, you will be able to run a JAR file directly (eg, by double-clicking on an icon of the JAR file in a file manager). If not, you can run a JAR file by invoking the java launcher tool from a command line and supplying the location of the JAR file as an argument. There are examples below of command lines for running the JAR file of the CrosswordEditor application under Linux/UNIX and Windows.

4.2  Installing CrosswordEditor

4.2.1  Installation with the installer program

The installer is an executable JAR (Java archive) file that requires the same Java runtime environment as the CrosswordEditor application itself. It can be run directly or indirectly in the ways described above.

In the opening display of the installer, you can choose the components that you want to install and the directories in which they will be installed. It is recommended that you install the configuration file in its default directory; the default directories of the other components should also be suitable for most users. If you install the executable file and the configuration file, a file named crosswordEditor-properties.xml will be generated and written to the same directory as the executable file to inform the CrosswordEditor application of the location of the configuration file. This file is required only if the configuration file was not installed in the default directory.

Any existing file that has the same name as an installed file will be overwritten without warning except for a configuration file, whose properties will be preserved if they conflict with the properties of the new file.

The final display of the installer has a Show files command that displays a list of files that were installed. If the installation was successful, you might want to keep a list of the files so that you will know where to find them when you uninstall CrosswordEditor, which does not have an automated means of uninstallation. If the installation failed, you might want to remove any files that were installed.

4.2.2  Direct installation

The direct installation of CrosswordEditor consists simply of copying the JAR file and, optionally, the default configuration file to suitable locations on your system. If the configuration file is not installed in its default directory, you will need to inform the CrosswordEditor application of the location of the configuration file, which can be done either on the command line or in a properties file.

4.3  Running CrosswordEditor

The CrosswordEditor application is an executable JAR (Java archive) file that requires a Java runtime environment. The JAR file can be run directly or indirectly in the ways described above.

If you run the CrosswordEditor application from a command line, the command line may contain configuration properties, including the location of a configuration file. The following subsections describe how to run CrosswordEditor from a command line.

4.3.1  Running under Linux/UNIX

Assuming that your PATH environment variable includes the path to the java tool and that you have copied crosswordEditor.jar to the directory /home/slothrop/bin/crosswordeditor/, the command

java -jar /home/slothrop/bin/crosswordeditor/crosswordEditor.jar

will run the CrosswordEditor application.

The file crosswordEditor.png can be used as the icon for the CrosswordEditor application.

4.3.2  Running under Windows

The CrosswordEditor application does not require a console window, so you can use the javaw launcher rather than the java launcher unless you particularly want a console window. Assuming that your PATH environment variable includes the path to the javaw tool and that you have copied crosswordEditor.jar to the directory C:\Program Files\CrosswordEditor\, the command

javaw -jar "C:\Program Files\CrosswordEditor\crosswordEditor.jar"

will run the CrosswordEditor application.

The file crosswordEditor.ico can be used as the icon for the CrosswordEditor application.

4.4  Uninstalling CrosswordEditor

CrosswordEditor does not have an automated means of uninstallation. To remove it from your system, delete the file crosswordEditor.jar from the location to which it was written when you installed CrosswordEditor. If you want to remove CrosswordEditor completely, you should also delete the configuration file, crosswordEditor-config.xml, which may be at its default location, and any other files that were installed (eg, the manual).

If you created a file association on Windows with the Options > Manage file associations command, it is recommended that you use the same command to remove the file association before you delete CrosswordEditor.

5  Configuration

When it starts up, CrosswordEditor is configured with configuration properties that are read from two sources: the command line that is used to run the Java launcher and a configuration file whose location may be explicitly specified. If the same property is specified on the command line and in a configuration file, the value from the configuration file takes precedence.

The recommended method of setting the properties in a configuration file is with the Options > Preferences command. For command-line properties, which must be edited manually, the form of the property values is given in an appendix, and it can also be inferred by generating a configuration file with the desired values and inspecting the contents of the file.

5.1  Command-line properties

When CrosswordEditor is run by means of the java launcher, configuration properties may be specified on the command line using the standard Java form -Dname="value"; eg, -Dapp.html.cellSize.block="23". (The quotation marks around the value aren't necessary if the value doesn't contain spaces.) CrosswordEditor's command-line configuration properties all have the prefix app. . A list of all the properties that are recognised by CrosswordEditor is given in an appendix.

One particular property, app.configDir, is used to specify the directory that contains a configuration file, as described below. The value of the app.configDir property may contain special constructions for system properties, environment variables and the user's home directory.

5.2  Configuration file

The configuration file is named crosswordEditor-config.xml. CrosswordEditor doesn't require a configuration file: it uses a default value for any configuration property that is missing from the source(s) of configuration. Similarly, if it finds a property value to be invalid, CrosswordEditor will display a message to this effect and use the default value of the property. If the configuration file contains a property that was specified on the command line, the value from the configuration file is used.

If the configuration has changed when you exit the application normally (ie, using the File > Exit command or an equivalent), CrosswordEditor will save its configuration to a configuration file. If a configuration file was read on startup, it will overwrite that file; otherwise, it will write a configuration file to the default directory described above, unless the value of the app.configDir property was an empty string.

A configuration file can be written explicitly with the Save configuration command within the Preferences dialog.

5.2.1  Location of the configuration file

When it starts up, CrosswordEditor is informed of the location of the configuration file with the app.configDir property, which may be set in two ways:

If the app.configDir property is set both in the properties file and on the command line, the value in the properties file takes precedence.

The crosswordEditor-properties.xml file is normally written by the installer. If you create the file manually, it should have the following form, with the example pathname replaced by the actual pathname:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
<properties>
<entry key="app.configDir">/home/slothrop/.blankaspect/crosswordEditor</entry>
</properties>

If the configuration file were located in a directory named config in the user's home directory, the sample command lines given above would become:

Linux/UNIX: java -Dapp.configDir="~/config" -jar /home/slothrop/bin/crosswordeditor/crosswordEditor.jar
Windows: javaw -Dapp.configDir="~/config" -jar "C:\Program Files\CrosswordEditor\crosswordEditor.jar"

The existence and value of the app.configDir property determines the locations that are searched for a configuration file:

6  Documents

CrosswordEditor's documents are called crossword documents in this manual. They are XML documents with a filename suffix that defaults to .xword but that can be configured with the file.filenameSuffix property.

A crossword document consists of several components:

All the components are optional except for the grid.

6.1  Grid

All crossword documents have a grid. CrosswordEditor supports only rectangular, orthogonal grids: two-dimensional arrays of cells, with fields of contiguous cells that run across the rows of the grid from left to right and down its columns from top to bottom.

The parameters of the grid — separator, size and symmetry — are specified when you create a document with the File > New document command. After the document is created, the separator and size of the grid are fixed, but the symmetry can be changed by editing the grid.

6.1.1  Separator

If a row or column of a grid contains more than one field, the fields in the row or column are separated from one another by separators. CrosswordEditor supports two kinds of separator: blocks and bars. A block occupies the cell of a grid; a bar divides two contiguous cells along their common border. A grid may have only one kind of separator.

6.1.2  Size

A grid can have between 2 and 99 rows and columns. The number of rows and the number of columns are independent of one another.

6.1.3  Symmetry

The separators of a grid are often arranged symmetrically, presumably for aesthetic reasons or because it is customary to do so. (In the UK, crossword grids commonly have 2-fold or 4-fold rotational symmetry.) In CrosswordEditor, a grid may have no symmetry or one of the kinds of rotational or reflectional symmetry listed below:

Symmetry: none
None
Symmetry: rotation by half-turn
Rotation by a half-turn
Symmetry: rotation by quarter-turn
Rotation by a quarter-turn
Available only if the grid is square.
Symmetry: reflection in V axis
Reflection in the vertical axis
Symmetry: reflection in H axis
Reflection in the horizontal axis
Symmetry: reflection in V & H axes
Reflection in the vertical and horizontal axes

6.2  Clues

The clues of a crossword document are associated with fields of the grid; each clue must have at least one field ID — a field number and direction. (CrosswordEditor does not currently support crosswords that have a list of unnumbered and directionless clues for which the solver is required to discover the field number and direction.)

6.3  Indications

A crossword document may have three indications: a clue-reference keyword, an answer-length pattern and substitutions, and a line-break sequence. A document's indications can be editied with the Edit > Edit indications command.

6.3.1  Clue-reference keyword

A clue-reference keyword is a specific word, phrase or symbol in the text of a clue that indicates that the clue contains a reference to another clue instead of a definition. The clue containing the reference is associated with a secondary field of a multiple-field clue that contains a definition. In the UK, the clue-reference keyword is usually the word "See", which is the default for CrosswordEditor. For example, if the clue for 5 across were

5, 23  A Chinese city (4,4) ,

the clue for 23 across would be the reference

23  See 5a

in which the word "See" is the clue-reference keyword.

A clue-reference keyword is stored with a document only if the lists of clues contain at least one reference. Conversely, if you open a document that contains no clue references, it will have no clue-reference keyword, so you will need to specify one if you add a reference to the clue lists.

6.3.2  Answer-length pattern and substitutions

An answer-length pattern and substitutions are used to find and process answer-length expressions in the document's clues. An answer-length expression is an optional component of a clue that indicates the length of its answer. If it is present, it must come at the end of a defined clue (ie, a clue that is not a reference). It usually consists of one or more numbers separated by punctuation and enclosed in parentheses. For example, in the clue

5, 23  A Chinese city (4,4) ,

the answer-length expression is "(4,4)".

An answer-length expression is processed in two stages: a pattern (a regular expression) is used to search for an answer-length expression in the text of a defined clue, then a list of substitutions is applied to any text that matches the pattern. The substitutions, whose target can be either literal text or a regular expression, are intended to remove numbers that don't contribute to the answer length (eg, the 2 in "(9, 2 words)"). After any substitutions are applied, numbers are extracted from the resulting text and added together to give the answer length.

A document's default answer-length pattern should be suitable in many cases. It matches a pair of parentheses, '(' (U+0028) and ')' (U+0029), at the end of a clue, with a decimal digit immediately after the opening parenthesis and zero or more characters, excluding a '(', between the digit and the closing parenthesis; for example, "(6)", "(3,7)", "(10-4)" or "(12, two words)".

If the clues of a crossword don't have answer-length expressions, is is recommended that you specify an empty answer-length pattern to avoid the possibility that part of a clue will be interpreted as the answer length.

6.3.3  Line-break sequence

A line-break sequence (usually referred to as a line break) is used in a prologue or epilogue to start a new line without starting a new paragraph. Its default value is specified by the textSection.lineBreak configuration property, which itself defaults to $$.

A line-break sequence is stored with a document only if there is at least one line break in the document's prologue or epilogue. If you edit the prologue or epilogue of a crossword document that was created by someone else, be aware that the document's line-break sequence might be different from the default value.

6.4  Text sections

A crossword document may have three text sections: a title, a prologue and an epilogue. The title and prologue are displayed above the grid; the epilogue is displayed below the grid and clues. (In the UK, the text above a grid is usually called a preamble, but the word does not have a counterpart that means "text that comes after", so prologue and epilogue were chosen instead.) The title is a single line of text whereas the prologue and epilogue may consists of multiple lines of text divided into paragraphs.

The prologue and epilogue support some basic text styles: bold, italic, superscript, subscript, underline and strikethrough. When a crossword document is exported as HTML, each paragraph of a prologue or epilogue has its own <p> element.

You can edit the text sections with the Edit > Edit text sections command.

6.5  Grid entries

Any entries that you make in the grid of a crossword will be saved with the crossword document, allowing you to solve a crossword over several sessions. If you want to restore the crossword to its original state after you've completed it, you can clear all the grid entries with the Edit > Clear all grid entries command.

If a crossword has a full set of grid entries, it is said to be complete, and the word "Complete" will be displayed in the status panel of the main window. When you've completed a crossword, you can set the document's solution to the grid entries with the Solution > Set solution to current entries command.

6.6  Solution

The solution is the set of correct answers to all the clues of a crossword. A crossword document may contain a solution or it may have a URL reference to another document containing a solution; in both cases, the solution may be protected by a passphrase. The passphrase facility is intended for use in crossword competitions.

If a document contains a solution, the word "Solution" will be displayed in the status panel of the main window. The solution is encrypted in the XML file of the document using the Salsa20 cipher with either a passphrase chosen by the crossword's author or, if no passphrase was specified, an empty passphrase that gives unrestricted access to the solution from within CrosswordEditor.

If a document contains a solution that is protected with a passphrase, you must enter the passphrase when you open the document. If you cannot supply the passphrase, you will still be able to open the document but the solution won't be loaded, and the document won't contain the solution if you subsequently save it.

If a document (called a public document) contains a URL reference to a separate solution (in a solution document), the external solution can be loaded from the location specified in the public document with the Solution > Load solution command. If the solution is protected with a passphrase, you must enter the passphrase in order to load the solution. CrosswordEditor checks that the external solution belongs to the crossword by comparing an authentication code in the public document with one in the solution document. When you create a linked pair of public document and solution document, you must ensure that the two documents have the same authentication code; a procedure for achieving this is described below.

6.6.1  Publishing a crossword with a solution

There are four ways in which a crossword may be published with a solution: the document may either contain a solution (internal solution) or a URL reference to a separate solution (external solution), and the solution may or may not be protected with a passphrase.

  1. Internal solution, no passphrase
    There is unrestricted access to the solution from within CrosswordEditor. This option is unsuitable for competitions.
  2. External solution, no passphrase
    You can control global access to the solution on a remote server by, for example, placing it at the specified location after the closing date of a competition.
  3. Internal solution, passphrase
    The solution is distributed with the crossword document but is accessible only with the passphrase. You could, for example, publish the passphrase after the closing date of a competition, obviating the need for the separate solution document in option 2.
  4. External solution, passphrase
    The solution is accessible only with the passphrase. This option is a belt-and-braces combination of options 2 and 3 for competitions.

If you use CrosswordEditor to publish a crossword competition, it is recommended that you use option 2 if you are able to make a solution document publicly accessible on a server, or option 3 otherwise. If it is available to you, option 4 gives most control over access to the solution.

6.6.2  Creating a separate solution document

You can use CrosswordEditor to publish a crossword in several ways, as discussed above. If you choose to do so by distributing a crossword document that contains a URL reference to a separate solution, you must ensure that the two documents have the same authentication code. One way of achieving this is to create the two documents from the same master document by following the procedure described below, in which the following terms are used:

Here is the procedure:

  1. Create or open the master document.
  2. Set the passphrase of the solution of the master document with the Solution > Edit solution properties command. If you want the solution to be accessible without a passphrase, ensure that the Passphrase field of the Solution properties dialog is empty.
  3. Create a solution document with the Solution > Create document containing solution command.
  4. Save the solution document that was created in step 3. It will be saved with the solution from the master document, and the solution will be accessible through the passphrase that was set on the master document in step 2.
  5. Save the master document under a different name from the original with the File > Save document as command. This will be the public document.
  6. Set the location of the solution of the public document with the Solution > Edit solution properties command. Do not change the passphrase.
  7. Edit the public document for publication; for example, clear any grid entries.
  8. Save the public document, which will contain a URL reference to the solution document instead of the solution.

7  The display

7.1  The main window

CrosswordEditor uses a tabbed document interface to display multiple documents. This kind of interface has a single tabbed window in which only one document — referred to as the current document — is visible at any one time. Each open document has its own view in a tab of the main window. A maximum of 64 documents may be open simultaneously.

You can select a document by clicking on its tab, or you can select a document from the alphabetically ordered list that is displayed by clicking on the down-arrow button at the right of the tab bar. You can move between documents by pressing Ctrl+PageUp and Ctrl+PageDown.

The main window can be moved and resized in a platform-dependent manner (for example, it may be possible to change the size by dragging a corner of the window). It can also be resized to the size of the current crossword view with the View > Resize window to view command.

The location of the main window can be saved between CrosswordEditor sessions according to the preference for saving the main window location. The size of the main window is saved when CrosswordEditor exits normally, and the size of the main window is set to the saved value when the program is next run.

7.1.1  Crossword view

A crossword document is displayed in a crossword view, which contains several components that correspond to the components of the document, some of which are optional. A view always has a grid and two lists of clues, although the lists may be empty. The width of the view can be controlled indirectly with the view.selectedClueNumColumns property. The colours of many of the components and subcomponents of a crossword view are configurable.

7.1.1.1  Title

The topmost component of a crossword view is an optional title, which is drawn in a bold variant of the main font, if one is available, and in a configurable colour (Text) that is shared with the other text sections. The title can be edited with the Edit > Edit text sections command or by double-clicking the left mouse button on it.

If a title is present, a horizontal line is drawn below it in a configurable colour (Title separator).

7.1.1.2  Prologue

Below the title is an optional prologue that may comprise multiple lines of text with some basic styling. The paragraphs of a prologue are separated by extra vertical space.

The text of the prologue is drawn in the main font and in a configurable colour (Text) that is shared with the other text sections. The prologue can be edited with the Edit > Edit text sections command or by double-clicking the left mouse button on it.

7.1.1.3  Grid

The grid is drawn below the prologue, on the left side of the view. The size of a cell of the grid can be configured with the grid.cellSize.block property for a blocked grid and the grid.cellSize.bar property for a barred grid. Grid lines and separators (blocks or bars) are drawn in a configurable colour (Grid line and separator).

Within the grid, the background of the fields of the currently selected clue are drawn in configurable colours: Background, focused selected field if the view has focus, Background, selected field otherwise. Field numbers are drawn in their own font (Field number) and configurable colour (Text, field number). Grid entries, too, are drawn in their own font (Grid entry) and configurable colour (Text, grid entry).

When a crossword view has keyboard focus, a blinking caret is drawn in a cell of the selected field to indicate the position of the next grid entry. The caret, which is drawn in a configurable colour (Caret), can be moved around the fields of the grid with the following keys:

Left Move left by one column
Right Move right by one column
Up Move up by one row
Down Move down by one row
Home Move to the first cell of the field
End Move to the last cell of the field

Depending on the setting of the grid.navigateOverSeparators configuration property, the caret may either stop when you try to move it beyond a separator or it may move over the separator to the next field in the row or column.

You can select a field and its corresponding clue by left-clicking on the field. If you click at an intersection of fields in the grid, the selection switches between the across and down fields. When the caret is at an intersection of fields, you can switch between the across and down fields with the following keys:

Ctrl+Left Select the down field
Ctrl+Right Select the down field
Ctrl+Up Select the across field
Ctrl+Down Select the across field
7.1.1.4  Selected clue

To the right of the grid is an area in which the currently selected clue is displayed. The width of this area can be configured with the view.selectedClueNumColumns property.

7.1.1.5  Clues

Below the grid are the lists of clues for each of the directions, across and down. The clues are drawn in their own font (Clue) and configurable colours: Text, clue if the clue exists, Text, empty clue otherwise. The field IDs of each clue and the headings of the clue lists are drawn in a bold variant of the clue font, if one is available. The selected clue (including any references) has a highlighted background, drawn in configurable colours: Background, selected clue if the clue exists, Background, selected empty clue otherwise.

When a crossword view has keyboard focus, you can change the clue selection with the following keys:

Tab Select the next clue
Shift+Tab Select the previous clue
7.1.1.6  Epilogue

The bottommost component of a crossword view is an optional epilogue that, like the prologue, may comprise multiple lines of text with some basic styling. The paragraphs of an epilogue are separated by extra vertical space.

The text of the epilogue is drawn in the main font and in a configurable colour (Text) that is shared with the other text sections. The epilogue can be edited with the Edit > Edit text sections command or by double-clicking the left mouse button on it.

7.1.2  Status panel

At the bottom of the main window, below the tabbed document panel, is a status panel comprising two fields, which may be empty. The fields have the following contents:

  1. The text "Solution" if the current document contains a solution.
  2. The text "Complete" if the all the cells of all the fields of the grid of the current document have entries.

The colour of the text of the status panel is configurable.

7.1.3  Drag-and-drop support

If your system supports the dragging and dropping of files (for example, from a file manager such as GNOME Nautilus or Windows Explorer), you can open multiple files by dragging and dropping them onto the main window. A file is opened only if its filename has the suffix specified by the file.filenameSuffix configuration property.

7.2  Graphical components in dialog boxes

Dialog boxes are displayed in response to some of CrosswordEditor's commands. Some of the dialogs contain non-standard graphical components or standard components that have unusual features.

7.2.1  Spinner

A spinner is a graphical component for editing a numerical value. It consists of a text field adjacent to a pair of small buttons. The value in the text field may be edited manually, or it may be incremented and decremented by one of the following methods:

Using the last two methods, the amount by which the value is incremented or decremented can be modified by holding down the Ctrl, Shift or Ctrl+Shift keys, which correspond to increments of 10, 100 and 1000 respectively.

7.2.2  Single-selection list box

A single-selection list box contains a list from which only one item can be selected. The position of an item in the list can be changed by dragging it up or down the list with the left mouse button, or by pressing Ctrl+Shift+Up or Ctrl+Shift+Down when the list box has keyboard focus.

A list box appears in a panel with a set of buttons, some of which issue commands that apply to the selected item in the list.

7.2.3  Pathname field

A pathname field is a text field that is intended to hold the pathname of a file or directory. The browse button () adjacent to the field brings up a file-selection dialog whose selection will be displayed in the field if the dialog is accepted. If the field is not empty, its background colour is different from when the field is empty.

The pathname in the field may contain special constructions for system properties, environment variables and the user's home directory.

You can transfer a file or directory to a pathname field by drag-and-drop or by copy-and-paste from a file manager.

7.2.4  Text panel

A text panel is a text area that supports multiple lines of text and some basic text styles, along with a set of buttons for issuing commands to apply the styles to selected text. The buttons of a text panel are disabled if no text is selected.

Text panels are used for editing the clues, prologue and epilogue of a crossword. The text of a clue is treated as a single, indivisible paragraph whereas the text of a prologue and epilogue may be divided into multiple paragraphs, with paragraphs separated by one or more empty lines.

In addition to multiple paragraphs, a prologue and epilogue may contain line breaks, which have the effect of starting a new line without starting a new paragraph, like a <br> element in HTML. A line break is denoted by a line-break sequence, which must come at the end of a line, with no space after it. The line-break sequence of a document can be set with the Edit > Edit indications command. By default, it is set to the value of the textSection.lineBreak configuration property, which itself defaults to $$.

Edits made in a text panel may be undone and redone with Undo and Redo commands, which can be issued from the keyboard (Ctrl+Z and Ctrl+Y respectively) or from a context menu.

7.2.4.1  Style markup

Markup is used for styles within the text area. A sequence of characters to which one or more styles is applied is called a span. Spans may be nested (ie, one span may contain another). A span cannot extend across paragraphs in a prologue or epilogue.

A span has the form {@<keys><separator><text>} . The prefix "{@" must be followed immediately by one or more keys: lower-case alphabetic characters in the range a to z. The first non-key character after the keys is a separator; it is ignored. The text of the span follows the separator, and the span ends with the suffix "}".

The characters '{' (U+007B), '}' (U+007D) and '\' (U+005C) are metacharacters; that is, they have a special meaning within the text. If you want the corresponding literal characters, you must escape the metacharacters by prefixing '\' to them: "\{", "\}" or "\\".

CrosswordEditor recognises only the keys in the following table; any others will result in an error message.

Style Key Command
Bold b Ctrl+B
Italic i Ctrl+I
Superscript h  (for high) Ctrl+H
Subscript l  (for low) Ctrl+L
Underline u Ctrl+U
Strikethrough s Ctrl+S

The keys h (superscript) and l (subscript) are mutually exclusive: they cannot both appear in the same span.

Here are some examples of style markup:

Here, the separator is a {@u space}; here, it is a {@u:colon}.
This example includes {@b bold text} and {@bi text that is both bold and italic}.
In this example, some {@b bold text has {@i italic text} within it}.
To get a literal '\{' or '\}', prefix a '\\' to it.

A style can be applied to a sequence of characters in a text area by selecting the characters and issuing the appropriate command, either by using a button below the text area or by a keyboard shortcut from the Command column in the table above. The command will apply style markup to the selected text, taking any paragraph breaks into account, but it will not consolidate multiple styles into a single span.

8  Capturing an external crossword

CrosswordEditor allows you to create a crossword document from an external source (eg, a crossword on a web page or in a PDF file), by "capturing" the grid and clues of the external crossword. The capturing process is controlled from the Capture crossword dialog, which is displayed in response to the Crossword > Capture crossword command.

The grid of a crossword is captured by processing an image that contains the grid. The grid may be detected within the image automatically, or it may be selected manually if the automatic detection algorithm cannot be made to work with a particular grid. CrosswordEditor gets the image from the system clipboard; the way in which you can copy an image containing the grid to the clipboard will depend on the source and on the tools available on your system. For example, if the grid is an image in a web page, the image could be copied to the clipboard with the Copy Image command from the context menu of the Firefox web browser, or it could be saved as a separate file, loaded into an image viewer and copied to the clipboard. Alternatively, your system might have a means of taking a screenshot of the window of an application (eg, a web browser or PDF viewer) in which the grid is displayed. (In Windows and in the GNOME desktop environment for Linux, this can be done by pressing Alt+PrtSc.)

The clues of a crossword are captured by processing separate lists of across clues and down clues. CrosswordEditor gets each list of clues from the clipboard as plain text; the way in which you can copy a list of clues to the clipboard will depend on the source and on the tools available on your system. For example, you could select the text of the clues from a web page or PDF document, and copy them to the clipboard with the standard Copy command of a browser or PDF viewer. If the clues that you copy to the clipboard are not formatted in a way that is acceptable to CrosswordEditor, you may need to paste them into an intermediate document (eg, in a text editor), perhaps edit them, then copy them to the clipboard again.

8.1  The Capture crossword dialog

The parameters that govern the process of capturing a crossword are controlled from the tabbed panels of the Capture crossword dialog. To avoid the need to set all the parameters each time you want to capture a crossword, most of them can be saved together as a parameter set that can be loaded, edited and applied when you next want to capture a similar crossword.

At the bottom of the dialog is a status panel comprising three fields, which may be empty. The fields have the following contents:

  1. The text "Grid" if a grid has been imported.
  2. The text "Clues - Across" if a list of across clues has been imported.
  3. The text "Clues - Down" if a list of down clues has been imported.

The colour of the text of the status panel is configurable.

8.1.1  The Auto grid detection tab

The Auto grid detection tab controls the parameters that apply to the automatic detection of a grid in an image that is imported from the system clipboard with the dialog's Get grid command. The grid-detection algorithm is crude: it looks for sets of horizontal and vertical lines that occupy the same area of the image. You are expected to tune its parameters so that it can distinguish a grid from other sets of horizontal and vertical lines in the image. Some trial and error may be required to set the parameters for crosswords from a particular source.

The algorithm detects a grid line (more properly, a line segment) when it encounters a sequence of "dark" pixels: pixels whose brightness lies below the value specified by the Brightness threshold spinner. To allow for lines that are more than one pixel wide, adjacent lines of dark pixels are treated as a single line. A pixel's brightness can vary from 0 (black) to 100 (white), and the brightness threshold for grid lines can vary between 1 and 99. A grid with light grey lines, for example, would a need a fairly high brightness threshold. Grid lines must be continuous, so that, for example, lines that have shadows to make them appear ridged or grooved would be problematic if orthogonal lines intersected in a way that made one or both lines discontinuous for all brightness thresholds.

The Minimum length spinner specifies the minimum length (in pixels) of a grid line. It could be used, for example, to distinguish the grid of interest from a small grid containing the solution to a previous puzzle.

The Minimum separation spinner specifies the minimum distance (in pixels) between successive grid lines of the same orientation.

The Endpoint tolerance spinner specifies the amount (in pixels) by which the endpoint of a line can vary and still be considered to belong to a set of grid lines. It is, in effect, the width of a border around the grid that the endpoints of all grid lines must lie within.

8.1.2  The Grid tab

The Grid tab controls the parameters that apply to the detection of separators in an image of the grid. The way in which separators are detected differs according to the kind of separator:

The Grid separator drop-down list allows you to choose the separator of the grid.

The Grid size spinners specify the dimensions of the grid. If the grid-detection algorithm was successful, you can choose to set the dimensions to those detected by the algorithm; otherwise, you'll have to count the columns and rows of the source crossword. The button to the right of the spinners links and unlinks the values of the two spinners.

The Automatic grid detection check box enables and disables the grid-detection algorithm.

The Grid size spinners specify the dimensions of the grid. If the grid-detection algorithm was successful, you can choose to set the dimensions to those detected by the algorithm; otherwise, you'll have to count the columns and rows of the source crossword. The button to the right of the spinners links and unlinks the values of the two spinners.

The X offset and Y offset spinners specify the offset of the sample point (blocked grid) or start of the sample line (barred grid) from the centre of the cell. For the x offset, the value is a percentage of the cell width, and the positive direction is right; for the y offset, the value is a percentage of the cell height, and the positive direction is down.

For a blocked grid, the Sample size spinner specifies the dimension of the square of pixels that will be sampled to determine the presence of a block. A single pixel will be sufficient if the block is of a solid colour.

For a barred grid, the Bar-width threshold spinner specifies the minimum width of a sampled cell border that will be deemed to be a bar.

The Brightness threshold spinner specifies the threshold below which a pixel is deemed to belong to a separator.

8.1.3  The Clue indications tab

The Clue indications tab controls the clue-reference keyword and the answer-length pattern and substitutions that are applied to the clues that are imported from the external crossword.

The Default button adjacent to the Pattern field sets the answer-length pattern to a default value that should be suitable for UK crosswords.

If you are importing clues that do not have an answer-length expression, or if you cannot specify a suitable answer-length pattern, you should leave the Pattern field empty. In this case, each clue must be on a separate line of text.

The answer-length substitution list can be edited with commands issued from the three buttons to the right of the list. In the dialog that is displayed in response to the Add and Edit commands, the target is the text that is searched for in the answer-length expression and the replacement is the text that will replace all occurrences of the target. You should select the Regular expression check box if the target is a regular expression rather than literal text. In the list box, regular-expression substitutions are indicated by RE in the first column.

8.1.4  The Clue substitutions tab

The Clue substitutions tab controls the substitutions that are applied to the text of defined clues. Clue substitutions are described in the section on the Edit > Import clues from clipboard command.

8.1.5  The Text tab

The Text tab allows the text sections of the captured crossword to be reproduced. The Number field isn't used directly; it is intended to contain a serial number or the least significant digits of a serial number, which can be substituted in the crossword's title and the three fields of the File tab.

The Title field and the Prologue and Epilogue areas provide the text sections of the document that will be created for the captured crossword. All occurrences of the number placeholder, %n, in the text of the Title field will be replaced by the contents of the Number field. The Prologue and Epilogue areas are described in the section on text panels.

8.1.6  The File tab

The File tab facilitates the consistent naming of files and directories relating to a document that is created from a captured crossword. The fields in this tab provide initial values for pathnames, but you are not bound to use the pathnames: you may change them when you save the crossword document or export an HTML from it.

The Base filename field specifies the base filename of both the crossword document and an HTML document that is exported from it. For the crossword document, the base filename is given the suffix specified by the file.filenameSuffix configuration property; for the HTML document, the base filename is given the suffix .html . The Document directory and HTML directory fields specify, respectively, the pathname of the directory of the crossword document and the pathname of the directory of the HTML document.

All occurrences of the number placeholder, %n, in the text of the three fields in this tab will be replaced by the contents of the Number field of the Text tab.

8.1.7  Parameter sets

With the exception of the Number field and the Prologue and Epilogue areas in the Text tab, all the parameters that correspond to controls in the tabs of the Capture crossword dialog constitute a parameter set that can be given a name and saved to the file specified by the path.parameterSetFile configuration property. A parameter set saved in this way can subsequently be loaded, avoiding the need to specify the values of the parameters again when capturing a similar crossword. An existing parameter set can be updated with the current values of the parameters.

8.1.8  The Manage parameter set command

The Manage parameter set command brings up a dialog box in which you can manage the parameter sets of CrosswordEditor's parameter-set file. If no parameter-set file is specified by the path.parameterSetFile configuration property, you will be asked to choose one. Any changes that you make to the parameter-set file from within the dialog won't take effect until you close the dialog with OK.

On the left of the dialog is a list box that shows the names of the parameter sets in the parameter-set file. If you double-click the left mouse button on a name in the list, the corresponding parameter set is loaded and the dialog is accepted as though you selected OK.

To add the current parameters as a new parameter set, enter the name in the Name field and issue the Add command. If the named set already exists, you will be prompted to replace it, which is equivalent to issuing the Update command.

The Delete command removes the selected parameter set from the list after prompting for confirmation. The command can also be issued by pressing the Delete key when the parameter-set list has keyboard focus.

The Load command sets the parameters to the values of the selected parameter set.

The Update command updates the selected parameter set with the current parameter values.

The Reset command resets the parameters to their default values.

If you close the dialog with OK, any changes that you made to the parameter-set file will be saved, and any changes that you made to the parameters of the Capture crossword dialog will be applied. If you close the parameter-set dialog with Cancel, any changes that you made will be cancelled.

8.1.9  The Clear command

The Clear command removes a captured grid and clues, and it clears the controls that don't correspond to elements of the parameter set: the Number field and the Prologue and Epilogue areas.

8.1.10  The Get grid image command

The Get grid image command first reads an image from the system clipboard. If the Automatic grid detection check box of the Grid tab is selected, the grid-detection algorithm is applied to the image. If it finds something that appears to be a grid in the image, a message is displayed to this effect, asking if you want to set the numbers of columns and rows of the grid to those found by the algorithm; otherwise, an error message is displayed.

Next, a dialog box is displayed in which you can select the grid from the image that was read from the clipboard. If automatic grid detection was successful, the region of the grid containing the grid is already selected; if the region is incorrect, you can make a new selection. You make a selection in the Select grid in image dialog by clicking the left mouse button on a corner of the grid in the image, dragging the mouse so that the rubber-band box roughly coincides with the boundary of the grid, then releasing the button. To proceed with the selected region, close the dialog with OK.

A grid will be created from the selected region of the image by applying the parameters in the Grid tab to detect the grid separators, and the text "Grid" will be displayed in the first field of the status panel. The grid might not be correct, but you won't discover this until a crossword document is created and displayed. If you are tuning the parameters in the Grid tab, you can skip the capture of clues (and the error message about missing clues) to view the result of the grid capture.

The command is enabled only if there is an image on the system clipboard.

8.1.11  The Get clues command

The Get clues command has two subcommands, one for each grid direction, across and down; select the appropriate subcommand. The command reads text from the system clipboard and processes it. The clue parser expects to find a list of clues, and it expects each clue to have a certain format: a list of comma-separated field IDs, followed either by a clue definition and an optional answer-length expression or by a clue reference.

The direction keywords specified by the clue.directionKeywords.across and clue.directionKeywords.down configuration properties are used when parsing the field IDs of a clue.

The clue-reference keyword and the answer-length pattern and substitutions that you specified in the Clue indications tab will be used to process each clue and to determine its end. If the clues do not have an answer-length expression, each clue must be on a separate line of text; otherwise, a clue can extend over multiple lines. You might need to edit the list of clues that you copy from an external crossword to ensure that the format of the clues is acceptable to CrosswordEditor.

If a list of clues is processed successfully, an indication is displayed in the relevant field of the status panel. The Get clues subcommands parse a list of clues but they don't check the clues for consistency: the clues are validated only when the dialog is accepted with OK.

The command is enabled only if there is text on the system clipboard.

8.1.12  Validation of clues

When the Capture crossword dialog is accepted with OK, a crossword document is created from the grid and any lists of clues that were imported. The clue indications, text sections, base filename and directories of the document are set to the values specified in the relevant tabs of the dialog. Before the clues of the document are set to the imported lists, the clues are validated by checking that they are consistent with each other and with the fields of the grid. If errors are found, a dialog box is displayed in which the erroneous clues are listed, grouped by error kind, field direction and field number. Some possible causes of errors are an incorrect field ID in the source crossword, corruption of text when the clues were copied to the clipboard, incorrect direction keywords or incorrect clue indications. You might be able to fix the errors by examining and editing a problematic list of clues in a text editor before importing it again with the Get clues command.

If you accept the error-list dialog with OK, the clue lists are modified in the following ways:

8.2  Example capture parameters

The file captureParams.xml in the examples directory of the CrosswordEditor distribution contains sets of parameters for capturing four free cryptic crosswords published by British newspapers on their websites:

The parameter sets for the four crosswords provide examples of the automatic grid-detection parameters for various crosswords, and they illustrate the use of a placeholder for a crossword number.

In all four examples, the number placeholder, %n, appears in the Title field of the Text tab and the Base filename field of the File tab of the Capture crossword dialog. It takes the place of the two least significant digits of the crossword's serial number, which you would enter in the Number field of the Text tab. When the two-digit number rolled over to zero, you would need to increment the 100s' digit in the Title and Base filename fields, then update the parameter set.

You can load the parameter sets in the Capture crossword dialog by setting the path.parameterSetFile configuration property to the pathname of the example captureParams.xml file on your system.

9  Exporting a document as an HTML file

CrosswordEditor does not have the ability to print crossword documents: if you want to print a crossword, you will need to export the document as an HTML file and print the file from a web browser. Exported HTML files can also be used as a means of distributing crosswords created with CrosswordEditor in a widely accessible — although non-interactive — form.

An HTML file is exported with the File > Export HTML file command. Most of the parameters that apply to an exported HTML file are configuration properties that can be set in the HTML tab of the Preferences dialog.

An exported HTML file may require one or two auxiliary files: an external stylesheet and, if a crossword has a blocked grid, a block-image file. These auxiliary files are described below. Both kinds of auxiliary file are specific to the size of the grid cell: if the same crossword is exported with different cell sizes, it will need different auxiliary files. Auxiliary files are shared by all the exported HTML files in a directory that have the same cell size, while the size-specific names of auxiliary files allow crosswords with different cell sizes to coexist in the same directory.

Exported HTML files conform to the XHTML 1.1 specification. Because they are XML files, they can be transformed by XSLT processors.

9.1  Stylesheet

Content and presentation are clearly separated in an exported HTML document. Presentation is controlled by a CSS stylesheet, which may be either internal (within a <style> element of the HTML file) or external (in a separate CSS file). An external stylesheet can be shared by a set of similar crosswords, whereas an internal stylesheet reduces the number of auxiliary files, allowing the HTML file of a barred grid to be self-contained. (The HTML file of a blocked grid cannot be self-contained because it requires an auxiliary file for the block image.)

The stylesheet for a blocked grid is different from that for a barred grid. The stylesheets for both kinds of grid have configurable content such as cell size, font and grid colour. If you have some knowledge of CSS, you can customise the appearance of the exported crossword by editing the stylesheet.

If the stylesheet is in a separate CSS file, the HTML file expects to find it in a directory named style. The CSS file may be created along with the HTML file, or the HTML file can use an existing CSS file. The name of the CSS file is size-specific; it has the form crossword‑<separator>‑<size>.png, where <separator> is either block or bar and <size> is the size of a cell in pixels.

9.2  Block image

The exported HTML file for a crossword with a blocked grid requires a separate image file for the block. The block-image file is intended primarily to allow a crossword to be printed economically by reducing the amount of ink or toner that is required to print a block. A block image may be a square of solid colour or it may be composed from diagonal hatching — a set of parallel diagonal lines of the same colour. The block image is always used when printing an exported HTML file, but an HTML file may use either the block image or a solid block of the same colour as the grid when it is displayed on a screen, depending on the value of the html.blockImage.printOnly configuration property.

The HTML file expects to find the block-image file in a directory named images. The block-image file may be created along with the HTML file, or the HTML file can use an existing image file. The name of the image file is size-specific; it has the form block‑<size>.png, where <size> is the size of a cell in pixels.

10  Commands

CrosswordEditor's main commands are accessible from its main menu. Some of the commands are also accessible from context menus that are activated in a system-dependent manner (eg, by pressing or releasing the right mouse button) while the mouse cursor is over the main window.

10.1  File menu

10.1.1  New document

The New document command (Ctrl+N) creates a new crossword document. It brings up a dialog box in which you can select the parameters of the crossword's grid: the separator, size and symmetry. Once they are set, the separator and size of a grid cannot be changed.

The command is disabled if the maximum number of documents are open in the application.

10.1.2  Open document

The Open document command (Ctrl+O) brings up a file-selection dialog in which you can choose the crossword document that you want to open.

If the document has a solution that was encrypted with a passphrase, a dialog will be displayed in which you can enter the passphrase. If you skip the passphrase, or if you continue after entering an incorrect passphrase, the document will be opened without the solution.

The command is disabled if the maximum number of documents are open in the application.

10.1.3  Revert document

The Revert document command reads the current crossword document again from the file system, replacing the modified document in CrosswordEditor. Any changes that you have made to the current document will be lost.

The command is disabled if the current document has not changed from when it was last opened or saved.

10.1.4  Close document

The Close document command (Ctrl+W) closes the current crossword document. If the document has unsaved changes, you will be prompted to save the document before it is closed.

10.1.5  Close all documents

The Close all documents command closes all open crossword documents. You will be prompted to save any documents that have unsaved changes.

10.1.6  Save document

The Save document command (Ctrl+S) writes the current crossword document to the file from which it was last read or to which which it was last written.

The command is disabled if the current document has not changed from when it was last opened or saved.

10.1.7  Save document as

The Save document as command writes the current crossword document to a file. The command brings up a file-selection dialog in which you can select the pathname of the file to which the document will be written. A warning is displayed if the selected file already exists.

10.1.8  Export HTML file

The Export HTML file command exports the current document as an HTML file. There is more information on exporting HTML files elsewhere in the manual.

The appearance of the HTML page is controlled by several configuration properties; most of them are set in the HTML tab of the Preferences dialog, but a couple of them are set from the Export HTML dialog that is displayed when you issue the Export HTML file command. Within the dialog, you can control the following parameters that affect the HTML file and its auxiliary files:

If you have chosen an external stylesheet, the Write stylesheet file check box determines whether a stylesheet file will be written along with the HTML file. If the check box is selected, a CSS file will be written to a directory named style in the same directory as the HTML file.

The HTML file for a blocked grid requires an auxiliary image file for the block. The Write block-image file check box determines whether an image file will be written along with the HTML file. If the check box is selected, an image file will be written to a directory named images in the same directory as the HTML file.

The external stylesheet and, if relevant, the block-image file are specific to the cell size. If you export the same crossword again with a different cell size, you will need a new stylesheet and block-image file to go with it.

Following the Export HTML dialog, a file-selection dialog is displayed in which you can select the pathname of the HTML file that will be written. If you accept the dialog, the selected HTML file will be written, along with any auxiliary files. A warning will be displayed if the selected file already exists, but existing auxiliary files will be overwritten without warning.

After an HTML file has been written, a dialog is displayed in which you are asked whether or not you want to view the file. If you choose to view the file, the operating-system command specified by the html.viewerCommand configuration property will be executed. The command will typically open the HTML file in a web browser. (The location of the HTML file is substituted for a placeholder in the command line.) If you select the Do not show this dialog again check box, your choice of whether or not to view an exported HTML file will be used automatically for the remainder of the current session.

10.1.9  Exit

The Exit command terminates the application. Before the program shuts down, you will be prompted to save any open documents that have unsaved changes.

10.2  Edit menu

10.2.1  Undo/Redo

The edits that you make to a document can be undone and redone with the complementary Undo and Redo commands (Ctrl+Z and Ctrl+Y respectively). The edits to a document are stored in a list whose length is limited by the general.maxEditListLength configuration property.

The Undo command reverses the last change to the current document. If an edit is undone with the Undo command, it can subsequently be restored with the Redo command provided that no other edits have been made since it was undone.

10.2.2  Clear edit history

The Clear edit history command clears the history of edits to the current text document. The command may be used to make more memory available if a "Not enough memory" error occurs.

10.2.3  Edit clue

The Edit clue command (F2) brings up a dialog in which the currently selected clue can be edited. The command can also be issued by double-clicking the left mouse button on a clue in the crossword view.

The command is disabled if no clue is selected.

10.2.3.1  The Clue dialog

At the top of the Clue dialog is a row of one or more boxes containing the IDs and lengths of the fields that are associated with the clue. The first box, which represents the primary field, is always present and cannot be changed. An asterisk (*) in front of a field ID indicates that the field is the primary field of a defined clue (ie, not a clue reference) other than the current clue.

When you add, edit or remove a field, a grid of field IDs is displayed from which you can make a selection. The grid is actually a modal dialog box, which must be closed by selecting one of its cells. You can use the arrow keys to change the selection, and the Esc key closes the dialog without a selection.

The row at the top of the grid contains two cells: "None", which removes the field, and a cell containing an X, which closes the grid without making a selection. The remaining rows are populated with field IDs according to the clue.allowMultipleFieldUse configuration property: if a field may be used by more than one clue, all fields except those of the current clue are available for selection; otherwise, only unused fields are available for selection. If the field ID has a leading asterisk, the field is used by another clue.

Although it is possible to set a reference to a defined clue by setting the text of the referring clue (to, for example, "See 12d"), the recommended method of setting a reference is to add a secondary field to the list of fields of the referent clue.

Below the row of fields in the Clue dialog is a text panel in which the text of the clue can be edited. The text panel supports some styling markup.

10.2.4  Edit grid

The Edit grid command brings up a dialog in which the grid of the current document can be edited. The dialog doesn't allow you to change the dimensions of the grid or the kind of separator; if you want to change either of these parameters, you will have to create a new document.

The Edit grid command is enabled only if the clue lists are empty. If you want to edit the grid of a crossword for which clues have been defined, you could preserve the clues by following these steps:

  1. Copy the clues to the system clipboard with the Edit > Copy clues to clipboard command.
  2. Paste the clues into a text editor.
  3. Delete all the clues from the document with the Edit > Clear all clues command.
  4. Edit the grid.
  5. Edit the clues in the text editor to make them compatible with the changed grid.
  6. Copy the clues from the text editor to the system clipboard.
  7. Import the clues into the document with the Edit > Import clues from clipboard command.
10.2.4.1  The Grid dialog

The Symmetry drop-down list at the top of the Grid dialog allows you to select the symmetry of the grid. Symmetry settings other than None have a notional primary region, which is shown as a shaded area in the images that illustrate the different kinds of symmetry. If you change the symmetry, the separators in the primary region are applied to the remainder of the grid.

When the Highlight fully intersecting fields check box is selected, fields are highlighted if all their cells are also cells of intersecting fields. (Such fields may be undesirable because they can be filled without solving their clues.) A fully intersecting field is highlighted by drawing the background of its cells in a configurable colour (Background, fully intersecting field).

A grid may contain isolated cells: single cells that are surrounded by the sides of the grid or separators. Such cells do not belong to any field and are highlighted by drawing their background in a configurable colour (Background, isolated cell).

The grid in the Grid dialog is drawn without field numbers. One cell — the active cell — has an internal border called the editing box. The editing box is drawn in a configurable colour: Editing box, focused if the grid has focus, Editing box otherwise.

When the grid has keyboard focus, the position of the active cell may be moved with the arrow keys:

Left Move left by one column
Right Move right by one column
Up Move up by one row
Down Move down by one row
Home Move to the first column
End Move to the last column
PageUp Move to the first row
PageDown Move to the last row

The separator(s) of a cell can be toggled on and off by left-clicking on the cell (blocked grid) or the borders of the cell (barred grid). When the grid has keyboard focus, the separators of the active cell can be toggled with the following keys:

Blocked grid
Space Toggle the block
Barred grid
Alt+Left Toggle the left bar
Alt+Right Toggle the right bar
Alt+Up Toggle the top bar
Alt+Down Toggle the bottom bar

Changes that you make to the grid's symmetry and separators can be undone and redone with commands that can be issued from a context menu or with the following keys:

Ctrl+Z Undo
Ctrl+Y Redo

The maximum length of the list of edits is controlled by the general.maxEditListLength configuration property, which also controls the length of a document's list of edits.

The two boxes below the grid show the number of across and down fields in the grid.

10.2.5  Edit text sections

The Edit text sections command (Ctrl+T) brings up a dialog in which you can edit the three text sections of the current document: title, prologue and epilogue. The command can also be issued by double-clicking the left mouse button on a text section in the crossword view.

In the Text sections dialog, the Title field is a simple text field and the Prologue and Epilogue text areas are text panels.

In a prologue or epilogue, paragraphs must be separated by one or more empty lines. You can start a new line without starting a new paragraph by ending a line with a line-break sequence, which defaults to $$.

10.2.6  Edit indications

The Edit indications command brings up a dialog in which you can edit the clue-reference keyword, the answer-length pattern and substitutions and the line-break sequence of the current document.

At the top of the Indications dialog are fields for the clue-reference keyword and the line-break sequence. Below them are a field for the pattern of the answer-length expression and a list box of substitutions that will be applied to an answer-length expression.

The Default button adjacent to the Pattern field sets the answer-length pattern to a default value that should be suitable for UK crosswords.

If you are importing clues that do not have an answer-length expression, or if you cannot specify a suitable answer-length pattern, you should leave the Pattern field empty. In this case, each clue must be on a separate line of text.

The answer-length substitution list can be edited with commands issued from the three buttons to the right of the list. In the dialog that is displayed in response to the Add and Edit commands, the target is the text that is searched for in the answer-length expression and the replacement is the text that will replace all occurrences of the target. You should select the Regular expression check box if the target is a regular expression rather than literal text. In the list box, regular-expression substitutions are indicated by RE in the first column.

10.2.7  Copy clues to clipboard

The Copy clues to clipboard command copies all the clues of the current document to the system clipboard. The clues are exported as plain text, in conventional clue order (ie, ordered by direction (across before down) and field number), with one clue per line and an empty line between the lists of across clues and down clues. Clues copied to the clipboard can be imported as separate lists of across clues and down clues with the Edit > Import clues from clipboard command.

The command is disabled if the current document has no defined clues.

10.2.8  Import clues from clipboard

The Import clues from clipboard command imports lists of clues into the current document from the system clipboard. The command brings up a dialog in which you can import clues for one or both clue lists, across and down.

The clues will be imported using the clue-reference keyword and the answer-length pattern and substitutions of the document, which can be edited with the Edit > Edit indications command. If the clues do not have an answer-length expression, the answer-length pattern should be empty. In this case, each clue on the clipboard must be on a separate line of text because the clue processor cannot otherwise determine the end of a clue that has no answer-length expression.

At the top of the Import clues dialog is a list of substitutions that will be applied to the text of imported clues. (You can define a substitution, for example, to replace three dots with an ellipsis character, U+2026.) Substitutions are applied only to defined clues, not to clue references, and they are applied as the penultimate stage of processing a clue, after an answer-length expression is processed and any line breaks are removed but before style markup is parsed. The list box and its associated commands are similar to those of the answer-length substitution list described in the preceding paragraph.

The substitution list can be edited with commands issued from the three buttons to the right of the list. In the dialog that is displayed in response to the Add and Edit commands, the target is the text that is searched for in the text of the clue and the replacement is the text that will replace all occurrences of the target. You should select the Regular expression check box if the target is a regular expression rather than literal text. In the list box, regular-expression substitutions are indicated by RE in the first column.

The Get clues button in the Import clues dialog has a menu from which you can select a subcommand corresponding to the direction of the clues that you want to import. Selecting the Across or Down subcommand will read the clues for the selected direction from the clipboard. The expected format of the clues on the clipboard is described elsewhere in the manual.

When you select OK, the clues are validated, and an error-list dialog is displayed if there are any errors in the clues.

10.2.9  Clear all clues

The Clear all clues command deletes all the clues from the current document.

10.2.10  Copy grid entries to clipboard

The Copy grid entries to clipboard command copies all the grid entries of the current document to the system clipboard. The entries are exported as plain text, in conventional clue order (ie, ordered by direction (across before down) and field number), with one field per line. Cells without an entry are indicated by a ? character (U+003F). Entries copied to the clipboard can be imported with the Edit > Import grid entries from clipboard command.

The command is disabled the current document has no grid entries.

10.2.11  Import grid entries from clipboard

The Import grid entries from clipboard command imports grid entries into the current document from the system clipboard. The command is enabled only if there is text on the clipboard.

The command expects the entries on the clipboard to be in conventional clue order (ie, ordered by direction (across before down) and field number), with whitespace (spaces, tabs or newlines) between fields and a ? character in the place of a cell with no entry. Entries that were exported by the Edit > Copy grid entries to clipboard command may be imported with the Import grid entries from clipboard command.

The command is disabled if there is no text on the system clipboard.

10.2.12  Clear all grid entries

The Clear all grid entries command removes all the entries from the grid of the current document.

10.2.13  Copy field numbers to clipboard

The Copy field numbers to clipboard command copies the numbers of all the fields of the current document to the system clipboard. The lists of field numbers could be used as a starting point when composing clues in a text editor for subsequent import into CrosswordEditor.

The field numbers are exported as plain text, in conventional clue order (ie, ordered by direction (across before down) and field number), with one field per line and an empty line between the lists of across fields and down fields.

10.2.14  Copy field IDs to clipboard

The Copy field IDs to clipboard command copies the IDs of all the fields of the current document to the system clipboard. The exported text is identical to that exported by the Edit > Copy field numbers to clipboard command except that each field number has a direction suffix, a or d.

10.3  Crossword menu

10.3.1  Capture crossword

The Capture crossword command (F9) allows you to import an external crossword into CrosswordEditor in a procedure that consists of a few steps. The procedure is controlled from a dialog box that is displayed in response to the command. If it is successful, a new crossword document will be created.

The command is disabled if the maximum number of documents are open in the application.

10.4  Solution menu

10.4.1  Highlight incorrect grid entries

The Highlight incorrect grid entries command (F5) highlights all open cells of the grid of the current document whose entry differs from the solution to the crossword, including cells for which there is no entry. The highlighting is temporary; it is removed when a grid entry is edited. A cell is highlighted by drawing its background with the same configurable colour (Background, isolated cell) as that of isolated cells in the Grid dialog.

The command is enabled only if the current document contains a solution and there is at least one grid entry.

10.4.2  Show solution

The Show solution command replaces the grid entries of the current document with the crossword's solution.

The command is disabled if the current document does not contain a solution.

10.4.3  Set solution to current entries

The Set solution to current entries command sets the solution of the current document to the current grid entries.

The command is enabled only if the grid entries of the current document are complete.

10.4.4  Import solution from clipboard

The Import solution from clipboard command imports a solution into the current document from the system clipboard. The command expects the answers that constitute the solution to be in conventional clue order (ie, ordered by direction (across before down) and field number), with whitespace (spaces, tabs or newlines) between fields. A solution that was exported by the Edit > Copy solution to clipboard command may be imported with the Import solution from clipboard command.

The command is disabled if there is no text on the system clipboard.

10.4.5  Load solution

The Load solution command sets the solution of the current document to the solution in another document — the solution document — whose location is specified in the current document's solution properties. The solution document, which may be on a remote server, is read over a network connection.

If the solution of the solution document was encrypted with a passphrase, a dialog will be displayed in which you can enter the passphrase.

The command is disabled if the current document's solution properties do not specify the location of a solution.

10.4.6  Clear solution

The Clear solution command removes the solution from the current document.

The command is disabled if the current document does not contain a solution.

10.4.7  Copy solution to clipboard

The Copy solution to clipboard command copies the solution of the current document to the system clipboard. The answers that constitute the solution are exported as plain text, in conventional clue order (ie, ordered by direction (across before down) and field number), with one field per line. Answers copied to the clipboard can be imported with the Edit > Import solution from clipboard command.

The command is disabled if the current document does not contain a solution.

10.4.8  Create document containing solution

The Create document containing solution command creates a new document from the current document; the new document — called a solution document — contains only a grid (required of all crossword documents) and a solution, both of which are copied from the current document. If a passphrase has been set in the solution properties of the current document, the solution document will have the same passphrase.

The solution from a solution document may be loaded into a public document (a document containing a link to its solution) with the Edit > Load solution command if the correct passphrase is supplied and the hash values of the two documents are identical. To ensure that a public document and its corresponding solution document have the same hash value, it is recommended that the two documents be created from the same master document.

The command is disabled if the current document does not contain a solution or the maximum number of documents are open in the application.

10.4.9  Edit solution properties

The Edit solution properties command brings up a dialog box in which you can edit two properties of the solution of the current document: the location of an external solution and the passphrase through which a solution may be accessed.

10.4.9.1  The Solution properties dialog

If the current document has a solution (indicated by the presence of "Solution" in the status panel at the bottom of the main window), the Save solution with document check box at the top of the Solution properties dialog controls whether the solution will be saved with the document when the document is written with the File > Save document command or File > Save document as command.

If the Save solution with document check box is not selected, the Location field is enabled, allowing you to specify the location of an external solution document. The location must be a valid URL, which will typically start with http: if the solution document is on a remote server, but it could start with file: if the solution document can be found on the local file system.

If you want to protect the solution with a passphrase, you should enter it in the Passphrase field; otherwise, leave the field empty. (A non-empty field has a different background colour from that of an empty field to indicate the presence of a passphrase.) When the dialog is displayed, the characters that you enter in the field are hidden; you can make them visible by issuing the Show command from the button adjacent to the field or from the dialog's context menu. The text of the button changes to Hide when the contents of the passphrase field are visible. The Show and Hide commands are also available through the Passphrase field's context menu, along with a Paste command, which can also be issued by pressing Ctrl+V when the field has keyboard focus. The command pastes text from the system clipboard into the passphrase field, then clears the clipboard.

10.5  View menu

10.5.1  Show field numbers

The Show field numbers command toggles the visibility of field numbers in the crossword grid. Field numbers are displayed in the grid by default when a document is created or opened; this command allows the field numbers to be hidden. The command also controls the visibility of the field numbers in an HTML document that is exported with the File > Export HTML file command.

This command can be used in conjunction with the View > Show clues command to hide the field numbers of a crossword that doesn't have numbered clues.

10.5.2  Show clues

The Show clues command toggles the visibility of the clue lists. Lists of clues are displayed below the grid by default when a document is created or opened; this command allows the clues to be hidden. The command also controls the visibility of clues in an HTML document that is exported with the File > Export HTML file command.

In some kinds of crossword, clues are not numbered; in addition to solving the clues, the solver must work out the correspondence between clues and fields in the grid. (One such kind of crossword is the alphabetical jigsaw, in which each answer starts with a different letter of the alphabet, and the clues are listed by this initial letter.) Unnumbered clues may be listed — with some effort, and extensive use of the line-break sequence — in the epilogue that is displayed below the clues. Clues entered in this way will be displayed as a single-column list both on the screen and in any exported HTML document. If you wanted to split the list into two columns in an HTML document, you would have to edit the HTML <table> element manually.

This command can be used in conjunction with the View > Show field numbers command to hide the clues of a crossword that doesn't have numbered clues.

10.5.3  Resize window to view

The Resize window to view command (F12) sets the size of the main window so that its viewport is the same size of the current view.

10.6  Options menu

10.6.1  Show full pathnames

The Show full pathnames option controls whether the full pathname of the current document or only its filename is displayed in the title bar of the main window.

10.6.2  Manage file associations

The Manage file associations command provides a means of adding or removing an association, on Windows, between the CrosswordEditor application and files with the filename suffix of crossword documents. A file association will allow you, for example, to open a crossword document in CrosswordEditor by double-clicking on its filename in Windows Explorer. However, when CrosswordEditor starts up, it doesn't check whether another instance of the program is running, so double-clicking on multiple documents will cause each one to be opened in a separate instance of CrosswordEditor.

The command creates a file association by modifying entries in the Windows Registry, which it achieves by generating and executing a Windows PowerShell script. You may execute the script automatically after it is generated, or just write a script file that you can use outside CrosswordEditor. You must have PowerShell 2.0 or later installed on your system to run the script. (A suitable version is included in Windows XP Service Pack 3, Windows 7 and Windows 8.x.)

The command is enabled only if the application is run on Windows.

10.6.2.1  The Windows file associations dialog

The command brings up a dialog box that controls the content of the PowerShell script and the way in which it is used. At the top of the dialog is a drop-down list from which you can select the action that you want to perform: Add creates a new file association or modifies an existing one; Remove removes a file association that was created with the Add option. (If you add a file association, you will probably want to remove it before you change the filename suffix or uninstall CrosswordEditor.) The same script is used for both adding and removing a file association; the difference in behaviour is achieved by adding a switch (the argument -remove) to the command line when the script is used to remove a file association.

Below the Action drop-down list are fields in which you specify the locations of three files that are required to create the file association. The fields are disabled if the selected action is Remove because the locations of the files aren't required when removing a file association, but the content of the fields is always included in the script in case you want to retain a single script for dual purposes.

The pathnames of the three files may contain special constructions for system properties and environment variables. If a specified system property exists, the construction that denotes the property key (eg, ${java.home}) will be replaced by the property value. Environment variables, however, will not be expanded but will be converted to their Windows form (eg, ${JAVA_HOME} will be converted to %JAVA_HOME%) before they are included in the script. The environment variables will be set in Registry values and expanded by the operating system.

Environment variables of the form %name% may appear in a pathname, but they don't have a special significance in CrosswordEditor and are treated as literal text. If a pathname contains environment variables of this form, you should ensure that the Files must exist check box is not selected to avoid an error when the pathnames are resolved.

To add a file association, the files whose locations you must specify are:

Java launcher
This is the Windows executable that launches a Java program; with Oracle's JRE, you have a choice of javaw.exe (no console) or java.exe (console). The corresponding Default command sets the pathname to that of the file bin\javaw.exe in the directory specified by the java.home system property, which is the Java installation directory that is associated with the current CrosswordEditor application. If you install another version of Java, the Java launcher might be at a different location; if so, you will need to update the file association accordingly.
JAR
This is the JAR (Java archive) file of the CrosswordEditor application. The corresponding Default command sets the pathname to that of the JAR file of the current CrosswordEditor application. (The command is disabled if the application was not run from a JAR file.)
Icon
This is a Windows icon file for CrosswordEditor. The file crosswordEditor.ico is included in the CrosswordEditor distribution for this purpose, and it is also in the Image files group of optional components that can be installed with the CrosswordEditor installer. However, you may choose to associate any suitable icon file with CrosswordEditor documents.

The Files must exist check box below the pathname fields should be selected if you want CrosswordEditor to check that the three files exist before it generates a script. You should not select the check box if any of the pathnames contain Windows-form environment variables, but environment variables in the form of special constructions will be expanded when a pathname is resolved.

The Script life cycle drop-down list controls what happens to the PowerShell script after it is generated. For all options, a script file named crosswordEditorAssociations.ps1 is written to a subdirectory of the system's temporary directory, which is typically AppData\Local\Temp within the user's home directory. The subdirectory has the prefix crosswordEditor_ , and the full pathname is displayed when the script file is written. After the file has been written, it may be executed and optionally deleted after execution, according to selection from the Script life cycle drop-down list. If you don't want to preserve the script, the default option of Write, execute and delete will add or remove a file association without leaving a residue on the file system.

When you select OK, the pathnames are validated if the action is Add and the Files must exist check box is selected. If there is no error, a further dialog box is displayed in which the progress of script operations is reported, along with any error messages from CrosswordEditor or the operating system. The pathname of the script file appears in the first message. When the script operations have finished, you can copy the contents of the text area to the system clipboard with the dialog's Copy command.

10.6.3  Preferences

The Preferences command brings up a tabbed dialog box in which the configuration properties of CrosswordEditor can be edited. The properties on the various tabbed pages are described below.

General
Display UNIX-style pathnames
If you select Yes, pathnames are displayed in a reduced "UNIX style" in some parts of the GUI. A pathname is converted from its platform-specific form in two steps:
  1. If the pathname starts with the user's home directory, the latter is replaced by '~'.
  2. The file-separator character ('\' on Windows systems) is replaced by '/'.
The default value is No.
Select text when focus is gained
If you select Yes, all the text in a text field will be automatically selected when the field gains keyboard focus, regardless of how the focus is transferred.
The default value is Yes.
Save location of main window
If you select Yes, the location of the main window on the screen will be saved to the configuration file when you exit the application. The next time that CrosswordEditor is run, its main window will be positioned at the previously saved location.
The default value is Yes.
Maximum size of edit history
This is the maximum number of edits that can be stored in a document's history for use by the Edit > Undo and Edit > Redo commands. The history of edits can be explicitly cleared with the Edit > Clear edit history command.
This property also controls the length of the list of undoable edits in text panels and in the Grid dialog.
The default value is 200.
Clear edit history on save
If you select Yes, a document's history of edits (see Edit > Undo/Redo) is cleared when the document is saved.
The default value is No.
Appearance
Look-and-feel
The look-and-feel (LAF) can be selected from a list of the LAFs that are available on the current system.
The default value is the cross-platform LAF, currently called Metal.
Text antialiasing
This determines the kind of antialiasing that is performed when text is drawn in custom or partially customised user-interface components (eg, in drop-down lists). Note that antialiasing is only a hint in Java; the implementation is not required to perform the chosen antialiasing.
This property has no effect on the antialiasing of text in standard UI components, such as labels and menus, which is determined by the Java implementation and the desktop setting for antialiasing text (often referred to as "font smoothing"). You can override the desktop setting with the unsupported system property awt.useSystemAAFontSettings.
The text antialiasing property can have the following values:
Default
The desktop setting for text antialiasing (font smoothing) is used, if the Java implementation recognises one; otherwise, no antialiasing is performed.
None
No antialiasing is performed.
Standard
This selects pixel-oriented antialiasing rather than subpixel antialiasing. It is suitable for non-LCD displays.
Subpixel, horizontal RGB
Subpixel, horizontal BGR
Subpixel, vertical RGB
Subpixel, vertical BGR
These four options are intended to optimise the rendering of text for LCD displays using subpixel antialiasing with subpixels in the chosen arrangement. Selecting an option that does not correspond to the actual arrangement of subpixels in your LCD display may result in blurred text. The most common arrangement of subpixels is horizontal RGB.
The default value is Default.
Status text colour
This is the colour of text in the status panel of the main window and the Capture crossword dialog.
The default value is RGB( 160, 64, 0 ).
View
Width of selected clue
This is the width (in columns) of the area of a crossword view to the right of the grid in which the selected clue is displayed. The width of a column is the width of a '0' (zero, U+0030) character.
The default value is 50.
Colours
These are the colours of the various parts of a crossword view and the grid in the Grid dialog.
Grid
Grid-entry characters
This is the set of characters that you are allowed to enter in the grid. Characters that you enter in this field are converted to upper case according to your locale, and you are prevented from entering duplicate characters in the field.
The default value is the set of 26 upper-case characters, 'A' to 'Z', of the ISO basic Latin alphabet.
Navigate over separators
If you select Yes, the caret is allowed to move over separators when you are navigating a grid in a crossword view with the arrow keys. If you select No, the caret stops at a separator, and moving between fields with the arrow keys is allowed only at the points at which fields intersect.
The default value is No.
Capture-image viewport size
These are the dimensions (width × height, in pixels) of the viewable region of an image in the grid-selection dialog that is displayed in response to a Get grid image command in the Capture crossword dialog.
The default size is 800 × 600.
Block | Cell size
This is the size (width and height, in pixels) of a cell of a blocked grid in a crossword view. A separate property, html.cellSize.block, controls the size of a cell in an exported HTML file.
The default value is 24.
Bar | Cell size
This is the size (width and height, in pixels) of a cell of a barred grid in a crossword view. A separate property, html.cellSize.bar, controls the size of a cell in an exported HTML file.
The default value is 24.
Bar | Bar width
This is the width (in pixels) of a bar of a barred grid in a crossword view. A separate property, html.barGrid.barWidth, controls the width of a bar in an exported HTML file.
The default value is 4.
Clues
Direction keywords
When importing clues with either the Edit > Import clues from clipboard command or the Crossword > Capture crossword command, the words in these two lists will be interpreted as denoting the direction in a field ID, either
  • in the secondary field of a clue, or
  • in a clue reference.
The keywords are used only when importing clues; they do not apply to the clues of a crossword document, in which the direction of a field is denoted by the suffix "a" or "d".
A field ID consists of a field number followed by an optional keyword to denote the direction of the field (across or down). The direction may follow immediately after the number, or the two components may be separated by one or more spaces. To allow a field number and direction to be separated by optional spaces, prefix a space to the direction keyword; eg, " across". Note, however, that the start of a clue may be mistaken for a keyword with a leading space. For example, if you specify the keyword " A" to denote an across field, the clue
5, 23  A Chinese city (4,4)
will be imported by CrosswordEditor as
5, 23a  Chinese city (4,4) .
A list of keywords can be edited in the dialog box that is displayed when you issue an Edit command with the button adjacent to the field.
Clue-reference keyword
This is the string that is used in a clue to indicate a reference to another clue; for example, "17 See 6". This property is used as the default clue-reference keyword for a crossword document that is created with the File > New document command.
The default value is "See".
Implicit direction of secondary fields
The field IDs of the secondary fields of a clue or a clue reference will have the suffix a or d to indicate the direction (across or down) if the field number is ambiguous. If you select Yes, the direction will be omitted from the ID of a secondary field or referent if the direction is the same as that of the primary field. If you select No, the field ID will have a direction suffix if the field number does not uniquely identify the field.
The default value is No.
Allow multiple clues for a field
If you select Yes, a single field may be used by more than one clue. This property is used only to control the available fields when editing a clue in the Clue dialog.
The default value is No.
Text sections
Line break
This is the sequence of characters that will be converted to a line break whenever it is encountered at the end of a line of text in a prologue or epilogue. A line break has the effect of starting a new line without starting a new paragraph, like the <br> element in HTML. The sequence is interpreted as a line break only if it is at the very end of a line (ie, with no trailing spaces).
The default value is "$$".
HTML
Viewer command
This is the operating-system command that will be used to launch a web browser or some other program for viewing an HTML document that is generated by the File > Export HTML file command. The pathname of the HTML file can be included in the command line so that it is opened by the viewer.
Within the command line, arguments must be separated with one or more spaces, and "%" (U+0025) acts as an escape character. "%f" is a placeholder for the pathname of the HTML file that is to be opened. All other characters that follow "%" are treated as themselves; thus, a literal space is represented by "" (ie, U+0025, U+0020), and a literal "%" is represented by "%%".
Pathnames in the command line may contain special constructions for system properties, environment variables and the user's home directory.
A typical command to open an exported HTML file in the Mozilla Firefox browser under Windows might be:
${ProgramFiles(x86)}/Mozilla% Firefox/firefox.exe -new-tab %f
Note the use of the special construction for the environment variable ProgramFiles(x86), the escaping of the space character and the presence of the placeholder, %f.
A typical command to open an exported HTML file in the Mozilla Firefox browser under Linux might be:
/usr/bin/firefox -new-tab %f
Font names
These are the font names that will be used in the stylesheet of an HTML document that is generated by the File > Export HTML file command.
A list of font names can be edited in the dialog box that is displayed when you issue an Edit command with the button adjacent to the field. In the dialog, the Font name drop-down list contains the names of fonts that are available on the current system, but you are not confined to those fonts. The three fonts at the top of the list — serif, sans-serif and monospace — are generic CSS fonts; it is recommended that you include at least one of them at the end of the list of font names as a fallback.
The default font names are Arial, Helvetica and sans-serif.
Font size
This is the size (in points) of the font that will be used in an HTML document that is generated by the File > Export HTML file command. The size applies to all the text in the document except for the clue numbers in the grid, whose size is controlled by a combination of this property and the html.fieldNumberFontSizeFactor property.
The default value is 8.
Field number font-size factor
This property, along with the html.fontSize property, controls the size of the font that will be used for the field numbers in the grid of an HTML document that is generated by the File > Export HTML file command. The values of the two properties are multiplied to give the font size of the field numbers.
The default value is 0.667 (ie, 2/3 of the normal font size).
Grid colour
This is the colour of the grid in an HTML document that is generated by the File > Export HTML file command. It is also used as the colour of the bars in a barred grid and, if the html.blockImage.printOnly property is true, as the colour of blocks in a blocked grid when the HTML document is displayed on a screen.
The default value is RGB( 160, 160, 160 ).
Block | Cell size
This is the size (width and height, in pixels) of a cell of a blocked grid in an HTML document that is generated by the File > Export HTML file command. A separate property, grid.cellSize.block, controls the size of a cell in a crossword view.
The default value is 20.
Block | Number of lines
(This property relates to the image of a block that is created for a blocked grid. The image consists of diagonal hatching: a set of lines parallel to the diagonal of the block from bottom-left to top-right. A block-image file is written if the Write block-image file check box is selected in the Export HTML dialog that is displayed in response to a File > Export HTML file command.)
This is the number of diagonal lines that intersect one side of the block image (ie, half the number of lines in the image). If you set the number of lines to zero, the image will be a solid square.
The default value is 4.
Block | Line width
(This property relates to the image of a block that is created for a blocked grid. The image consists of diagonal hatching: a set of lines parallel to the diagonal of the block from bottom-left to top-right. A block-image file is written if the Write block-image file check box is selected in the Export HTML dialog that is displayed in response to a File > Export HTML file command.)
This is the width (in pixels) of a diagonal line of the block image.
The default value is 1.0.
Block | Colour
(This property relates to the image of a block that is created for a blocked grid. The image consists of diagonal hatching: a set of lines parallel to the diagonal of the block from bottom-left to top-right. A block-image file is written if the Write block-image file check box is selected in the Export HTML dialog that is displayed in response to a File > Export HTML file command.)
This is the colour of the diagonal lines of the block image, or, if html.blockImage.numLines is zero, the colour of the solid block.
The default value is RGB( 96, 96, 96 ).
Block | Print only
(This property relates to the image of a block that is created for a blocked grid. The image consists of diagonal hatching: a set of lines parallel to the diagonal of the block from bottom-left to top-right. A block-image file is written if the Write block-image file check box is selected in the Export HTML dialog that is displayed in response to a File > Export HTML file command.)
If you select Yes, the block image is used only when the HTML document is printed; blocks are drawn as solid squares when the document is displayed on a screen. If you select No, the block image is used both on the screen and when the HTML document is printed.
The default value is No.
Bar | Cell size
This is the size (width and height, in pixels) of a cell of a barred grid in an HTML document that is generated by the File > Export HTML file command. A separate property, grid.cellSize.bar, controls the size of a cell in a crossword view.
The default value is 20.
Bar | Bar width
This is the width (in pixels) of a bar of a barred grid in an HTML document that is generated by the File > Export HTML file command. A separate property, grid.bar.barWidth, controls the width of a bar in a crossword view.
The default value is 4.
Bar | Excess bar width
In a barred grid of an HTML document that is generated by the File > Export HTML file command, a bar is formed by increasing the width of the appropriate border of a cell and reducing the internal padding of the cell to compensate for the wider border. If the bar width is odd, the extra width of the border is distributed evenly on both sides of the 1-pixel-wide grid line. If the bar width is even, the distribution of the extra width depends on the browser; in order to preserve the squareness of cells by correctly adjusting their padding, this property should be set according to the way in which your browser renders the bars.
The images below illustrate the two ways of distributing even-width top and left bars. For clarity, the bars are shown in a different colour from the grid lines. The red dot indicates the cell to which the notions of top, left, inside and outside relate.
T and L inside
T and L outside
T and L inside
T and L outside
HTML documents exported by CrosswordEditor have been tested on two browsers: Mozilla Firefox and Microsoft Internet Explorer (IE). If the bar width is even, both browsers distribute the width of a bar at the top of a cell in the same way as a bar on the left of a cell, but the distribution is different for the two browsers: Firefox draws the excess width on the inside of the cell whereas IE draws it on the outside. Thus, you should set this property to T and L inside for Firefox and T and L outside for IE.
For other browsers, you should inspect the rendering of an appropriate HTML document at a high zoom and set this property accordingly. (It is assumed that all browsers treat the top and left borders of a cell similarly when distributing an even-width border.)
The default value is T and L inside.
Files
Filename suffix
This is the suffix that is given to the filenames of crossword documents.
The default value is ".xword".
Parameter-set file
This is the location of the file that is associated with the Manage parameter set command in the Capture crossword dialog. The file is read when the command is issued and updated when the resulting parameter-set dialog is closed with OK. If the file specified by this property does not exist when the Manage parameter set command is issued, an empty parameter-set file is created.
Fonts
These are the fonts that are used in CrosswordEditor's display. Remember that font names may be platform-dependent, so that a configuration that specifies font names may not work across platforms.
The main font is used for various components including labels (static text), menus, buttons and list boxes.
The text field font is used for text fields, spinners and some other text components.
The combo box font is used for drop-down lists and related components.
The clue font is used for clues in a crossword view.
The field number font is used for the numbers of fields in the grid of a crossword view.
The grid entry font is used for grid entries in a crossword view.
The default values of all the font properties are those of the default fonts for the platform and look-and-feel. A default font size is specified by leaving the Size field empty (the minimum position on the spinner). A default font is used if no font name is specified in CrosswordEditor's configuration or if the named font is not available.

Some of the configuration properties will take effect when the Preferences dialog is accepted (by closing it with OK); other properties (eg, the look-and-feel and fonts) will not take effect until the next time that CrosswordEditor is run.

The configuration file is normally saved automatically when CrosswordEditor exits, if the configuration has changed. The Save configuration command in the Preferences dialog can be used to save a configuration file explicitly.

Appendix A:  Glossary of terms

Crosswords have their own jargon. Most of the terms that are defined in the following list are conventional ones, though some are used in a particular way in the CrosswordEditor program and in this manual. The terms marked with an asterisk, '*', are unlikely to be found outside of CrosswordEditor, and they have been employed to give a precise meaning to elements of a crossword.

answer
An answer is the correct entry for a clue or, depending on the context, for a field.
answer-length expression *
An answer-length expression is an optional component of a clue that indicates the length of its answer. If it is present, it must come at the end of the clue. It usually consists of one or more numbers enclosed in parentheses, "(" (U+0028) and ")" (U+0029). By convention, the length of a compound answer may be indicated either by a single number to denote the total length or by multiple numbers separated by characters that indicate the structure of the answer (for example, a comma to indicate separate words or a hyphen to indicate a hyphenated compound word).
bar
A bar is a separator that lies on the vertical or horizontal edge between two adjacent grid cells. It is shown as a thicker line than the grid lines.
barred grid
A barred grid is a grid whose separators are bars.
block
A block is a separator that occupies a grid cell. It is customarily shown as a dark square.
blocked grid
A blocked grid is a grid whose separators are blocks.
cell
A cell is one of the squares into which a grid is divided. A cell may be open or blocked.
clue
Informally, a clue is some text from which the solver is expected to deduce an answer that is to be entered into the grid in the field(s) specified by the clue. There is usually a one-to-one correspondence between clues and fields, though CrosswordEditor allows a single clue to be associated with more than one field; such a clue is called a multiple-field clue. CrosswordEditor also allows multiple clues to be associated with a single field, but this is rare in published crosswords.
Formally, a clue consists of
  1. one or more field IDs, separated by commas and followed by
  2. either a definition or a clue reference, and
  3. an optional answer-length expression.
clue definition *
In CrosswordEditor, the definition of a clue is the text of a self-contained clue (ie, a clue that is not a reference) from which the solver is expected to deduce an answer. It does not include the clue's field IDs or any answer-length expression. This differs from the customary meaning of definition in British cryptic crosswords, in which it refers to the defining part of a clue as opposed to the clue's wordplay or subsidiary indication.
clue ID *
A clue ID (identifier) is usually the same as a field ID. If multiple clues are associated with a single field, the clues are disambiguated by appending an index to the field ID. For example, if there are two clues for 14 down, their IDs are 14d#1 and 14d#2.
clue list
A clue list is the list of clues for one of the directions, across or down.
clue number
A clue number is a loose term for the number of the field with which the clue is associated (the first field, if a clue is associated with more than one field). A clue number is a field ID from which the direction has been omitted because it is implied by the direction of the clue list to which the clue belongs.
clue reference *
If a clue has a reference to another clue instead of a definition, the reference is called a clue reference. (A clue may refer to another clue in its definition, but this is not what is meant by a clue reference.) Clue references are usually found in the clues for the secondary fields of multiple-field clues. A clue reference consists of a clue-reference keyword followed by a clue ID. No answer-length expression is expected in a clue reference. For example, the multiple-field clue
5, 23  A Chinese city (4,4)
may be accompanied by the clue
23  See 5a ,
which is a reference to the first clue.
clue-reference keyword *
In a multiple-field clue, it is customary for the clues for secondary fields to contain only a reference to the clue for the primary field. The word, phrase or symbol that denotes the reference is called a clue-reference keyword; for example, the word "See" is the clue-reference keyword in the second clue of this pair:
6, 17  A British warmonger (4,5) and 17  See 6d .
direction
CrosswordEditor supports only orthogonal grids; that is, grids with horizontal and vertical fields. The two directions of fields and their associated clues are called across (horizontal) and down (vertical), which are abbreviated to a and d respectively in a field ID.
field *
A field is a horizontal or vertical group of two or more contiguous open cells, bounded by a side of the grid or a separator. A horizontal field — called an across field — starts at its leftmost cell; a vertical field — called a down field — starts at its topmost cell. Fields are numbered sequentially according to the position of their first cell, starting at the top left corner of the grid and going from left to right and top to bottom. If an across field and a down field have a cell in common, they are said to intersect.
field ID *
A field ID (identifier) is the number of a field followed by its direction. CrosswordEditor abbreviates the two directions, across and down, to their initial letters; for example, 5 across is 5a and 23 down is 23d. In a clue, the direction is omitted from the field ID of a secondary field or a clue reference when it can be inferred unambiguously by applying the following rules, in order:
  1. there is only one field with the given number, or
  2. the clue.implicitFieldDirection configuration property is true and the secondary field or reference has the same direction as the primary field.
grid
A grid is a rectangular area, divided into squares by sets of vertical and horizontal grid lines. The vertical divisions of the grid are called columns; the horizontal divisions are called rows. The square subdivisions of a grid are called cells.
grid entry
A grid entry — sometimes abbreviated to entry — denotes, according to the context, either the characters that are entered by the solver into the cells of a field or the character that is entered into an individual cell. A cell of a field that has no entry is said to be empty; if all the cells of a field have entries, the entry for the field is said to be full. A crossword is complete if all the fields of the grid have full entries.
multiple-field clue *
A multiple-field clue is a clue that is associated with more than one field, and the IDs of all the fields are listed, separated by commas, at the start of the clue for the first field, which is called the primary field. The remaining fields are called secondary fields. The clue for each secondary field may consist only of a reference to the clue for the primary field.
open cell *
An open cell is a cell that is not occupied by a block. All cells of a barred grid are open. Open cells usually belong to fields, although CrosswordEditor allows a grid to contain isolated cells (single cells surrounded by sides of the grid or separators), which don't belong to any field.
primary field *
In a clue that is associated with more than one field, the first field is called the primary field and the remaining fields are called secondary fields.
secondary field *
In a clue that is associated with more than one field, the first field is called the primary field and the remaining fields are called secondary fields. The clue for a secondary field is a reference to the clue for the primary field.
separator
If a row or column of a grid contains more than one field, the fields in the row or column are separated from one another by separators. CrosswordEditor supports two kinds of separator: blocks and bars. The corresponding grids are called a blocked grid and a barred grid. A single grid may have only one kind of separator.
solution
A solution is the set of answers for all the fields of a grid. A crossword is solved if it is complete (ie, all its fields have full entries) and the entries match the solution.

Appendix B:  Special constructions in pathnames

Where indicated elsewhere in this document, pathname parameters and properties in CrosswordEditor can contain special constructions for system properties, environment variables and the user's home directory. The special constructions are expanded when the pathname is used.

System properties and environment variables
Java system properties (eg, the user's home directory, user.home) and environment variables (eg, PATH) are referenced by enclosing them between '${' and '}'; that is, they must have the form ${<name>}. A Java system property takes precedence over an environment variable with the same name.
• Example: ${user.home}/projects
• Example: ${HOME}/projects
A Java system property can be specified by prefixing sys. to it.
• Example: ${sys.user.home}/projects
An environment variable can be specified by prefixing env. to it.
• Example: ${env.HOME}/projects
User's home directory
A leading '~' in a pathname is expanded into the user's home directory using the user.home system property, which is usually equivalent to the environment variable $HOME on Linux/UNIX systems or %USERPROFILE% on Windows systems.
• Example: ~/projects

Appendix C:  Configuration properties

The table below lists the configuration properties of CrosswordEditor. Apart from the app.configDir property, which, for obvious reasons, cannot be used within a configuration file, all properties can be used in the two configuration locations: command-line properties and configuration file.

When used in a -D command-line property, app. must be prefixed to the property key (eg, app.general.mainWindowLocation).

Any spaces (U+0020), commas (',', U+002C), or backslash characters ('\', U+005C) in a direction keyword or an HTML font name must be escaped by prefixing a '\' character to them.

Any commas (',') or backslash characters ('\') in the name of a font must be escaped by prefixing a '\' character to them.

In the table below, the initial character of an italicised component of a property value denotes its data type according to the following convention:

f floating-point number
i integer
p platform-specific pathname, which may contain special constructions
s string
Property key Property value
configDir pPathname
appearance.lookAndFeel sName
appearance.statusTextColour iRed, iGreen, iBlue
appearance.textAntialiasing default | none | normal | subpixelHRgb | subpixelHBgr | subpixelVRgb | subpixelVBgr
clue.allowMultipleFieldUse false | true
clue.directionKeywords.across sKeyword [, sKeyword …]
clue.directionKeywords.down sKeyword [, sKeyword …]
clue.implicitFieldDirection false | true
clue.referenceKeyword sKeyword
file.filenameSuffix sSuffix
font.clue sName, plain | bold | italic | boldItalic, iSize
font.comboBox sName, plain | bold | italic | boldItalic, iSize
font.fieldNumber sName, plain | bold | italic | boldItalic, iSize
font.gridEntry sName, plain | bold | italic | boldItalic, iSize
font.main sName, plain | bold | italic | boldItalic, iSize
font.textField sName, plain | bold | italic | boldItalic, iSize
general.clearEditListOnSave false | true
general.mainWindowLocation iX, iY
general.mainWindowSize iWidth, iHeight
general.maxEditListLength iLength
general.selectTextOnFocusGained false | true
general.showFullPathnames false | true
general.showUnixPathnames false | true
grid.bar.barWidth iWidth
grid.cellSize.bar iSize
grid.cellSize.block iSize
grid.entryCharacters sCharacters
grid.imageViewportSize iWidth, iHeight
grid.navigateOverSeparators false | true
html.barGrid.barWidth iWidth
html.barGrid.excessBarWidth topLeftInside | topLeftOutside
html.blockImage.colour iRed, iGreen, iBlue
html.blockImage.lineWidth iWidth
html.blockImage.numLines iNumLines
html.blockImage.printOnly false | true
html.cellSize.bar iSize
html.cellSize.block iSize
html.fieldNumberFontSizeFactor fFactor
html.fontNames sName [, sName …]
html.fontSize iSize
html.gridColour iRed, iGreen, iBlue
html.stylesheetKind internal | external
html.viewerCommand sCommand
path.exportHtmlDirectory pPathname
path.openCrosswordDirectory pPathname
path.parameterSetFile pPathname
path.saveCrosswordDirectory pPathname
textSection.lineBreak sSequence
view.colour.background iRed, iGreen, iBlue
view.colour.caret iRed, iGreen, iBlue
view.colour.clueText iRed, iGreen, iBlue
view.colour.editingBox iRed, iGreen, iBlue
view.colour.emptyClueText iRed, iGreen, iBlue
view.colour.fieldNumberText iRed, iGreen, iBlue
view.colour.focusedEditingBox iRed, iGreen, iBlue
view.colour.focusedSelectedFieldBackground iRed, iGreen, iBlue
view.colour.fullyIntersectingFieldBackground iRed, iGreen, iBlue
view.colour.gridEntryText iRed, iGreen, iBlue
view.colour.gridLine iRed, iGreen, iBlue
view.colour.isolatedCellBackground iRed, iGreen, iBlue
view.colour.selectedClueBackground iRed, iGreen, iBlue
view.colour.selectedEmptyClueBackground iRed, iGreen, iBlue
view.colour.selectedFieldBackground iRed, iGreen, iBlue
view.colour.text iRed, iGreen, iBlue
view.colour.titleSeparator iRed, iGreen, iBlue
view.selectedClueNumColumns iNumColumns

Appendix D:  Providing feedback about CrosswordEditor

The CrosswordEditor project is hosted by SourceForge. You can submit bug reports, feature requests and suggestions for improvement through the SourceForge website, but the mechanism for doing so may change depending on the facilities that SourceForge provides. For current information, please see the feedback page for Blank Aspect projects.

When reporting a problem with CrosswordEditor, please try to include enough relevant information to enable the problem to be reproduced. You should include at least the following information:

A Java stack trace, if one is available, would be helpful.

Last modified: 2015-05-20