Add FAQ entry: "How can I make an ImGui window fill the entire viewport?"

[PossiblyAShrub]

This is a fairly common question which we receive on the discord server. I decided that it'd be worth it to add as an FAQ entry.

[ocornut]

I'm currently not happy with the answer being different between master and docking, and this shall act as I remember that we need to standardize some form of access to a standard origin point/size (AT LEAST, add io.DisplayPos). It's been in my mind for a long time. Until then it seems embarrassing to provide such an awkward answer in the FAQ :)

Also:

• This library is called "Dear ImGui"
• Until we move forward, code should follow styling guidelines used by our codebase. e.g. Use ImVec2() constructors.
• There are typos in comments.
• It's an unusually large answer for such a question. Partly because of the master<>docking thing but not only.

I would like to leave it open as a reminder to add a io.DisplayPos and then we can give a short answer to this

Thank you.

[PossiblyAShrub]

Whoops! Sorry about the typos :) I've fixed those, cut down the answer size, and fixed the code style.

This library is called "Dear ImGui"

Not sure where I've implied otherwise? I understand the frustration around people not using the name correctly, and I don't want to add to that.

[ocornut]

Not sure where I've implied otherwise? I understand the frustration around people not using the name correctly, and I don't want to add to that.

When used in sentence/comments (vs actual compiled code) it's better referred to as "Dear ImGui".

Looking at this I realized we should probably just add a examples in the demo to do exactly that. Going to try now!

[ocornut]

Something like that:

// Demonstrate creating a window covering the entire screen/viewport
static void ShowExampleAppFullscreen(bool* p_open)
{
    ImGuiIO& io = ImGui::GetIO();
    static ImGuiWindowFlags flags = ImGuiWindowFlags_NoDecoration | ImGuiWindowFlags_NoMove | ImGuiWindowFlags_NoResize | ImGuiWindowFlags_NoSavedSettings;
    ImGui::SetNextWindowPos(ImVec2(0, 0));
    ImGui::SetNextWindowSize(io.DisplaySize);
    if (ImGui::Begin("Example: Fullscreen window", p_open, flags))
    {
        ImGui::CheckboxFlags("ImGuiWindowFlags_NoBackground", &flags, ImGuiWindowFlags_NoBackground);
        ImGui::CheckboxFlags("ImGuiWindowFlags_NoDecoration", &flags, ImGuiWindowFlags_NoDecoration);
        ImGui::Indent();
        ImGui::CheckboxFlags("ImGuiWindowFlags_NoTitleBar", &flags, ImGuiWindowFlags_NoTitleBar);
        ImGui::CheckboxFlags("ImGuiWindowFlags_NoCollapse", &flags, ImGuiWindowFlags_NoCollapse);
        ImGui::CheckboxFlags("ImGuiWindowFlags_NoScrollbar", &flags, ImGuiWindowFlags_NoScrollbar);
        ImGui::Unindent();
    }
    ImGui::End();
}

Except I am going to introduce io.DisplayPos as always (0.0) on master.

[ocornut]

After quite a deep dive, I now have merged a small chunk of viewport infrastructure into master to be able to solve this problem neatly.

This should work everywhere:

const ImGuiViewport* viewport = ImGui::GetMainViewport();
ImGui::SetNextWindowPos(viewport->Pos);
ImGui::SetNextWindowSize(viewport->Size);

In addition we are exposing a work area:

const ImGuiViewport* viewport = ImGui::GetMainViewport();
ImGui::SetNextWindowPos(viewport->WorkPos);
ImGui::SetNextWindowSize(viewport->WorkSize);

An example called "Fullscreen window" has been added to the Demo, showcasing this with various flags and allowing to choose between work area and main area.

The definition of viewport has been tweaked in order to cater for the future much wanted "no main viewports" feature.

