🚧 Removal of GetContentRegionMax(), GetWindowContentRegionMax() etc. (1.91)

[ocornut]

For a long while I have been trying to phase out some functions which I think are confusing, misleading and error-prone.

In 1.91 those three functions are marked obsolete:

• GetContentRegionMax()
• GetWindowContentRegionMin()
• GetWindowContentRegionMax()

They will exist for two more years or disappear immediately if building with IMGUI_DISABLE_OBSOLETE_FUNCTIONS.

I am opening this thread as a recap and to gather questions from users who might have issues.

---

The reason is: You should never need those functions. I believe you can do everything with simply GetCursorScreenPos() and GetContentRegionAvail().

The three functions above were using some weird window-local coordinates space which required user to take account of scrolling and possible padding. In my experience, a good portion of uses of those functions were actually incorrect. And another portion was simply making user code vastly more complicated than needed.

• Instead of: GetWindowContentRegionMax().x - GetCursorPos().x
  You can use: GetContentRegionAvail().x.
• Instead of: GetWindowContentRegionMax().x + GetWindowPos().x
  You can use: GetCursorScreenPos().x + GetContentRegionAvail().x (when called from left edge of window)
• Instead of: GetContentRegionMax()
  You can use: GetContentRegionAvail() + GetCursorScreenPos() - GetWindowPos() (right edge in local coordinates)
• Instead of: GetWindowContentRegionMax().x - GetWindowContentRegionMin().x
  You can use: GetContentRegionAvail() (when called from left edge of window)

I am providing equivalence to facilitate transition, but TL;DR the use of local coordinates has been a mistake done early version of dear imgui and I am trying to correct that. the fact that e.g. the equivalent for GetContentRegionMax() looks abnormally complicated is simply that it replicate the same old value, but this value is rarely meaningful by itself.

If you get rid of local coordinates you will notice your code will be simpler.
You should PROBABLY never call a function like GetWindowPos(). Calling this generally betray that you are using local coordinates unnecessarily.
Absolute coordinates are unambiguous and may be used in ImDrawList functions.

---

The remaining functions using local coordinates are:

• GetCursorPos(), SetCursorPos() -> you can use GetCursorScreenPos(), SetCursorScreenPos() (absolute coordinates)
  • I am not thrilled with that function name but it's been called this way for a long time.
  • When translating (apply a delta) it doesn't matter if you use local or absolute coordinates: SetCursorPos(GetCursorPos() + {100,0}) is the same as SetCursorScreenPos(GetCursorScreenPos() + {100,0}).
• GetCursorStartPos() -> for various reasons this has also been error-prone. Calling GetCursorScreenPos() right after Begin() will get you this position in absolute coordinates.
• The SameLine(float offset_from_start_x) is technically local coordinates and quite misleading.
• The PushTextWrapPos(float wrap_local_pos_x) is also local coordinates.

---

I suggest that you mostly use those two functions:

• GetCursorScreenPos() : current layout position in absolute coordinates.
• GetContentRegionAvail(): difference between lower-right inner edge of window (with padding) and current layout position.

When you use -FLT_MIN or 0.0f in many function taking a width, it essentially uses GetContentRegionAvail().x.
When you use e.g -100.0f to the same function, it essentually uses GetContentRegionAvail().x - 100.0f (with a minimum size)

---

Debug Drawing

If you are not sure what a position or size is... draw it directly on the screen!

ImVec2 some_pos = ImGui::GetCursorScreenPos();
ImGui::GetForegroundDrawList()->AddCircleFilled(my_pos, 3, IM_COL32(255, 0, 0, 255)); // Draw red circle at position

A nice trick is to condition the display of debug primitive to holding a keyboard modifier:

ImVec2 some_pos = ImGui::GetCursorScreenPos();
if (ImGui::GetIO().KeyShift)
    ImGui::GetForegroundDrawList()->AddCircleFilled(my_pos, 3, IM_COL32(255, 0, 0, 255)); // Draw red circle at position

Additionally, The Metrics/Debugger window has tools to visualize various internal state of windows and various rectangles:

[ocornut]

@ElectroidDes instead of thumbing this down please consider that the code in your myriad of issues is too complicated because you are using too many of those functions, and your code would be simpler without them.

[Arugin]

Hello, thanks for clarification. I have a question: you've mentioned what to use instead of GetContentRegionMax(). But what to use instead of GetContentRegionMin()? I guess its ImGui.GetCursorScreenPos() - ImGui.GetWindowPos()?

[GamingMinds-DanielC]

I guess its ImGui.GetCursorScreenPos() - ImGui.GetWindowPos()?

Correct. At least taking the formulas above and solving for GetContentRegionMin() will give that exact result.