PsMessageBox

An owner-drawn modal message box for FreeBASIC Win32 applications: an owner-drawn caption band with a title and a close X, a body holding an optional icon and a wrapped left-justified message, and a footer holding one to three buttons.

It is the control you reach for when MessageBox() would do the job but looks like it came from a different application than the rest of yours. Every pixel is drawn by this control — the caption band, the title, the close X, the icon, the message and the chrome — so nothing about its appearance depends on the visual style the user happens to be running, and every colour it paints is one you can set. The footer buttons are PsButtons: real child windows that paint themselves and are reached with Tab.

PsMessageBox_DoModal blocks. It sizes and centres the box, disables the parent, runs its own nested message loop, destroys the box, and returns the id of whatever dismissed it. Because it owns that loop it also owns IsDialogMessage, which means this control adds nothing at all to your message pump.

---

What it looks like

An actual modal box, raised from the demo and captured while its nested message loop was running. The caption band, its title and the close X are all owner-drawn; below them an icon and a wrapped, left-justified message, then one to three PsButtons with the default carrying the accent border. These are the shipped dark defaults; the light set matching the reference screenshot lives in the demo.

---

Requirements

Files to copy into your project:

Use the PsBufferPaint copy shipped in this repo. The box draws its wrapped message with PsBufferPaint.PaintTextEx. PaintText forces DT_VCENTER or DT_SINGLELINE, which cannot coexist with DT_WORDBREAK, so it structurally cannot draw a wrapped message — an older copy of PsBufferPaint without PaintTextEx will not build against this control.

