TStyledDbNavigator - Technical Reference

Overview

TStyledDbNavigator is a styled database navigator that replaces the standard TDBNavigator: every button is a TStyledNavButton with the full styling of the library, optional captions and custom images. This page lists all the published and public members of TStyledDbNavigator (class TStyledDBNavigator), of its base class TCustomStyledDBNavigator and of the button class TStyledNavButton. For the usage see TStyledDbNavigator.

Class Hierarchy

TCustomPanel
  └─ TCustomStyledDBNavigator
      ├─ TStyledDBNavigator
      └─ TStyledBindNavigator   (see TStyledBindNavigator-Reference)

TStyledGraphicButton
  └─ TStyledNavButton           (the buttons inside the navigator)

Unit

Vcl.StyledDbNavigator

Description

TStyledDbNavigator has the same behavior of TDBNavigator (a TDataSource is linked through DataSource; the buttons are enabled/disabled according to the state of the dataset) but draws the buttons with the Styled Components renderer. The ten standard buttons are created together with the two buttons nbApplyUpdates and nbCancelUpdates, which are hidden by default.

The class is registered for Win32 and Win64 and, at design time, has the Component Editor Styled DbNavigator Editor... (see Component Editor).

Key Features

• All TDBNavigator functionality: First, Prior, Next, Last, Insert, Delete, Edit, Post, Cancel, Refresh, ApplyUpdates, CancelUpdates
• Styled buttons: StyleFamily / StyleClass / StyleAppearance / StyleDrawType / StyleRadius for the whole navigator, overridable on each button
• Captions: show/hide with ShowCaptions, customizable with Captions
• Built-in icons readable with light and dark styles, with vertical variants of the move buttons
• Custom ImageList support (Images, DisabledImages)
• Auto-repeat of the Prior and Next buttons while the mouse is held down
• Keyboard: Left/Right arrows move the focus between the buttons, Space clicks the focused button
• OnEnableNavBtn: your own rule to enable/disable each button

Published properties (Object Inspector)

Database and behavior

Property	Type	Default	Description
DataSource	TDataSource	nil	Data source to navigate
VisibleButtons	TNavButtonSet	First..Refresh (10 buttons)	Buttons shown; nbApplyUpdates and nbCancelUpdates are not in the default set
ConfirmDelete	Boolean	True	Asks for confirmation (styled dialog) before deleting the record
MaxErrors	Integer	-1	Maximum number of errors passed to ApplyUpdates / CancelUpdates of the dataset
Enabled	Boolean	True	When False all the buttons are disabled

Layout, captions and hints

Property	Type	Default	Description
Kind	TDBNavigatorKind	dbnHorizontal	Orientation: dbnHorizontal or dbnVertical (swaps Width and Height)
ShowCaptions	Boolean	False	Shows the caption of each button
Captions	TStrings	built-in texts	One line for each button, in the order of TNavigateBtn; an empty line keeps the default caption
Hints	TStrings	built-in texts	One line for each button; an empty line keeps the default hint
Flat	Boolean	False	Flat buttons
Cursor	TCursor	crHandPoint	Cursor of the navigator and of its buttons

The size of every button is calculated from the size of the navigator and the number of visible buttons (read-only ButtonWidth, ButtonHeight).

Images

Property	Type	Default	Description
Images	TCustomImageList	nil	Images of the buttons (index = Ord(TNavigateBtn); from index 12 on the vertical images of First..Last). When nil the built-in icons are used (Delphi 10.4+)
DisabledImages	TCustomImageList	nil	Images of the disabled buttons

Style

