gui.ui.tab_settings

File:

EuljiroBible/gui/ui/tab_settings.py

Author:

Benjamin Jaedon Choi - https://github.com/saintbenjamin

Affiliated Church:

The Eulji-ro Presbyterian Church [대한예수교장로회(통합) 을지로교회]

Address:

The Eulji-ro Presbyterian Church, 24-10, Eulji-ro 20-gil, Jung-gu, Seoul 04549, South Korea

Telephone:

+82-2-2266-3070

E-mail:

euljirochurch [at] G.M.A.I.L. (replace [at] with @ and G.M.A.I.L as you understood.)

License:

MIT License with Attribution Requirement (see LICENSE file for details); Copyright (c) 2025 The Eulji-ro Presbyterian Church.

Implements the gui.ui.tab_settings.TabSettings class for managing application fonts, overlay behavior, polling, and output path configuration.

class gui.ui.tab_settings.TabSettings(*args, **kwargs)

Bases: QWidget, TabSettingsUI

Settings tab widget for configuring application behavior and overlay display.

This tab provides UI and orchestration for user-adjustable settings such as fonts, theme mode, overlay display configuration, output file path selection, and the polling mechanism that monitors the verse output file.

Most per-feature operations are delegated to TabSettingsLogic, while this class coordinates the Qt timer, overlay window lifecycle, and language refresh.

tr

Translation function for UI labels and messages.

Type:

Callable[[str], str]

app

Qt application instance used for theme changes and global styling.

Type:

QApplication

settings

Shared application settings dictionary (loaded and persisted via ConfigManager).

Type:

dict

verse_path

Path to the verse output file used by polling/overlay logic.

Type:

str

poll_timer

Timer that periodically triggers polling of the verse output file.

Type:

QTimer

refresh_settings_callback

Callback invoked when settings should be refreshed outside of this tab.

Type:

Callable[[], None]

get_poll_enabled

Callback returning whether polling is enabled externally.

Type:

Callable[[], bool]

overlay

Active overlay window instance when enabled; otherwise None.

Type:

QWidget | None

overlay_denied

Flag indicating the user denied overlay usage on single-display setups.

Type:

bool

logic

Backend logic handler for applying UI-driven settings changes.

Type:

TabSettingsLogic

Note

The following callable is intentionally omitted from Attributes to avoid duplicate autodoc entries, as it is already documented as a class method:

• get_main_geometry (Callable[[], QRect]): Callback returning the main window geometry used to determine which screen is treated as the “main” display.

__init__(app, settings, tr, get_poll_enabled_callback=None, get_main_geometry=None, refresh_settings_callback=None)

Initialize the settings tab with application context and user settings.

This sets up the polling timer, installs optional callbacks, initializes the logic backend, and builds the UI.

Parameters:

• app (QApplication) – QApplication instance.

• settings (dict) – Shared settings dictionary.

• tr (Callable[[str], str]) – Translation function for UI labels.

• get_poll_enabled_callback (Callable[[], bool] | None) – Optional callback that returns whether polling is enabled externally.

• get_main_geometry (Callable[[], QRect] | None) – Optional callback that returns the main window geometry used for screen selection logic.

• refresh_settings_callback (Callable[[], None] | None) – Optional callback invoked when settings should be refreshed outside this tab.

change_language(lang_code)

Update all labels and buttons to reflect a new language setting.

This updates visible UI text, persists the selected language in settings, and writes the change through ConfigManager.

Parameters:

lang_code (str) – Language code (e.g., “ko”, “en”).

apply_dynamic_settings()

Apply all dynamic settings through the logic module.

This delegates to TabSettingsLogic to apply the current UI selections to the application and persisted settings.

apply_font_to_children(widget, font)

Apply a font to child widgets recursively.

Parameters:

• widget (QWidget) – Root widget whose children should receive the font.

• font (QFont) – Font to apply.

select_text_color()

Open a color picker dialog to select the display text color.

This delegates to TabSettingsLogic, which updates both UI previews and persisted settings.

select_bg_color()

Open a color picker dialog to select the display background color.

This delegates to TabSettingsLogic, which updates both UI previews and persisted settings.

select_output_path()

Open a file browser dialog to select the verse output path.

This delegates to TabSettingsLogic, which validates and stores the selected path.

apply_polling_settings()

Apply polling settings and restart polling if enabled.

This delegates to TabSettingsLogic to validate the polling interval, update settings, and start/stop the polling timer as needed.

save_poll_interval(parent)

Save the polling interval value from the UI.

This delegates to TabSettingsLogic, which validates the input and persists it.

toggle_theme()

Toggle between dark and light application themes.

This flips the current theme state, applies the stylesheet accordingly, updates the settings dictionary, and persists the change via gui.config.config_manager.ConfigManager.

toggle_overlay()

Toggle the overlay display on or off.

When enabling, this determines the target screen geometry based on the current overlay mode (fullscreen vs resizable), screen count, and the main window geometry. When disabling, it closes the active overlay window.

This method also respects a user-denial flag for single-display setups.

Note

• In fullscreen mode, the overlay prefers a secondary monitor if available.

• In resizable mode, the overlay uses the user-selected display index.

get_main_geometry()

Return the main window geometry.

This is a stub fallback used when no external callback is injected. Call sites should inject a real geometry provider so overlay placement logic can determine the primary screen reliably.

Returns:

Geometry of the main window (fallback is a zero rect).

Return type:

QRect

populate_displays()

Populate the display dropdown with available screen descriptions.

This clears the display combo box and fills it with human-readable display names.

ensure_overlay_on()

Ensure the overlay window is visible, enabling it if necessary.

If overlay usage was previously denied by the user, this does nothing.

poll_file()

Poll the verse output file and control overlay visibility.

If polling is disabled, any active overlay is closed. If polling is enabled, the overlay is shown when the verse output file indicates content should be displayed, and hidden when the output is empty.

This method is intended to be called periodically by poll_timer.

update_presentation_visibility()

Update visibility of the overlay configuration group.

Visibility is determined by the effective polling state, defined as: polling enabled OR the “always show on/off buttons” setting enabled.