SizerBase - ContentSizer + PropertySizer Controls w/ GridSplitter

[michael-hawker]

SizerBase class for ContentSizer + PropertySizer + GridSplitter

Tracking Issue: #101

Problem Statement

We have various types of experience which need 'gripper bars' in order to provide a user with the ability to resize/drag an area of UI around in an application. These all have similar visual and behavior cues, but may require different logic to manipulate the underlying UI structure.

Inspiration

I had built my original ContentSizer component for XAML Studio to mimic the behavior of the VS Code Activity Bar and made a comment on this issue here in the toolkit repo about issues with GridSplitter.

Proposed Solution

We'll create a SizerBase class which represents the Visual Template of one of these components and contains an abstraction around the implementation needed for the logic to manipulate other UI components. Our three other components can then be built on top of this infrastructure more easily while the base class can handle visuals, accessibility, etc...

    public abstract partial class SizerBase : Control
    {
        /// <summary>
        /// Called when the control has been initialized.
        /// </summary>
        /// <param name="e">Loaded event args.</param>
        protected virtual void OnLoaded(RoutedEventArgs e)
        {
        }

        /// <summary>
        /// Called when the <see cref="SizerBase"/> control starts to be dragged by the user.
        /// Implementor should record current state of manipulated target at this point in time.
        /// They will receive the cumulative change in <see cref="OnDragHorizontal(double)"/> or
        /// <see cref="OnDragVertical(double)"/> based on the <see cref="Orientation"/> property.
        /// </summary>
        /// <remarks>
        /// This method is also called at the start of a keyboard interaction. Keyboard strokes use the same pattern to emulate a mouse movement for a single change. The appropriate
        /// <see cref="OnDragHorizontal(double)"/> or <see cref="OnDragVertical(double)"/>
        /// method will also be called after when the keyboard is used.
        /// </remarks>
        protected abstract void OnDragStarting();

        /// <summary>
        /// Method to process the requested horizontal resize.
        /// </summary>
        /// <param name="horizontalChange">The <see cref="ManipulationDeltaRoutedEventArgs.Cumulative"/> horizontal change amount from the start in device-independent pixels DIP.</param>
        /// <returns><see cref="bool"/> indicates if a change was made</returns>
        /// <remarks>
        /// The value provided here is the cumulative change from the beginning of the
        /// manipulation. This method will be used regardless of input device. It will already
        /// be adjusted for RightToLeft <see cref="FlowDirection"/> of the containing
        /// layout/settings. It will also already account for any settings such as
        /// <see cref="DragIncrement"/> or <see cref="KeyboardIncrement"/>. The implementor
        /// just needs to use the provided value to manipulate their baseline stored
        /// in <see cref="OnDragStarting"/> to provide the desired change.
        /// </remarks>
        protected abstract bool OnDragHorizontal(double horizontalChange);

        /// <summary>
        /// Method to process the requested vertical resize.
        /// </summary>
        /// <param name="verticalChange">The <see cref="ManipulationDeltaRoutedEventArgs.Cumulative"/> vertical change amount from the start in device-independent pixels DIP.</param>
        /// <returns><see cref="bool"/> indicates if a change was made</returns>
        /// <remarks>
        /// The value provided here is the cumulative change from the beginning of the
        /// manipulation. This method will be used regardless of input device. It will also
        /// already account for any settings such as <see cref="DragIncrement"/> or
        /// <see cref="KeyboardIncrement"/>. The implementor just needs
        /// to use the provided value to manipulate their baseline stored
        /// in <see cref="OnDragStarting"/> to provide the desired change.
        /// </remarks>
        protected abstract bool OnDragVertical(double verticalChange);

It is then straight-forward to inherit from this class and implement only the logic needed by the manipulator, for instance:

• GridSplitter knows how to manipulate a Grid's rows/columns
• ContentSizer knows how to manipulate the Width/Height of any FrameworkElement
• PropertySizer knows how to directly manipulate any bound double value

Open Questions

• Are these good names for this base/controls?

API Reference Docs

• GridSplitter WPF

References

• Toolkit GridSplitter Refactor Redesign of GridSplitter API WindowsCommunityToolkit#2976

[michael-hawker]

This was shipped in the 8.0 Release, please update to use that version of the component. Any further issues/requests should start in the main repository.