spacr.qt.screens.settings_model
===============================

.. py:module:: spacr.qt.screens.settings_model

.. autoapi-nested-parse::

   Bridge between spacr's plain-python default settings and Qt form widgets.

   The existing spacr GUI expresses settings as `{name: (widget_type, options,
   default)}` triples via `spacr.gui_utils.convert_settings_dict_for_gui`.
   Here we consume the same conversion output and materialize each entry as
   a real Qt widget grouped into logical Section boxes based on
   `spacr.settings.categories`.









Module Contents
---------------

.. py:function:: resolve_default_settings(app_key: str) -> Dict[str, Any]

   Return a fresh defaults dict for an app key, mirroring the Tk GUI
   dispatch in gui_core.setup_settings_panel.


.. py:function:: get_categories() -> Dict[str, List[str]]

   Return the {category_name: [setting keys]} mapping.


.. py:function:: get_tooltips() -> Dict[str, str]

   Return per-key tooltip text (spacr.settings.descriptions and .tooltips).


.. py:data:: DOCS_BASE
   :value: 'https://einarolafsson.github.io/spacr/index.html'


.. py:function:: api_docs_url(app_key: str) -> str

   Return the spacr documentation URL for a given app.

   The published docs don't yet split into per-function anchors, so
   we point every setting at the docs landing page. Users can search
   from there and don't hit 404s.


.. py:function:: format_tooltip(text: str, app_key: str) -> str

   Return an HTML tooltip body: description + a docs footer link.

   Kept minimal — Qt auto-detects rich text from any HTML tag, but
   complex containers/styles trip up some builds and the tip renders
   empty. Plain <br> line breaks and a plain <a> footer are the
   format that renders reliably on every platform we've tested.

   Also normalises whitespace so multi-line descriptions from
   spacr.settings.descriptions collapse into a single paragraph.


.. py:function:: plain_tooltip(text: str, app_key: str) -> str

   Same content as `format_tooltip` but plain text — used by the
   hover-follows footer at the bottom of each AppScreen.


.. py:class:: SettingsWidgets(app_key: str, parent: Optional[PySide6.QtWidgets.QWidget] = None)

   Container for the Qt widgets bound to a settings dict.

   Instantiate with an `app_key`; call `.build_sections()` to get a list
   of (section_title, list_of_(label, widget)) tuples to feed into the
   Section widgets on a screen. `.collect()` returns the current settings
   dict after user edits.


   .. py:attribute:: app_key


   .. py:method:: build_sections() -> List[Tuple[str, List[Tuple[str, PySide6.QtWidgets.QWidget]]]]

      Group the settings by category and return one (title, rows)
      tuple per non-empty category, plus a trailing 'Other' section
      for anything not categorized.



   .. py:method:: tooltip_for(key: str) -> str

      Return the HTML-formatted tooltip for a given setting key.



   .. py:method:: plain_tooltip_for(key: str) -> str

      Return the plain-text hint (description + docs URL) for a setting.



   .. py:method:: collect() -> Dict[str, Any]

      Read all widgets and return the current settings dict.



