PsTextBox

A textbox control for FreeBASIC Win32 applications: a themeable frame of your own colours — border, rounded corners, outer fill — wrapped around a real RichEdit50W editor that does the typing, the selection, the clipboard and the undo.

It is the control you reach for when a plain EDIT gets you the behaviour but not the look. The frame is drawn by the control, so nothing about it depends on the visual style the user happens to be running, and every colour it paints is one you set. Inside the frame you get a cue banner with its own colour and font, vertically centred text on a single-line control, optional numeric-only input with a decimal-place limit, and a right-click menu that is itself an owner-drawn PsPopupMenu you can theme to match the rest of your application.

Single-line by default. Pass true at creation for a multiline control: word wrap, ENTER inserts a newline, TAB inserts a tab character, and the wheel scrolls. A multiline control never shows a native scrollbar — it exposes its scroll state in lines instead, shaped to be wired straight to an external scrollbar.

---

What it looks like

Five boxes, all on one subclassed RichEdit50W: a cue banner with its own colour and a rounded focus border; a read-only box with wide margins; a numeric-only box with two decimal places; a multiline editable box whose cue banner word-wraps; and a multiline read-only box preloaded with 40 lines. The green line at the bottom is the demo printing scroll events from the control's PsVScrollBar-shaped scroll API.

---

Requirements

Files to copy into your project:

AfxNova is required. The control is built on CWindow, uses AfxNova\AfxRichEdit.inc for the RichEdit_* helpers and AfxNova\AfxWin.inc for clipboard access, and CBufferPaint 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. PsTextBox.bi pulls in PsBufferPaint.bi and PsPopupMenu.bi itself, but the three implementation files must be included in dependency order:

#include once "PsBufferPaint.inc"
#include once "PsPopupMenu.inc"    ' PsTextBox's built-in right-click menu runs on it
#include once "PsTextBox.inc"

GDI+ must be running before the first repaint and must outlive the last one. The frame is rendered 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. If you also call CoInitialize, shut GDI+ down before CoUninitialize — GDI+ leans on COM.

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.

PsTextBox_FilterMessage in your message pump is mandatory. The right-click menu is a PsPopupMenu, which is not modal: its keyboard navigation and its dismissal on an outside click both live in that filter. Skip the call and the menu still opens and still paints, but it cannot be driven with the arrow keys or Enter, and it never closes when the user clicks elsewhere.

dim uMsg as MSG
do while GetMessage( @uMsg, null, 0, 0 )
    if uMsg.message = WM_QUIT then exit do
    if PsTextBox_FilterMessage( @uMsg ) then continue do
    TranslateMessage @uMsg
    DispatchMessage @uMsg
loop

One call serves every PsTextBox in the application: only one menu chain can be open at a time and the filter finds it. An application that also hosts a PsMenuBar calls that filter too; the two are independent and each stands down while the other's menu is up.

Tab navigation works without IsDialogMessage. The control's container carries WS_EX_CONTROLPARENT and the RichEdit child inside it carries WS_TABSTOP, so the dialog manager can see through the container to the tabstop — but you do not need the dialog manager for the common case, because a single-line control handles VK_TAB itself (GetNextDlgTabItem against the top-level ancestor, Shift+Tab for the previous stop).

If you do add IsDialogMessage, know what it costs you here: it claims VK_RETURN and VK_ESCAPE before the control sees them, which defeats the EnterPressedCallback and any ESC handling you have put in the message callback. The bundled demo deliberately runs without it.

A multiline control inserts a tab character on TAB and never moves focus. If Tab must leave a multiline box, veto WM_KEYDOWN / VK_TAB in the message callback and move focus yourself.

---

Quick start

' Create it. The control is created zero-sized and hidden.
dim as HWND hCtl = PsTextBox_Create( hWndParent, IDC_MYFORM_SEARCH )

' Fonts are yours: the control never creates or deletes an HFONT.
PsTextBox_SetFont( hCtl, ghFont(GUIFONT_10) )
PsTextBox_SetForeColor( hCtl, theme.ForeColor )
PsTextBox_SetBackColor( hCtl, theme.BackColorBox )

