Table of contents

1  Introduction

[ Table of contents ]

PasswordGenerator is a JavaFX application for generating random text that may be used for passwords. It can also be used for more esoteric purposes such as generating random permutations of digits.

1.1  Features

PasswordGenerator has the following features:

• The characters of the generated text may be selected from five categories that cover the printable characters of the ASCII character encoding. A category may be marked as required; if so, it must contribute at least one character to the generated text.
• Characters may be explicitly included in and excluded from the generated text.
• The length of the generated text may be a specified value or a random value between specified lower and upper bounds, up to a maximum length of 1024 characters.
• There is an option to require generated text to consist of unique characters (that is, no character may appear more than once in the text).
• Generated text can be easily copied to the system clipboard.
• You can save a set of parameters — character categories and their required flags; explicitly included and excluded characters; the unique characters flag — as a named preset that may be selected from a menu.
• The default implementation of the Java SecureRandom class is used as the pseudo-random number generator for generating random characters.
• Programmers can extend the pool of characters from which the generated text is drawn by the simple means of adding categories to the CharCategory enumeration.

1.2  Licence

PasswordGenerator is made available under three licences:

• The contents of the uk.blankaspect.passwordgenerator package (including resources) may be used under the terms and conditions of version 3 of the GNU General Public License.
• The Roboto Mono fonts may be used under the terms and conditions of version 1.1 of the SIL Open Font License.
• All other contents of the blankaspect/passwordGenerator repository may be used under the terms and conditions of the MIT License.

2  Building and running the application

[ Table of contents ]

This section assumes that you have some experience of building and running a Java application.

2.1  Building the application

The following software is required to build PasswordGenerator:

• A Java Development Kit (JDK) that supports Java 17, such as Eclipse Temurin from Adoptium.
• The following JavaFX modules:
  • javafx.base
  • javafx.controls
  • javafx.graphics
  • javafx.swing
  The JavaFX modules must be compatible with the JDK. The modules may be supplied as JMOD files for compiling and linking, or the contents of the modules may be supplied by JAR files from the JavaFX software development kit (SDK). The JavaFX JMODs and SDK are available from OpenJFX.
  If you're building with Gradle or Maven, JavaFX artifacts are available from Maven Central.

The src directory of the blankaspect/passwordGenerator 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:

• replace the local dependency on a JavaFX SDK with an external dependency on a JavaFX artifact from a repository, or
• use the JavaFX Gradle plug-in.

2.2  Running the application

A Java Runtime Environment (JRE) and the JavaFX modules listed above are required to run PasswordGenerator. 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:

• If you run PasswordGenerator with a JRE that does not contain JavaFX modules, the location and names of the modules must be specified with the --module-path and --add-modules options on the command line of the Java launcher.
• You can avoid the use of the command-line options if you run PasswordGenerator with a JRE that contains JavaFX modules. JavaFX modules are included in some third-party JREs, such as the Azul Zulu JRE FX packages, or you can use the 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 PasswordGenerator:

• The 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.
• The 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.

runMain

Runs the main class from the class files that were generated by the compileJava task.

runMainJre

Runs the main class from the class files that were generated by the compileJava task. The class is run with a Java launcher from a JRE that includes JavaFX modules.

runJar

Runs the executable JAR that was generated by the jar task.

runJarJre

Runs the executable JAR that was generated by the jar task. The JAR is run with a Java launcher from a JRE that includes JavaFX modules.

All four tasks extend the JavaExec task.

3  Configuration

[ Table of contents ]

When it starts up, PasswordGenerator is configured from an optional configuration file named passwordGenerator-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.

3.1  The blankaspect.app.auxDir system property

The blankaspect.app.auxDir system property specifies, explicitly or implicitly, the directory that contains the configuration file.

• If the value of the blankaspect.app.auxDir system property is an empty string, PasswordGenerator 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.)
• If the value of the 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, PasswordGenerator will look for a configuration file in that directory.
  The value of the system property may contain special constructs for system properties, environment variables and the user's home directory.
• If the blankaspect.app.auxDir system property does not exist, PasswordGenerator will look for a configuration file in the default directory:
  • On Unix-like systems, the default directory is $HOME/.blankaspect/passwordGenerator, where HOME is the environment variable that denotes the user's home directory.
  • On Windows, the default directory is %APPDATA%\blankaspect\passwordGenerator, 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.

