PsChart

An owner-drawn chart control for FreeBASIC / Win32, built on the AfxNova framework.

One control draws four kinds of chart: a line chart of one or more series, a column chart with the series grouped side by side, an HLOC (high-low-open-close) price chart, and a pie chart that can also be drawn as a doughnut with slices pulled out of it. You choose which when you create the control, and it stays that kind for its lifetime.

You hand it series and points; it works out everything else. It picks readable gridline values, measures the widest axis label and reserves a gutter for it, spaces the categories evenly and drops every Nth category label when they would otherwise collide. An optional legend and an optional title and subtitle take their space out of the plot before the plot is measured, so turning either on never overlaps anything.

It is a display control. It takes no focus, no keyboard and no mouse capture, and clicking it does nothing. The one thing it tracks is the data point under the cursor, which drives a tooltip naming that point and a callback you can hook. Every message it receives is offered to your message callback first, so anything interactive — click-to-drill-down being the obvious case — is yours to add.

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

What it looks like

Six charts from the demo: line with three series (the third smoothed, with markers), grouped columns, 60 HLOC bars with the date labels auto-skipped, a pie with its values inside the wedges, a doughnut with one slice exploded and name/percent labels on leader lines, and columns straddling zero.

Requirements

PsChart_SetSeriesSymbol draws its markers with geometry, not glyphs, so there is no font file to ship.

Include order

Include the .inc files in this order, once, from your main module:

#include once "PsBufferPaint.inc"
#include once "PsChart.inc"

PsChart.inc pulls in PsChart.bi (which includes PsBufferPaint.bi and PsTipHost.bi) and PsTipHost.inc itself, so those four need no line of their own. PsBufferPaint.inc must come first.

GDI+ must be running

Every wedge, polyline, bar and gridline is drawn through GDI+. Start it before the first repaint and shut it down after every window is destroyed:

dim as ULONG_PTR gdipToken = AfxGdipInit()
frmMain_Show( 0 )
AfxGdipShutdown( gdipToken )

Without the bracket the control draws nothing at all — it does not fail loudly.

Do not name anything ok

GDI+ defines Ok = 0 as a Status enum value in namespace AfxNova, and your host almost certainly says using AfxNova. Any identifier of yours named ok — a variable, a parameter, in any casing, because FreeBASIC is case-insensitive — becomes a duplicate definition the moment you include this control. Name yours bOK.

For the same reason, avoid parameter names that collide with the C runtime declarations AfxNova pulls in: fOpen, fClose, fMin and fMax are all real functions (fopen, fclose, fmin, fmax) and a parameter of any of those names will not compile.

There is no pump obligation

There is no PsChart_FilterMessage. The control needs nothing added to your message loop. It takes no focus, so it needs no IsDialogMessage handling and no startup SetFocus either.

Quick start

dim as HWND hChart = PsChart_Create( hWndParent, IDC_MYCHART, PSCHART_TYPE_COLUMN )
PsChart_SetFont( hChart, ghFont(GUIFONT_9) )

' Bracketed so the control lays out once and repaints once, not per point.
PsChart_BeginUpdate( hChart )
dim as long s1 = PsChart_AddSeries( hChart, "Series 1" )
PsChart_AddPoint( hChart, s1, "Oranges",    1.0 )
PsChart_AddPoint( hChart, s1, "Apples",     4.0 )
PsChart_AddPoint( hChart, s1, "Pears",      5.0 )
dim as long s2 = PsChart_AddSeries( hChart, "Series 2" )
PsChart_AddPoint( hChart, s2, "Oranges",    7.0 )
PsChart_AddPoint( hChart, s2, "Apples",     3.0 )
PsChart_AddPoint( hChart, s2, "Pears",      8.0 )
PsChart_EndUpdate( hChart )

PsChart_SetLegendVisible( hChart, true )
PsChart_SetHotChangeCallback( hChart, @MyChart_HotChange )

The control has no opinion about where it sits — position it yourself from your WM_SIZE:

SetWindowPos( hChart, 0, rc.left, rc.top, rc.right - rc.left, rc.bottom - rc.top, SWP_NOZORDER )

And the callback it references:

sub MyChart_HotChange( byval hChart as HWND, byval iSeries as long, byval iPoint as long )
    if iPoint < 0 then exit sub          ' the cursor left the data
    dim as DWSTRING wszName = PsChart_GetPointLabel( hChart, iSeries, iPoint )
    dim as double   fValue  = PsChart_GetPointValue( hChart, iSeries, iPoint )
end sub

Concepts

The handle is a real HWND

PsChart_Create returns an ordinary child window. SetWindowPos, ShowWindow, EnableWindow, GetParent and DestroyWindow all work on it directly and there is no wrapper for any of them. The control never positions itself.

The chart type is fixed at creation

PsChart_Create takes the type and there is no setter for it. The four types do not share a data shape — a pie has no value axis, and an HLOC point carries four numbers where a column point carries one — so a control that could switch types would have to tolerate data authored for a type it is no longer showing. Create a second control instead.

Series and points