' Cue banner, shown whenever the buffer is empty. Its colour and font are its own.
PsTextBox_SetCueBannerText( hCtl, "Search anything..." )
PsTextBox_SetCueBannerColor( hCtl, theme.ForeColorCue )
PsTextBox_SetCueBannerFont( hCtl, ghFont(CUEFONT_10) )

' Frame. Every pixel value is a raw device pixel: DPI-scale at the call site.
PsTextBox_SetBorderColor( hCtl, theme.BorderColor )
PsTextBox_SetFocusBorderColor( hCtl, theme.FocusAccent )
PsTextBox_SetCornerRadius( hCtl, pWindow->ScaleX(4) )
PsTextBox_SetOuterBackColor( hCtl, theme.BackColorWindow )   ' corners blend into the form
PsTextBox_SetMargins( hCtl, pWindow->ScaleX(8), pWindow->ScaleX(8) )

' Events.
PsTextBox_SetChangeCallback( hCtl, @TextBox_ChangeCallback )
PsTextBox_SetEnterPressedCallback( hCtl, @TextBox_EnterPressedCallback )

' Place it. SWP_SHOWWINDOW is required -- the control is created hidden.
SetWindowPos( hCtl, 0, x, y, nWidth, nHeight, SWP_NOZORDER or SWP_SHOWWINDOW )

And the callbacks:

sub TextBox_ChangeCallback( byval hTextBox as HWND )
    ' USER edits only -- typing, cut, paste, undo. PsTextBox_SetText never lands here.
    gFilter = PsTextBox_GetText( hTextBox )
end sub

sub TextBox_EnterPressedCallback( byval hTextBox as HWND )
    ' Single-line only. The keypress itself is always swallowed: no newline, no beep.
    RunSearch( PsTextBox_GetText( hTextBox ) )
end sub

Plus the mandatory PsTextBox_FilterMessage line in the message pump, shown above.

That is the whole minimum. Everything below is refinement.

---

Concepts

The handle is a real HWND

PsTextBox_Create returns an ordinary window handle, and every PsTextBox_* function takes it. It is not an opaque type, so you can treat the control as the window it is — SetWindowPos to place and size it, ShowWindow to show it, GetDlgItem to find it by the CtrlID you passed at creation.

There is a real editor inside

The control is a container window that owns the chrome and the geometry, plus a subclassed RichEdit50W child that does all the editing. RichEdit rather than EDIT because it supports vertical centring of the text (EM_SETRECT) and per-control colours (EM_SETCHARFORMAT, EM_SETBKGNDCOLOR) without owner-draw.

Two consequences you will meet immediately:

• GetFocus() = hTextBox is always false. Focus sits on the child. Use PsTextBox_HasFocus. Calling SetFocus on the container, or sending it WM_SETFOCUS, redirects focus to the child for you.
• The child's geometry is derived, never assigned. Its rect is the container's client rect inset by the border width on all four sides. Resizing the control, or changing the border width, recomputes it and re-applies the vertical centring and the margins.

PsTextBox_GetRichEditHandle is the escape hatch for RichEdit-specific messages the flat API and the message door below do not cover.

The message door

Sending a classic edit-control message to the control works as if it were the edit control itself. The container forwards:

Same operation, two doors: the message for a separate control or window, the function for an in-process host.

dim as long n = SendMessage( hCtl, WM_GETTEXTLENGTH, 0, 0 )
SendMessage( hCtl, EM_SETSEL, 0, 9 )

It is created zero-sized and hidden

PsTextBox_Create gives the container the styles WS_CHILD, WS_CLIPSIBLINGS and WS_CLIPCHILDREN, with WS_EX_CONTROLPARENT as its extended style. WS_VISIBLE is deliberately absent, so a newly created control shows nothing until you size it. Include SWP_SHOWWINDOW in your SetWindowPos — and note that the RichEdit child is shown by the first resize, so a control that is never sized never displays its editor at all.

Single-line and multiline are different controls

The choice is made at PsTextBox_Create and is fixed for the control's lifetime — ES_MULTILINE cannot be toggled on a live window. What changes:

Pixels, and who scales them

