nsAttachedProperties – README.md (1.2.0)

このページは、github.comに登録されているnsAttachedPropertiesのREADME.mdを日本語化したものです。英語版の最新版はgithub.comを参照してください。

このページの内容は、nsAttachedProperties 1.2.0 相当の内容が翻訳されています。

nsAttachedPropertiesの日本語トップページへ戻る

nsAttachedProperties (NishySoftware.Wpf.AttachedProperties)

開発のステータス (Development status)

Build Status (master) Build Status (develop)

Downloads Nuget Nuget (pre) Release

Issues Issues

License

概要 (About)

nsAttachedProperties (NishySoftware.Wpf.AttachedProperties) は、既存のWPFコントロールの機能を拡張したり、動作を変更するために使用できる添付プロパティのライブラリです。

ライセンス (License)

このライブラリーは、Apache-2.0 ライセンスで提供されいます。

変更履歴 (Change history)

このライブラリーの変更履歴はこちらです。

インストール方法 (Installation)

NuGetパッケージをインストールします。 

PM> Install-Package NishySoftware.Wpf.AttachedProperties

機能 / 使い方 (Features / How to use)

本ライブラリが提供する添付プロパティは、既存のWPFコントロールの機能拡張や動作変更に利用することができます。
xaml で名前空間を指定するときには、xmlns:nsAttachedProps="http://schemas.nishy-software.com/xaml/attached-properties" または xmlns:nsXaml="http://schemas.nishy-software.com/xaml" を使用します。

<Window
  xmlns:nsAttachedProps="http://schemas.nishy-software.com/xaml/attached-properties"
  ...
  >
...
</Window>

ScrollViewerProperties クラス (ScrollViewerProperties class)

Namespace: NishySoftware.Wpf.AttachedProperties
Assembly: nsAttachedProperties.Wpf.dll
nuget packageId: NishySoftware.Wpf.AttachedProperties

ScrollViewerPropertiesクラスが提供する添付プロパティは、ScrollViewer コントロールの機能拡張や動作変更を行うために使用することができます。

  • MouseWheelHandlingMode

MouseWheelHandlingMode enum

スクロール可能なコンテンツに対して利用される ScrollViewer のマウスホイールイベントの処理モードを指定します。

この列挙型の値は、ScrollViewerProperties.MouseWheelHandlingModeの添付プロパティで使用されます。

    public enum MouseWheelHandlingMode
    {
        Inherit,
        Normal,
        OnlyVisible,
        OnlyScrollable,
    }
値振舞
Inherit親の値を継承します。この値は既定値です。
Normalマウスホイールイベントを常に処理します。ScrollViewer の本来の動作です。
OnlyVisible垂直スクロールバーが表示されているときのみ、マウスホイールイベントを処理します。
OnlyScrollable垂直スクロールバーがマウスホイールの回転方向にスクロールできるときのみ、マウスホイールイベントを処理します。

MouseWheelHandlingMode 添付プロパティ (MouseWheelHandlingMode attached property)

この添付プロパティは、入れ子になった(ネストされた)ScrollViewerのマウスホイール回転によるスクロール動作を改善するために使用することができます。

具体的な動作として、この添付プロパティを使用すると、ScrollViewerが入れ子(ネスト)で使用されている場合に、内側のScrollViewerが常にマウスホイールイベントを処理するのを防ぐことができます。

マウスホイールイベントを処理する際の具体的な動作は、MouseWheelHandlingMode列挙値を使って指定します。

この添付プロパティは、主にDataGrid/ListView/ListBoxなどのScrollViewerを使用してコンテンツを表示するコントロールに使用します。しかしながらWindow、Grid、GroupBoxなどにも設定可能です。

この添付プロパティが ScrollViewer 以外の FrameworkEelement に設定された場合、その値はその FrameworkEelement の子の ScrollViewer に継承されます。
値が継承されるScrollViewerは、MouseWheelHandlingMode 添付プロパティを持たないか、MouseWheelHandlingMode 添付プロパティがInheritに設定されているかのどちらかのScrollViewerです。

