ComboBox

Represents a drop down control in the browser.

The Wisej.Web.ComboBox control displays a text box combined with a ListBox, which enables the user to select items from the list or enter a new value. Objects in the drop down list can be of any type, the list will show a string representation of each item.

For a full list of properties, methods and events see the API documentation.

Features

Label

The ComboBox control supports the inline Label property. This allows an application to set a label in relation to a ComboBox control without having to create an additional Label control.

pageLabels

Editing

There are three DropDownStyle options that determine whether the user can edit the value in the ComboBox or must select an item from the drop down list:

• DropDown. The ComboBox is editable, the user can either pick an item from the list or enter any value in the editable control. If the value entered by the user is not in the list, the SelectedIndex value will be -1.

• DropDownList. The ComboBox is not editable, the user must pick an item from the list.

• Simple. The ComboBox is editable, like the DropDown option, but the drop down list is always visible making the ComboBox display like a TextBox on top of a ListBox.

AutoComplete Modes

There are six auto complete modes supported by the ComboBox control:

• None (Default). There is no auto complete. The user can type anything and the control will not auto select or suggest any item in the list.

• Suggest. Causes the drop down list to open automatically as soon as the user starts typing and scrolls the list to show the items that start with the edited text. However, it doesn't select any item.

• Append. Automatically completes the text with the full text of the first item that starts with the typed text and highlights the remaining portion of the text. It doesn't select any item, it only completes the text as it's typed. It doesn't open the drop down list, but if the list is already opened it also scrolls the list to show the items that match the text.

• SuggestAppend. It's the combination of Suggest and Append. It opens the drop down list as soon as the user starts typing and completes the text being entered with the text of the first matching item.

• Filter. Automatically opens the list when the user starts typing and filters the items in the list to show only the items that start with the text being typed. See Custom Item Filtering to implement custom filters.

• AppendFilter. It is the combination of Filter and Append. Automatically opens the list when the user starts typing and filters the items in the list to show only the items that start with the text being typed, and completes the text being type with the firs item that matches. See Custom Item Filtering to implement custom filters.

Data Binding

Data binding is fully supported, including formatting and conversion of the value, through the default data binding infrastructure. For the ComboBox the default data property is Text.

In addition to binding the value (Text, or SelectedItem or SelectedValue bindable properties), the ComboBox control also supports data binding to populate the drop down list using the DataSource property in conjunction with the DisplayMember, ValueMember, ToolTipMember and IconMember properties.

You can use DisplayMember, ValueMember, ToolTipMember and IconMember to name which properties to use from objects in the ComboBox.Items list without binding to a DataSource.

When the ShowToolTips property is set to true, the ComboBox control uses the name specified in the ToolTipMember to read the tooltip text to display next to each item in the drop down list.

C#

this.comboBox1.IconMember = "Icon";
this.comboBox1.ValueMember = "ID";
this.comboBox1.DisplayMember = "Name";
this.comboBox1.ToolTipMember = "Tooltip";

this.comboBox1.Items.Add(
	new
	{
		ID = 1,
		Name = "Wisej",
		Icon = "icon-print",
		Tooltip = "Tooltip for item 1"
	});

this.comboBox1.Items.Add(
	new
	{
		ID = 12,
		Name = "Blazor",
		Icon = "icon-exit",
		Tooltip = "Tooltip for item 2"
	});

The code above shows how to add custom objects to the drop down list and bind to their properties.

pageData Binding

Spell Checking

You can enable the browser's built-in spell checking by setting the SpellCheck property to true.

This functionality is entirely based on the browser's current language and spell checking support. If you need to use a third party spell checking you can, but it's outside of the Wisej functionality.

Tool Buttons

This is one of the most useful features that Wisej adds to most controls. The Tools property allows the application to add internal buttons aligned left or right and handle user clicks through the ToolClicked event.

For the ComboBox, the tools are located to the left of the drop down button (arrow).

pageEmbedded Tools

Lazy Events

Some events exposed by the ComboBox control are fired only when there is a handler attached to the event. This features prevents the browser from sending frequent events unless the application has explicitly subscribed to the event.

For example, the KeyDown event is a Lazy Event, otherwise the browser would fire an ajax request every time the user typed a character in the ComboBox.

If you extend a control class and override the On[EventName] method to handle a lazy event without attaching a handler, your code will not be called unless there is an handler attached to the event.

pageEvents

Watermark

Displays a background text in the control when there is no item selected. The watermark text is replaced by the selected item's text and it's restored when the SelectedIndex is reset to -1.

Wisej renders the watermark property to the placeholder HTML attribute, if it's supported by the browser, otherwise it creates an overlaid label entirely managed by the Wisej JavaScript library.

Character Casing

Use the CharacterCasing property to force the browser and the server to change the casing of the text entered by the user. Wisej performs the transformation on the client when typing and on the server when assigning the Text property.

HTML Text

Use the AllowHtml property to render the text in the items as plain HTML. This feature allows an application to render any type of content in the drop down list.

An item with this text "<big><big><big>A</big></big></big>ustralia" is rendered like this:

Wisej uses the plain text version of the item's HTML text for item filtering, and the AutoCompleteMode options.

How To

Filter keyboard input