3.2  The 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 PasswordGenerator starts up, default values will be used for the configuration properties and no configuration file will be written when the application terminates.

4  The main window

[ Table of contents ]

PasswordGenerator's main window is divided into four sections, from top to bottom:

• a toolbar,
• a control pane,
• a password pane,
• a button pane.

4.1  The toolbar

The toolbar contains three buttons, from left to right:

• The Add or update preset button issues the Add or update preset command.
• The Presets button displays a menu that is divided into two sections. The top section of the menu contains an item for each of the available presets. A preset can be applied to the components of the control pane by selecting the corresponding item in the menu. The bottom section of the menu contains an item for the Edit presets command. The Presets button is disabled if there are no presets.
• The Preferences button issues the Preferences command.

4.2  The control pane

The control pane contains components that control the generation of a password.

4.2.1  Character-category check boxes

At the top of the control pane, there is a pair of check boxes for each of five character categories; each pair comprises a category check box and a category required check box. The categories are associated with disjoint subsets of the ASCII character encoding; taken together, they cover the 95 printable characters of the encoding. The category check box determines whether the characters that belong to the category will be included in the pool from which the characters of a password are drawn. If the category required check box is selected, a generated password must contain at least one character from the corresponding category.

4.2.2  The Include field and Required check box

Characters in the Include text field are added to the pool from which the characters of a password are drawn. If the associated Required check box is selected, a generated password must contain at least one of the characters from the field. If any included character is a duplicate of a character from a selected category, the character is removed from the characters that are contributed by the category so that each character in the pool has the same probability of being drawn.

By default, you can include only printable ASCII characters (Unicode code points in the range from U+0020 to U+007E inclusive). This restriction is controlled by a user preference.

4.2.3  The Exclude field

Characters in the Exclude text field are removed from the the pool from which the characters of a password are drawn.

4.2.4  The Unique characters check box

If the Unique characters check box is selected, a generated password will not contain any duplicate characters. This requirement implicitly limits the length of a password to the number of characters in the pool from which the characters of a password are drawn.

4.2.5  The Length spinners and link button

The Length spinners determine the lower and upper bounds of the length of a generated password. The link button links and unlinks the values of the two spinners. If the spinners are linked, the length of a password will be the value of both spinners. If the spinners are unlinked, the length of a password will be a random value between the lower and upper bounds (inclusive), and all values are equally likely.

4.3  The password pane

The password pane contains a label in which a password is displayed after it has been generated. If a password is too long for the label, it is truncated and the missing part is replaced by an ellipsis. In this case, you can view the whole password — or, at least, as much of it as can fit in the width of the screen — by holding down the primary mouse button on the label.

4.4  The button pane

The button pane contains three buttons, from left to right:

• The Copy button issues the Copy password command.
• The Generate button issues the Generate password command.
• The Exit button issues the Exit command.

5  Commands

[ Table of contents ]

The application's commands may be issued from a button in the toolbar or button pane of the main window or from an item in the Presets menu. Most of the commands may also be issued with a key combination.

5.1  The Add or update preset command

The Add or update preset command (Ctrl+P) displays a modal dialog for the name of the preset.

• If you want to add a preset, you should enter the name of the new preset in the text field. When you accept the dialog, a new preset will be created from the current parameters and appended to the list of presets.
• If you want to update an existing preset, you should choose the name of the preset from the drop-down list. When you accept the dialog, you will be notified of the conflicting name and asked whether you want to update the existing preset. If you agree, the preset will be updated with the current parameters.

5.2  The Edit presets command

The Edit presets command (Ctrl+E) is available from the Presets menu. It displays a modal dialog that contains a list view of the names of the presets and some buttons for performing operations on the preset that is selected in the list view:

• The Edit button displays a modal dialog in which the preset may be renamed.
• The Remove button removes the selected preset from the list after confirmation. You can suppress the confirmation dialog by holding down the Shift key while you click the button. You can issue a remove command by pressing the Delete key when the list view has keyboard focus. (Shift+Delete removes the preset from the list without asking for confirmation.)
• The Move up and Move down buttons change the position of the preset in the list.

