Menus API work

[ocornut]

Discussion for an upcoming menu api (still being designed).
If you have ideas or references of menu being implemented in imgui systems please post here!

Some thoughts:

• Menu items typically contains a label, an optional checkmark, an optional local shortcut, an optional global shorcut, an optional link to a submenu, an optional Icon. Menus will be created and developed in a way analogous to the existing patterns in ImGui. API needs to be terse for the common case.
• We should be able to use most types of widgets within a menu. Menu specialize for "menu items" but other widgets should be usable. We should be able to pack sliders or images into a menu.
• We need "menu bars" as the common way to layout menus. Menu bars can be inside individual windows but we need to provide an easy way to have a "top of the screen" menu bar. Also provide easy way to hide menus.
• We want popups menu. They are likely spawned from an event (e.g. clicking a button). This is posing a small problem: if a menu appears upon reacting to an event, we need to design a coding pattern that will allow the menu to stay on after the event has happened.
• Support local keyboard shortcuts, We can use Windows syntax of using & (e.g. "&Save") for convenience.
• Support general "global" shortcuts (e.g. "CTRL+S"). As a design goal of ImGui we want to avoid code and state duplication, so I'd like the ImGui system to handle shortcuts for the user. It will be optional but likely available by default. So the program can have a single entry point for "Save" whether it is activated via clicking in the menu or via pressing the shortcut. The way it would work is that when a global shortcut scheme is activated, the menu functions always notify the user code to develop its content so ImGui can parse and execute the shortcuts as they are declared, but the actual menu is not layed out nor rendered. The shortcut scheme can be disabled on a per-menu/window/global basis. In particular, procedurally generated menus that may have infinite depth will need to be able to disable the global shortcut scheme. In its "closed" state, the system has to be as lightweight as if the user were testing a bunch of shortcuts themselves. The scope of shortcuts can be dependent on factor such as if the parent window is focused so they aren't always "global". The user should also be able to display the label for a shortcut in the menu without letting ImGui handle the shortcut itself.
• Menu navigation may requires ImGui to support more thorough keyboard navigation (currently we only handle TAB and Shift+TAB for navigation).
• Menus needs to scroll if they can't fit in screen.
• Menus needs to position themselves nicely when opened from a parent menu.
• Search in menus like OSX does?

[ocornut]

To mimic similar existing api, the "default" could be something like this:

IMGUI_API bool MenuBegin(const char* label, flags);
IMGUI_API bool Item(const char* label, const char* shortcut = "", bool enabled = true, bool selected = false);
IMGUI_API bool Item(const char* label, const char* shortcut, bool enabled, bool* p_selected);

Using overload of Item(), Not considering extra parameters to MenuBegin yet.

