mirror of
https://github.com/Stone-Red-Code/docs-desktop.git
synced 2026-09-04 09:06:04 +02:00
Initial publish of WinForms for .NET 5. (#96)
* Migrate inprogress winforms contnet from docs * Fix preview note * Fix vb code * Minor fixes to keyboard articles * Minor adjustment to overview * Test redirects for 4.0 -> 5.0 * adjust links * Add mouse input section winforms (#81) * Update projects to .NET 5 * Update keyboard desc * Finish mouse events * Add remaining mouse articles;code * finish mouse input * minor fixes * Remove branch restriction (#82) * Update build-validation.yml (#84) * Update build-validation.yml (#85) * Fix vb proj * Add WinForms tutorial (#91) * redirect between overview * New create an app tutorial * Fix markdown * Fix preserve view setting * Add forms articles (#93) * Add forms articles * Fix warnings * Winforms publish (#95) * Prep TOC for publish * Updated date * Automatic how-to topic type * Update desc/headers * Fix links * Fix build errors * Add preview note * Update toc landing page * Convert old style project files * update download links * Apply suggestions from code review Co-authored-by: Genevieve Warren <[email protected]> * Adjust number key * Update dotnet-desktop-guide/net/winforms/overview/index.md * Try toc position task via bookmark * Improve images * Remove sentence * File redirects Co-authored-by: Genevieve Warren <[email protected]>
This commit is contained in:
Andy De George
co-authored by
Genevieve Warren
Genevieve Warren
parent
f7e5ce92ea
commit
184e6c9a0c
@@ -0,0 +1,65 @@
|
||||
---
|
||||
title: "Automatic form scaling"
|
||||
description: "A look into how Windows Forms for .NET handles scaling the UI."
|
||||
ms.date: 10/26/2020
|
||||
ms.topic: overview
|
||||
helpviewer_keywords:
|
||||
- "scalability [Windows Forms], automatic in Windows Forms"
|
||||
- "Windows Forms, automatic scaling"
|
||||
---
|
||||
|
||||
# Automatic scaling (Windows Forms .NET)
|
||||
|
||||
Automatic scaling enables a form and its controls, designed on one machine with a certain display resolution or font, to be displayed appropriately on another machine with a different display resolution or font. It assures that the form and its controls will intelligently resize to be consistent with native windows and other applications on both the users' and other developers' machines. Automatic scaling and visual styles enable Windows Forms applications to maintain a consistent look-and-feel when compared to native Windows applications on each user's machine.
|
||||
|
||||
For the most part, automatic scaling works as expected in Windows Forms. However, font scheme changes can be problematic.<!-- TODO For an example of how to resolve this, see [How to: Respond to Font Scheme Changes in a Windows Forms Application](how-to-respond-to-font-scheme-changes-in-a-windows-forms-application.md). -->
|
||||
|
||||
[!INCLUDE [desktop guide under construction](../../includes/desktop-guide-preview-note.md)]
|
||||
|
||||
## Need for automatic scaling
|
||||
|
||||
Without automatic scaling, an application designed for one display resolution or font will either appear too small or too large when that resolution or font is changed. For example, if the application is designed using Tahoma 9 point as a baseline, without adjustment it will appear too small if run on a machine where the system font is Tahoma 12 point. Text elements, such as titles, menus, text box contents, and so on will render smaller than other applications. Furthermore, the size of user interface (UI) elements that contain text, such as the title bar, menus, and many controls are dependent on the font used. In this example, these elements will also appear relatively smaller.
|
||||
|
||||
An analogous situation occurs when an application is designed for a certain display resolution. The most common display resolution is 96 dots per inch (DPI), which equals 100% display scaling, but higher resolution displays supporting 125%, 150%, 200% (which respectively equal 120, 144 and 192 DPI) and above are becoming more common. Without adjustment, an application, especially a graphics-based one, designed for one resolution will appear either too large or too small when run at another resolution.
|
||||
|
||||
Automatic scaling seeks to address these problems by automatically resizing the form and its child controls according to the relative font size or display resolution. The Windows operating system supports automatic scaling of dialog boxes using a relative unit of measurement called dialog units. A dialog unit is based on the system font and its relationship to pixels can be determined though the Win32 SDK function `GetDialogBaseUnits`. When a user changes the theme used by Windows, all dialog boxes are automatically adjusted accordingly. In addition, Windows Forms supports automatic scaling either according to the default system font or the display resolution. Optionally, automatic scaling can be disabled in an application.
|
||||
|
||||
> [!CAUTION]
|
||||
> Arbitrary mixtures of DPI and font scaling modes are not supported. Although you may scale a user control using one mode (for example, DPI) and place it on a form using another mode (Font) with no issues, but mixing a base form in one mode and a derived form in another can lead to unexpected results.
|
||||
|
||||
## Automatic scaling in action
|
||||
|
||||
Windows Forms uses the following logic to automatically scale forms and their contents:
|
||||
|
||||
01. At design time, each <xref:System.Windows.Forms.ContainerControl> records the scaling mode and it current resolution in the <xref:System.Windows.Forms.ContainerControl.AutoScaleMode%2A> and <xref:System.Windows.Forms.ContainerControl.AutoScaleDimensions%2A>, respectively.
|
||||
|
||||
01. At run time, the actual resolution is stored in the <xref:System.Windows.Forms.ContainerControl.CurrentAutoScaleDimensions%2A> property. The <xref:System.Windows.Forms.ContainerControl.AutoScaleFactor%2A> property dynamically calculates the ratio between the run-time and design-time scaling resolution.
|
||||
|
||||
01. When the form loads, if the values of <xref:System.Windows.Forms.ContainerControl.CurrentAutoScaleDimensions%2A> and <xref:System.Windows.Forms.ContainerControl.AutoScaleDimensions%2A> are different, then the <xref:System.Windows.Forms.ContainerControl.PerformAutoScale%2A> method is called to scale the control and its children. This method suspends layout and calls the <xref:System.Windows.Forms.Control.Scale%2A> method to perform the actual scaling. Afterwards, the value of <xref:System.Windows.Forms.ContainerControl.AutoScaleDimensions%2A> is updated to avoid progressive scaling.
|
||||
|
||||
01. <xref:System.Windows.Forms.ContainerControl.PerformAutoScale%2A> is also automatically invoked in the following situations:
|
||||
|
||||
- In response to the <xref:System.Windows.Forms.Control.OnFontChanged%2A> event if the scaling mode is <xref:System.Windows.Forms.AutoScaleMode.Font>.
|
||||
|
||||
- When the layout of the container control resumes and a change is detected in the <xref:System.Windows.Forms.ContainerControl.AutoScaleDimensions%2A> or <xref:System.Windows.Forms.ContainerControl.AutoScaleMode%2A> properties.
|
||||
|
||||
- As implied above, when a parent <xref:System.Windows.Forms.ContainerControl> is being scaled. Each container control is responsible for scaling its children using its own scaling factors and not the one from its parent container.
|
||||
|
||||
01. Child controls can modify their scaling behavior through several means:
|
||||
|
||||
- The <xref:System.Windows.Forms.Control.ScaleChildren%2A> property can be overridden to determine if their child controls should be scaled or not.
|
||||
|
||||
- The <xref:System.Windows.Forms.Control.GetScaledBounds%2A> method can be overridden to adjust the bounds that the control is scaled to, but not the scaling logic.
|
||||
|
||||
- The <xref:System.Windows.Forms.Control.ScaleControl%2A> method can be overridden to change the scaling logic for the current control.
|
||||
|
||||
## See also
|
||||
|
||||
- <xref:System.Windows.Forms.ContainerControl.AutoScaleMode%2A>
|
||||
- <xref:System.Windows.Forms.Control.Scale%2A>
|
||||
- <xref:System.Windows.Forms.ContainerControl.PerformAutoScale%2A>
|
||||
- <xref:System.Windows.Forms.ContainerControl.AutoScaleDimensions%2A>
|
||||
|
||||
<!-- TODO
|
||||
- [Rendering Controls with Visual Styles](controls/rendering-controls-with-visual-styles.md)
|
||||
- [How to: Improve Performance by Avoiding Automatic Scaling](advanced/how-to-improve-performance-by-avoiding-automatic-scaling.md)-->
|
||||
@@ -0,0 +1,52 @@
|
||||
---
|
||||
title: "Events Overview"
|
||||
description: "A brief overview about events with .NET Windows Forms."
|
||||
ms.date: 10/26/2020
|
||||
ms.topic: overview
|
||||
helpviewer_keywords:
|
||||
- "Windows Forms, event handling"
|
||||
- "events [Windows Forms], about events"
|
||||
- "delegates [Windows Forms], multicast"
|
||||
- "delegates [Windows Forms], events and"
|
||||
- "multicast event delegates"
|
||||
- "Windows Forms controls, events"
|
||||
---
|
||||
|
||||
# Events overview (Windows Forms .NET)
|
||||
|
||||
An event is an action that you can respond to, or "handle," in code. Events can be generated by a user action, such as clicking the mouse or pressing a key, by program code, or by the system.
|
||||
|
||||
[!INCLUDE [desktop guide under construction](../../includes/desktop-guide-preview-note.md)]
|
||||
|
||||
Event-driven applications execute code in response to an event. Each form and control exposes a predefined set of events that you can program against. If one of these events occurs and there's code an associated event handler, that code is invoked.
|
||||
|
||||
The types of events raised by an object vary, but many types are common to most controls. For example, most objects will handle a <xref:System.Windows.Forms.Control.Click> event. If a user clicks a form, code in the form's <xref:System.Windows.Forms.Control.Click> event handler is executed.
|
||||
|
||||
> [!NOTE]
|
||||
> Many events occur in conjunction with other events. For example, in the course of the <xref:System.Windows.Forms.Control.DoubleClick> event occurring, the <xref:System.Windows.Forms.Control.MouseDown>, <xref:System.Windows.Forms.Control.MouseUp>, and <xref:System.Windows.Forms.Control.Click> events occur.
|
||||
|
||||
For information about how to raise and consume an event, see [Handling and raising events](/dotnet/standard/events/index).
|
||||
|
||||
## Delegates and their role
|
||||
|
||||
Delegates are classes commonly used within .NET to build event-handling mechanisms. Delegates roughly equate to function pointers, commonly used in Visual C++ and other object-oriented languages. Unlike function pointers however, delegates are object-oriented, type-safe, and secure. Also, where a function pointer contains only a reference to a particular function, a delegate consists of a reference to an object, and references to one or more methods within the object.
|
||||
|
||||
This event model uses *delegates* to bind events to the methods that are used to handle them. The delegate enables other classes to register for event notification by specifying a handler method. When the event occurs, the delegate calls the bound method. For more information about how to define delegates, see [Handling and raising events](/dotnet/standard/events/index).
|
||||
|
||||
Delegates can be bound to a single method or to multiple methods, referred to as multicasting. When creating a delegate for an event, you typically create a multicast event. A rare exception might be an event that results in a specific procedure (such as displaying a dialog box) that wouldn't logically repeat multiple times per event. For information about how to create a multicast delegate, see [How to combine delegates (Multicast Delegates)](/dotnet/csharp/programming-guide/delegates/how-to-combine-delegates-multicast-delegates).
|
||||
|
||||
A multicast delegate maintains an invocation list of the methods it's bound to. The multicast delegate supports a <xref:System.Delegate.Combine%2A> method to add a method to the invocation list and a <xref:System.Delegate.Remove%2A> method to remove it.
|
||||
|
||||
When an event is recorded by the application, the control raises the event by invoking the delegate for that event. The delegate in turn calls the bound method. In the most common case (a multicast delegate), the delegate calls each bound method in the invocation list in turn, which provides a one-to-many notification. This strategy means that the control doesn't need to maintain a list of target objects for event notification—the delegate handles all registration and notification.
|
||||
|
||||
Delegates also enable multiple events to be bound to the same method, allowing a many-to-one notification. For example, a button-click event and a menu-command–click event can both invoke the same delegate, which then calls a single method to handle these separate events the same way.
|
||||
|
||||
The binding mechanism used with delegates is dynamic: a delegate can be bound at run-time to any method whose signature matches that of the event handler. With this feature, you can set up or change the bound method depending on a condition and to dynamically attach an event handler to a control.
|
||||
|
||||
## See also
|
||||
|
||||
- [Handling and raising events](/dotnet/standard/events/index)
|
||||
|
||||
<!-- TODO
|
||||
- [Creating Event Handlers in Windows Forms](creating-event-handlers-in-windows-forms.md)
|
||||
- [Event Handlers Overview](event-handlers-overview-windows-forms.md)-->
|
||||
@@ -0,0 +1,49 @@
|
||||
---
|
||||
title: "Add a form to a project"
|
||||
description: "Add a new form to a .NET Windows Forms project in Visual Studio"
|
||||
ms.date: 10/26/2020
|
||||
helpviewer_keywords:
|
||||
- "Windows Forms, create add form"
|
||||
---
|
||||
|
||||
# How to add a form to a project (Windows Forms .NET)
|
||||
|
||||
Add forms to your project with Visual Studio. When your app has multiple forms, you can choose which is the startup form for your app, and you can display multiple forms at the same time.
|
||||
|
||||
[!INCLUDE [desktop guide under construction](../../includes/desktop-guide-preview-note.md)]
|
||||
|
||||
## Add a new form
|
||||
|
||||
Add a new form with Visual Studio.
|
||||
|
||||
01. In Visual Studio, find the **Project Explorer** pane. Right-click on the project and choose **Add** > **Form (Windows Forms)**.
|
||||
|
||||
:::image type="content" source="media/how-to-add/right-click.png" alt-text="Right click solution explorer to add new form to windows forms project":::
|
||||
|
||||
01. In the **Name** box, type a name for your form, such as *MyNewForm*. Visual Studio will provide a default and unique name that you may use.
|
||||
|
||||
:::image type="content" source="media/how-to-add/new-form-dialog.png" alt-text="Add item dialog in visual studio for windows forms":::
|
||||
|
||||
Once the form has been added, Visual Studio opens the form designer for the form.
|
||||
|
||||
## Add a project reference to a form
|
||||
|
||||
If you have the source files to a form, you can add the form to your project by copying the files into the same folder as your project. The project automatically references any code files that are in the same folder or child folder of your project.
|
||||
|
||||
Forms are made up of two files that share the same name: _form2.cs_ (_form2_ being an example of a file name) and _form2.Designer.cs_. Sometimes a resource file exists, sharing the same name, _form2.resx_. In in the previous example, _form2_ represents the base file name. You'll want to copy all related files to your project folder.
|
||||
|
||||
Alternatively, you can use Visual Studio to import a file into your project. When you add an existing file to your project, the file is copied into the same folder as your project.
|
||||
|
||||
01. In Visual Studio, find the **Project Explorer** pane. Right-click on the project and choose **Add** > **Existing Item**.
|
||||
|
||||
:::image type="content" source="media/how-to-add/existing-right-click.png" alt-text="Right click solution explorer to add existing form to windows forms project":::
|
||||
|
||||
02. Navigate to the folder containing your form files.
|
||||
|
||||
03. Select the _form2.cs_ file, where _form2_ is the base file name of the related form files. Don't select the other files, such as _form2.Designer.cs_.
|
||||
|
||||
## See also
|
||||
|
||||
- [How to position and size a form (Windows Forms .NET)](how-to-position-and-resize.md)
|
||||
- [Events overview (Windows Forms .NET)](events.md)
|
||||
- [Position and layout of controls (Windows Forms .NET)](../controls/layout.md)
|
||||
@@ -0,0 +1,156 @@
|
||||
---
|
||||
title: "Position and resize a form"
|
||||
description: "Learn how to set the size and position of a form in .NET Windows Forms and Visual Studio. The size and location can either be set in the Visual Studio designer or through code."
|
||||
ms.date: 10/26/2020
|
||||
dev_langs:
|
||||
- "csharp"
|
||||
- "vb"
|
||||
helpviewer_keywords:
|
||||
- "positioning Windows Forms"
|
||||
- "resizing Windows Forms"
|
||||
- "Windows Forms, location"
|
||||
- "Windows Forms, size"
|
||||
---
|
||||
|
||||
# How to position and size a form (Windows Forms .NET)
|
||||
|
||||
When a form is created, the size and location is initially set to a default value. The default size of a form is generally a width and height of _800x500_ pixels. The initial location, when the form is displayed, depends on a few different settings.
|
||||
|
||||
You can change the size of a form at design time with Visual Studio, and at run time with code.
|
||||
|
||||
[!INCLUDE [desktop guide under construction](../../includes/desktop-guide-preview-note.md)]
|
||||
|
||||
## Resize with the designer
|
||||
|
||||
After [adding a new form](how-to-add.md) to the project, the size of a form is set in two different ways. First, you can set it is with the size grips in the designer. By dragging either the right edge, bottom edge, or the corner, you can resize the form.
|
||||
|
||||
:::image type="content" source="media/how-to-position-and-resize/designer-grips.png" alt-text="Right click solution explorer to add new form to windows forms project with grips":::
|
||||
|
||||
The second way you can resize the form while the designer is open, is through the properties pane. Select the form, then find the **Properties** pane in Visual Studio. Scroll down to **size** and expand it. You can set the **Width** and **Height** manually.
|
||||
|
||||
:::image type="content" source="media/how-to-position-and-resize/designer-properties-size.png" alt-text="Right click solution explorer to add new form to windows forms project":::
|
||||
|
||||
## Resize in code
|
||||
|
||||
Even though the designer sets the starting size of a form, you can resize it through code. Using code to resize a form is useful when something about your application determines that the default size of the form is insufficient.
|
||||
|
||||
To resize a form, change the <xref:System.Windows.Forms.Form.Size%2A>, which represents the width and height of the form.
|
||||
|
||||
### Resize the current form
|
||||
|
||||
You can change the size of the current form as long as the code is running within the context of the form. For example, if you have `Form1` with a button on it, that when clicked invokes the `Click` event handler to resize the form:
|
||||
|
||||
```csharp
|
||||
private void button1_Click(object sender, EventArgs e) =>
|
||||
Size = new Size(250, 200);
|
||||
```
|
||||
|
||||
```vb
|
||||
Private Sub Button1_Click(sender As Object, e As EventArgs)
|
||||
Size = New Drawing.Size(250, 200)
|
||||
End Sub
|
||||
```
|
||||
|
||||
### Resize a different form
|
||||
|
||||
You can change the size of another form after it's created by using the variable referencing the form. For example, let's say you have two forms, `Form1` (the startup form in this example) and `Form2`. `Form1` has a button that when clicked, invokes the `Click` event. The handler of this event creates a new instance of the `Form2` form, sets the size, and then displays it:
|
||||
|
||||
```csharp
|
||||
private void button1_Click(object sender, EventArgs e)
|
||||
{
|
||||
Form2 form = new Form2();
|
||||
form.Size = new Size(250, 200);
|
||||
form.Show();
|
||||
}
|
||||
```
|
||||
|
||||
```vb
|
||||
Private Sub Button1_Click(sender As Object, e As EventArgs)
|
||||
Dim form = New Form2 With {
|
||||
.Size = New Drawing.Size(250, 200)
|
||||
}
|
||||
form.Show()
|
||||
End Sub
|
||||
```
|
||||
|
||||
If the `Size` isn't manually set, the form's default size is what it was set to during design-time.
|
||||
|
||||
## Position with the designer
|
||||
|
||||
When a form instance is created and displayed, the initial location of the form is determined by the <xref:System.Windows.Forms.Form.StartPosition%2A> property. The <xref:System.Windows.Forms.Form.Location%2A> property holds the current location the form. Both properties can be set through the designer.
|
||||
|
||||
:::image type="content" source="media/how-to-position-and-resize/startposition.png" alt-text="visual studio properties pane with start position highlighted":::
|
||||
|
||||
| FormStartPosition Enum | Description |
|
||||
|------------------------|------------------------------------------------------------------------------------------------------------------|
|
||||
| CenterParent | The form is centered within the bounds of its parent form. |
|
||||
| CenterScreen | The form is centered on the current display. |
|
||||
| Manual | The position of the form is determined by the [Location](xref:System.Windows.Forms.Form.Location%2A) property. |
|
||||
| WindowsDefaultBounds | The form is positioned at the Windows default location and is resized to the default size determined by Windows. |
|
||||
| WindowsDefaultLocation | The form is positioned at the Windows default location and isn't resized. |
|
||||
|
||||
The [CenterParent](xref:System.Windows.Forms.FormStartPosition.CenterParent) value only works with forms that are either a multiple document interface (MDI) child form, or a normal form that is displayed with the <xref:System.Windows.Window.ShowDialog%2A> method. `CenterParent` has no affect on a normal form that is displayed with the <xref:System.Windows.Window.Show%2A> method. To center a form (`form` variable) to another form (`parentForm` variable), use the following code:
|
||||
|
||||
```csharp
|
||||
form.StartPosition = FormStartPosition.Manual;
|
||||
form.Location = new Point(parentForm.Width / 2 - form.Width / 2 + parentForm.Location.X,
|
||||
parentForm.Height / 2 - form.Height / 2 + parentForm.Location.Y);
|
||||
form.Show();
|
||||
```
|
||||
|
||||
```vb
|
||||
form.StartPosition = Windows.Forms.FormStartPosition.CenterParent.Manual
|
||||
form.Location = New Drawing.Point(parentForm.Width / 2 - form.Width / 2 + parentForm.Location.X,
|
||||
parentForm.Height / 2 - form.Height / 2 + parentForm.Location.Y)
|
||||
|
||||
form.Show()
|
||||
```
|
||||
|
||||
## Position with code
|
||||
|
||||
Even though the designer can be used to set the starting location of a form, you can use code either change the starting position mode or set the location manually. Using code to position a form is useful if you need to manually position and size a form in relation to the screen or other forms.
|
||||
|
||||
### Move the current form
|
||||
|
||||
You can move the current form as long as the code is running within the context of the form. For example, if you have `Form1` with a button on it, that when clicked invokes the `Click` event handler. The handler in this example changes the location of the form to the top-left of the screen by setting the <xref:System.Windows.Forms.Form.Location%2A> property:
|
||||
|
||||
```csharp
|
||||
private void button1_Click(object sender, EventArgs e) =>
|
||||
Location = new Point(0, 0);
|
||||
```
|
||||
|
||||
```vb
|
||||
Private Sub Button1_Click(sender As Object, e As EventArgs)
|
||||
Location = New Drawing.Point(0, 0)
|
||||
End Sub
|
||||
```
|
||||
|
||||
### Position a different form
|
||||
|
||||
You can change the location of another form after it's created by using the variable referencing the form. For example, let's say you have two forms, `Form1` (the startup form in this example) and `Form2`. `Form1` has a button that when clicked, invokes the `Click` event. The handler of this event creates a new instance of the `Form2` form and sets the size:
|
||||
|
||||
```csharp
|
||||
private void button1_Click(object sender, EventArgs e)
|
||||
{
|
||||
Form2 form = new Form2();
|
||||
form.Size = new Size(250, 200);
|
||||
form.Show();
|
||||
}
|
||||
```
|
||||
|
||||
```vb
|
||||
Private Sub Button1_Click(sender As Object, e As EventArgs)
|
||||
Dim form = New Form2 With {
|
||||
.Size = New Drawing.Size(250, 200)
|
||||
}
|
||||
form.Show()
|
||||
End Sub
|
||||
```
|
||||
|
||||
If the `Size` isn't set, the form's default size is what it was set to at design-time.
|
||||
|
||||
## See also
|
||||
|
||||
- [How to add a form to a project (Windows Forms .NET)](how-to-add.md)
|
||||
- [Events overview (Windows Forms .NET)](events.md)
|
||||
- [Position and layout of controls (Windows Forms .NET)](../controls/layout.md)
|
||||
Binary file not shown.
Binary file not shown.
|
After Width: | Height: | Size: 50 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 32 KiB |
Binary file not shown.
Binary file not shown.
|
After Width: | Height: | Size: 50 KiB |
BIN
Binary file not shown.
|
After Width: | Height: | Size: 12 KiB |
BIN
Binary file not shown.
|
After Width: | Height: | Size: 15 KiB |
BIN
Binary file not shown.
|
After Width: | Height: | Size: 11 KiB |
Reference in New Issue
Block a user