Skip to content

Commit ff71c59

Browse files
jevonsflashjevonsflash
committed
doc: add English docs
1 parent eabb90a commit ff71c59

25 files changed

Lines changed: 2367 additions & 0 deletions

‎docs/colors-en.md‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
# Color System
2+
3+
## Description
4+
5+
The colors in V-Control are imported from the Material Design system and follow the semantic variable naming conventions of Material Design. You can use these colors to create your own themes.
6+
7+
The resource dictionary path for colors is:
8+
```
9+
.\src\Resources\Styles\VControlColors.xaml
10+
```
11+
12+
## Standard Colors
13+
14+
There are 21 standard colors divided into six groups: Primary, Secondary, Tertiary, Background, Surface, and Outline.
15+
16+
![alt text](assets/image-19.png)
17+
18+
### Semantic Definitions of Standard Colors:
19+
20+
* **Surface** – Used for large, low-emphasis background areas on screens.
21+
* **Primary, Secondary, Tertiary** – Used as accent colors to emphasize or de-emphasize foreground elements.
22+
* **Container** – Used as fill colors for foreground elements like buttons. They should not be applied to text or icons.
23+
* **On** – Roles prefixed with "On" indicate colors used for text or icons placed on top of their paired parent colors. For example, "OnPrimary" is used for text and icons that appear over the primary fill color.
24+
* **Variant** – Roles ending in "Variant" provide a lower-emphasis alternative to their non-variant counterparts. For instance, "OutlineVariant" is a less prominent version of the outline color.
25+
26+
The standard color resources are as follows. You can use these as a foundation to create your own theme.
27+
28+
```xml
29+
<Color x:Key="Primary">#FF7415</Color>
30+
<Color x:Key="OnPrimary">#FFFFFF</Color>
31+
<Color x:Key="PrimaryContainer">#FEF4EA</Color>
32+
<Color x:Key="OnPrimaryContainer">#ED6103</Color>
33+
34+
<Color x:Key="Secondary">#f38e47</Color>
35+
<Color x:Key="OnSecondary">#FFFFFF</Color>
36+
<Color x:Key="SecondaryContainer">#FEF4EA</Color>
37+
<Color x:Key="OnSecondaryContainer">#EB6B13</Color>
38+
39+
<Color x:Key="Tertiary">#FDDB3A</Color>
40+
<Color x:Key="OnTertiary">#2C3639</Color>
41+
<Color x:Key="TertiaryContainer">#786301</Color>
42+
<Color x:Key="OnTertiaryContainer">#fef1b0</Color>
43+
44+
<Color x:Key="Surface">#FFFFFF</Color>
45+
<Color x:Key="OnSurface">#3F4E4F</Color>
46+
<Color x:Key="SurfaceVariant">#E7E0EC</Color>
47+
<Color x:Key="OnSurfaceVariant">#49454E</Color>
48+
49+
<Color x:Key="Background">#F5F5F5</Color>
50+
<Color x:Key="OnBackground">#1C1B1F</Color>
51+
52+
<Color x:Key="Outline">#E1E1E1</Color>
53+
<Color x:Key="OutlineVariant">#C4C7C5</Color>
54+
<Color x:Key="Shadow">#000000</Color>
55+
```
56+
57+
## Auxiliary Colors
58+
59+
Auxiliary colors are used for different scenarios apart from the primary colors (e.g., error colors for dangerous actions).
60+
61+
![alt text](assets/image-20.png)
62+
63+
The auxiliary color resources are as follows. You can use these as a foundation to create your own theme.
64+
65+
```xml
66+
<Color x:Key="Error">#B3261E</Color>
67+
<Color x:Key="ErrorContainer">#F9DEDC</Color>
68+
69+
<Color x:Key="Success">#01ae54</Color>
70+
<Color x:Key="SuccessContainer">#a8eac0</Color>
71+
72+
<Color x:Key="Warning">#F7B548</Color>
73+
<Color x:Key="WarningContainer">#FFE5B9</Color>
74+
75+
<Color x:Key="DisabledText">#ba919191</Color>
76+
<Color x:Key="PlaceHolderText">#E0E0E0</Color>
77+
<Color x:Key="DisabledBackground">#80919191</Color>
78+
```
79+
80+
## Neutral Colors
81+
82+
Neutral colors are used for text, backgrounds, and border colors. Applying different neutral colors helps establish a visual hierarchy.
83+
84+
![alt text](assets/image-21.png)
85+
86+
The neutral color resources are as follows. You can use these as a foundation to create your own theme.
87+
```xml
88+
<Color x:Key="White">White</Color>
89+
<Color x:Key="Black">Black</Color>
90+
91+
<Color x:Key="Gray50">#F8F8F8</Color>
92+
<Color x:Key="Gray60">#F7F7F7</Color>
93+
<Color x:Key="Gray100">#F5F5F5</Color>
94+
<Color x:Key="Gray120">#F3F3F3</Color>
95+
<Color x:Key="Gray150">#F1F1F1</Color>
96+
<Color x:Key="Gray170">#F0F0F0</Color>
97+
<Color x:Key="Gray190">#E1E1E1</Color>
98+
<Color x:Key="Gray200">#E0E0E0</Color>
99+
<Color x:Key="Gray230">#B7B7B7</Color>
100+
<Color x:Key="Gray240">#B5B5B5</Color>
101+
<Color x:Key="Gray250">#B3B3B3</Color>
102+
<Color x:Key="Gray270">#AEAEAE</Color>
103+
<Color x:Key="Gray300">#ACACAC</Color>
104+
<Color x:Key="Gray360">#A6A6A6</Color>
105+
<Color x:Key="Gray380">#919191</Color>
106+
<Color x:Key="Gray400">#848381</Color>
107+
<Color x:Key="Gray500">#6E6E6E</Color>
108+
<Color x:Key="Gray550">#666666</Color>
109+
<Color x:Key="Gray600">#404040</Color>
110+
<Color x:Key="Gray900">#212121</Color>
111+
<Color x:Key="Gray950">#141414</Color>
112+
```
113+