この添付プロパティがScrollViewerに設定されている場合、そのScrollViewerの値は子のScrollViewerには継承されません。

ただし、WPFのパフォーマンスに影響を与えないために、子要素のScrollViewerを検索するタイミングは以下のように制限されています。
「そのコントロールの添付プロパティの値が変更されたとき」と「そのコントロールのLoadedイベントが発生したとき」です。

そのため、親コントロールに設定された添付プロパティの値が、一部の子要素のScrollViewerに反映されない場合があります。

例えば、TabControlのTabItemなどでは、TabItemがアクティブになった時に、そのコンテンツ内のコントロールがインスタンス化されます。
コンテンツがインスタンス化された時に発生する Loaded イベントは、TabControl や TabItem には伝搬されません。そのため、TabControlやTabItemに設定された添付プロパティの値は、TabItem内のコンテンツに反映されません。
この場合、TabItemのコンテンツ内で最も親になるコントロールにこの添付プロパティを設定する必要があります。

子要素のScrollViewerに添付プロパティの値が反映されないことがある場合、このような状況が考えられます。この場合、後からインスタンス化されるコントロールに添付プロパティを設定すれば、反映されます。

例 (Examples)

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>
...

TextBoxProperties クラス (TextBoxProperties class)

Namespace: NishySoftware.Wpf.AttachedProperties
Assembly: nsAttachedProperties.Wpf.dll
nuget packageId: NishySoftware.Wpf.AttachedProperties

TextBoxPropertiesクラスが提供する添付プロパティは、TextBoxコントロールの機能拡張や動作変更を行うために使用することができます。

  • ReturnBehavior

ReturnBehaviorMode enum

Enter キーが押されたときのTextBoxコントロールの動作を指定します。

この列挙型の値は、TextBoxProperties.ReturnBehaviorの添付プロパティで使用されます。

public enum ReturnBehaviorMode
{
    None = 0,
    MoveFocus = 1,
    UpdateSource = 2,
    SelectAll = 4,

    // combination
    UpdateSourceAndMoveFocus = 3,
    UpdateSourceAndSelectAll = 6
}
値振舞
None振舞は拡張されません。TextBoxの本来の動作です。この値は既定値です。
MoveFocusEnterキーが単独で押された場合、次の要素にフォーカスを移動します。EnterキーとShiftキーが同時に押された場合、前の要素にフォーカスを移動させます。
UpdateSourceTextBox.Textプロパティがバインディングである場合、バインディングソースを更新します。
SelectAllテキストをすべて選択します。
UpdateSourceAndMoveFocusReturnBehaviorMode.UpdateSourceの振る舞いをした後、ReturnBehaviorMode.MoveFocusの振る舞いをします。
UpdateSourceAndSelectAllReturnBehaviorMode.UpdateSourceの振る舞いをした後、ReturnBehaviorMode.SelectAllの振る舞いをします。

ReturnBehavior 添付プロパティ (ReturnBehavior attached property)

この添付プロパティは、Enter キーが押されたときのTextBoxコントロールと編集可能なComboBoxコントロールの動作を改善することができます。Enterキーが押されたときの挙動は、ReturnBehaviorMode列挙値を使って指定します。ReturnBehaviorMode列挙に定義された値は多くありますが、通常利用されのはMoveFocusとUpdateSourceとUpdateSourceAndSelectAllです。

ComboBox.IsEditable=true であるような編集可能なComboBoxにおいては、ComboBox.Text にデータバインディングしたときの UpdateSourceTriggerの既定値はPropertyChangedです。しかし、この添付プロパティはUpdateSourceTriggerがLostFocusに設定されたときにより効果があります。

この添付プロパティがTextBoxコントロールおよびComboBoxコントロール以外の FrameworkEelement に設定されている場合は、無視されます。

この添付プロパティがTextBox.AcceptsReturn プロパティが true に設定されているTextBoxコントロールに設定されている場合は、無視されます。

例 (Examples)

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}"/>
...

nsAttachedPropertiesの日本語トップページへ戻る