Add button_image_pos support for flat buttons

[idrassi]

Closes #226.

This adds the button_image_pos() API proposed in #226 so button_flat() and button_flatgle() can optionally render text relative to their image, while preserving the current image-only behavior unless the new API is explicitly used.

The change introduces the shared gui_pos_t enum in guictx.hxx together with the public button_image_pos() function, and updates the GTK, Windows, and macOS backends to render flat-button text at the requested image position. Flat-toggle alternate text and image handling stays synchronized with the toggle state.

As requested in review, the image-position enum used by both gui and osgui now lives in guictx.hxx, and the native backends no longer include high-level gui headers to access button-specific types.

The macOS implementation also includes the AppKit type fix needed for the new image-position helper to build cleanly with Xcode.

The Windows implementation also includes follow-up fixes required by this feature: the Win32 flat-button text drawing path, tooltip clearing for image-only flat buttons, explicit redraw on flat-toggle state changes, and sizing hardening so flat toggles reserve enough space for both states under custom padding.

The GuiHello demos were updated to cover the new behavior. The Buttons page now exercises ekGUI_POS_TOP, and the Button padding page now covers flat toggles with button_image_pos(), alternate text/image states, and zero/high padding.

Below cross-platform GuiHello screenshots for the updated behavior:

macOS

Windows

Linux Ubuntu 24.04

[frang75]

This implementation looks great. It's clear you have a firm grasp of the NAppGUI architecture. Before merging:

• I have pending changes requested by sponsors that may conflict with these. I need to prioritize these changes.

• Please correct the comments.

• I need to take down the branch first to compile and test it in the NAppGUI CI/CD.

• Once everything is OK, I will merge it and include it in the official NAppGUI documentation.

[idrassi]

Thank you for the review and for the guidance on the gui/osgui boundary. I addressed the requested changes in follow-up commit. I also rechecked the updated branch on macOS, Windows and Linux after this change set.
I’ve also updated the PR description to reflect the shared gui_pos_t change.

Concerning the NAppGUI architecture, I got help in the beginning from https://deepwiki.com/frang75/nappgui_src but I found some issues in it and so I ended up creating a more accurate documentation: https://idrassi.github.io/nappgui_src/site/index.html

This documentation is in a dedicated branch in my fork: https://github.com/idrassi/nappgui_src/tree/docs_html_site/docs

I can create a PR for it if you think it can be helpful to the project

[frang75]

@idrassi

Incredible! I'm so glad to see the great work you're doing with the SDK. As you know, the NAppGUI documentation is currently only "user-level." The architecture isn't documented.

I'll try to merge my changes as soon as possible to merge this pull request and make your implementation available to everyone.

Thank you again for your cooperation.

[frang75]

@idrassi
I'm reviewing the PR and making some minor refactorings, taking advantage of some native support included in the latest GroupBox. In GTK, I see that the underline on CheckBox/RadioButton shortcuts has been lost. The underline should always be visible (without needing to press ALT). I know it's a GTK feature, but some production projects require the shortcut to always be visible. Please review this.

I'm also working on customizing the flatbutton drawing for macOS. Cocoa's default routines paste the images to the button's border, ignoring the padding.

Again, congratulations on your work. And thank you very much for the support you're providing to users in the issue section. I have very limited time and can't dedicate as much time to NAppGUI as I'd like.

[idrassi]

@frang75 thank you for the update and for the ongoing refactoring work.
No issues to help other users of the library. I'm also a maintainer of open source projects and I understand how time consuming supporting users can be.

For the GTK underline issue you reported, do you want me to tackle it in this PR branch or are you already planning to cover GTK as part of your current native refactoring pass?

[frang75]

@frang75 thank you for the update and for the ongoing refactoring work. No issues to help other users of the library. I'm also a maintainer of open source projects and I understand how time consuming supporting users can be.

For the GTK underline issue you reported, do you want me to tackle it in this PR branch or are you already planning to cover GTK as part of your current native refactoring pass?

You can fix it in this PR branch. I'm working also in this branch.

[idrassi]

@frang75
I pushed the GTK change.

The fix keeps the native GTK mnemonic path then applies a persistent PANGO_UNDERLINE_SINGLE attribute directly to the child GtkLabel for check/radio buttons. This keeps accelerator activation native while making the underline visible without requiring Alt.

I also adjusted the GTK shortcut text conversion so the mnemonic position is tracked as a displayed-character index not as a GTK-escaped string offset. This avoids incorrect underline placement for cases like "File_&Open".

Below is a screenshot.

Let me know if this approach is acceptable.