Skip to content

Commit f3db844

Browse files
rds1983rds1983
committed
Integrating docfx
1 parent 11be122 commit f3db844

22 files changed

+587
-3
lines changed

‎.github/workflows/build-and-publish-docs.yml‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
name: Build & Publish Docs
2+
3+
# Your GitHub workflow file under .github/workflows/
4+
# Trigger the action on push to master
5+
on:
6+
push:
7+
branches:
8+
- master
9+
workflow_dispatch:
10+
11+
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
12+
permissions:
13+
actions: read
14+
pages: write
15+
id-token: write
16+
17+
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
18+
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
19+
concurrency:
20+
group: "pages"
21+
cancel-in-progress: false
22+
23+
jobs:
24+
publish-docs:
25+
environment:
26+
name: github-pages
27+
url: ${{ steps.deployment.outputs.page_url }}
28+
runs-on: ubuntu-latest
29+
steps:
30+
- name: Checkout
31+
uses: actions/checkout@v3
32+
- name: Dotnet Setup
33+
uses: actions/setup-dotnet@v3
34+
with:
35+
dotnet-version: 8.x
36+
37+
- run: dotnet tool update -g docfx
38+
- run: docfx docfx/docfx.json
39+
40+
- name: Upload artifact
41+
uses: actions/upload-pages-artifact@v3
42+
with:
43+
# Upload entire repository
44+
path: 'docfx/_site'
45+
- name: Deploy to GitHub Pages
46+
id: deployment
47+
uses: actions/deploy-pages@v4

‎.gitignore‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -258,4 +258,9 @@ paket-files/
258258

259259
# Python Tools for Visual Studio (PTVS)
260260
__pycache__/
261-
*.pyc
261+
*.pyc
262+
263+
# API Docs
264+
docfx/api
265+
!docfx/api/index.md
266+
docfx/_site

‎Directory.Build.props‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
<Description>UI Library for MonoGame, FNA and Stride</Description>
99
<VersionPrefix>1.5.10</VersionPrefix>
1010
<XNAssetsVersion>0.8.2</XNAssetsVersion>
11-
<FontStashSharpVersion>1.5.2</FontStashSharpVersion>
11+
<FontStashSharpVersion>1.5.4</FontStashSharpVersion>
1212
<InfoLundinMathVersion>1.2.6</InfoLundinMathVersion>
1313
<MonoGameVersion>3.8.0.1641</MonoGameVersion>
1414
<AppMonoGameVersion>3.8.4.1</AppMonoGameVersion>

‎docfx/docfx.json‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
{
2+
"$schema": "https://raw.githubusercontent.com/dotnet/docfx/main/schemas/docfx.schema.json",
3+
"metadata": [
4+
{
5+
"src": [
6+
{
7+
"src": "../src",
8+
"files": [
9+
"**/Myra.MonoGame.csproj"
10+
]
11+
}
12+
],
13+
"dest": "api"
14+
}
15+
],
16+
"build": {
17+
"content": [
18+
{
19+
"files": [
20+
"**/*.{md,yml}"
21+
],
22+
"exclude": [
23+
"_site/**"
24+
]
25+
}
26+
],
27+
"resource": [
28+
{
29+
"files": [
30+
"images/**"
31+
]
32+
}
33+
],
34+
"output": "_site",
35+
"template": [
36+
"default",
37+
"modern"
38+
],
39+
"globalMetadata": {
40+
"_appName": "Myra",
41+
"_appTitle": "Myra",
42+
"_enableSearch": true
43+
}
44+
}
45+
}

