Configuration and Preferences

Relevant source files

The following files were used as context for generating this wiki page:

• sofl/preferences.py
• sofl/main.py
• sofl/proton/proton_manager.py
• sofl/importer/source.py
• sofl/details_dialog.py
• tasklist.md
• sofl/preferences_backup.py

The Configuration and Preferences system provides a centralized dialog for users to manage application settings. Built using GTK4 and LibAdwaita, it allows customization of general behavior, game import sources, Online-Fix parameters, Proton version management, and SteamGridDB integration.

All settings are persisted using Gio.Settings (GSettings), interacting with the application's GSettings schema. The main class, SOFLPreferences, orchestrates the UI and logic, which is structured into several distinct pages for clarity and ease of use.

Core Architecture

The preferences system is encapsulated within the SOFLPreferences class, which inherits from Adw.PreferencesDialog. It is instantiated and presented from the main application when the user triggers the "preferences" action.

Sources: sofl/preferences.py:53-56, sofl/main.py:313-326

Class Structure and Components

The SOFLPreferences class loads its layout from a UI template file and binds class attributes to GTK widgets defined within it. It manages several pages, each dedicated to a specific category of settings.

The following diagram illustrates the main components of the SOFLPreferences dialog and its relationship with other core parts of the application.

Settings Persistence

Configuration is stored via Gio.Settings, which provides a high-level API for GSettings. Most UI controls, particularly Adw.SwitchRow widgets, are directly bound to a GSettings key. This ensures that any change in the UI is automatically saved and vice-versa.

A bind_switches method is used to link a set of setting keys to their corresponding switch widgets.

Sources: sofl/preferences.py:408-416

The table below lists some of the key GSettings keys managed by the preferences dialog.

GSettings Key	UI Widget	Description
exit-after-launch	exit_after_launch_switch	Closes the app after launching a game.
cover-launches-game	cover_launches_game_switch	Allows launching a game by clicking its cover.
force-theme	force_theme_switch	Forces a light or dark theme.
auto-import	auto_import_switch	Automatically imports games on startup.
sgdb	sgdb_switch	Enables/disables SteamGridDB integration.
online-fix-install-path	online_fix_entry_row	The root directory for Online-Fix games.
online-fix-proton-version	online_fix_proton_combo	The specific Proton version to use for Online-Fix games.
online-fix-auto-patch	online_fix_auto_patch_switch	Enables automatic patching for Online-Fix games.

Sources: sofl/preferences.py:328-347, sofl/preferences.py:646-652, sofl/preferences.py:680-686

Preferences Pages

The dialog is organized into multiple pages to group related settings.

General Page

This page contains application-wide settings and "danger zone" actions.

• Behavior Switches: Toggles for application behavior like exit-after-launch.
• Theme: A switch to force a dark or light theme, overriding the system default.
• Danger Zone:
  • Remove All Games: A button to mark all games in the library as removed. This action is reversible via an "Undo" toast notification.
  • Reset App: A button (visible only in development profile) to completely wipe all application data, cache, and configuration.

Sources: sofl/preferences.py:202-203, sofl/preferences.py:426-439, sofl/preferences_backup.py:186-218

Import Sources Page

This section allows users to enable and configure game importers for various platforms like Steam, Lutris, and Heroic.

• Source Detection: For each potential source, the application checks if it is available on the system. If not, the corresponding configuration row is hidden.
• Path Configuration: For sources that require a path (e.g., Steam's data directory), an Adw.ActionRow is provided with a file chooser button.
• Path Resolution: The system attempts to automatically resolve the location of each source. If it fails, a warning icon is displayed, prompting the user to select a valid directory.

The following diagram shows the logic for resolving an import source's location.

Online-Fix Page

This page is dedicated to configuring the launch environment for games that use an "Online-Fix".

• Installation Path: An entry row to specify the directory where Online-Fix games are stored. The default is ~/Games/Online-Fix.
• Proton Version: A combo box (Adw.ComboRow) to select the specific GE-Proton or Proton version to be used for launching these games. The list is populated by available versions found on the system.
• Patching Options:
  • An "Auto-Patch" switch hides or shows manual patch settings.
  • When auto-patch is disabled, users can manually enable specific patches like steam_appid.txt creation or steam_fix_64.dll usage.
  • A field for WINEDLLOVERRIDES is also provided.

Sources: sofl/preferences.py:623-718

Proton Manager Page

The Proton page features a manager for downloading, viewing, and deleting GE-Proton versions directly from within the application. This functionality is handled by the ProtonManager class.

Sources: sofl/preferences.py:1001, tasklist.md:14-26

UI and Functionality

• Installed Versions: An Adw.ExpanderRow lists all Proton versions currently installed in the Steam compatibility tools directory. Each version has a "Delete" button.
• Available Versions: Another Adw.ExpanderRow lists available GE-Proton releases fetched from the GitHub API. Each version shows its name, size, and release date, along with a "Download" button.
• Asynchronous Operations: Fetching available versions and downloading a selected version are performed in a background thread to keep the UI responsive. A spinner is shown during these operations.

Download and Installation Flow

When a user clicks the "Download" button for an available Proton version, a background thread is initiated to handle the download and extraction.

The diagram below illustrates the sequence of events for fetching and displaying available Proton versions.

The download process for a single version follows these steps:

1. The user clicks the download button, which becomes insensitive and shows a progress bar.
2. The download_version method of ProtonManager is called in a new thread.
3. This method downloads the .tar.gz archive, providing progress updates via a callback.
4. The UI callback updates the progress bar in real-time.
5. Once downloaded, the archive is extracted to the Steam compatibility tools directory.
6. Upon completion (or error), the UI is updated, the installed versions list is refreshed, and a toast notification is shown.

Sources: sofl/preferences.py:1432-1481

Conclusion

The preferences system is a comprehensive and user-friendly module that provides extensive control over the application's functionality. It effectively uses GSettings for data persistence and modern LibAdwaita widgets for a clean user experience. Key features like the dynamic Import Sources configuration and the integrated Proton Manager significantly simplify the setup process for Linux gaming, which is a core goal of the SOFL project.

Sources: idea.md:7-19