SudokuGenerator : manual
SudokuGenerator is a JavaFX application whose main purpose is, as its name suggests, to generate sudoku puzzles.
SudokuGenerator has the following features:
SudokuGenerator is made available under three licences:
uk.blankaspect.sudokugenerator package (including
resources) may be used under the terms and conditions of version 3 of the GNU General Public
License.
This section assumes that you have some experience of building and running a Java application.
The following software is required to build SudokuGenerator:
javafx.base
javafx.controls
javafx.graphics
javafx.swing
The src directory of the blankaspect/sudokuGenerator
repository contains the source code and resources that constitute the application; there
are no external dependencies apart from JavaFX. The directory conforms to the Maven
standard directory layout: the source code is in src/main/java and the
resources are in src/main/resources.
The supplied Kotlin-DSL-based Gradle
build script, build.gradle.kts, modifies the compileJava and
jar tasks (provided by the java plug-in) to compile the
application and to create an executable JAR file for it. The compileJava
task expects the required JavaFX modules to be supplied by a JavaFX SDK whose location
is specified by the JAVAFX_HOME environment variable. If this is
unsuitable, you could modify the build script in one of the following ways:
A Java Runtime Environment (JRE) and the JavaFX modules listed above are required to run SudokuGenerator. A Java Development Kit (JDK) includes a JRE. The JavaFX modules may be provided by separate JAR files or they may be included in a JRE:
--module-path and --add-modules options on the command line
of the Java launcher.
jlink tool from a JDK to create a
JRE that contains a custom set of Java SE, JDK and JavaFX modules. The blankaspect/makejre repository
contains a Bash script and a PowerShell 7 script that may be used to create a JRE with
jlink.
The supplied Kotlin-DSL-based Gradle build script, build.gradle.kts,
defines four tasks that may be used to run SudokuGenerator:
runMain and runJar tasks require the JavaFX modules to
be supplied by a JavaFX SDK whose location is specified by the
JAVAFX_HOME environment variable.
runMainJre and runJarJre tasks require a JRE that
includes JavaFX modules. The tasks expect the location of the JRE to be specified by
the JRE_DIR environment variable.
compileJava task.
compileJava task. The class is run with a Java launcher from a JRE that
includes JavaFX modules.
jar task.
jar task. The JAR is
run with a Java launcher from a JRE that includes JavaFX modules.
All four tasks extend the JavaExec task.
By default, when SudokuGenerator starts up, it seeks another running instance of the
application through a local port. If it finds one, it transmits the locations of any
files that were specified on its command line to the other instance, then it terminates.
If it doesn't find another instance of the application, it becomes the primary
instance of SudokuGenerator: it listens on the port for the locations of files from
other instances of the application when they start up, and it opens any file whose
location it receives. However, if the independentInstance system property
is true when an instance of SudokuGenerator is launched, it will run
independently of other instances of the application, neither transmitting nor receiving
the locations of files to or from another instance. The system property may be set on
the command line of the Java launcher (java or javaw) with the
-D option:
When it starts up, SudokuGenerator is configured from an optional configuration file
named sudokuGenerator-config.json whose location may be specified
explicitly or implicitly. The configuration file is a text file in JSON (JavaScript
Object Notation) format that is laid out to make it easy for humans to read. A default
value is used for a property that isn't explicitly defined in the configuration
file.
The location and use of a configuration file are controlled by two system properties:
blankaspect.app.auxDir
blankaspect.app.noConfigFile
The system properties may be set on the command line of the Java launcher
(java or javaw) with the -D option.
blankaspect.app.auxDir system property
The blankaspect.app.auxDir system property specifies, explicitly or
implicitly, the directory that contains the configuration file.
blankaspect.app.auxDir system property is an empty
string, SudokuGenerator will look for a configuration file in the current working
directory, which depends on the system and the way in which the application was run.
(On Unix-like systems, the working directory is denoted by the environment variable
PWD.)
blankaspect.app.auxDir system property is not an
empty string, it will be taken as the location of a directory that contains a
configuration file. If the location denotes an existing directory, SudokuGenerator
will look for a configuration file in that directory.
blankaspect.app.auxDir system property does not exist,
SudokuGenerator will look for a configuration file in the default directory:
$HOME/.blankaspect/sudokuGenerator, where HOME is the
environment variable that denotes the user's home directory.
%APPDATA%\blankaspect\sudokuGenerator, where APPDATA is
an environment variable that denotes a subdirectory of the user's home
directory named AppData.
After the location of the directory is determined in the way described above, if the directory does not exist or it does not contain a configuration file, default values will be used for the configuration properties.
If the configuration has changed when you exit the application normally (ie, using the
Exit command or an equivalent), the
configuration will be written to a configuration file unless the writing of the file is
suppressed by the blankaspect.app.noConfigFile system
property. If the writing of a configuration file is allowed, a file will be written
to the directory whose location is determined in the way described above.
blankaspect.app.noConfigFile system property
If the system property blankaspect.app.noConfigFile exists and its value is
true, no configuration file will be read when SudokuGenerator starts up,
default values will be used for the configuration properties and no configuration file
will be written when the application terminates.
The main window displays a view of a puzzle that has been created with the File > New command or loaded from a file, and it allows the puzzle to be edited. The window contains the following components, from top to bottom:
The menus in the menu bar provide access to the main commands of the application. Several of the commands in the menus can be issued by key combinations. The View menu and Puzzle menu are disabled if no puzzle is open in the application.
The pathname bar shows the location of the file that is associated with the current puzzle, if the puzzle has been loaded from or saved to a file. The square at the left of the pathname bar is highlighted if any unsaved changes have been made to the current puzzle.
The spinner is actually a combined spinner and drop-down list that can be used to navigate the list of documents that are open in SudokuGenerator. Pressing the primary mouse button on a component of the spinner has the following effect:
If no puzzle is open in the application, the spinner is disabled and its central label contains the text "No puzzles".
To the right of the spinner is a button that closes the current puzzle. If the puzzle has unsaved changes, a warning dialog is displayed in which you are asked to confirm the closure of the puzzle.
The current puzzle is displayed in the puzzle view, where it can be edited. The puzzle grid is drawn to fit the area between the puzzle spinner and the status bar, taking into account the minimum size of the margin around the grid and the requirement for the thicknesses of grid lines and the dimensions of cells to be an integral number of pixels. When the size of cells falls below a threshold, symbols in cells are rendered as dots.
The keyboard or mouse can be used to select a cell in the grid; the selected cell is highlighted when the puzzle view has keyboard focus. The arrow keys and the PageUp, PageDown, Home and End keys move the selected cell within the grid.
A symbol can be entered in the selected cell by typing the character that corresponds to the symbol. If the character is a letter, its case is ignored by default, but this can be changed with a user preference. If the selected cell contains a symbol, the symbol can be deleted with the space key or the Delete key.
If you edit a cell, you can undo the change with the Edit > Undo command (Ctrl+Z), and you can redo the change with the Edit > Redo command (Ctrl+Y).
The puzzle view has a context menu that contains all the commands from the Puzzle menu as well as some commands from the Edit menu and View menu. The context menu is triggered in a platform-specific manner, typically by pressing or releasing the secondary mouse button or by pressing a Menu key.
If the Puzzle > Solve command finds solutions to the current puzzle, the main window switches to solution mode in which the solutions are displayed in the puzzle view until the Puzzle > Close solutions command is issued (or the Escape key is pressed), which restores puzzle mode.
As an alternative to typing a character in the selected cell, you can also choose a symbol to be entered in the selected cell from a pop-up window that is displayed on the puzzle view. There are two variants of the pop-up: one in which navigation and selection are controlled with the mouse and one in which navigation and selection are controlled from the keyboard. The pop-up can be triggered in the following ways:
| Controller | Trigger |
|---|---|
| Mouse | Press the primary mouse button on a cell while the Control key is held down. The cell is selected before the pop-up is displayed. |
| Issue the Puzzle > Choose symbol for selected cell command (F6), which is also available from the context menu for the puzzle view. | |
| Keyboard | Press the Ctrl+Enter key combination. |
Within the pop-up, the symbols are displayed in a grid of buttons. If a symbol would conflict with another cell in the same row, column or block, its button is disabled. The mouse-controlled pop-up has a clear button below the grid if the target cell is not empty. You can close the pop-up without making a selection by pressing the Escape key or by pressing the primary mouse button on the main window.
The status bar may contain two kinds of information:
You can open one or more puzzle files and/or template files in SudokuGenerator by dragging representations of the files from a source such as a file browser and dropping them on the main window of the application. Files with the following filename extensions are accepted:
.sgp.sgt.txtThe directory-browser window is a modeless window that can be displayed from the main window of SudokuGenerator with the File > Browse directory command (F12). The window contains a grid view of representations of all the SudokuGenerator puzzle files and/or template files in a chosen directory.
The puzzles cannot be modified in the directory-browser window; the main purposes of the window are to provide an overview of a collection of puzzles and to allow multiple puzzles to be selected for opening and for export as an HTML document.
At the top of the browser window is a bar that contains two groups of buttons. The first button in the group on the left triggers a drop-down dialog that contains two controls: a spinner for the number of columns in the grid and a spinner that applies a filter to the files that are displayed in the window. The second button allows you to choose the directory whose files will be displayed in the window. The pathname of directory is shown in the title of the window. The third button refreshes the contents of the window to reflect external changes to the directory.
On the right of the button bar are a pair of buttons for selecting and deselecting all the files in the browser window. An individual file may be selected by clicking the primary mouse button on the header of the cell; if the Control key is held down when clicking, the selection of the file is toggled.
A file that is displayed in the browser window can be opened in SudokuGenerator by double-clicking the primary mouse button on the cell that is associated with the file.
The directory-browser window has a context menu that contains items to perform the following actions:
SudokuGenerator's main commands are accessible from its main menu. Some of the commands are also accessible from a context menu that is activated in a platform-specific manner (eg, by pressing or releasing the right mouse button) while the mouse cursor is over the puzzle view.
The New command (Ctrl+N) displays a modal dialog in which you can choose the order of the new puzzle. When you click the appropriate button or press the corresponding digit key, an empty puzzle of the chosen order is created and displayed in the puzzle view of the main window.
The Open puzzle command (Ctrl+O) displays a file-chooser
dialog in which you can choose a puzzle file to open. The dialog has filters for JSON
(.sgp) and plain-text (.txt) file formats. If the file is
read and parsed successfully, a document
is created from its contents and the puzzle is displayed in the puzzle view of the main window.
The Open template command (Ctrl+Shift+O) displays a
file-chooser dialog in which you can choose a template file to open. The dialog has
filters for JSON (.sgt) and plain-text (.txt) file formats.
If the file is read and parsed successfully, a document is created from its contents and the template is
displayed in the puzzle view of the main
window.
The Reload command reloads the current puzzle or template if it is associated with a file (that is, a file-system location).
The Close command (Ctrl+W) closes the current document. If the document has unsaved changes, a warning to this effect is displayed, and the document is closed after you have confirmed that you want to proceed.
The Close all command closes all the open documents. If any documents have unsaved changes, a list of those documents is displayed, from which you can choose the documents that you want to save before they are closed.
If the current document is associated with a file, the Close and delete command closes the document and deletes the associated file after you have confirmed that you want to proceed with the action. The command may be used to delete a template file after a puzzle has been generated from the template.
If the current document has unsaved changes, the Save command (Ctrl+S) command writes the document to a file. If the document is already associated with a file, it is immediately written to the file; otherwise, a dialog is displayed in which you can choose whether to save the current document as a puzzle or as a template, after which you can choose the file to which the document will be written.
The Save as puzzle command displays a file-chooser dialog
in which you can choose a file to which the current document will be written as a
puzzle. The dialog has filters for JSON (.sgp) and plain-text
(.txt) file formats.
The Save as template command displays a file-chooser dialog
in which you can choose a file to which the current document will be written as a
template. The dialog has filters for JSON (.sgt) and plain-text
(.txt) file formats.
The Export HTML file command (Ctrl+E) allows you to export the current puzzle or template as an HTML file that may be displayed in a web browser. The command first displays a dialog in which you can choose some parameters that relate to the HTML document that is generated. If this dialog is accepted, a file-chooser dialog is then displayed in which you can choose the file to which the HTML document will be written.
If you want to include multiple puzzles in an HTML document, you can do so from the directory-browser window.
The Browse directory command (F12) first displays a dialog in which you can choose the directory whose puzzle files and/or template files you wish to browse. After you've chosen a directory, the relevant files in the directory are displayed in the directory-browser window.
The Exit command terminates the application. Before the program shuts down, you will be prompted to save any open documents that have unsaved changes.
The edits (changes) 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 are stored in a list (the document's history) whose length is limited by a user preference.
The Undo command reverses the last edit that was made 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.
The Copy text command copies a textual representation of the current puzzle to the system clipboard. The text has the format of a plain-text file. The command displays a modal dialog in which the Separate blocks check box controls whether the blocks of the puzzle will be separated by spaces and empty lines in the textual representation.
If the system clipboard contains text that was copied to it by the Edit > Copy text command, the Paste command creates a puzzle document from it and displays the puzzle in the puzzle view of the main window.
The Preferences command displays a modal dialog in which the user preferences of SudokuGenerator can be edited. By default, the preferences are stored in a configuration file. The use of a configuration file can be disabled.
The individual user preferences are described in a later section.
The Copy image command creates an image of the current puzzle and puts it on the system clipboard for use by other applications. The command displays a modal dialog that contains two controls:
The Choose symbol for selected cell command (F6) triggers the symbol-chooser pop-up from which you can choose a symbol to be entered in the selected cell of the grid of the current puzzle. The pop-up is controlled by the mouse.
If the current puzzle is valid, the Find entry for selected cell command (Ctrl+F) searches for solutions to the puzzle after asking for confirmation. If it finds a unique solution, it sets the symbol of the selected cell of the current puzzle to the corresponding entry in the solution.
The search for solutions is equivalent to executing the Puzzle > Solve command with the following parameter values:
Note that the time taken to execute the Find entry for selected cell command can vary widely depending on the puzzle. It will usually be a fraction of a second for an order-3 puzzle, but it can be several minutes for a particularly tricky order-5 puzzle.
If the current puzzle is valid, the Solve command (F9) will search for solutions to the puzzle. The command displays a modal dialog that contains two controls:
The search for solutions uses backtracking, with flags that keep track of the available values (symbols) in the row, column and block to which a cell belongs. The time taken to search for a given maximum number of solutions varies with the puzzle; for a particularly tricky order-5 puzzle, it can be several minutes. Without randomisation, multiple searches of the same puzzle will follow the same path, and will therefore take roughly the same time, allowing for the vagaries of scheduling. With randomisation, multiple searches of the same puzzle will be likely to follow different paths, and a given randomised search may take more or less time than an unrandomised search. The randomised search option is selected by default because there is no reason to believe that, in the long run, the arbitrary ordering of search paths in an unrandomised search will outperform a random ordering.
If a search finds solutions, the main window switches to solution mode:
You can return to puzzle mode from solution mode with the Puzzle > Close solutions command or by pressing the Escape key.
Besides the Close solutions command, the only other command from the puzzle menu that is available in solution mode is the Puzzle > Duplicate command, which allows you to make a copy of the solution that is currently displayed.
The Close solutions command (Escape) is available only in solution mode. The command ends solution mode and restores puzzle mode (the default mode of the main window).
The Duplicate command (Ctrl+D) creates a new puzzle that is a copy of the current puzzle, and the copy becomes the current puzzle. The command can be used in solution mode to create a copy of a solution that survives beyond the end of solution mode.
The Generate command (Ctrl+G) attempts to generate a puzzle whose order is the order of the current puzzle and whose entries are constrained in one of two ways:
A puzzle may be generated in one of two ways, which are referred to as modes. Both modes have the same goal of finding entries for a set of target cells; they differ in how the search is performed:
The command dispays a modal dialog in which you can choose the parameters that control the generation of a puzzle using the following controls:
Runtime.availableProcessors() method. This number is displayed next to
the spinner when the value 0 is selected.
In both additive and subtractive modes, the tasks that run on multiple threads are independent of each other. This approach was adopted because, when generating a puzzle, most of the time (≈99% in additive mode, ≈90% in subtractive mode) is spent on verifying candidates — checking that a candidate has a unique solution by searching for two solutions. To partition the search tree over multiple threads would require the sharing of state between threads, and the synchronisation needed to achieve it was deemed too costly. The chosen approach means that the independent threads are in a race to generate a puzzle; if the number of threads is greater than 1, the order in which they finish is indeterminate. In other words, it is possible for two iterations of the race with the same set of parameters (seed of the PRNG, number of threads, etc) to be 'won' by different threads, yielding different puzzles.
Puzzle generation is started with the Generate button (Ctrl+Enter). During generation, a count of attempts is displayed as an indication of progress. The meaning of an attempt differs between additive mode and subtractive mode:
The Create template command (Ctrl+T) displays a modal dialog in which you can create a template that you can use to generate a puzzle. The dialog allows you to create multiple templates and to choose the one that you prefer.
The top part of the dialog contains a grid in which you can edit a template. The grid appears similar to the one in the puzzle view of the main window except that it is overlaid with representations of the kind of symmetry that is in effect in the dialog (ie, the value that is selected in the Symmetry spinner): reflectional symmetry is represented by axes of symmetry and rotational symmetry is represented by circular arcs.
When you issue the Create template command, if the current puzzle is not empty, its entries are copied, homogenised and set on the grid of the template dialog. The homogenised copy becomes the first element in the dialog's list of templates. Within the dialog, you can create templates and add them to the list, select a template from the list and edit the selected template. When you accept the dialog with the OK button, the selected template replaces the current puzzle in the main window and the remaining templates in the list are discarded.
The keyboard or mouse can be used to select a cell in the grid of the template dialog; the selected cell is highlighted when the puzzle view has keyboard focus. The arrow keys and the PageUp, PageDown, Home and End keys move the selected cell within the grid.
The symbol that is selected in the Symbol drop-down list can be entered in the selected cell by typing any of the characters that correspond to the symbols in the drop-down list. If the character is a letter, its case is ignored by default, but this can be changed with a user preference. If the selected cell contains a symbol, the symbol can be deleted with the space key or the Delete key.
Double-clicking the primary mouse button on a cell will toggle the grid entry between an empty cell and the symbol that is selected in the Symbol drop-down list.
Changes to the entries of the template can be undone and redone with the dialog's Undo and Redo commands, which can be accessed from a context menu on the grid or with the Ctrl+Z and Ctrl+Y key combinations.
The template dialog contains the following controls in the pane below the grid:
The four buttons at the bottom left of the dialog are associated with commands that are related to the list of templates:
The commands that are associated with the buttons are accessible through the context menu on the grid.
To the right of the four buttons are a box that contains the number of entries in the current template and a label that shows the index of the current template.
The Count entries command (F7) displays the number of grid entries in the current puzzle.
The Check command (F8) first tests whether the current puzzle is valid. If the puzzle contains conflicting entries, the first pair of such entries is highlighted; otherwise, a search for solutions is performed and the result of the search is reported. The search for solutions is equivalent to executing the Puzzle > Solve command with the following parameter values:
Note that the time taken to execute the Check command can vary widely depending on the puzzle. It will usually be a fraction of a second for an order-3 puzzle, but it can be several minutes for a particularly tricky order-5 puzzle.
The Transform submenu contains menu items for commands that perform geometric transformations on the current puzzle. The following transformations are available:
All the transformations preserve the well-posed property of a puzzle; that is, if a puzzle is well-posed before it is transformed, it will remain well-posed after the transformation.
The Homogenise entries command is intended for use when converting a puzzle to a template. It displays a modal dialog in which you can choose a symbol. If you accept the dialog with the OK button, the chosen symbol will replace the existing symbol in all the entries of the current puzzle. The command can be undone.
It is recommended that you use the same symbol for all the entries of a template so that a template can be visually distinguished from a puzzle in the puzzle view. The SudokuGenerator application does not distinguish between a regular puzzle and a template in its internal representation of a puzzle.
It may be unnecessary to execute the Homogenise entries command before you save a template with the File > Save command or the File > Save as template command because the Save commands will ask you whether you want to homogenise the entries of a template whose entries are not already homogeneous.
The Clear command removes all the entries of the current puzzle. The command can be undone.
The Delete properties command displays a modal dialog in which you can choose the properties that you want to remove from the current puzzle. Currently, there is only one property: generation information, which, if present, is displayed in the status bar. The command can be undone.
The Edit symbols command displays a modal dialog in which you can choose the symbols that will apply to the current puzzle. When a new puzzle is created, its symbols are set to the default symbols for the order of the puzzle. The command can be undone.
The background colour of the Symbols field indicates whether the set of symbols is invalid (red) or valid (green). A set of symbols is invalid if
A symbol is valid if it belongs to one of the following Unicode general categories:
| Lu | Uppercase_Letter |
| Ll | Lowercase_Letter |
| Lt | Titlecase_Letter |
| Lo | Other_Letter |
| Nd | Decimal_Number |
| Nl | Letter_Number |
| Pc | Connector_Punctuation |
| Pd | Dash_Punctuation |
| Ps | Open_Punctuation |
| Pe | Close_Punctuation |
| Po | Other_Punctuation |
| Sm | Math_Symbol |
| Sc | Currency_Symbol |
| So | Other_Symbol |
The Manage Windows file associations command is enabled
only when SudokuGenerator is running on Windows. It provides a means of adding or
removing an association between the SudokuGenerator application and files whose filename
extension is that of a SudokuGenerator JSON-format puzzle file (.sgp) or
template file (.sgt). A file association will allow you, for example, to
open a puzzle document in SudokuGenerator by double-clicking on its filename in File
Explorer. If SudokuGenerator is already running, the document will be opened in it;
otherwise, the document will be opened in a new instance of SudokuGenerator. (This
behaviour can be changed with the independentInstance system property.)
The command creates a file association by modifying entries in the Windows Registry, which it does by generating and executing a Windows PowerShell script. You may execute the script automatically after it is generated, or you can create a script file that you can use outside SudokuGenerator. In order to run the script, you must have PowerShell 5.1 or later installed on your system and you must be able to run a PowerShell script as an administrator.
The Manage Windows file associations command displays a
dialog 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 new file associations or modifies existing
associations; Remove removes file associations that were created with the
Add option. The same script is used for both adding and removing file
associations; the difference in behaviour is achieved by adding a switch (the argument
-remove) to the command line when the script is used to remove file
associations.
Below the Action drop-down list are fields in which you specify the locations of three files that are required to create the file associations. The fields are disabled if the selected action is Remove because the locations of the files aren't required when removing file associations, 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 constructs
for system properties and environment variables. If a specified system property exists,
the construct 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 SudokuGenerator 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 file associations, the files whose locations you must specify are:
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 directory that contains the
launcher of the current SudokuGenerator 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.
app.ico, which
can be found in the uk.blankaspect.sudokugenerator.images package of the
application's resources, is provided for this purpose, but you may choose any
suitable icon file to associate with SudokuGenerator documents.
The Files must exist check box below the pathname fields should be selected if you want SudokuGenerator 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 constructs 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 sudokuGeneratorAssociations.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 name of the subdirectory has the prefix
sudokuGenerator_ , 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 accept the dialog with the OK button, the pathnames are validated if the action is Add and the Files must exist check box is selected. If there is no error, a text-output dialog is displayed to serve as a console for reports of the progress of script operations along with error messages from SudokuGenerator and PowerShell. The location of the script file is written to the text-output dialog. Because the script is run as an administrator, Windows may display a User Account Control dialog to ask for confirmation that you want to run the script. When the script operations have finished, you can copy the contents of the text-output dialog to the system clipboard with the dialog's Copy command.
The Colour scheme spinner selects the colour scheme — light or dark — that applies to the user interface of the application. When you change the value in the spinner, the new colour scheme takes effect immediately. The old scheme is restored if you cancel the Preferences dialog.
The three Grid font components control the font that is used for the symbols of a grid in the main window, the directory-browser window and the template dialog. If the check box is not selected, the default font (System, Regular) is used. If the check box is selected, you can choose the family and style of the font from the two drop-down lists.
This preference applies when you use the keyboard to enter a symbol into the grid in the main window or the template dialog, if the symbol is a letter. If the Ignore letter case when typing in a grid check box is selected, the case of the typed letter is ignored when it is matched against the symbols of the puzzle. If the check box is not selected, the case of the typed letter must match the case of the symbol.
The two controls in the Default symbols pane allow you to choose a default set of symbols for each order of a puzzle that is supported by SudokuGenerator. First, select the order with the Order spinner, then enter the required number of characters in the Symbols field. The background colour of the field indicates whether the set of symbols is invalid (red) or valid (green). A set of symbols is invalid if
The default symbols apply initially to a new puzzle that is created with the File > New command. The symbols of a puzzle can be changed with the Puzzle > Edit symbols command.
The Maximum size of history spinner selects the maximum number of edits that can be stored in a document's history for use by the Edit > Undo and Edit > Redo commands.
If the Clear history on save check box is selected, a document's history of edits (see Edit > Undo/Redo) is cleared when the document is saved.
The following terms are used in this document and in the SudokuGenerator application. The terms marked with an asterisk, *, were coined for use with SudokuGenerator.
Where indicated elsewhere in this document, some pathname parameters and system properties in SudokuGenerator can contain special constructs for system properties, environment variables and the user's home directory. The special constructs are expanded when the pathname is used.
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
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 Unix-like systems or USERPROFILE
on Windows systems.
• Example: ~/projects
SudokuGenerator recognises the system properties listed below. A system property can be
set on the command line of the Java launcher (java or javaw)
with the -D option (eg, -Dblankaspect.app.noConfigFile=true).
true, the style sheets that are generated by StyleManager
will be written to a temporary file; otherwise, the style sheets will be data-scheme
URIs.
LocationChooser.Dialog is displayed. The delays are applied in the order
size – location – opacity.
SimpleDialog is displayed. The delays are applied in the order
size – location – opacity.
SimpleProgressDialog is displayed. The delays are applied in the order
size – location – opacity.
Most of the system properties listed above are delays that have been introduced as a workaround for a persistent problem in JavaFX that has been observed on Linux/GNOME when the size or location of a window is changed after it first appears. The default values for the delays have been chosen in a trade-off between two kinds of poor user experience: the shrinking of a window, which is the observable symptom of the problem, versus the unpleasant visual effect of moving the window after it has appeared on the screen. The default values were determined by experiment on a single machine running Ubuntu. They may not be appropriate for other machines and systems, so the delays have been exposed as system properties so that users can modify them. The property values are expected to be integers and the units are milliseconds.
Although the problem is not present in JavaFX on Windows, the same set of delays are applied to simplify the code. This was deemed acceptable because the unpleasant effect of moving a visible window is avoided by setting the opacity of the window to 0 before it is shown, then setting the opacity to 1 after the size and location of the window have been changed. Sadly, the same trick doesn't work on Linux/GNOME because it seems that GNOME doesn't allow the opacity of a window to be changed.
SudokuGenerator supports two file formats for puzzles and templates: a JSON format, which is recommended for general use, and a plain-text format, which is intended to allow files to be created and edited manually. The plain-text format is also used by the commands for copying and pasting text. In this appendix, a file in plain-text format is referred to as a text file.
To inform the description of the plain-text format in the following sections, here are two examples of the format.
The first example is a minimal document that contains
# . ..9....2. 6....8... ...7....5 .3..9.6.. ...1.5... ..2.6..7. 4....3... ...2....9 .6....8..
The second example is a puzzle that was written to a file by SudokuGenerator. The puzzle is the same as the previous example except for the replacement of the default symbols by letters, which requires an an explicit symbol-definition line. The document contains
*3 denotes the order of the puzzle),
# Sudoku *3 .ABCDEFGHJ #------------ ..J ... .B. F.. ..H ... ... G.. ..E .C. .J. F.. ... A.E ... ..B .F. .G. D.. ..C ... ... B.. ..J .F. ... H..
A text file contains text encoded as UTF-8 and consisting of a sequence of lines. Successive lines are separated by one of the following:
A file must contain the following lines, in the order given:
There may also be blank lines anywhere in the file, and there may be additional comment lines anywhere after the first comment line.
A blank line is empty or contains only ignored characters.
A comment line contains zero or more ignored characters followed by a comment. A comment line is generally equivalent to a blank line in that it is ignored. However, the first comment line of a file is significant because it defines the comment-prefix character that applies to the file.
The symbol-definition line must start with a placeholder character, which denotes an empty grid cell in a puzzle row. The placeholder character may optionally be followed by a character for each of the n × n symbols of a puzzle of order n. These are the symbols that are expected to appear in the puzzle rows of the file. If the symbols are omitted, the application's default symbols for the puzzle order will be assumed. The application's default symbols are the initial values of the default symbols user preference:
| Order 2 | 1 2 3 4 |
| Order 3 | 1 2 3 4 5 6 7 8 9 |
| Order 4 | A B C D E F G H J K L M N O P Q |
| Order 5 | A B C D E F G H J K L M N O P Q R S T U V W X Y Z |
Note that the default symbols of order-4 and order-5 puzzles do not contain the letter
I. In addition to the mandatory placeholder character and the optional
symbols, the symbol-definition line may contain ignored characters and a trailing
comment, which is ignored. The symbol-definition line must be the first line of the
file that is neither a blank line nor a comment line.
A puzzle row must contain n × n significant characters, where n is the order of the puzzle. A significant character is either
An ignored character is a character whose Unicode general category is one of the following:
| Zs | Space_Separator |
| Zl | Line_Separator |
| Zp | Paragraph_Separator |
| Cf | Format |
| Cs | Surrogate |
| Co | Private_Use |
| Cn | Unassigned |
Ignored characters include spaces (U+0020) and tabs (U+0009).
A comment is the optional part of a line of a text file that starts at the first comment-prefix character in the line and ends at the end of the line.
The comment-prefix character is defined as the first character of the first non-blank line of the file that is not an ignored character. In other words, the first non-blank line of a file is taken to be a comment line, and the first significant character of that line is taken to be the comment prefix for the whole file.
A comment may contain any characters except for those that mark the end of a line; all the characters in the comment, including the comment prefix, are ignored. The effect of a comment-prefix character does not extend beyond the line in which it appears.
The following steps are performed when parsing a file in plain-text format:
