{"id":1170,"date":"2025-05-07T11:18:15","date_gmt":"2025-05-07T08:18:15","guid":{"rendered":"https:\/\/www.juustila.com\/antti\/?p=1170"},"modified":"2025-05-07T11:22:12","modified_gmt":"2025-05-07T08:22:12","slug":"managing-app-settings-with-java-properties","status":"publish","type":"post","link":"https:\/\/www.juustila.com\/antti\/2025\/05\/07\/managing-app-settings-with-java-properties\/","title":{"rendered":"Managing app settings with Java Properties"},"content":{"rendered":"\n

Many (most?) apps need some kind of settings the user can modify, that influence on the behavior of the app across app launches. In this post, I’ll show how to implement this with java.util.Properties<\/code> class in a Java \/ Swing game.<\/p>\n\n\n\n

As an example, I will use the Snakeses game from the previous post. In this game, user can change the difficulty, game mode and light\/dark mode of the UI:<\/p>\n\n\n\n

\"\"<\/figure>\n\n\n\n

The selections will be saved to and read from a file named snakeses.ini<\/code>: <\/p>\n\n\n\n

#Snakeses Settings\n#Tue May 06 19:28:32 EEST 2025\ndifficulty=hard\nmode=dark\nplayername=Antti\nstyle=classic<\/code><\/pre>\n\n\n\n
The settings file contains key-value pairs<\/em> (e.g. on line difficulty=hard<\/code> the  difficulty<\/code> is a key<\/em>, and hard<\/code> is the value<\/em>). Managing the settings is then just handling these key-value pairs, providing a user a way to change these in a controlled manner, and then handling the saving and restoring the values with the settings file. The file can also contain commented lines (beginning with #<\/code>) that are just for humans to read, and are not actual settings.<\/p>\n\n\n\n
As you can see, also the latest player’s name, who entered the Hall of Fame, is also stored in the settings. Assuming the game is mostly played by the same player, she does not need to write her name again and again, but can just accept the notification as you can see in the previous post video.<\/p>\n\n\n\n
The settings are managed in a single class, unsurprisingly named Settings<\/code>:<\/p>\n\n\n\n
public class Settings {\n    public Settings() {\n        difficulty = \"easy\";\n        style = \"modern\";\n        mode = \"dark\";\n        playerName = \"Anonymous\";\n    }\n\n    public String difficulty;\n    public String style;\n    public String mode;\n    public String playerName;\n\n    public boolean isDirty = false;\n    private static final String SETTINGS_FILE_NAME = \"snakeses.ini\";<\/code><\/pre>\n\n\n\n
As you can see, the constructor gives the default values to the various settings. You can also see that I’ve taken the easy road of letting the members be public<\/code> instead of the default and recommended private<\/code>. Lazy me, but I am myself making sure that as the only programmer in this project I will treat these public members responsibly and not mess the values with anything that is invalid. In a larger project I would let them be private<\/code> and make sure that setter methods would check that the parameters to change the setting values would always be valid.<\/p>\n\n\n\n
How to read the settings from the snakeses.ini<\/code> file, is shown here:<\/p>\n\n\n\n
public void read() throws IOException {\n    File configFile = new File(SETTINGS_FILE_NAME);\n    Properties config = new Properties();\n    try (FileInputStream istream = new FileInputStream(configFile)) {\n        config.load(istream);\n        if (config.containsKey(\"difficulty\")) {\n            difficulty = config.getProperty(\"difficulty\");\n        } else {\n            difficulty = \"easy\";\n        }\n        if (config.containsKey(\"style\")) {\n            style = config.getProperty(\"style\");\n        } else {\n            style = \"modern\";\n        }\n        if (config.containsKey(\"mode\")) {\n            mode = config.getProperty(\"mode\");\n        } else {\n            mode = \"dark\";\n        }\n        if (config.containsKey(\"playername\")) {\n            playerName = config.getProperty(\"playername\");\n        }\n    } catch (FileNotFoundException e) {\n        difficulty = \"easy\";\n        style = \"modern\";\n        mode = \"dark\";\n        playerName = \"Anonymous\";\n        save();\n    } finally {\n        isDirty = false;\n    }\n}<\/code><\/pre>\n\n\n\n
Opening and reading the settings file is handled using java.io.File<\/code>, java.io.FileInputStream<\/code> and java.util.Properties<\/code> classes. The Properties<\/code> object will then contain the settings read from the ini file, after calling config.load(istream)<\/code>.<\/p>\n\n\n\n
After that, it is simple to read the setting values from the properties object by calling config.getProperty<\/code>, giving the name of the property. Just to be sure, the code checks if the properties contain that key (using config.containsKey<\/code>, and if it does not, a default value is used. This is necessary, since the file could be changed outside of the app, by the user, for example, so as a programmer you cannot trust that the file (after saving it) will surely contain those key-value pairs.<\/p>\n\n\n\n
Also, when the app launches for the first time, the settings file is not there. It could be delivered with the app with default values, but again, nothing stops the user accidentally or deliberately deleting that file. So the code must prepare for the situation that the settings file does not exist — that’s why the catch (FileNotFoundException e)<\/code>. If the file is not there, again, resort to the default setting values. And then<\/em> save the settings immediately, calling save()<\/code>. That makes sure that at least now we have the settings file there.<\/p>\n\n\n\n
The member variable isDirty<\/code> is also set to false. isDirty<\/code> is convenient to have. When the user opens up the settings panel and closes it, there is no sense in saving the settings if they were not changed. As you can see below, the isDirty<\/code> is set to true if the settings change, and only then the settings are actually saved. No need to do any disk access if there is no need for it.<\/p>\n\n\n\n
\n
Do note that the app in this demo does not check if the settings are actually different from the original when user leaves the settings panel. If there are lots of settings and changing them leads to lots of code to be executed, you might want to keep the old settings somewhere, let the user to manipulate the settings, and then when the user is done, actually compare the old setting values to new ones. For those values that are actually different, then handle the changes to those settings only.<\/p>\n<\/blockquote>\n\n\n\n
How about saving the settings:<\/p>\n\n\n\n
public void save() throws FileNotFoundException, IOException {\n    File configFile = new File(SETTINGS_FILE_NAME);\n    Properties config = new Properties();\n    try(FileOutputStream ostream = new FileOutputStream(configFile)) {\n        config.setProperty(\"difficulty\", difficulty);\n        config.setProperty(\"style\", style);\n        config.setProperty(\"mode\", mode);\n        config.setProperty(\"playername\", playerName);\n        config.store(ostream, \"Snakeses Settings\");\n    } finally {\n        isDirty = false;\n    }\n}<\/code><\/pre>\n\n\n\n
Saving settings to a file is handled using java.io.File<\/code>, java.io.FileOutputStream<\/code> and java.util.Properties<\/code> classes. In this case we just set the various properties of the Properties<\/code> object, using config.setProperty<\/code>, giving the key and value pairs to the configuration, and finally call config.store<\/code>. As you can see, the string “Snakeses Settings” and the date of the update is saved as comments to the snakeses.ini<\/code> file.<\/p>\n\n\n\n
Also, the isDirty<\/code> is set to false at this time; settings are now saved and not changed.<\/p>\n\n\n\n
How the Settings panel then uses the settings when user is shown the current settings? As an example, let’s see how the game difficulty radio buttons are created and how the radio button corresponding to the current setting is selected, in SettingsPanel<\/code> constructor, other details omitted:<\/p>\n\n\n\n
public class SettingsPanel extends JPanel implements ActionListener {\n\n    private Settings settings;\n\n    public SettingsPanel(Settings settings) {\n        this.settings = settings;\n\n        ButtonGroup levelGroup = new ButtonGroup();\n        JRadioButton easy = new JRadioButton(\"Easy\");\n        easy.setActionCommand(\"easy\");\n        easy.addActionListener(this);\n        JRadioButton hard = new JRadioButton(\"Hard\");\n        hard.setActionCommand(\"hard\");\n        hard.addActionListener(this);\n        levelGroup.add(easy);\n        levelGroup.add(hard);\n        if (settings.difficulty.equals(\"easy\")) {\n            easy.setSelected(true);\n        } else {\n            hard.setSelected(true);\n        }<\/code><\/pre>\n\n\n\n
The “Easy” and “Hard” radio buttons are created to a ButtonGroup<\/code>. That takes care of managing the principle of the related radiobuttos that only one of them can be selected at one time. The last if-else block shows how the current value of the Settings<\/code> is used to select one or the other from these game difficulty radio buttons.<\/p>\n\n\n\n
\n
Did you know that the name “radio button” for this control comes from the actual radios to listen to radio stations? Radios used to have several buttons for selecting preselected radio station frequencies to listen to. Obviously, you can only listen to one station at a time. So pressing down one station button would then deselect (pop up) the previously selected station button.<\/p>\n\n\n\n
That’s why these buttons are called “radio buttons”. Radio buttons in GUI frameworks are round to distinguish them from check boxes, which are rectangular and function differently (many of them can be selected simultaneously).<\/p>\n<\/blockquote>\n\n\n
\n
\"A
Row of seven white rectangular radio buttons in a vintage radio divide. Image from https:\/\/www.collectorsweekly.com\/stories\/273171-1950s-grundig-fleetwood-tube-radio-mode<\/figcaption><\/figure>\n<\/div>\n\n\n
Obviously, the controls to use in managing the settings depends on the setting and the possible values of that setting. For example, if we would have a setting with multiple values, like e.g. 42 distinct values, using radio buttons would not be a good choice. Then one could use a dropdown \/ combobox list instead, populating the available options to the list and selecting the one found in the settings.<\/p>\n\n\n\n
What happens then when user changes the setting? In the code above, you can see that the SettingsPanel<\/code> is set as the action listener to the radiobuttons, e.g. in easy.addActionListener(this)<\/code>. Also, each radio button were given a name<\/em> for the command they represent, e.g. like this: easy.setActionCommand(\"easy\")<\/code>.<\/p>\n\n\n\n
The panel implements the ActionListener<\/code> interface, and therefore must have the method actionPerformed<\/code> overridden. Again, let’s look at the relevant parts of this method:<\/p>\n\n\n\n
public void actionPerformed(ActionEvent e) {\n    final String action = e.getActionCommand();\n    if (action.equals(\"easy\") || action.equals(\"hard\")) {\n        if (!settings.difficulty.equals(action)) {\n            settings.difficulty = action;\n            settings.isDirty = true;\n        }\n    } else if (action.equals(\"classic\") || action.equals(\"modern\")) {\n\/\/ and the same for the other radio buttons...<\/code><\/pre>\n\n\n\n
Here, we check which was the action command related to the action event. So if the command was “easy” or “hard”, we check if the related setting value is different, we then change it and also set the isDirty<\/code> of the setting to true<\/code> indicating a need to actually save the settings to the snakeses.ini<\/code> file as seen above.<\/p>\n\n\n\n
So far we have seen how the Settings<\/code> class manages the settings file, and how the SettingsPanel<\/code> displays the current settings, and then changes the settings based on user actions.<\/p>\n\n\n\n
How the app then actually initializes the settings and saves them if they have been changed? This is done, in this app, in the SnakesesApp<\/code> class that contains the main<\/code> method of the app.<\/p>\n\n\n\n
When the app is launched, the settings object is the first one to be created:<\/p>\n\n\n\n
    public static void main( String[] args )\n    {\n        javax.swing.SwingUtilities.invokeLater(new Runnable() {\n            public void run() {\n                new SnakesesApp().run();\n            }\n        });        \n    }\n    private static SnakesesGame game;\n    private static Settings settings;\n    private static HallOfFame hallOfFame;\n\n\/\/ Later...\n\nprivate void run() {\n    try {\n        settings = new Settings();\n        settings.read();\n        hallOfFame = new HallOfFame();\n        hallOfFame.read();\n        game = new SnakesesGame(GameViewConstants.GAME_WIDTH, GameViewConstants.GAME_HEIGHT, settings);\n        \/\/ GUI\n        JFrame mainFrame = new JFrame(\"Snakeses\");\n\/\/ And the rest of the GUI is then created...<\/code><\/pre>\n\n\n\n
Things to note here: The app object contains the relevant application objects as member variables (game, settings, hall of fame). Also the GUI objects (frame, panels) are member variables, but left out from code snippet above since they are not relevant in this post.<\/p>\n\n\n\n
As you can see, the settings are read from the settings file as the very first step of the application launch. Therefore, they are read from the file and available to the rest of the application immediately.<\/p>\n\n\n\n
How about saving the settings? This could have been done in the SettingsPanel<\/code>, but in this implementation it is done also in the SnakesesApp<\/code>. The reason is, that changing some of the settings needs to be reflected in other components of the app. The method SnakesesApp.switchTo<\/code> is called by the SettingsPanel<\/code> when the close button is pressed. The app then switches back to the game view. <\/p>\n\n\n\n
But before that, the app first checks if the settings were changed (isDirty<\/code> is true), and saves the settings. App also instructs the hall of fame object to switch the hall of fame visible to the user, to the corresponding game difficulty level hall of fame data. This is because the game always shows the hall of fame for the current difficulty level only. This is shown in the code snippet below:<\/p>\n\n\n\n
public static void switchTo(final View view) {\n    CardLayout cardLayout = (CardLayout) (mainView.getLayout());\n    if (settings.isDirty) {\n        try {\n            settings.save();                \n            hallOfFame.setCurrentLevel(\n                HallOfFame.Level.fromString(settings.difficulty)\n            );\n\/\/ ...<\/code><\/pre>\n\n\n\n
Other game objects and panels read the settings continuously as they do their things, so they need not to be updated the same way as the hall of fame needs to be. For example, the game panel that draws the snake and the food, uses the light\/dark mode setting in painting the graphics each time the game screen is drawn:<\/p>\n\n\n\n
public void paintComponent(Graphics g) {\n\tsuper.paintComponent(g);\n\tif (settings.mode.equals(\"dark\") && getBackground().equals(Color.WHITE)) {\n\t\tsetBackground(Color.BLACK);\n\t} else if (settings.mode.equals(\"light\") && getBackground().equals(Color.BLACK)) {\n\t\tsetBackground(Color.WHITE);\n\t}\n\/\/ ....<\/code><\/pre>\n\n\n\n
Summarizing, we have now seen:<\/p>\n\n\n\n