Skip to content

visualdynamics.gui.preferences

preferences

What the application remembers between launches: the appearance, and whether the plots read in 3-D.

One QSettings under one name, so a preference set on one launch is read on the next; the tests point the store at a temporary folder through QSettings.setPath, so nothing a test chooses reaches the user's own file.

The appearance a window wears is decided in this order, and the order is the point: an explicit statement for this launch (VISUALDYNAMICS_THEME, which --theme sets) beats the remembered choice, and the remembered choice beats what the platform reports — 'system' means follow the platform, which is the default and what theme.system_scheme answers.

Functions:

Name Description
settings

The application's own store: the platform's (a plist on macOS,
remembered_appearance

'system', 'light' or 'dark' — 'system' when nothing was chosen
remember_appearance

Store the choice; 'system' clears it rather than storing a word
remembered_3d

Whether the plots open in 3-D: True, the default (Brandon's
remember_3d

Store the 2D/3D choice.
remembered_creator

The name an exported ESCDF file records as its creator
remember_creator

Store the creator name.
chosen_scheme

The theme to wear now: this launch's statement, else the
wear_appearance

Make the whole application wear the chosen appearance — the
refresh_palettes

Make every widget re-read the application palette.

Functions:

settings 

settings() -> QSettings

The application's own store: the platform's (a plist on macOS, the registry on Windows, a file under ~/.config on Linux), or the file VISUALDYNAMICS_SETTINGS names.

Source code in src/visualdynamics/gui/preferences.py 
36
37
38
39
40
41
42
43
def settings() -> QSettings:
    """The application's own store: the platform's (a plist on macOS,
    the registry on Windows, a file under ~/.config on Linux), or the
    file `VISUALDYNAMICS_SETTINGS` names."""
    path = os.environ.get(STORE)
    if path:
        return QSettings(path, QSettings.Format.IniFormat)
    return QSettings('visualdynamics', 'Visual Dynamics')

remembered_appearance 

remembered_appearance() -> str

'system', 'light' or 'dark' — 'system' when nothing was chosen or the stored word is not one of ours.

Source code in src/visualdynamics/gui/preferences.py 
46
47
48
49
50
def remembered_appearance() -> str:
    """'system', 'light' or 'dark' — 'system' when nothing was chosen
    or the stored word is not one of ours."""
    said = str(settings().value(KEY, 'system')).strip().lower()
    return said if said in APPEARANCES else 'system'

remember_appearance 

remember_appearance(choice: str) -> None

Store the choice; 'system' clears it rather than storing a word that means "nothing chosen".

Source code in src/visualdynamics/gui/preferences.py 
53
54
55
56
57
58
59
60
61
62
63
def remember_appearance(choice: str) -> None:
    """Store the choice; 'system' clears it rather than storing a word
    that means "nothing chosen"."""
    if choice not in APPEARANCES:
        raise ValueError(f'appearance is one of {APPEARANCES}, not {choice!r}')
    store = settings()
    if choice == 'system':
        store.remove(KEY)
    else:
        store.setValue(KEY, choice)
    store.sync()

remembered_3d 

remembered_3d() -> bool

Whether the plots open in 3-D: True, the default (Brandon's call), until the toggle was last left on 2-D (Brandon, 2026-09-28: the choice persists across the MAC and across launches).

Source code in src/visualdynamics/gui/preferences.py 
70
71
72
73
74
75
def remembered_3d() -> bool:
    """Whether the plots open in 3-D: True, the default (Brandon's
    call), until the toggle was last left on 2-D (Brandon, 2026-09-28:
    the choice persists across the MAC and across launches)."""
    said = settings().value(THREE_D_KEY, True)
    return str(said).strip().lower() not in ('false', '0', 'no')

remember_3d 

remember_3d(on: bool) -> None

Store the 2D/3D choice.

Source code in src/visualdynamics/gui/preferences.py 
78
79
80
81
82
def remember_3d(on: bool) -> None:
    """Store the 2D/3D choice."""
    store = settings()
    store.setValue(THREE_D_KEY, bool(on))
    store.sync()

remembered_creator 

remembered_creator() -> str

The name an exported ESCDF file records as its creator (File → Creator Name…), '' when none was set: the writer then records the login name rather than asking, since a file format library must never prompt (2026-09-30).

Source code in src/visualdynamics/gui/preferences.py 
88
89
90
91
92
93
def remembered_creator() -> str:
    """The name an exported ESCDF file records as its creator
    (File → Creator Name…), '' when none was set: the writer then
    records the login name rather than asking, since a file format
    library must never prompt (2026-09-30)."""
    return str(settings().value(CREATOR_KEY, '') or '').strip()

remember_creator 

remember_creator(name: str) -> None

Store the creator name.

Source code in src/visualdynamics/gui/preferences.py 
 96
 97
 98
 99
100
def remember_creator(name: str) -> None:
    """Store the creator name."""
    store = settings()
    store.setValue(CREATOR_KEY, str(name).strip())
    store.sync()

chosen_scheme 

chosen_scheme() -> str

The theme to wear now: this launch's statement, else the remembered choice, else the platform's.

Source code in src/visualdynamics/gui/preferences.py 
103
104
105
106
107
108
109
110
111
112
def chosen_scheme() -> str:
    """The theme to wear now: this launch's statement, else the
    remembered choice, else the platform's."""
    said = os.environ.get(OVERRIDE, '').strip().lower()
    if said in THEMES:
        return said
    remembered = remembered_appearance()
    if remembered in THEMES:
        return remembered
    return system_scheme()

wear_appearance 

wear_appearance(app: Any = None, choice: str | None = None, refresh: bool = True) -> None

Make the whole application wear the chosen appearance — the window chrome, the menus, every native widget — not only the parts this program draws itself.

Qt 6.8 gave QStyleHints.setColorScheme: Light or Dark forces the application's appearance (on macOS, the NSApp appearance), Unknown follows the platform again. Without it the first cut of the menu changed the plots and the scene and left the chrome as the OS had it, and Brandon chose Light and saw nothing change (2026-09-14). The platform then reports the forced scheme, which is what theme.system_scheme and the colorSchemeChanged slot read, so every later repaint agrees. choice defaults to what chosen_scheme would answer: this launch's statement, else the remembered choice, else the platform's.

refresh also makes every widget already built re-read the palette (refresh_palettes) — what a switch of appearance needs. A window being built passes False: its widgets read the palette as they are made, and walking every other top-level widget from its constructor reached windows and web views from before that were closed and waiting to be deleted — a segmentation fault in refresh_palettes on a CI runner (2026-09-27, the Python 3.12 job after public #62).

Source code in src/visualdynamics/gui/preferences.py 
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
def wear_appearance(app: Any = None, choice: str | None = None,
                    refresh: bool = True) -> None:
    """Make the whole application wear the chosen appearance — the
    window chrome, the menus, every native widget — not only the parts
    this program draws itself.

    Qt 6.8 gave `QStyleHints.setColorScheme`: Light or Dark forces the
    application's appearance (on macOS, the NSApp appearance), Unknown
    follows the platform again. Without it the first cut of the menu
    changed the plots and the scene and left the chrome as the OS had
    it, and Brandon chose Light and saw nothing change (2026-09-14).
    The platform then reports the forced scheme, which is what
    `theme.system_scheme` and the `colorSchemeChanged` slot read, so
    every later repaint agrees. `choice` defaults to what
    `chosen_scheme` would answer: this launch's statement, else the
    remembered choice, else the platform's.

    `refresh` also makes every widget already built re-read the palette
    (`refresh_palettes`) — what a switch of appearance needs. A window
    being built passes False: its widgets read the palette as they are
    made, and walking every other top-level widget from its constructor
    reached windows and web views from before that were closed and
    waiting to be deleted — a segmentation fault in `refresh_palettes`
    on a CI runner (2026-09-27, the Python 3.12 job after public #62).
    """
    from PySide6.QtCore import Qt
    from PySide6.QtWidgets import QApplication

    app = app or QApplication.instance()
    if app is None:
        return
    hints = app.styleHints()
    if not hasattr(hints, 'setColorScheme'):
        return                      # an older Qt: the drawn parts only
    if choice is None:
        said = os.environ.get(OVERRIDE, '').strip().lower()
        choice = said if said in THEMES else remembered_appearance()
    hints.setColorScheme({'light': Qt.ColorScheme.Light,
                          'dark': Qt.ColorScheme.Dark}.get(
                              choice, Qt.ColorScheme.Unknown))
    if refresh:
        refresh_palettes(app)

refresh_palettes 

refresh_palettes(app: Any = None) -> None

Make every widget re-read the application palette.

On macOS with Qt 6.11 the application palette follows a color scheme change at once, but widgets already on screen keep the palette they resolved before it — the status bar and the panes stayed light after Brandon switched back to Dark (his screenshot, 2026-09-14), while a fresh window came up right. Setting an empty palette on a widget makes it resolve from its parent and the application again, and leaves WA_SetPalette clear, so the widgets that own a palette on purpose (the tree and the tables, colored by the theme) are skipped and keep theirs.

Source code in src/visualdynamics/gui/preferences.py 
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
def refresh_palettes(app: Any = None) -> None:
    """Make every widget re-read the application palette.

    On macOS with Qt 6.11 the application palette follows a color
    scheme change at once, but widgets already on screen keep the
    palette they resolved before it — the status bar and the panes
    stayed light after Brandon switched back to Dark (his screenshot,
    2026-09-14), while a fresh window came up right. Setting an
    *empty* palette on a widget makes it resolve from its parent and
    the application again, and leaves `WA_SetPalette` clear, so the
    widgets that own a palette on purpose (the tree and the tables,
    colored by the theme) are skipped and keep theirs.
    """
    from PySide6.QtCore import Qt
    from PySide6.QtGui import QPalette
    from PySide6.QtWidgets import QApplication, QWidget

    app = app or QApplication.instance()
    if app is None or not hasattr(app, 'topLevelWidgets'):
        return
    for top in app.topLevelWidgets():
        for widget in (top, *top.findChildren(QWidget)):
            if not widget.testAttribute(Qt.WidgetAttribute.WA_SetPalette):
                widget.setPalette(QPalette())