AfxNova is required. The control is built on CWindow, and PsBufferPaint draws through AfxNova\CGdiPlus.inc. Sources include AfxNova relative to the workspace root (#include once "AfxNova\CWindow.inc"), so builds need the workspace root on the include path:

fbc64.exe -i "C:\dev" main.bas

Include order. Each .inc pulls in its own .bi, and PsMessageBox.bi pulls in both PsBufferPaint.bi and PsButton.bi. The three implementation files are included in this order, after AfxNova and after using AfxNova:

#include once "windows.bi"
#include once "AfxNova\CWindow.inc"
#include once "AfxNova\AfxStr.inc"
#include once "AfxNova\AfxGdiplus.inc"

using AfxNova

#include once "PsBufferPaint.inc"
#include once "PsButton.inc"
#include once "PsMessageBox.inc"

GDI+ must be running before the first repaint and must outlive the last one. The control renders its geometry through GDI+, so bracket your message loop:

dim as ULONG_PTR gdipToken = AfxGdipInit()
' ... create windows, run the message loop ...
AfxGdipShutdown( gdipToken )

AfxGdipShutdown must come after every window is destroyed, because each repaint builds and tears down a PsBufferPaint.

Never name an identifier ok. GDI+ defines Ok = 0 as a Status enum value in namespace AfxNova, and hosts customarily say using AfxNova. An existing variable, parameter or function called ok becomes a duplicate definition the moment you adopt these files. Use bOK instead.

There is no pump obligation. There is no PsMessageBox_FilterMessage and nothing to add to your GetMessage loop — not for Tab, not for Escape, not for the focus ring. PsMessageBox_DoModal runs its own nested loop and calls IsDialogMessage itself, so everything keyboard-related is already handled inside the blocking call. If you have adopted controls that drop a floating window into your host's pump and therefore require a filter, this one is the exception: it takes the pump over rather than borrowing it.

You supply the fonts, and you own them. The control never creates a font. Four handles are settable and all four are borrowed — keep them alive while the box is up and destroy them yourself:

The last two are separate on purpose: one font cannot serve a 32px icon and a 10px caption glyph, and since the control creates no fonts it cannot derive the smaller one for you. Leave the glyph font unset and the icon codepoints render as missing-glyph boxes; leave the close font unset and the X is drawn in the icon font, comically large.

---

Quick start

' Create it. The box is a hidden, zero-sized popup owned by hWndParent.
dim as HWND hBox = PsMessageBox_Create( hWndParent )

' The fonts. All four stay yours; the control never creates or destroys one.
PsMessageBox_SetFont( hBox, ghFont(GUIFONT_10) )
PsMessageBox_SetCaptionFont( hBox, ghFont(GUIFONT_10) )
PsMessageBox_SetGlyphFont( hBox, ghFont(SYMBOLFONT_20) )        ' the ~32px message icon
PsMessageBox_SetCloseGlyphFont( hBox, ghFont(SYMBOLFONT_10) )   ' the ~10px close X

' The content.
PsMessageBox_SetCaption( hBox, "Warning" )
PsMessageBox_SetText( hBox, "This buffer contains unsaved edits. Do you want to save it?" )
PsMessageBox_SetIconKind( hBox, MBX_ICON_WARNING )

' Three buttons, plus a matching default button and cancel id.
PsMessageBox_AddPreset( hBox, MBX_BTN_SAVE_DONTSAVE_CANCEL )

' THIS BLOCKS. It measures, sizes, centres, disables the parent, shows the box, runs its own
' message loop, re-enables the parent, destroys the box, and returns the dismissing id.
' hBox is dead after this line.
select case PsMessageBox_DoModal( hBox )
case IDYES
    SaveDocument()
case IDNO
    ' discard
case IDCANCEL
    ' Cancel, Escape, the close X and Alt+F4 all arrive here
end select

Or, for the plainest case, one call that creates, configures, shows and returns:

if PsMessageBox_Show( hWndParent, "Delete this file?", "Confirm", _
                     MBX_ICON_QUESTION, MBX_BTN_YESNO ) = IDYES then
    DeleteTheFile()
end if

PsMessageBox_Show sets no fonts, so its icon comes out as a missing-glyph box. Use the long form whenever you want icons.

That is the whole minimum. Everything below is refinement.

---

Concepts

The handle is a real HWND

PsMessageBox_Create returns an ordinary window handle, and every PsMessageBox_* function takes it. It is a WS_POPUP top-level window — not a child — owned by the hWndParent you passed, with WS_CLIPSIBLINGS, WS_CLIPCHILDREN and WS_EX_CONTROLPARENT. It carries no system caption, because the caption band, its title and its X are all drawn by this control; that is the only way your colours and your font reach them. CS_DROPSHADOW is added so the box reads as floating above the parent rather than painted onto it.

hWndParent may be 0. Nothing is disabled and the box centres on the monitor holding the cursor.

It is created hidden and zero-sized

Nothing is shown by PsMessageBox_Create. PsMessageBox_DoModal is what measures the box, sizes it to its ideal size, centres it and shows it — so you configure a box completely before it is ever seen, and you never size it yourself.

The modal loop

PsMessageBox_DoModal does all of this, in this order:

1. Measures the box and sizes the window to PsMessageBox_GetIdealSize.
2. Centres it — on the parent's window rect, or with no parent on the monitor holding the cursor — then clamps it into that monitor's work area.
3. Sounds the MessageBeep for the icon kind, unless PsMessageBox_SetBeep( ..., false ).
4. Disables the parent, then shows the box, so there is never a frame in which both are live.
5. Gives a button the focus (see Which button owns Enter), because IsDialogMessage ignores Tab until a descendant already has it.
6. Runs a nested GetMessage loop with its own IsDialogMessage.
7. Re-enables and re-activates the parent, then destroys the box. Destroying an owned window while its owner is still disabled hands activation to another application.
8. Returns the dismissing id.

The handle is dead when DoModal returns. A box that is created and then abandoned without DoModal is yours to DestroyWindow.

WM_QUIT is re-posted, not consumed. If the host shuts down while a box is up, the nested loop puts the quit message back before exiting, so your outer pump still sees it.

Nested boxes work. A second DoModal raised from inside a callback of the first puts a second loop on the stack. The inner box ends its own loop without ending the outer one, and the outermost parent stays disabled throughout.

It is a container, and its buttons are the tabstops

The box window is not focusable. It has no WS_TABSTOP and never calls SetFocus on itself. The tabstops are the child PsButtons, which is why the box carries WS_EX_CONTROLPARENT and the buttons do not: the dialog manager must descend into the box to find them, and must treat each button as a leaf. Tab and Shift+Tab walk the buttons in the order they were added; Space and Enter activate the focused one.

Three bands tile the client exactly

All three span the full client width. The caption band holds the title on the left and the close X in a closeWidth-wide cell hard against the right edge; the title's span stops short of the X, and a long title ellipsizes into it rather than sliding underneath. The band does not collapse just because the title is empty — its height is declared, so an untitled box still has a caption band and still has an X.

How the box is sized

  iconBlock    = hasIcon ? iconWidth + iconGap : 0
  availW       = maxWidth - 2*bodyPadX - iconBlock          the WRAP width (floored at 40)
  textW/textH  = DrawTextW( DT_CALCRECT or DT_WORDBREAK ) at availW

  btnW(i)      = max( button's own ideal width , buttonMinWidth )
  buttonH      = the TALLEST button's ideal height
  footerH      = buttonCount ? 2*footerPadY + buttonH : 0
  bodyH        = 2*bodyPadY + max( textH , hasIcon ? iconHeight : 0 )

  idealW       = max( 2*bodyPadX   + iconBlock + textW ,
                      2*footerPadX + sum(btnW) + (n-1)*buttonGap ,
                      captionPadX  + captionTextW + closeWidth ,
                      minWidth )
  idealH       = captionHeight + bodyH + footerH

Three things follow from that, and all three surprise people:

SetMaxWidth constrains the text wrap, not the window. It is one term of a max(), not a clamp. Three long-captioned buttons legitimately make the box wider than the wrap width, and a long title does too. What the maximum limits is how far a line of the message runs before it wraps.

The box shrinks to fit. DT_CALCRECT reports the width the wrapped text actually used, not the width it was offered, so "Delete this file?" produces a small box rather than one padded out to the maximum. SetMinWidth is the floor that stops it becoming silly.

The title contributes a width floor only. The caption band's height is declared, so a title taller than the band clips rather than growing the box.

Icon and text share a vertical centre

Both are centred on the taller of the two, so a one-line message sits level with a 32px icon instead of clinging to its top edge, and a long message keeps the icon beside its first lines rather than leaving it floating at the top of a tall block.

MBX_ICON_NONE is a real layout state, not "no artwork available": the icon cell and its gap are not charged at all, so the text starts at the body padding and the box is narrower.

The icon cell is a layout rect. The control never measures the icon font, so a glyph too large for the cell clips instead of resizing the box — set PsMessageBox_SetIconSize to match your font, or size the font to the cell.

The buttons share one height but not one width

A row of buttons must sit on one baseline or it reads as broken, so every button is given the tallest one's ideal height. Widths are each button's own ideal width, floored at PsMessageBox_SetButtonMinWidth — which is what Windows does, and why Save / Don't Save / Cancel are three different widths.

They are right-aligned, laid out from the right edge inwards, and appear left to right in the order you added them. That order is also the tab order.

The dismissal contract

Every route out of the box goes through one place, so nothing can end the loop without also setting a result:

The cancel id, when you have not set one, is the LAST button's id. That convention was chosen because the last button is Cancel or No in every preset — it is not a law, and it is the one thing in this control that can hurt you. See Behaviour and limits.

The button ids are entirely yours. They are never used as Win32 command ids; the buttons carry separate internal control ids, so a host id of 0 or 1 cannot collide with anything the dialog manager cares about.

Which button owns Enter, and which one has the focus

PsMessageBox_SetDefaultButton does three things at once: it paints that button's accent border, it claims Enter box-wide, and it takes the initial focus.

Enter fires the default button only when no button has the focus. A focused button claims Enter for itself, so once the user has tabbed to Cancel, Enter presses Cancel — not the default. That is what you want, and it is the natural thing to get wrong.

Initial focus resolves in this order:

  an explicit SetFocusButton   >   the default button   >   the first button

Order matters. SetDefaultButton takes the focus with it, so if you want Delete to be the default while Cancel has the focus ring, call SetFocusButton after SetDefaultButton.

Dragging, and the close X

The whole caption band answers HTCAPTION, so DefWindowProc moves the window for you — that is the entire drag implementation. The close X is excluded from it, or it would be both undraggable and unclickable.

The X is the one thing on the box that takes mouse capture, because it has an ordinary press/cancel gesture: press it, slide off, release, and nothing happens. Its idle background defaults equal to the caption's, so it is invisible until the cursor reaches it, at which point it turns the Windows close-red. The footer buttons take their own capture; the box neither knows nor cares.

Pixels, and who scales them

Only the creation-time defaults are DPI-scaled for you:

Every setter afterwards takes raw pixels and expects you to scale — typically pWindow->ScaleX(...) / ScaleY(...). The two thickness values should not be scaled at all: a hairline should stay a hairline at any DPI.

Layout is lazy

A setter marks the layout stale and asks for a repaint; the next paint — or any size query, rect query, or DoModal — recomputes it in one measuring pass. There is no begin-update / end-update pair to remember, and configuring a box with fifteen calls in a row costs one measuring pass, not fifteen.

Setters that cannot change a measurement repaint without re-laying out at all: SetIconColor, SetBorderThickness, SetGlyphFont and SetCloseGlyphFont.

Lifetime

PsMessageBox_DoModal destroys the box before returning. The child buttons are ordinary child windows and go with it; each frees its own state. Your fonts are left alone. A box created and then abandoned without DoModal must be destroyed by you with DestroyWindow.

---

Behaviour and limits

The cancel id defaults to the LAST button's id. Escape, the close X and Alt+F4 all answer it. That is correct for every preset, where the last button is Cancel or No — but a box whose last button is destructive must call PsMessageBox_SetCancelID explicitly, or pressing Escape performs the destructive action. With no buttons at all there is nothing to name, and the answer is 0.

Firm properties of the control, not settings:

• PsMessageBox_DoModal blocks, and the handle is dead when it returns. Do not touch hMsgBox afterwards.
• Three buttons maximum. PsMessageBox_AddButton returns 0 once the box holds PSMESSAGEBOX_MAXBUTTONS. A question that needs a fourth answer wants a real dialog.
• PsMessageBox_AddPreset is additive. It appends to whatever is already there and then sets the default button and the cancel id. Calling it on a box that already has buttons is a host error; the control does not police it.
• There is no disabled mood anywhere. A message box is modal and everything on it is live by definition — a disabled button on a box the user cannot leave would be a trap. The colour struct carries no disabled fields.
• The box is not resizable. There is no thick frame and no size grip, and DoModal always sizes it to its ideal size. If you resize it yourself, rects are computed honestly rather than squeezed: the text and title spans collapse to empty rather than going negative, and the buttons keep their sizes and run off the left edge.
• No tooltips. There is no tooltip window and no tooltip callback anywhere on the box. The footer buttons have their own tooltip API, reachable through PsMessageBox_GetButtonHandle.
• No HICON support. The icon is a glyph string drawn in a font you supply — by default a Segoe Fluent Icons / Segoe MDL2 Assets codepoint. Ship a different icon font and remap the PSMESSAGEBOX_GLYPH_* values, or override per box with PsMessageBox_SetGlyph.
• No Ctrl+C. The real Win32 MessageBox copies its text to the clipboard; this one does not. The message is drawn with DrawTextW and there is no text object behind it.
• No text selection, for the same reason.
• No rounded corners. Square, so that adopting the control does not force a dwmapi link on every host.
• CS_DBLCLKS is deliberately off. The only double-clickable thing on the box is the X, and a rapid second click there is a legitimate second click on a window that may already be gone.
• The caption is not the window text. PsMessageBox_SetCaption does not alias WM_SETTEXT, so GetWindowText on the box returns nothing useful.
• Leaving the glyph font unset draws missing-glyph boxes, not nothing. So does PsMessageBox_Show, which sets no fonts at all.
• PsMessageBox_SetIconColor cannot be undone. It latches an override, and there is no way to hand the colour decision back to the icon kind. PsMessageBox_SetGlyph( ..., "" ) does clear the glyph override.
• Out-of-range values are ignored, leaving the current setting in place: an icon kind outside the five constants, a negative padding, gap, thickness, height or width, a maximum width below 1, a button index outside the current button count.
• The footer divider has no setter. Its thickness is fixed at 1 pixel and never scaled; its colour is DividerColor in the colour struct.

---

API reference

Creation and showing

Content

All silent, and all lazy — a burst of them costs one measuring pass.

Buttons

Dismissal

Geometry and layout

All setters take raw pixels; you do the DPI scaling. Each marks the layout stale and requests a repaint, except where noted.

Every rect query forces a pending layout first, so results are always current, and all are in client coordinates. Each returns FALSE — leaving rc empty — when the box has no client area yet, which is the case between PsMessageBox_Create and PsMessageBox_DoModal. An absent part answers TRUE with an empty rect: empty is the honest answer.

Fonts

All four handles are borrowed. Keep them alive and destroy them yourself.

Appearance

The two resolvers are there for a host writing its own paint callback that wants to draw an icon of its own while still matching the kind, or that wants to know a kind's glyph and colour without building a box first. Inside a paint callback you rarely need either: MBX_PAINTINFO already carries wszGlyph and clrIcon, and those do have the overrides folded in.

To change one colour, read-modify-write:

dim as MBX_COLORS clrs
PsMessageBox_GetColors( hBox, @clrs )
clrs.BackColor        = BGR(255,255,255)
clrs.CaptionBackColor = BGR(243,243,243)
PsMessageBox_SetColors( hBox, @clrs )

Callback registration

Both are optional and independent.

---

Colors

The colour surface is one flat struct, MBX_COLORS, with seventeen COLORREF fields. Every field ships with a usable default, so a box you never call PsMessageBox_SetColors on still looks right.

The defaults are dark. They are inherited from the button palette rather than matched to a light system theme, so an untouched box looks like a dark-themed application. A light box is a read-modify-write away — and remember PsMessageBox_SetButtonColors, or a light box gets dark buttons.

There is no disabled mood anywhere in this struct. A message box is modal, and everything on it is live by definition.

MBX_ICON_NONE has no colour field because it has no glyph.

Which colour wins

The close X is the only part with moods, and it has three:

pressed   >   hot   >   idle

PsMessageBox_SetIconColor overrides whichever IconColor* the kind selected, for that box.

What the painter draws

Presence is decided on the rects, not on the strings: an absent part's rect is empty, so an untitled caption, an iconless body and an empty footer all drop out of the same test.

The built-in painter ignores isActive deliberately — a modal box is the only thing the user can interact with, so greying its title says nothing useful. A custom painter is handed the flag and may use it.

All of it goes through PsBufferPaint, which renders geometry with GDI+ and text with GDI. A paint callback gets that same buffer and the same primitives.

---

Callbacks

Paint

type MBX_PaintCallbackSub as sub( byval p as MBX_PAINTINFO ptr )

Draws the whole box instead of the built-in painter. Paint through p->b, the box's double buffer for this repaint — do not touch the screen DC.

The control has already filled the client with BackColor before calling you, so a callback that only wants to add something on top does not have to repaint the background.

The buttons are not yours to draw. They are real child windows with their own WM_PAINT; draw the box around them.

MBX_PAINTINFO carries everything you need:

Every rect is precomputed. Use them as given — in particular never re-derive rcText by re-applying the body padding to rcBody, because the icon cell and the icon gap can change underneath you.

Two contracts worth honouring:

• Draw the message with the same font you handed to PsMessageBox_SetFont and with DT_WORDBREAK. The box's height was measured with that font and that flag; a different either, and the height is a lie and the text clips.
• Use PaintTextEx for the message, not PaintText — the latter forces DT_SINGLELINE.

A paint callback that fills a rectangle covering the whole box will erase everything under it. In particular PsBufferPaint.PaintBorderRect fills before it strokes, so reaching for it to draw the window outline or the footer divider floods everything beneath and the box renders as one solid block — which survives a glance, because the flood colour is a real colour from the box. PaintRoundOutline and PaintLine stroke without filling. PsMessageBox_CountRenderedTones exists so you can assert you have not done it: a wiped part is literally one tone.

Message

type MBX_MessageCallbackFunc as function( byval m as MBX_MESSAGEINFO ptr ) as boolean

Observes the box's own messages as they arrive. Return TRUE to suppress the control's default handling of that message, FALSE to let it proceed.

Mouse movement and leave, left button down and up, capture loss, WM_CLOSE and WM_DESTROY are all reported here. This is also the natural place to raise a nested box — return FALSE afterwards and the outer box carries on handling the message normally.

Your return value is ignored for three messages:

For every other message, TRUE suppresses the default handling.

---

Constants

enum                        ' the icon, and the MessageBeep that goes with it
    MBX_ICON_NONE = 0       ' no icon cell and no gap -- a layout state, not a missing picture
    MBX_ICON_INFO
    MBX_ICON_WARNING
    MBX_ICON_ERROR
    MBX_ICON_QUESTION
end enum

enum                             ' ready-made button sets for AddPreset / Show
    MBX_BTN_OK = 0               ' [OK]                          default OK,    cancel OK
    MBX_BTN_OKCANCEL             ' [OK] [Cancel]                 default OK,    cancel Cancel
    MBX_BTN_YESNO                ' [Yes] [No]                    default Yes,   cancel No
    MBX_BTN_YESNOCANCEL          ' [Yes] [No] [Cancel]           default Yes,   cancel Cancel
    MBX_BTN_RETRYCANCEL          ' [Retry] [Cancel]              default Retry, cancel Cancel
    MBX_BTN_SAVE_DONTSAVE_CANCEL ' [Save] [Don't Save] [Cancel]  default Save,  cancel Cancel
end enum

The presets use the standard Win32 ids — IDOK, IDCANCEL, IDYES, IDNO, IDRETRY — and those are what DoModal returns. There is no IDSAVE in Win32, so Save / Don't Save / Cancel answers IDYES / IDNO / IDCANCEL. Note that MBX_BTN_YESNO points the cancel path at IDNO, the safe half of a yes/no question, and MBX_BTN_OK points it at IDOK so that Escape is not a silent no-op on a one-button box.

enum                        ' which rect PsMessageBox_CountRenderedTones looks at
    MBX_PART_CAPTION = 0
    MBX_PART_BODY
    MBX_PART_FOOTER
    MBX_PART_TEXT
    MBX_PART_ICON
    MBX_PART_CLOSE
end enum

The glyph codepoints are #defines rather than literals buried in the resolver, so that a host shipping a different icon font can see exactly what to remap:

To use different artwork without changing these, call PsMessageBox_SetGlyph per box.

Two more exist for the close button's hover polling — IDT_CMESSAGEBOX_HOTTRACK and PSMESSAGEBOX_HOTTRACK_MS (100). They back a timer that guarantees the X's hot state is cleared when the mouse leaves, because WM_MOUSELEAVE is not reliably delivered on a fast exit. Neither is a host concern.

---

Related controls

PsButton — the footer buttons are PsButtons, created and owned by the box. Everything about how they look and behave is documented there: the mood precedence, the accent border that PsMessageBox_SetDefaultButton switches on, the focus ring, the press-and-slide-off gesture, and the PSBUTTON_COLORS struct that PsMessageBox_SetButtonColors takes. PsMessageBox_AddButton returns each button's HWND, so any PsButton function — a left glyph, a tooltip, a different colour set for a destructive choice — is reachable directly.

PsMessageBox.bi includes PsButton.bi for you; you only need both .inc files in your build.