TStyledPanel - Technical Reference

Overview

TStyledPanel is a styled container control based on TCustomPanel that provides styled background rendering with full support for StyleFamily, StyleClass and StyleAppearance. Available from version 3.9.1. See the component page for an introduction.

Class Hierarchy

TWinControl
  └─ TCustomPanel
      └─ TStyledPanel

Unit

Vcl.StyledPanel

Description

TStyledPanel extends TCustomPanel with the styling system of the styled buttons: shapes, colours and border come from a Family/Class/Appearance, while all the standard TPanel properties, events and docking features are kept.

Unlike the styled buttons, which use TStyledButtonRender, TStyledPanel uses TStyledButtonAttributes directly for its Normal and Disabled states (PanelStyleNormal, PanelStyleDisabled), a lightweight implementation for container controls.

Development Note: this component was developed using the Vibe Coding technique with Claude Code.

Key Features

• Container control with child controls and docking
• Two states: Normal and Disabled
• Style families: Classic, Bootstrap, Angular-Light, Angular-Dark, Angular-M3-Light, Angular-M3-Dark, Basic-Colors, SVG-Colors and custom
• Shapes: btRect, btRoundRect, btRounded, btEllipse, with StyleRadius and StyleRoundedCorners
• Caption with CaptionAlignment and CaptionMargin
• AsVCLComponent and per-control StyleName (Delphi 10.4+) for the VCL Styles
• Component Editor with previews drawn as panels (Component-Editor)
• DPI aware: StyleRadius scales with the monitor

Published properties

Style

Property	Type	Default	Description
StyleFamily	TStyledButtonFamily	Classic	Style family. An unregistered family raises EStyledAttributesException (while streaming a form it falls back to Classic). Choosing Classic sets StyleElements := [seFont, seClient, seBorder]
StyleClass	TStyledButtonClass	Windows	Class within the family. In Classic, a class other than Windows removes seClient
StyleAppearance	TStyledButtonAppearance	Normal	Visual variant (Normal, Outline, Flat, Raised, Text, Filled...; depends on the family)
StyleDrawType	TStyledButtonDrawType	btRoundRect	Shape: btRoundRect, btRounded, btRect, btEllipse. Also sets ParentBackground (True for the rounded shapes, False for btRect). Stored only if explicitly set
StyleRadius	Integer	6	Corner radius (btRoundRect)
StyleShadowSize	Integer	-1	Shadow below the face in pixels, the same in the Normal and Disabled states: -1 = the shadow of the style family (Elevated and Fab of Angular-M3), 0 = none, greater than zero = that shadow in any family. It is seen only below the panel, inside its area, and scaled with the DPI like StyleRadius; the children are placed above the shadow (AdjustClientRect). Ignored with AsVCLComponent. Values below -1 raise an exception
StyleRoundedCorners	TRoundedCorners	all four	Corners to round: rcTopLeft, rcTopRight, rcBottomRight, rcBottomLeft
StyleName	string	''	Per-control VCL Style (Delphi 10.4+): selects the Classic family with that class
StyleElements	TStyleElements		Parts that follow the VCL Style; stored only in the Classic family when different from [seFont, seClient, seBorder]
ActiveStyleName	string		Name of the VCL Style in use (read-only)
AsVCLComponent	Boolean		True = Classic family with seClient: colours of a TPanel in the active VCL Style, square corners. Not stored
PanelStyleNormal	TStyledButtonAttributes		Attributes of the enabled panel (ButtonColor, BorderColor, BorderWidth, FontColor, FontStyle, DrawType, Radius, RoundedCorners...)
PanelStyleDisabled	TStyledButtonAttributes		Attributes of the disabled panel

Caption

Property	Type	Default	Description
Caption	TCaption		Text of the panel
ShowCaption	Boolean	True	Draw the caption
CaptionAlignment	TAlignment	taCenter	Horizontal alignment of the caption (drawn on one line, vertically centered)
CaptionMargin	Integer	4	Margin of the caption from the border
Alignment	TAlignment	taCenter	Standard TPanel property, published; the styled caption uses CaptionAlignment
VerticalAlignment	TVerticalAlignment	taVerticalCenter	Standard TPanel property, published; the styled caption is vertically centered

Colour and background

Property	Type	Default	Description
Color	TColor	from the style	Setting it changes PanelStyleNormal.ButtonColor; stored only if different from the style colour
ParentColor	Boolean		Use the colour of the parent
ParentBackground	Boolean	by shape	Show the parent as background (see StyleDrawType)
DoubleBuffered, ParentDoubleBuffered, FullRepaint	Boolean		Painting options

Standard panel properties

Property	Type	Default	Description
Align, Anchors, Constraints, AutoSize, Padding (10.4+)			Layout
BevelEdges, BevelInner, BevelKind, BevelOuter, BevelWidth		BevelOuter = bvNone	Bevels of the panel
BorderStyle, BorderWidth			Border
BiDiMode, ParentBiDiMode, Ctl3D, ParentCtl3D			Bi-directional and 3D
DockSite, UseDockManager (True), DragCursor, DragKind, DragMode			Docking and drag
Enabled, Visible, Font, ParentFont, PopupMenu, ShowHint, ParentShowHint, TabOrder, TabStop, Touch			General

Public methods