‎docs/global-styles-en.md‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
# Built-in Styles
2+
3+
## Description
4+
5+
The functionality of the V-Control components does not rely on global styles. Global styles only provide some basic and commonly used styles. Styles without a specified Key attribute will override your global styles.
6+
7+
The resource dictionary path for global styles is:
8+
```
9+
.\src\Resources\Styles\VControlGlobalStyles.xaml
10+
```
11+
12+
13+
## Default Button Style
14+
15+
![alt text](assets/image.png)
16+
17+
The default button style provides a themed background color and text color.
18+
19+
It also provides the following button style resources:
20+
21+
* PrimaryButton - Basic button
22+
* TextButton - Text button
23+
* OutlinedButton - Outlined button
24+
* LightButton - Light button (light background color)
25+
26+
The default button modifies the style when in a disabled state.
27+
28+
## Default Border Style
29+
30+
![alt text](assets/image-1.png)
31+
32+
The default Border style provides a background color and border color.
33+
34+
## Default CheckBox Style
35+
36+
![alt text](assets/image-2.png)
37+
38+
The default CheckBox style provides a foreground color based on the primary color.
39+
40+
## Default RadioButton Style
41+
42+
![alt text](assets/image-10.png)
43+
44+
The default RadioButton style provides a foreground color based on the primary color.
45+
46+
## Default RadioButton Style
47+
48+
![alt text](assets/image-11.png)
49+
50+
The default RadioButton style provides a foreground color based on the primary color.
51+
52+
## Default Picker Style
53+
54+
![alt text](assets/image-3.png)
55+
56+
The default Picker style makes some style modifications to the native component.
57+
58+
## Default DatePicker Style
59+
60+
![alt text](assets/image-5.png)
61+
62+
The default DatePicker style makes some style modifications to the native component.
63+
64+
## Default TimePicker Style
65+
66+
![alt text](assets/image-4.png)
67+
68+
The default TimePicker style makes some style modifications to the native component.
69+
70+
## Default Editor Style
71+
72+
![alt text](assets/image-6.png)
73+
74+
The default Editor style removes the border and background color of the native component, while adding text color and placeholder color.
75+
76+
## Default Entry Style
77+
78+
![alt text](assets/image-7.png)
79+
80+
The default Entry style removes the border and background color of the native component, while adding text color and placeholder color.
81+
82+
## Default Label Style
83+
84+
![alt text](assets/image-8.png)
85+
86+
The default Label style modifies the text color.
87+
88+
## Default ProgressBar Style
89+
90+
![alt text](assets/image-9.png)
91+
92+
The default ProgressBar style modifies the progress bar color and background color.
93+
94+
## Default RefreshView Style
95+
96+
![alt text](assets/image-13.png)
97+
98+
The default RefreshView style modifies the foreground color of the circular progress bar during refresh, based on the primary color.
99+
100+
## Default SearchBar Style
101+
102+
![alt text](assets/image-14.png)
103+
104+
The default SearchBar style modifies the text color and placeholder color.
105+
106+
## Default Slider Style
107+
108+
![alt text](assets/image-16.png)
109+
110+
The default Slider style modifies the progress bar color and background color.
111+
112+
## Default SwipeView Style
113+
114+
![alt text](assets/image-15.png)
115+
116+
The default SwipeView style modifies the text color and background color.
117+
118+
## Default Shell Style
119+
120+
![alt text](assets/image-17.png)
121+
122+
![alt text](assets/image-18.png)
123+
124+
In Shell applications, the default Shell style modifies the Tabbed icon, text color, and background color, as well as the TabBarTitle text color and background color.

