Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: update overview and getting started for single project #1385

Merged
merged 11 commits into from
Apr 12, 2024
Merged
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
kazo0 marked this conversation as resolved.
Show resolved Hide resolved

### Creating a new project with Uno.Cupertino installed from command-line
1. Install the [`dotnet new` CLI templates](xref:Uno.GetStarted.dotnet-new) with:
kazo0 marked this conversation as resolved.
Show resolved Hide resolved

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)
kazo0 marked this conversation as resolved.
Show resolved Hide resolved

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)
kazo0 marked this conversation as resolved.
Show resolved Hide resolved

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)
kazo0 marked this conversation as resolved.
Show resolved Hide resolved

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" />
kazo0 marked this conversation as resolved.
Show resolved Hide resolved
```

### 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:
kazo0 marked this conversation as resolved.
Show resolved Hide resolved

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:
kazo0 marked this conversation as resolved.
Show resolved Hide resolved

```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.
kazo0 marked this conversation as resolved.
Show resolved Hide resolved

```xml
<Application>
Expand Down
Loading
Loading