Skip to content

Document the new properties of the MCCB and Menu #3095

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Oct 16, 2025
Merged

Document the new properties of the MCCB and Menu #3095

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 38 additions & 19 deletions controls/radmenu/features/icons.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: Icons
page_title: Icons
description: Check our "Icons" documentation article for the RadMenu {{ site.framework_name }} control.
description: Check our "Icons" documentation article for the RadMenu WPF control.
slug: radmenu-features-icons
tags: icons
published: True
Expand All @@ -10,16 +10,15 @@ position: 5

# Icons

The __RadMenu__ allows you to display an icon for each of the menu items. This can be done by setting the __Icon__ property of the __RadMenuItem__. For the icon to be displayed as expected, you have to either provide an element of type __Image__ for it or also set the **IconTemplate** property of the item.
The `RadMenu` allows you to display an icon for each of the menu items. This can be done by setting the `Icon` property of the `RadMenuItem`. For the icon to be displayed as expected, you have to either provide an element of type `Image` for it or also set the `IconTemplate` property of the item.

## Setting the Icon of a Static Item

>tipTo learn more about this way of populating the __RadMenu__ with static data take a look at the [Using Static Items]({%slug radmenu-populating-with-data-using-static-items%}) topic.
>tipTo learn more about this way of populating the RadMenu with static data take a look at the [Using Static Items]({%slug radmenu-populating-with-data-using-static-items%}) topic.

When using static items you can directly access the __Icon__ property of each item. Respectively you can set it directly:

__Example 1: Setting the Icon property declaratively__
When using static items you can directly access the Icon property of each item. Respectively you can set it directly:

__Setting the Icon property declaratively__
```XAML
<telerik:RadMenuItem Header="New File">
<telerik:RadMenuItem.Icon>
Expand All @@ -29,22 +28,19 @@ __Example 1: Setting the Icon property declaratively__
</telerik:RadMenuItem>
```

**Figure 1** illustrates the resulting items.

#### Figure 1: RadMenuItems with their Icon property set
__RadMenuItems with their Icon property set__

![RadMenuItems with their Icon property set](images/RadMenu_Features_Icons_01.png)

## Setting the Icon of a Dynamic Item

>tipTo learn more about this way of populating the __RadMenu__ with dynamic data take a look at the [Binding to Dynamic Data]({%slug radmenu-populating-with-data-binding-to-dynamic-data%}) topic.
>tipTo learn more about this way of populating the RadMenu with dynamic data take a look at the [Binding to Dynamic Data]({%slug radmenu-populating-with-data-binding-to-dynamic-data%}) topic.

When using dynamic items, you have to bind the __Icon__ property to a property of the data item. The specific here is that your data item needs to either expose a property of type __Image__, so the __Icon__ property can be bound properly or you need to define the **IconTemplate** property of the menu items if you wish to bind it to a **string** or **Uri**, for example.
When using dynamic items, you have to bind the Icon property to a property of the data item. The specific here is that your data item needs to either expose a property of type Image, so the Icon property can be bound properly or you need to define the IconTemplate property of the menu items if you wish to bind it to a `string` or `Uri`, for example.

Let's assume you've defined the following class which exposes the icon Uri as well as a read-only property which returns an image from this Uri.

__Example 2: MenuItem class with Uri and Image properties__

__MenuItem class with Uri and Image properties__
```C#
public class MenuItem
{
Expand Down Expand Up @@ -90,12 +86,11 @@ __Example 2: MenuItem class with Uri and Image properties__
End Class
```

You can then bind the Icon using any of the two properties. Following the example from the [Binding to Dynamic Data]({%slug radmenu-populating-with-data-binding-to-dynamic-data%}) article, you can add the following setters to **ItemContainerStyle**.
You can then bind the Icon using any of the two properties. Following the example from the [Binding to Dynamic Data]({%slug radmenu-populating-with-data-binding-to-dynamic-data%}) article, you can add the following setters to `ItemContainerStyle`.

* If you wish to bind directly to a property of type Image:

__Example 2: Setting the Icon property to an Image__

__Setting the Icon property to an Image__
```XAML
<!-- If you are using the NoXaml binaries, you will have to base the style on the default one for the theme like so:
<Style TargetType="telerik:RadMenuItem" BasedOn="{StaticResource RadMenuItemStyle}">-->
Expand All @@ -108,8 +103,7 @@ You can then bind the Icon using any of the two properties. Following the exampl

* If you wish to bind directly to a property of type Uri/string:

__Example 3: Setting the Icon property to an Uri/string__

__Setting the Icon property to an Uri/string__
```XAML
<!-- If you are using the NoXaml binaries, you will have to base the style on the default one for the theme like so:
<Style TargetType="telerik:RadMenuItem" BasedOn="{StaticResource RadMenuItemStyle}">-->
Expand All @@ -131,10 +125,35 @@ You can then bind the Icon using any of the two properties. Following the exampl