5.3  The Preferences command

The Preferences command (F8) displays a modal dialog in which the user preferences of PasswordGenerator can be edited. By default, the preferences are stored in a configuration file. The use of a configuration file can be disabled.

5.4  The Copy password command

The Copy password command (Ctrl+C) copies the last password to be generated by the Generate password command to the system clipboard. The last password is the one that is displayed in the password pane of the main window.

5.5  The Generate password command

The Generate password command (Ctrl+G) generates a password with the parameters that are obtained from the components in the control pane of the main window. An error message is displayed if the parameters do not allow a password of the desired length to be generated. If a password is generated successfully, it is displayed in the password pane.

5.6  The Exit command

The Exit command terminates the application.

6  Preferences

[ Table of contents ]

The user preferences of PasswordGenerator may be edited in the Preferences dialog that is displayed in response to the Preferences command.

6.1  Appearance

6.1.1  Colour scheme

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.

6.2  Characters

6.2.1  Include only ASCII characters

The Include only ASCII characters check box applies to the characters in the Include field of the main window, which are referred to as included characters. If the check box is selected, an included character must be a printable ASCII character (a Unicode code point in the range from U+0020 to U+007E inclusive); otherwise, an included character may be any character that you can type in the Include field.

6.3  Saved settings

The check boxes in the Saved settings pane control whether the state of components in the control pane of the main window will be saved to the configuration file when the application terminates, unless the use of a configuration file has been disabled.

6.3.1  Save character parameters

If the Save character parameters check box is selected, the state of the character-related components of the main window will be saved to the configuration file when the application terminates. The character-related components are those whose states correspond to the parameters of a preset.

6.3.2  Save password length

If the Save password length check box is selected, the values of the Length spinners and the selected state of the link button will be saved to the configuration file when the application terminates.

7  Presets

[ Table of contents ]

7.1  The parameters of a preset

A preset is a named set of parameters that correspond to the following states of components in the control pane of the main window:

• the selected state of each of the category check boxes and category required check boxes;
• the content of the Include field and the selected state of its Required check box;
• the content of the Exclude field;
• the selected state of the Unique characters check box.

7.2  Operations related to presets

A preset is created with the Add or update preset command. The new preset is added to a list that may be edited with the Edit presets command. When PasswordGenerator terminates, the list of presets is saved to the configuration file unless the use of a configuration file has been disabled.

The names of the current presets are displayed in a menu that is triggered by the Presets button in the toolbar of the main window. If a preset is selected from the menu, the states of the relevant components in the control pane of the main window are updated from the parameters of the preset.

You can update an existing preset with the current state of the components in the control pane by issuing the Add or update preset command and choosing the name of the preset from the drop-down list.

You can perform the following operations from the dialog that is displayed in response to the Edit presets command:

• rename a preset,
• remove a preset from the list,
• change the position of a preset in the list.

Appendix A:  Special constructs in pathnames

[ Table of contents ]

Where indicated elsewhere in this document, some pathname parameters and system properties in PasswordGenerator 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.

A.1  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

A.2  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 Unix-like systems or USERPROFILE on Windows systems.

• Example: ~/projects

Appendix B:  System properties

[ Table of contents ]

PasswordGenerator 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).

blankaspect.app.auxDir

This property determines the location of the application's configuration file.

blankaspect.app.noConfigFile

This property controls the use of a configuration file by the application.

mainWindowDelay.size
mainWindowDelay.location
mainWindowDelay.opacity

The values of these properties are the durations (in milliseconds) of the three delays that are applied after the main window of the application is displayed. The delays are applied in the order size – location – opacity.

useStyleSheetFile

This property may be used by developers for debugging a CSS style sheet. If its value is 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.

blankaspect.ui.jfx.simpleDialog.windowDelay.size
blankaspect.ui.jfx.simpleDialog.windowDelay.location
blankaspect.ui.jfx.simpleDialog.windowDelay.opacity

The values of these properties are the durations (in milliseconds) of the three delays that are applied after an instance of SimpleDialog is displayed. The delays are applied in the order size – location – opacity.

B.1  Window delays

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.