Skip to content

Update combobox.md for IsEditable changes #633

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

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Update combobox.md for IsEditable changes #633

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d34a8b7
Update combobox.md for IsEditable changes
almightyju Apr 3, 2025
140ae24
Update combobox.md after some changes to the code
almightyju Apr 4, 2025
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
24 changes: 24 additions & 0 deletions docs/reference/controls/combobox.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,8 @@ You will probably use these properties most often:
| `MaxDropDownHeight` | The maximum height for the dropdown list. This is the actual height of the list part, not the number of items that show. |
| `ItemPanel` | The container panel to place items in. By default, this is a StackPanel. See [this page](../../concepts/custom-itemspanel) to customise the ItemsPanel.|
| `Styles` | The style that is applied to any child element of the ItemControl. |
| `IsEditable` | Allows the user to type any value into the `ComboBox`. Make sure to use `DisplayMemberBinding` or `TextSearch.TextBinding` if using complex item types. |
| `Text` | When `IsEditable` will be the text value of the `SelectedItem` or the text a user has entered. |

## Examples

Expand Down Expand Up @@ -125,6 +127,28 @@ namespace AvaloniaControls.Views

<img src={ComboBoxDataTemplateScreenshot} alt="" />

When using `IsEditable` with complex types it is important to set either `DisplayMemberBinding` or `TextSearch.TextBinding`, or both.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What happens if you don't?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It'll throw an error

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would say that should be mentioned somewhere then.

A complex example of the editable text using `Id` to match items when typing in text, but the showing `DisplayValue` in the dropdown is found below:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this needs to be reworded. It took me a few tries to parse it. Perhaps:

Suggested change
A complex example of the editable text using `Id` to match items when typing in text, but the showing `DisplayValue` in the dropdown is found below:
The below example uses a property named `Id`, to match items when typing in text to a `ComboBox` that has `IsEditable` set to true. The display value in the `ComboBox` will be the bound `DisplayValue` value:

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah this one is tricky without a visual, I went thought a few iterations myself. Basically in that example:

  • Items in the open dropdown will display using DisplayMemberBinding
  • The editable portion (i.e. TextBox) will select items that match TextSearch.TextBinding and also display the value using TextSearch.TextBinding

Does listing those bullet points make more sense how it works to you?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is certainly an improvement. If you do go with that, I would suggest a slight change:

Say "will select an item that matches" instead of "selects items", as it makes it sounds like it will match multiple values at once.


```xml
<ComboBox PlaceholderText="Editable" IsEditable="true"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Put IsEditable on a different line like the rest of the properties are. It makes it a lot more readable. I almost missed it was there.

ItemsSource="{Binding MyComplexItems}"
Text="{Binding EditableText}"
DisplayMemberBinding="{Binding DisplayValue}"
TextSearch.TextBinding="{Binding Id, DataType=viewModels:ComplexItem}"
SelectedItem="{Binding Selected}" />
```

```csharp title='C#'
public record ComplexItem(int Id, string DisplayValue);
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I generally suggest people avoid using newer C# features like records for docs. Avalonia technically supports all the way back to .NET 4.8, which means people may have to rewrite the code if they are trying to use it there.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good point, I was trying to make the c# part concise, I'll update to use a class instead


public class ViewModel
{
public string EditableText { get; set; }
public ComplexItem? Selected { get; set; }
}
```

## More Information

:::info
Expand Down