PsProgressBar

An owner-drawn progress bar for FreeBASIC / Win32, built on the AfxNova framework.

A rounded track with a fill that grows along it. The fill can be a flat colour or a two-stop linear gradient, and it can be continuous or broken into blocks — those two settings are independent, so all four combinations are available. When there is nothing to measure, switch it to indeterminate mode and a chunk floats back and forth inside the track (or slides off one end and in at the other, if you prefer the classic Windows marquee).

It covers what a standard Win32 progress bar does — range, position, step, marquee, and the normal / paused / error states of PBM_SETSTATE — and adds gradients, blocks, an optional percentage or caption drawn across the bar in two colours split at the fill boundary, and a vertical orientation.

It is display-only. It takes no focus, no mouse capture and no keyboard, and it never reacts to a click. Every message it receives is offered to your message callback, so anything interactive — click-to-cancel being the obvious case — is yours to add.

Repository: <https://github.com/PaulSquires/PsProgressBar>

---

What it looks like

---

Requirements

Copy these files into your project:

PsProgressBar.bi includes PsBufferPaint.bi and PsTipHost.bi itself, and PsProgressBar.inc includes PsTipHost.inc (which in turn includes PsTooltip.inc), so the extra files cost you no include lines — they only have to be present.

Include order

Headers first, implementations after your globals — the same order main.bas uses:

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

using AfxNova

' ... your fonts, theme and other globals here ...

#include once "PsBufferPaint.inc"
#include once "PsProgressBar.inc"

Your sources reference AfxNova as AfxNova\..., i.e. relative to the workspace root, so the compiler needs that root on its include path:

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

GDI+ must be running

All geometry is drawn through GDI+, and the gradient fills are GDI+ linear-gradient brushes. Initialise it before the first repaint and shut it down only after every window is destroyed:

CoInitialize(null)
dim as ULONG_PTR gdipToken = AfxGdipInit()

function = frmMain_Show( 0 )

AfxGdipShutdown( gdipToken )   ' before CoUninitialize -- GDI+ leans on COM
CoUninitialize

Without this the control draws nothing at all.

Do not name anything ok

GDI+ defines Ok = 0 as a Status enum value that lands at global scope, and FreeBASIC identifiers are case-insensitive. Any variable or parameter of yours named ok, Ok or OK becomes a duplicate definition the moment you include PsBufferPaint.bi. Dropping using AfxNova does not help. Use bOK.

There is no pump obligation

PsProgressBar has no PsProgressBar_FilterMessage, and needs no call in your message loop. If you are coming from a neighbouring control you will look for one — there isn't one. The marquee animation runs on a WM_TIMER, and neither tooltip backend needs your loop: the system tip subclasses the control itself (TTF_SUBCLASS) and PsTooltip has no FilterMessage at all. Switching backends therefore adds no pump obligation either.

Nor does it need IsDialogMessage: it takes no focus and is not a tab stop.

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

---

Quick start

' Create it, place it, show it. Orientation is chosen here and cannot change later.
dim as HWND hBar = PsProgressBar_Create( hWndParent, IDC_MYBAR, PRG_HORIZONTAL )

PsProgressBar_SetRange( hBar, 0, 100 )
PsProgressBar_SetPos( hBar, 45 )

' A vertical gradient across a horizontal bar gives a glossy top-to-bottom sheen.
PsProgressBar_SetFillStyle( hBar, PRG_FILL_GRADIENT )

' Optional: write the percentage across the bar. The font is yours -- the control
' borrows the handle and never destroys it.
PsProgressBar_SetFont( hBar, ghFont(GUIFONTBOLD_9) )
PsProgressBar_SetTextMode( hBar, PRG_TEXT_PERCENT )

PsProgressBar_SetMessageCallback( hBar, @MyBar_MessageCallback )

SetWindowPos( hBar, 0, 20, 20, 320, 18, SWP_NOZORDER )
ShowWindow( hBar, SW_SHOW )

The message callback — the only place this control can be made interactive:

function MyBar_MessageCallback( byval m as PSPROGRESSBAR_MESSAGEINFO ptr ) as boolean
    select case m->uMsg
    case WM_LBUTTONUP
        ' The control will never act on this itself.
        MyCancelTheJob()
    end select
    return false        ' let the control's default handling proceed
end function

To drive it while work happens, call PsProgressBar_SetPos (or PsProgressBar_StepIt) as the work progresses. The bar moves immediately — it does not ease toward the new value.

---

Concepts

The handle is a real HWND

PsProgressBar_Create returns an ordinary window handle, not an opaque type, so you place and size the control with SetWindowPos / MoveWindow like any other child window. Every PsProgressBar_* function takes that handle.

The control frees itself when its window is destroyed, and destroys its own tooltip window with it. It does not own the font you give it.

Orientation is fixed at creation

Pass PRG_HORIZONTAL or PRG_VERTICAL to PsProgressBar_Create. It cannot change afterwards; PsProgressBar_GetOrientation reads it back. A vertical bar fills bottom-up by default.

