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 properties. Available from version 3.9.1.

Class Hierarchy

TWinControl
  └─ TCustomPanel
      └─ TStyledPanel

Unit

Vcl.StyledPanel

Description

TStyledPanel extends TCustomPanel with modern styling capabilities similar to styled buttons. It provides styled background rendering with customizable shapes, colors, and borders while maintaining full compatibility with standard TPanel/TCustomPanel properties and behavior.

Unlike styled buttons that use TStyledButtonRender, TStyledPanel directly uses TStyledButtonAttributes for its Normal and Disabled states, providing a lightweight implementation optimized for container controls.

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

Key Features

• Container control: Full TWinControl functionality with child control support
• Two panel states: Normal and Disabled
• Multiple style families: Classic, Bootstrap, Angular-Light, Angular-Dark, Basic-Color, SVG-Color
• Custom shapes: Rectangle, RoundedRect, Rounded (full-round), Ellipse
• Caption rendering: Customizable caption alignment and margins
• VCL compatibility: Can switch between styled and VCL rendering
• GDI+ rendering: Smooth antialiased rendering independent of VCL Styles
• Standard panel features: Bevel, Border, Alignment, Docking support

Main Properties

Styling Properties

Property	Type	Description
StyleFamily	TStyledButtonFamily	Style family (Classic, Bootstrap, Angular-Light, Angular-Dark, Basic-Color, SVG-Color)
StyleClass	TStyledButtonClass	Predefined style class within the family
StyleAppearance	TStyledButtonAppearance	Visual variant (Normal, Outline, Flat, Raised, etc.)
StyleDrawType	TStyledButtonDrawType	Panel shape (btRect, btRoundRect, btRounded, btEllipse)
StyleRadius	Integer	Corner radius for btRoundRect (default: 6)
StyleRoundedCorners	TRoundedCorners	Which corners to round ([rcTopLeft, rcTopRight, rcBottomLeft, rcBottomRight])

Caption Properties

Property	Type	Description
Caption	TCaption	Panel caption text
CaptionAlignment	TAlignment	Caption horizontal alignment (taLeftJustify, taCenter, taRightJustify) - default: taCenter
CaptionMargin	Integer	Margin around caption text (default: 4)
ShowCaption	Boolean	Show/hide caption (inherited from TCustomPanel)
VerticalAlignment	TVerticalAlignment	Caption vertical alignment (taAlignTop, taAlignBottom, taVerticalCenter)

Standard Panel Properties

Property	Type	Description
Align	TAlign	Panel alignment in parent
Alignment	TAlignment	Content alignment (deprecated, use CaptionAlignment)
BevelEdges	TBevelEdges	Which edges have bevels
BevelInner	TBevelCut	Inner bevel style
BevelOuter	TBevelCut	Outer bevel style
BevelKind	TBevelKind	Bevel kind (bkNone, bkTile, bkSoft, bkFlat)
BevelWidth	Integer	Width of beveled edges
BorderWidth	Integer	Border width
BorderStyle	TBorderStyle	Border style (bsNone, bsSingle)
Padding	TPadding	Internal padding (Delphi 10.4+)

Compatibility

Property	Type	Description
AsVCLComponent	Boolean	Switch to VCL-style rendering (uses VCL Styles if active)
ParentBackground	Boolean	Use parent's background
ParentColor	Boolean	Use parent's color

Container Properties

Property	Type	Description
DockSite	Boolean	Can act as docking site
UseDockManager	Boolean	Use docking manager (default: True)
FullRepaint	Boolean	Repaint entire panel on resize

Main Methods

RegisterDefaultRenderingStyle (Class Method)

Sets the default rendering style for all TStyledPanel instances created afterwards.

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;

Example:

// Set all panels to Bootstrap Light with rounded corners
TStyledPanel.RegisterDefaultRenderingStyle(
  btRounded,
  BOOTSTRAP_FAMILY,
  btn_light,
  BOOTSTRAP_NORMAL
);

SetPanelStyle

Changes the panel style at runtime.

procedure SetPanelStyle(
  const AStyleFamily: TStyledButtonFamily;
  const AStyleClass: TStyledButtonClass;
  const AStyleAppearance: TStyledButtonAppearance);

CreateStyled (Constructor)

Creates a panel with specific style settings.

constructor CreateStyled(
  AOwner: TComponent;
  const AFamily: TStyledButtonFamily;
  const AClass: TStyledButtonClass;
  const AAppearance: TStyledButtonAppearance);

Events

TStyledPanel supports all standard TCustomPanel events:

Event	Description
OnClick	Panel clicked
OnDblClick	Panel double-clicked
OnMouseDown	Mouse button pressed
OnMouseUp	Mouse button released
OnMouseMove	Mouse moves over panel
OnMouseEnter	Mouse enters panel area
OnMouseLeave	Mouse leaves panel area
OnResize	Panel resized
OnDockDrop	Control docked onto panel
OnDockOver	Control dragged over panel
OnEnter	Panel receives focus
OnExit	Panel loses focus

Usage Examples

Basic Styled 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;

Panel as Card Container

Panel := TStyledPanel.CreateStyled(Self,
  BOOTSTRAP_FAMILY,
  btn_light,
  BOOTSTRAP_NORMAL);
