HypernovaDesktop Components · docs
Binarymission
WinForms › Search Text Box › SearchTextBox

SearchTextBox

class.NET 6 / 8 / 10.NET Framework 4.8Binarymission.WinForms.Controls.InputControls

A one-line search box with a grey prompt and three buttons drawn inside its right-hand end – a magnifier to run the search, a cross to clear it, and a chevron to open a list such as recent searches.

public class SearchTextBox : BinaryExtendedText

Inherits from / implements: BinaryExtendedText

Remarks

What it is for

Use it at the top of a list, a grid or a document view, wherever the user filters or finds something: "Search customers", "Find in orders". It is a BinaryExtendedText, so it has the flat coloured border, hover effect and blinking of that control, plus the search furniture.

How it works

The control does no searching itself. Each button raises an event and leaves the work to the application:

ButtonEvent

Magnifier

TextSearchRequested, carrying the text to search for.

Cross

ClearSearchTextRequested – the handler clears the box and the results.

Chevron

SearchDropListOpenRequested, carrying where to show a list; set IsSearchDropListOpenRequestCompleted back to true when the list closes.

The prompt (CueText) is the Windows cue banner, shown in grey while the box is empty. Set IsSearchCommandSetEnabled to false to keep only the chevron, or IsOnlyWatermarkProvider to true for a plain box with a prompt.

Appearance

The buttons are drawn as vector glyphs, sharp at every display scale, in NormalColorForSearchDropListChevron; the chevron turns HoverColorForSearchDropListChevron under the pointer. Each can be replaced with a picture of your own (SearchCommandInvokerImage, ClearSearchTextCommandInvokerImage, SearchDropListCommandInvokerImage). Each button is as wide as 1.2 times the font height, and at least 24 logical pixels; the text never runs under them.

Tip

Pressing Enter does not raise TextSearchRequested. To search on Enter as well, handle Control.KeyDown, as the example does.

Examples

using System;
using System.Drawing;
using System.Windows.Forms;
using Binarymission.WinForms.Controls.InputControls;

public class CustomerListForm : Form
{
    private readonly SearchTextBox searchBox;
    private readonly ListBox results;
    private readonly ContextMenuStrip recentSearches = new ContextMenuStrip();
    private readonly string[] customers = { "Acme Trading", "Brightwell Ltd", "Carter & Sons", "Northwind Foods" };

    public CustomerListForm()
    {
        Text = "Customers";
        ClientSize = new Size(360, 300);

        searchBox = new SearchTextBox
        {
            Location = new Point(12, 12),
            Width = 336,
            CueText = "Search customers by name",
            NormalColorForSearchDropListChevron = Color.DimGray,
            HoverColorForSearchDropListChevron = Color.SteelBlue
        };
        searchBox.TextSearchRequested += (sender, e) => RunSearch(e.SearchText);
        searchBox.ClearSearchTextRequested += (sender, e) => { searchBox.Clear(); RunSearch(""); };
        searchBox.SearchDropListOpenRequested += SearchBox_SearchDropListOpenRequested;
        searchBox.KeyDown += (sender, e) =>
        {
            if (e.KeyCode == Keys.Enter) { RunSearch(searchBox.Text); e.SuppressKeyPress = true; }
        };

        recentSearches.Items.Add("Northwind");
        recentSearches.Items.Add("Ltd");
        recentSearches.ItemClicked += (sender, e) => { searchBox.Text = e.ClickedItem.Text; RunSearch(e.ClickedItem.Text); };
        recentSearches.Closed += (sender, e) => searchBox.IsSearchDropListOpenRequestCompleted = true;

        results = new ListBox { Location = new Point(12, 44), Size = new Size(336, 244) };

        Controls.Add(searchBox);
        Controls.Add(results);
        RunSearch("");
    }