PsProgressBar_SetReverse mirrors the growth direction on whichever axis is in use: a horizontal bar grows right-to-left, a vertical bar grows top-down.

Three rects, all derived

You never set the control's geometry directly. It derives three rects from the client area and your settings, and recomputes them lazily — a setter marks the layout stale, and the next repaint (or the next rect query) rebuilds it.

rcTrack   spans the client along the growth axis;
          nThickness deep across it, centred on that axis.
          nThickness = 0 (the default) means "fill the client".

rcFill    rcTrack deflated by nBarInset on all four sides.
          This is where a 100% bar reaches.

rcBar     the drawn portion.
            determinate    anchored to rcFill's start edge,
                           length = (pos - min) / (max - min) * fill length
            indeterminate  a chunk of nChunkPercent of the fill, floating
                           at whatever offset the marquee gives for the
                           current tick. NOT anchored to either end.

Read them with PsProgressBar_GetTrackRect, GetFillRect and GetBarRect. All three are in client coordinates.

If the client is smaller than the settings ask for, the rects are computed honestly and the overflow is clipped — the track keeps its proper shape rather than being squeezed into a different one.

Everything is silent

There is no change callback of any kind. A progress bar's position is only ever set programmatically, so there is nothing a user did that you would need telling about. Set the position and the bar repaints; that is the whole contract.

The position jumps, it does not animate

PsProgressBar_SetPos moves the bar immediately. Windows' own common control eases toward the new value; this one does not, which means the control runs a timer only in indeterminate mode. A determinate bar costs nothing between repaints.

If you want smooth motion, drive the position from your own timer.

Text is drawn twice

When a text mode is set, the string is drawn centred on rcTrack in two clipped passes over the same rectangle: the part lying over the filled bar takes TextColorOnBar, the part over the empty track takes TextColor. Because both passes use the identical rect, the glyphs land in the same place and only the colour changes at the fill boundary — including part-way through a single glyph.

A disabled bar draws the text once, in TextColorDisabled.

---

Behaviour and limits

• Orientation cannot change after creation. Create a second control if you need both.
• Vertical bars draw their text horizontally. The string is not rotated, so a text mode on a narrow vertical bar will clip. Leave it at PRG_TEXT_NONE.
• PsProgressBar_StepIt clamps at the maximum; it does not wrap. Windows' PBM_STEPIT wraps around to the minimum, which makes a finished job look restarted.
• An empty or inverted range draws an empty bar rather than dividing by zero. PsProgressBar_SetRange normalises an inverted pair and pulls the position into the new range.
• In indeterminate mode the position means nothing. It is still stored and still readable, but nothing draws from it until you switch back.
• The marquee animates only while the control is enabled and not hidden. Disabling it or hiding it stops the timer; re-enabling or re-showing restarts it.
• Blocks inherit the track's curvature. At the default stadium setting each block is drawn as a small capsule rather than a rectangle, because the curvature is clamped to half the block's own shorter side. Call PsProgressBar_SetCurvature( hBar, 0 ) for square blocks, or a small value such as 3 for softened ones.
• PRG_MARQUEE_WRAP clips its chunk at the track edges. That is what makes it slide in and out rather than snap, so the visible chunk is narrower during the transition. PRG_MARQUEE_BOUNCE never clips — the chunk keeps one width throughout.
• At curvature 0 with no track border, the fill leaves a one-pixel seam down its right edge and along its bottom. This is the rounded-rectangle fill convention the drawing layer uses throughout, matched to what GDI's RoundRect covers. Any curvature above 0 hides it behind the end caps, and a track border of 1 or more covers it.
• PsProgressBar_SetFont borrows the handle. The control never creates or destroys a font; yours must outlive the control.
• There is no PsProgressBar_HitTest. The whole client is the same inert surface.
• No accessibility support. The control does not expose itself to screen readers.

---

API reference

Creation and lifetime

Range and position

Every function in this group is silent: none of them fires a callback.

Mode and state

Marquee (indeterminate mode)

Setting any of these while in determinate mode is legal and simply has no visible effect until you switch.

Fill style and segmentation

These two settings are independent — every combination of them is legal.

Geometry and chrome

Setters here take raw pixels. Only the creation-time defaults are DPI-scaled for you; scale your own values with CWindow::ScaleX / ScaleY.

Text

Colors

Tooltips

Tooltips: two backends

The control ships on the system (comctl32) tooltip. PSTIP_MODE_PS switches this instance to PsTooltip: owner-drawn, themeable, word-wrapping without a hand-sent TTM_SETMAXTIPWIDTH, and — the one that matters structurally — not a subclass of the control it serves. Either way the control adds no pump obligation: PsTooltip has no FilterMessage.

The default is deliberate, not caution. PsTooltip's colour defaults are dark, so a control that switched itself would put a dark tip on a light form. Theme every tip in the process with PsTooltip_SetDefaultColors and friends, then opt in per instance.

