add legendTitleEntry() method to Plot for legend titles

Author: bhaller

QtSLiM/QtSLiMGraphView.cpp

@@ -856,15 +856,23 @@ int QtSLiMGraphView::lineCountForLegend(QtSLiMLegendSpec &legend)
 
     for (const QtSLiMLegendEntry &legendEntry : legend)
     {
-        QString labelString = legendEntry.label;
-        auto existingEntry = displayedLabels.find(labelString);
-        
-        if (existingEntry == displayedLabels.end())
+        if (legendEntry.entry_type == QtSLiM_LegendEntryType::kTitle)
         {
-            // not a duplicate
-            displayedLabels.insert(labelString, 0);
+            // title items do not participate in the duplicate process; they always stand alone
             lineCount++;
         }
+        else
+        {
+            QString labelString = legendEntry.label;
+            auto existingEntry = displayedLabels.find(labelString);
+            
+            if (existingEntry == displayedLabels.end())
+            {
+                // not a duplicate
+                displayedLabels.insert(labelString, 0);
+                lineCount++;
+            }
+        }
     }
 
     return lineCount;
@@ -922,7 +930,11 @@ QSizeF QtSLiMGraphView::legendSize(QPainter &painter)
 
         // incorporate the width of the label into the width of the legend
         QRectF labelBoundingBox = painter.boundingRect(QRect(), Qt::TextDontClip | Qt::TextSingleLine, labelString);
-        double labelWidth = legendGraphicsWidth + legendInteriorMargin + labelBoundingBox.width();
+        double labelWidth = labelBoundingBox.width();
+        
+        // items other than title entries have a graphics box and an interior margin as well
+        if (legendEntry.entry_type != QtSLiM_LegendEntryType::kTitle)
+            labelWidth += legendGraphicsWidth + legendInteriorMargin;
 
         labelWidth = SLIM_SCREEN_ROUND(labelWidth);
 
@@ -983,18 +995,29 @@ void QtSLiMGraphView::drawLegend(QPainter &painter, QRectF legendRect)
 
         // check for duplicate labels, which get uniqued into a single line
         int positionIndex;
-        auto existingEntry = displayedLabels.find(labelString);
+        bool isDuplicate = false;
 
-        if (existingEntry == displayedLabels.end())
+        if (legendEntry.entry_type == QtSLiM_LegendEntryType::kTitle)
         {
-            // not a duplicate
+            // title items do not participate in the duplicate process; they always stand alone
             positionIndex = (nextLinePosition--);
-            displayedLabels.insert(labelString, positionIndex);
         }
         else
         {
-            // duplicate; use the previously determined position
-            positionIndex = existingEntry.value();
+            auto existingEntry = displayedLabels.find(labelString);
+            
+            if (existingEntry == displayedLabels.end())
+            {
+                // not a duplicate
+                positionIndex = (nextLinePosition--);
+                displayedLabels.insert(labelString, positionIndex);
+            }
+            else
+            {
+                // duplicate; use the previously determined position
+                positionIndex = existingEntry.value();
+                isDuplicate = true;
+            }
         }
 
         QRectF entryBox(legendRect.x(), legendRect.y() + positionIndex * (legendLineHeight + legendInteriorMargin), legendRect.width(), legendLineHeight);