    private void SearchBox_SearchDropListOpenRequested(object sender, SearchTextBoxDropListInvokedEventArgs e)
    {
        // Show the list under the chevron.
        recentSearches.Show(searchBox, new Point(e.DropListInvokerTopLeftPoint.X, searchBox.Height));
    }

    private void RunSearch(string text)
    {
        results.Items.Clear();
        foreach (string name in customers)
        {
            if (name.IndexOf(text, StringComparison.OrdinalIgnoreCase) >= 0)
            {
                results.Items.Add(name);
            }
        }
    }
}

See also

Members at a glance

Constructors
SearchTextBoxInitialises a search box showing the prompt "Search..." and all three buttons.
Properties
ClearSearchTextCommandInvokerImageGets or sets a picture to show in place of the drawn cross.
CueTextGets or sets the grey prompt shown while the box is empty – "Search orders", "Find a customer".
DefaultDropListChevronBorderColorGets or sets the colour of the outline round the drawn chevron.
DefaultDropListChevronBorderOnHoverColorGets or sets the colour of the chevron's outline while the pointer is over it or its list is open.
DefaultDropListChevronBorderWidthGets or sets the width of the outline round the drawn chevron.
DefaultDropListChevronRotateFlipTypeGets or sets which way the drawn chevron points.
HoverColorForSearchDropListChevronGets or sets the colour of the drawn chevron while the pointer is over it or its list is open.
IsCueTextRenderedWhenInFocusGets or sets whether the prompt stays visible in the empty box while it has the focus.
IsOnlyWatermarkProviderGets or sets whether the box is a plain text box with a prompt, without its three buttons.
IsSearchCommandSetEnabledGets or sets whether the magnifier and the cross are shown; the chevron is shown either way.
IsSearchDropListOpenRequestCompletedGets or sets whether the list opened from the chevron has been dealt with – closed or dismissed.
MarginBetweenTextAndCommandInvokersGets or sets the space left between the end of the text and the magnifier.
MultilineGets whether the box takes more than one line of text – which a search box never does.
NormalColorForSearchDropListChevronGets or sets the colour the drawn magnifier, cross and chevron are drawn in.
ScrollBarsGets which scroll bars the box shows – none, as it holds a single line.
SearchCommandInvokerImageGets or sets a picture to show in place of the drawn magnifier.
SearchDropListCommandChevronFillColorGets or sets a fill colour for the chevron. The chevron is not drawn with it: use NormalColorForSearchDropListChevron and HoverColorForSearchDropListChevron instead.
SearchDropListCommandInvokerImageGets or sets a picture to show in place of the drawn chevron.
Methods
OnDpiChangedAfterParentRaises the Control.DpiChangedAfterParent event and resizes and redraws the buttons for the new display scale.
OnFontChangedRaises the Control.FontChanged event, resizes the buttons for the new font, and re-creates the window so the prompt and the text margin are applied again.
OnHandleCreatedRaises the Control.HandleCreated event and applies the prompt and the space kept free for the buttons, both of which belong to the window.
OnParentChangedRaises the Control.ParentChanged event, resizes the buttons for the font now inherited, and re-creates the window.
OnParentFontChangedRaises the Control.ParentFontChanged event, resizes the buttons for the new font, and re-creates the window.
OnResizeRaises the Control.Resize event and places the three buttons against the right-hand edge for the new size.
RefreshControlBlinkStarts or stops the border blinking, to draw the eye to the box.
Events
ClearSearchTextRequestedOccurs when the user clicks the cross to clear the search.
SearchDropListOpenRequestedOccurs when the user clicks the chevron, asking for a list – recent searches, saved filters – to be shown.
TextSearchRequestedOccurs when the user clicks the magnifier to run a search.

Constructors

SearchTextBox

public SearchTextBox()

Initialises a search box showing the prompt "Search..." and all three buttons.

Properties

ClearSearchTextCommandInvokerImage

public Image ClearSearchTextCommandInvokerImage

Gets or sets a picture to show in place of the drawn cross.

Value
The picture, or null for the drawn cross. The default is null.
Remarks