Unlike the TextBox control, the ComboBox doesn't provide a Filter property. You can, however, attach to the "keydown" JavaScript event on the client and filter the keyboard input.

It is not possible to stop the <input> element from accepting a character by handling the KeyDown event on the server side - the event has already happened and it has already been processed by the browser by the time it reaches the server.

For example, to allow the user to only type alphabetical characters in the range a-z or A-Z add an handler for the keydown event and prevent the default processing by the browser when the typed character doesn't match the expression.

Customize the appearance

There are several ways to customize the appearance of a ComboBox: use the available properties, customize the theme, or adding custom styles.

The properties that can change the appearance of a ComboBox (and most controls) are usually limited to BackColor, ForeColor, BorderStyle, and Font properties.

If you need to achieve some very special UI design, like the Material-3 animated underline when the ComboBox gains the focus, you will have to either create a custom theme, or a theme mixin or add custom styles to the control.

You can see in the image above a ComboBox with "border:2px solid green;border-radius:20px" assigned to the CssStyle property. To apply a shared style, set the CssClass property instead and add a StyleSheet file (.css) to the application either in Default.html or using the StyleSheet extender.

Change the size of the items

The minimum height of the items in the drop down list is set in the theme under the "combobox" appearance: combobox/states/default/properties/itemHeight.

However, the rendered height in the browser depends on the content of each item and the font. You can change the minimum height either in the theme or programmatically by setting the ComboBox.ItemHeight property, in pixels.

Advanced

Lazy Loading

By default, all the items of a ComboBox are sent to the browser together with the data necessary for the creation of the ComboBox widget. However, what if the user never drops down a particular ComboBox and just wants to read the selected item, and that ComboBox happens to have 5,000 items? There is no reason to send all that data back to the browser unless the user opens the drop down list.

Set the LazyLoading property to true and Wisej will take care of the rest. It will show the selected item as if the list is already populated and, when the user open the list, it will show an ajax loader icon over the drop down button while it retrieves the items from the server.

If the ComboBox.Items collection is already populated, Wisej sends back to the browser all the items in the list. However, when LazyLoading is true, it also fires the Load event allowing the application to add items to the list the first time it's opened by the user.

While the Load event is fired only the first time a LazyLoading ComboBox is opened, the DropDown event is always fired, with or without LazyLoading, giving your app a chance to update the items list every time the user opens the drop down list.

Virtual Scrolling

The ComboBox in Wisej can handle an unlimited number of items (we have projects with close to 100,000 items in a ComboBox!) However, creating too many widgets - each item is a widget - will impact the performance of the browser. Fortunately, Wisej implements a sophisticated virtual scrolling infrastructure for all controls that manage child items.

For the ComboBox, ListBox, and TreeView it's the VirtualScroll property. Set VirtualScroll to true and the JavaScript widget will only render the visible items allowing your application to show huge amount of data with no impact to the browser performance.

Custom Item Rendering

Override the dynamic RenderItem(object item) method to implement your custom rendering of the items in the list. This method is called for each item in the list and returns a dynamic object representing the corresponding widget in the list. Since each item is an actual widget, the rendering object can specify any valid widget property.

For example, if you have a ComboBox that shows a list of strings (countries) and you want to show all the ones that start with "A" with a yellow background and the ones that start with "B" with a blue background:

This is the simple override:

C#

protected override dynamic RenderItem(object item)
{
		var config = base.RenderItem(item);
		
		var text = (string)item;
		if (text.StartsWith("A"))
			config.backgroundColor = "yellow";
		else if (text.StartsWith("B"))
			config.backgroundColor = "cyan";

		return config;
}

VB.NET

Protected Overrides Function RenderItem(item As Object) As <Dynamic> Object

	Dim config = MyBase.RenderItem(item)

	Dim text As String = item
	If text.StartsWith("A") Then
		config.backgroundColor = "yellow"
	ElseIf text.StartsWith("B") Then
		config.backgroundColor = "cyan"
	End If

	Return config

End Function

Remember that in VB.NET you need to use Option Strict Off for dynamic objects or use the indexer for the fields of the dynamic object.

Custom Item Filtering

Items in the drop down list are filtered as the user types when the AutoCompleteMode is set to either Filter or AppendFilter. The built-in filter matches the starting text of the items in a case insensitive comparison.

If you want to implement a different filtering algorithm you can do it simply by overriding the onFilterListItem(label, text) JavaScript function in the wisej.web.ComboBox JavaScript class. You can install the method override on a specific control, or you can patch the wisej.web.ComboBox class, or you can create a new custom JavaScript class.

To install a specific custom filter on a ComboBox control, add your JavaScript override to the InitScript property:

Return true to include the item represented by label or false to remove it from the list.

JavaScript Widget

Item	Description
Class name	"wisej.web.ComboBox" or "wisej.web.VirtualComboBox" when VirtualScroll is true.
Theme appearance	"combobox", "listitem" for the items in the drop down, see Themes.
Child components	"textfield" is the inner <input> widget, "button" is the drop down button, "list" is the drop down list, "popup" is the container of the drop down list, "labelfield" is the inner content when the ComboBox is not editable, and "icon" is the icon for the selected item when it shows an icon. See JavaScript.
ToolContainer state	"editor", see Embedded Tools.
Source code	https://github.com/iceteagroup/wisej-js