%-------------------------------------------------------------------------------
% seq66 mutes
%-------------------------------------------------------------------------------
%
% \file        seq66 mutes.tex
% \library     Documents
% \author      Chris Ahlstrom
% \date        2020-01-13
% \update      2023-11-06
% \version     $Revision$
% \license     $XPC_GPL_LICENSE$
%
%     Provides a discussion of the MIDI GUI mutes that Seq66 supports.
%
%-------------------------------------------------------------------------------

\section{Seq66 Mutes Master}
\label{sec:mutes_master}

   The \textbf{Mutes} tab provides a global view of all the mute-groups
   in a \textsl{Seq66} MIDI file or global configuration.
   It also provides for manipulation of mute-groups, to supplement
   what can be done via the live grid..

\subsection{Mute Group}
\label{sec:mutes_mute_group}

   A mute-group
   (see \sectionref{subsubsec:concepts_terms_group})
   holds the desired statuses (armed/muted) of all
   of the patterns in a screenset/bank
   (see \sectionref{subsubsec:concepts_terms_bank}).
   By setting up multiple mute-groups,
   one can quickly transition to different arrangements or
   musical themes.

   A mute-group can be associated with a hot-key or MIDI control;
   when the mute-group is selected, the patterns that are armed changes.
   This makes it easy to change what the tune is playing in a big way.
   Mute-groups are \textsl{learned} by

   \begin{enumerate}
      \item Arming all of the desired patterns in the set.
      \item Clicking the \textbf{Learn} ("L") button.
         See \sectionref{subsubsec:introduction_mute_group_learn_button}.
      \item Clicking the keystroke, which is the shifted version
         of the hot-key to arm/mute the pattern corresponding to
         the mute-group number..
         This is accomplished in the default keyboard configuration via the
         \index{auto-shift}
         auto-shift function, which shifts the keystroke automatically
         for group-learn.
   \end{enumerate}

   These steps can also be done via MIDI control.
   More tediously, mute-groups can be edited in a 'mutes' file.

   To learn more about mute-groups, see
   \sectionref{subsubsec:introduction_mute_group_learn_button}, and
   \sectionref{subsubsec:concepts_terms_group}.

