TdxOfficeSearchBox Class

A search box suggesting Ribbon or Toolbar UI elements based on user input.

Declaration

TdxOfficeSearchBox = class(
    TcxCustomTextEdit
)

Remarks

The Office Search Box editor is an auxiliary UI element inspired by the Tell Me text box found in Microsoft Office® applications. The Office Search Box simplifies command search in a complex Ribbon or Toolbar UI. You can use a TdxOfficeSearchBox editor as a standalone UI element or embed the editor into a toolbar item container (TcxBarEditItem).

A Ribbon Form caption can display a toolbar item with an embedded Office Search Box when the Office 365 style is active.

VCL Bars: An Office Search Box in a Ribbon Form Caption

Quick Start

Use the Properties.SearchSource property to associate an Office Search Box with the required UI command source (a TdxRibbon control or a TdxBarManager component). A Office Search Box with a specified search source lists all UI commands whose names include the current user input:

Refer to the code example below for detailed information on how to create and configure a TdxOfficeSearchBox editor.

Main API Members

The list below outlines key members of the TdxOfficeSearchBox class that allow you to configure Office Search Box editors.

Appearance Settings

Style | StyleDisabled | StyleFocused | StyleHot: Allow you to define individual appearance settings for different Office Search Box states.

Tip
To apply the same style settings to multiple editors, use a TcxEditStyleController component. If you need to apply the same settings to all editors in your application, you can use a TcxDefaultEditStyleController component.
Styles: Provides access to individual styles applied to the editor in different states.

Clear: Clears the editor.
ClearSelection: Deletes content selection.
SelLength | SelStart | SetSelection | SelectAll: Select content.
CopyToClipboard | CutToClipboard | PasteFromClipboard: Allow you to perform clipboard operations.
EditValue: Specifies the edit value.
SelectAll: Selects editor content.

Editor Settings

ActiveProperties: Provides access to the current editor settings. This property set does not allow you to customize editor settings.
GetPropertiesClass: Returns the actual editor settings type.
Properties: Allows you to customize editor settings.

General-Purpose API Members

Enabled: Specifies if the editor is enabled.
ShowHint: Specifies if the editor can display hints.

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
C++

uses
  dxRibbonForm,  // Declares the TdxRibbonForm class
  dxOfficeSearchBox; // 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;

#include "dxRibbonForm.hpp"  // Declares the TdxRibbonForm class
#include "dxOfficeSearchBox.hpp"  // 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;
};

VCL Bars: An Office Search Box Embedded into a Ribbon Form Caption