The mode changes how a tip is drawn, never what it says. Both backends resolve text through the same rule — this control's own text first, then PRG_TooltipCallbackFunc, then nothing.

The three delay setters are the control's only ones; before them a tip ran at whatever the backend derived and there was no way to say otherwise. A delay you set is stored as well as pushed, so it survives a switch in either direction. A delay you never set keeps the backend's own derivation from the system double-click time, which is what makes a tip appear on the same beat as every other tip on the machine.

PsTooltip_SetDefaultColors( @myTipColors )     ' once, at startup, for every tip in the process
PsTooltip_SetDefaultFonts( ghFontUI )

PsProgressBar_SetTooltipMode( hBar, PSTIP_MODE_PS )
PsProgressBar_SetHoverTime( hBar, 400 )
dim as HWND hTip = PsProgressBar_GetPsTooltipHandle( hBar )
if hTip then PsTooltip_SetTitle( hTip, "Copying files" )   ' not reachable on the system backend

Callback registration

Render probes

These render the control offscreen and measure the result. They exist so that a host supplying its own paint callback can assert it has not accidentally erased the control — the standing hazard described under Callbacks.

Pure functions

These take no window and touch no state. They are the arithmetic the control itself uses, exposed so you can predict or reproduce it.

PsProgressBar_ComputeMarqueeOffset's two ranges:

---

Colors

PSPROGRESSBAR_COLORS is a flat struct of COLORREF fields, all with defaults. Read-modify-write:

dim as PSPROGRESSBAR_COLORS clrs
PsProgressBar_GetColors( hBar, @clrs )
clrs.BarColor    = BGR( 62,140, 90)
clrs.BarColorEnd = BGR( 40,100, 62)
PsProgressBar_SetColors( hBar, @clrs )

Bar colour precedence: disabled > PRG_STATE_ERROR > PRG_STATE_PAUSED > PRG_STATE_NORMAL. Disabled wins outright — a paused-and-disabled bar draws grey, not yellow.

With PRG_FILL_SOLID only the first stop of the chosen pair is used; the *End field is ignored. That means one set of colours serves both fill styles and switching between them needs no changes.

---

Callbacks

Paint

type PRG_PaintCallbackSub as sub( byval p as PSPROGRESSBAR_PAINTINFO ptr )

Replaces the built-in painter entirely. Draw through p->b — the control's double buffer for this repaint — and never touch the screen DC. The client has already been filled with BackColor before you are called, so a callback that only adds something on top does not have to repaint the background.

A callback that fills a rectangle covering the whole control erases everything already drawn. PsBufferPaint's PaintBorderRect and PaintRoundBorderRect fill before they stroke, so using either as a frame over your own drawing wipes it out. Use PaintRoundOutline, which strokes only. PsProgressBar_CountRenderedTones exists so you can assert you have not done this.

PSPROGRESSBAR_PAINTINFO

Message

type PRG_MessageCallbackFunc as function( byval m as PSPROGRESSBAR_MESSAGEINFO ptr ) as boolean

Return TRUE if you handled the message and want the control's default handling suppressed, FALSE to let it proceed.

Every message is offered and every answer is honoured, with one exception: WM_DESTROY and WM_NCDESTROY are never offered at all. They free the control's state and its tooltip window, and a callback suppressing either would leak both.

There are no other exemptions. Controls that take mouse capture have to ignore your answer for the button-up messages, or a callback could strand the capture; this control takes no capture, has no press gesture and no focus, so everything it offers you is genuinely suppressible. This is also the only place the control can be made interactive, since it never acts on a click itself.

PSPROGRESSBAR_MESSAGEINFO

Tooltip

type PRG_TooltipCallbackFunc as function( byval hProgressBar as HWND ) as DWSTRING

Called only when a tip is about to show, and only when the control has no tooltip text of its own. Return "" for no tooltip. There is no fallback to the displayed percentage — a bar with neither authored text nor a callback answer shows nothing.

Text

type PRG_TextCallbackFunc as function( byval hProgressBar as HWND, _
                                       byval nPos as long, _
                                       byval nMin as long, _
                                       byval nMax as long ) as DWSTRING

Consulted only in PRG_TEXT_CALLBACK mode, and called on every repaint — keep it cheap, and do not create windows in it. Returning "" draws nothing. If the mode is set but no callback is installed, nothing is drawn.

---

Constants

Orientation — fixed at creation

Mode

Marquee style

Fill style

State

Text mode

Probe parts

Defaults

The range defaults to 0..100, the position to 0, and the step to 10.

Licence

Mozilla Public License 2.0.

MPL-2.0 is file-level copyleft, chosen deliberately for a drop-in control:

• You may use this in closed-source software, commercial or otherwise. §3.2 permits static linking with no additional conditions.
• If you modify these files, publish those files' changes. The obligation is per-file — your own sources are unaffected however tightly they are combined with these.
• The Exhibit B "Incompatible With Secondary Licenses" notice is not applied, which keeps this GPL-compatible.