if (ImGui::BeginMenu("&File"))
{
    if (ImGui::Item("&New", "CTRL+N")) {}
    if (ImGui::Item("&Open..", "CTRL+O")) {}
    if (ImGui::Item("&Save", "CTRL+S") {}
    if (ImGui::Item("Save &As..")) {}
    ImGui::Separator();
    if (ImGui::BeginMenu("Recent Files"))
    {
        // iterate items..
        // e.g. if (ImGui::Item("&1. filename.txt")) {}
        ImGui::EndMenu();
    }
    ImGui::Separator();
    if (ImGui::Item("Quit", "CTRL+W")) {}
    ImGui::EndMenu();
}

But something along those lines.
We could potentially store the activated item and have an api to query it back before the end of a menu or later (it would match the char* the user passed), which would allow to write the "execution" code later. If this ends up a useful pattern we can pass around a parameter (id, pointer, etc.) to make the execution code shorter to write. But it make sense to focus on immediate execution as the common case since this is analogous to everything else in ImGui.

The order of parameters makes it a bit tricky if we want to add a printf-format style version of the function, but I imagine this is rather rare (e.g. for filenames in a Recent Files you may want to embed a local shortcut). I don't have a solution I am happy with for that.

[emoon]

I would imagine that Popup menu can work in a similar way:

ImGui::BeginPopupMenu();
if (ImGui::Item("Foo")) {}
ImGui::EndMenu();

[ocornut]

Yes, but you'd need to keep track of the menu lifetime somehow. Pseudo-code:

static bool popup_is_active = false;
if (ImGui::Button("click me"))
    popup_is_active = true;

if (ImGui::BeginPopupMenu(&popup_is_active))
{
    if (ImGui::Item("Foo")) {}
    ImGui::EndMenu();
}

ImGui would keep track of the menu being active. Clicking outside the menu or pressing Escape would deactivate it.

Or better?

if (ImGui::Button("clickme"))
   ImGui::OpenPopupMenu("popup_id");

if (ImGui::BeginPopupMenu("popup_id"))
{
    if (ImGui::Item("Foo")) {}
    ImGui::EndMenu();
}

Except ID can be string / idx / pointer the same way ImGui::TreeNode() allows for all three. Then within a tree we can test for right-click over a node and start a popup that would run for this specific node.

[emoon]

How would it work for mouse? Something like this?

if (ImGui::IsRmbDown())
{
  if (ImGui::BeginPopupMenu("popup_id"))
  {
    if (ImGui::Item("Foo")) {}
    ImGui::EndMenu();
  }
}

I think this is quite common because you may not press an actual control to bring up a Popup menu.

[emoon]

Hum.. I think I like approach 1 better even if I don't have any strong opinions about it.

[ocornut]

Under the above scheme it would be somethng like

if (!ImGui::IsAnyItemActive() && ImGui::IsMouseClicked(2))
{
    ImGui::OpenPopup("foobar");
}
if (ImGui::BeginPopup("foobar"))
{
   ...
}

Which leaves a chance for another item to be active or another more specialized menu to run. Note how the Begin() test is outside of the mouse test block.

With the Open/Begin scheme maybe Begin is a misleading word. It is more analogous to TreeNode() which tests a state (is the tree node open). Or if we keep the bool on the user side as in the first example of my previous post, then we become more analogous to Begin() so it is clearer but the common case requires a little more work. So to reiterate:

static bool menu_opened = false;
if (!ImGui::IsAnyItemActive() && ImGui::IsMouseClicked(2))
{
    menu_opened = true;
}
if (ImGui::BeginPopup(&menu_opened))
{
   ...
}

[emoon]

Alright. That makes sense.

[ocornut]

Add to that: as a user I would like to be able to right-click on any tree node and have popup with a "Copy" button that allows copying the entire node contents to the clipboard (the logging api allows to do that easily). I think it'd be a sensible default in many cases.

Now, ideally I don't want to user to have to add the popup code after every TreeNode call. The user can create their own replacement helper for TreeNode() that does both. Or we can have a dedicated functionality just for this case were TreeNode can automatically spawn a popup with a "Copy" function when right-clicking. Or we can have a system where the user can push a callback to provide a default popup menu. Either way it would need to allow the user code to ignore that menu and create their own. Not sure how to approach that exactly but it is solvable. I guess this is more of a feature of the general/tree API rather than specific to menus.

[ocornut]

FYI i tested and added a demo of the idea of creating popup menus with the existing API.

static bool popup_open = false;
static int selected_fish = -1;
const char* fishes[] = { "Bream", "Mackerel", "Pollock", "Tilefish" };
if (ImGui::Button("Select.."))
{
    popup_open = true;
    ImGui::SetNextWindowPos(ImGui::GetMousePos());
}
ImGui::SameLine();
ImGui::Text(selected_fish == -1 ? "<None>" : fishes[selected_fish]);
if (popup_open)
{
    ImGui::PushStyleVar(ImGuiStyleVar_WindowRounding, 0.0f);
    ImGui::Begin("##Popup", &popup_open, ImGuiWindowFlags_NoMove|ImGuiWindowFlags_NoTitleBar|ImGuiWindowFlags_NoSavedSettings|ImGuiWindowFlags_AlwaysAutoResize);
    if (!ImGui::IsWindowFocused())
        popup_open = false;
    for (size_t i = 0; i < IM_ARRAYSIZE(fishes); i++)
        if (ImGui::Selectable(fishes[i], false))
        {
            selected_fish = i;
            popup_open = false;
        }
    ImGui::End();
    ImGui::PopStyleVar();
}

There's a few problems but it works. I hope by the next version I'll be able to turn that into a 2nd class citizen (with shorter API, automatic positioning, clipping within screen, perhaps ALT+letter shortcuts).

Some of the most immediate problems with this:

• The Begin() call is long.
• Won't position elegantly if size is too big.
• Creating a tooltip (within the popup window or elsewhere, e.g. hovering another window that has code to create a tooltip) will unfocus and remove the popup.

[ocornut]

I added a simple BeginPopup() / EndPopup() API to wrap the pattern above.

static bool popup_open = false;
static int selected_fish = -1;
const char* fishes[] = { "Bream", "Mackerel", "Pollock", "Tilefish" };
if (ImGui::Button("Select.."))
    popup_open = true;
ImGui::SameLine();
ImGui::Text(selected_fish == -1 ? "<None>" : fishes[selected_fish]);

if (popup_open)
{
    ImGui::BeginPopup(&popup_open))
    for (size_t i = 0; i < IM_ARRAYSIZE(fishes); i++)
        if (ImGui::Selectable(fishes[i], false))
        {
            selected_fish = i;
            popup_open = false;
        }
    ImGui::EndPopup();
}