‎docfx/docs/Images.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
### Overview
2+
This entry describes in detail how Myra deals with images.
3+
4+
### IBrush
5+
[IBrush](https://github.com/rds1983/Myra/blob/master/src/Myra/Graphics2D/IBrush.cs) represents something that can draw itself in the specified rectangle with the specified color:
6+
```c#
7+
public interface IBrush
8+
{
9+
void Draw(RenderContext context, Rectangle dest, Color color);
10+
}
11+
```
12+
13+
Many widgets properties such as Widget.Background or Menu.SelectionBackground have IBrush type.
14+
The most simple implementation of IBrush is [SolidBrush](https://github.com/rds1983/Myra/blob/master/src/Myra/Graphics2D/Brushes/SolidBrush.cs).
15+
16+
I.e. following code sets SolidBrush as widget.Background:
17+
```c#
18+
widget.Background = new SolidBrush(Color.Red); // SolidBrush from Color
19+
widget.Background = new SolidBrush("#808000FF"); // SolidBrush from RGBA string
20+
widget.Background = new SolidBrush("#FFA500"); // SolidBrush from RGB string
21+
```
22+
Also it could be set through [[MML]].
23+
24+
I.e. following MML:
25+
```xml
26+
<Project>
27+
<Panel>
28+
<HorizontalStackPanel Spacing="8" >
29+
<Panel Width="100" Height="50" Background="#FF0000FF" >
30+
</Panel>
31+
<Label Text="Label" Background="#0000FF" />
32+
<TextButton Text="Push Me" Background="YellowGreen" />
33+
</HorizontalStackPanel>
34+
</Panel>
35+
</Project>
36+
```
37+
Would result in following image:
38+
39+
![alt text](~/images/images.png)
40+
41+
### IImage
42+
[IImage](https://github.com/rds1983/Myra/blob/master/src/Myra/Graphics2D/IImage.cs) extends IBrush with Size property:
43+
```c#
44+
public interface IImage: IBrush
45+
{
46+
Point Size { get; }
47+
}
48+
```
49+
Widgets properties such as Image.Renderable or TextBox.Cursor have IImage type.
50+
51+
Myra provides 2 IImage implementation: TextureRegion and NinePatchRegion.
52+
53+
### TextureRegion
54+
[TextureRegion](https://github.com/rds1983/Myra/blob/master/src/Myra/Graphics2D/TextureAtlases/TextureRegion.cs) describes rectangle in the texture. TextureRegion implements IImage.
55+
56+
Therefore following code will work:
57+
```c#
58+
// 'texture' is object of type Texture2D
59+
image.Renderable = new TextureRegion(texture, new Rectangle(10, 10, 50, 50));
60+
```
61+
62+
Also following:
63+
```c#
64+
// If 2nd parameter is omitted, then TextureRegion covers the whole texture
65+
image.Renderable = new TextureRegion(texture);
66+
```
67+
_**Note**. It's also possible to use TextureRegion as IBrush. However usually it wont make much sense, since it would result in the TextureRegion streched over the rectangle IBrush is drawn at._
68+
69+
### NinePatchRegion
70+
[NinePatchRegion](https://github.com/rds1983/Myra/blob/master/src/Myra/Graphics2D/TextureAtlases/NinePatchRegion.cs) represents region with unstrechable border and strechable center.
71+
72+
It could be used following way:
73+
```c#
74+
widget.Background = new NinePatchRegion(texture, new Rectangle(10, 10, 50, 50),
75+
new Thickness {Left = 2, Right = 2,
76+
Top = 2, Bottom = 2});
77+
```
78+
_**Note**. Since NinePatchRegion is stretchable, it makes a lot of sense to use it as IBrush. In fact all backgrounds of the Myra widgets are NinePatchRegion._
79+
80+
### TextureRegionAtlas
81+
[TextureRegionAtlas](https://github.com/rds1983/Myra/blob/master/src/Myra/Graphics2D/TextureAtlases/TextureRegionAtlas.cs) is collection of texture regions(each could be nine patch) accessible by string key.
82+
83+
It could be loaded from [MyraTexturePacker](https://github.com/rds1983/MyraTexturePacker) format(.xmat) using following code:
84+
```c#
85+
// 'data' is string containing contents of .atlas file
86+
// 'textures' is dictionary that maps texture file names to actual textures
87+
TextureRegionAtlas spriteSheet = TextureRegionAtlas.Load(data, name => textures[name]);
88+
```

‎docfx/docs/MML.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
MML(Myra Markup Language) is XML based declarative language to describe UI.
2+
3+
I.e. following MML is equivalent to the UI from [[Quick Start Tutorial]]:
4+
```xml
5+
<Project>
6+
<Project.ExportOptions />
7+
<Grid ColumnSpacing="8" RowSpacing="8">
8+
<Grid.ColumnsProportions>
9+
<Proportion Type="Auto" />
10+
<Proportion Type="Auto" />
11+
</Grid.ColumnsProportions>
12+
<Grid.RowsProportions>
13+
<Proportion Type="Auto" />
14+
<Proportion Type="Auto" />
15+
</Grid.RowsProportions>
16+
<Label Text="Hello, World!" Id="label" />
17+
<ComboBox Grid.Column="1">
18+
<ListItem Text="Red" Color="#FF0000FF" />
19+
<ListItem Text="Green" Color="#008000FF" />
20+
<ListItem Text="Blue" Color="#0000FFFF" />
21+
</ComboBox>
22+
<Button Grid.Row="1"><Label Text="Show"/></Button>
23+
<SpinButton Nullable="True" Width="100" Grid.Column="1" Grid.Row="1" />
24+
</Grid>
25+
</Project>
26+
```
27+
28+
".xmmp" is preferred extension for files with MML.
29+
30+
Following code loads Project from MML:
31+
```c#
32+
string data = File.ReadAllText(filePath);
33+
Project project = Project.LoadFromXml(data);
34+
```
35+
36+
Following code saves it:
37+
```c#
38+
string data = project.Save();
39+
File.WriteAllText(filePath, data);
40+
```
41+
42+
Following code is used to obtain a reference to the element by id (used to attach event handlers):
43+
```c#
44+
Label label = (Label) project.Root.FindChildById("label");
45+
```

‎docfx/docs/MyraPad.md‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
MyraPad is WYSIWYG [[MML]] based UI designer.
2+
3+
![alt text](~/images/MyraPad.png)
4+
5+
It is included in the Myra binary distribution, which is Myra.v.v.v.v.zip from the latest release at https://github.com/rds1983/Myra/releases.
6+
7+
Following video demonstrates creation of simple main menu project in MyraPad:
8+
https://youtu.be/NZUCq2RMgZU
9+
10+
It creates UI with the following [[MML]]:
11+
```xml
12+
<Project>
13+
<Panel>
14+
<TextBlock Text="My Awesome Game" TextColor="#FFA500FF" HorizontalAlignment="Center" />
15+
<VerticalMenu HorizontalAlignment="Center" VerticalAlignment="Center" >
16+
<MenuItem Id="_menuStartNewGame" Text="Start New Game" />
17+
<MenuItem Id="_menuOptions" Text="Options" />
18+
<MenuItem Id="_menuQuit" Text="Quit" />
19+
</VerticalMenu>
20+
</Panel>
21+
</Project>
22+
```
23+
**Note**. MyraPad itself is made with Myra.
24+
25+
# Export To C#
26+
MyraPad can export projects to C#:
27+
https://youtu.be/94bPYKw4cAI
28+
29+
**Note**. Notice that export setting had been saved in the project in the newly appeared tag &lt;ExportOptions&gt;. Thus it wouldn't be required to enter it again.
30+
31+
That procedure created two files: MainMenu.cs and MenuMenu.Generated.cs. Now if export would be rerun, only MainMenu.Generated.cs would be rewritten. So it is safe to add any user code to MainMenu.cs
32+
33+
Let's take a look at contents of produced files.
34+
35+
MainMenu.cs:
36+
```c#
37+
/* Generated by MyraPad at 27.07.2019 13:00:34 */
38+
using Myra.Graphics2D.UI;
39+
40+
namespace MyraPadTest.UI
41+
{
42+
public partial class MainMenu: Panel
43+
{
44+
public MainMenu()
45+
{
46+
BuildUI();
47+
}
48+
}
49+
}
50+
```
51+
52+
MainMenu.Generated.cs
53+
```c#
54+
/* Generated by MyraPad at 27.07.2019 13:49:27 */
55+
using Microsoft.Xna.Framework;
56+
using Myra.Graphics2D.UI;
57+
58+
namespace MyraPadTest.UI
59+
{
60+
partial class MainMenu
61+
{
62+
private void BuildUI()
63+
{
64+
var textBlock1 = new TextBlock();
65+
textBlock1.Text = "My Game";
66+
textBlock1.TextColor = Color.Orange;
67+
textBlock1.HorizontalAlignment = Myra.Graphics2D.UI.HorizontalAlignment.Center;
68+
69+
_menuStartNewGame = new MenuItem();
70+
_menuStartNewGame.Id = "_menuStartNewGame";
71+
_menuStartNewGame.Text = "Start New Game";
72+
73+
_menuOptions = new MenuItem();
74+
_menuOptions.Id = "_menuOptions";
75+
_menuOptions.Text = "Options";
76+
77+
_menuQuit = new MenuItem();
78+
_menuQuit.Id = "_menuQuit";
79+
_menuQuit.Text = "Quit";
80+
81+
var verticalMenu1 = new VerticalMenu();
82+
verticalMenu1.HorizontalAlignment = Myra.Graphics2D.UI.HorizontalAlignment.Center;
83+
verticalMenu1.VerticalAlignment = Myra.Graphics2D.UI.VerticalAlignment.Center;
84+
verticalMenu1.Items.Add(_menuStartNewGame);
85+
verticalMenu1.Items.Add(_menuOptions);
86+
verticalMenu1.Items.Add(_menuQuit);
87+
88+
89+
Widgets.Add(textBlock1);
90+
Widgets.Add(verticalMenu1);
91+
}
92+
93+
94+
public MenuItem _menuStartNewGame;
95+
public MenuItem _menuOptions;
96+
public MenuItem _menuQuit;
97+
}
98+
}
99+
```
100+
101+
Notice that tags with id(all **MenuItem**) had been exported as class fields. Thus it's possible to work with it from code.
102+
I.e. if we update the MainMenu constructor with the following code:
103+
```c#
104+
public MainMenu()
105+
{
106+
BuildUI();
107+
_menuQuit.Selected += (s, a) => { Exit(); };
108+
}
109+
```
110+
111+
Then the app would quit when 'Quit' menu item is clicked.

‎docfx/docs/adding-reference-to-fna.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
Clone following projects in one folder:
2+
3+
Link|Description
4+
----|-----------
5+
<https://github.com/FNA-XNA/FNA>|FNA
6+
<https://github.com/FontStashSharp/FontStashSharp>|Text rendering library
7+
<https://github.com/rds1983/XNAssets>|Assets management library
8+
<https://github.com/rds1983/Myra>|Myra
9+
10+
Now add every required project .FNA.Core.csproj to your project

0 commit comments

Comments
 (0)