%-------------------------------------------------------------------------------
% palettes
%-------------------------------------------------------------------------------
%
% \file        palettes.tex
% \library     Documents
% \author      Chris Ahlstrom
% \date        2020-12-29
% \update      2023-10-25
% \version     $Revision$
% \license     $XPC_GPL_LICENSE$
%
%     Provides a discussion of the MIDI GUI palettes that Seq66
%     supports.
%
%-------------------------------------------------------------------------------

\section{Palettes for Coloring}
\label{sec:palettes}

   Many user-interface elements in \textsl{Seq66} are drawn independently of
   the Qt theme in force, and they have their own coloring.  Also, patterns can
   be colored, and the color is stored (as a color number) in the pattern when
   the tune is saved.
   There are four palettes:

   \begin{itemize}
      \item \textbf{Pattern}.  This palette contains 32 color entries, and each
         can be used to add color to a pattern in the \textsl{Live} grid or in
         the \textsl{Song} editor.  The color of a pattern, if used, is saved
         with the pattern in the MIDI file.
      \item \textbf{Ui}.  This palette contains 24 color entries.  These
         color entries are used in drawing text, backgrounds, grid lines,
         background patterns, drum notes, and more.  These colors each have a
         counterpart that is used with the \texttt{-{}-inverse} option is
         applied to a run of \textsl{Seq66}.
      \item \textbf{Inverse Ui}.  This palette contains 24 color entries.
         These colors are used when the \texttt{-{}-inverse} option is applied
         to a run of \textsl{Seq66}.
      \item \textbf{Brushes}.  This "palette" provides a way to specify the
         fill type for the drawing of notes, the scale (if shown) in the
         pattern editor, and the background sequence (if shown).  It allows the
         user to select solid file, hatching, and some other fill patterns.
   \end{itemize}

   All palettes have default values built into the application.  However, the
   user can also include 'palette' files to change the colors used.  For
   example, the normal colored palette can be changed to a gray-scale palette.
   The name of the palette file is specified in the 'rc' file by lines like the
   following:

   \begin{verbatim}
      [palette-file]
      1     # palette_active
      qseq66-alt-gray.palette
   \end{verbatim}

   If this palette file is active, it is loaded, changing all of the palettes,
   and thus the coloring of \textsl{Seq66}.
   In \sectionref{subsec:palettes_theming}, some weird behavior with
   the \textsl{qt5ct} configuration application and non-Qt-based window managers
   is discussed.

\subsection{Palettes Setup}
\label{subsec:palettes_setup}

   The palette file is a standard \textsl{Seq66} configuration file with a name
   something like \texttt{qseq66.palette}, plus three sections:

   \begin{verbatim}
      [palette]
      [ui-palette]
      [brushes]
   \end{verbatim}

   The first section is the "Pattern" palette; the second section is the
   "Ui" palette, which includes the inverse palette as well; and the third
   section defines brushes for drawing the interiors of some elements.

\subsubsection{Palettes Setup / Pattern}
\label{subsubsec:palettes_setup_pattern}

   The pattern palette is meant for changing the color of the progress
   area of the grid slot.
   This coloring helps in locating a pattern in the grid at a glance.
   The color selected for a pattern is also shown in the Song editor;
   both the name of the pattern and any triggers associated with the pattern
   are painted in the same color.

   Each color is numbered. When a color is applied to the pattern,
   that color number is stored in a SeqSpec in the pattern, and saved
   in the MIDI file.

   The following shows the pattern palette, with some entries elided for
   brevity:

   \begin{verbatim}
      [palette]
       0            "Black" [ 0xFF000000 ]      "White" [ 0xFFFFFFFF ]
       1              "Red" [ 0xFFFF0000 ]      "White" [ 0xFFFFFFFF ]
       2            "Green" [ 0xFF008000 ]      "White" [ 0xFFFFFFFF ]
       3           "Yellow" [ 0xFFFFFF00 ]      "Black" [ 0xFF000000 ]
       4             "Blue" [ 0xFF0000FF ]      "White" [ 0xFFFFFFFF ]
       ...            ...       ...             ...       ...
      29      "Dark Violet" [ 0xFF9400D3 ]      "Black" [ 0xFF000000 ]
      30       "Light Grey" [ 0xFF778899 ]      "Black" [ 0xFF000000 ]
      31        "Dark Grey" [ 0xFF2F4F4F ]      "Black" [ 0xFF000000 ]
