|
|
@@ -35,8 +35,6 @@ Tenets higher in the list have precedence over tenets lower in the list.
|
|
|
|
|
|
* **Decouple Concepts** - In v1 `CanFocus` is tightly coupled with `HasFocus`, `TabIndex`, `TabIndexes`, and `TabStop` and vice-versa. There was a bunch of "magic" logic that automatically attempted to keep these concepts aligned. This resulted in a poorly specified, hard-to-test, and fragile API. In v2 we strive to keep the related navigation concepts decoupled. For example, `CanFocus` and `TabStop` are decoupled. A view with `CanFocus == true` can have `TabStop == NoStop` and still be focusable with the mouse.
|
|
|
|
|
|
-# Design
|
|
|
-
|
|
|
## Keyboard Navigation
|
|
|
|
|
|
The majority of the Terminal.Gui Navigation system is dedicated to enabling the keyboard to be used to navigate Views.
|
|
|
@@ -56,13 +54,13 @@ Terminal.Gui defines these keys for keyboard navigation:
|
|
|
|
|
|
These keys are all registered as `KeyBindingScope.Application` key bindings by `Application`. Because application-scoped key bindings have the lowest priority, Views can override the behaviors of these keys (e.g. `TextView` overrides `Key.Tab` by default, enabling the user to enter `\t` into text). The `AllViews_AtLeastOneNavKey_Leaves` unit test ensures all built-in Views have at least one of the above keys that can advance.
|
|
|
|
|
|
-### `HotKey`
|
|
|
+### HotKeys
|
|
|
|
|
|
See also [Keyboard](keyboard.md) where HotKey is covered more deeply...
|
|
|
|
|
|
-In v2, `HotKey`s can be used to navigate across the entire application view-hierarchy. They work independently of `Focus`. This enables a user to navigate across a complex UI of nested subviews if needed (even in overlapped scenarios). An example use case is the `AllViewsTester` scenario.
|
|
|
+`HotKeys` can be used to navigate across the entire application view-hierarchy. They work independently of `Focus`. This enables a user to navigate across a complex UI of nested subviews if needed (even in overlapped scenarios). An example use case is the `AllViewsTester` Scenario.
|
|
|
|
|
|
-Additionally, in v2, multiple Views in an application (even within the same SuperView) can have the same HotKey. Each press of the HotKey will invoke the next HotKey across the View hierarchy (NOT IMPLEMENTED YET see https://github.com/gui-cs/Terminal.Gui/issues/3554).
|
|
|
+Additionally, multiple Views in an application (even within the same SuperView) can have the same HotKey. Each press of the HotKey will invoke the next HotKey across the View hierarchy (NOT IMPLEMENTED YET see https://github.com/gui-cs/Terminal.Gui/issues/3554).
|
|
|
|
|
|
## Mouse Navigation
|
|
|
|
|
|
@@ -80,21 +78,15 @@ If the View was not previously focused, `AdvanceFocus()` is called.
|
|
|
|
|
|
For this to work properly, there must be logic that removes the focus-cache used by `RestoreFocus()` if something changes that makes the previously-focusable view not focusable (e.g. if Visible has changed).
|
|
|
|
|
|
-## `Application`
|
|
|
-
|
|
|
-At the application level, navigation is encapsulated within the `ApplicationNavigation` helper class which is publicly exposed via the `Application.Navigation` property.
|
|
|
-
|
|
|
-### `Application.Navigation.GetFocused ()`
|
|
|
+## Application Level Navigation
|
|
|
|
|
|
-Gets the most-focused View in the application. Will return `null` if there is no view with focus (an extremely rare situation). This replaces `View.MostFocused` in v1.
|
|
|
+At the application level, navigation is encapsulated within the @Terminal.Gui.ApplicationNavigation helper class which is publicly exposed via the @Terminal.Gui.Application.Navigation property.
|
|
|
|
|
|
-### `Application.Navigation.FocusedChanged` and `Application.Navigation.FocusedChanging`
|
|
|
[email protected] gets the most-focused View in the application. Will return `null` if there is no view with focus (an extremely rare situation). This replaces `View.MostFocused` in v1.
|
|
|
|
|
|
-Events raised when the most-focused View in the application is changing or has changed. `FocusedChanged` is useful for apps that want to do something with the most-focused view (e.g. see `AdornmentsEditor`). `FocusChanging` is useful apps that want to override what view can be focused across an entire app.
|
|
|
+The @Terminal.Gui.ApplicationNavigation.FocusedChanged and @Terminal.Gui.ApplicationNavigation.FocusedChanging events are raised when the most-focused View in the application is changing or has changed. `FocusedChanged` is useful for apps that want to do something with the most-focused view (e.g. see `AdornmentsEditor`). `FocusChanging` is useful apps that want to override what view can be focused across an entire app.
|
|
|
|
|
|
-### `Application.Navigation.AdvanceFocus (NavigationDirection direction, TabBehavior? behavior)`
|
|
|
-
|
|
|
-Causes the focus to advance (forward or backwards) to the next View in the application view-hierarchy, using `behavior` as a filter.
|
|
|
+The @Terminal.Gui.ApplicationNavigation.AdvanceFocus(Terminal.Gui.NavigationDirection,System.Nullable{Terminal.Gui.TabBehavior}) method causes the focus to advance (forward or backwards) to the next View in the application view-hierarchy, using `behavior` as a filter.
|
|
|
|
|
|
The implementation is simple:
|
|
|
|
|
|
@@ -106,10 +98,11 @@ This method is called from the `Command` handlers bound to the application-scope
|
|
|
|
|
|
This method replaces about a dozen functions in v1 (scattered across `Application` and `Toplevel`).
|
|
|
|
|
|
-## `View`
|
|
|
+## View Level Navigation
|
|
|
|
|
|
-At the View-level, navigation is encapsulated within `View.Navigation.cs`.
|
|
|
+@Terminal.Gui.View.AdvanceFocus(Terminal.Gui.NavigationDirection,System.Nullable{Terminal.Gui.TabBehavior}) is the primary method for developers to cause a view to gain or lose focus.
|
|
|
|
|
|
+Various events are raised when a View's focus is changing. For example, @Terminal.Gui.View.HasFocusChanging and @Terminal.Gui.View.HasFocusChanged.
|
|
|
|
|
|
## What makes a View focusable?
|
|
|
|
|
|
@@ -173,41 +166,9 @@ In v2, developers need to explicitly set `CanFocus` for any view in the view-hie
|
|
|
|
|
|
In v2, the automatic setting of `TabStop` in `Add` is retained because it is not overly complex to do so and is a nice convenience for developers to not have to set both `Tabstop` and `CanFocus`. Note we do NOT automatically change `CanFocus` if `TabStop` is changed.
|
|
|
|
|
|
-## Overriding `HasFocus` changes - `OnEnter/OnLeave` and `Enter/Leave`
|
|
|
-
|
|
|
-These virtual methods and events are raised when a View's `HasFocus` property is changing. In v1 they were poorly defined and weakly implemented. For example, `OnEnter` was `public virtual OnEnter` and it raised `Enter`. This meant overrides needed to know that the base raised the event and remember to call base. Poor API design.
|
|
|
-
|
|
|
-`FocusChangingEventArgs.Handled` in v1 was documented as
|
|
|
-
|
|
|
-```cs
|
|
|
- /// <summary>
|
|
|
- /// Indicates if the current focus event has already been processed and the driver should stop notifying any other
|
|
|
- /// event subscriber. It's important to set this value to true specially when updating any View's layout from inside the
|
|
|
- /// subscriber method.
|
|
|
- /// </summary>
|
|
|
-```
|
|
|
-
|
|
|
-This is clearly copy/paste documentation from keyboard code and describes incorrect behavior. In practice this is not what the implementation does. Instead the system never even checks the return value of `OnEnter` and `OnLeave`.
|
|
|
+## Knowing When a View's Focus is Changing
|
|
|
|
|
|
-Additionally, in v1 `private void SetHasFocus (bool newHasFocus, View view, bool force = false)` is confused too complex.
|
|
|
-
|
|
|
-In v2, `SetHasFocus ()` is replaced by `private bool EnterFocus (View view)` and `private bool LeaveFocus (View view)`. These methods follow the standard virtual/event pattern:
|
|
|
-
|
|
|
-- Check pre-conditions:
|
|
|
- - For `EnterFocus` - If the view is not focusable (not visible, not enabled, or `CanFocus == false`) returns `true` indicating the change was cancelled.
|
|
|
- - For `EnterFocus` - If `CanFocus == true` but the `SuperView.CanFocus == false` throws an invalid operation exception.
|
|
|
- - For `EnterFocus` - If `HasFocus` is already `true` throws an invalid operation exception.
|
|
|
- - For `LeaveFocus` - If `HasFocus` is already `false` throws an invalid operation exception.
|
|
|
-- Call the `protected virtual bool OnEnter/OnLeave (View?)` method. If the return value is `true` stop and return `true`, preventing the focus change. The base implementations of these simply return `false`.
|
|
|
-- Otherwise, raise the cancelable event (`Enter`/`Leave`). If `args.Cancel == true` stop and return `true`, preventing the focus change.
|
|
|
-- Check post-conditions: If `HasFocus` has not changed, throw an invalid operation exception.
|
|
|
-- Return `false` indicating the change was not cancelled (or invalid).
|
|
|
-
|
|
|
-The `Enter` and `Leave` events use `FocusChangingEventArgs` which provides both the old and new Views. `FocusChangingEventArgs.Handled` changes to `Cancel` to be more clear on intent.
|
|
|
-
|
|
|
-These could also be named `Gain/Lose`. They could also be combined into a single method/event: `HasFocusChanging`.
|
|
|
-
|
|
|
-QUESTION: Should we retain the same names as in v1 to simplify porting? Or, given the semantics of `Handled` v. `Cancel` are reversed would it be better to rename and/or combine?
|
|
|
[email protected] and @Terminal.Gui.View.HasFocusChanged are raised when a View's focus is changing.
|
|
|
|
|
|
## Built-In Views Interactivity
|
|
|
|
|
|
@@ -222,454 +183,9 @@ QUESTION: Should we retain the same names as in v1 to simplify porting? Or, give
|
|
|
| **Slider** | > 1 | No | No | 1 | SetFocusedOption | SetFocusedOption<br>OnAccept | Focus | SetFocus<br>SetFocusedOption | | SetFocus<br>SetFocusedOption | | Yes |
|
|
|
| **ListView** | > 1 | No | No | 1 | MarkUnMarkRow | OpenSelectedItem<br>OnAccept | OnAccept | SetMark<br>OnSelectedChanged | OpenSelectedItem<br>OnAccept | | | No |
|
|
|
|
|
|
-### v1 Behavior
|
|
|
-
|
|
|
-In v1, within a set of focusable subviews that are TabStops, and within a view hierarchy containing TabGroups, the default order in which views gain focus is the same as the order the related views were added to the SuperView. As `superView.Add (view)` is called, each view is added to the end of the `TabIndexes` list.
|
|
|
-
|
|
|
-`TabIndex` allows this order to be changed without changing the order in `SubViews`. When `view.TabIndex` is set, the `TabIndexes` list is re-ordered such that `view` is placed in the list after the peer-view with `TabIndex-1` and before the peer-view with `TabIndex+1`.
|
|
|
-
|
|
|
-QUESTION: With this design, devs are required to ensure `TabIndex` is unique. It also means that `set_TabIndex` almost always will change the passed value. E.g. this code will almost always assert:
|
|
|
-
|
|
|
-```cs
|
|
|
-view.TabIndex = n;
|
|
|
-Debug.Assert (view.TabIndex == n);
|
|
|
-```
|
|
|
-
|
|
|
-This is horrible API design.
|
|
|
-
|
|
|
-### Proposed New Design
|
|
|
-
|
|
|
-In `Win32` there is no concept of tab order beyond the Z-order (the equivalent to the order superview.Add was called).
|
|
|
-
|
|
|
-In `WinForms` the `Control.TabIndex` property:
|
|
|
-
|
|
|
-> can consist of any valid integer greater than or equal to zero, lower numbers being earlier in the tab order. If more than one control on the same parent control has the same tab index, the z-order of the controls determines the order to cycle through the controls.
|
|
|
-
|
|
|
-In `WPF` the `UserControl.Tabindex` property:
|
|
|
-
|
|
|
-> When no value is specified, the default value is MaxValue. The system then attempts a tab order based on the declaration order in the XAML or child collections.
|
|
|
-
|
|
|
-Terminal.Gui v2 should adopt the `WinForms` model.
|
|
|
-
|
|
|
-# Implementation Plan
|
|
|
-
|
|
|
-A bunch of the above is the proposed design. Eventually `Toplevel` will be deleted. Before that happens, the implementation will retain dual code paths:
|
|
|
-
|
|
|
-- The old `Toplevel` and `OverlappedTop` code. Only utilized when `IsOverlappedContainer == true`
|
|
|
-- The new code path that treats all Views the same but relies on the appropriate combination of `TabBehavior` and `ViewArrangement` settings as well as `IRunnable`.
|
|
|
-
|
|
|
-
|
|
|
-# Rough Design Notes
|
|
|
-
|
|
|
## Accesibilty Tenets
|
|
|
|
|
|
See https://devblogs.microsoft.com/dotnet/the-journey-to-accessible-apps-keyboard-accessible/
|
|
|
|
|
|
https://github.com/dotnet/maui/issues/1646
|
|
|
|
|
|
-## Focus Chain & DOM ideas
|
|
|
-
|
|
|
-The navigation/focus code in `View.Navigation.cs` has been rewritten in v2 (in https://github.com/gui-cs/Terminal.Gui/pull/3627) to simplify and make more robust.
|
|
|
-
|
|
|
-The design is fundamentally the same as in v1: The logic for tracking and updating the focus chain is based on recursion up and down the `View.Subviews`/`View.SuperView` hierarchy. In this model, there is the need for tracking state during recursion, leading to APIs like the following:
|
|
|
-
|
|
|
-```cs
|
|
|
-// From v1/early v2: Note the `force` param.
|
|
|
-private void SetHasFocus (bool newHasFocus, View view, bool force = false)
|
|
|
-
|
|
|
-// From #3627: Note the `traversingUp` param
|
|
|
- private bool EnterFocus ([CanBeNull] View leavingView, bool traversingUp = false)
|
|
|
-```
|
|
|
-
|
|
|
-The need for these "special-case trackers" is clear evidence of poor architecture. Both implementations work, and the #3627 version is far cleaner, but a better design could result in further simplification.
|
|
|
-
|
|
|
-For example, moving to a model where `Application` is responsible for tracking and updating the focus chain instead `View`. We would introduce a formalization of the *Focus Chain*.
|
|
|
-
|
|
|
-**Focus Chain**: A sequence or hierarchy of UI elements (Views) that determines the order in which keyboard focus is navigated within an application. This chain represents the potential paths that focus can take, ensuring that each element can be reached through keyboard navigation. Instead of using recursion, the Focus Chain can be implemented using lists or trees to maintain and update the focus state efficiently at the `Application` level.
|
|
|
-
|
|
|
-By using lists or trees, you can manage the focus state without the need for recursive traversal, making the navigation model more scalable and easier to maintain. This approach allows you to explicitly define the order and structure of focusable elements, providing greater control over the navigation flow.
|
|
|
-
|
|
|
-Now, the interesting thing about this, is it really starts to look like a DOM!
|
|
|
-
|
|
|
-Designing a DOM (Document Object Model) for UI library involves creating a structured representation of the UI elements and their relationships.
|
|
|
-
|
|
|
-1. Hierarchy and Structure- Root Node: The top-level node representing the entire application or window.
|
|
|
- - View Nodes: Each UI element (View) is a node in the DOM. These nodes can have child nodes, representing nested or contained elements.
|
|
|
-2. Node Properties- Attributes: Each node can have attributes such as id, class, style, and custom properties specific to the View.
|
|
|
- - State: Nodes can maintain state information, such as whether they are focused, visible, enabled, etc.
|
|
|
-3. Traversal Methods- Parent-Child Relationships: Nodes maintain references to their parent and children, allowing traversal up and down the hierarchy.
|
|
|
- - Sibling Relationships: Nodes can also maintain references to their previous and next siblings for easier navigation.
|
|
|
-4. Event Handling- Event Listeners: Nodes can have event listeners attached to handle user interactions like clicks, key presses, and focus changes.
|
|
|
- - Event Propagation: Events can propagate through the DOM, allowing for capturing and bubbling phases similar to web DOM events.
|
|
|
-5. Focus Management- Focus Chain: Maintain a list or tree of focusable nodes to manage keyboard navigation efficiently.
|
|
|
- - Focus Methods: Methods to programmatically set and get focus, ensuring the correct element is focused based on user actions or application logic.
|
|
|
-6. Mouse Events - Mouse handling in Terminal.Gui involves capturing and responding to mouse events such as clicks, drags, and scrolls. In v2, mouse events are managed at the View level, but for a DOM-like structure, this should be centralized.
|
|
|
-7. Layout - The Pos/Dim system in Terminal.Gui is used for defining the layout of views. It allows for dynamic positioning and sizing based on various constraints. For a DOM-model we'd maintain the Pos/Dim system but ensure the layout calculations are managed by the DOM manager.
|
|
|
-8. Drawing - Drawing in Terminal.Gui involves rendering text, colors, and shapes. This is handled within the View class today. In a DOM model we'd centralize the drawing logic in the DOM manager to ensure consistent rendering.
|
|
|
-
|
|
|
-This is all well and good, however we are NOT going to fully transition to a DOM in v2. But we may start with Focus/Navigation (item 3 above). Would could retain the existing external `View` API for focus (e.g. `View.SetFocus`, `Focused`, `CanFocus`, `TabIndexes`, etc...) but refactor the implementation of those to leverage a `FocusChain` (or `FocusManager`) at the `Application` level.
|
|
|
-
|
|
|
-(Crap code generated by Copilot; but gets the idea across):
|
|
|
-
|
|
|
-```cs
|
|
|
-public class FocusChain {
|
|
|
- private List<View> focusableViews = new List<View>();
|
|
|
- private View currentFocusedView;
|
|
|
-
|
|
|
- public void RegisterView(View view) {
|
|
|
- if (view.CanFocus) {
|
|
|
- focusableViews.Add(view);
|
|
|
- focusableViews = focusableViews.OrderBy(v => v.TabIndex).ToList();
|
|
|
- }
|
|
|
- }
|
|
|
-
|
|
|
- public void UnregisterView(View view) {
|
|
|
- focusableViews.Remove(view);
|
|
|
- }
|
|
|
-
|
|
|
- public void SetFocus(View view) {
|
|
|
- if (focusableViews.Contains(view)) {
|
|
|
- currentFocusedView?.LeaveFocus();
|
|
|
- currentFocusedView = view;
|
|
|
- currentFocusedView.EnterFocus();
|
|
|
- }
|
|
|
- }
|
|
|
-
|
|
|
- public View GetFocusedView() {
|
|
|
- return currentFocusedView;
|
|
|
- }
|
|
|
-
|
|
|
- public void MoveFocusNext() {
|
|
|
- if (focusableViews.Count == 0) return;
|
|
|
- int currentIndex = focusableViews.IndexOf(currentFocusedView);
|
|
|
- int nextIndex = (currentIndex + 1) % focusableViews.Count;
|
|
|
- SetFocus(focusableViews[nextIndex]);
|
|
|
- }
|
|
|
-
|
|
|
- public void MoveFocusPrevious() {
|
|
|
- if (focusableViews.Count == 0) return;
|
|
|
- int currentIndex = focusableViews.IndexOf(currentFocusedView);
|
|
|
- int previousIndex = (currentIndex - 1 + focusableViews.Count) % focusableViews.Count;
|
|
|
- SetFocus(focusableViews[previousIndex]);
|
|
|
- }
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-
|
|
|
-
|
|
|
-# NOTES
|
|
|
-
|
|
|
-v1 was all over the map for how the built-in Views dealt with common keyboard user-interactions such as pressing `Space`, `Enter`, or the `Hotkey`. Same for mouse interactions such as `Click` and`DoubleClick`.
|
|
|
-
|
|
|
-I fixed a bunch of this a while back in v2 for `Accept` and `Hotkey` as part of making `Shortcut` and the new `StatusBar` work. `Shortcut` is a compbound View that needs to be able to host any view as `CommandView` and translate user-actions of those subviews in a consistent way.
|
|
|
-
|
|
|
-As I've been working on really making `Bar` support a replacement for `Menu`, `ContextMenu`, and `MenuBar` I've found that my work wasn't quite right and didn't go far enough.
|
|
|
-
|
|
|
-This issue is to document and track what I've learned and lay out the design for addressing this correcxtly.
|
|
|
-
|
|
|
-Related Issues:
|
|
|
-
|
|
|
-- #2975
|
|
|
-- #3493
|
|
|
-- #2404
|
|
|
-- #3631
|
|
|
-- #3209
|
|
|
-- #385
|
|
|
-
|
|
|
-I started fixing this in
|
|
|
-
|
|
|
-- #3749
|
|
|
-
|
|
|
-However, I'm going to branch that work off to a new branch derived from `v2_develop` to address this issue separately.
|
|
|
-
|
|
|
-Here's a deep-dive into the existing built-in Views that indicate the inconsistencies.
|
|
|
-
|
|
|
-| | | | | **Keyboard** | | | | **Mouse** | | | | |
|
|
|
-|----------------|-------------------------|------------|---------------|--------------|--------------------------------------|--------------------------------------------------|---------------------------------------|-------------------------------|------------------------------|-------------------------------|----------------|---------------|
|
|
|
-| | **Number<br>of States** | **Static** | **IsDefault** | **Hotkeys** | **Select<br>Command<br>`Space`** | **Accept<br>Command<br>`Enter`** | **Hotkey<br>Command** | **CanFocus<br>Click** | **CanFocus<br>DblCLick** | **!CanFocus<br>Click** | **RightClick** | **GrabMouse** |
|
|
|
-| **View** | 1 | Yes | No | 1 | | OnAccept | Focus | Focus | | | | No |
|
|
|
-| **Label** | 1 | Yes | No | 1 | | OnAccept | FocusNext | Focus | | FocusNext | | No |
|
|
|
-| **Button** | 1 | No | Yes | 1 | Focus<br>OnAccept | Focus<br>OnAccept | Focus<br>OnAccept | Focus<br>OnAccept | | OnAccept | | No |
|
|
|
-| **Checkbox** | 3 | No | No | 1 | AdvanceCheckState<br>OnAccept | AdvanceCheckState<br>OnAccept | AdvanceCheckState<br>OnAccept | AdvanceCheckState<br>OnAccept | | AdvanceCheckState<br>OnAccept | | No |
|
|
|
-| **RadioGroup** | > 1 | No | No | 2+ | Set SelectedItem<br>OnAccept | Set SelectedItem<br>OnAccept | Focus<br>Set SelectedItem<br>OnAccept | SetFocus<br>Set _cursor | | SetFocus<br>Set _cursor | | No |
|
|
|
-| **Slider** | > 1 | No | No | 1 | SetFocusedOption<br>OnOptionsChanged | SetFocusedOption<br>OnOptionsChanged<br>OnAccept | Focus | SetFocus<br>SetFocusedOption | | SetFocus<br>SetFocusedOption | | Yes |
|
|
|
-| **ListView** | > 1 | No | No | 1 | MarkUnMarkRow | OpenSelectedItem<br>OnAccept | OnAccept | SetMark<br>OnSelectedChanged | OpenSelectedItem<br>OnAccept | | | No |
|
|
|
-
|
|
|
-Next, I'll post a table showing the proposed design.
|
|
|
-
|
|
|
-This will involve adding `View.OnSelect` virtual method and a `Select` event to `View`.
|
|
|
-
|
|
|
-## User Interaction Model
|
|
|
-
|
|
|
-Here's what we're really talking about here: What is the correct user interaction model for common actions on Views within a container. See `navigation.md` for the baseline. Here we're going beyond that to focus on:
|
|
|
-
|
|
|
-- What happens when there are bunch of SubViews and the user presses `Enter` with the intention of "accepting the current state".
|
|
|
-- What happens when the user presses `Space` with the intention of changing the selection of the currently focused View. E.g. which list item is selected or the check state?
|
|
|
-- What happens when the user presses `HotKey` with the intention of causing some non-focused View to EITHER "accept the current state" (`Button`), or "change a selection" (`RadioGroup`).
|
|
|
-
|
|
|
-Same for mouse interaction:
|
|
|
-
|
|
|
-- What happens when I click on a non-focused View?
|
|
|
-- What if that view has `CanFocus == false`?
|
|
|
-
|
|
|
-This gets really interesting when there's a View like a `Shortcut` that is a composite of several subviews.
|
|
|
-
|
|
|
-### New Model
|
|
|
-
|
|
|
-| | | | | **Keyboard** | | | | **Mouse** | | | | |
|
|
|
-|----------------|-------------------------|------------|---------------|--------------|--------------------------------------------------------------------------------|--------------------------------------------------|---------------------------------------|--------------------------------------------|-------------------------------------------------------------------|---------------------------------|----------------|---------------|
|
|
|
-| | **Number<br>of States** | **Static** | **IsDefault** | **Hotkeys** | **Select<br>Command<br>`Space`** | **Accept<br>Command<br>`Enter`** | **Hotkey<br>Command** | **CanFocus<br>Click** | **CanFocus<br>DblCLick** | **!CanFocus<br>Click** | **RightClick** | **GrabMouse** |
|
|
|
-| **View** | 1 | Yes | No | 1 | | OnAccept | Focus | SetFocus | | | | No |
|
|
|
-| **Label** | 1 | Yes | No | 1 | | OnAccept | FocusNext | SetFocus | | FocusNext | | No |
|
|
|
-| **Button** | 1 | No | Yes | 1 | Focus<br>OnAccept | Focus<br>OnAccept | Focus<br>OnAccept | SetFocus<br>OnAccept | | OnAccept | | No |
|
|
|
-| **Checkbox** | 3 | No | No | 1 | AdvanceCheckState<br>OnSelect | OnAccept | AdvanceCheckState<br>OnSelect | AdvanceCheckState<br>OnSelect | | AdvanceCheckState<br>OnAccept | | No |
|
|
|
-| **RadioGroup** | > 1 | No | No | 2+ | If cursor not selected,<br>select. Else, Advance <br>selected item<br>OnSelect | Set SelectedItem<br>OnSelect<br>OnAccept | Focus<br>Set SelectedItem<br>OnSelect | Set Cursor<br>Set SelectedItem<br>OnSelect | SetFocus<br>SetCursor<br>Set SelectedItem<br>OnSelect<br>OnAccept | AdvanceSelectedItem<br>OnSelect | | No |
|
|
|
-| **Slider** | > 1 | No | No | 1 | SetFocusedOption<br>OnOptionsChanged | SetFocusedOption<br>OnOptionsChanged<br>OnAccept | Focus | SetFocus<br>SetFocusedOption | | SetFocus<br>SetFocusedOption | | Yes |
|
|
|
-| **ListView** | > 1 | No | No | 1 | MarkUnMarkRow | OpenSelectedItem<br>OnAccept | OnAccept | SetMark<br>OnSelectedChanged | OpenSelectedItem<br>OnAccept | | | No |
|
|
|
-
|
|
|
-## `View` - base class
|
|
|
-
|
|
|
-### `!HasFocus`
|
|
|
-
|
|
|
-* `Enter` - n/a because no focus
|
|
|
-* `Space` - n/a because no focus
|
|
|
-* `Hotkey` - `Command.Hotkey` which does `OnHotkey/Hotkey`
|
|
|
-* `Click` - If `CanFocus`, sets focus, then invoke `Command.Hotkey`. If `!CanFocus` n/a.
|
|
|
-
|
|
|
-### `HasFocus`
|
|
|
-
|
|
|
-* `Enter` - `Command.Accept` which does `OnAccept/Accept`
|
|
|
-* `Space` - `Command.Select` which does `OnSelect/Select`
|
|
|
-* `Hotkey` - `Command.Hotkey` which does `OnHotkey/Hotkey`
|
|
|
-* `Click` - `Command.Hotkey`.
|
|
|
-
|
|
|
-## `Label` - Purpose is to be a "label" for another View.
|
|
|
-
|
|
|
-Said "label" can contain a Hotkey that will be forward to that other View.
|
|
|
-
|
|
|
-(Side note, with the `Border` adornment, and the decoupling of `Title` and `Text`, `Label` is not needed if the developer is OK with the Title appearing ABOVE the View... just enable `Border.Thickness.Top`. It is my goal that `Border` will support the `Title` being placed in `Border.Thick.ess.Left` at some point; which will eliminate the need for `Label` in many cases.)
|
|
|
-
|
|
|
-### `!HasFocus`
|
|
|
-
|
|
|
-99% of the time `Label` will be `!HasFocus`.
|
|
|
-
|
|
|
-* `Enter` - n/a because no focus
|
|
|
-* `Space` - n/a because no focus
|
|
|
-* `Hotkey` - `Command.Hotkey` - Invoke the `Hotkey` Command on the next enabled & visible View (note, today AdvanceFocus is called which is not quite rigtht`
|
|
|
-* `Click` - If `CanFocus`, sets focus. If `!CanFocus` Invoke the `Hotkey` Command on the next enabled & visible View (note, today AdvanceFocus is called which is not quite right).
|
|
|
-
|
|
|
-### `HasFocus`
|
|
|
-
|
|
|
-The below is debatable. An alternative is a `Label` with `CanFocus` effectively is a "meld" of the next view and `Enter`, `Space`, `HotKey`, and `Click` all just get forwarded to the next View.
|
|
|
-
|
|
|
-* `Enter` - `Command.Accept` which does `OnAccept/Accept`
|
|
|
-* `Space` - `Command.Select` which does `OnSelect/Select`
|
|
|
-* `Hotkey` - `Command.Hotkey` -
|
|
|
-* `Click` - If `CanFocus`, sets focus. If `!CanFocus` Invoke the `Hotkey` Command on the next enabled & visible View (note, today AdvanceFocus is called which is not quite right).
|
|
|
-
|
|
|
-## `Button` - A View where the user expects some action to happen when pressed.
|
|
|
-
|
|
|
-Note: `Button` has `IsDefault` which does two things:
|
|
|
-
|
|
|
-1) change how a `Button` appears (adds an indicator indicating it's the default`).
|
|
|
-2) `Window`'s `Command.Accept` handler searches the subviews for the first `Button` with `IsDefault` and invokes `Command.Accept` on that button. If no such `Button` is found, or none do `Handled=true`, the `Window.OnAccept` is invoked.
|
|
|
-
|
|
|
-The practical impact of the above is devs have a choice for how to tell if the user "accepts" a superview:
|
|
|
-
|
|
|
-a) Set `IsDefault` on one button, and subscribe to `Accept` on that button.
|
|
|
-b) Subscribe to `Accept` on the superview.
|
|
|
-
|
|
|
-The `Dialogs` Scenario is illustrative:
|
|
|
-
|
|
|
-For the `app` (Window):
|
|
|
-
|
|
|
-```cs
|
|
|
- showDialogButton.Accepting += (s, e) =>
|
|
|
- {
|
|
|
- Dialog dlg = CreateDemoDialog (
|
|
|
- widthEdit,
|
|
|
- heightEdit,
|
|
|
- titleEdit,
|
|
|
- numButtonsEdit,
|
|
|
- glyphsNotWords,
|
|
|
- alignmentGroup,
|
|
|
- buttonPressedLabel
|
|
|
- );
|
|
|
- Application.Run (dlg);
|
|
|
- dlg.Dispose ();
|
|
|
- };
|
|
|
-```
|
|
|
-
|
|
|
-Changing this to
|
|
|
-
|
|
|
-```cs
|
|
|
- app.Accepting += (s, e) =>
|
|
|
- {
|
|
|
- Dialog dlg = CreateDemoDialog (
|
|
|
- widthEdit,
|
|
|
- heightEdit,
|
|
|
- titleEdit,
|
|
|
- numButtonsEdit,
|
|
|
- glyphsNotWords,
|
|
|
- alignmentGroup,
|
|
|
- buttonPressedLabel
|
|
|
- );
|
|
|
- Application.Run (dlg);
|
|
|
- dlg.Dispose ();
|
|
|
- };
|
|
|
-```
|
|
|
-
|
|
|
-... should do exactly the same thing. However, there's a bug in `v2_develop` where the `Command.Accept` handler for `Window` ignores the return value of `defaultBtn.InvokeCommand (Command.Accept)`. Fixing this bug makes this work as I would expect.
|
|
|
-
|
|
|
-However, for `Dialog` the `Dialogs` scenario illustrates why a dev might actually want multiple buttons and to have one be `Default`:
|
|
|
-
|
|
|
-```cs
|
|
|
- button.Accepting += (s, e) =>
|
|
|
- {
|
|
|
- clicked = buttonId;
|
|
|
- Application.RequestStop ();
|
|
|
- };
|
|
|
-
|
|
|
-...
|
|
|
-
|
|
|
-dialog.Closed += (s, e) => { buttonPressedLabel.Text = $"{clicked}"; };
|
|
|
-```
|
|
|
-
|
|
|
-With this, the `Accept` handler sets `clicked` so the dev can tell what button the user clicked to end the Dialog.
|
|
|
-
|
|
|
-Removing the code in `Window`'s `Command.Accept` handler that special-cases `IsDefault` changes nothing. Any subview that `Handles = true` `Accept` will, BY DEFINITION be the "default" `Enter` handler.
|
|
|
-
|
|
|
-If `Enter` is pressed and no Subview handles `Accept` with `Handled = true`, the Superview (e..g `Dialog` or `Window`) will get `Command.Accept`. Thus developers need to do nothing to make it so `Enter` "accepts".
|
|
|
-
|
|
|
-ANOTHER BUG in v2_develop: This code in `View.Mouse` is incorect as it ignores if an `MouseClick` handler sets `Handled = true`.
|
|
|
-
|
|
|
-```cs
|
|
|
- // If mouse is still in bounds, generate a click
|
|
|
- if (!WantContinuousButtonPressed && Viewport.Contains (mouseEvent.Position))
|
|
|
- {
|
|
|
- return OnMouseClick (new (MouseEvent));
|
|
|
- }
|
|
|
-
|
|
|
- return mouseEvent.Handled = true;
|
|
|
-```
|
|
|
-
|
|
|
-This is more correct:
|
|
|
-
|
|
|
-```cs
|
|
|
- // If mouse is still in bounds, generate a click
|
|
|
- if (!WantContinuousButtonPressed && Viewport.Contains (mouseEvent.Position))
|
|
|
- {
|
|
|
- var meea = new MouseEventEventArgs (mouseEvent);
|
|
|
-
|
|
|
- // We can ignore the return value of OnMouseClick; if the click is handled
|
|
|
- // meea.Handled and meea.MouseEvent.Handled will be true
|
|
|
- OnMouseClick (meea);
|
|
|
- }
|
|
|
-```
|
|
|
-
|
|
|
-AND, `Dialogs` should set `e.Handled = true` in the `Accept` handler.
|
|
|
-
|
|
|
-Finally, `Button`'s (or any View that wants to be an explicit-"IsDefault" view) `HotKey` handler needs to do this:
|
|
|
-
|
|
|
-```cs
|
|
|
- AddCommand (
|
|
|
- Command.HotKey,
|
|
|
- () =>
|
|
|
- {
|
|
|
- bool cachedIsDefault = IsDefault; // Supports "Swap Default" in Buttons scenario
|
|
|
-
|
|
|
- bool? handled = OnAccept ();
|
|
|
-
|
|
|
- if (handled == true)
|
|
|
- {
|
|
|
- return true;
|
|
|
- }
|
|
|
-
|
|
|
- SetFocus ();
|
|
|
-
|
|
|
- // TODO: If `IsDefault` were a property on `View` *any* View could work this way. That's theoretical as
|
|
|
- // TODO: no use-case has been identified for any View other than Button to act like this.
|
|
|
- // If Accept was not handled...
|
|
|
- if (cachedIsDefault && SuperView is { })
|
|
|
- {
|
|
|
- return SuperView.InvokeCommand (Command.Accept);
|
|
|
- }
|
|
|
-
|
|
|
- return false;
|
|
|
- });
|
|
|
-```
|
|
|
-
|
|
|
-With these changes, both mouse and keyboard "default accept" handling work without `View`, `Window` or anyone else knowing about `Button.IsDefault`.
|
|
|
-
|
|
|
-## `CheckBox` - An interesting use case because it has potentially 3 states...
|
|
|
-
|
|
|
-Here's what it SHOULD do:
|
|
|
-
|
|
|
-### `!HasFocus`
|
|
|
-
|
|
|
-* `Enter` - n/a because no focus
|
|
|
-* `Space` - n/a because no focus
|
|
|
-* `Hotkey` - `Command.Hotkey` -> does NOT set focus, but advances state
|
|
|
-* `Click` - If `CanFocus`, sets focus AND advances state
|
|
|
-* `Double Click` - Advances state and then raises `Accept` (this is what Office does; it's pretty nice. Windows does nothing).
|
|
|
-
|
|
|
-### `HasFocus`
|
|
|
-
|
|
|
-* `Enter` - `Command.Accept` -> Raises `Accept`
|
|
|
-* `Space` - `Command.Select` -> Advances state
|
|
|
-* `Hotkey` - `Command.Hotkey` -> Advances state
|
|
|
-* `Click` - Advances state
|
|
|
-* `Double Click` - Advances state and then raises `Accept` (this is what Office does; it's pretty nice. Windows does nothing).
|
|
|
-
|
|
|
-An interesting tid-bit about the above is for `Checkbox` the right thing to do is for Hotkey to NOT set focus. Why? If the user is in a TextField and wants to change a setting via a CheckBox, they should be able to use the hotkey and NOT have to then re-focus back on the TextView. The `TextView` in `Text Input Controls` Scenario is a good example of this.
|
|
|
-
|
|
|
-## `RadioGroup` - Has > 1 state AND multiple hotkeys
|
|
|
-
|
|
|
-In v2_develop it's all kinds of confused. Here's what it SHOULD do:
|
|
|
-
|
|
|
-### `!HasFocus`
|
|
|
-
|
|
|
-* `Enter` - n/a because no focus
|
|
|
-* `Space` - n/a because no focus
|
|
|
-* `Title.Hotkey` - `Command.Hotkey` -> Set focus. Do NOT advance state.
|
|
|
-* `RadioItem.Hotkey` - `Command.Select` -> DO NOT set Focus. Advance State to RadioItem with hotkey.
|
|
|
-* `Click` - `Command.Hotkey` -> If `CanFocus`, sets focus and advances state to clicked RadioItem.
|
|
|
-* `Double Click` - Advances state to clicked RadioItem and then raises `Accept` (this is what Office does; it's pretty nice. Windows does nothing).
|
|
|
-
|
|
|
-### `HasFocus`
|
|
|
-
|
|
|
-* `Enter` - `Command.Accept` -> Advances state to selected RadioItem and Raises `Accept`
|
|
|
-* `Space` - `Command.Select` -> Advances state
|
|
|
-* `Title.Hotkey` - `Command.Hotkey` -> Advance state
|
|
|
-* `RadioItem.Hotkey` - `Command.Select` -> Advance State to RadioItem with hotkey.
|
|
|
-* `Click` - advances state to clicked RadioItem.
|
|
|
-* `Double Click` - Advances state to clicked RadioItem and then raises `Accept` (this is what Office does; it's pretty nice. Windows does nothing).
|
|
|
-
|
|
|
-Like `Checkbox` the right thing to do is for Hotkey to NOT set focus. Why? If the user is in a TextField and wants to change a setting via a RadioGroup, they should be able to use the hotkey and NOT have to then re-focus back on the TextView. The `TextView` in `Text Input Controls` Scenario is a good example of this.
|
|
|
-
|
|
|
-## `Slider` - Should operate just like RadioGroup
|
|
|
-
|
|
|
-- BUGBUG: Slider should support Hotkey w/in Legends
|
|
|
-
|
|
|
-## `NumericUpDown`
|
|
|
-
|
|
|
-## `ListView`
|
|
|
-
|
|
|
-### `!HasFocus`
|
|
|
-
|
|
|
-* `Enter` - n/a because no focus
|
|
|
-* `Space` - n/a because no focus
|
|
|
-* `Title.Hotkey` - `Command.Hotkey` -> Set focus. Do NOT advance state.
|
|
|
-* `Click` - `Command.Select` -> If `CanFocus`, sets focus and advances state to clicked ListItem.
|
|
|
-* `Double Click` - Sets focus and advances state to clicked ListItem and then raises `Accept`.
|
|
|
-
|
|
|
-### `HasFocus`
|
|
|
-
|
|
|
-* `Enter` - `Command.Accept` -> Raises `Accept`
|
|
|
-* `Space` - `Command.Select` -> Advances state
|
|
|
-* `Title.Hotkey` - `Command.Hotkey` -> does nothing
|
|
|
-* `RadioItem.Hotkey` - `Command.Select` -> Advance State to RadioItem with hotkey.
|
|
|
-* `Click` - `Command.Select` -> If `CanFocus`, sets focus and advances state to clicked ListItem.
|
|
|
-* `Double Click` - Sets focus and advances state to clicked ListItem and then raises `Accept`.
|
|
|
-
|
|
|
-What about `ListView.MultiSelect` and `ListViews.AllowsMarking`?
|
Tig