A series is what the legend names and what the palette colours: one line, or one set of bars. A point is one datum in a series. Series are indexed from 0 in creation order, and points from 0 within their series.

Categories along the X axis are positional: point 3 of every series lines up, whatever its label says. Only series 0's labels are drawn on the axis — a second series' labels are still carried, and a tooltip can use them, but two series disagreeing about what category 3 is called has no rendering that is not a lie. The number of categories is the length of the longest visible series, so a series with fewer points simply stops early.

A pie reads only series 0, and enumerates the palette per point rather than per series: on a pie the slices are what the colours have to distinguish.

The value axis is derived, not set

Unless you turn autoscaling off, the control scans every visible series for its minimum and maximum, then snaps the range outward to gridlines a human would have chosen — the step is always 1, 2 or 5 times a power of ten:

step  = the 1/2/5 x 10^n nearest (range / tick hint)
min   = floor( data minimum / step ) * step
max   = ceil ( data maximum / step ) * step

The bounds widen to that step deliberately: a top gridline exactly at the highest datum puts the tallest bar flush against the edge of the plot with nothing above it.

Two type-specific rules ride on top:

• A column chart forces zero into the range, because bars are drawn from a baseline and a baseline that is not zero makes a bar four times taller than its neighbour for a value twice as large. If the data straddles zero the origin therefore sits inside the plot and negative bars hang below it.
• A line or HLOC chart does not. A price series trading at 1,120 plotted against a zero baseline is a flat line across the top of the plot.

An HLOC chart takes its range from the low and high of each point, never from the close.

Rects are the control's, and layout owns them

rcPlot, the axis gutters, the legend block and the title strips are all derived from the client rect and the measured text — you never set one. Layout is lazy: a mutator marks it stale and the next repaint recomputes it, so populating a thousand points costs one layout. Every geometry query (PsChart_GetPlotRect, PsChart_GetPointRect, PsChart_HitTest, PsChart_ValueToY) forces a pending layout first, so none of them can answer from stale numbers.

The same rects drive both the renderer and the hit test, which is what makes "the tooltip named a different bar than the one under the cursor" impossible rather than merely unlikely.

Everything is silent except the mouse

Every setter here is silent: adding a point, hiding a series, changing a colour and re-ranging the axis all repaint and fire nothing. Only user interaction notifies — which in this control means only the hot point changing under the cursor. That makes it safe to call any function from inside any callback.

Raw pixels; you scale

Only the create-time defaults are DPI-scaled for you. Every size you pass afterwards — PsChart_SetPadding, PsChart_SetBarGap, PsChart_SetPointExplode, symbol sizes, line widths — is in device pixels, and you scale it: pWindow->ScaleX( 14 ). Gridline and axis thickness are never scaled, because a hairline should stay a hairline.

Fonts are borrowed

The control never owns an HFONT and never destroys one. Whatever you pass to PsChart_SetFont, PsChart_SetTitleFont or PsChart_SetSubtitleFont stays yours to delete. Unset title and subtitle fonts fall back to the label font.

Behaviour and limits

• The chart type cannot change after PsChart_Create.
• Column charts are grouped only. There is no stacked mode and no horizontal (bar) orientation.
• Line charts have no area fill under the line.
• A pie reads series 0 only. Additional series on a pie chart are ignored.
• PsChart_SetPointExplode is pie-only and always addresses series 0.
• A horizontal legend gets one row. Entries that do not fit are dropped rather than drawn over the plot. Use a left or right legend when you have many series.
• Slice labels can be dropped. In CHT_PIEPLACE_INSIDE, a label wider than its wedge's chord is not drawn at all. CHT_PIEPLACE_AUTO (the default) promotes those to an outside leader instead, and never silently drops one.
• A zero-valued column draws nothing — a zero-height bar would put a stray hairline on the baseline where the data says there is nothing — and therefore cannot be hit-tested.
• A zero-valued pie slice draws nothing and has no sweep.
• The X axis is categorical. Points are evenly spaced whatever their labels say, so a gap in a date sequence is not a gap on the axis.
• Supplying a paint callback replaces the entire renderer — plot, axes, legend and chrome. It is all-or-nothing.
• Single-threaded. UI thread only.

API reference

Creation and type

Destroy it with DestroyWindow; the control frees its own state and tooltip.

Series

Points

Bulk population

Value axis

Title, subtitle and legend

The control also honours WM_SETFONT / WM_GETFONT, which set and read the label font.

Column charts

A bar narrower than one pixel is drawn as a one-pixel hairline rather than vanishing — the chart is too narrow for the data, and a hairline says so where nothing does not.

HLOC charts

Each bar is a vertical high-to-low line with the open ticked to the left and the close ticked to the right. The hit band is the whole category slot, not the two-pixel line.

Pie charts

Wedge sweeps come from the absolute value of each point over the sum of absolute values, so a negative datum still gets a proportional slice instead of silently making the remaining wedges add up to more than their total.

Colours

Query and hit testing

Tooltips