Every pixel value passed to this API is a raw device pixel. Margins, border width and corner radius are all taken verbatim; the control never scales a caller's value. DPI-scale at the call site, typically pWindow->ScaleX(...) / ScaleY(...).

That is not an oversight: margins go straight into EM_SETMARGINS, so a control-side scale would both lie to anything reading EM_GETMARGINS and double-scale a host that had already scaled.

One format for the whole buffer

The editor runs in TM_PLAINTEXT mode. That is what gives you one character format across the entire buffer — the control never colours individual characters — and what makes pasted text shed any rich formatting it arrived with.

PsTextBox_SetFont and PsTextBox_SetForeColor are converted together into a single CHARFORMATW (face, size, charset, bold, italic, underline, strikeout, colour) and applied to the whole buffer with SCF_ALL. There is no way to format a run of characters differently, and that is by design.

TM_PLAINTEXT is also the reason PsTextBox_SetTextAlign is more expensive than it looks — see that function, and Behaviour and limits.

Programmatic changes are silent

PsTextBox_SetText, PsTextBox_ReplaceSel, PsTextBox_Clear, PsTextBox_SetValue, the numeric reformat the control performs on focus loss, and a WM_SETTEXT or EM_REPLACESEL sent through the message door all leave the change callback alone. It reports user interaction — typing, cut, paste, undo — and nothing else, which means you can call a setter from inside your own change handler without recursing.

The scroll-changed callback is the deliberate exception; see Callbacks.

The cue banner

Drawn by the control whenever the buffer is empty, focused or not — the caret blinks over it. It is painted at the editor's formatting rect, so it sits exactly where typed text will appear, including the vertical centring on a single-line control. Its colour is independent of the text forecolor, and its font falls back to the text font when you do not set one.

The frame

The container paints the outer fill across its whole client area first, then the rounded frame on top of it. The pixels outside the corner arcs keep showing the outer fill — pass your form's background colour to PsTextBox_SetOuterBackColor and rounded corners blend into it instead of showing white.

The border colour switches to the focus border colour while the editor has focus. A border width of 0 draws no border at all, and the child then fills the entire client area.

Lifetime

The control frees itself when its window is destroyed, including the PsPopupMenu window behind the right-click menu — that is a WS_POPUP window, not a child, so it would not go with the window tree otherwise. It owns no host resources: every HFONT you hand it stays yours to delete. Destroy the parent and you are done.

---

Behaviour and limits

Firm properties of the control, not settings:

• PsTextBox_SetTextAlign discards the undo history on a control that already has content. Set it at setup time, before anything has been typed. TM_PLAINTEXT refuses EM_SETPARAFORMAT outright and silently, so the only sequence the editor accepts is: save the text, empty the buffer, switch to TM_RICHTEXT, apply the format, switch back, restore the text — and then empty the undo buffer, because the undo stack now spans a rewrite the user never made. On an empty control that costs nothing and nobody notices.
• The PsTextBox_FilterMessage pump call is not optional. Without it the right-click menu has no keyboard navigation and never dismisses on an outside click.
• Multiline is a creation-time choice. There is no setter, because ES_MULTILINE cannot be toggled on a live window.
• Numeric mode is single-line only. PsTextBox_SetNumericMode returns without doing anything on a multiline control, and the getter still reads FALSE afterwards.
• EnterPressedCallback is single-line only, and the ENTER keypress is always swallowed there — no newline, no beep — whether or not a callback is installed.
• ESCAPE is swallowed in both line modes, because the editor would beep. Act on it, if you want to, from the message callback.
• There is no horizontal scroll API. A single-line control auto-scrolls horizontally on its own (ES_AUTOHSCROLL); a multiline control wraps instead, so there is nothing to scroll.
• A multiline control never shows a native scrollbar. No scrollbar styles are applied. Drive an external one through ScrollChangedCallback / PsTextBox_GetVScrollInfo / PsTextBox_ScrollToLine.
• The control implements multiline wheel scrolling itself, converting the delta to EM_LINESCROLL and honouring SPI_GETWHEELSCROLLLINES (including WHEEL_PAGESCROLL, which scrolls a page per notch). The RichEdit's own wheel handling is bypassed entirely. Sub-notch deltas from a high-precision wheel or trackpad accumulate, so a slow swipe scrolls smoothly instead of doing nothing.
• No mouse capture is taken. The RichEdit manages its own selection-drag capture internally, which is why a message callback's return value is honoured uniformly — there is no invariant of the control's that a suppressed message could strand.
• No per-character formatting. One font and one forecolor for the whole buffer, guaranteed by TM_PLAINTEXT.
• No vertical alignment setting. A single-line control's text is always vertically centred; a multiline control's always starts at the top.
• Alignment is measured between the margins, not between the border edges. A centred value in a control with lopsided margins sits off-centre by design. Give it equal margins if you want it optically centred.
• An unrecognized alignment value falls back to TXT_ALIGN_LEFT rather than being rejected, so the control's alignment can never silently disagree with what the host thinks it set.
• The right-click menu is rebuilt on every open, from the current selection, clipboard and read-only state. When nothing qualifies — no selection, nothing to paste, no text — no menu appears at all.
• Only one popup chain may be open per application. A second textbox's menu closes the first's.

