Add labeled border child

[SuperRonan]

I am proposing to add labeled border to child windows.

---

Motivation

Child windows rendered with a border (using ImGuiChildFlags_Borders) often need to be labeled.
This can be done using a SeparatorText(label) at the begining, but this is not the most elegant solution.
GUI APIs generaly provide a way to render a labeled border (fieldset in HTML, TitledBorder in java.swing or QGroupBox in Qt to name a few), but I haven't found a way to do it with imgui.
It is possible to construct a labled border with a custom wrapper arround Begin/EndChild() (as mentioned in the comments of #9181, not sure how it interacts with other window decorations), but I think it makes sense for imgui to support this feature "natively".

---

Solution

I propose to add a new child flag to decorate the child with a labled border: ImGuiChildFlags_TopLabel (must be used with ImGuiChildFlags_Borders).
This does not introduce any breaking change.
This is then handled by the backend code for rendering window's border / decoration.

The labeled border depends on several parameters:

• child window name (the one passed to BeginChild(const char* name), not the constructed child name) for the label.
• child window rect (window->Rect())
• the border color is controlled by ImGuiCol_Border like with the classic border.
• The label is rendered with RenderTextEllipsis() (like SeparatorText()) (so indirectly colored with ImGuiCol_Text).
• The border size is set by window->WindowBorderSize (set by style.ChildBorderSize).
• The border can be rounded with window->WindowBorderSize (set by style.ChildBorderSize).
• The label alignment is controlled by Style.SeparatorTextAlign. I think it makes sense to re-use separator control variables here.
• The horizontal label padding is controlled by Style.SeparatorTextPadding.x, same argument as above.
• The vertical label padding is controlled by Style.FramePadding.y, because this is not a separatorn but a frame.
• The spacing (space (in pixel) between the label and the horizontal bars left and right) is controlled by Style.ItemSpacing (same as SeparatorText())

I had to add three members to ImGuiWindow:

• BorderDecoOffset is the vertical offset (in pixel) at which the top border starts.
• LabelOffset and LabelLen to store the label of the child window (Since the window name of the child is some combination of the parent name, name and the id). As noted in the code, there is a little issue where this label is not available at the first frame of the window creation.

I added a helper RenderLabeledFrame() which is essentialy a mashup between DrawList::AddRect() and SeparatorText().
Currently it is only declared in imgui.cpp, but it could be worth declaring it in a header as part of the imgui API.

There are some interaction with other child rendering features:

• background / menu bar rect must adjusted to the new border rect.
• resize handles must adjusted to the new border rect.

API discussion:

One could argue that it is not necessary to add a new flag ImGuiChildFlags_TopLabel to use a bordered label:
If the BeginChild is called with ImGuiChildFlags_Borders and a name with a non empty rendering name (according to FindRenderedTextEnd()), then a labeled border should be used.

ImGui::BeginChild("##Child", ImVec2(0, 0), ImGuiChildFlags_Borders); // Regular child with a plain border
ImGui::BeginChild("Child", ImVec2(0, 0), ImGuiChildFlags_Borders); // Child with a labeled border

The main issue is that this would be a breaking change.

---

Background rendering tweak

I did some tweaks (in de7e90c) to improve the visuals when the child window has a background (or a menu bar).
The issue is best explained visually:

Without tweak.
With tweak.

The background rect is the same as the border rect. But with labled border, there is hole in the border arround the label.
When the border is one pixel thick, the background is in the continuation of the border in the label region, which is less pleasantly looking than when the background is "contained" one pixel below with the tweak.
The solution is to manually crop by one pixel the edges of the background rectange.
A similar tweak is also aplied for the menu bar:

Without tweak.
With tweak.

---

Possible extensions

Here are some ideas for potential improvements I did not include in this PR:

• Collapsing child window:

  Windows can be collapsed, but that requires a title bar (which is currently explicitely disabled for child windows). I think it would make sense to allow child window collapsing, and it would fit well with labled border. When collapsed, only the top border with the label would be shown (essentialy a SeparatorText() with a symbol indicating that it can be opened like a TreeNode()).

• Tootips:

  Tooltips already have a border. It would be possible to decorate the top border with a label (with a vertical alignment forced to zero).

• Header and Footer labels:

  We could add an option to label the top border or (inclusive) the bottom border (with a mirror alignment).

• Using the space in the top border

  SeparatorText() provides an extra_w parameter to reserve some space in the separator bar (and sets the cursor there). Maybe a similar mechanism could be done with labeled border, given that its similarity with SeparatorText().

[ocornut]

Hello,

May I ask if some of the PR description was written aided by an AI?

[SuperRonan]

May I ask if some of the PR description was written aided by an AI?

No, I don't use these tools (neither for coding).

[ocornut]

Thank you. I’ll try to look at this when I have time.