// - Currently represents the Platform Window created by the application which is hosting our Dear ImGui windows.
// - In 'docking' branch with multi-viewport enabled, we extend this concept to have multiple active viewports.
// - In the future we will extend this concept further to also represent Platform Monitor and support a "no main platform window" operation mode.
// - About Main Area vs Work Area:
//   - Main Area = entire viewport.
//   - Work Area = entire viewport minus sections used by main menu bars (for platform windows), or by task bar (for platform monitor).
//   - Windows are generally trying to stay within the Work Area of their host viewport.
struct ImGuiViewport
{
[...]

// Flags stored in ImGuiViewport::Flags
enum ImGuiViewportFlags_
{
    ImGuiViewportFlags_None                     = 0,
    ImGuiViewportFlags_IsPlatformWindow         = 1 << 0,   // Represent a Platform Window
    ImGuiViewportFlags_IsPlatformMonitor        = 1 << 1,   // Represent a Platform Monitor (unused yet)

The idea being that in the future in "no main platform window" mode GetMainViewport() data will redirect to primary monitor data.

As per this PR, I actually don't think we need a FAQ entry for this.

• Because there's now an example and various comments leading to it.
• I realize it's been asked a few times in the past but it's nowhere the amount of importance as other FAQ items.
• If the FAQ gets too crowed it lowers the chance of people reading it. The most striking problem with documentation is not that information is lacking but that it is not structured well enough and that people don't read it. We can only strive to improve the structure (more focus on wiki?) and have redundancy and multiple pointers allowing to find the desired information. Previously the answer to this question was extremely awkward, now it is extremely simple so we made a big step forward.

Although I won't be merging this as is I however must thank you for pushing it toward making this long awaited change, even so little it is bridging a gap that existed. Thank you :)

[ocornut]

For reference here's the current Fullscreen Window demo:

// Demonstrate creating a window covering the entire screen/viewport
static void ShowExampleAppFullscreen(bool* p_open)
{
    static bool use_work_area = true;
    static ImGuiWindowFlags flags = ImGuiWindowFlags_NoDecoration | ImGuiWindowFlags_NoMove | ImGuiWindowFlags_NoResize | ImGuiWindowFlags_NoSavedSettings;

    // We demonstrate using the full viewport area or the work area (without menu-bars, task-bars etc.)
    // Based on your use case you may want one of the other.
    const ImGuiViewport* viewport = ImGui::GetMainViewport();
    ImGui::SetNextWindowPos(use_work_area ? viewport->WorkPos : viewport->Pos);
    ImGui::SetNextWindowSize(use_work_area ? viewport->WorkSize : viewport->Size);

    if (ImGui::Begin("Example: Fullscreen window", p_open, flags))
    {
        ImGui::Checkbox("Use work area instead of main area", &use_work_area);
        ImGui::SameLine();
        HelpMarker("Main Area = entire viewport,\nWork Area = entire viewport minus sections used by the main menu bars, task bars etc.\n\nEnable the main-menu bar in Examples menu to see the difference.");

        ImGui::CheckboxFlags("ImGuiWindowFlags_NoBackground", &flags, ImGuiWindowFlags_NoBackground);
        ImGui::CheckboxFlags("ImGuiWindowFlags_NoDecoration", &flags, ImGuiWindowFlags_NoDecoration);
        ImGui::Indent();
        ImGui::CheckboxFlags("ImGuiWindowFlags_NoTitleBar", &flags, ImGuiWindowFlags_NoTitleBar);
        ImGui::CheckboxFlags("ImGuiWindowFlags_NoCollapse", &flags, ImGuiWindowFlags_NoCollapse);
        ImGui::CheckboxFlags("ImGuiWindowFlags_NoScrollbar", &flags, ImGuiWindowFlags_NoScrollbar);
        ImGui::Unindent();

        if (p_open && ImGui::Button("Close this window"))
            *p_open = false;
    }
    ImGui::End();
}

[PossiblyAShrub]

I understand the choice to not add this as an entry to the FAQ to reduce noise. And with it as an example in the demo window, I have to agree it is the right decision. I am glad that I was able to help improve this area of Dear ImGui.