Add ImPlotStyle::DigitalPadding; add spec demo and docs

epezent · epezent · Sep 30, 2023 · Sep 30, 2023 · Sep 30, 2023 · Oct 2, 2023
commit 56f71697c04e71b1ff78250494626016419cefec
diff --git a/implot.cpp b/implot.cpp
@@ -31,12 +31,13 @@ Below is a change-log of API breaking changes only. If you are using one of the
 When you are not sure about a old symbol or function name, try using the Search/Find function of your IDE to look for comments or references in all implot files.
 You can read releases logs https://github.com/epezent/implot/releases for more details.
 
-- 2023/09/29 (0.17) - ImPlotSpec was made the default and _only_ way of styling plot items. Therefore the following features were removed:
+- 2023/10/02 (0.17) - ImPlotSpec was made the default and _only_ way of styling plot items. Therefore the following features were removed:
                       - SetNextLineStyle, SetNextFillStyle, SetNextMarkerStyle, and SetNextErrorBarStyle have been removed; pass styling variables directly to PlotX functions now with ImPlotSpec
                       - ImPlotCol_Line, ImPlotCol_Fill, ImPlotCol_MarkerOutline, ImPlotCol_MarkerFill, ImPlotCol_ErrorBar have been removed and thus are no longer supported by PushStyleColor.
                         You can use a common ImPlotSpec instance across multiple PlotX calls to emulate PushStyleColor behavior.
                       - ImPlotStyleVar_LineWeight, ImPlotStyleVar_Marker, ImPlotStyleVar_MarkerSize, ImPlotStyleVar_MarkerWeight, ImPlotStyleVar_FillAlpha, ImPlotStyleVar_ErrorBarSize, and ImPlotStyleVar_ErrorBarWeight
                         have been removed and thus are no longer supported by PushStyleVar. You can use a common ImPlotSpec instance across multiple PlotX calls to emulate PushStyleVar behavior.
+                      - ImPlotStyle/ImPlotStyleVar_ DigitalBitGap as renamed to DigitalSpacing; DigitalBitHeight was removed (use ImPlotSpec::Size); DigitalPadding was added for padding from bottom.  
                       - PlotX offset, stride, and flags parameters are now incorporated into ImPlotSpec; specify these variables in the ImPlotSpec passed to PlotX.                    
 - 2023/08/20 (0.17) - ImPlotFlags_NoChild was removed as child windows are no longer needed to capture scroll. You can safely remove this flag if you were using it. 
 - 2023/06/26 (0.15) - Various build fixes related to updates in Dear ImGui internals.
@@ -103,7 +104,7 @@ You can read releases logs https://github.com/epezent/implot/releases for more d
 - 2020/09/07 (0.8)  - Plotting functions which accept a custom getter function pointer have been post-fixed with a G (e.g. PlotLineG)
 - 2020/09/06 (0.7)  - Several flags under ImPlotFlags and ImPlotAxisFlags were inverted (e.g. ImPlotFlags_Legend -> ImPlotFlags_NoLegend) so that the default flagset
                       is simply 0. This more closely matches ImGui's style and makes it easier to enable non-default but commonly used flags (e.g. ImPlotAxisFlags_Time).
-- 2020/08/28 (0.5)  - ImPlotMarker_ can no longer be combined with bitwise OR, |. This features caused unecessary slow-down, and almost no one used it.
+- 2020/08/28 (0.5)  - ImPlotMarker_ can no longer be combined with bitwise OR, |. This features caused unnecessary slow-down, and almost no one used it.
 - 2020/08/25 (0.5)  - ImPlotAxisFlags_Scientific was removed. Logarithmic axes automatically uses scientific notation.
 - 2020/08/17 (0.5)  - PlotText was changed so that text is centered horizontally and vertically about the desired point.
 - 2020/08/16 (0.5)  - An ImPlotContext must be explicitly created and destroyed now with `CreateContext` and `DestroyContext`. Previously, the context was statically initialized in this source file.
