Custom Painting Hints

• Dec 28, 2020
• 5 minutes to read

The NavBar control supports a custom draw feature. It can be applied to any NavBar control element. This topic explains how to implement custom painting of the NavBar control hints.

There are two hint types in the NavBar control: group hint and link hint. The NavBar control provides a number of events used for runtime hints customization:

Event	Description
OnGetGroupHint	Occurs when the group hint text is obtained. Allows you to specify the hint text for groups dynamically, as opposed to the default behavior of using the value in the Group.Hint property. The hint text specified via this event is passed to the custom draw event.
OnCalcGroupHintRect	Occurs when a group hint bounds are to be calculated. Allows the group hint bounds customization according to your. The TRect instance, representing the hint bounds is passed to the custom draw event.
OnCustomDraw.GroupHint	Occurs when painting of a group hint is required. Two parameters of this event (the hint text and bounds) depend on the two previous events handlers. If these events are not handled, then the hint text is specified by the Group.Hint property. Its bounding rectangle is calculated automatically.
OnGetLinkHint	Occurs when the link hint text is required. Allows you to specify the hint text for items dynamically, as opposed to the default behavior of using the value in the Item.Hint property. The hint text specified via this event is passed to the custom draw event.
OnCalcLinkHintRect	Occurs when a link hint bounds are to be calculated. Allows the link hint bounds customization according to your. The TRect instance, representing the hint bounds is passed to the custom draw event.
OnCustomDraw.LinkHint	Occurs when the painting of a link hint is required. Two parameters of this event (the hint text and bounds) depend on the two previous events handlers. If these events are not handled, then the hint text is specified by the Item.Hint property. Its bounding rectangle is calculated automatically.
OnCalcNavigationPaneOverflowPanelHintRect	Enables you to specify a custom size for hints displayed when hot-tracking icons within the navigation pane’s overflow panel.
OnCustomDraw.NavigationPaneOverflowPanelHint	Enables you to custom paint the hints displayed for icons within the navigation pane’s overflow panel.

The following code demonstrates custom painting of the group and item link hints:

//This event handler specifies the group hint text
procedure TfmFeaturesMain.nbMainGetGroupHint(Sender: TObject;
  AGroup: TdxNavBarGroup; var AHint: String);
begin
  //The group hint text is composed of the group caption
  AHint := 'This is ' + AGroup.Caption + ' group';
end;
//This event handler performs custom drawing of the group hint.  The
//group hint text is specified via the previous event handler
procedure TfmFeaturesMain.nbMainCustomDrawGroupHint(Sender: TObject;
  ACanvas: TCanvas; AGroup: TdxNavBarGroup; AHint: String; R: TRect;
  var AHandled: Boolean);
begin
  //The Brush color for the hint area is set to clBtnFace
  ACanvas.Brush.Color := clBtnFace;
  //The hint area background is filled with Brush
  ACanvas.FillRect(R);
  //Two following lines draw the 3D border within the hint area
  Frame3D(ACanvas, R, clWhite, clBlack, 1);
  Frame3D(ACanvas, R, clBtnFace, clGray, 1);
  //The hint text is drawn
  ACanvas.TextRect(R, 1, 1, AHint);
  //The AHandled parameter must be set to True,because the default
  //hint painting is not requried
  AHandled := True;
end;
//This event handler specifies the link hint text
procedure TfmFeaturesMain.nbMainGetLinkHint(Sender: TObject;
  ALink: TdxNavBarItemLink; var AHint: String);
begin
  //The item link hint is composed of the item caption
  AHint := 'This is ' + ALink.Item.Caption + ' item';
end;
//This event handler recalculates the link hint bounding rectangle to
//include the link's small image into it
procedure TfmFeaturesMain.nbMainCalcLinkHintRect(Sender: TObject;
  ALink: TdxNavBarItemLink; AViewInfo: TdxNavBarViewInfo; var R: TRect);
var
  Img: TBitmap;
begin
  Img := TBitmap.Create;
  //The Img variable is assigned the small image of an item whose
  //hint area bounds are calculated
  imgSmall.GetBitmap(Alink.Item.SmallImageIndex, Img);
  //The hint area bounds are resized to include the item's
  //small image
  R.Bottom := R.Top + Img.Height + 4;
  R.Right := R.Right + Img.Width;
end;
//This event handler performs custom drawing of the link hint.  The
//link hint text and bounding rectangle are obtained from two
//previous event handlers
procedure TfmFeaturesMain.nbMainCustomDrawLinkHint(Sender: TObject;
  ACanvas: TCanvas; ALink: TdxNavBarItemLink; AHint: String; R: TRect;
  var AHandled: Boolean);
var
  Img: TBitmap;
begin
  Img := TBitmap.Create;
  //The Img variable is assigned the small image of an item whose
  //hint is drawn
  imgSmall.GetBitmap(Alink.Item.SmallImageIndex, Img);
  //The Brush color for the hint area is set to clBtnFace
  ACanvas.Brush.Color := clBtnFace;
  //The hint area background is filled with Brush
  ACanvas.FillRect(R);
  //Two following lines draw the 3D border within the hint area
  Frame3D(ACanvas, R, clWhite, clBlack, 1);
  Frame3D(ACanvas, R, clBtnFace, clGray, 1);
  //The item's small image is drawn at the left of the hint area
  Img.TransparentMode := tmFixed;
  Img.TransparentColor := clWhite;
  Img.Transparent := True;
  ACanvas.Draw(2, 2, Img);
//The Brush style should be set to bsClear to prevent drawing of
//the hint text over the link small image
  ACanvas.Brush.Style := bsClear;
  ACanvas.TextRect(R, Img.Width + 1, 2, AHint);
  //The AHandled parameter must be set to True,because the default
  //hint painting is not requried
  AHandled := True;
end;

The result is demonstrated below:

Group hint	Item link hint