---

API reference

Creation

Text and content

Selection

Positions are 0-based character indices.

Edit behaviour

Clipboard and undo

These six drive the editor exactly as Ctrl+X / Ctrl+C / Ctrl+V / Ctrl+Z would, so unlike the text setters they are not silent — the change callback fires for them.

Numeric mode

Single-line only. The accepted grammar is: an optional leading minus, digits, and at most one decimal point followed by at most DecimalPlaces fractional digits. Typing is filtered character by character against the text as it will be after the pending selection is replaced, and a paste is validated as a whole. Control characters below 32 always pass, so backspace and the Ctrl+C / V / X / Z / A shortcuts keep working.

On focus loss a non-empty value is reformatted to exactly DecimalPlaces ("5." becomes "5.00"), silently, and before the focus callback runs — so a host reading the text there sees the formatted value. An empty box stays empty, and the cue banner shows, unless ZeroWhenEmpty is on.

Multiline and scrolling

Units are lines, shaped 1:1 for an external scrollbar: on each ScrollChangedCallback read the three numbers and push them into the scrollbar's range, and wire the scrollbar's position callback back to PsTextBox_ScrollToLine.

Appearance

All fonts are caller-owned HFONTs — the control never deletes one.

Context menu and the message pump

Callback registration

All five are optional and independent.

---

Colors

There is no colour struct. Each colour is its own property with its own getter and setter, and each ships with a usable light-theme default, so a control you never colour still looks right.

Which colour wins

The frame takes exactly one colour per repaint:

editor has focus   ->   FocusBorderColor
otherwise          ->   BorderColor

There is no hot, pressed or disabled variant of any of these. The control does not track hover, and disabling it is the host's business — EnableWindow on the container or on the editor — which is why there is no disabled colour to configure.

The paint order is: OuterBackColor across the whole client, then the rounded frame filled with BackColor and stroked in whichever border colour applies. Where the border width is 0 the frame is filled and not stroked, and the editor covers the whole client anyway.

CueColor is independent of ForeColor on purpose: a cue banner that is simply the text colour reads as content rather than as a hint.

---

Callbacks

Change

type TXT_ChangeCallbackSub as sub( byval hTextBox as HWND )

The text changed because of user interaction — typing, cut, paste, undo. Read the new text with PsTextBox_GetText.

It never fires for PsTextBox_SetText, PsTextBox_ReplaceSel, PsTextBox_Clear, PsTextBox_SetValue, a WM_SETTEXT or EM_REPLACESEL sent through the message door, the numeric reformat on focus loss, or the buffer rewrite PsTextBox_SetTextAlign performs. That is what makes it safe to call a setter from inside this handler.

Focus

type TXT_FocusCallbackSub as sub( byval hTextBox as HWND, byval bGotFocus as boolean )

The editor gained (bGotFocus = true) or lost (false) the keyboard focus. In numeric mode the value has already been reformatted by the time you are called on a focus loss, so the text you read here is the formatted one. The control has also already invalidated itself for the border-colour switch.

