diff --git a/docs/fundamentals/data-binding/commanding.md b/docs/fundamentals/data-binding/commanding.md index 3a7c10353..c43a4a440 100644 --- a/docs/fundamentals/data-binding/commanding.md +++ b/docs/fundamentals/data-binding/commanding.md @@ -51,12 +51,15 @@ When the user presses the , the , and when the data binding changes in some way, the calls the `CanExecute` method in the object. If `CanExecute` returns `false`, then the disables itself. This indicates that the particular command is currently unavailable or invalid. -The also attaches a handler on the `CanExecuteChanged` event of . The event is raised from within the viewmodel. When that event is raised, the calls `CanExecute` again. The enables itself if `CanExecute` returns `true` and disables itself if `CanExecute` returns `false`. +The also attaches a handler on the `CanExecuteChanged` event of . The event must be raised manually from within the viewmodel whenever conditions change that affect the `CanExecute` result. When that event is raised, the calls `CanExecute` again. The enables itself if `CanExecute` returns `true` and disables itself if `CanExecute` returns `false`. + +> [!IMPORTANT] +> Unlike some UI frameworks (such as WPF), .NET MAUI does not automatically detect when the return value of `CanExecute` might change. You must manually raise the `CanExecuteChanged` event (or call `ChangeCanExecute()` on the `Command` class) whenever any condition changes that would affect the `CanExecute` result. This is typically done when properties that `CanExecute` depends on are modified. > [!WARNING] > Do not use the `IsEnabled` property of if you're using the command interface. -When your viewmodel defines a property of type , the viewmodel must also contain or reference a class that implements the interface. This class must contain or reference the `Execute` and `CanExecute` methods, and fire the `CanExecuteChanged` event whenever the `CanExecute` method might return a different value. You can use the `Command` or `Command` class included in .NET MAUI to implement the interface. These classes allow you to specify the bodies of the `Execute` and `CanExecute` methods in class constructors. +When your viewmodel defines a property of type , the viewmodel must also contain or reference a class that implements the interface. This class must contain or reference the `Execute` and `CanExecute` methods, and manually fire the `CanExecuteChanged` event whenever the `CanExecute` method might return a different value. You can use the `Command` or `Command` class included in .NET MAUI to implement the interface. These classes allow you to specify the bodies of the `Execute` and `CanExecute` methods in class constructors. > [!TIP] > Use `Command` when you use the `CommandParameter` property to distinguish between multiple views bound to the same property, and the `Command` class when that isn't a requirement. @@ -296,7 +299,7 @@ public class PersonCollectionViewModel : INotifyPropertyChanged When the user clicks the **New** button, the `execute` function passed to the `Command` constructor is executed. This creates a new `PersonViewModel` object, sets a handler on that object's `PropertyChanged` event, sets `IsEditing` to `true`, and calls the `RefreshCanExecutes` method defined after the constructor. -Besides implementing the interface, the `Command` class also defines a method named `ChangeCanExecute`. A viewmodel should call `ChangeCanExecute` for an property whenever anything happens that might change the return value of the `CanExecute` method. A call to `ChangeCanExecute` causes the `Command` class to fire the `CanExecuteChanged` method. The has attached a handler for that event and responds by calling `CanExecute` again, and then enabling itself based on the return value of that method. +Besides implementing the interface, the `Command` class also defines a method named `ChangeCanExecute`. Your viewmodel must call `ChangeCanExecute` for an property whenever anything happens that might change the return value of the `CanExecute` method. A call to `ChangeCanExecute` causes the `Command` class to fire the `CanExecuteChanged` event. The has attached a handler for that event and responds by calling `CanExecute` again, and then enabling itself based on the return value of that method. When the `execute` method of `NewCommand` calls `RefreshCanExecutes`, the `NewCommand` property gets a call to `ChangeCanExecute`, and the calls the `canExecute` method, which now returns `false` because the `IsEditing` property is now `true`.