Click here for Japanese page (日本語ページはこちら)
nsAttachedProperties (NishySoftware.Wpf.AttachedProperties) is a library of attached properties that can be used to extend the functionality and change the behavior of existing WPF controls.
This library is under the Apache-2.0 License.
Install NuGet package(s).
PM> Install-Package NishySoftware.Wpf.AttachedProperties- NishySoftware.Wpf.AttachedProperties - nsAttachedProperties library.
The change history of this library is here.
The attached properties provided by this library can be used to extend the functionality and change the behavior of existing WPF controls.
To specify a namespace in xaml, use xmlns:nsAttachedProps="http://schemas.nishy-software.com/xaml/attached-properties" or xmlns:nsXaml="http://schemas.nishy-software.com/xaml".
<Window
xmlns:nsAttachedProps="http://schemas.nishy-software.com/xaml/attached-properties"
...
>
...
</Window>Namespace: NishySoftware.Wpf.AttachedProperties
Assembly: nsAttachedProperties.Wpf.dll
nuget packageId: NishySoftware.Wpf.AttachedProperties
The attached properties provided by ScrollViewerProperties are attached properties that can be used to extend the functionality and change the behavior of ScrollViewer control.
- MouseWheelHandlingMode
Specify the handling mode of mouse wheel events of ScrollViewer for scrollable contents.
This enumeration value is used in the ScrollViewerProperties.MouseWheelHandlingMode attached property.
public enum MouseWheelHandlingMode
{
Inherit,
Normal,
OnlyVisible,
OnlyScrollable,
}| Value | Behavior |
|---|---|
| Inherit | Depends on the inheritance value of the parent. This value is default. |
| Normal | Always handle the mouse wheel event. Original behavior of ScrollViewer |
| OnlyVisible | Handle the mouse wheel event only when the vertical scroll bar is visible. |
| OnlyScrollable | Handle mouse wheel events only when the vertical scroll bar can scroll in the direction of the mouse wheel rotation. |
This attached property can be used to improve the scrolling behavior of a nested ScrollViewer by rotating the mouse wheel.
As a concrete behavior, this attached property can be used to prevent the inner ScrollViewer from always handling the mouse wheel events when the ScrollViewer is nested.
The behavior for handling mouse wheel events is specified by the MouseWheelHandlingMode enumeration value.
This attached property is mainly used for controls that use ScrollViewer to display content, such as DataGrid/ListView/ListBox. However, it can also be set for Window, Grid, GroupBox, etc.
If this attached property is set to a FrameworkEelement other than ScrollViewer, its value will be inherited by the child ScrollViewers of that FrameworkEelement. The ScrollViewer whose value is inherited either does not have the MouseWheelHandlingMode attached property or has the MouseWheelHandlingMode attached property set to Inherit.
If this attached property is set to a ScrollViewer, the value of that ScrollViewer will not be inherited by the child ScrollViewer.
However, in order not to affect the performance of WPF, the timing of searching for the ScrollViewer of a child element is limited to "when the value of the attached property of that control is changed" and "when the Loaded event of that control is fired".
Therefore, the value of the attached property set in the parent control may not be reflected in the ScrollViewer of some child elements.
For example, in TabControl's TabItem, etc., the controls in its content are instantiated when the TabItem becomes active. The Loaded event that occurs when the content is instantiated is not propagated to the TabControl or TabItem. Therefore, the value of the attached property set in the TabControl or TabItem will not be reflected in the content in the TabItem. In this case, it is necessary to set the attached property to the most parent control in the content of the TabItem.
If the value of the attached property is sometimes not reflected in the ScrollViewer of the child element, this may be the situation. In this case, you can set the attached property for the control that is going to be instantiated later and it will be reflected.
Example for nsAttachedProps:ScrollViewerProperties.MouseWheelHandlingMode
<Window
...
xmlns:nsAttachedProps="http://schemas.nishy-software.com/xaml/attached-properties">
<ScrollViewer Grid.Row="1"
Width="300"
Height="300">
...
<DataGrid Grid.Row="1"
ItemsSource="{Binding Source={StaticResource SmallDataItemsView1}}"
nsAttachedProps:ScrollViewerProperties.MouseWheelHandlingMode="OnlyScrollable"/>
</DataGrid>
...Namespace: NishySoftware.Wpf.AttachedProperties
Assembly: nsAttachedProperties.Wpf.dll
nuget packageId: NishySoftware.Wpf.AttachedProperties
The attached properties provided by TextBoxProperties are attached properties that can be used to extend the functionality and change the behavior of TextBox control.
- ReturnBehavior
Specify the behavior of the TextBox control when the Enter key is pressed.
This enumeration value is used in the TextBoxProperties.ReturnBehavior attached property.
public enum ReturnBehaviorMode
{
None = 0,
MoveFocus = 1,
UpdateSource = 2,
SelectAll = 4,
// combination
UpdateSourceAndMoveFocus = 3,
UpdateSourceAndSelectAll = 6
}| Name | Value | Behavior when inputing Enter key |
|---|---|---|
| None | 0 | The behavior is not extended. Original behavior of TextBox. This value is default. |
| MoveFocus | 1 | Move the focus to the next element if the Enter key is pressed alone. Move the focus to the previous element if the Enter and Shift keys are pressed at the same time. |
| UpdateSource | 2 | Update binding source if TextBox.Text property is binding. |
| SelectAll | 4 | Select all the text. |
| UpdateSourceAndMoveFocus | 3 | ReturnBehaviorMode.MoveFocus behavior after ReturnBehaviorMode.UpdateSource behavior. |
| UpdateSourceAndSelectAll | 6 | ReturnBehaviorMode.SelectAll behavior after ReturnBehaviorMode.UpdateSource behavior. |
This attached property can be used to improve the behavior of the TextBox control and the editable ComboBox control when the Enter key is pressed.
The behavior when the Enter key is pressed is specified using the ReturnBehaviorMode enumeration value.
There are many values defined in the ReturnBehaviorMode enumeration, but the most commonly used are MoveFocus, UpdateSource, and UpdateSourceAndSelectAll.
In ComboBox with ComboBox.IsEditable=true , the default value of UpdateSourceTrigger when data-binding to ComboBox.Text is PropertyChanged,
but this attached property is most effective when UpdateSourceTrigger is set to LostFocus.
If this attached property is set to a FrameworkEelement other than the TextBox control and the ComboBox control, it will be ignored.
If this attached property is set to a TextBox control that has AcceptsReturn property set to true, it will be ignored.
Example for nsAttachedProps:TextBoxProperties.ReturnBehavior
<Window
...
xmlns:nsAttachedProps="http://schemas.nishy-software.com/xaml/attached-properties">
<Grid>
...
<TextBox Grid.Row="0"
nsAttachedProps:TextBoxProperties.ReturnBehavior="MoveFocus"
Text="{Binding EditBoxValue0}"/>
<TextBox Grid.Row="1"
nsAttachedProps:TextBoxProperties.ReturnBehavior="UpdateSource"
Text="{Binding EditBoxValue1}"/>
<TextBox Grid.Row="2"
nsAttachedProps:TextBoxProperties.ReturnBehavior="UpdateSourceAndSelectAll"
Text="{Binding EditBoxValue2}"/>
...
<ComboBox Grid.Row="5"
nsAttachedProps:TextBoxProperties.ReturnBehavior="MoveFocus"
IsEditable="True"
Text="{Binding EditBoxValue5,UpdateSourceTrigger=LostFocus}"/>
<ComboBox Grid.Row="6"
nsAttachedProps:TextBoxProperties.ReturnBehavior="UpdateSource"
IsEditable="True"
Text="{Binding EditBoxValue6,UpdateSourceTrigger=LostFocus}"/>
<ComboBox Grid.Row="7"
nsAttachedProps:TextBoxProperties.ReturnBehavior="UpdateSourceAndSelectAll"
IsEditable="True"
Text="{Binding EditBoxValue7,UpdateSourceTrigger=LostFocus}"/>
...