documentation

2 files changed, 119 insertions, 5 deletions

diff --git a/muse2/doc/documentation.tex b/muse2/doc/documentation.tex
index 6c12cfa4..d0f17dfe 100644
--- a/muse2/doc/documentation.tex
+++ b/muse2/doc/documentation.tex
@@ -129,6 +129,7 @@
 \newcommand{\shell}[1]{\texttt{\textbf{#1}}}
 \newcommand{\menu}[1]{\textbf{#1}}
 \newcommand{\sym}[1]{\texttt{\camelhyph{#1}}}
+\newcommand{\listing}[1]{\texttt{\camelhyph{#1}}}
 \newcommand{\usym}[1]{\texttt{\underscorehyph{#1}}}
 \newcommand{\file}[1]{\texttt{\camelhyph{#1}}}
 \newcommand{\screenshotwidth}[0]{0.8\textwidth}
@@ -1025,6 +1026,105 @@ This chapter explains how MusE is built internally, and is meant
 to be an aid for developers wanting to quickly start up with MusE.
 For details on \emph{why} stuff is done please refer to the following
 chapter. 
+
+\section{User interface programming}
+We use the QT Toolkit for GUI- and other programming. The \emph{QT-Assistant}
+is an important tool for getting help. Almost everything can be looked
+up there.
+
+GUIs can be either be hardcoded (see \file{arranger.cpp} for an example)
+or can be created using \emph{QT-Designer} (see the dialogs under
+\file{widgets/function_dialogs/} for mostly cleanly-written examples).
+Don't forget to add your \file{cpp}, \file{h} and \file{ui} files to the
+corresponding sections in the \file{CMakeLists.txt}!
+
+Additionally, MusE offers some custom widgets, like menu title items etc.
+Following, there will be a small, unordered list about custom widgets:
+\begin{itemize}
+\item \sym{MusEGui::MenuTitleItem}: Provides a title-bar in a \sym{QMenu}. \\
+      Usage: \listing{someMenu->addAction(new MusEGui::MenuTitleItem(tr("fnord"), someMenu));} \\
+      Defined in \file{widgets/menutitleitem.h}.
+\item \sym{MusEGui::PopupMenu}: Provides a \sym{QMenu}-like menu which
+      can stay open after the user checks a checkable action.
+      Usage: just create a \listing{new PopupMenu( true|false )} instead of
+             a \listing{new QMenu()}. (\listing{true} means 'stay open')
+      Defined in \file{widgets/popupmenu.h}.
+\end{itemize}
+
+
+\section{Configuration} \label{portconfig_sucks}
+Configuration is a bit pesky in MusE in its current state. If you get
+confused by reading this chapter, that's a sign of a sane mind.
+
+There are three kinds of configuration items:
+\begin{itemize}
+\item (1) Global configuration, like coloring schemes, plugin categories, MDI-ness settings
+\item (2) Per-Song configuration, like whether to show or hide certain track types in the arranger
+\item (3) Something in between, like MIDI port settings etc. They obviously actually are
+      global configuration issues (or ought to be), but also obviously must be stored
+      in the song file for portability. (This problem could possibly be solved by
+      the feature proposal in \ref{symbolic_ports}.
+\end{itemize}
+
+\paragraph{Reading configuration}
+\sym{void MusECore::readConfiguration(Xml\&, bool, bool)} in
+\file{conf.cpp} is the central point
+of reading configuration. It is called when MusE is started first
+(by \sym{bool MusECore::readConfiguration()}), and also when a
+song is loaded. \\ %TODO: call paths!
+It can be instructed whether to read MIDI ports (3), global configuration
+and MIDI ports (1+3). Per-Song configuration is always read (2).
+
+When adding new configuration items and thus altering \sym{readConfiguration()},
+you must take care to place your item into the correct section. The code is
+divided into the following sections:
+\begin{itemize}
+\item Global and/or per-song configuration (3)
+\item Global configuration (1)
+\item Code for skipping obsolete entries
+\end{itemize}
+
+The sections are divided by comments (they contain \texttt{----}, so just
+search for them). Please do not just remove code for reading obsolete entries, 
+but always add an appropriate entry to the 'skipping' section in order to
+prevent error messages when reading old configs.
+
+\paragraph{Writing configuration}
+Global configuration is written using the
+\sym{MusEGui::MusE::writeGlobalConfiguration()} functions, while
+per-song-config is written by \sym{MusEGui::MusE::writeConfiguration()}
+(notice the missing \sym{Global}; both implemented in \file{conf.cpp}).
+
+\sym{writeConfiguration} is actually just a subset of the code in
+\sym{writeGlobalConfiguration}. \textbf{Duplicate code!}                  % TODO fix that in the sourcecode.
+
+\paragraph{Song state}
+Additionally to per-song configuration, there is the song's state.
+This contains "the song", that is all tracks, parts and note events,
+together with information about the currently opened windows, their
+position, size, settings and so on. Adding new items here is actually
+pretty painless: Configuration is read and written using
+\sym{MusECore::Song::read} and \sym{::write}, both implemented in
+\file{songfile.cpp}. There are no caveats.
+
+\paragraph{How to add new items}
+When adding global configuration items, then add them into the second
+block ("global configuration") in \sym{readConfiguration} and into
+\sym{writeGlobalConfiguration}.
+
+When adding just-per-song items, better don't bother to touch the
+"configuration" code and just add it to the song's state (there might
+be rare exceptions).
+
+When adding global configuration items, make sure you add them into the
+correct section of \sym{readConfiguration}, and into \sym{writeGlobalConfiguration}.
+
+
+%TODO: how to write config,
+%TODO: song/global stuff
+%TODO: config lesen und schreiben fuer plugingroups
+
+
 \section{User controls and automation}
 \subsection{Handling user input}
 \subsubsection{Plugins and synthesizers}
@@ -1418,7 +1518,21 @@ particular useful for stuff like "which low/high-pass filter type to use").
 
 Maybe make this behaviour default for discrete controllers?
 
-
+\section{Symbolic names for MIDI ports} \label{symbolic_ports}
+MIDI ports shall have a user-defined symbolic name (like "Korg" or "Yamaha DX 7").
+The mapping between these symbolic names and the hardware port (like
+"ALSA midi out port") is stored in the global configuration.
+
+Song files only specify the symbolic names as the ports associated with
+their tracks. No information about physical devices/port names, but only
+symbolic names are stored in the song file.
+
+This resolves the issues mentioned in \ref{portconfig_sucks}, and also
+allows the user to share his pieces with other people: They would only
+have to set up that symbolic-to-hardware mapping once (collisions are
+unlikely, because an equal symbolic name should usually mean the same
+device) and are happy, instead of having to re-map \emph{every} port
+for \emph{every} song.
 
 \end{document}
 
diff --git a/muse2/muse/widgets/popupmenu.h b/muse2/muse/widgets/popupmenu.h
index 1848d3af..d1d863e9 100644
--- a/muse2/muse/widgets/popupmenu.h
+++ b/muse2/muse/widgets/popupmenu.h
@@ -44,14 +44,14 @@ class QMouseEvent;
 class QVariant;
 class QAction;
 class QEvent;
-//class QTimer;
-//class QStandardItemModel;
 
 namespace MusEGui {
 
+/** offers a QMenu-like menu, which stays open once the user
+ *  clicked a checkable action. */
 class PopupMenu : public QMenu
 {
-  Q_OBJECT
+Q_OBJECT
   
     bool _stayOpen;
     #ifndef POPUP_MENU_DISABLE_AUTO_SCROLL  
@@ -75,7 +75,7 @@ class PopupMenu : public QMenu
     PopupMenu(bool stayOpen);
     PopupMenu(QWidget* parent=0, bool stayOpen = false);
     PopupMenu(const QString& title, QWidget* parent = 0, bool stayOpen = false);
-    ///void clear();
+    //void clear();
     QAction* findActionFromData(const QVariant&) const;
     bool stayOpen() const { return _stayOpen; }
     void clearAllChecks() const;