docs: 继续补充英文文档

OrgEleCho · Jul 5, 2024 · 08f9b25 · 08f9b25
1 parent 8384fb1
commit 08f9b25
Show file tree

Hide file tree

Showing 8 changed files with 1,217 additions and 5 deletions.
diff --git a/docs/en/custom_styles.md b/docs/en/custom_styles.md
@@ -0,0 +1,198 @@
+---
+title: Custom Styles
+layout: default
+nav_order: 1
+permalink: /en/custom-styles
+parent: Documentation
+---
+
+# Custom Styles
+{: .fs-9 }
+
+In the following sections of the document, a style similar to FluentDesign is used for demonstration purposes.
+{: .fs-6 .fw-300 }
+
+---
+
+Add the following ResourceDictionary to App.xaml to apply it globally
+
+```xml
+<ResourceDictionary xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
+                    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
+                    xmlns:ws="clr-namespace:EleCho.WpfSuite;assembly=EleCho.WpfSuite"
+                    xmlns:sys="clr-namespace:System;assembly=mscorlib">
+
+    <sys:String x:Key="WpfSuiteDesignName">SimpleDesign</sys:String>
+
+    <Color x:Key="PrimaryColor">#0067c0</Color>
+    <SolidColorBrush x:Key="PrimaryBrush" Color="{DynamicResource PrimaryColor}"/>
+
+    <LinearGradientBrush x:Key="ControlBorder" StartPoint="0,0" EndPoint="0,1">
+        <GradientStop Offset="0" Color="#18000000"/>
+        <GradientStop Offset=".9" Color="#18000000"/>
+        <GradientStop Offset="1" Color="#33000000"/>
+    </LinearGradientBrush>
+
+    <LinearGradientBrush x:Key="TextBoxBorder" StartPoint="0,0" EndPoint="0,1">
+        <GradientStop Offset="0" Color="#18000000"/>
+        <GradientStop Offset=".9" Color="#18000000"/>
+        <GradientStop Offset="1" Color="#88000000"/>
+    </LinearGradientBrush>
+
+    <LinearGradientBrush x:Key="FocusedTextBoxBorder" StartPoint="0,0" EndPoint="0,1">
+        <GradientStop Offset="0" Color="#18000000"/>
+        <GradientStop Offset=".9" Color="#18000000"/>
+        <GradientStop Offset="1" Color="{DynamicResource PrimaryColor}"/>
+    </LinearGradientBrush>
+
+    <Style TargetType="{x:Type ws:TextBox}"
+           BasedOn="{StaticResource {x:Type ws:TextBox}}">
+        <Setter Property="CornerRadius" Value="4"/>
+        <Setter Property="Padding" Value="4 6"/>
+        <Setter Property="VerticalContentAlignment" Value="Center"/>
+        <Setter Property="BorderBrush" Value="{StaticResource TextBoxBorder}"/>
+        <Setter Property="HoverBorderBrush" Value="{x:Null}"/>
+        <Setter Property="FocusedBorderBrush" Value="{StaticResource FocusedTextBoxBorder}"/>
+        <Setter Property="Background" Value="#EEFFFFFF"/>
+        <Setter Property="HoverBackground" Value="#88FFFFFF"/>
+    </Style>
+
+    <Style TargetType="{x:Type ws:PasswordBox}"
+           BasedOn="{StaticResource {x:Type ws:PasswordBox}}">
+        <Setter Property="CornerRadius" Value="4"/>
+        <Setter Property="Padding" Value="4 6"/>
+        <Setter Property="VerticalContentAlignment" Value="Center"/>
+        <Setter Property="BorderBrush" Value="{StaticResource TextBoxBorder}"/>
+        <Setter Property="HoverBorderBrush" Value="{x:Null}"/>
+        <Setter Property="FocusedBorderBrush" Value="{StaticResource FocusedTextBoxBorder}"/>
+        <Setter Property="Background" Value="#EEFFFFFF"/>
+        <Setter Property="HoverBackground" Value="#88FFFFFF"/>
+    </Style>
+
+    <Style TargetType="{x:Type ws:Button}"
+           BasedOn="{StaticResource {x:Type ws:Button}}">
+        <Setter Property="CornerRadius" Value="4"/>
+        <Setter Property="Padding" Value="8 6"/>
+        <Setter Property="BorderBrush" Value="{StaticResource ControlBorder}"/>
+        <Setter Property="HoverBorderBrush" Value="{x:Null}"/>
+        <Setter Property="PressedBorderBrush" Value="{StaticResource ControlBorder}"/>
+        <Setter Property="Background" Value="#EEFFFFFF"/>
+        <Setter Property="HoverBackground" Value="#88FFFFFF"/>
+        <Setter Property="PressedBackground" Value="#44FFFFFF"/>
+    </Style>
+
+    <Style TargetType="{x:Type ws:ToggleButton}"
+           BasedOn="{StaticResource {x:Type ws:ToggleButton}}">
+        <Setter Property="CornerRadius" Value="4"/>
+        <Setter Property="Padding" Value="8 6"/>
+        <Setter Property="BorderBrush" Value="{StaticResource ControlBorder}"/>
+        <Setter Property="HoverBorderBrush" Value="{x:Null}"/>
+        <Setter Property="PressedBorderBrush" Value="{StaticResource ControlBorder}"/>
+        <Setter Property="Background" Value="#EEFFFFFF"/>
+        <Setter Property="HoverBackground" Value="#88FFFFFF"/>
+        <Setter Property="PressedBackground" Value="#44FFFFFF"/>
+    </Style>
+
+    <Style TargetType="{x:Type ws:ComboBox}"
+           BasedOn="{StaticResource {x:Type ws:ComboBox}}">
+        <Setter Property="Padding" Value="8 6"/>
+        <Setter Property="CornerRadius" Value="4"/>
+        <Setter Property="PopupCornerRadius" Value="4"/>
+        <Setter Property="ClipToBounds" Value="True"/>
+        <Setter Property="BorderBrush" Value="{StaticResource ControlBorder}"/>
+        <Setter Property="HoverBorderBrush" Value="{StaticResource ControlBorder}"/>
+        <Setter Property="PressedBorderBrush" Value="{StaticResource ControlBorder}"/>
+        <Setter Property="Background" Value="#EEFFFFFF"/>
+        <Setter Property="HoverBackground" Value="#88FFFFFF"/>
+        <Setter Property="PressedBackground" Value="#44FFFFFF"/>
+
+        <!--Popup-->
+        <Setter Property="PopupBorderBrush" Value="{DynamicResource ControlBorder}"/>
+    </Style>
+
+    <Style TargetType="{x:Type ws:ComboBoxItem}"
+           BasedOn="{StaticResource {x:Type ws:ComboBoxItem}}">
+        <Setter Property="Margin" Value="2 1"/>
+        <Setter Property="Padding" Value="8 6"/>
+        <Setter Property="CornerRadius" Value="2"/>
+        <Setter Property="BorderThickness" Value="2 0 0 0"/>
+        <Setter Property="HoverBackground" Value="#11000000"/>
+        <Setter Property="HoverBorderBrush" Value="#11000000"/>
+
+        <Setter Property="SelectedBackground" Value="#11000000"/>
+        <Setter Property="SelectedBorderBrush" Value="{DynamicResource PrimaryBrush}"/>
+
+        <Setter Property="HoverFocusedBackground" Value="#11000000"/>
+        <Setter Property="HoverFocusedBorderBrush" Value="#11000000"/>
+
+        <Setter Property="SelectedFocusedBackground" Value="#11000000"/>
+        <Setter Property="HoverSelectedBackground" Value="#11000000"/>
+        <Setter Property="HoverSelectedBorderBrush" Value="{DynamicResource PrimaryBrush}"/>
+        <Setter Property="FocusedBorderBrush" Value="Transparent"/>
+    </Style>
+
+    <Style TargetType="{x:Type ws:CheckBox}"
+           BasedOn="{StaticResource {x:Type ws:CheckBox}}">
+        <Setter Property="CornerRadius" Value="2"/>
+    </Style>
+
+    <Style TargetType="{x:Type ws:ListBox}"
+           BasedOn="{StaticResource {x:Type ws:ListBox}}">
+        <Setter Property="CornerRadius" Value="4"/>
+    </Style>
+
+    <Style TargetType="{x:Type ws:ListBoxItem}"
+           BasedOn="{StaticResource {x:Type ws:ListBoxItem}}">
+        <Setter Property="CornerRadius" Value="4"/>
+    </Style>
+
+    <Style TargetType="{x:Type ws:TabControl}"
+           BasedOn="{StaticResource {x:Type ws:TabControl}}">
+        <Setter Property="CornerRadius" Value="4"/>
+    </Style>
+
+    <Style TargetType="{x:Type ws:TabItem}"
+           BasedOn="{StaticResource {x:Type ws:TabItem}}">
+        <Setter Property="CornerRadius" Value="2"/>
+    </Style>
+
+    <Style TargetType="{x:Type ws:ContextMenu}"
+           BasedOn="{StaticResource {x:Type ws:ContextMenu}}">
+        <Setter Property="CornerRadius" Value="4"/>
+    </Style>
+
+    <Style TargetType="{x:Type ws:Menu}"
+           BasedOn="{StaticResource {x:Type ws:Menu}}">
+        <Setter Property="CornerRadius" Value="4"/>
+    </Style>
+
+    <Style TargetType="{x:Type ws:MenuItem}"
+           BasedOn="{StaticResource {x:Type ws:MenuItem}}">
+        <Setter Property="CornerRadius" Value="2"/>
+    </Style>
+
+    <Style TargetType="{x:Type ws:ScrollBar}"
+           BasedOn="{StaticResource {x:Type ws:ScrollBar}}">
+        <Setter Property="ThumbCornerRadius" Value="3"/>
+        <Setter Property="ButtonCornerRadius" Value="3"/>
+        <Style.Triggers>
+            <Trigger Property="Orientation" Value="Vertical">
+                <Setter Property="Width" Value="12"/>
+                <Setter Property="MinWidth" Value="12"/>
+                <Setter Property="GlyphMargin" Value="1 2"/>
+            </Trigger>
+            <Trigger Property="Orientation" Value="Horizontal">
+                <Setter Property="Height" Value="12"/>
+                <Setter Property="MinHeight" Value="12"/>
+                <Setter Property="GlyphMargin" Value="1 2"/>
+            </Trigger>
+        </Style.Triggers>
+    </Style>
+
+    <Style TargetType="{x:Type ws:Tooltip}"
+           BasedOn="{StaticResource {x:Type ws:Tooltip}}">
+        <!--nothing-->
+    </Style>
+
+</ResourceDictionary>
+```
diff --git a/docs/en/enhanced_controls.md b/docs/en/enhanced_controls.md
@@ -0,0 +1,168 @@
+---
+title: Enhanced Controls
+layout: default
+nav_order: 3
+permalink: /en/enhanced-controls
+parent: Documentation
+---
+
+# Enhanced Controls
+{: .fs-9 }
+
+WPF Suite has property extensions for most controls, including state properties, corner rounding, and some controls have functionality extensions.
+{: .fs-6 .fw-300 }
+
+---
+
+## State Properties
+
+You will see in the enhanced control, some additional properties, such as `HoverBackground`, `HoverBorderBrush`, which,
+as the name suggests, indicate the value of the corresponding property in the corresponding state.
+
+If these properties are set to null, they will also fallback correctly to the set `Background` and `BorderBrush` property values.
+
+This means that you don't need to change the template to set the control to look a certain way in a certain state.
+
+Example
+{: .fw-300}
+
+```xml
+<ws:Button Content="TextButton" 
+           Padding="4"
+           BorderBrush="Transparent"
+           Background="Transparent"
+           HoverBorderBrush="#33000000"
+           HoverBackground="#EEFFFFFF"
+           PressedBackground="#c8f8ff"/>
+```
+
+Appearence, non-hovering, hovering and pressed states:
+
+<p>
+    <img src="/images/stateproperty-example-state1.png" title="状态属性示例,状态1" />
+    <img src="/images/stateproperty-example-state2.png" title="状态属性示例,状态2" />
+    <img src="/images/stateproperty-example-state3.png" title="状态属性示例,状态3" />
+</p>
+
+## Rounding Corners
+
+Button, TextBox, PasswordBox and most controls now support CornerRadius for rounding corners.
+
+Example
+{: .fw-300}
+
+```xml
+<ws:StackPanel Orientation="Horizontal"
+               Spacing="4">
+    <ws:Button Content="Button"
+               CornerRadius="10"/>
+    <ws:TextBox MinWidth="60"
+                CornerRadius="10"/>
+    <ws:PasswordBox MinWidth="60"
+                    CornerRadius="10"/>
+</ws:StackPanel>
+```
+
+![CornerRadius Example](/images/cornerradiusproperty-example.png)
+
+## Placeholder
+
+TextBox and PasswordBox can now set placeholders via the Placeholder property. The placeholder is displayed when the textbox is empty.
+
+
+Example
+{: .fw-300}
+
+```xml
+<ws:StackPanel Spacing="4">
+    <ws:TextBox Placeholder="This is a text box"/>
+    <ws:PasswordBox Placeholder="This is a password box"/>
+</ws:StackPanel>
+```
+
+![Placeholder Example](/images/placeholderproperty-example.png)
+
+## Rounding Corners Clipping
+
+By binding the Clip property to the Border's ContentClip property, you can automatically clip the portion that extends beyond the rounded corners.
+
+Example:
+{: .fw-300}
+
+```xml
+<ws:StackPanel Orientation="Horizontal" 
+               Spacing="4">
+    <Border Width="100" Height="100"
+            BorderThickness="1"
+            BorderBrush="Gray"
+            CornerRadius="15">
+        <TextBlock Text="Hello"/>
+    </Border>
+    <ws:Border Width="100" Height="100"
+               BorderThickness="1"
+               BorderBrush="Gray"
+               CornerRadius="15">
+        <TextBlock Text="Hello"
+                   Clip="{Binding RelativeSource={RelativeSource AncestorType=ws:Border},Path=ContentClip}"/>
+    </ws:Border>
+</ws:StackPanel>
+```
+
+![Rounding corners clipping example](/images/borderclip-example.png)
+
+## Smooth Scrolling
+
+If you use the ScrollViewer provided by the WPF Suite, it will have a smoother effect on content scrolling with the mouse.
+
+| Property | Type | Description |
+| --- | --- | --- |
+| ScrollWithWheelDelta | bool | Determines the scroll distance by the delta value of Wheel event. This option is used to optimize the scroll effect. The default value is true |
+| EnableScrollingAnimation | bool | Enable scrolling animation, which determines whether to use easing when scrolling with the mouse. The default value is true and this option requires ScrollWithWheelDelta to be set to true. Otherwise it doesn't work |
+| ScrollingAnimationDuration | Duration | The duration of scrolling animation, the default value is 250 ms |
+| MouseScrollDeltaFactor | double | When scrolling with the mouse, the multiplier of the scrolling Delta value. Change this value to change the scroll speed and direction. The default is 1 |
+| TouchpadScrollDeltaFactor | double | When scrolling with the touchpad, the multiplier of the scrolling Delta value. Change this value to change the scroll speed and direction. The default is 1 |
+| AlwaysHandleMouseWheelScrolling | bool | Always handle the mouse Wheel event for scrolling, ScrollViewer content is scrolled when the mouse wheel scrolls. The default is true |
+
+
+{: .tip }
+> Will AlwaysHandleMouseWheelScrolling set to false, the ScrollViewer smooth scrolling effect will not be applied in TextBox
+
+Example:
+{: .fw-300}
+
+```xml
+<ws:ScrollViewer>
+    Some content...
+</ws:ScrollViewer>
+```
+
+![ScrollViewer Example](/images/scrollviewer-example.webp)
+
+## Touch Simulation
+
+Native WPF does not support scrolling with a stylus on a ScrollViewer. However, if you want to enable scrolling with a stylus, you can use "touch device simulation". By simulating a touch device with the stylus, you can achieve scrolling functionality using the stylus.
+
+| AttachedProperty | Type | Description |
+| --- | --- | --- |
+| StylusTouchDevice.Simulate | bool | Whether to simulate the pen as a touch device, default is false |
+| StylusTouchDevice.MoveThreshold | double | Move threshold, the pen will report as touch move only after moving beyond the specified distance, default is 3 |
+| MouseTouchDevice.Simulate | bool | Whether to simulate the mouse as a touch device, default is false |
+| MouseTouchDevice.MoveThreshold | double | Move threshold, the mouse will report as touch move only after moving beyond the specified distance, default is 3 |
+
+{: .tip }
+> If you set the move threshold to 0, you will not be able to click on controls inside the ScrollViewer using the pen, because the pen always has some jitter and touch move will trigger the scrolling of the ScrollViewer, interrupting the click action.
+>
+> So, adjust the move threshold according to your desired "precision".
+> (Many programs have a larger threshold for this, such as 5px, or even 10px or more)
+
+Example:
+{: .fw-300}
+
+```xml
+<ws:ScrollViewer PanningMode="Both"
+                 ws:MouseTouchDevice.Simulate="True">
+    SomeContent...
+</ws:ScrollViewer>
+```
+
+![Touch simulation example](/images/simulatetouch-example.webp)