TTMSFNCWXQRCode

The TTMSFNCWXQRCode is a component to generate and display highly customizable QR codes. It uses the EasyQRCodeJS JavaScript library.

Notice

With the default settings this component requires an internet connection. If you'd like to run the component in an offline environment, please change the LibraryLocation property. Read more about this at the Loading modes section of this documentation.

Creating QR codes

Creating a QR code is as simple as setting the Text property either at design time or at runtime. The QR code is regenerated automatically whenever Text or any setting changes.

procedure TForm1.Button1Click(Sender: TObject);
begin
  TMSFNCWXQRCode1.Text := 'https://www.tmssoftware.com';
end;

Error correction level

The ErrorCorrectionLevel property controls how much data redundancy is built into the QR code. Higher levels allow the code to be read even when partially damaged or obscured, but result in a denser code.

Value	Level	Recovery capacity
`eclL`	Low	~7%
`eclM`	Medium (default)	~15%
`eclQ`	Quartile	~25%
`eclH`	High	~30%

procedure TForm1.Button1Click(Sender: TObject);
begin
  TMSFNCWXQRCode1.ErrorCorrectionLevel := eclH;
  TMSFNCWXQRCode1.Text := 'https://www.tmssoftware.com';
end;

QR code version (ModuleVersion)

The ModuleVersion property sets the QR code version (1–40). Each version defines the number of modules (dots) in the code and therefore its data capacity. Version 1 is the smallest (21×21 modules) and version 40 is the largest (177×177 modules).

Setting ModuleVersion to 0 (the default) causes the component to automatically select the smallest version that can encode the given Text at the current ErrorCorrectionLevel.

// Force at least version 5 (37x37 modules)
TMSFNCWXQRCode1.ModuleVersion := 5;

The table below shows the maximum character capacity for alphanumeric data at each error correction level for selected versions:

Version	L	M	Q	H
1	17	14	11	7
5	106	84	60	44
10	271	213	151	119
20	858	666	482	382
40	2953	2331	1663	1273

Retrieving QR codes

To retrieve the generated QR code as a bitmap, implement the OnGetQRCode event. The event fires every time the QR code is rendered.

procedure TForm1.TMSFNCWXQRCode1GetQRCode(Sender: TObject;
  ABitmap: TTMSFNCBitmap);
begin
  // Save to a file
  ABitmap.SaveToFile('C:\Temp\qrcode.png');
end;

The ABitmap parameter is a TTMSFNCBitmap containing the rendered QR code image. The bitmap is owned by the event; do not free it inside the handler.

Customization

All visual customization options are grouped under the Settings property of type TTMSFNCWXQRCodeSettings.

Colors

Property	Description	Default
`Settings.ColorDark`	Color of the dark modules	`gcBlack`
`Settings.ColorLight`	Color of the light modules	`gcWhite`

TMSFNCWXQRCode1.Settings.ColorDark := gcNavy;
TMSFNCWXQRCode1.Settings.ColorLight := gcLightcyan;

Dot scale

The dot scale properties shrink the rendered dots below their full module size, giving the QR code an open, airy appearance. All values are in the range 0.0–1.0, where 1.0 (the default) means full-size dots.

Property	Affects
`Settings.DotScale`	All data modules
`Settings.DotScaleTimingVertical`	Vertical timing pattern
`Settings.DotScaleTimingHorizontal`	Horizontal timing pattern
`Settings.DotScaleAlignOuter`	Outer squares of alignment patterns
`Settings.DotScaleAlignInner`	Inner dots of alignment patterns

TMSFNCWXQRCode1.Settings.DotScale := 0.7;
TMSFNCWXQRCode1.Settings.DotScaleAlignOuter := 0.8;
TMSFNCWXQRCode1.Settings.DotScaleAlignInner := 0.6;

Position detection colors

The three large square "finder patterns" at the corners of the QR code can be colored independently. Each pattern has an outer ring and an inner dot.

The Settings.PositionColor sub-property exposes six color values:

Property	Corner	Part
`TopLeftOuterColor`	Top-left	Outer ring
`TopLeftInnerColor`	Top-left	Inner dot
`TopRightOuterColor`	Top-right	Outer ring
`TopRightInnerColor`	Top-right	Inner dot
`BottomRightOuterColor`	Bottom-left	Outer ring
`BottomRightInnerColor`	Bottom-left	Inner dot

TMSFNCWXQRCode1.Settings.PositionColor.TopLeftOuterColor    := gcDodgerblue;
TMSFNCWXQRCode1.Settings.PositionColor.TopLeftInnerColor    := gcDodgerblue;
TMSFNCWXQRCode1.Settings.PositionColor.TopRightOuterColor   := gcDodgerblue;
TMSFNCWXQRCode1.Settings.PositionColor.TopRightInnerColor   := gcDodgerblue;
TMSFNCWXQRCode1.Settings.PositionColor.BottomRightOuterColor := gcDodgerblue;
TMSFNCWXQRCode1.Settings.PositionColor.BottomRightInnerColor := gcDodgerblue;

Timing pattern colors

The thin lines that connect the finder patterns can also be recolored:

TMSFNCWXQRCode1.Settings.TimingHorizonalColor := gcDeepskyblue;
TMSFNCWXQRCode1.Settings.TimingVerticalColor  := gcDeepskyblue;

Quiet zone

The quiet zone is a margin of empty modules surrounding the QR code. A wider quiet zone makes the code easier to scan in dense layouts.

TMSFNCWXQRCode1.Settings.QuietZone      := 20;
TMSFNCWXQRCode1.Settings.QuietZoneColor := gcWhitesmoke;

Title and subtitle

The QR code can display a text title above the image and an optional subtitle.

Property	Description	Default
`Title`	Title text drawn above the QR code	`''`
`Settings.TitleFont`	Font for the title	System default
`Settings.TitleBackgroundColor`	Background fill behind the title	`gcWhite`
`Settings.TitleHeight`	Height of the title area (px)	`0`
`Settings.TitleTop`	Vertical offset of the title text (px)	`30`
`SubTitle`	Subtitle text drawn above the title	`''`
`Settings.SubTitleFont`	Font for the subtitle	System default
`Settings.SubTitleTop`	Vertical offset of the subtitle text (px)	`0`

TMSFNCWXQRCode1.Title    := 'Scan to visit';
TMSFNCWXQRCode1.SubTitle := 'www.tmssoftware.com';
TMSFNCWXQRCode1.Settings.SubTitleTop := 10;
TMSFNCWXQRCode1.Settings.TitleHeight := 50;
TMSFNCWXQRCode1.Settings.TitleBackgroundColor := gcWhitesmoke;

Note

TitleHeight must be set to a positive value for the title to be visible. The height is subtracted from the QR code area, so increase the component's Height accordingly.

Logo overlay

An image can be placed in the center of the QR code. Because the logo occludes data modules, a higher ErrorCorrectionLevel (eclQ or eclH) is recommended when using a logo.

Property	Description	Default
`Logo`	`TTMSFNCBitmap` displayed at the center	(empty)
`Settings.LogoWidth`	Logo width in pixels; `-1` = auto (size/3.5)	`-1`
`Settings.LogoHeight`	Logo height in pixels; `-1` = auto (size/3.5)	`-1`
`Settings.LogoMaxWidth`	Maximum logo width constraint in pixels; `-1` = none	`-1`
`Settings.LogoMaxHeight`	Maximum logo height constraint in pixels; `-1` = none	`-1`
`Settings.LogoBackgroundColor`	Background color behind the logo	`gcWhite`
`Settings.LogoBackgroundTransparent`	Whether the logo background is transparent	`False`

TMSFNCWXQRCode1.ErrorCorrectionLevel := eclH;
TMSFNCWXQRCode1.Logo.LoadFromFile('C:\Images\logo.png');
TMSFNCWXQRCode1.Settings.LogoWidth  := 60;
TMSFNCWXQRCode1.Settings.LogoHeight := 60;
TMSFNCWXQRCode1.Settings.LogoBackgroundTransparent := True;

Background image

A background image can be placed behind the QR code modules.

