TdxCustomRibbon.CaptionAreaSearchToolbar Property

Provides access to the settings of the search toolbar displayed in the Ribbon form caption area.

Declaration

Delphi

property CaptionAreaSearchToolbar: TdxRibbonCaptionAreaSearchToolbar read; write;

Property Value

Type	Description
TdxRibbonCaptionAreaSearchToolbar	Stores settings of the Caption Area Search Toolbar in a Ribbon UI.

Remarks

The Ribbon control can display the Caption Area Search Toolbar in the caption of the Ribbon form if the Style property is set to rsOffice365. The Caption Area Search Toolbar allows users to access important functionality through the form caption, similar to the search box found in Microsoft Office® 365 applications.

Caption Area Search Toolbar Settings

You can use CaptionAreaSearchToolbar.Toolbar and CaptionAreaSearchToolbar.Alignment properties to display a toolbar and all its bar items in the parent form’s caption and position the toolbar within it.

Note

If the Style property value changes to rs2016, rs2016Tablet or rs2019, the toolbar displayed in the Caption Area Search Toolbar container moves to the Tab Area Search Toolbar.

Refer to the TdxRibbonCaptionAreaSearchToolbar class description for detailed information on all available options.

Code Example: Display an Office Search Box in a Ribbon Form Caption

The following code example creates a TdxOfficeSearchBox editor, associates it with an existing TdxRibbon control, and embeds the created editor into the Ribbon Form caption:

Delphi

uses
  dxRibbonForm,  // This unit declares the TdxRibbonForm class
  dxOfficeSearchBox; // This unit declares the TdxOfficeSearchBox class
// ...
procedure TMyForm.FormCreate(Sender: TObject);
var
  ABar: TdxBar;
  ABarItem: TcxBarEditItem;
  ASearchBoxProperties: TdxOfficeSearchBoxProperties;
  AIconFolder: string;
begin
  DisableAero := True; // Allows the DevExpress Skin Engine to draw non-client form areas
  AIconFolder := 'C:\Program Files (x86)\DevExpress\VCL\ExpressLibrary\Sources\Icon Library\';
  dxRibbon1.Style := rsOffice365;  // Selects the Office 365 style with support for form caption toolbars
  ABar := dxBarManager1.Bars.Add;  // Creates a toolbar as a container for the Office Search Box
  ABar.Visible := True;  // Displays the created toolbar container
  ABarItem := ABar.ItemLinks.AddItem(TcxBarEditItem).Item as TcxBarEditItem;
  ABarItem.PropertiesClass := TdxOfficeSearchBoxProperties;
  ASearchBoxProperties := ABarItem.Properties as TdxOfficeSearchBoxProperties;
  ASearchBoxProperties.BeginUpdate;  // Initiates the following batch change
  try
    ASearchBoxProperties.SearchSource := dxRibbon1;  // Associates the Office Search Box with the Ribbon UI
    ASearchBoxProperties.Nullstring := 'Tell me what you want to do...';
    ASearchBoxProperties.UseNullString := True;  // Displays the defined null string in the empty editor
    ASearchBoxProperties.Glyph.LoadFromFile(AIconFolder + 'SVG Images\Icon Builder\Business_Idea.svg');
    ASearchBoxProperties.Glyph.SourceWidth := 16;  // Explicitly specifies the required glyph width
    ASearchBoxProperties.Glyph.SourceHeight := 16;  // Explicitly specifies the required glyph height
    ASearchBoxProperties.ShowResultPaths := True;  // Displays navigation paths to found UI commands
  finally
    ASearchBoxProperties.EndUpdate;  // Calls EndUpdate regardless of the batch operation's success
  end;
  dxRibbon1.CaptionAreaSearchToolbar.Toolbar := ABar;  // Displays the toolbar container in the caption area
  dxRibbon1.CaptionAreaSearchToolbar.Alignment := TdxRibbonCaptionAreaSearchToolbarAlignment.Left;
end;

C++

#include "dxRibbonForm.hpp"  // This header declares the TdxRibbonForm class
#include "dxOfficeSearchBox.hpp"  // This header declares the TdxOfficeSearchBox class
// ...
void __fastcall TMyForm::FormCreate(TObject *Sender)
{
  TdxBar *ABar;
  TcxBarEditItem *ABarItem;
  TdxOfficeSearchBoxProperties *ASearchBoxProperties;
  UnicodeString AIconFolder;
  DisableAero = true;  // Allows the DevExpress Skin Engine to draw non-client form areas
  dxRibbon1->Style = rsOffice365;  // Selects the Office 365 style with support for form caption toolbars 
  ABar = dxBarManager1->Bars->Add();  // Creates a toolbar as a container for the office search box
  ABar->Visible = true;  // Displays the created toolbar container
  AIconFolder = "C:\\Program Files (x86)\\DevExpress\\VCL\\ExpressLibrary\\Sources\\Icon Library\\";
  ABarItem = dynamic_cast<TcxBarEditItem*>(ABar->ItemLinks->AddItem(__classid(TcxBarEditItem))->Item);
  ABarItem->PropertiesClass = __classid(TdxOfficeSearchBoxProperties);
  ASearchBoxProperties = dynamic_cast<TdxOfficeSearchBoxProperties*>(ABarItem->Properties);
  ASearchBoxProperties->BeginUpdate();  // Initiates the following batch change
  try
  {
    ASearchBoxProperties->SearchSource = dxRibbon1;  // Associates the office search box with the Ribbon UI
    ASearchBoxProperties->Nullstring = "Tell me what you want to do...";
    ASearchBoxProperties->UseNullString = true;  // Displays the defined null string in the empty editor
    ASearchBoxProperties->Glyph->LoadFromFile(AIconFolder + "SVG Images\\Icon Builder\\Business_Idea.svg");
    ASearchBoxProperties->Glyph->SourceWidth = 16;  // Explicitly specifies the required glyph width
    ASearchBoxProperties->Glyph->SourceHeight = 16;  // Explicitly specifies the required glyph height
    ASearchBoxProperties->ShowResultPaths = true;  // Displays navigation paths to found UI commands
  }
  __finally
  {
    ASearchBoxProperties->EndUpdate();  // Calls EndUpdate regardless of the batch operation's success
  }
  dxRibbon1->CaptionAreaSearchToolbar->Toolbar = ABar;  // Displays the toolbar container in the caption area
  dxRibbon1->CaptionAreaSearchToolbar->Alignment = TdxRibbonCaptionAreaSearchToolbarAlignment::Left;
};

Limitations

The Ribbon control can display the Caption Area Search Toolbar in the caption of the Ribbon form only when the following conditions are met:

• The SupportNonClientDrawing property is set to True.
• The Style property is set to rsOffice365.
• The parent form’s DisableAero property is set to True.