Both approaches will lead to the same results as when you set the icon declaratively.

#### Figure 2: Dynamic RadMenuItems with their icons
__Dynamic RadMenuItems with their icons__

![Dynamic RadMenuItems with their icons](images/RadMenu_Features_Icons_01.png)

## Setting the Icon Position

The `RadMenuItem` element exposes the `ItemIconPosition` property that allows for specifying the location of the icon. It is of the type of `ItemIconPosition`, which exposes the following two options:

* `Left`&mdash;The icon will be displayed on the left side of the RadMenuItem's content. This is the default value.
* `Right`&mdash;The icon will be displayed on the right side of the RadMenuItem's content.

__Setting the ItemIconPosition property to Right__
```XAML
<telerik:RadMenu>
<telerik:RadMenuItem Header="Options">
<telerik:RadMenuItem Header="Save" ItemIconPosition="Right">
<telerik:RadMenuItem.Icon>
<Image Source="/Images/save.png"
Stretch="UniformToFill"/>
</telerik:RadMenuItem.Icon>
</telerik:RadMenuItem>
</telerik:RadMenuItem>
</telerik:RadMenu>
```

__RadMenuItem with its icon positioned on the right__

![RadMenuItem with its icon positioned on the right](images/menu-features-icon-2.png)

## See Also

* [Checkable Items]({%slug radmenu-features-checkable-items%})
Expand Down
Binary file added controls/radmenu/features/images/menu-features-icon-2.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
61 changes: 33 additions & 28 deletions controls/radmulticolumncombobox/key-properties-and-methods.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: Key Properties and Methods
page_title: Key Properties and Methods
description: Check our &quot;Key Properties and Methods&quot; documentation article for the RadMultiColumnComboBox {{ site.framework_name }} control.
description: Check our &quot;Key Properties and Methods&quot; documentation article for the RadMultiColumnComboBox WPF control.
slug: multicolumncombobox-dropdown-key-properties-and-methods
tags: key, properties, methods
published: True
Expand All @@ -10,21 +10,21 @@ position: 6

# Key Properties and Methods

The article lists the most important properties and methods of __RadMultiColumnComboBox__.
The article lists the most important properties and methods of `RadMultiColumnComboBox`.

## Text Change Without Delay

By default, the reaction of __RadMultiColumnComboBox__ to a text change will be deferred. In case when updating needs to be done immediately, the __DeferTextChange__ property can be set to __False__.
By default, the reaction of RadMultiColumnComboBox to a text change will be deferred. In case when updating needs to be done immediately, the `DeferTextChange` property can be set to __False__.

## Disable Items Highlighting

With all settings for its __AutoCompleteMode, RadMultiColumnComboBox__ will highlight its items. This can be switched off by setting the __HighlightMatches__ property to __False__.
With all settings for its AutoCompleteMode, RadMultiColumnComboBox will highlight its items. This can be switched off by setting the `HighlightMatches` property to __False__.

## Setting Text for an Empty Selection

When there is no selection applied, the control will display an empty AutoCompleteBox. In case a custom text needs to be displayed in it, the __NullText__ property comes in handy.
When there is no selection applied, the control will display an empty AutoCompleteBox. In case a custom text needs to be displayed in it, the `NullText` property comes in handy.

__Example 1: Setting the NullText property__
__Setting the NullText property__
```XAML
<telerik:RadMultiColumnComboBox VerticalAlignment="Top" DisplayMemberPath="Name"
NullText="Please enter input">
Expand All @@ -34,51 +34,56 @@ __Example 1: Setting the NullText property__
</telerik:RadMultiColumnComboBox>
```

#### __Figure 1: MultiColumnComboBox with NullText set__
__MultiColumnComboBox with NullText set__

![MultiColumnComboBox with NullText set](images/MultiColumnComboBox_KeyProperties_01.png)

## Open,Close and Toggle the DropDown

The following set of methods is provided for manipulating the visibility of the DropDown.

* __OpenDropDown__: Opens the DropDown if it is closed.
* __CloseDropDown__: Closes the DropDown if it is opened.
* __ToggleDropDown__: Toggles the opened/closed state of the DropDown.
* `OpenDropDown`&mdash;Opens the DropDown if it is closed.
* `CloseDropDown`&mdash;Closes the DropDown if it is opened.
* `ToggleDropDown`&mdash;Toggles the opened/closed state of the DropDown.

## DropDownElementStyle
## Drop Down Element Style