Property	Type	Default	Description
StyleFamily	TStyledButtonFamily	Classic	Style family of all the buttons
StyleClass	TStyledButtonClass	Windows	Style class of all the buttons
StyleAppearance	TStyledButtonAppearance	Normal	Appearance of all the buttons
StyleDrawType	TStyledButtonDrawType	btRoundRect	Shape of the buttons (btRect, btRoundRect, btRounded, btEllipse)
StyleRadius	Integer	6	Corner radius; must be greater than zero
StyleShadowSize	Integer	-1	Shadow of the buttons in pixels, the same in every state (-1 = the one of the style family, 0 = none); values below -1 raise an exception
StyleElements	TStyleElements	all	VCL Style elements used when the Classic family is active
AsVCLComponent	Boolean	not stored	True when the navigator follows the VCL Style (Classic family, class equal to the active style, seClient in StyleElements); setting it to True resets the style to Classic/Windows/Normal
ActiveStyleName	string	read-only	Name of the VCL Style in use for the navigator

Setting StyleFamily to a family that is not registered raises EStyledAttributesException (while streaming a form it falls back to Classic).

Standard control properties

Align, Anchors, Constraints, Ctl3D, ParentCtl3D, DragCursor, DragKind, DragMode, ParentShowHint, ShowHint, PopupMenu, TabOrder, TabStop, Visible.

Events

Event	Type	Description
BeforeAction	ENavClick (Sender: TObject; Button: TNavigateBtn)	Before the action of a button (not fired at design time). It cannot be canceled with a parameter: raise Abort to skip the action
OnClick	ENavClick	After the action of a button has been executed
OnEnableNavBtn	TEnableNavBtnProc	Called every time a button is enabled/disabled: (const ADbNavigator: TCustomStyledDBNavigator; const ABtn: TStyledNavButton; var AEnabled: Boolean); change AEnabled to override
OnContextPopup, OnDblClick, OnDragDrop, OnDragOver, OnEndDock, OnEndDrag, OnEnter, OnExit, OnResize, OnStartDock, OnStartDrag		Standard control events

Public members

Properties

Property	Type	Description
Buttons	TNavButtons	Array of the buttons indexed by TNavigateBtn (read-only)
ButtonItems[Index: TNavigateBtn]	TStyledNavButton	The button of the given kind (read-only): use it to customize a single button
ButtonWidth	Integer	Current width of a button (read-only)
ButtonHeight	Integer	Current height of a button (read-only)
StyleApplied	Boolean	True when the style of the navigator has been resolved

Methods

Method	Description
constructor CreateStyled(AOwner; const AFamily; const AClass; const AAppearance)	Creates the navigator with a given style (Create uses the defaults registered with RegisterDefaultRenderingStyle)
class procedure RegisterDefaultRenderingStyle(const ADrawType; const AFamily = DEFAULT_CLASSIC_FAMILY; const AClass = DEFAULT_WINDOWS_CLASS; const AAppearance = DEFAULT_APPEARANCE; const AStyleRadius = DEFAULT_RADIUS; const ACursor = DEFAULT_CURSOR)	Default style, shape, radius and cursor of the navigators created afterwards (static: call on TCustomStyledDBNavigator to affect also TStyledBindNavigator)
procedure SetDbNavigatorStyle(const AStyleFamily; const AStyleClass; const AStyleAppearance)	Sets family, class and appearance together; raises EStyledButtonError if the combination is not available
procedure BtnClick(Index: TNavigateBtn)	Executes the action of a button as if it was clicked (TStyledDbNavigator only): calls BeforeAction, the dataset method and OnClick
procedure Assign(Source: TPersistent)	Copies Flat, Kind, ConfirmDelete, images, ShowCaptions and the style of another navigator
procedure SetBounds(...)	Sizes the navigator keeping a whole number of pixels for each button

Navigation buttons

Button	Action	Enabled when
nbFirst	Go to the first record	active, not BOF
nbPrior	Go to the previous record (auto-repeat)	active, not BOF
nbNext	Go to the next record (auto-repeat)	active, not EOF
nbLast	Go to the last record	active, not EOF
nbInsert	Insert a record	the dataset CanModify
nbDelete	Delete the current record (asks confirmation if ConfirmDelete)	CanModify and not empty
nbEdit	Edit the current record	CanModify, not editing
nbPost	Post the changes	editing
nbCancel	Cancel the changes	editing
nbRefresh	Refresh the dataset	CanRefresh
nbApplyUpdates	ApplyUpdates (datasets supporting IDataSetCommandSupport)	the dataset can apply updates
nbCancelUpdates	CancelUpdates (same)	the dataset can cancel updates