@@ -1007,6 +1030,12 @@ void QtSLiMGraphView::drawLegend(QPainter &painter, QRectF legendRect)
         // draw the graphics in graphicsBox
         switch (legendEntry.entry_type)
         {
+        case QtSLiM_LegendEntryType::kTitle:
+        {
+            // use the full entry box for title items
+            labelBox = entryBox;
+            break;
+        }
         case QtSLiM_LegendEntryType::kSwatch:
         {
             QRectF swatchBox = graphicsBox;
@@ -1058,7 +1087,7 @@ void QtSLiMGraphView::drawLegend(QPainter &painter, QRectF legendRect)
         }
 
         // if the entry is not a duplicate, draw the text label
-        if (existingEntry == displayedLabels.end())
+        if (!isDuplicate)
         {
             double labelX = labelBox.x();
             double labelY = labelBox.y() + labelVerticalAdjust;

QtSLiM/QtSLiMGraphView.h

@@ -43,7 +43,8 @@ class QPushButton;
 // Legend support
 enum class QtSLiM_LegendEntryType : int {
     kUninitialized = -1,
-    kSwatch = 0,
+    kTitle = 0,
+    kSwatch,
     kLine,
     kPoint
 };
@@ -81,6 +82,10 @@ class QtSLiMLegendEntry {
     // constructor for an entry that shows a point symbol
     QtSLiMLegendEntry(QString p_label, int p_point_symbol, QColor p_point_color, QColor p_point_border, double p_point_lwd, double p_point_size) :
         label(p_label), entry_type(QtSLiM_LegendEntryType::kPoint), point_symbol(p_point_symbol), point_color(p_point_color), point_border(p_point_border), point_lwd(p_point_lwd), point_size(p_point_size) {};
+    
+    // constructor for an entry that shows a title
+    QtSLiMLegendEntry(QString p_label) :
+        label(p_label), entry_type(QtSLiM_LegendEntryType::kTitle) {};
 };
 
 typedef std::vector<QtSLiMLegendEntry> QtSLiMLegendSpec;

QtSLiM/QtSLiMGraphView_CustomPlot.cpp

@@ -489,6 +489,12 @@ void QtSLiMGraphView_CustomPlot::addLegendSwatchEntry(QString label, QColor colo
     update();
 }
 
+void QtSLiMGraphView_CustomPlot::addLegendTitleEntry(QString label)
+{
+    legend_entries_.emplace_back(label);
+    update();
+}
+
 QString QtSLiMGraphView_CustomPlot::graphTitle(void)
 {
     return title_;

QtSLiM/QtSLiMGraphView_CustomPlot.h

@@ -81,6 +81,7 @@ class QtSLiMGraphView_CustomPlot : public QtSLiMGraphView
     void addLegendLineEntry(QString label, QColor color, double lwd);
     void addLegendPointEntry(QString label, int symbol, QColor color, QColor border, double lwd, double size);
     void addLegendSwatchEntry(QString label, QColor color);
+    void addLegendTitleEntry(QString label);
 
     virtual QString graphTitle(void) override;
     virtual QString aboutString(void) override;

QtSLiM/QtSLiM_Plot.cpp

@@ -104,7 +104,8 @@ EidosValue_SP Plot::ExecuteInstanceMethod(EidosGlobalStringID p_method_id, const
         case gID_axis:                  return ExecuteMethod_axis(p_method_id, p_arguments, p_interpreter);
 		case gID_legendLineEntry:       return ExecuteMethod_legendLineEntry(p_method_id, p_arguments, p_interpreter);
 		case gID_legendPointEntry:      return ExecuteMethod_legendPointEntry(p_method_id, p_arguments, p_interpreter);
-		case gID_legendSwatchEntry:     return ExecuteMethod_legendSwatchEntry(p_method_id, p_arguments, p_interpreter);
+        case gID_legendSwatchEntry:     return ExecuteMethod_legendSwatchEntry(p_method_id, p_arguments, p_interpreter);
+        case gID_legendTitleEntry:      return ExecuteMethod_legendTitleEntry(p_method_id, p_arguments, p_interpreter);
 		case gID_lines:					return ExecuteMethod_lines(p_method_id, p_arguments, p_interpreter);
 		case gID_points:				return ExecuteMethod_points(p_method_id, p_arguments, p_interpreter);
 		case gID_text:					return ExecuteMethod_text(p_method_id, p_arguments, p_interpreter);
@@ -534,7 +535,7 @@ EidosValue_SP Plot::ExecuteMethod_legendPointEntry(EidosGlobalStringID p_method_
         EIDOS_TERMINATION << "ERROR (Plot::ExecuteMethod_legendPointEntry): legendPointEntry() requires the elements of size to be in (0, 1000]." << EidosTerminate(nullptr);
 
     if (!plotview_->legendAdded())
-        EIDOS_TERMINATION << "ERROR (Plot::ExecuteMethod_legendLineEntry): addLegend() must be called before adding legend entries." << EidosTerminate(nullptr);
+        EIDOS_TERMINATION << "ERROR (Plot::ExecuteMethod_legendPointEntry): addLegend() must be called before adding legend entries." << EidosTerminate(nullptr);
 
     plotview_->addLegendPointEntry(label, symbol, color, border, lwd, size);
 
@@ -564,13 +565,31 @@ EidosValue_SP Plot::ExecuteMethod_legendSwatchEntry(EidosGlobalStringID p_method
     QColor color(colorR, colorG, colorB, 255);
 
     if (!plotview_->legendAdded())
-        EIDOS_TERMINATION << "ERROR (Plot::ExecuteMethod_legendLineEntry): addLegend() must be called before adding legend entries." << EidosTerminate(nullptr);
+        EIDOS_TERMINATION << "ERROR (Plot::ExecuteMethod_legendSwatchEntry): addLegend() must be called before adding legend entries." << EidosTerminate(nullptr);
 
     plotview_->addLegendSwatchEntry(label, color);
 
     return gStaticEidosValueVOID;
 }
 
+//	*********************	– (void)legendTitleEntry(string$ label)
+//
+EidosValue_SP Plot::ExecuteMethod_legendTitleEntry(EidosGlobalStringID p_method_id, const std::vector<EidosValue_SP> &p_arguments, EidosInterpreter &p_interpreter)
+{
+#pragma unused (p_method_id, p_arguments, p_interpreter)
+    EidosValue *label_value = p_arguments[0].get();
+    
+    // label
+    QString label = QString::fromStdString(label_value->StringAtIndex_NOCAST(0, nullptr));
+    
+    if (!plotview_->legendAdded())
+        EIDOS_TERMINATION << "ERROR (Plot::ExecuteMethod_legendTitleEntry): addLegend() must be called before adding legend entries." << EidosTerminate(nullptr);
+    
+    plotview_->addLegendTitleEntry(label);
+    
+    return gStaticEidosValueVOID;
+}
+
 //	*********************	– (void)lines(numeric x, numeric y, [string$ color = "red"], [numeric$ lwd = 1.0], [float$ alpha = 1.0])
 //
 EidosValue_SP Plot::ExecuteMethod_lines(EidosGlobalStringID p_method_id, const std::vector<EidosValue_SP> &p_arguments, EidosInterpreter &p_interpreter)
@@ -1017,6 +1036,8 @@ const std::vector<EidosMethodSignature_CSP> *Plot_Class::Methods(void) const
                                   ->AddNumeric_OS("lwd", gStaticEidosValue_Float1)->AddNumeric_OS("size", gStaticEidosValue_Float1)));
         methods->emplace_back(static_cast<EidosInstanceMethodSignature *>((new EidosInstanceMethodSignature(gStr_legendSwatchEntry, kEidosValueMaskVOID))
                                   ->AddString_S("label")->AddString_OS("color", EidosValue_String_SP(new (gEidosValuePool->AllocateChunk()) EidosValue_String("red")))));
+        methods->emplace_back(static_cast<EidosInstanceMethodSignature *>((new EidosInstanceMethodSignature(gStr_legendTitleEntry, kEidosValueMaskVOID))
+                                  ->AddString_S("label")));
         methods->emplace_back(static_cast<EidosInstanceMethodSignature *>((new EidosInstanceMethodSignature(gStr_lines, kEidosValueMaskVOID))
                                   ->AddNumeric("x")->AddNumeric("y")->AddString_OS("color", EidosValue_String_SP(new (gEidosValuePool->AllocateChunk()) EidosValue_String("red")))
                                   ->AddNumeric_OS("lwd", gStaticEidosValue_Float1)->AddFloat_OS("alpha", gStaticEidosValue_Float1)));

QtSLiM/QtSLiM_Plot.h

@@ -69,6 +69,7 @@ class Plot : public EidosDictionaryUnretained
     EidosValue_SP ExecuteMethod_legendLineEntry(EidosGlobalStringID p_method_id, const std::vector<EidosValue_SP> &p_arguments, EidosInterpreter &p_interpreter);
     EidosValue_SP ExecuteMethod_legendPointEntry(EidosGlobalStringID p_method_id, const std::vector<EidosValue_SP> &p_arguments, EidosInterpreter &p_interpreter);
     EidosValue_SP ExecuteMethod_legendSwatchEntry(EidosGlobalStringID p_method_id, const std::vector<EidosValue_SP> &p_arguments, EidosInterpreter &p_interpreter);
+    EidosValue_SP ExecuteMethod_legendTitleEntry(EidosGlobalStringID p_method_id, const std::vector<EidosValue_SP> &p_arguments, EidosInterpreter &p_interpreter);
     EidosValue_SP ExecuteMethod_lines(EidosGlobalStringID p_method_id, const std::vector<EidosValue_SP> &p_arguments, EidosInterpreter &p_interpreter);
     EidosValue_SP ExecuteMethod_points(EidosGlobalStringID p_method_id, const std::vector<EidosValue_SP> &p_arguments, EidosInterpreter &p_interpreter);
     EidosValue_SP ExecuteMethod_text(EidosGlobalStringID p_method_id, const std::vector<EidosValue_SP> &p_arguments, EidosInterpreter &p_interpreter);

QtSLiM/help/SLiMHelpClasses.html

@@ -772,6 +772,8 @@
 <p class="p6">Adds a legend entry with text <span class="s1">label</span> to the plot.<span class="Apple-converted-space">  </span>The entry will be displayed as a point symbol specified by <span class="s1">symbol</span>, <span class="s1">color</span>, <span class="s1">border</span>, <span class="s1">lwd</span>, and <span class="s1">size</span>, mirroring the appearance produced by <span class="s1">points()</span> for the same parameters; see <span class="s1">points()</span> for further details.<span class="Apple-converted-space">  </span>If one or more other legend entries already exist with the same label, the new entry will be drawn on top of the previously set entries for that label (allowing legend entries that display both a line and a point, for example).</p>
 <p class="p5">– (void)legendSwatchEntry(string$ label, [string$ color = "red"])</p>
 <p class="p6">Adds a legend entry with text <span class="s1">label</span> to the plot.<span class="Apple-converted-space">  </span>The entry will be displayed as a swatch drawn in color <span class="s1">color</span>.<span class="Apple-converted-space">  </span>If one or more other legend entries already exist with the same label, the new entry will be drawn on top of the previously set entries for that label (allowing legend entries that display both a line and a point, for example).</p>
+<p class="p5">– (void)legendTitleEntry(string$ label)</p>
+<p class="p6">Adds a legend entry with text <span class="s1">label</span> to the plot.<span class="Apple-converted-space">  </span>The entry will be displayed as a title, left-aligned with no graphical representation (no line, point, or swatch).<span class="Apple-converted-space">  </span>A label of <span class="s1">""</span>, the empty string, is allowed and will produce a blank line in the legend (for spacing).<span class="Apple-converted-space">  </span>Note that title entries always produce their own separate line in the legend; they do not participate in the overdrawing scheme used for other types of legend entries.</p>
 <p class="p5">– (void)lines(numeric x, numeric y, [string$ color = "red"], [numeric$ lwd = 1.0], [float$ alpha = 1.0])</p>
 <p class="p6">Adds line data given by <span class="s1">x</span> and <span class="s1">y</span> to the plot.<span class="Apple-converted-space">  </span>The data will be plotted as a series of connected line segments, following the (<i>x</i>, <i>y</i>) positions given; note that the <span class="s1">x</span> and <span class="s1">y</span> vectors must be the same length.<span class="Apple-converted-space">  </span>The new line data will be plotted on top of any previously added data.</p>
 <p class="p6">The lines will be drawn in color <span class="s1">color</span>, using line width <span class="s1">lwd</span>, with opacity <span class="s1">alpha</span>.<span class="Apple-converted-space">  </span>Alpha values must be in [<span class="s1">0.0</span>, <span class="s1">1.0</span>], where <span class="s1">0.0</span> is fully transparent and <span class="s1">1.0</span> is fully opaque.<span class="Apple-converted-space">  </span>Unlike <span class="s1">points()</span> and <span class="s1">text()</span>, the parameters <span class="s1">color</span>, <span class="s1">lwd</span>, and <span class="s1">alpha</span> must be singletons, since each point (except the two ends) is shared by two line segments; if you wish to vary the color/width/opacity for each line segment, separate calls to <span class="s1">lines()</span> are necessary. <span class="Apple-converted-space">  </span>See also <span class="s1">abline()</span>.</p>

SLiMgui/SLiMHelpClasses.rtf

@@ -6826,6 +6826,16 @@ The
 \f4\fs20 .  If one or more other legend entries already exist with the same label, the new entry will be drawn on top of the previously set entries for that label (allowing legend entries that display both a line and a point, for example).\
 \pard\pardeftab397\li720\fi-446\ri720\sb180\sa60\partightenfactor0
 
+\f3\fs18 \cf2 \'96\'a0(void)legendTitleEntry(string$\'a0label)\
+\pard\pardeftab720\li547\ri720\sb60\sa60\partightenfactor0
+
+\f4\fs20 \cf2 Adds a legend entry with text 
+\f3\fs18 label
+\f4\fs20  to the plot.  The entry will be displayed as a title, left-aligned with no graphical representation (no line, point, or swatch).  A label of 
+\f3\fs18 ""
+\f4\fs20 , the empty string, is allowed and will produce a blank line in the legend (for spacing).  Note that title entries always produce their own separate line in the legend; they do not participate in the overdrawing scheme used for other types of legend entries.\
+\pard\pardeftab397\li720\fi-446\ri720\sb180\sa60\partightenfactor0
+
 \f3\fs18 \cf2 \'96\'a0(void)lines(numeric\'a0x, numeric\'a0y, [string$\'a0color\'a0=\'a0"red"], [numeric$\'a0lwd\'a0=\'a01.0], [float$\'a0alpha\'a0=\'a01.0])\
 \pard\pardeftab720\li547\ri720\sb60\sa60\partightenfactor0
 

SLiMgui/plot.h

@@ -71,6 +71,7 @@ class Plot : public EidosDictionaryUnretained
 	EidosValue_SP ExecuteMethod_legendLineEntry(EidosGlobalStringID p_method_id, const std::vector<EidosValue_SP> &p_arguments, EidosInterpreter &p_interpreter);
 	EidosValue_SP ExecuteMethod_legendPointEntry(EidosGlobalStringID p_method_id, const std::vector<EidosValue_SP> &p_arguments, EidosInterpreter &p_interpreter);
 	EidosValue_SP ExecuteMethod_legendSwatchEntry(EidosGlobalStringID p_method_id, const std::vector<EidosValue_SP> &p_arguments, EidosInterpreter &p_interpreter);
+	EidosValue_SP ExecuteMethod_legendTitleEntry(EidosGlobalStringID p_method_id, const std::vector<EidosValue_SP> &p_arguments, EidosInterpreter &p_interpreter);
 	EidosValue_SP ExecuteMethod_lines(EidosGlobalStringID p_method_id, const std::vector<EidosValue_SP> &p_arguments, EidosInterpreter &p_interpreter);
 	EidosValue_SP ExecuteMethod_points(EidosGlobalStringID p_method_id, const std::vector<EidosValue_SP> &p_arguments, EidosInterpreter &p_interpreter);
 	EidosValue_SP ExecuteMethod_text(EidosGlobalStringID p_method_id, const std::vector<EidosValue_SP> &p_arguments, EidosInterpreter &p_interpreter);

SLiMgui/plot.mm

@@ -100,6 +100,7 @@
 		case gID_legendLineEntry:		return ExecuteMethod_legendLineEntry(p_method_id, p_arguments, p_interpreter);
 		case gID_legendPointEntry:		return ExecuteMethod_legendPointEntry(p_method_id, p_arguments, p_interpreter);
 		case gID_legendSwatchEntry:		return ExecuteMethod_legendSwatchEntry(p_method_id, p_arguments, p_interpreter);
+		case gID_legendTitleEntry:		return ExecuteMethod_legendTitleEntry(p_method_id, p_arguments, p_interpreter);
 		case gID_lines:					return ExecuteMethod_lines(p_method_id, p_arguments, p_interpreter);
 		case gID_points:				return ExecuteMethod_points(p_method_id, p_arguments, p_interpreter);
 		case gID_text:					return ExecuteMethod_text(p_method_id, p_arguments, p_interpreter);
@@ -162,6 +163,15 @@
 	return gStaticEidosValueVOID;
 }
 
+//	*********************	– (void)legendTitleEntry(...)
+//
+EidosValue_SP Plot::ExecuteMethod_legendTitleEntry(EidosGlobalStringID p_method_id, const std::vector<EidosValue_SP> &p_arguments, EidosInterpreter &p_interpreter)
+{
+#pragma unused (p_method_id, p_arguments, p_interpreter)
+	// The user has no way to call this method in SLiMguiLegacy, since createPlot() does not return a Plot object.
+	return gStaticEidosValueVOID;
+}
+
 //	*********************	– (void)lines(...)
 //
 EidosValue_SP Plot::ExecuteMethod_lines(EidosGlobalStringID p_method_id, const std::vector<EidosValue_SP> &p_arguments, EidosInterpreter &p_interpreter)
@@ -256,6 +266,8 @@
 							  ->AddNumeric_OS("lwd", gStaticEidosValue_Float1)->AddNumeric_OS("size", gStaticEidosValue_Float1));
 		methods->emplace_back((EidosInstanceMethodSignature *)(new EidosInstanceMethodSignature(gStr_legendSwatchEntry, kEidosValueMaskVOID))
 							  ->AddString_S("label")->AddString_OS("color", EidosValue_String_SP(new (gEidosValuePool->AllocateChunk()) EidosValue_String("red"))));
+		methods->emplace_back((EidosInstanceMethodSignature *)(new EidosInstanceMethodSignature(gStr_legendTitleEntry, kEidosValueMaskVOID))
+							  ->AddString_S("label"));
 		methods->emplace_back((EidosInstanceMethodSignature *)(new EidosInstanceMethodSignature(gStr_lines, kEidosValueMaskVOID))
 							  ->AddNumeric("x")->AddNumeric("y")->AddString_OS("color", EidosValue_String_SP(new (gEidosValuePool->AllocateChunk()) EidosValue_String("red")))->AddNumeric_OS("lwd", gStaticEidosValue_Float1)->AddFloat_OS("alpha", gStaticEidosValue_Float1));
 		methods->emplace_back((EidosInstanceMethodSignature *)(new EidosInstanceMethodSignature(gStr_points, kEidosValueMaskVOID))