Custom CheckBox Component for QuickReportQuickReport is a powerful reporting framework used in many Delphi and C++Builder applications for designing and printing reports. While it provides a solid set of standard components, creating custom visual and data-aware components—such as a CheckBox—can make your reports more user-friendly, clearer, and tailored to the needs of your application. This article walks through the design, implementation, and usage of a custom CheckBox component for QuickReport, with examples, considerations for data-binding, printing fidelity, and styling.
Why create a custom CheckBox for QuickReport?
- Visual clarity: Many reports require checkboxes to convey binary choices (Yes/No, Active/Inactive). A visual checkbox is more immediately understandable than text values like “⁄0” or “Y/N”.
- Consistency: A reusable component ensures the same appearance and behavior across multiple reports.
- Data-binding: A component that can read boolean or enumerated fields directly from a dataset reduces template logic and simplifies report maintenance.
- Printing control: QuickReport’s canvas-based rendering requires careful handling to ensure checkboxes print crisply and align with other report elements.
Design goals
Before coding, define what your CheckBox component should do:
- Render a checkbox (checked/unchecked) on the report preview and printed output.
- Bind to a DataSet field (Boolean, integer, or string) with optional value mappings.
- Support custom captions or no caption (just the box).
- Offer styling options: box size, border color/width, fill color, check-mark style (X, tick), alignment, font for caption.
- Support transparent background and proper layering with other QuickReport components.
- Measure and align correctly within band layouts; participate in QuickReport’s autosizing and stretching behaviors if needed.
- Handle Null values gracefully (e.g., treat as unchecked or show an indeterminate state).
Component architecture
A QuickReport visual component typically descends from TQRPrintable or TQRCustomControl (names vary by QuickReport version). The custom CheckBox will:
- Expose published properties for design-time configuration: DataField, DataSource, CheckedValue, UncheckedValue, Caption, BoxSize, Pen, Brush, CheckStyle, WordWrap, Alignment.
- Override the painting routine to draw checkbox and caption on the QRCanvas used by QuickReport.
- Implement data-binding behavior: in the BeforePrint or OnPrint event (or overridden method), read the field value and set an internal state used by painting.
- Support design-time preview by reading sample values or a design-time property.
High-level class outline (Delphi-style pseudocode):
type TQRCheckBox = class(TQRPrintable) private FDataField: string; FDataSource: TDataSource; FCaption: string; FBoxSize: Integer; FCheckedValue: string; FUncheckedValue: string; FCheckStyle: TCheckStyle; // e.g., csTick, csCross FAlignment: TAlignment; FIsChecked: Boolean; procedure SetDataField(const Value: string); ... protected procedure Paint; override; // or QuickReport-specific PaintToCanvas method procedure BeforePrint; override; // read data field and set FIsChecked public constructor Create(AOwner: TComponent); override; published property DataField: string read FDataField write SetDataField; property DataSource: TDataSource read FDataSource write FDataSource; property Caption: string read FCaption write FCaption; property BoxSize: Integer read FBoxSize write FBoxSize default 12; property CheckedValue: string read FCheckedValue write FCheckedValue; property UncheckedValue: string read FUncheckedValue write FUncheckedValue; property CheckStyle: TCheckStyle read FCheckStyle write FCheckStyle; property Alignment: TAlignment read FAlignment write FAlignment default taLeftJustify; ... end; Painting the checkbox
QuickReport uses its own QRCanvas abstraction, but drawing primitives are similar to VCL’s Canvas. The painting routine must:
- Draw the box (rectangle) with Pen and Brush settings.
- If checked, draw the check mark (line segments or a glyph).
- Draw the caption text, respecting alignment, WordWrap, and Font.
- Respect Transparent property—if transparent, don’t fill the background rectangle.
- Handle high-DPI and scaling by using element dimensions relative to the component’s PixelPerInch or Report DPI.
Example painting pseudocode:
procedure TQRCheckBox.Paint; var BoxRect, TextRect: TRect; CX: Integer; begin // Compute box rectangle based on alignment and BoxSize BoxRect := Rect(Left, Top, Left + FBoxSize, Top + FBoxSize); // Draw box border Canvas.Pen.Color := Self.Pen.Color; Canvas.Brush.Style := Self.Transparent ? bsClear : bsSolid; Canvas.Rectangle(BoxRect); // Draw check if needed if FIsChecked then begin Canvas.Pen.Color := CheckMarkColor; case FCheckStyle of csTick: DrawTick(Canvas, BoxRect); csCross: DrawCross(Canvas, BoxRect); end; end; // Draw caption TextRect := Rect(BoxRect.Right + 2, Top, Self.Width, Self.Height); DrawText(Canvas.Handle, PChar(FCaption), Length(FCaption), TextRect, DT_LEFT or DT_VCENTER or DT_SINGLELINE); end; Tip: use DrawText with DT_CALCRECT to support word wrap and multi-line captions.
Data-binding and value mapping
The component should accept multiple field types. Implement logic in BeforePrint (or its equivalent) to evaluate the field:
- If Field.DataType = ftBoolean: FIsChecked := Field.AsBoolean.
- If numeric: treat non-zero as checked.
- If string: compare trimmed value with CheckedValue/UncheckedValue properties; support case-insensitive match.
- If Field.IsNull: respect a NullStyle property (nsUnchecked, nsChecked, nsIndeterminate).
Provide example code:
procedure TQRCheckBox.BeforePrint; var Field: TField; s: string; begin inherited; FIsChecked := False; if Assigned(FDataSource) and Assigned(FDataSource.DataSet) and (FDataSource.DataSet.Active) then begin Field := FDataSource.DataSet.FindField(FDataField); if Assigned(Field) then begin if Field.IsNull then begin // handle null per NullStyle end else case Field.DataType of ftBoolean: FIsChecked := Field.AsBoolean; ftInteger, ftSmallint, ftWord: FIsChecked := Field.AsInteger <> 0; ftString, ftMemo, ftWideString: begin s := Trim(Field.AsString); FIsChecked := SameText(s, FCheckedValue); end; else FIsChecked := Trim(Field.AsString) <> ''; end; end; end; end; Handling indeterminate state
Some reports need to show a third “indeterminate” or “unknown” state. Options:
- Draw a hyphen or shaded box when NullStyle = nsIndeterminate.
- Expose a property IndeterminateGlyph: TBitmap to allow custom glyphs for that state.
- Map database NULL explicitly via NullStyle property.
Design-time support
- Register the component in the IDE so developers can drop it on QuickReport bands.
- Provide default sample data or a design-time property to preview states.
- Expose an OnDraw or OnGetChecked event so developers can override logic without subclassing.
Printing considerations
- Ensure the drawing uses QuickReport’s QRCanvas so output to printers and previews match.
- Avoid GDI objects leaking: create pens/brushes/bitmaps locally or free them after use.
- For sharp printing, draw simple vector lines for checkmarks instead of bitmaps.
- Test with different printers and resolutions; consider rounding coordinates to integer pixels for thinner lines.
Accessibility and localization
- Use caption and hints that can be localized.
- If the report is to be consumed electronically (PDF), ensure text captions remain selectable/searchable where needed — prefer drawing text with the QRCanvas text methods rather than embedding text in images.
- Allow Right-to-Left alignment for languages like Arabic or Hebrew.
Example usage in a report
- Drop TQRCheckBox onto a detail band.
- Set DataSource to your dataset component and DataField to “IsActive”.
- Set CheckedValue to “Y” if the field is a string storing ‘Y’/‘N’, or leave defaults for boolean fields.
- Adjust BoxSize, Caption, and Alignment.
This results in each record printing a checkbox that reflects the dataset’s value.
Performance tips
- Keep drawing operations minimal—avoid complex bitmap operations in large datasets.
- If printing large data sets, test time-to-render; measuring and caching glyph shapes can help.
- Use simple geometric check marks (two lines) rather than complex shapes.
Example enhancements and variants
- Read-only interactive preview: allow preview toggling of checkboxes in report preview for interactive reports.
- Animated preview (for design-time only) to show transitions between states.
- Grouped checkbox behavior: multiple checkboxes representing an enum where only one can be checked (radio-like behavior).
- Export-friendly modes: ensure the component exports to PDF/SVG with vector check marks.
Troubleshooting common issues
- Checkbox misalignment: ensure Font and BoxSize match band height; use Margins and Padding properties.
- Blurry print output: use vector drawing, not scaled bitmaps; round coordinates.
- Data not reflected: verify DataSource is active and DataField spelled correctly; use OnGetChecked event to debug.
Conclusion
A custom CheckBox component for QuickReport improves readability, enforces consistency, and reduces template logic across reports. With careful attention to data-binding, painting, and printing behavior, such a component becomes a small but powerful enhancement to your reporting toolkit. The architecture described above provides a flexible starting point to implement features like indeterminate states, custom glyphs, and localized captions. Building and registering the component in the IDE makes it accessible to report designers and keeps your reports consistent across projects.
Leave a Reply