What's the object ownership model?

[davidgiven]

When I create a control and add it to a hierarchy, apparently the parent control takes ownership of the child and ensures that it gets cleaned up properly.

If I create a window and show it with uiControlShow(), it seems that libui takes ownership of the window. Maybe because it's been reparented to the conceptual screen?

What happens then if I call uiControlHide()? Is the window deparented and therefore mine again, or does libui still keep it? What happens if I then show it once more?

[davidgiven]

Also, when I pass a string into a function, does libui copy the string or is the pointer expected to remain valid while the string is in use?

[ghaberek]

When I create a control and add it to a hierarchy, apparently the parent control takes ownership of the child and ensures that it gets cleaned up properly.

I think this is a combination of libui and the native platform. Controls are based on struct uiControl which includes a function that returns the parent of the control. Each platform has its own unique struct ui[Platform]Control that includes a pointer to the uiControl *parent object: struct uiDarwinControl, struct uiUnixControl, struct uiWindowsControl.

The function uiWindowSetChild() only allows for one child, which should be a container that can contain other children. If you call uiWindowSetChild() more than once, it will destroy the existing child and replace it with the new one. When the window is destroyed it will destroy and free its child if it exists.

Some controls are containers which can contain multiple children. These cases are handled in an implementation-specific way, but they all contain some array type of children and will destroy and free each child when the container is destroyed.

If I create a window and show it with uiControlShow(), it seems that libui takes ownership of the window. Maybe because it's been reparented to the conceptual screen?

uiControlShow() calls the control's specific "show" function stored in struct uiControl which for a window would be uiWindowShow() and for other controls is typically ui[Platform]ControlDefaultShow() which calls the platform-specific "show" function. But uiControlShow() doesn't have anything to do with ownership.

On any platform, a top-level window is owned by the system and the window cleans up itself when it's time to close the application. Part of that involves destroying the window's child which then kicks off a recursive series of child destruction as I described above.

What happens then if I call uiControlHide()? Is the window deparented and therefore mine again, or does libui still keep it? What happens if I then show it once more?

uiControlHide() calls the control's specific "hide" function stored in struct uiControl. For windows on some platforms there's a specific uiWindowHide() but otherwise it just calls the platform-specific "hide" function. But just like uiControlShow(), uiControlHide() doesn't have anything to do with ownership.

Also, when I pass a string into a function, does libui copy the string or is the pointer expected to remain valid while the string is in use?

This seems to be the case, except for instances where libui just passes the string directly to the platform, in which case the platform should be copying the string. Functions that return strings allocate memory for the result which needs to be freed with uiFreeText().

Hope this helps!

[simplexidev]

Also, when I pass a string into a function, does libui copy the string or is the pointer expected to remain valid while the string is in use?

This seems to be the case, except for instances where libui just passes the string directly to the platform, in which case the platform should be copying the string. Functions that return strings allocate memory for the result which needs to be freed with uiFreeText().

So the string has to remain valid unless sent directly to the platform? How do we know when/if?

[ghaberek]

So the string has to remain valid unless sent directly to the platform? How do we know when/if?

Sorry, I see now that my response was a bit vague. Looking through the code, it seems that a copy is always made.

It's just that sometimes libui passes your string pointer directly to the platform so the platform makes its own copy.

I'm not the author so I could be wrong. It'd be worth doing a deeper-dive to ensure string copying is consistent.

[simplexidev]

Ahh, no problem for the confusion. Thanks for the clarification!