Columns API work

[ocornut]

This thread to discuss the existing Columns() system. They are still a bit confusing at times and not as well supported as other part of the API. Some discussions there:

#124
#85

[ocornut]

OK, so I see a few problems

• In general we need a better definition of columns (sizing policy). Can maybe introduce a ColumnsHeader api that will handle both the nicer display of a header AND passing on sizing policy. Optionally those can also act as button for sorting, passing the sorting information to the user.

• The usage of Separator() within column needs to be tweaked / clarified. Separator currently span all columns, however they only advance the cursor vertically on the column calling them so it is pretty much inconsistent/buggy (workaround is to call Separator on all columns for now).

• On Dale's last issue from thread Optimization question: Is there a way to compute only the "visible" portion of data for submission to ImGui? #124, due to manually clipping the contents of entries that are laid in columns. The problem with the top line bits disappearing is when we do fast forward with SetCursorPosY() we are already within the first column so we are making that cell very big. As we call NextColumn() the cursor resets itself to the "top". One workaround is to get out of columns first.

          ImGui::Columns(1);
          ImGui::CalcListClipping(items_count, items_height, &display_start, &display_end);
          ImGui::SetCursorPosY(ImGui::GetCursorPosY() + display_start * items_height);
          ImGui::Columns(4);
  

Note that this particular case is part of an optimisation to skip entries. A normal small-sized columns display wouldn't have to worry about those calls. It's not terribly complicated but all this smell a bit fishy and confusing (it can be hard to "get" why xx or xx happening) which is a sign that an improvement is probably needed eventually. I'll have to think about it for a bit.

• Also consider the feature of user dragging and re-ordering columns. Shouldn't be too hard to get to work, but will also exacerbate those issues of "are we working on the first column or in the whole set ?", enforcing a clearer approach.

[unpacklo]

What do you mean by "sizing policy"? Are you referring to setting up the column widths so that the window width isn't split evenly amongst the columns?

vs

That kind of a feature would be really nice to have. Most of the time, I do have some sort of idea of how wide the contents of each column should be, so just having a default to initialize to would suffice for me. If the user changes the widths, would be nice to remember their settings maybe? An issue here though might be the columns could be set so that the total width exceeds the window width. Not sure how you handle this currently. Looks like you just end up trying to make the window bigger?

With regard to the column header, sorting would be awesome. I had already been thinking about coming up with my own implementation using the current operations exposed, but it would have been pretty laborious to make happen. Basically, I would have had an array of indices which holds the display order of the column contents. Something like this https://gist.github.com/Roflraging/64c18e50099488837bf5.

Except, of course, the buttons would just be the top of those columns instead of being actual separate buttons. In any case, this would be really convenient to have since I need to do a lot of manual state maintenance right now to achieve this.

Something I'll need to spend more time thinking about is where the display order should live. This might be something that could live on ImGui side and it wouldn't feel too "retained mode" and be a plus for convenience.

[ocornut]

Sizing policy: I haven't thought of the details but probably specifying a mixture of "size in pixels", "% of remaining size" (after size in pixels are consumed) and "fill remaining space".

Columns header:
The sorting itself would still be your responsibility.
Your can currently move the buttons to be in place of the column header, and you'll be closer to final functionality (except it wouldn't look exactly as neat as how it should eventually look). Just replace the "Index" text by a button called "Index" that does what you already do. You can add a "v" or "^" characters to the end of the button label to denote the current active sorting, thought that would be a little cheap looking..*

I would personally compact your sample code quite a bit (I am a bit obsessed with code compaction) using ternary, Etc.

Seeing those big list we should also add a mechanism for alternating a subtle background color to increase readability. So much to do!

(*) we'd probably want to feature stock icons later on.

[emoon]

Would it be possible to also have Tree Items in this?

[ocornut]

That should work already.

[emoon]

Ah, cool :) Thanks!

[unpacklo]

I just saw #129 and having a selection feature like that except for columns would be really convenient.

Right now we have some pretty janky stuff to kind of get that functionality by making column contents buttons and we detect when a button is pressed to do something with that row of data.

[ocornut]

Well in your column header instead of calling Text() you can call Selectable(). You'll still need to do a bit of manual work. An eventual Column Header api will be a little better.

Based on your gist, you can replace

ImGui::Text("Path")

By

if (ImGui::Selectable("Path", comparison == pathCompare))
{
   reverse = (comparison == pathCompare) ? !reverse : false;
   comparison == pathCompare;
}

And you can remove the button and the text at the top, so that's the only thing you'll have.

[unpacklo]

Sorry, I should have been more clear.

The actual functionality I'm looking for is being able to select items in the column and have the entire row be indicated as selected across all the columns. So it's more like the ListBox() function but it operates over multiple columns instead of being restricted to just one column:

        const int cols = 5;
        const int rows = 100;
        static char items[cols][rows][32] = {};
        static bool selected[cols][rows] = {};
        static bool needInit = true;

        if (needInit)
        {
            for (int col = 0; col < cols; ++col)
            {
                for (int row = 0; row < rows; ++row)
                {
                    snprintf(items[col][row], sizeof(items[col][row]), "Col %d, Row %d", col + 1, row + 1);
                }
            }

            needInit = false;
        }

        ImGui::Begin("Column row selection");
        ImGui::Columns(cols);

        for (int col = 0; col < cols; ++col)
        {
            ImGui::Text("Col %d", col + 1);
            ImGui::Separator();

            for (int row = 0; row < rows; ++row)
            {
                if (ImGui::Selectable(items[col][row], &selected[col][row]))
                {
                    memset(selected, 0, sizeof(selected));

                    for (int selectedCol = 0; selectedCol < cols; ++selectedCol)
                    {
                        selected[selectedCol][row] = true;
                    }
                }
            }

            ImGui::NextColumn();
        }

        ImGui::Columns(1);
        ImGui::End();

