improved documentation

jkriege2 · Dec 19, 2023 · 2913a9a · 2913a9a
1 parent 83c9803
commit 2913a9a
Show file tree

Hide file tree

Showing 3 changed files with 33 additions and 15 deletions.
diff --git a/lib/jkqtplotter/jkqtpkey.h b/lib/jkqtplotter/jkqtpkey.h
@@ -39,11 +39,13 @@ class JKQTMathText;
 /*! \brief base class for drawing a key (or legend)
     \ingroup jkqtpbaseplotter_elements
 
-    The class JKQTPBaseKey implements the basic layouting and drawing of a key/legend. The basic style properties are defined in JKQTPKeyStyle.
+    The class JKQTPBaseKey implements the basic layouting and drawing of a key/legend.
 
-    The following image shows, which properties of the key may be altered with the style:
+    \section JKQTPBaseKey_Styling Key/Legend Styling
 
-    \image html plot_key.png
+    \copydetails JKQTPKeyStyle
+
+    \note The class JKQTPBaseKey offers setters (slots) and getters for all the properties in the used instance of JKQTPKeyStyle .
 
     \section JKQTPBaseKey_Usage Usage
 
@@ -350,7 +352,7 @@ class JKQTPLOTTER_LIB_EXPORT JKQTPBaseKey: public QObject {
 
 
 /*! \brief concrete class for drawing the main plot key (or legend).
- *         This class reads the key entries fromm the graphs list of its parent JKQTBasePlotter.
+ *         This class reads the key entries from the graphs list of its parent JKQTBasePlotter und references the JKQTPKeyStyle object from JKQTBasePlotterStyle::keyStyle in the parent JKQTBasePlotter.
     \ingroup jkqtpbaseplotter_elements
 
 

diff --git a/lib/jkqtplotter/jkqtpkeystyle.h b/lib/jkqtplotter/jkqtpkeystyle.h
@@ -34,9 +34,17 @@ class JKQTBasePlotterStyle; // forward
 /** \brief Support Class for JKQTBasePlotter, which summarizes all properties that define the visual styling of the key in a JKQTBasePlotter
  *  \ingroup jkqtpplotter_styling_classes
  *
+ *  With JKQTPKeyStyle you can style the appearance of a key/legend:
+ *
  *  \image html plot_key.png
  *
- *  \see JKQTPKey, JKQTBasePlotter, JKQTBasePlotterStyle, \ref jkqtpplotter_styling
+ *  In addition it is possible to set:
+ *    - its visiblility with JKQTPKeyStyle::visible
+ *    - its location within or besides the plot area, using JKQTPKeyStyle::position
+ *    - its overall layout (i.e. how the entries are distributed over the available space), using JKQTPKeyStyle::layout
+ *  .
+ *
+ *  \see JKQTPBaseKey, JKQTBasePlotter, JKQTBasePlotterStyle, \ref jkqtpplotter_styling
  */
 class JKQTPLOTTER_LIB_EXPORT JKQTPKeyStyle  {
         Q_GADGET
@@ -101,9 +109,9 @@ class JKQTPLOTTER_LIB_EXPORT JKQTPKeyStyle  {
         /** \brief distance between two columns of key entries [in units of width of 'X' set in fontName, fontSize] */
         double columnSeparation;
 
-        /** \brief key position */
+        /** \brief key position inside or besides the plot area, see JKQTPKeyPositions for details and examples */
         JKQTPKeyPosition position;
-        /** \brief the key layout */
+        /** \brief the key layout, i.e. how the entries are distributed over the available space, see JKQTPKeyLayout for details and examples */
         JKQTPKeyLayout layout;
 };
 

diff --git a/lib/jkqtplotter/jkqtptools.h b/lib/jkqtplotter/jkqtptools.h
@@ -628,14 +628,22 @@ JKQTPLOTTER_LIB_EXPORT JKQTPKeyPosition String2JKQTPKeyPosition(const QString& p
  * \ingroup jkqtpplottersupprt
  */
 enum JKQTPKeyLayout {
-    JKQTPKeyLayoutOneColumn=0,            /*!< \brief the key consists of one column
-                                               \image html keylayouts/JKQTPKeyLayout_one_column.png */
-    JKQTPKeyLayoutOneRow,                 /*!< \brief the key consists of one row
-                                               \image html keylayouts/JKQTPKeyLayout_one_row.png */
-    JKQTPKeyLayoutMultiColumn,            /*!< \brief the key consists of multiple columns, (top->bottom, top->bottom, ...)
-                                               \image html keylayouts/JKQTPKeyLayout_multi_column.png */
-    JKQTPKeyLayoutMultiRow,               /*!< \brief the key consists of multiple rows (left->right,left->right,...)
-                                               \image html keylayouts/JKQTPKeyLayout_multi_row.png */
+    JKQTPKeyLayoutOneColumn=0,            /*!< \brief the key consists of one column. This may overflow the available space, use JKQTPKeyLayoutMultiColumn or JKQTPKeyLayoutMultiRow if you have many entries!
+                                               \image html keylayouts/JKQTPKeyLayout_one_column.png
+                                               \image html keylayouts/JKQTPKeyLayout_outsidebottom_one_column.png
+                                               \image html keylayouts/JKQTPKeyLayout_outsideright_one_column.png */
+    JKQTPKeyLayoutOneRow,                 /*!< \brief the key consists of one row. This may overflow the available space, use JKQTPKeyLayoutMultiColumn or JKQTPKeyLayoutMultiRow if you have many entries!
+                                               \image html keylayouts/JKQTPKeyLayout_one_row.png
+                                               \image html keylayouts/JKQTPKeyLayout_outsidebottom_one_row.png
+                                               \image html keylayouts/JKQTPKeyLayout_outsideright_one_row.png */
+    JKQTPKeyLayoutMultiColumn,            /*!< \brief the key items are distributed over multiple columns that fill the available space, (top->bottom, top->bottom, ...)
+                                               \image html keylayouts/JKQTPKeyLayout_multi_column.png
+                                               \image html keylayouts/JKQTPKeyLayout_outsidebottom_multi_column.png
+                                               \image html keylayouts/JKQTPKeyLayout_outsideright_multi_column.png */
+    JKQTPKeyLayoutMultiRow,               /*!< \brief the key items are distributed over multiple rows that fill the available space (left->right,left->right,...)
+                                               \image html keylayouts/JKQTPKeyLayout_multi_row.png
+                                               \image html keylayouts/JKQTPKeyLayout_outsidebottom_multi_row.png
+                                               \image html keylayouts/JKQTPKeyLayout_outsideright_multi_row.png */
 
     JKQTPKeyLayoutMax=JKQTPKeyLayoutMultiRow
 };