diff --git a/docs/get-started/getting-started.md b/docs/get-started/getting-started.md index 86c93c3e1..d89f191a5 100644 --- a/docs/get-started/getting-started.md +++ b/docs/get-started/getting-started.md @@ -1,4 +1,4 @@ -s--- +--- id: getting-started title: Starting with the CLI --- diff --git a/docs/get-started/install.md b/docs/get-started/install.md index f687fcc9a..7273ebb41 100644 --- a/docs/get-started/install.md +++ b/docs/get-started/install.md @@ -3,11 +3,16 @@ id: install title: Install --- +## Preinstallation + +Please start with the supported IDE of your choice installed. Avalonia supports Visual Studio, Rider, and Visual Studio +Code. + ## Install Avalonia UI Templates -The best place to get started with Avalonia is by creating an application using a template. +The best way to get started with Avalonia is by creating an application using a project template. -To install the Avalonia templates, run the following command: +To install the [Avalonia templates](https://github.com/AvaloniaUI/avalonia-dotnet-templates), run the following command: ```bash dotnet new install Avalonia.Templates @@ -36,4 +41,56 @@ Avalonia Styles avalonia.styles Avalonia TemplatedControl avalonia.templatedcontrol [C#],F# Desktop/Xaml/Avalonia/Windows/Linux/macOS Avalonia UserControl avalonia.usercontrol [C#],F# Desktop/Xaml/Avalonia/Windows/Linux/macOS Avalonia Window avalonia.window [C#],F# Desktop/Xaml/Avalonia/Windows/Linux/macOS -``` \ No newline at end of file +``` + +## Create a new Application + +Once the project templates are installed, you can create a new _Avalonia UI_ application from CLI by running the following command: + +```bash +dotnet new avalonia.app -o MyApp +``` + +This will create a new folder called `MyApp` containing your application files. To run the application, navigate to the `MyApp` folder and run: + +```bash +cd MyApp +dotnet run +``` + +The project templates will also allow for project creation from your IDE. + +## Installation Troubleshooting + +### Ensure .NET SDK is installed + +``` +dotnet --list-sdks + +8.0.202 [C:\Program Files\dotnet\sdk] <-- Your version may vary +``` + +If `dotnet` is not a recognized program, then ensure you've installed your IDE first. Next, ensure that `dotnet` is +associated with the terminal. On Windows, this involves checking environment variables: `echo %PATH%` in the command prompt or +`echo $Env:PATH` in PowerShell. + +### Ensure NuGet source is correct + +If while installing the project templates, you receive an error stating the `Avalonia.Templates` package cannot be found, +then ensure NuGet is correctly setup with .NET's standard global package source. + +``` +dotnet nuget list source + +Registered Sources: + 1. nuget.org [Enabled] + https://api.nuget.org/v3/index.json +``` + +If this source is not listed, add it: + +``` +dotnet nuget add source https://api.nuget.org/v3/index.json -n nuget.org +``` + +If the package install still fails despite NuGet being listed, then suspect a network connectivity or firewall issue. diff --git a/docs/get-started/set-up-an-editor.md b/docs/get-started/set-up-an-editor.md index 44560eb37..cb754324c 100644 --- a/docs/get-started/set-up-an-editor.md +++ b/docs/get-started/set-up-an-editor.md @@ -8,15 +8,18 @@ import AvaloniaVsExtensionNuGetScreenshot from '/img/get-started/avalonia-vs-ext # Set Up an Editor -You can create an Avalonia application using any code editor, but using an IDE will give you support for authoring Avalonia XAML files with a previewer and code completion. +You can create an Avalonia application using any code editor, but using an IDE will give you support for authoring +Avalonia XAML files with a previewer and code completion. ## JetBrains Rider -The [JetBrains Rider](https://www.jetbrains.com/rider/) IDE has built-in support for Avalonia XAML [starting in 2020.3](https://www.jetbrains.com/rider/whatsnew/2020-3/#version-2020-3-avalonia-support) including first-class support for Avalonia-specific XAML features and custom code inspections. +The [JetBrains Rider](https://www.jetbrains.com/rider/) IDE has built-in support for Avalonia XAML [starting in 2020.3](https://www.jetbrains.com/rider/whatsnew/2020-3/#version-2020-3-avalonia-support) including first-class +support for Avalonia-specific XAML features and custom code inspections. See the [JetBrains Rider 2020.3 release announcement](https://www.jetbrains.com/rider/whatsnew/2020-3/#version-2020-3-avalonia-support) for more information. -Rider does not yet provide a visual designer, but this is in development. See [the GitHub project](https://github.com/ForNeVeR/AvaloniaRider) for more information and instructions on how to install. +Rider does not yet provide a visual designer, but this is in development. See [the GitHub project](https://github.com/ForNeVeR/AvaloniaRider) for more +information and instructions on how to install. ## Visual Studio @@ -24,7 +27,7 @@ If you're developing Avalonia with Visual Studio you should install the [Avaloni -The extension provides intellisense support for Avalonia XAML together with a previewer. +The extension provides IntelliSense support for Avalonia XAML together with a previewer. To install the Avalonia for Visual Studio extension: diff --git a/docs/get-started/test-drive/add-a-control.md b/docs/get-started/test-drive/add-a-control.md index 578edbbe3..7b3f36df6 100644 --- a/docs/get-started/test-drive/add-a-control.md +++ b/docs/get-started/test-drive/add-a-control.md @@ -7,34 +7,38 @@ import Highlight from '@site/src/components/Highlight'; import CalculateButton from '/img/get-started/test-drive/calculate-button.png'; import ButtonIntellisenseScreenshot from '/img/get-started/test-drive/button-intellisense.png'; -So far the main window of your application displays only a text string. On this page, you will learn how to add some of the built-in controls that are part of Avalonia. +So far, the main window of your application displays only a text string. On this page, you will learn how to add some of the built-in controls that are part of Avalonia. ## Button -Avalonia contains a built-in control that creates a button. Follow this procedure to replace the text string you currently have in the content zone of the window, with a button control. +Avalonia contains a built-in control that creates a button. Follow this procedure to replace the text string currently in the `Window`'s content zone with a button control. - Stop the app if it is running. - Locate the `` in the `MainView.axaml` file.. - Delete the entire line. -- Insert a 'Button' tag as shown: +- Insert a `Button` tag as shown: ```xml ``` :::tip -If you're using a previewer, you will see the button appear in the preview pane as soon as the XAML is valid. You can also try out a mouse move-over and click on the button to see the different colors it displays in different states. +If you're using the previewer, you will see the button appear in the preview pane as soon as the XAML is valid. You can +also try hovering and clicking the `Button` to see it change appearance in different states. ::: - Run the app to confirm that the presentation and behaviour of the button is the same at runtime. ## Control Attributes -The XAML code for Avalonia controls uses attributes to specify presentation and behaviour. The attributes can set properties, call methods and event handlers in the controls created by the XAML. +XAML uses XML attributes to specify presentation and behavior for controls. These attributes can set properties, call +methods, and call event handlers in the controls created by the XAML. -For example, you will notice that the button you just implemented is rendered hard against the left edge of the window. This is a result of the default value of its horizontal alignment property (which is left). Follow this procedure to set the horizontal alignment to centered instead. +For example, the `Button` is currently positioned hard against the left edge of the `Window`. This is a result +of the default value (left) of its `HorizontalAlignment` property. Follow this +procedure to set the `HorizontalAlignment` to centered instead. - Add a new attribute to the Button tag as follows: @@ -43,12 +47,13 @@ For example, you will notice that the button you just implemented is rendered h ``` :::tip -If you're using an IDE, notice how the Avalonia Intellisense guides you as you add attributes to the XAML. +If you're using an IDE, notice how the Avalonia code completion guides you as you add attributes to the XAML. ::: -The button should now move to the center of the window content zone (both horizontally and vertically). +The `Button` should now move to the center of the window content zone. Horizontally because of the change and vertically +because of the Button's default. :::info For full information about the complete range of Avalonia UI built-in controls, and their attributes, see the reference section [here](../../reference/controls). diff --git a/docs/get-started/test-drive/add-some-layout.md b/docs/get-started/test-drive/add-some-layout.md index 7504aaeb2..5a08fb52b 100644 --- a/docs/get-started/test-drive/add-some-layout.md +++ b/docs/get-started/test-drive/add-some-layout.md @@ -6,15 +6,18 @@ title: Add Some Layout import StackPanelZonesDiagram from '/img/get-started/test-drive/stackpanel-zones.png'; import TemperatureStackPanelScreenshot from '/img/get-started/test-drive/temperature-stackpanel.png'; -Avalonia provides a range of built-in controls to help you layout the visual elements of an application. On this page you will see how to use some of these layout controls. +Avalonia provides a range of built-in controls to help you layout the visual elements of an application. On this page, +you will see how to use some of these layout controls. At this stage, your application has a single button located in the content zone of the main window. -In fact an Avalonia window allows only a single other control in its content zone. So to add the multiple visual elements required for most applications, you will need to use one of the built-in layout controls that allows multiple other controls inside its content zone. +In fact, an Avalonia `Window` allows only one control in its content zone. To show multiple visual elements, you +must use a layout control that allows multiple controls within its content zone. -## Stack Panel +## StackPanel -The stack panel control allows multiple controls in its content zone, and arranges them in a vertical stack in the sequence they are defined in the XAML. +The `StackPanel` control lays out a sequence of controls in the order they are defined in XAML. By default, it lays out +in a vertical stack but this can be changed to horizontal with its `Orientation` property. @@ -25,33 +28,30 @@ The stack panel control allows multiple controls in its content zone, and arrang ``` -## Text Block +## TextBlock -The text block control gives you full control over the styling of the text it contains. +The `TextBlock` control allows extensive styling of its contained text. -To take the example forwards, add a stack panel as follows (you can include the existing the button XAML). +To take the example forward, add a `StackPanel` as follows (include the preexisting `Button` XAML): ```xml - - - + + + - - + - + ``` :::info -You can explore the other layout controls in Avalonia from the reference [here](../../reference/controls/layout-controls.md). +You can explore the other layout controls in Avalonia using the reference [here](../../reference/controls/layout-controls.md). ::: On the next page, you will add some inputs to the middle of the window. \ No newline at end of file diff --git a/docs/get-started/test-drive/code-with-controls.md b/docs/get-started/test-drive/code-with-controls.md index 3e9e5b90f..7de5c72eb 100644 --- a/docs/get-started/test-drive/code-with-controls.md +++ b/docs/get-started/test-drive/code-with-controls.md @@ -3,19 +3,18 @@ id: code-with-controls title: Code With Controls --- -import Highlight from '@site/src/components/Highlight'; - -The action you will implement here is to update the Fahrenheit temperature control, using the value of the `celsius` control, and a simple formula, whenever the button is clicked. +In this section, you will implement the core logic to update the Fahrenheit temperature based on the Celsius input. ## Control Names -When Avalonia creates the main window at runtime, it also creates objects for each of the controls defined in the window. Your code can access the controls at runtime, but to access them, it will need some control names. +Avalonia creates objects for each control defined in the XAML hierarchy. Your code can access these controls at runtime, +but should be named for easy access. -To add some control names, follow this procedure: +To add control names, follow this procedure: - Stop the app if it is running. - Locate the `TextBox` for Celsius. -- Add the name attribute like this: +- Add the `Name` attribute like this: ```xml @@ -27,11 +26,11 @@ To add some control names, follow this procedure: ``` -## Get Control Values in Code-behind +## Get Control Values in Code-Behind -To demonstrate access to the text value of the `celsius` input, follow this procedure: +To access the `Text` value of the `celsius` input, follow this procedure: -- Switch to the **MainWindow.axaml.cs** code-behind file. +- Switch to the **MainView.axaml.cs** code-behind file. - Locate the `ButtonClicked` event handler. - Alter the `Debug` statement to display the text property of the `celsius` input, like this: @@ -41,9 +40,10 @@ Debug.WriteLine($"Click! Celsius={celsius.Text}"); - Run the app to confirm that you can see the value in the Celsius appear in the debug window. -## Set Control Values in Code-behind +## Set Control Values in Code-Behind -To use the simple formula that converts Celsius temperature to Fahrenheit, you will first need to ensure that the Celsius input text converts to a number. The formula is then: +To use the simple formula that converts Celsius temperature to Fahrenheit, you will first need to ensure that the +Celsius input text converts to a number. The formula is then: ``` Tf = Tc * (9/5) + 32 @@ -52,43 +52,47 @@ Tf = Tc * (9/5) + 32 To add the conversion formula, follow this procedure: - Locate the `ButtonClicked` event handler. -- Alter the code in the event handler to check that the Celsius input text converts to a number. -- Alter the code to include the conversion formula. -- Update the text in the Fahrenheit input to the result of the conversion formula. +- Validate the Celsius input text as a number. +- Use the conversion formula. +- Update the `Text` in the Fahrenheit input. - Run the app to check your work. One implementation of the above is as follows: ```csharp -if (Double.TryParse(celsius.Text, out double C)) -{ - var F = C * (9d / 5d) + 32; - fahrenheit.Text = F.ToString("0.0"); -} -else +public void ButtonClicked(object source, RoutedEventArgs args) { - celsius.Text = "0"; - fahrenheit.Text = "0"; + if (Double.TryParse(celsius.Text, out double C)) + { + var F = C * (9d / 5d) + 32; + fahrenheit.Text = F.ToString("0.0"); + } + else + { + celsius.Text = "0"; + fahrenheit.Text = "0"; + } } ``` You can check your work using the following conversion table: -| Celsius | Farenheit | -| ---------- | --------- | -| -10 | 14.0 | -| 0 | 32.0 | -| 10 | 50.0 | -| 21 | 69.8 | -| 25 | 77.0 | -| 32 | 89.6 | +| Celsius | Fahrenheit | +|---------|------------| +| -10 | 14.0 | +| 0 | 32.0 | +| 10 | 50.0 | +| 21 | 69.8 | +| 25 | 77.0 | +| 32 | 89.6 | ### Exercises -- You have now used an event handler to get and set control properties at runtime. You could now try some of these exercises: +You have now used an event handler to get and set control properties at runtime. Try some of these exercises: + - Stop showing the gridlines (easy). -- Stop the user changing the text in the Fahrenheit input by setting the `IsReadOnly` attribute (easy). -- Calculate the conversion as the user types into the Celsius input (moderate). +- Stop the user from changing the text in the Fahrenheit input by setting the `IsReadOnly` attribute (easy). +- Calculate the conversion as the user types into the Celsius input using the `TextChanged` event (moderate). :::info For full information about the complete range of Avalonia built-in controls, events and attributes, see the controls reference section [here](../../reference/controls/). diff --git a/docs/get-started/test-drive/create-a-project.md b/docs/get-started/test-drive/create-a-project.md index 37a9d7754..d2e4cd67f 100644 --- a/docs/get-started/test-drive/create-a-project.md +++ b/docs/get-started/test-drive/create-a-project.md @@ -25,7 +25,7 @@ dotnet new install Avalonia.Templates To get started, we're going to use the MVVM Avalonia template: `Avalonia MVVM Application` (or `avalonia.mvvm` in the CLI). - + Run the command: @@ -75,7 +75,7 @@ The template will create a new solution and two new projects. `GetStartedApp` is We're now ready to run the project! - + Go into the `GetStartedApp` directory and run: diff --git a/docs/get-started/test-drive/input-controls.md b/docs/get-started/test-drive/input-controls.md index 2c6840062..9b3288d00 100644 --- a/docs/get-started/test-drive/input-controls.md +++ b/docs/get-started/test-drive/input-controls.md @@ -5,64 +5,78 @@ title: Input Controls import InputControlsScreenshot from '/img/get-started/test-drive/input-controls.png'; -On this page, you will learn how to add some of the Avalonia input controls in a neat layout. The aim is to add a numerical inputs with their associated labels in horizontal rows; with an output control in the row below. +On this page, you will learn how to add input controls and arrange them in a neatly aligned layout. The aim is to add +numerical inputs with labels and an output control following in the row below. -To achieve this layout, you will use the built-in grid control, and locate label and input controls in its cells. +To achieve this layout, you will use the built-in `Grid` control to create cells and assign our controls to those cells. -This picture shows the resulting layout (running) with the gridlines showing. The gridlines are showing for the purpose of visualizing the layout - you would not usually do this on a production UI. +The following picture shows the finished application at runtime with the gridlines showing for layout visualization purposes. Normally, +these are invisible on a production UI. -To create a layout using the grid control, follow this procedure: +To create a layout using the `Grid` control with 2 columns and 3 rows, follow this procedure: - Stop the app if it is running. -- Locate the middle stack panel in the XAML, and delete the tag. +- Locate the empty line in the XAML between `` and ` + ``` -This sets out the column and row sizes for the grid (and makes the gridlines visible - although it will show as just a straight line now, as the grid is still empty). - -Now add label and input controls to the cells of the grid: +This assigns the number of rows and columns, their sizes, and makes the gridlines visible. Currently, it will show as a +straight line because the grid cells are empty. The `Auto` rows size to their content and will have zero height until +content is added. -- Add `