project.
   \end{verbatim}

   The names are color names, and these names are what show up in the popup
   color menus for the pattern buttons in the \textsl{Live} grid.
   The colors on the left are the background colors, and the colors on the
   right are the foreground colors, which are chosen for contrast with the
   background.  The colors are in \texttt{\#AARRGGB} format, with the "\#"
   replaced by "0x" because "\#" starts a comment in \textsl{Seq66}
   configuration files.  Note that all the alpha values are "FF" (opaque); we
   have not yet experimented with changing them.
   Lastly, only 32 entries are accepted.

\subsubsection{Palettes Setup / Ui and Inverse Ui}
\label{subsubsec:palettes_setup_ui}

   The "UI palette" applies to other elements drawn by \textsl{Seq66}:
   foreground lines, background paint that can differ between various
   backgrounds, text colors that can differ between slot, time-panels,
   the data panel, and the Song editor's name panel.
   
   If the user has chosen a particular Qt theme or has applied a
   style-sheet, a palette can be created to match.
   There are a couple of style-sheet/palette pairs in the
   \texttt{data/samples} directory.

   The following shows the pattern and song palette,
   with some entries elided for brevity:

   \begin{verbatim}
      [ui-palette]
       0       "Foreground" [ 0xFF000000 ]  "Foreground" [ 0xFFFFFFFF ]
       1       "Background" [ 0xFFFFFFFF ]  "Background" [ 0xFF000000 ]
       2            "Label" [ 0xFF000000 ]       "Label" [ 0xFFFFFFFF ]
       3        "Selection" [ 0xFFFFA500 ]   "Selection" [ 0xFFFF00FF ]
       4             "Drum" [ 0xFFFF0000 ]        "Drum" [ 0xFF000080 ]
             ...            ...       ...        ...       ...
      29       "Slots Text" [ 0xFF000000 ]  "Slots Text" [ 0xFFFFFFFF ]
      30          "Extra 1" [ 0xFF000000 ]     "Extra 1" [ 0xFFFFFFFF ]
      31          "Extra 2" [ 0xFF000000 ]     "Extra 2" [ 0xFFFFFFFF ]
   \end{verbatim}

   Here, the names are feature names, not color names.  The first color is the
   normal color, and the second color is the inverse color.  Only 32 entries
   are supported. The numbers have no meaning except to order the colors.

\subsubsection{Palettes Setup / Brushes}
\label{subsubsec:palettes_setup_brushes}

   The last "palette" is small, allowing the fill-pattern of a few pattern-editor
   items to be changed.

   \begin{verbatim}
      [brushes]
      empty = solid              # preferred
      note = lineargradient      # default
      scale = dense3
      backseq = dense2
   \end{verbatim}

   On the left of the equals sign is the item than can be filled, and on the
   right side is the \textsl{Qt} brush to be used.  The defaults for most are
   solid fill.

   The entry \texttt{empty} isn't too useful; best to leave it set to 'solid'.
   The entry \texttt{note} affects the fill of normal/selected notes.
   The best values are either 'lineargradient' (the default) or 'solid'.
   The entry \texttt{scale} affects the fill for the piano roll scale.  The
   hatching used here makes it easier to recognize that the scale is just there
   for orientation.
   The entry \texttt{backseq} affects the fill of the background sequence.  The
   hatching used here helps further distinguish the real notes from the
   background notes.

\subsection{Palettes Summary}
\label{subsec:palettes_summary}

   There are some obvious enhancements to this scheme, including increasing the
   number of palette items, synchronizing the palette with the current desktop
   them semi-automatically, and providing a user interface to drag-and-drop
   colors.

\subsection{Theming}
\label{subsec:palettes_theming}

   Theming for a mix of \textsl{Qt} and \textsl{Gtk-N} applications can be a
   bit tricky.
   The \textsl{qt5ct} application helps in obtaining nicely rendered
   widgets, though some combinations have visibility issues.

\subsubsection{Qt5ct}
\label{subsubsec:palettes_theming_qt5ct}

   The \textsl{qt5ct} configuration application can be used to select installed
   \textsl{Qt5} themes.

   When using a non-Qt-based window manager or desktop manager, such as our
   favorite, \textsl{Fluxbox}, in conjunction with \textsl{GTK+} themes,
   there can be issues on some \textsl{Linux} distros.

   First, if using a Gtk theme setter (e.g. \textsl{gtk-chtheme}
   or \textsl{lxappearance}),
   one needs to
   use \textsl{qt5ct} to set Qt to work with Gtk themes.
   For this to work well, use this setting in the \texttt{.bashrc} or
   \texttt{.profile} file:

   \begin{verbatim}
      export QT_QPA_PLATFORMTHEME=gtk2
   \end{verbatim}

   Otherwise some GUI elements might be difficult to see.
   If not, use the following setting:

   \begin{verbatim}
      export QT_QPA_PLATFORMTHEME=qt5ct
   \end{verbatim}

   Another option is to provide an executable script like the following,
   giving it a name such as \texttt{dseq66}
   (for a dark themed \textsl{Seq66}) to
   distinguish it from the normal-themed \texttt{qseq66}.

   \begin{verbatim}
      #!/bin/sh
      # Use dark coloring on qseq66, as we have configured in qt5ct.
      QT_QPA_PLATFORMTHEME=qt5ct qseq66
   \end{verbatim}

   One might still encounter the issue that, with a Gtk theme, applications
   take about 20 to 30 seconds to start up!

   Another issue is that some Qt themes might upset the sizing of button or
   text.

   Also see the style-sheet discussion in
   \sectionref{sec:configuration}.

\subsubsection{Kvantum}
\label{subsubsec:palettes_theming_kvantum}

   The \textsl{Kvantum} theming engine uses SVG to draw theme elements.
   It has a number interesting themes. Once installed,
   the \texttt{kvantum} and
   the \texttt{kvantum-dark}
   styles can be selected in \textsl{qt5ct}.

   These styles provide a number of themes that can be
   accessed via the \textsl{kvantummanager} application.
   Some nice \textsl{Kvantum} themes are \texttt{KvCurves},
   \texttt{KvCyan},
   \texttt{KvOxygen}, and
   \texttt{KvYaru}.

%-------------------------------------------------------------------------------
% vim: ts=3 sw=3 et ft=tex
%-------------------------------------------------------------------------------