Method	Description
constructor Create(AOwner: TComponent)	Creates the panel with the default style
constructor CreateStyled(AOwner: TComponent; const AFamily; const AClass; const AAppearance)	Creates the panel with the given style (AOwner is required)
procedure SetPanelStyle(const AStyleFamily; const AStyleClass; const AStyleAppearance)	Sets the style at run-time; raises EStyledPanelError if the combination is not available
class procedure RegisterDefaultRenderingStyle(const ADrawType: TStyledButtonDrawType; const AFamily = DEFAULT_CLASSIC_FAMILY; const AClass = DEFAULT_WINDOWS_CLASS; const AAppearance = DEFAULT_APPEARANCE; const AStyleRadius: Integer = DEFAULT_RADIUS)	Default style of the panels created afterwards (call it after Application.Initialize)
procedure Assign(Source: TPersistent)	From another TStyledPanel copies the style (family, class, appearance, shape, radius, rounded corners, caption alignment)
procedure AssignStyleTo(Dest: TPersistent)	Copies the style to another TStyledPanel
function IsCustomDrawType: Boolean	True if the shape was set explicitly (otherwise it follows the style)
procedure SetCustomStyleDrawType(ACustomStyleDrawType: Boolean)	Sets that flag
procedure ChangeScale(M, D: Integer; isDpiChange: Boolean)	Scales StyleRadius with the DPI (Delphi 10.1+)
procedure ScaleForPPI(NewPPI: Integer)	Repaints for the new PPI (Delphi 10.4+)

class procedure RegisterDefaultRenderingStyle(
  const ADrawType: TStyledButtonDrawType;
  const AFamily: TStyledButtonFamily = DEFAULT_CLASSIC_FAMILY;
  const AClass: TStyledButtonClass = DEFAULT_WINDOWS_CLASS;
  const AAppearance: TStyledButtonAppearance = DEFAULT_APPEARANCE;
  const AStyleRadius: Integer = DEFAULT_RADIUS); virtual;

Events

TStyledPanel has no event of its own: it publishes the ones of TCustomPanel.

Event	Description
OnClick, OnDblClick	Click and double click
OnMouseDown, OnMouseUp, OnMouseMove, OnMouseEnter, OnMouseLeave, OnMouseActivate	Mouse
OnEnter, OnExit	Focus
OnResize, OnCanResize, OnConstrainedResize	Size
OnAlignInsertBefore, OnAlignPosition	Alignment of the child controls (Delphi 10.3+)
OnContextPopup, OnGesture	Context menu and touch
OnDockDrop, OnDockOver, OnGetSiteInfo, OnUnDock, OnStartDock, OnEndDock	Docking
OnDragDrop, OnDragOver, OnEndDrag, OnStartDrag	Drag and drop

Related types

Name	Description
TStyledPanelClass	class of TStyledPanel
EStyledPanelError	Exception class of the unit
DEFAULT_CAPTION_MARGIN	Default CaptionMargin (4)

Usage Examples

Basic panel

var
  Panel: TStyledPanel;
begin
  Panel := TStyledPanel.CreateStyled(Self,
    BOOTSTRAP_FAMILY, btn_primary, BOOTSTRAP_NORMAL);
  Panel.Parent := Self;
  Panel.Align := alTop;
  Panel.Height := 60;
  Panel.Caption := 'Header Panel';
  Panel.StyleDrawType := btRoundRect;
  Panel.StyleRadius := 8;
end;

Card container

Panel := TStyledPanel.CreateStyled(Self,
  BOOTSTRAP_FAMILY, btn_light, BOOTSTRAP_NORMAL);
Panel.Parent := Self;
Panel.Align := alClient;
Panel.ShowCaption := False;
Panel.StyleDrawType := btRoundRect;
Panel.StyleRadius := 12;
Panel.Padding.SetBounds(16, 16, 16, 16);   //Delphi 10.4+

Caption alignment and rounded corners

Panel.Caption := 'Left-Aligned Header';
Panel.CaptionAlignment := taLeftJustify;
Panel.CaptionMargin := 12;
Panel.StyleRoundedCorners := [rcTopLeft, rcTopRight];

Styled or VCL rendering

Panel.AsVCLComponent := CheckBoxUseVCLStyle.Checked;

Default style for all the panels

begin
  Application.Initialize;
  TStyledPanel.RegisterDefaultRenderingStyle(btRoundRect,
    BOOTSTRAP_FAMILY, btn_light, BOOTSTRAP_NORMAL, 8);
  Application.CreateForm(TMainForm, MainForm);
  Application.Run;
end.

Differences from TStyledButton

Aspect	TStyledPanel	TStyledButton
Base class	TCustomPanel	TWinControl (TCustomStyledButton)
Rendering	TStyledButtonAttributes directly	TStyledButtonRender
States	2 (Normal, Disabled)	5 (Normal, Pressed, Selected, Hot, Disabled)
Purpose	Container for child controls	Interactive button
Layout	Panel (Alignment, Bevel, Padding)	Button (ImageAlignment, Layout)

Important Notes

• Container: can contain other controls and be a docking site.
• Two states only: no Hot, Pressed or Selected.
• VCL Styles: only the Classic family with AsVCLComponent (or a StyleName) takes the colours of the VCL Style; the other families are independent from it.
• ParentBackground: follows the shape of the panel (see StyleDrawType); set it after the shape if you need another value.
• DPI aware: StyleRadius scales with the monitor.

See Also

• TStyledPanel - Component page
• StyledPanelDemo - Demo
• Component-Editor - Design-time editor
• TStyledButton-Reference - Styled button control
• TStyledToolbar-Reference - Styled toolbar