TStyledNavButton

TStyledNavButton (a TStyledGraphicButton) is the button created by the navigator, one for each TNavigateBtn. It is created with the style of the navigator. Only the members added by the class are listed here; all the other published properties of the graphic buttons (see TStyledGraphicButton-Reference) are inherited.

Published

Property	Type	Default	Description
Caption	TCaption	built-in text	Caption; drawn only if the navigator has ShowCaptions True
ImageAlignment	TImageAlignment	iaTop	Position of the image relative to the caption when the captions are shown (with captions hidden the image is centered)
StyleFamily	TStyledButtonFamily	of the navigator	Overrides the family of the navigator
StyleClass	TStyledButtonClass	of the navigator	Overrides the class of the navigator
StyleAppearance	TStyledButtonAppearance	of the navigator	Overrides the appearance of the navigator
StyleDrawType	TStyledButtonDrawType	of the navigator	Overrides the shape
StyleRadius	Integer	of the navigator	Overrides the corner radius
StyleShadowSize	Integer	of the navigator	Shadow of the item (-1 = the one of the style family); stored only if different
StyleRoundedCorners	TRoundedCorners	all four	Which corners are rounded
ButtonStyleNormal, ButtonStylePressed, ButtonStyleSelected, ButtonStyleHot, ButtonStyleDisabled	TStyledButtonAttributes	from the style	Colors and borders of each state
NotificationBadge	TNotificationBadgeAttributes	no badge	Badge on the button: see Notification Badge
OnDropDownClick	event	nil	Inherited drop-down event

Public

Member	Type	Description
Index	TNavigateBtn	Which navigation action the button performs
NavStyle	TNavButtonStyle	Set of nsAllowTimer (auto-repeat) and nsFocusRect; Prior and Next have nsAllowTimer
procedure EnabledNavBtn(AValue: Boolean)		Enables/disables the button, giving to OnEnableNavBtn the chance to change the value

Types and constants

Name	Description
TNavButtons	array[TNavigateBtn] of TStyledNavButton
TEnableNavBtnProc	procedure(const ADbNavigator: TCustomStyledDBNavigator; const ABtn: TStyledNavButton; var AEnabled: Boolean) of object
TNavigateButtonEvent	procedure(Sender: TObject; Button: TNavigateButton) of object, used by TStyledBindNavigator
TNavigatorOrientation	(orHorizontal, orVertical), used by TStyledBindNavigator
NavigatorDefaultBtns	The ten standard buttons, First..Refresh
NavigatorMoveBtns	nbFirst..nbLast
EStyledDbnavigatorError	Exception class

Replacing TDBNavigator with the Interposer unit

Vcl.StyledComponentsHooks declares TDbNavigator = class(TStyledDbNavigator) and TBindNavigator = class(TStyledBindNavigator): adding the unit as the last of the uses clause turns the standard navigators of the forms into the styled ones. See Interposer Unit.

Important Notes

• DataSource: the buttons are all disabled until the dataset is active.
• Vertical icons: the navigator uses the built-in "vertical" icons for the move buttons when Kind = dbnVertical.
• Buttons are not streamed: the navigator creates its buttons in the constructor; to customize one at design time use the style properties of the navigator, otherwise do it in code (for example in FormCreate).
• DPI Aware: the buttons and the built-in icons scale with the DPI.

See Also

• TStyledDbNavigator - Usage and examples
• TStyledDbNavigator Demo
• TStyledBindNavigator Reference - LiveBindings navigator
• TStyledToolbar Reference - Styled toolbar