Add is_dark_mode() template function

manual/template_lang.rst

@@ -595,6 +595,10 @@ In `GPM` the functions described in `Single Function Mode` all require an additi
 * ``has_cover()`` -- return ``'Yes'`` if the book has a cover, otherwise the empty string.
 * ``has_extra_files([pattern])`` -- returns the count of extra files, otherwise '' (the empty string). If the optional parameter ``pattern`` (a regular expression) is supplied then the list is filtered to files that match ``pattern`` before the files are counted. The pattern match is case insensitive. See also the functions ``extra_file_names()``, ``extra_file_size()`` and ``extra_file_modtime()``. This function can be used only in the GUI.
 * ``identifier_in_list(val, id_name [, found_val, not_found_val])`` -- treat ``val`` as a list of identifiers separated by commas. An identifier has the format ``id_name:value``. The ``id_name`` parameter is the id_name text to search for, either ``id_name`` or ``id_name:regexp``. The first case matches if there is any identifier matching that id_name. The second case matches if id_name matches an identifier and the regexp matches the identifier's value. If ``found_val`` and ``not_found_val`` are provided then if there is a match then return ``found_val``, otherwise return ``not_found_val``. If ``found_val`` and ``not_found_val`` are not provided then if there is a match then return the ``identifier:value`` pair, otherwise the empty string (``''``).
+* ``is_dark_mode()`` -- returns ``'1'`` if calibre is running in dark mode, ``''`` (the empty string) otherwise. This function can be used in advanced color and icon rules to choose different colors/icons according to the mode. Example::
+
+   if is_dark_mode() then 'dark.png' else 'light.png' fi
+
 * ``is_marked()`` -- check whether the book is `marked` in calibre. If it is then return the value of the mark, either ``'true'`` (lower case) or a comma-separated list of named marks. Returns ``''`` (the empty string) if the book is not marked. This function works only in the GUI.
 * ``language_codes(lang_strings)`` -- return the `language codes <https://www.loc.gov/standards/iso639-2/php/code_list.php>`_ for the language names passed in `lang_strings`. The strings must be in the language of the current locale. ``Lang_strings`` is a comma-separated list.
 * ``list_contains(value, separator, [ pattern, found_val, ]* not_found_val)`` -- (Alias of ``in_list``) Interpreting the value as a list of items separated by ``separator``, evaluate the ``pattern`` against each value in the list. If the ``pattern`` matches any value then return ``found_val``, otherwise return ``not_found_val``. The ``pattern`` and ``found_value`` can be repeated as many times as desired, permitting returning different values depending on the search. The patterns are checked in order. The first match is returned. Aliases: ``in_list()``, ``list_contains()``

src/calibre/utils/formatter_functions.py

@@ -2643,6 +2643,30 @@ class BuiltinHasNote(BuiltinFormatterFunction):
         return '1' if note is not None else ''
 
 
+class BuiltinIsDarkMode(BuiltinFormatterFunction):
+    name = 'is_dark_mode'
+    arg_count = 0
+    category = 'other'
+    __doc__ = doc = _("is_dark_mode() -- Returns '1' if calibre is running "
+                      "in dark mode, '' (the empty string) otherwise. This "
+                      "function can be used in advanced color and icon rules "
+                      "to choose different colors/icons according to the mode. "
+                      "Example: if is_dark_mode() then 'dark.png' else 'light.png' fi ")
+
+    def evaluate(self, formatter, kwargs, mi, locals):
+        # Import these here so that Qt isn't referenced unless this function is used.
+        try:
+            from qt.core import QApplication, Qt
+            from calibre.gui2 import gprefs
+
+            system_is_dark = QApplication.instance().styleHints().colorScheme() == Qt.ColorScheme.Dark
+            palette = gprefs['color_palette']
+            is_dark = palette == 'dark' or (palette == 'system' and system_is_dark)
+            return '1' if is_dark else ''
+        except Exception:
+            only_in_gui_error('is_dark_mode')
+
+
 _formatter_builtins = [
     BuiltinAdd(), BuiltinAnd(), BuiltinApproximateFormats(), BuiltinArguments(),
     BuiltinAssign(),
@@ -2661,7 +2685,7 @@ _formatter_builtins = [
     BuiltinGetLink(),
     BuiltinGetNote(), BuiltinGlobals(), BuiltinHasCover(), BuiltinHasExtraFiles(),
     BuiltinHasNote(), BuiltinHumanReadable(), BuiltinIdentifierInList(),
-    BuiltinIfempty(), BuiltinLanguageCodes(), BuiltinLanguageStrings(),
+    BuiltinIfempty(), BuiltinIsDarkMode(), BuiltinLanguageCodes(), BuiltinLanguageStrings(),
     BuiltinInList(), BuiltinIsMarked(), BuiltinListCountMatching(),
     BuiltinListDifference(), BuiltinListEquals(), BuiltinListIntersection(),
     BuiltinListitem(), BuiltinListJoin(), BuiltinListRe(),