Skip to content

Commit 223beaa

Browse files
adamgrahamadamgraham
committed
Add documentation manuals
1 parent 97b6c7a commit 223beaa

File tree

8 files changed

+234
-0
lines changed

8 files changed

+234
-0
lines changed

‎Documentation~/articles/index.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
---
2+
slug: "/manual"
3+
---
4+
5+
# UI Toolkit
6+
7+
The **UI Toolkit** package contains scripts and utilities for creating UI in Unity projects. The package is intended to solve common problems that arise when developing UI and menus. The package is still early in development, and more functionality will be added over time.
8+
9+
<hr/>
10+
11+
## 📌 Overview
12+
13+
- [Scripting API](/api/Zigurous.UI)
14+
- [Installation](/manual/installation)
15+
- [Changelog](/changelog)
16+
- [License](/license)
17+
18+
<hr/>
19+
20+
## 📖 Reference
21+
22+
- [Menu Tools](/manual/menus)
23+
- [Letterboxing](/manual/letterboxing)
24+
- [Screen Size](/manual/screen-size)

‎Documentation~/articles/installation.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
slug: "/manual/installation"
3+
---
4+
5+
# Installation
6+
7+
Use the Unity [Package Manager](https://docs.unity3d.com/Manual/upm-ui.html) to install the **UI Toolkit** package.
8+
9+
1. Open the Package Manager in `Window > Package Manager`
10+
2. Click the add (`+`) button in the status bar
11+
3. Select `Add package from git URL` from the add menu
12+
4. Enter the following Git URL in the text box and click Add:
13+
14+
```http
15+
https://github.com/zigurous/unity-ui-toolkit.git
16+
```
17+
18+
<hr/>
19+
20+
## 🏷️ Namespace
21+
22+
Import the package namespace in each script or file you want to use it. You may need to regenerate project files/assemblies first.
23+
24+
```csharp
25+
using Zigurous.UI;
26+
```
27+
28+
<hr/>
29+
30+
## 💻 Source Code
31+
32+
The source code for the **UI Toolkit** package is in the following repository:
33+
34+
- https://github.com/zigurous/unity-ui-toolkit

‎Documentation~/articles/letterboxing.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
---
2+
slug: "/manual/letterboxing"
3+
---
4+
5+
# Letterboxing
6+
7+
Letterboxing is the process of changing an image or video's aspect ratio to another format while preserving the original aspect ratio. The resulting image has mattes (black bars) above and below it. The **UI Toolkit** packages includes a [Letterboxing](/api/Zigurous.UI/Letterboxing) script to handle this process. This script is most useful when displaying in-game cutscenes to give it a more cinematic feeling.
8+
9+
![](../images/letterboxing.jpg)
10+
11+
<hr/>
12+
13+
## 🎞️ Cinematic Bars
14+
15+
Also included in the **UI Toolkit** package is the script [CinematicBars](/api/Zigurous.UI/CinematicBars) which allows you to simulate the letterboxing effect without actually changing the camera's viewport. This script displays the mattes (black bars) as UI elements overlayed in screen space.
16+
17+
The color and material of the mattes can be customized as well as the desired aspect ratio. The script will animate the mattes in and out simply by enabling or disabling the script.

‎Documentation~/articles/menus.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
---
2+
slug: "/manual/menus"
3+
---
4+
5+
# Menu Tools
6+
7+
The **UI Toolkit** comes with a few scripts to assist in creating UI menus. There are several common problems that arise, especially in regards to menu navigation and controller-support. Generally speaking, basic navigation in menus across any input device can be achieved out-of-box using Unity's EventSystem component; however, this is not always the case.
8+
9+
<br/>
10+
11+
### [NavigationStack](/api/Zigurous.UI/NavigationStack)
12+
13+
This script manages a stack of game objects (menus) that you can navigate between. As you navigate to other menus or sub-menus, you push the menu's game object onto the stack. Then, when you need to navigate back to the previous menu, you simply pop the game object off the stack. The script can also automatically turn on/off the game objects as they are pushed and popped from the stack. The script also provides an InputAction to handle backwards navigation.
14+
15+
<hr/>
16+
17+
### [ScrollToSelection](/api/Zigurous.UI/ScrollToSelection)
18+
19+
This script works in conjunction with the EventSystem to handle scrolling a ScrollRect component to the selected game object. For example, when using a controller you usually do not freely scroll menus that display a list of buttons, such as a level select menu. Rather, you simply navigate up and down to the next or previous button, respectively. The ScrollRect will automatically be scrolled to whichever game object is selected.
20+
21+
<hr/>
22+
23+
### [ScrollWithInput](/api/Zigurous.UI/ScrollWithInput)
24+
25+
For other menus that use a ScrollRect component, you may just want to be able to freely scroll up and down. This may not be supported out of the box for controllers, so this script simply exposes an InputAction that you can bind controls to in order to scroll the menu. There is actually nothing specific to controllers in this script, so you can also use it with any kind of input, but generally mouse+keyboard already works with ScrollRect.

‎Documentation~/articles/screen-size.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
slug: "/manual/screen-size"
3+
---
4+
5+
# Screen Size
6+
7+
Detecting changes to the screen size is very common for many different use cases in games. The **UI Toolkit** package includes the singleton [ScreenSizeListener](/api/Zigurous.UI/ScreenSizeListener) that allows you to register a callback to know when the screen size changes.
8+
9+
```csharp
10+
ScreenSizeListener.Instance.resized += OnResize;
11+
12+
private void OnResize(float width, float height)
13+
{
14+
// handle resize here
15+
}
16+
```
17+
18+
You can simply get the current screen size too. There seems to be a bug with Unity's `Screen.width` and `Screen.height` because they do not always return the correct values. Using the listener can be more reliable.
19+
20+
```csharp
21+
if (ScreenSizeListener.HasInstance)
22+
{
23+
// Individual properties
24+
float width = ScreenSizeListener.Instance.width;
25+
float height = ScreenSizeListener.Instance.height;
26+
27+
// Single property
28+
Vector2Int size = ScreenSizeListener.Instance.size;
29+
}
30+
```

‎Documentation~/data/header.json‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
[
2+
{
3+
"name": "Manual",
4+
"basePath": "/manual"
5+
},
6+
{
7+
"name": "Scripting API",
8+
"basePath": "/api",
9+
"api": true
10+
},
11+
{
12+
"name": "Changelog",
13+
"basePath": "/changelog"
14+
},
15+
{
16+
"name": "License",
17+
"basePath": "/license"
18+
}
19+
]

‎Documentation~/data/sidenav.json‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
[
2+
{
3+
"basePath": "/",
4+
"categories": [
5+
{
6+
"title": "📌 Overview",
7+
"items": [
8+
{
9+
"name": "Getting Started",
10+
"path": "/manual"
11+
},
12+
{
13+
"name": "Installation",
14+
"path": "/manual/installation"
15+
},
16+
{
17+
"name": "Changelog",
18+
"path": "/changelog"
19+
},
20+
{
21+
"name": "License",
22+
"path": "/license"
23+
}
24+
]
25+
},
26+
{
27+
"title": "📖 Reference",
28+
"items": [
29+
{
30+
"name": "Menu Tools",
31+
"path": "/manual/menus"
32+
},
33+
{
34+
"name": "Letterboxing",
35+
"path": "/manual/letterboxing"
36+
},
37+
{
38+
"name": "Screen Size",
39+
"path": "/manual/screen-size"
40+
}
41+
]
42+
},
43+
{
44+
"title": "💬 Contact",
45+
"items": [
46+
{
47+
"name": "Discord",
48+
"href": "https://discord.gg/DdYyWVb",
49+
"icon": "launch"
50+
},
51+
{
52+
"name": "Twitter",
53+
"href": "https://twitter.com/zigurous",
54+
"icon": "launch"
55+
}
56+
]
57+
},
58+
{
59+
"title": "🔗 Other Links",
60+
"items": [
61+
{
62+
"name": "GitHub",
63+
"href": "https://github.com/zigurous/unity-ui-toolkit",
64+
"icon": "launch"
65+
},
66+
{
67+
"name": "Asset Store",
68+
"href": "https://assetstore.unity.com/publishers/51884",
69+
"icon": "launch"
70+
},
71+
{
72+
"name": "YouTube",
73+
"href": "https://youtube.com/c/zigurous?sub_confirmation=1",
74+
"icon": "launch"
75+
},
76+
{
77+
"name": "Patreon",
78+
"href": "https://patreon.com/zigurous",
79+
"icon": "launch"
80+
}
81+
]
82+
}
83+
]
84+
}
85+
]

‎Documentation~/images/letterboxing.jpg‎

59.6 KB
Loading

0 commit comments

Comments
 (0)