Scaled to fit the button, keeping its proportions, and centred.

CueText

public string CueText

Gets or sets the grey prompt shown while the box is empty – "Search orders", "Find a customer".

Value
The prompt. The default is "Search...". An empty string shows no prompt.
Remarks

The prompt is the Windows cue banner, drawn by the system in its own grey; it is never part of Control.Text.

See also

DefaultDropListChevronBorderColor

public Color DefaultDropListChevronBorderColor

Gets or sets the colour of the outline round the drawn chevron.

Value
The outline colour. The default is Color.Teal.
Remarks

No outline is drawn until DefaultDropListChevronBorderWidth is above zero.

DefaultDropListChevronBorderOnHoverColor

public Color DefaultDropListChevronBorderOnHoverColor

Gets or sets the colour of the chevron's outline while the pointer is over it or its list is open.

Value
The outline colour. The default is Color.Empty, which draws no outline while the chevron is hot.

DefaultDropListChevronBorderWidth

public float DefaultDropListChevronBorderWidth

Gets or sets the width of the outline round the drawn chevron.

Value
The width in logical pixels. The default is 0: no outline.
See also

DefaultDropListChevronRotateFlipType

public RotateFlipType DefaultDropListChevronRotateFlipType

Gets or sets which way the drawn chevron points.

Value
One of the RotateFlipType values, applied about the chevron's centre. The default is RotateNoneFlipNone: pointing down.
Remarks

Rotate180FlipNone points it up – for a list that opens above the box, say.

HoverColorForSearchDropListChevron

public Color HoverColorForSearchDropListChevron

Gets or sets the colour of the drawn chevron while the pointer is over it or its list is open.

Value
The hover colour. The default is Color.Tomato.
Designer category
Colors
See also

IsCueTextRenderedWhenInFocus

public bool IsCueTextRenderedWhenInFocus

Gets or sets whether the prompt stays visible in the empty box while it has the focus.

Value
true to keep the prompt until the user types; false to hide it as soon as the box takes the focus. The default is true.

IsOnlyWatermarkProvider

public bool IsOnlyWatermarkProvider

Gets or sets whether the box is a plain text box with a prompt, without its three buttons.

Value
true to remove the magnifier, the cross and the chevron; false to show them. The default is false.
Remarks

Setting it to false puts all three buttons back, even if IsSearchCommandSetEnabled is false. While it is true, changes to IsSearchCommandSetEnabled are ignored.

IsSearchCommandSetEnabled

public bool IsSearchCommandSetEnabled

Gets or sets whether the magnifier and the cross are shown; the chevron is shown either way.

Value
true for all three buttons; false to keep only the chevron, for a box whose list does something other than search. The default is true.
Remarks

Ignored while IsOnlyWatermarkProvider is true.

IsSearchDropListOpenRequestCompleted

public bool IsSearchDropListOpenRequestCompleted

Gets or sets whether the list opened from the chevron has been dealt with – closed or dismissed.

Value
true when no list is open; false while one is. The default is true.
Remarks

While it is false the chevron stays in HoverColorForSearchDropListChevron, even after the pointer leaves it. The control sets it to false when it raises SearchDropListOpenRequested; set it to true when the list closes, for example in the menu's Closed event.

MarginBetweenTextAndCommandInvokers

public int MarginBetweenTextAndCommandInvokers

Gets or sets the space left between the end of the text and the magnifier.

Value
The space in logical pixels. The default is 9.
Remarks

Used while the magnifier and the cross are shown; with only the chevron the text runs up to it.

Multiline

public new bool Multiline

Gets whether the box takes more than one line of text – which a search box never does.

Value
Always false.

NormalColorForSearchDropListChevron

public Color NormalColorForSearchDropListChevron

Gets or sets the colour the drawn magnifier, cross and chevron are drawn in.

Value
The glyph colour. The default is Color.SteelBlue.
Designer category
Colors
Remarks

