Skip to content

Commit

Permalink
docs: update overview and getting started for single project
Browse files Browse the repository at this point in the history
  • Loading branch information
kazo0 committed Apr 11, 2024
1 parent caac9ed commit 86dec17
Show file tree
Hide file tree
Showing 5 changed files with 141 additions and 85 deletions.
Binary file added doc/assets/material-wizard.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
88 changes: 55 additions & 33 deletions doc/cupertino-getting-started.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
uid: Uno.Themes.Cupertino.GetStarted
---

# Uno.Cupertino
# Uno Cupertino

<p align="center">
<img src="assets/cupertino-design-system.png" alt="Cupertino design system" />
Expand All @@ -12,34 +12,59 @@ Uno Cupertino is an add-on package that lets you apply [Cupertino - Human Interf

## Getting Started

> [!NOTE]
> As of [Uno Platform 4.7](https://platform.uno/blog/uno-platform-4-7-new-project-template-performance-improvements-and-more/), the solution template of an Uno app has changed. There is no longer a Shared project (.shproj), it has been replaced with a regular cross-platform library containing all user code files, referred to as the **App Code Library** project. This also implies that package references can be included in a single location without the previous need to include those in all project heads.
### Creating a new project with Uno Cupertino

### Creating a new project with Uno.Cupertino installed from command-line
1. Install the [`dotnet new` CLI templates](xref:Uno.GetStarted.dotnet-new) with:

1. Install `dotnet new` templates with:

```dotnetcli
```bash
dotnet new install Uno.Templates
```

2. Create a new application with:

```dotnetcli
dotnet new unoapp -o AppName -theme cupertino
```bash
dotnet new unoapp -o UnoCupertinoApp -theme cupertino
```

### Installing Uno Cupertino in an existing project

Depending on the type of project template that the Uno Platform application was created with, follow the instructions below to install Uno Cupertino.

# [**Single Project Template**](#tab/singleproj)

1. Edit your project file (`PROJECT_NAME.csproj`) and add `Cupertino` to the list of `UnoFeatures`:

```xml
<UnoFeatures>Cupertino</UnoFeatures>
```

### Installing Uno.Cupertino in existing project that uses class library
2. Initialize the Cupertino resources in the `App.xaml`:

```xml
<Application.Resources>
<ResourceDictionary>
<ResourceDictionary.MergedDictionaries>
<!-- Code ommitted of brevity -->
<uc:CupertinoColors xmlns="using:Uno.Cupertino" />
<uc:CupertinoFonts xmlns="using:Uno.Cupertino" />
<uc:CupertinoResources xmlns="using:Uno.Cupertino" />
</ResourceDictionary.MergedDictionaries>
</ResourceDictionary>
</Application.Resources>
```

# [**Multi-Head Project Template**](#tab/multihead)

1. In the Solution Explorer panel, right-click on your app's **App Code Library** project (`PROJECT_NAME.csproj`) and select `Manage NuGet Packages...`
1. Install the [`Uno.Cupertino.WinUI`](https://www.nuget.org/packages/Uno.Cupertino.WinUI)
1. Add the following Cupertino resources `AppResources.xaml`:
1. Add the following Cupertino resources to `AppResources.xaml`:
```xml
<ResourceDictionary>
<ResourceDictionary.MergedDictionaries>
<!-- Load Uno.Cupertino resources -->
<CupertinoColors xmlns="using:Uno.Cupertino" />
<CupertinoFonts xmlns="using:Uno.Cupertino" />
<CupertinoResources xmlns="using:Uno.Cupertino" />
Expand All @@ -48,25 +73,22 @@ Uno Cupertino is an add-on package that lets you apply [Cupertino - Human Interf
</ResourceDictionary>
```
### Installing Uno.Cupertino on previous versions of Uno Platform
# [**Shared Project (.shproj) Template**](#tab/shproj)
If your application is based on the older solution template that includes a shared project (.shproj), follow these steps:
1. Open an existing Uno project
2. In the Solution Explorer panel, right-click on your solution name and select `Manage NuGet Packages for Solution ...`. Choose either:
1. In the Solution Explorer panel, right-click on your solution name and select `Manage NuGet Packages for Solution ...`. Choose either:
- The [`Uno.Cupertino`](https://www.nuget.org/packages/Uno.Cupertino/) package when targetting Xamarin/UWP
- The [`Uno.Cupertino.WinUI`](https://www.nuget.org/packages/Uno.Cupertino.WinUI) package when targetting net6.0+/WinUI
3. Select the following projects for installation:
2. Select the following projects for installation:
- `PROJECT_NAME.Wasm.csproj`
- `PROJECT_NAME.Mobile.csproj` (or `PROJECT_NAME.iOS.csproj`, `PROJECT_NAME.Droid.csproj`, and `PROJECT_NAME.macOS.csproj` if you have an existing project)
- `PROJECT_NAME.Skia.Gtk.csproj`
- `PROJECT_NAME.Skia.WPF.csproj`
- `PROJECT_NAME.Windows.csproj` (or `PROJECT_NAME.UWP.csproj` for existing projects)
4. Add the following resources inside `App.xaml`:
3. Add the following resources inside `App.xaml`:
```xml
<Application ...>
<Application>
<Application.Resources>
<ResourceDictionary>
<ResourceDictionary.MergedDictionaries>
Expand All @@ -88,13 +110,14 @@ If your application is based on the older solution template that includes a shar
</Application>
```
---
## Customization
### Customize Color Palette
1. In the application's **App Code Library** project (`PROJECT_NAME.csproj`), add a new Resource Dictionary named `CupertinoColorsOverride.xaml`
2. Save the new override file within the **App Code Library**, for example, under `Style/Application`.
3. Replace the content with:
1. Add a new Resource Dictionary named `CupertinoColorsOverride.xaml` to the application project, for example, under `Styles/Application`.
2. Replace the content with:
```xml
<ResourceDictionary xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
Expand Down Expand Up @@ -123,36 +146,35 @@ If your application is based on the older solution template that includes a shar
</ResourceDictionary>
```
4. In `AppResources.xaml`, update `<CupertinoColors />` with the override from the previous steps:
3. In `App.xaml`, update `<CupertinoColors />` with the override from the previous steps:
```xml
<CupertinoColors xmlns="using:Uno.Cupertino"
OverrideSource="ms-appx:///PROJECT_NAME/Style/Application/CupertinoColorsOverride.xaml" />
OverrideSource="ms-appx:///Styles/Application/CupertinoColorsOverride.xaml" />
```
### Change Default Font
By default, Uno.Cupertino comes pre-packaged with the [SF Pro](https://developer.apple.com/fonts/) `FontFamily` and automatically includes them in your application. Upon installation of the Uno.Cupertino package, you will have a `CupertinoFontFamily` resource available.
By default, Uno Cupertino comes pre-packaged with the [SF Pro](https://developer.apple.com/fonts/) `FontFamily` and automatically includes them in your application. Upon installation of the Uno Cupertino package, you will have a `CupertinoFontFamily` resource available.
If you would like Uno.Cupertino to use a different font, you can override the default `FontFamily` following these steps:
If you would like Uno Cupertino to use a different font, you can override the default `FontFamily` following these steps:
1. Add the custom font following [Custom Fonts documentation](https://platform.uno/docs/articles/features/custom-fonts.html).
2. In the application's **App Code Library** project (`PROJECT_NAME.csproj`), add a new Resource Dictionary named `CupertinoFontsOverride.xaml`.
3. Save the new override file within the **App Code Library**, for example, under `Style/Application`.
4. Assuming the font file has been placed in the **App Code Library** within, for example, a directory such as `Assets/Fonts/MyCustomFont.ttf`, your override file would look like the following:
2. Add a new Resource Dictionary named `CupertinoFontsOverride.xaml` to the application project, for example, under `Styles/Application`.
3. Assuming the font file has been placed in a directory such as `Assets/Fonts/MyCustomFont.ttf`, your override file would look like the following: file would look like the following:
```xml
<ResourceDictionary xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
<FontFamily x:Key="CupertinoFontFamily">ms-appx:///PROJECT_NAME/Assets/Fonts/MyCustomFont.ttf</FontFamily>
<FontFamily x:Key="CupertinoFontFamily">ms-appx:///Assets/Fonts/MyCustomFont.ttf</FontFamily>
</ResourceDictionary>
```
5. In `AppResources.xaml`, update `<CupertinoFonts />` with the override from the previous steps:
4. In the `App.xaml`, update `<CupertinoFonts />` with the override from the previous steps:
```xml
<CupertinoFonts xmlns="using:Uno.Cupertino"
OverrideSource="ms-appx:///PROJECT_NAME/Style/Application/CupertinoFontsOverride.xaml" />
OverrideSource="ms-appx:///Styles/Application/CupertinoFontsOverride.xaml" />
```
2 changes: 1 addition & 1 deletion doc/fluent-getting-started.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ The step-by-step process to enable Fluent design styles within an existing Uno P

1. In only the `UWP` head project of your solution, if you have one, install the [WinUI 2 NuGet package](https://www.nuget.org/packages/Microsoft.UI.Xaml). This step is the same as required for WinUI 2 UWP apps.

1. Within the shared project used by all platform heads, add the `XamlControlsResources` resource dictionary to your application resources inside `App.xaml`. This step is the same as required for WinUI 2 UWP apps.
1. Add the `XamlControlsResources` resource dictionary to your application resources inside `App.xaml`. This step is the same as required for WinUI 2 UWP apps.

```xml
<Application>
Expand Down
Loading

0 comments on commit 86dec17

Please sign in to comment.