Property	Description	Default
`BackgroundImage`	`TTMSFNCBitmap` used as the background	(empty)
`Settings.BackgroundImageAlpha`	Opacity of the background image (`0.0`–`1.0`)	`1.0`
`Settings.BackgroundAutoColor`	Derive module colors from the background image	`False`
`Settings.AutoColorDark`	Fallback dark color used with `BackgroundAutoColor`	`gcBlack`
`Settings.AutoColorDarkAlpha`	Alpha of the auto dark color	`0.6`
`Settings.AutoColorLight`	Fallback light color used with `BackgroundAutoColor`	`gcWhite`
`Settings.AutoColorLightAlpha`	Alpha of the auto light color	`0.7`

TMSFNCWXQRCode1.BackgroundImage.LoadFromFile('C:\Images\background.jpg');
TMSFNCWXQRCode1.Settings.BackgroundImageAlpha := 0.4;
TMSFNCWXQRCode1.Settings.BackgroundAutoColor  := True;

AutoCenter

When AutoCenter is True (the default), the QR code image is centered both horizontally and vertically within the component bounds using CSS flexbox. Set it to False if you want to control the alignment yourself.

CrossOrigin

Use CrossOrigin when the Logo or BackgroundImage is loaded from a remote URL and the server requires a CORS preflight:

Value	Description
`coNull` (default)	No `crossOrigin` attribute
`coAnonymous`	Sets `crossOrigin="anonymous"` on the image request

Customization example

procedure TForm1.Button1Click(Sender: TObject);
begin
  TMSFNCWXQRCode1.Text := 'my cusomized barcode';
  TMSFNCWXQRCode1.Settings.ColorDark := gcDeepskyblue;
  TMSFNCWXQRCode1.Settings.ColorLight := gcAzure;
  TMSFNCWXQRCode1.Settings.TimingHorizonalColor := gcDeepskyblue;
  TMSFNCWXQRCode1.Settings.TimingVerticalColor := gcDeepskyblue;
  TMSFNCWXQRCode1.Settings.PositionColor.TopLeftOuterColor := gcDodgerblue;
  TMSFNCWXQRCode1.Settings.PositionColor.TopLeftInnerColor := gcDodgerblue;
  TMSFNCWXQRCode1.Settings.PositionColor.TopRightOuterColor := gcDodgerblue;
  TMSFNCWXQRCode1.Settings.PositionColor.TopRightInnerColor := gcDodgerblue;
  TMSFNCWXQRCode1.Settings.PositionColor.BottomRightOuterColor := gcDodgerblue;
  TMSFNCWXQRCode1.Settings.PositionColor.BottomRightInnerColor := gcDodgerblue
end;

TTMSFNCWXQRCode

Properties reference

TTMSFNCWXQRCode

Property	Type	Default	Description
`AutoCenter`	`Boolean`	`True`	Centers the QR code inside the component
`AutoClearCache`	`Boolean`	—	Clears the internal web browser cache on reinitialize
`BackgroundImage`	`TTMSFNCBitmap`	(empty)	Background image drawn behind the QR modules
`CrossOrigin`	`TTMSFNCWXQRCodeCrossOrigin`	`coNull`	CORS attribute for remote image URLs
`ErrorCorrectionLevel`	`TTMSFNCWXQRCodeErrorCorrectionLevel`	`eclM`	Error correction / redundancy level
`LibraryLocation`	`TTMSFNCWXLibraryLocation`	`llOnline`	Whether to load the JS library online or from resources
`Logo`	`TTMSFNCBitmap`	(empty)	Logo image overlaid at the center of the QR code
`ModuleVersion`	`Byte`	`0`	QR code version (1–40); `0` = auto
`Settings`	`TTMSFNCWXQRCodeSettings`	—	All visual and layout options (see below)
`SubTitle`	`string`	`''`	Subtitle text shown below the title
`Text`	`string`	`'123456'`	Data to encode
`Title`	`string`	`''`	Title text shown below the QR code

TTMSFNCWXQRCodeSettings

