Subplots

[epezent]

This PR extends the work of @ozlb's aligned plots #144. It adds a new API for creating both 1D and 2D sublots with automatic alignment along rows and columns. I expect this PR to be a WIP for a few weeks, as I want to make subplots a first-class feature and I have several ImPlotSubplotFlags_ options in mind for them.

Looping in interested parties and regulars: @yaman, @peterwilson136, @Mrgoodbytes13, @arximboldi, @ocornut, @bear24rw, @jvannugteren, @mindv0rtex, @PeterJohnson, @hoffstadt

What features would you like to see in a subplot API? How could this be more useful than plots inside of ImGui tables?

Current API prototype (feel free to try, but very rough at the moment). Usage is a simple a matter of surrounding rows*cols calls to Begin/EndPlot inside of Begin/EndSubplot. Plots are arranged in row-major order. Currently it is not possible to plot out of order (and I don't see an easy path forward for that). IDs are handled behind the scenes, so no need to Push/Pop IDs or use different titles. The ImVe2 size parameter of BeginPlot is ignored when inside of a Subplot context, as the size is determind from the parameter passed to BeginSubplot. Otherwise, everything else is the same as using BeginPlot.

ImGui::Begin("Subplots Test");
if (ImPlot::BeginSubplot("Subplots", 3, 3, ImVec2(800,600))) {
    for (int i = 0; i < 9; ++i) {
        if (ImPlot::BeginPlot("Subplot","X","Y") {
            ...
            ImPlot::EndPlot();
        }
    }
    ImPlot::EndSubplot();
}
ImGui::End();

[yan-zaretskiy]

Two things that come to mind:

• Linked axes, both x and y. I saw it in the AlignedPlots: Y/X axis padding over multiple plots #144, so it's probably already supported.
• Common title. The title string at the top of the subplot grid.

[peterwilson136]

Some things also, (they might be a bit pedantic)

1. Multi line titles and labels for axis
2. Right hand side Y axis labels
3. Control over the scale of the axes, ie, instead of 1+e06, something such as 1m
4. Perhaps this might be a tricky one, but when you use ImPlotAxisFlags_Time, can there be another flag that (if specific days are skipped), the plot continues on as if its the next day from when there was a gap., ie,
   1 2 3 7 8 9 11... but representing specific dates / times on the axis? Edit - This would be for something like hours worked in a week, say mon-fri, sat + sun are skipped so have a continuous x-axis of mon-fri for each week.

[epezent]

@mindv0rtex, I added two flags ImPlotSubplotFlags_LinkRows and ImPlotSubplotFlags_LinkCols that can enable axis linking:

[bear24rw]

One thing that would be super useful for my application is the ability to resize the rows and columns. I currently achieve this in my app by using an invisible button between the plots as demonstrated here.

This currently works "okay" but i have the issue of time alignment if the y ticks change width on one of the plots which this branch aims so solve:

EDIT: Simply using ImPlot::BeginAlignedPlots in my application "just worked" :) The ability for implot to provide the plot resizing feature as a built-in is less important to me now that I can achieve alignment.

[epezent]

Some new features to report:

• titles
• shared legends and items
• draggable splitters

[PeterJohnson]

This looks amazing! Can the split locations be read / initialized? (I have an application where we need to persist the user-edited layout across application restarts).

[epezent]

Yes, that's what I'm planning. It's not currently implemented in full, but:

IMPLOT_API bool BeginSubplots(const char* title_id,
                             int rows,
                             int cols,
                             const ImVec2& size,
                             ImPlotSubplotFlags flags = ImPlotSubplotFlags_None,
                             float* row_sizes = NULL,
                             float* col_sizes = NULL);

You can set row and col sizes by passing arrays as optional args. These are percentages of total plot width/height, so each array sums to 1. If the user manipulates the splitters, these arrays will be updated and returned as an out paramter.