Since __R1 2019 SP1__, RadMultiColumnComboBox exposes the __DropDownElementStyle__ property. Through it, you can get or set a Style that will be applied to the dropdown element.
RadMultiColumnComboBox exposes the `DropDownElementStyle` property. Through it, you can get or set a Style that will be applied to the dropdown element.

> The TargetType of the Style should match the type of the dropdown element.

## Search Mode

With **R2 2019** we introduced a new **SearchMode** property which allows you to control how items are matched when search is executed. It has the following two possible values:

* **MatchAnyTerm**: Items match the search operation when they fulfill any of the search terms. For example, if `John Terry` is inputted, items containing **any** of the terms "John" and "Terry" in any of their properties will be matched. This is the **default** value.
* **MatchAllTerms**: Items match the search operation only when they fulfill all of the search terms. Continuing with the previous example, if `John Terry` is entered as the search text, only items which contain **both** terms ("John" and "Terry") in any of their properties will be matched.

>important The SearchMode property takes effect only if the **AutoCompleteMode** of the control is **Search**.
The RadMultiColumnComboBox exposes a new `SearchMode` property which allows you to control how items are matched when search is executed. It has the following two possible values:

## SelectionOnFocus
* `MatchAnyTerm`&mdash;Items match the search operation when they fulfill any of the search terms. For example, if `John Terry` is inputted, items containing __any__ of the terms "John" and "Terry" in any of their properties will be matched. This is the default value.
* `MatchAllTerms`&mdash;Items match the search operation only when they fulfill all of the search terms. Continuing with the previous example, if `John Terry` is entered as the search text, only items which contain __both__ terms ("John" and "Terry") in any of their properties will be matched.

With the **R3 2020 SP1 version**, the __SelectionOnFocus__ property of the __RadMultiColumnComboBox__ control was introduced, which allows you to specify what will happen with the cursor when the control gets focus.
>important The SearchMode property takes effect only if the `AutoCompleteMode` of the control is `Search`.

> This property is respected when the **SelectionBoxesVisibility** property is set to **Collapsed**.
## Selection On Focus

The values for the __SelectionOnFocus__ property are predefined in the __SelectionOnFocus__ enumeration. It exposes the following members:
The RadMultiColumnComboBox control exposes the `SelectionOnFocus` property, which allows you to specify what will happen with the cursor when the control gets focus.

* __SelectAll__: Once the control is focused, it will select its whole text.
> This property is respected when the `SelectionBoxesVisibility` property is set to `Collapsed`.

* __CaretToBeginning__: Once the control is focused, the cursor will be positioned at its beginning.
The values for the SelectionOnFocus property are predefined in the `SelectionOnFocus` enumeration. It exposes the following members:

* __CaretToEnd__: Once the control is focused, the cursor will be positioned at its end.
* `SelectAll`&mdash;Once the control is focused, it will select its whole text.
* `CaretToBeginning`&mdash;Once the control is focused, the cursor will be positioned at its beginning.
* `CaretToEnd`&mdash;Once the control is focused, the cursor will be positioned at its end.
* `Unchanged`&mdash;Once the control is focused, the cursor's position won't be changed. This is the default value for the SelectionOnFocus property.
* `Default`&mdash;Once the control is focused, the cursor will be positioned at its end.
* `DefaultSelectAll`&mdash;This property changes the SelectionOnFocus behavior of the control depending on the source of the focus. If the control is focused on mouse click, the Default SelectionOnFocus behavior will be used. If, on the other hand, the control is focused using the __Tab__ key, the SelectAll SelectionOnFocus behavior will be used.

* __Unchanged__: Once the control is focused, the cursor's position won't be changed. This is the __default value__ for the __SelectionOnFocus__ property.
## Clear Selection On Delete Or Back Key

* __Default__: Once the control is focused, the cursor will be positioned at its end.
The RadMultiColumnComboBox control provides the ability to control if the selected item/s will be removed when pressing the Delete or Back key when typing into the input box. This is done via the `ClearSelectionOnDeleteOrBackKey` property and its default value is __True__. Setting it to __False__ will prevent the removal of selected items when pressing the into the input box

* __DefaultSelectAll__: This property changes the __SelectionOnFocus__ behavior of the control depending on the source of the focus. If the control is focused on mouse click, the __Default SelectionOnFocus__ behavior will be used. If, on the other hand, the control is focused using the __Tab__ key, the __SelectAll SelectionOnFocus__ behavior will be used.
__Setting the ClearSelectionOnDeleteOrBackKey property__
```XAML
<telerik:RadMultiColumnComboBox ClearSelectionOnDeleteOrBackKey="False"/>
```

## See Also

Expand Down