Property	Type	Default	Description
`AutoColorDark`	`TTMSFNCGraphicsColor`	`gcBlack`	Auto-color dark value (used when `BackgroundAutoColor = True`)
`AutoColorDarkAlpha`	`Single`	`0.6`	Alpha of the auto dark color
`AutoColorLight`	`TTMSFNCGraphicsColor`	`gcWhite`	Auto-color light value
`AutoColorLightAlpha`	`Single`	`0.7`	Alpha of the auto light color
`BackgroundAutoColor`	`Boolean`	`False`	Derive module colors from the background image
`BackgroundImageAlpha`	`Single`	`1.0`	Opacity of the background image
`ColorDark`	`TTMSFNCGraphicsColor`	`gcBlack`	Color of dark modules
`ColorLight`	`TTMSFNCGraphicsColor`	`gcWhite`	Color of light modules
`DotScale`	`Single`	`1.0`	Scale factor for all data modules
`DotScaleAlignInner`	`Single`	`1.0`	Scale for alignment pattern inner dots
`DotScaleAlignOuter`	`Single`	`1.0`	Scale for alignment pattern outer squares
`DotScaleTimingHorizontal`	`Single`	`1.0`	Scale for horizontal timing modules
`DotScaleTimingVertical`	`Single`	`1.0`	Scale for vertical timing modules
`LogoBackgroundColor`	`TTMSFNCGraphicsColor`	`gcWhite`	Background color behind the logo
`LogoBackgroundTransparent`	`Boolean`	`False`	Whether the logo background is transparent
`LogoHeight`	`Integer`	`-1`	Logo height in pixels (`-1` = auto)
`LogoMaxHeight`	`Integer`	`-1`	Maximum logo height constraint (`-1` = none)
`LogoMaxWidth`	`Integer`	`-1`	Maximum logo width constraint (`-1` = none)
`LogoWidth`	`Integer`	`-1`	Logo width in pixels (`-1` = auto)
`PositionColor`	`TTMSFNCWXQRCodePositionColor`	—	Colors for the finder pattern squares
`QuietZone`	`Integer`	`0`	Margin (in pixels) around the QR code
`QuietZoneColor`	`TTMSFNCGraphicsColor`	`gcWhite`	Fill color of the quiet zone
`SubTitleFont`	`TTMSFNCGraphicsFont`	—	Font for the subtitle text
`SubTitleTop`	`Integer`	`0`	Vertical offset of the subtitle
`TimingHorizonalColor`	`TTMSFNCGraphicsColor`	`gcBlack`	Color of the horizontal timing pattern
`TimingVerticalColor`	`TTMSFNCGraphicsColor`	`gcBlack`	Color of the vertical timing pattern
`TitleBackgroundColor`	`TTMSFNCGraphicsColor`	`gcWhite`	Background fill behind the title area
`TitleFont`	`TTMSFNCGraphicsFont`	—	Font for the title text
`TitleHeight`	`Integer`	`0`	Height reserved for the title area
`TitleTop`	`Integer`	`30`	Vertical offset of the title text

TTMSFNCWXQRCodePositionColor

Property	Default	Description
`TopLeftOuterColor`	`gcBlack`	Outer ring of the top-left finder pattern
`TopLeftInnerColor`	`gcBlack`	Inner dot of the top-left finder pattern
`TopRightOuterColor`	`gcBlack`	Outer ring of the top-right finder pattern
`TopRightInnerColor`	`gcBlack`	Inner dot of the top-right finder pattern
`BottomRightOuterColor`	`gcBlack`	Outer ring of the bottom-left finder pattern
`BottomRightInnerColor`	`gcBlack`	Inner dot of the bottom-left finder pattern

Events reference

Event	Signature	Description
`OnGetQRCode`	`procedure(Sender: TObject; ABitmap: TTMSFNCBitmap)`	Fired each time the QR code is rendered; provides the result as a bitmap
`OnInitialized`	`TNotifyEvent`	Fired once the embedded browser and JS library have finished loading

Loading modes (LibraryLocation)

Most WX components offer the option to load the JavaScript library from an online CDN or from embedded resources. Set this via the LibraryLocation property:

llOnline — The library is loaded live from cdn.jsdelivr.net. Fastest initial load; requires an internet connection.
llOffline — The library is loaded from the application's resources. Works without internet; may increase load time on low-powered devices.

When deploying your application, choose the mode that matches your target environment.