‎docs/icons-en.md‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
# Icons
2+
3+
V-Control introduces three character sets from Font Awesome 6 for displaying icons.
4+
5+
The font file paths are:
6+
7+
```
8+
.\src\Resources\Fonts\Font_Awesome_6_Brands-Regular-400.otf
9+
.\src\Resources\Fonts\Font_Awesome_6_Free-Regular-400.otf
10+
.\src\Resources\Fonts\Font_Awesome_6_Free-Solid-900.otf
11+
```
12+
13+
These correspond to three aliases:
14+
15+
* `"FontAwesome-Regular"`
16+
* `"FontAwesome-Solid"`
17+
* `"FontAwesome-Brands"`
18+
19+
## Usage
20+
21+
In XAML, you can specify any control that displays text to show an icon, such as: Label, Button, Editor.
22+
23+
1. Set the `FontFamily` property to `"FontAwesome-Solid"` or another character set alias.
24+
2. Set the `Text` property to the icon name or the icon's Unicode code.
25+
26+
Both the icon name and the Unicode code can point to the same icon. The following two examples are equivalent:
27+
28+
Name
29+
30+
```xml
31+
<Label FontFamily="FontAwesome-Solid"
32+
Text="user"></Label>
33+
```
34+
35+
Unicode Code
36+
37+
```xml
38+
<Label FontFamily="FontAwesome-Solid"
39+
Text="&#xf007;"></Label>
40+
```
41+
42+
You can dynamically set icons through data binding. In the CodeBehind, you need to use the escape character format for Unicode codes.
43+
44+
```xml
45+
<DataTemplate>
46+
<Grid RowDefinitions="*,auto"
47+
Margin="20,2.5">
48+
<Label TextColor="{Binding TextColor}"
49+
FontFamily="{Binding FontFamily}"
50+
FontAttributes="Bold"
51+
FontSize="40"
52+
HorizontalOptions="Center"
53+
Text="{Binding Icon}"></Label>
54+
<Label Text="{Binding Title}"
55+
Grid.Row="1"
56+
HorizontalOptions="Center"
57+
Style="{StaticResource ItemDetailsLabel}" />
58+
</Grid>
59+
</DataTemplate>
60+
```
61+
62+
CodeBehind
63+
64+
```csharp
65+
IconItemList = new ObservableCollection<dynamic>(){
66+
new { Title= "house" , Icon="\uF015", TextColor="Red", FontFamily="FontAwesome-Solid"},
67+
new { Title= "magnifying-glass" , Icon="\uF002", TextColor="green", FontFamily="FontAwesome-Solid" },
68+
new { Title= "user" , Icon="\uF007", TextColor="orange" , FontFamily="FontAwesome-Solid"},
69+
new { Title= "facebook" , Icon="\uF09a", TextColor="blue" , FontFamily="FontAwesome-Brands"},
70+
new { Title= "check" , Icon="\uF00c", TextColor="green" , FontFamily="FontAwesome-Solid"},
71+
new { Title= "download" , Icon="\uF019", TextColor="Red", FontFamily="FontAwesome-Solid" },
72+
};
73+
```
74+
75+
The result is as follows:
76+
77+
![alt text](assets/image-24.png)
78+
79+
## How to find the encoding and character set of the icon you need?
80+
81+
Go to the official Font Awesome 6 site (https://fontawesome.com/search).
82+
83+
Enter the icon name in the search box and press Enter.
84+
85+
![alt text](assets/image-22.png)
86+
87+
Click on the icon you need, and in the pop-up window, find the Unicode code and copy it.
88+
89+
The example code below shows the character set where the icon is located.

0 commit comments

Comments
 (0)