\subsection{Mute Master Tab}
\label{sec:mutes_mute_master_tab}

   By themselves, mute groups are not easy to see except by activating
   each mute-group.
   The mute-master (\textbf{Mutes} tab provides a way to view
   them more systematically, as well as assigning names to them.

% TODO: provide a way in the Live Grid, if room allows, to show the
% mute-group name of the activated mutes.

\begin{figure}[H]
   \centering 
   \includegraphics[scale=0.50]{tabs/mutes/mute-master-tab-3.png}
   \caption{Mute Master Tab}
   \label{fig:mutes_master_tab}
\end{figure}

   This diagram shows the \textbf{Mutes} tab after some mute-groups have been
   created.  Mute-groups can be created in the main window's patterns panel,
   but it is difficult to know what each group comprises.
   This tab makes it
   easy to see the layout of the mute-groups, and also allows for some editing
   and live control of the mute-groups.

   Note that the Qt theme shown here (\textsl{kvantum})
   shows that buttons are checkable; other themes often do not show that status.
   Annoying.

\subsection{Mute-Groups Table}
\label{sec:mutes_mute_groups_table}

   The most important user-interface element is the table at the right.
   Here, one can select a mute-group for editing and control.

   \setcounter{ItemCounter}{0}      % Reset the ItemCounter for this list.

   \itempar{Mute-Groups Table}{mutes!table}
   At the right is a table that shows the assigned mute-group keys and
   some information about them:

      \begin{itemize}
         \item \textbf{Group}.
            This column holds the group numbers for each group, ranging from 0
            to 31.  Each row corresponds to a button in the
            \textbf{Mute-Groups} grid.
         \item \textbf{Active}.
            This column shows the number of activated patterns in the
            mute-group.  A zero means the mute-group is inactive.
         \item \textbf{Key}.
            Indicates the keystroke that can be used to activate that
            mute-group.
            By default, these are shifted version of the corresponding
            mute/unmute pattern-slot hotkey.
         \item \textbf{Group Name}.
            Provides a mnemonic name for the mute group.  A feature for the
            future.
      \end{itemize}

   Only the group-name column of This table is editable.
   The user can also edit \texttt{qseq66.mutes} with a text editor, or
   edit \texttt{qseq66.ctrl} to modify the the hot-keys or MIDI controls.

   Click on the desired group.

\subsection{Mute-Groups Buttons}
\label{sec:mutes_mute_groups_buttons}

   Once a mute-group has been selected, its mute-group button is activated.
   Click on the group button (perhaps twice), to be able to add pattern
   mute states via the pattern buttons,
   as an alternative to group-learn.

   \itempar{Mute-Groups}{mutes!groups}
   This grid is always of size \textbf{4 x 8}.
   It represents the maximum of 32
   mute-groups that can be supported by \textsl{Seq66}.
   To start, all group buttons are \textsl{disabled} and
   \textsl{unchecked} (inactive).
   Where a mute-group exists, the button is made \textsl{checked} (active),
   but still disabled.

   Here, the user clicked on mute-group 2, which becomes active in the
   user-interface.
%  (But it is not made active in the patterns panel).
   The \textbf{2} button is also enabled, and can be clicked.

   Clicking once deactivates the button, which potentially flags that
   mute-group for removal.
   Clicking it again reactivates it and
   enables all of the
   buttons in the \textbf{Group Patterns} grid.

   Also, if the \textbf{Triggers} button has been activated,
   then these buttons can activate mute-groups, as if
   activated in the live grid.

\subsection{Group-Patterns Buttons}
\label{sec:mutes_mute_group_patterns_guttons}

   \itempar{Group Patterns}{mutes!patterns}
   Once this grid is enabled by clicking on a mute-groups button,
   each button here can be clicked to add a pattern to
   the mute-group, or remove a pattern from the mute-group.

%  \itempar{Update Group}{mutes!update group}
%  When a change in the mute-group status or the status of one of its patterns
%  is made, this button is enabled.
%  Once clicked, the current mute-group is modified internally,
%  where it can later be saved when \textsl{Seq66}
%  exits, or when the \textbf{Save All} button is clicked.

\subsection{Other Controls}
\label{sec:mutes_mute_other_controls}

   \itempar{Mutes File}{mutes!mutes file}
   The mutes-file read-only field
   shows the base-name of a file into which one can save the
   current-mute group setup, as a way to back up the setup.
   To change this file-name, do so in
   \textbf{Edit / Preferences / Session / .mutes}.

   \itempar{Save File}{mutes!save file}
   This button saves all of the mute-groups to the specified 'mutes' file.
   It is enabled when any change has been made to a mute-group
   or to the check-boxes.
%  and has been registered by pressing the \textbf{Update Group} button.
   If the user has provided a path in the
   \textbf{Edit / Preferences / Session / .mutes} field,
   the path is stripped;
   \textsl{Seq66} must not write configuration information outside of
   the session configuration directory.

%  The file is saved, but is not made official in the
%  'rc' file; one must edit the 'rc' file to use the new 'mutes' file.
%  We might provide a button for that function at some point.

   \itempar{Load File}{mutes!load file}

   This button brings up a dialog to select an external mutes file.
   

   \itempar{Read/Write Format}{mutes!read/write format}
   This section provides the following features, which still need some work:

      \begin{itemize}
         \item \textbf{From MIDI}.
            If checked, the mute-groups are read from the MIDI file, if
            present.  These mute-group override the one from an external
            'mutes' file.
         \item \textbf{From Mutes}.
            If checked, the mute-groups are read from the specified
            'mutes' file, if present and active.
         \item \textbf{Binary}.
            This flag indicates to save the mute-group information in
            binary format, which is the normal format.
            Each mute-group pattern's setting is indicated by a 0 or a 1.
            This is the default format for writing the mute-groups.
         \item \textbf{Hex}.
            In this format, each set of mute-group is written in 8-bit
            hexadecimal format (e.g. "0xff").  This format is useful if the
            user has opted to have large set sizes such as 64 and 96 patterns.
            Not well-supported yet.
         \item \textbf{To MIDI}.
            When a tune is closed, as when \textsl{Seq66} exits, this option
            indicates to write the mute-group information to the
            \textsl{Seq66}-style MIDI file.
         \item \textbf{To Mutes}.
            When a tune is closed, as when \textsl{Seq66} exits, this option
            indicates to write the mute-group information to the 'mutes'
            configuration file (e.g. \texttt{qseq66.mutes}).
            Mute-groups can be written to both.
         \item \textbf{Toggle Only Active}.
            Normally, if a musician turns on a mute-group, then toggles
            other patterns separately, all patterns are turned off
            when the musician selects another mute group.
            If this option is checked, only the patterns that are
            part of the mute-group are toggled; the other patterns remain
            on.
         \item \textbf{Strip If No Mutes}.
            If checked, and there are no defined mute-groups, then
            they are not saved to the song.
      \end{itemize}

   The only time one would want to read/write the mute-groups to a 'mutes' file
   is when one uses standard song sets for all of one's songs.

   \itempar{Triggers}{mutes!trigger mode}
      When activated, this option will enable the \textbf{Mute-Groups} buttons,
      deactive them all, and turn them into standard push-buttons.
      in the \textbf{Triggers} mode, when a button is clicked,
      the corresponding mute-group will be actived.

   \itempar{Zeroes}{mutes!clear all mutes}
      This button will clear every mute group, and replace them with
      mute-group where all patterns are off (zeroed).

      There are a couple of small buttons.
      The first is reserved for expansion.
      The second displays an asterisk when a mute-group or mute setting
      has changed.

%  \itempar{Fill}{mutes!fill mutes}
%     This button will create a set of empty mute-groups.
%     Currently, this alters the current MIDI tune, forcing a prompt to save.
%     This action creates 32 empty mute-groups.
%     If a single mute-group is created in the patterns panel,
%     then only that mute-group is saved.

%  \itempar{Pattern Offset}{mutes!pattern offset}
%     If the user has selected a larger set size that is a multiple of 32, this
%     item is enabled.  It then allows the user to modify patterns with a
%     sequence number greater than 31.  A future feature.
%
%  \itempar{Up/Down Buttons}{mutes!up/down buttons}
%     A future feature to move mute-group around without
%     changing the keystroke for that mute group.

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