The tooltip text is resolved in this order: text you set with PsChart_SetTooltipText, then your tooltip callback, then the control's own description of the hot point. There is no caption fallback — a chart has no caption of its own.

The control's own description is the point's label plus its value; on a multi-series chart the series name is included, on a pie the share as a percentage, and on an HLOC chart all four of O H L C.

Callback registration

Passing 0 to any of these removes the callback.

Render probes

Both render the control offscreen through the same function WM_PAINT uses, then read the resulting pixels on a fixed 32×32 sample grid. They exist so a regression check measures what is actually drawn rather than a parallel implementation of it. Neither touches the screen.

Both return 0 if the control has no client area yet.

Colors

PSCHART_COLORS, read and written whole:

dim as PSCHART_COLORS clrs
PsChart_GetColors( hChart, @clrs )
clrs.BackColor = BGR(255,255,255)
clrs.GridColor = BGR(220,220,220)
PsChart_SetColors( hChart, @clrs )

SliceGapColor defaults equal to BackColor, which is what makes the default pie read as wedges separated by the background rather than as an outlined disc.

Series colours are not in this struct. They resolve in this order: an explicit per-point colour, then an explicit per-series colour, then the palette. On a pie the palette is indexed by point; everywhere else by series. The ten palette defaults are a blue, orange, green, magenta, yellow, teal, red, periwinkle, tan and grey, wrapping after ten.

Callbacks

Paint

type CHT_PaintCallbackSub as sub( byval p as PSCHART_PAINTINFO ptr )

Fires once per repaint, after the control has filled the background and resolved every rect. Supplying one replaces the entire default renderer — the plot, the axes, the gridlines, the legend and the chrome. This is not the additive kind of paint callback: draw the chart yourself, or do not set one.

Draw through p->b, which is the control's own PsBufferPaint for this repaint. Never build a second GDI+ Graphics on its DC, and never touch the screen DC.

Every sentinel is already resolved: fMin/fMax/fStep are the real range even when autoscaling, nDecimals is the derived count and never −1, and nLabelStride is the measured skip and never 0.

PSCHART_PAINTINFO

Message

type CHT_MessageCallbackFunc as function( byval m as PSCHART_MESSAGEINFO ptr ) as boolean

Fires for every message the control receives except WM_DESTROY and WM_NCDESTROY — offering those would let a callback suppress the cleanup that frees the state it is holding a pointer to. Return TRUE to suppress the control's own handling of that message, FALSE to let it proceed.

WM_LBUTTONUP's return value is ignored. Nothing here takes mouse capture today, but the rule stands so that a control which later does cannot be stranded by a callback that swallowed the up-message that would have released it.

PSCHART_MESSAGEINFO

Tooltip

type CHT_TooltipCallbackFunc as function( byval hChart as HWND ) as DWSTRING

Consulted when no text was set with PsChart_SetTooltipText. Return "" to fall through to the control's own description of the hot point. Call PsChart_GetHotPoint inside it to find out what the cursor is over.

Value label

type CHT_ValueLabelCallbackFunc as function( byval hChart as HWND, byval fValue as double, _
                                             byval nContext as long ) as DWSTRING

Formats one number. nContext is CHT_FMT_AXIS, CHT_FMT_PIELABEL or CHT_FMT_TOOLTIP, so one function can format an axis tick and a tooltip differently. Return "" to fall back to the control's own formatting, which lets you special-case a few values without formatting all of them.

Axis labels are measured to size the value gutter, so a callback that returns much wider strings widens the gutter rather than overlapping the plot.

Hot change

type CHT_HotChangeCallbackSub as sub( byval hChart as HWND, byval iSeries as long, _
                                      byval iPoint as long )

Fires when the data point under the cursor changes, including to -1, -1 when the cursor leaves the data or the control. User interaction only — a programmatic change that happens to move data under the cursor does not fire it. It fires after the state is updated, so PsChart_GetHotPoint inside the handler already reports the new point.

Constants

Chart type

Line symbols

CHT_SYM_NONE (the default), CHT_SYM_CIRCLE, CHT_SYM_SQUARE, CHT_SYM_DIAMOND, CHT_SYM_TRIANGLE.

Legend position

CHT_LEGEND_BOTTOM (the default), CHT_LEGEND_TOP, CHT_LEGEND_LEFT, CHT_LEGEND_RIGHT. Top and bottom lay the entries out in one row; left and right in a column.

Pie label mode

Pie label placement

Value-label context

CHT_FMT_AXIS, CHT_FMT_PIELABEL, CHT_FMT_TOOLTIP.

Sentinels

Defaults

The size values are DPI-scaled once, when the control is created. PSCHART_DEFAULT_PIEGAP and the gridline and axis thicknesses are not, ever.

Related controls

PsChart draws through PsBufferPaint and shows its tooltips through PsTooltip when you switch it to PSTIP_MODE_PS. See those documents for the drawing surface's primitives and the tooltip's own styling functions — the tooltip's colours, fonts and glyph are set on the tooltip, not mirrored here.

Licence

Mozilla Public License 2.0. See LICENSE.