Or is there some easy way to achieve this row selection functionality with the current API that I'm not aware of?

The actual information I'm looking for is to see which item or row index is currently selected. The GUI indication that something is selected is a nice touch which was made easy to do because of #129 selection!

[ocornut]

I see, you can't exactly do that right at the moment. Only one column will appear "hovered". But your example seems to be a good workaround, and you can simplify it as:

        const int cols = 5;
        const int rows = 100;
        static char items[cols][rows][32] = {};
        static int selected_row = -1;
        static bool needInit = true;

        if (needInit)
        {
            for (int col = 0; col < cols; ++col)
            {
                for (int row = 0; row < rows; ++row)
                {
                    snprintf(items[col][row], sizeof(items[col][row]), "Col %d, Row %d", col + 1, row + 1);
                }
            }

            needInit = false;
        }

        ImGui::Begin("Column row selection");
        ImGui::Columns(cols);

        for (int col = 0; col < cols; ++col)
        {
            ImGui::Text("Col %d", col + 1);
            ImGui::Separator();

            for (int row = 0; row < rows; ++row)
            {
                if (ImGui::Selectable(items[col][row], selected_row == row))
                {
                    selected_row = row;
                }
            }

            ImGui::NextColumn();
        }

        ImGui::Columns(1);
        ImGui::End();

What we can do is make Selectable span all columns, I'll have to see how this is better one. There's a bit of juggling the library may need to do with scissor rectangles.

[unpacklo]

One of the annoying parts about the current workaround is coming up with the label for the Selectable. Because the function takes in just a const char* label and doesn't allow for a format string and varargs, I need to prep the label ahead of time in a buffer myself:

for (int i = displayStart; i < displayEnd; ++i)
{
    char buffer[32];
    snprintf(buffer, sizeof(buffer), "%zu", pack.manifest->bytes[i]);

    if (ImGui::Selectable(buffer, i == selected))
    {
        selected = i;
    }
}

When I would really prefer to be able to do something like this:

for (int i = displayStart; i < displayEnd; ++i)
{
    if (ImGui::Selectable(i == selected, "%zu", pack.manifest->bytes[i]))
    {
        selected = i;
    }
}

I work around this currently with my own function to do the format string printing:

static bool ImGuiSelectable(bool selected, int id, const char *format, ...)
{
    char buffer[1024] = {};
    va_list list;
    va_start(list, format);
    vsnprintf(buffer, sizeof(buffer), format, list);
    va_end(list);

    ImGui::PushID(id);
    bool changed = ImGui::Selectable(buffer, selected);
    ImGui::PopID();

    return changed;
}

I provide the id so I can avoid collisions to keep the Selectable working.

[ocornut]

Hmm yes.. this has nothing to do with columns or the workaround for selectable on columns tho?

The reason I didn't go for a printf style api is because there's a second optional ImVec2 size parameter (default to 0.0f,0.0f = meaning full width, height of text).

Now I could invert the parameter order (the api is very new and if any early adopter used it it won't be too damaging of a change for them) and add two extra variants:

Selectable(bool, const char* fmt, ...)
Selectable(bool_, const char_ fmt, ...)
Selectable(bool, ImVec2, const char* fmt, ...)
Selectable(bool_, ImVec2, const char_ fmt, ...)

It's a bit "meh" but it probably does the job?

[ocornut]

Not sure about that anymore, because Selectable is mimicing the Button/Checkbox apis so inverting the parameter would be a little odd ? I guess TreeNode already follows that pattern though, and the format string are really helpful.

The way I suggest that you can extend the library by declare your own functions in the ImGui namespace (they can be declared/implemented in your own files or imgui_user.*). then you have a consistent syntax from the user's point of view. ImGui::SelectableEx() or whatever fits you best.

[unpacklo]

I definitely don't think its necessary to add in my particular case to the API. The basics are there to let people create convenience functions, as I have.

Just thought I'd give you a short update on some of the column work I've been doing recently. I implemented the sorting and selection as was mentioned earlier in this issue and also hacked up the column header thing we talked briefly about.

You can see some of this in action at http://youtu.be/uZEvcTREKFc. The column header is a separate set of columns and the actual content portion is a child with the same number of columns so I can scroll independently. What I had to do was grab out the offsets from the child content columns and set the header offsets to (nearly) the same values. This is why I can resize the child columns but not the header ones (by clicking the borders).

To get the header to line up with the children, I had to basically just hand tweak the offsets so that they line up, due to the fact that the child eats up some of the window space. You can see the tiny separation between the header and contents columns; about one or two pixels.

Through the process of implementing this, I actually didn't come up against any serious pains. Really, just the header part is a total kludge. I end up grabbing the content column offsets every frame, saving them off and then setting the header offsets the next frame. The other thing I do is I initialize the column offsets on the first frame so that each column has a pleasing width to start with, instead of just splitting the window evenly amongst all the columns.

I don't really have any standalone example code that you can compile, but almost everything in my code is based on snippets mentioned earlier. Nevertheless, I'll see if I can rip out the core that can compile and run independently of my own code.