@@ -192,6 +193,7 @@ ImPlotStyle::ImPlotStyle() {
     MousePosPadding    = ImVec2(10,10);
     AnnotationPadding  = ImVec2(2,2);
     FitPadding         = ImVec2(0,0);
+    DigitalPadding     = 20;
     DigitalSpacing     = 4;
 
     ImPlot::StyleColorsAuto(this);
@@ -299,7 +301,8 @@ static const ImPlotStyleVarInfo GPlotStyleVarInfo[] =
     { ImGuiDataType_Float, 2, (ImU32)IM_OFFSETOF(ImPlotStyle, MousePosPadding)    }, // ImPlotStyleVar_MousePosPadding
     { ImGuiDataType_Float, 2, (ImU32)IM_OFFSETOF(ImPlotStyle, AnnotationPadding)  }, // ImPlotStyleVar_AnnotationPadding
     { ImGuiDataType_Float, 2, (ImU32)IM_OFFSETOF(ImPlotStyle, FitPadding)         }, // ImPlotStyleVar_FitPadding
-    { ImGuiDataType_Float, 1, (ImU32)IM_OFFSETOF(ImPlotStyle, DigitalSpacing)     }, // ImPlotStyleVar_DigitalBitGap
+    { ImGuiDataType_Float, 2, (ImU32)IM_OFFSETOF(ImPlotStyle, DigitalPadding)     }, // ImPlotStyleVar_DigitalPadding
+    { ImGuiDataType_Float, 1, (ImU32)IM_OFFSETOF(ImPlotStyle, DigitalSpacing)     }, // ImPlotStyleVar_DigitalSpacing
 };
 
 static const ImPlotStyleVarInfo* GetPlotStyleVarInfo(ImPlotStyleVar idx) {
@@ -4954,7 +4957,8 @@ void ShowStyleEditor(ImPlotStyle* ref) {
             ImGui::SliderFloat2("MousePosPadding", (float*)&style.MousePosPadding, 0.0f, 20.0f, "%.0f");
             ImGui::SliderFloat2("AnnotationPadding", (float*)&style.AnnotationPadding, 0.0f, 5.0f, "%.0f");
             ImGui::SliderFloat2("FitPadding", (float*)&style.FitPadding, 0, 0.2f, "%.2f");
-            ImGui::SliderFloat("DigitalSpacing", &style.DigitalSpacing, 0.0f, 20.0f, "%.1f");
+            ImGui::SliderFloat("DigitalPadding", &style.DigitalPadding, 0.0f, 20.0f, "%.1f");
+            ImGui::SliderFloat("DigitalSpacing", &style.DigitalSpacing, 0.0f, 10.0f, "%.1f");
             ImGui::EndTabItem();
         }
         if (ImGui::BeginTabItem("Colors")) {

diff --git a/implot.h b/implot.h
@@ -393,7 +393,8 @@ enum ImPlotStyleVar_ {
     ImPlotStyleVar_MousePosPadding,    // ImVec2, padding between plot edge and interior info text
     ImPlotStyleVar_AnnotationPadding,  // ImVec2, text padding around annotation labels
     ImPlotStyleVar_FitPadding,         // ImVec2, additional fit padding as a percentage of the fit extents (e.g. ImVec2(0.1f,0.1f) adds 10% to the fit extents of X and Y)
-    ImPlotStyleVar_DigitalSpacing,     // float,  digital plots padding gap in pixels
+    ImPlotStyleVar_DigitalPadding,     // float,  digital plot padding from bottom in pixels
+    ImPlotStyleVar_DigitalSpacing,     // float,  digital plot spacing gap in pixels
     ImPlotStyleVar_COUNT
 };
 
@@ -464,7 +465,25 @@ enum ImPlotBin_ {
 };
 
 // Plot item styling specification. Provide these to PlotX functions to override styling, specify
-// offsetting or stride, or set optional flags. 
+// offsetting or stride, or set optional flags. This struct can be used in the following ways:
+//
+// 1. By declaring and defining a struct instance:
+//
+//    ImPlotSpec spec;
+//    spec.LineColor = ImVec4(1,0,0,1);
+//    spec.LineWeight = 2.0f;
+//    spec.Marker = ImPlotMarker_Circle;
+//    spec.Flags = ImPlotItemFlags_NoLegend | ImPlotLineFlags_Segments;
+//    ImPlot::PlotLine("MyLine", xs, ys, 100, spec);
+//
+// 2. Inline using ImProp,value pairs (order does NOT matter):
+//
+//    ImPlot::PlotLine("MyLine", xs, ys, 100, {
+//      ImProp_LineColor, ImVec4(1,0,0,1),
+//      ImProp_LineWeight, 2.0f,
+//      ImProp_Marker, ImPlotMarker_Circle,
+//      ImProp_Flags, ImPlotItemFlags_NoLegend | ImPlotLineFlags_Segments
+//    });
 struct ImPlotSpec {
     ImVec4          LineColor  = IMPLOT_AUTO_COL;       // line color (applies to lines, bar edges, marker edges); IMPLOT_AUTO_COL will use next Colormap color or current item color
     float           LineWeight = 1.0f;                  // line weight in pixels (applies to lines, bar edges, marker edges)
@@ -585,7 +604,8 @@ struct ImPlotStyle {
     ImVec2  MousePosPadding;         // = 10,10   padding between plot edge and interior mouse location text
     ImVec2  AnnotationPadding;       // = 2,2     text padding around annotation labels
     ImVec2  FitPadding;              // = 0,0     additional fit padding as a percentage of the fit extents (e.g. ImVec2(0.1f,0.1f) adds 10% to the fit extents of X and Y)
-    float   DigitalSpacing;          // = 4,      digital plot padding gap in pixels
+    float   DigitalPadding;          // = 20,     digital plot padding from bottom in pixels
+    float   DigitalSpacing;          // = 4,      digital plot spacing gap in pixels
     // style colors
     ImVec4  Colors[ImPlotCol_COUNT]; // Array of styling colors. Indexable with ImPlotCol_ enums.
     // colormap

diff --git a/implot_demo.cpp b/implot_demo.cpp
@@ -1938,6 +1938,52 @@ void Demo_Tables() {
 
 //-----------------------------------------------------------------------------
 
+void Demo_ItemStylingAndSpec() {
+    static ImVec2 data1[20];
+    for (int i = 0; i < 20; ++i) {
+        data1[i].x = i * 1/19.0f;
+        data1[i].y = data1[i].x * data1[i].x;
+    }
+    static ImVec2 data2[20];
+    for (int i = 0; i < 20; ++i) {
+        data2[i].x = i * 1/19.0f;
+        data2[i].y = data2[i].x * data2[i].x * data2[i].x;
+    }
+    if (ImPlot::BeginPlot("##SpecStyling")) {
+        ImPlot::SetupAxes("x","y");
+
+        // Two options for using ImPlotSpec:
+
+        // 1. By declaring and defining a struct instance:
+        ImPlotSpec spec;
+        spec.LineColor = ImVec4(1,1,0,1);
+        spec.LineWeight = 1.0f;
+        spec.FillColor = ImVec4(1,0.5f,0,1);
+        spec.FillAlpha = 0.5f;
+        spec.Marker = ImPlotMarker_Square;
+        spec.Size = 6;
+        spec.Stride = sizeof(ImVec2);
+        spec.Flags = ImPlotItemFlags_NoLegend | ImPlotLineFlags_Shaded;
+        ImPlot::PlotLine("Line 1", &data1[0].x, &data1[0].y, 20, spec);
+
+        // 2. Inline using ImProp,value pairs (order does NOT matter):
+        ImPlot::PlotLine("Line 2", &data2[0].x, &data2[0].y, 20, {
+            ImProp_LineColor, ImVec4(0,1,1,1),
+            ImProp_LineWeight, 1.0f,
+            ImProp_FillColor, ImVec4(0,0,1,1),
+            ImProp_FillAlpha, 0.5f,
+            ImProp_Marker, ImPlotMarker_Diamond,
+            ImProp_Size, 6,
+            ImProp_Stride, sizeof(ImVec2),
+            ImProp_Flags, ImPlotItemFlags_NoLegend | ImPlotLineFlags_Shaded
+        });
+
+        ImPlot::EndPlot();
+    }    
+}
+
+//-----------------------------------------------------------------------------
+
 void Demo_OffsetAndStride() {
     static const int k_circles    = 11;
     static const int k_points_per = 50;
@@ -2328,6 +2374,7 @@ void ShowDemoWindow(bool* p_open) {
             ImGui::EndTabItem();
         }
         if (ImGui::BeginTabItem("Tools")) {
+            DemoHeader("Item Styling and Spec", Demo_ItemStylingAndSpec);
             DemoHeader("Offset and Stride", Demo_OffsetAndStride);
             DemoHeader("Drag Points", Demo_DragPoints);
             DemoHeader("Drag Lines", Demo_DragLines);
@@ -2438,6 +2485,7 @@ void StyleSeaborn() {
     style.PlotPadding      = ImVec2(12,12);
     style.LabelPadding     = ImVec2(5,5);
     style.LegendPadding    = ImVec2(5,5);
+    style.DigitalPadding   = 20;
     style.DigitalSpacing   = 4;
 }
 

diff --git a/implot_items.cpp b/implot_items.cpp
@@ -2689,7 +2689,7 @@ void PlotDigitalEx(const char* label_id, Getter getter, const ImPlotSpec& spec)
                 pixYMax = ImMax(pixYMax, pixY_chPosOffset);
                 ImVec2 pMin = PlotToPixels(itemData1,IMPLOT_AUTO,IMPLOT_AUTO);
                 ImVec2 pMax = PlotToPixels(itemData2,IMPLOT_AUTO,IMPLOT_AUTO);
-                int pixY_Offset = 0; // TODO: previously 20 to accomodate plot mouse cursor label position; add another padding variable? 
+                int pixY_Offset = (int)gp.Style.DigitalPadding;
                 pMin.y = y_axis.PixelMin + (-gp.DigitalPlotOffset                   - pixY_Offset);
                 pMax.y = y_axis.PixelMin + (-gp.DigitalPlotOffset - pixY_0 - pixY_1 - pixY_Offset);
                 //plot only one rectangle for same digital state