Panel.Parent := Self;
Panel.Align := alClient;
Panel.Caption := '';  // No caption
Panel.StyleDrawType := btRoundRect;
Panel.StyleRadius := 12;
Panel.BevelOuter := bvNone;
Panel.Padding.SetBounds(16, 16, 16, 16);  // 16px padding on all sides

// Add controls inside
var Lbl := TLabel.Create(Panel);
Lbl.Parent := Panel;
Lbl.Caption := 'Card Content';
Lbl.Align := alTop;

Info/Warning/Error Panels

// Info Panel
PanelInfo := TStyledPanel.CreateStyled(Self,
  BOOTSTRAP_FAMILY,
  btn_info,
  BOOTSTRAP_NORMAL);
PanelInfo.Parent := Self;
PanelInfo.Caption := 'Information';
PanelInfo.StyleDrawType := btRoundRect;

// Warning Panel
PanelWarning := TStyledPanel.CreateStyled(Self,
  BOOTSTRAP_FAMILY,
  btn_warning,
  BOOTSTRAP_NORMAL);
PanelWarning.Parent := Self;
PanelWarning.Caption := 'Warning';
PanelWarning.StyleDrawType := btRoundRect;

// Error Panel
PanelError := TStyledPanel.CreateStyled(Self,
  BOOTSTRAP_FAMILY,
  btn_danger,
  BOOTSTRAP_NORMAL);
PanelError.Parent := Self;
PanelError.Caption := 'Error';
PanelError.StyleDrawType := btRoundRect;

Panel with Custom Caption Alignment

Panel := TStyledPanel.CreateStyled(Self,
  BOOTSTRAP_FAMILY,
  btn_dark,
  BOOTSTRAP_NORMAL);
Panel.Parent := Self;
Panel.Caption := 'Left-Aligned Header';
Panel.CaptionAlignment := taLeftJustify;
Panel.CaptionMargin := 12;  // Left margin
Panel.VerticalAlignment := taAlignTop;
Panel.Height := 40;

Rounded Card Panel

Panel := TStyledPanel.CreateStyled(Self,
  BOOTSTRAP_FAMILY,
  btn_light,
  BOOTSTRAP_NORMAL);
Panel.Parent := Self;
Panel.Caption := '';
Panel.StyleDrawType := btRoundRect;
Panel.StyleRadius := 16;
Panel.BevelOuter := bvNone;

// Round specific corners
Panel.StyleRoundedCorners := [rcTopLeft, rcTopRight];  // Only top corners rounded

Switch Between Styled and VCL Rendering

Panel := TStyledPanel.CreateStyled(Self,
  BOOTSTRAP_FAMILY,
  btn_primary,
  BOOTSTRAP_NORMAL);
Panel.Parent := Self;
Panel.Caption := 'Switchable Panel';

// Toggle between styled and VCL rendering
if CheckBoxUseVCLStyle.Checked then
  Panel.AsVCLComponent := True  // Use VCL Styles
else
  Panel.AsVCLComponent := False; // Use styled rendering

Setting Default Styles Globally

// In project DPR file, after Application.Initialize
uses
  Vcl.StyledPanel, Vcl.ButtonStylesAttributes;

begin
  Application.Initialize;

  // All TStyledPanel instances will use these defaults
  TStyledPanel.RegisterDefaultRenderingStyle(
    btRoundRect,
    BOOTSTRAP_FAMILY,
    btn_light,
    BOOTSTRAP_NORMAL,
    8  // Radius
  );

  Application.CreateForm(TMainForm, MainForm);
  Application.Run;
end.

Creating Styled Panel at Runtime with Specific Style

Panel := TStyledPanel.CreateStyled(
  Self,
  ANGULAR_LIGHT_FAMILY,
  acl_primary,
  ANGULAR_RAISED
);
Panel.Parent := Self;
Panel.Align := alTop;
Panel.Caption := 'Angular Styled Header';
Panel.Height := 50;

Differences from TStyledButton

Aspect	TStyledPanel	TStyledButton
Base Class	TCustomPanel	TWinControl
Rendering	Uses TStyledButtonAttributes directly	Uses TStyledButtonRender
States	2 (Normal, Disabled)	5 (Normal, Hot, Pressed, Selected, Disabled)
Purpose	Container for child controls	Interactive button
Focus	Can receive focus as container	Button-specific focus behavior
Layout	Panel-specific (Alignment, Bevel)	Button-specific (ImageAlignment)

Important Notes

• Container Control: Can contain child controls (labels, buttons, etc.)
• Two States Only: Normal and Disabled (no Hot, Pressed, or Selected states)
• DPI Aware: Automatically scales with DPI changes
• VCL Compatibility: Full compatibility with TPanel/TCustomPanel
• GDI+ Required: Requires Windows XP SP2+ for antialiased rendering
• Bevel Support: Works with BevelInner, BevelOuter, BevelKind properties
• Docking Support: Full docking capabilities inherited from TCustomPanel

See Also

• TStyledButton - Styled button control
• TStyledGraphicButton - Graphic button control
• TStyledToolbar - Styled toolbar