Skip to content

Commit 7b3b16d

Browse files
haavamoahaavamoa
committed
Merge remote-tracking branch 'origin/main' into task/hmo-wiki-sync
2 parents 63418c2 + 5ac9306 commit 7b3b16d

45 files changed

Lines changed: 3895 additions & 0 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎wiki/Accessibility.md‎

Lines changed: 741 additions & 0 deletions
Large diffs are not rendered by default.

‎wiki/Alerting.md‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
Notifying people when you have information that (might) be relevant is important. Leaving people clueless can lead be very confusing and frustrating. We provide different APIs or views that you can use to make sure people are happy.
2+
3+
# System Message
4+
A system message is a message that is displayed at the top of the screen.
5+
6+
## Inspiration
7+
[Android Developer - Toast](https://developer.android.com/guide/topics/ui/notifiers/toasts)
8+
9+
## Configuration
10+
A system message can be configured when calling the function to display the system message, with the [`ISystemMessageConfigurator`](https://github.com/DIPSAS/DIPS.Mobile.UI/blob/main/src/library/DIPS.Mobile.UI/Components/Alerting/SystemMessage/ISystemMessageConfigurator.cs) interface.
11+
12+
## Usage
13+
In the following example a system message with the text: "A system message" and a duration of 2 seconds is displayed.
14+
15+
```csharp
16+
SystemMessageService.Display(config =>
17+
{
18+
config.Text = "A system message";
19+
config.Duration = 2000;
20+
});
21+
```
22+
23+
# Dialogs
24+
Dialogs presents critical information that users needs right away. There are three different dialogs:
25+
* _Regular_. A dialog with a title, description and a single button.
26+
* _Confirmation_. A dialog with a title, description, a cancel button and a confirmation button.
27+
* _Destructive_. A dialog with a title, description, a cancel button and a destructive button.
28+
29+
## Inspiration
30+
[Material Design 2 - Dialogs](https://developer.android.com/guide/topics/ui/notifiers/toasts)
31+
32+
[iOS Developer - Alerts](https://developer.apple.com/design/human-interface-guidelines/alerts)
33+
34+
## Usage
35+
In the following example a _Regular_ dialog is presented with title, description and action title set. The function will return a `DialogAction` that either tells the system that the user cancelled the dialog or tapped the action button.
36+
37+
```csharp
38+
var result = await DialogService.ShowMessage("Title",
39+
"Description",
40+
"OK");
41+
```
42+
43+
## API
44+
Inspect the [DialogService class](https://github.com/DIPSAS/DIPS.Mobile.UI/blob/main/src/library/DIPS.Mobile.UI/Components/Alerting/Dialog/DialogService.cs) to examine how it is used.
45+
46+
47+
# AlertView
48+
Alerts can be used when you need to display information in line of your apps page to people. There are different types of styles:
49+
- Information
50+
- Warning
51+
- Success
52+
- Error
53+
54+
You need to provide a good title along with an optional description.
55+
56+
> You can optionally display a left / right button that people can tap.
57+
58+
## Usage
59+
60+
```xml
61+
62+
<dui:AlertView Title="Informing title"
63+
Description="This is a description that will provide you with information."
64+
Style="{dui:Styles Alert=Information}"
65+
LeftButtonText="{Binding ButtonText}"
66+
LeftButtonCommand="{Binding Command}"
67+
LeftButtonCommandParameter="Here's the info!" />
68+
69+
...
70+
<dui:AlertView Title="Something went wrong"
71+
Description="Something terribly wrong happened."
72+
Style="{dui:Styles Alert=Error}" />
73+
74+
75+
...
76+
<dui:AlertView Title="We warn you"
77+
Description="Dont do it...okay do it. No, dont!"
78+
Style="{dui:Styles Alert=Warning}" />
79+
80+
...
81+
<dui:AlertView Title="Yey"
82+
Description="Good job! You did it!"
83+
Style="{dui:Styles Alert=Success}" />
84+
```
85+
86+
## Title Truncation
87+
When only a title is set (no description), the maximum number of lines for the title depends on the `TitleTruncationMode` property:
88+
89+
```xml
90+
<dui:AlertView Title="A very long title that might need to be truncated"
91+
TitleTruncationMode="Aggressive" />
92+
```
93+
94+
The `TitleTruncationMode` can be set to:
95+
- **Aggressive**: Title is limited to 1 line
96+
- **Moderate**: Title can span up to 2 lines
97+
98+
## Large vs Small AlertView
99+
The AlertView has two different layout modes depending on whether a description is provided:
100+
101+
### Small AlertView (Title only)
102+
- Maximum 1-2 lines for title (based on `TitleTruncationMode`)
103+
- Icon is centered vertically with the text
104+
- Buttons appear inline with the content (If there is space, otherwise underlying)
105+
106+
### Large AlertView (Title + Description)
107+
- Maximum 4 lines total for all text content
108+
- Icon is positioned at the top-left
109+
- Buttons are always positioned below the text content
110+
111+
```xml
112+
<!-- Small AlertView -->
113+
<dui:AlertView Title="Short alert"
114+
Style="{dui:Styles Alert=Information}" />
115+
116+
<!-- Large AlertView -->
117+
<dui:AlertView Title="Detailed alert"
118+
Description="This creates a large AlertView with different layout behavior."
119+
Style="{dui:Styles Alert=Information}" />
120+
```
121+
122+
## Text Truncation and Expansion
123+
When text content exceeds the maximum line limits, the AlertView will display a "...more" indicator. Users can tap on the truncated text to view the complete content in a bottomsheet.
124+
125+
This behavior applies to:
126+
- Title text when it exceeds the `TitleTruncationMode` limits in Small AlertView
127+
- Combined title and description text when it exceeds 4 lines in Large AlertView
128+
129+
```xml
130+
<dui:AlertView Title="This is a very long title that will be truncated and show a more indicator"
131+
Description="Along with a description that makes the total content exceed the 4-line limit, triggering the truncation behavior."
132+
Style="{dui:Styles Alert=Information}" />
133+
```
134+
135+
## API
136+
Inspect the [AlertView properties class](https://github.com/DIPSAS/DIPS.Mobile.UI/blob/main/src/library/DIPS.Mobile.UI/Components/Alerting/Alert/AlertView.Properties.cs) to examine how it is used.

‎wiki/AmplitudeView.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
The `AmplitudeView` is a versatile component designed for visualizing audio input, such as capturing audio from a microphone. It provides a dynamic representation of audio amplitude in real-time, making it ideal for applications requiring audio visualization.
2+
3+
## Features
4+
5+
- **Audio Visualization**: Displays real-time amplitude data.
6+
- **Timer Integration**: Includes a built-in timer to track the duration of audio input or visualization sessions.
7+
- **Customizable**: Easily adaptable to fit various design and functional requirements.
8+
9+
## Use Cases
10+
11+
- Visualizing live audio input from a microphone.
12+
- Monitoring audio levels during recording sessions.
13+
- Enhancing user interfaces with dynamic audio feedback.
14+
15+
## Initialization of `AmplitudeView`
16+
17+
To initialize the `AmplitudeView`, you need to create a custom controller that inherits from `AmplitudeViewController`. This controller will manage the logic and data binding for the view.
18+
19+
```csharp
20+
public class Controller : AmplitudeViewController
21+
{
22+
public override float GetNextAmplitude()
23+
{
24+
return (float)new Random().NextDouble();
25+
}
26+
}
27+
```
28+
29+
```xml
30+
<dui:AmplitudeView Controller="{Binding Controller}" />
31+
```
32+
33+
The `GetNextAmplitude` function expects a normalized float value between `0` and `1`, where `0` corresponds to the minimum amplitude (minimum height) and `1` corresponds to the maximum amplitude (maximum height). It is your responsibility to ensure that the amplitude values are appropriately scaled to fit within this range.
34+
35+
## Running state
36+
37+
To control the running state of the `AmplitudeView`, toggle the `IsRunning` property in the `AmplitudeViewController`. Setting `IsRunning` to `true` starts the visualization, while setting it to `false` pauses it.
38+
39+
## Customization
40+
41+
### SampleRate
42+
43+
The `SampleRate` property determines how frequently the `AmplitudeView` fetches and updates amplitude data. A `SampleRate` of 15 retrieves 15 amplitudes a second.
44+
45+
Adjust the `SampleRate` to balance performance and visualization quality based on your application's requirements.
46+
47+
> The `SampleRate` is default set to 15.
48+
49+
### Frames per second
50+
51+
The `FramesPerSecond` property controls the rendering speed of the `AmplitudeView`. It defines how many frames are drawn per second, directly impacting the smoothness of the visualization.
52+
53+
A higher `FramesPerSecond` value results in smoother animations but may increase CPU usage. Conversely, a lower value reduces resource consumption but may make the visualization appear less fluid.
54+
55+
> The `FramesPerSecond` is default set to the device's screen refresh rate.
56+
57+
### HasTimer
58+
The `HasTimer` property determines whether the `AmplitudeView` includes a timer to track the duration of the visualization session. When set to `true`, the timer is displayed and actively tracks the elapsed time. If set to `false`, the timer is hidden.
59+
60+
This property is useful for applications where tracking the duration of audio input or visualization is necessary, such as in recording or monitoring scenarios.
61+
62+
> The `HasTimer` property is default set to `true`.
63+
64+
### Colors
65+
#### AmplitudeColor
66+
The `AmplitudeColor` property defines the color of the amplitude bars displayed in the visualization. You can set this property to match your application's theme or to provide a visually appealing representation of the audio data.
67+
68+
#### PlaceholderAmplitudeColor
69+
The `PlaceholderAmplitudeColor` property specifies the color used for placeholder amplitudes when no real amplitude data is available. This can be useful for providing a visual cue or fallback state in the absence of live audio input.
70+
71+
#### FadeColor
72+
The `FadeColor` property determines the color used for fading effects in the amplitude visualization. This is utilized to create a smooth transition effect, enhancing the overall visual appeal of the `AmplitudeView`.
73+
74+
>Ideally, this should be set to match the background color of the container in which the `AmplitudeView` resides. This ensures that the fading effects blend seamlessly with the background, making the fading boxes invisible.
75+
76+
77+

‎wiki/Animations.md‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
# Animation API
2+
We have created an attached bindable property that you can use on any `VisualElement`.
3+
4+
## Supported Animations
5+
- **FadeIn**: This animation gradually increases the opacity of a `VisualElement` from 0 to 1, creating a smooth fade-in effect. It is triggered when the element appears on the screen or when its `IsVisible` property changes from `False` to `True`.
6+
7+
## Usage
8+
To set an animation to a `VisualElement`, set the property to your `VisualElement` in XAML or C#.
9+
10+
### XAML Example:
11+
```xml
12+
<Label
13+
Text="Hello, World!">
14+
15+
<dui:Animation.FadeIn>
16+
<AnimationConfig />
17+
</dui:Animation.FadeIn>
18+
19+
</Label>
20+
```
21+
22+
### C# Example:
23+
```csharp
24+
var label = new Label { Text = "Hello, World!" };
25+
Animation.SetFadeIn(label, new AnimationConfig());
26+
```
27+
28+
> If no properties are changed on `AnimationConfig`, default values will be used that is set by .NET MAUI.
29+
30+
#### AnimationConfig
31+
`AnimationConfig` allows you to customize your animation by setting the following properties:
32+
33+
- **Duration**: Specifies the duration of the animation in milliseconds. Default is `250ms`.
34+
- **Easing**: Defines the easing function to control the animation's acceleration and deceleration. Default is `Easing.CubicInOut`.
35+
36+
### Example:
37+
#### XAML:
38+
```xml
39+
<Label
40+
Text="Hello, World!">
41+
42+
<dui:Animation.FadeIn>
43+
<AnimationConfig Duration="500"
44+
Easing="Easing.Linear" />
45+
</dui:Animation.FadeIn>
46+
47+
</Label>
48+
```
49+
50+
#### C#:
51+
```csharp
52+
var label = new Label { Text = "Hello, World!" };
53+
var config = new AnimationConfig
54+
{
55+
Duration = 500,
56+
Easing = Easing.CubicInOut
57+
};
58+
Animation.SetFadeIn(label, config);
59+
```
60+
61+
# SKLottieView animations
62+
DIPS delivers a set of animated images that you can use in your app. [The animations are located in the mobile design tokens repository.](https://github.com/DIPSAS/DIPS.Mobile.DesignTokens/tree/main/src/tokens/animations)
63+
64+
## Usage
65+
The animations are available for you to use with [SKLottieView](https://mono.github.io/SkiaSharp.Extended/api/ui-maui/sklottieview) from [SkiaSharp.Extended.UI.Maui](https://mono.github.io/SkiaSharp.Extended/api/ui-maui/):
66+
67+
XAML Shared:
68+
```xml
69+
<skia:SKLottieView
70+
Source="{dui:Animations saved}"
71+
HeightRequest="{dui:Sizes size_25}"
72+
WidthRequest="{dui:Sizes size_25}"
73+
/>
74+
```
75+
76+
## Tips and tricks
77+
### Detect animation completed
78+
To know when an animation has completed, subscribe to `SKLottieView.PropertyChanged`. Inspect the `PropertyChangedEventArgs` to know that `IsCompleted` property changed. If it changes, it will be completed when `IsCompleted` is `true`.
79+
80+
## Turn it off
81+
If you do not use our animations and are worried your app including animations that are not needed, you can turn it off by setting the following property in your `.csproj`:
82+
83+
```xml
84+
<PropertyGroup>
85+
<DIPSIncludeAnimations>False</DIPSIncludeAnimations>
86+
</PropertyGroup>
87+
```

‎wiki/AutoScrollingTextView.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
The `AutoScrollingTextView` is a UI component designed to enhance the user experience when displaying dynamic text content. It ensures that the text always resides at the vertical end and automatically scrolls when new text is appended to the bottom.
2+
3+
## Key Features
4+
- **Automatic Scrolling**: Automatically scrolls to the bottom when new content is added.
5+
- **Fade Effect**: Displays a fade effect at the top to indicate overflow content.
6+
- **Scroll-to-Bottom Button**: A button appears when the view is not at the bottom, allowing users to quickly scroll to the latest content.
7+
8+
This component is ideal for use cases such as chat applications, logs, or any scenario where real-time updates to text content are required.
9+
10+
## Usage
11+
12+
Here is an example of how to use the `AutoScrollingTextView`. You can also customize properties such as `textColor` and `textStyle`:
13+
14+
```xml
15+
<dui:AutoScrollingTextView
16+
Text="{Binding TranscriptionText}" />
17+
```
18+
19+
### Customization Options
20+
- **`TextColor`**: Set the color of the text using a color resource or hex value.
21+
- **`Style`**: Define the style of the text.
22+
- **`ShouldFadeOut`**: Whether the text should fade out at the top.
23+
- **`FadeColor`**: Defines the fade color at the top.

0 commit comments

Comments
 (0)