Despite the name, the colour is used for all three drawn buttons. While the box is disabled they are drawn in SystemColors.ControlDark.

See also

ScrollBars

public new ScrollBars ScrollBars

Gets which scroll bars the box shows – none, as it holds a single line.

Value
Always None.

SearchCommandInvokerImage

public Image SearchCommandInvokerImage

Gets or sets a picture to show in place of the drawn magnifier.

Value
The picture, or null for the drawn magnifier. The default is null.
Remarks

The picture is scaled to fit the button, keeping its proportions, and centred. A picture with transparency, 32 x 32 or larger, looks best at high display scales.

SearchDropListCommandChevronFillColor

public Color SearchDropListCommandChevronFillColor

Gets or sets a fill colour for the chevron. The chevron is not drawn with it: use NormalColorForSearchDropListChevron and HoverColorForSearchDropListChevron instead.

Value
The stored colour. The default is Color.Empty.
Designer category
Colors

SearchDropListCommandInvokerImage

public Image SearchDropListCommandInvokerImage

Gets or sets a picture to show in place of the drawn chevron.

Value
The picture, or null for the drawn chevron. The default is null.
Remarks

Scaled to fit the button, keeping its proportions, and centred. A picture does not change colour under the pointer, and DefaultDropListChevronRotateFlipType does not apply to it.

Methods

OnDpiChangedAfterParent

protected override void OnDpiChangedAfterParent(EventArgs e)

Raises the Control.DpiChangedAfterParent event and resizes and redraws the buttons for the new display scale.

Parameters
e
The data for the event.

OnFontChanged

protected override void OnFontChanged(EventArgs e)

Raises the Control.FontChanged event, resizes the buttons for the new font, and re-creates the window so the prompt and the text margin are applied again.

Parameters
e
The data for the event.

OnHandleCreated

protected override void OnHandleCreated(EventArgs e)

Raises the Control.HandleCreated event and applies the prompt and the space kept free for the buttons, both of which belong to the window.

Parameters
e
The data for the event.

OnParentChanged

protected override void OnParentChanged(EventArgs e)

Raises the Control.ParentChanged event, resizes the buttons for the font now inherited, and re-creates the window.

Parameters
e
The data for the event.

OnParentFontChanged

protected override void OnParentFontChanged(EventArgs e)

Raises the Control.ParentFontChanged event, resizes the buttons for the new font, and re-creates the window.

Parameters
e
The data for the event.

OnResize

protected override void OnResize(EventArgs e)

Raises the Control.Resize event and places the three buttons against the right-hand edge for the new size.

Parameters
e
The data for the event.

Events

ClearSearchTextRequested

public event EventHandler ClearSearchTextRequested

Occurs when the user clicks the cross to clear the search.

Remarks

The control does not clear its text; do that in the handler – with Clear – along with resetting whatever the search filtered.

SearchDropListOpenRequested

public event EventHandler<SearchTextBoxDropListInvokedEventArgs> SearchDropListOpenRequested

Occurs when the user clicks the chevron, asking for a list – recent searches, saved filters – to be shown.

Remarks

SearchTextBoxDropListInvokedEventArgs.DropListInvokerTopLeftPoint is the chevron's top-left corner in the search box's client coordinates; show the list there, or below the box.

Before raising the event the control sets IsSearchDropListOpenRequestCompleted to false, which keeps the chevron in its hover colour. Set it back to true when the list closes. The event is not raised, and the property not changed, when no handler is attached.

TextSearchRequested

public event EventHandler<SearchTextBoxRequestEventArgs> TextSearchRequested

Occurs when the user clicks the magnifier to run a search.

Remarks

SearchTextBoxRequestEventArgs.SearchText holds the box's text at the moment of the click – possibly empty. Pressing Enter does not raise this event.

Example
searchBox.TextSearchRequested += (sender, e) =>
    ordersGrid.DataSource = orderRepository.FindByCustomer(e.SearchText);
See also