Enter pressed

type TXT_EnterPressedCallbackSub as sub( byval hTextBox as HWND )

The user pressed ENTER. Single-line only — in a multiline control ENTER inserts a newline and this never fires.

The keypress itself is always swallowed, whether or not a callback is installed: no newline is inserted and the editor does not beep.

Scroll changed

type TXT_ScrollChangedCallbackSub as sub( byval hTextBox as HWND )

The vertical scroll state may have changed. Multiline only. It is relayed from the editor's EN_UPDATE, which fires on any display update — typing, a programmatic SetText, scrolling by wheel, key or caret movement — and the control's wheel handler calls it directly as well.

Deliberately not gated the way the change callback is: a programmatic SetText changes the line count, and a scrollbar has to hear about that. Treat it as "re-read the numbers", not as "the user scrolled":

sub TextBox_ScrollChangedCallback( byval hTextBox as HWND )
    dim as integer nTotal, nPage, nFirst
    PsTextBox_GetVScrollInfo( hTextBox, nTotal, nPage, nFirst )
    PsVScrollBar_SetRange( ghScrollBar, nTotal, nPage, nFirst )
end sub

Message

type TXT_MessageCallbackFunc as function( byval m as PSTEXTBOX_MESSAGEINFO ptr ) as boolean

Observes messages arriving at the editor before the control acts on them. Return TRUE to suppress both the control's handling and the editor's own; FALSE to let it proceed.

PSTEXTBOX_MESSAGEINFO:

Only these messages are reported:

WM_KEYDOWN, WM_KEYUP, WM_CHAR, WM_LBUTTONDOWN, WM_LBUTTONUP, WM_LBUTTONDBLCLK, WM_RBUTTONDOWN, WM_RBUTTONUP, WM_MBUTTONDOWN, WM_MBUTTONUP, WM_MOUSEMOVE, WM_MOUSEWHEEL, WM_CONTEXTMENU, WM_SETFOCUS, WM_KILLFOCUS.

The return value is honoured uniformly — there is no message whose suppression is quietly ignored. That is a direct consequence of the control taking no mouse capture: the RichEdit manages its own selection-drag capture internally, so there is no state of the control's that a suppressed message could strand.

Two vetoes worth knowing about:

A worked example — ESC clears the box:

function TextBox_MessageCallback( byval m as PSTEXTBOX_MESSAGEINFO ptr ) as boolean
    if (m->uMsg = WM_KEYDOWN) andalso (m->wParam = VK_ESCAPE) then
        PsTextBox_Clear( m->hTextBox )     ' programmatic, so no change callback
        return true
    end if
    return false
end function

---

Constants

enum
    TXT_ALIGN_LEFT = 0      ' the default
    TXT_ALIGN_CENTER
    TXT_ALIGN_RIGHT
end enum

These are the control's own constants rather than richedit's PFA_* values: how alignment reaches the editor is an implementation detail, the same way you do not have to know that the forecolor arrives by EM_SETCHARFORMAT.

There are no #defined default constants — the defaults live on the control's own type:

Colour defaults are listed under Colors.

---

Related controls

PsPopupMenu is not optional — it is the built-in right-click menu, and both its files must be in your project and included before PsTextBox.inc. Reach the control's instance with PsTextBox_GetContextMenu and style it with PsPopupMenu's own setters; that handle is stable for the control's lifetime, so theming it once at startup is enough. PsTextBox_FilterMessage exists because PsPopupMenu is not modal, and it simply routes the message on to PsPopupMenu's filter.

PsBufferPaint is the drawing surface the frame is painted through, and the reason for the GDI+ bracket and the ok identifier rule in Requirements.

PsVScrollBar is what a multiline control's scroll API is shaped for: ScrollChangedCallback fires, you read PsTextBox_GetVScrollInfo and push the three numbers into PsVScrollBar_SetRange( total, page, pos ), and the scrollbar's own position callback goes straight into PsTextBox_ScrollToLine. Nothing about PsTextBox requires it — any external scrollbar that speaks in lines will do — but the units were chosen to make that wiring a one-liner in each direction.