Form Features

Overview

This article mainly introduces how to use WinFormium's form Formium class and its form-related contents. The browser-related content in the Formium class will be introduced in Browser Features.

Create form

You can inherit from the Formium class to create and set form properties.

using WinFormium;

class MyWindow : Formium
{
     publicMyWindow()
     {
         Url = "https://www.bing.com/"
     }
}

Using the above code you can create a simple form. Specifying the value of the Url property of the Formium class can specify the page that the form loads by default. This property accepts a string type parameter, and you can specify a web page address here. Just like the sample code above, it will load the https://www.bing.com/ web page after the form is displayed.

Set form style

Formium forms have a variety of built-in form styles. You can overload the ConfigureWindowStyle method of the Formium class to set the form style. The ConfigureWindowStyle method accepts a parameter WindowStyleBuilder with which you can set the style of the form.

protected override FormStyle ConfigureWindowStyle(WindowStyleBuilder builder)
{
     var style = builder.UseSystemForm();
     return style
}

The above code example uses the system form style, which is also the default Formium form style. If your application has no special requirements for window styles, then there is no need to overload the ConfigureWindowStyle method.

The WindowStyleBuilder object provides multiple UseXXX methods to set different form styles. These methods return a FormStyle subclass. In addition to the style settings provided in the base class FormStyle, different form styles also Provides properties specific to this style. You can set properties of the FormStyle class to set the base style of a form, and use its subclasses to set unique style properties.

The following properties are provided in the FormStyle object:

Properties	Description	Type	Default Value
AllowFullScreen	Whether to allow full screen	bool	true
AllowSystemMenu	Whether to allow system menu	bool	true
ColorMode	Form color mode, property value: SystemPreference - Follow the system (Windows 11) Light - Light mode Dark - Dark mode	FormiumColorMode	FormiumColorMode. SystemPreference
DefaultAppTitle	Default form title	string	WinFormium
Icon	Form Icon	Icon	DefaultIcon
Location	Form location	Point	Point.Empty
Maximizable	Whether to allow maximization	bool	true
MaximiumSize	The maximum size of the form	Size	Size.Empty
Minimizable	Whether to allow minimization	bool	true
MinimiumSize	The minimum size of the form	Size	Size.Empty
ShowInTaskbar	Whether to display in the taskbar	bool	true
Sizable	Whether to allow resizing of the form	bool	true
Size	Form size	Size	Size.Empty
StartCentered	Whether and how the form is centered, property value: None - not centered CenterScreen - in the center of the screen CenterParent - in the parent form Centered	StartCenteredMode	StartCenteredMode.None
TopMost	Whether the form is displayed on top	bool	false
UsePageTitle	Whether to use the web page title as the form title	bool	false
WindowState	Form state, property value: Normal - normal Maximized - maximized Minimized - minimized FullScreen - full screen	FormWindowState	FormWindowState.Normal

Currently, WinFormium forms have the following built-in form styles. If you need to know about these form styles, please refer to the following articles:

• System Style Forms
• KIOSK Style Forms
• Borderless Style Forms
• Transparency Style Forms
• Control Style

The form style set using the FormStyle object is read-only. These settings will take effect when the form is created. After the form creation is completed, you will not be able to modify the form style through FormStyle again. The Formium class itself provides some properties that you can use to modify the form style after the form is created.

Show form

When you have finished setting up your Formium form, you can use the Show method of the Formium class to display the form, or use the ShowDialog method to display the form modally.

If you need to use the current Formium form as the main form of the project, please refer to Startup Configuration - Configure the main form of the application".

Hide form

You can use the Hide() method to hide the current form. After hiding the form, you can use the Show() method to redisplay the form. However, in order to ensure that the form can be hidden and displayed normally, it is strongly recommended that you set the property value of the Visible property of Formium to hide and display the form.

Close the form

You can use the Close() method to close the current form. After closing the form, the form object will be destroyed and you will not be able to display the form again. If you need to display the form here, you need to create a new form object.

Activate the form

You can use the Activate() method to activate the current form. After activating the form, the form will be brought to the front and the form title bar will be displayed as activated.

Set form focus

You can use the Focus() method to set the focus of the current form. After setting the focus, the form will become the focused form. If the form is a child form, its parent form will lose focus.

Center the form

You can center the form using the CenterToScreen() method, which will center the form on the screen. If your form is a child form, you can use the CenterToParent() method to center the form on the parent form.

Update interface elements in the UI thread

In the process of using WinFormium forms, you will find a large number of asynchronous methods. These asynchronous methods run in different threads from the UI thread. If you want to operate the form in these non-UI threads, then you need to use the InvokeOnUIThread method to update interface elements in the UI thread. There are multiple overloads of this method:

Method	Description
void InvokeOnUIThread(System.Action action)	Execute a delegate in the UI thread
object InvokeOnUIThread(System.Delegate method, params object[] args)	Execute a delegate with a parameter list and return value in the UI thread
T InvokeOnUIThread<T>(System.Delegate method, params object[] args)	Execute a delegate with a parameter list and a generic return value in the UI thread
T InvokeOnUIThread<T>(System.Func<T> method)	Execute a delegate with a generic return value in the UI thread

For example, to create and display a subform in the UI thread, you can use the following code:

InvokeOnUIThread(() =>
{
     //Execute a delegate in the UI thread
     var form = new Form();
     form.Show(this);
});

Forms created using the InvokeOnUIThread method will be displayed in the UI thread, which can avoid exceptions caused by displaying the form in non-UI threads. Likewise, if you need to modify the form's properties at runtime, you also need to use the InvokeOnUIThread method to update the form properties.

Parent form

You can use the Owner property to get the parent form of the current form. If the current form has no parent form, the value of this property is null. This property does not return an actual Form object, but an IWin32Window interface. You can obtain the handle of the parent form through the Handle property of this interface, or directly use this interface to connect to certain APIs of WinForm, such as the MessageBox.Show method.

Window size and position

You can set the location of the current form using the Location property, which accepts a parameter of type Point where you can specify the location of the form. If you need to get the location of a form, you can use the Location property to get the location of the form. You can also use the Top and Left properties to set or get the position of the form on the current desktop. In addition, you can also use the Right and Bottom properties to get the position of the right and bottom borders of the form. .

You can set the size of the current form using the Size property, which accepts a parameter of type Size where you can specify the size of the form. If you need to get the size of the form, you can use the Size property to get the size of the form. You can also use the Width and Height properties to set or get the width and height of the form.

In addition, you can use the Bounds property to obtain an object of type Rectangle, and you can obtain the position and size of the form through the properties of the object.

You can also set the maximum and minimum size of the form using the MaximiumSize and MinimiumSize properties, which accept a parameter of type Size where you can specify the maximum and minimum size of the form.

Form title

You can use the AppTitle property to set the title of the current form. This property accepts a string type parameter, where you can specify the title of the form. If you need to get the title of the form, you can get the title of the form through the Title property.

In addition, if the property value of the UsePageTitle property is true, then the title of the form will be spliced using the title of the current web page and the value of the AppTitle property. The default splicing method is PageTitle - AppTitle. You can change the TitlePattern property to set the splicing format of the title string. This property accepts a string type parameter, and you can specify the splicing format here.

Form icon

You can use the Icon property to set the icon of the current form. This property accepts a parameter of type Icon, where you can specify the icon of the form. If you need to get the icon of the form, you can get the icon of the form through the Icon property.

Form status

You can set the state of the current form using the WindowState property, which accepts a parameter of type FormWindowState where you can specify the state of the form. If you need to get the state of the form, you can get the state of the form through the WindowState property. The property values of the FormWindowState type are as follows:

Property value	Description
Normal	Normal
Maximized	Maximized
Minimized	Minimized
FullScreen	Full screen

Additionally, you can specify the AllowFullScreen property to set whether to allow the form to go full screen. Use the Minimizable and Maximizable properties to set whether to allow the window to be minimized and maximized. Specify the Sizable property to set whether resizing of the form is allowed.

In addition to the above properties and methods, the form state also involves a lot of front-end content. Therefore, for details about the WinFormium form state, please refer to [Form JavaScript Guide] (./Form JavaScript Guide.md).

Splash screen

You can use the EnableSplashScreen property to set whether to enable a form's splash screen. If you need to display a splash screen before the form is displayed, you can set the EnableSplashScreen property to true in the form constructor. The splash screen will be displayed before the form page is loaded. When the form is displayed, the splash screen will automatically close.

You can customize a form's splash screen by overriding the PaintSplashScreen method of the Formium class. This method accepts a parameter of type Graphics where you can draw your splash screen.

The splash screen is only applicable to forms that do not have CEF off-screen rendering turned on. Forms with CEF off-screen rendering turned on will not display the splash screen.

By default, the following splash screen will be displayed:

Overload the PaintSplashScreen method and delete the base.PaintSplashScreen(e); code to delete the default splash screen. Then use GDI+ code to customize the splash screen:

protected override void PaintSplashScreen(PaintEventArgs e)
{
     e.Graphics.Clear(Color.Yellow);
     e.Graphics.DrawString("Loading...", SystemFonts.DefaultFont, Brushes.Black, 10, 10);
}

API Reference

Attributes

Property name	Description	Type	Default value
AllowDrop	Gets or sets a value that indicates whether the control can accept data dragged and dropped onto it by the user.	bool	false
AllowFullScreen	Gets or sets a value indicating whether the form allows full screen.	bool	true
AllowSystemMenu	Gets or sets a value indicating whether the form allows system menus.	bool	true
ApplicationContext	Gets or sets the application context.	ApplicationContext	WinFormiumApp
AppTitle	Gets or sets the title of the form.	string	WinFormium
Bottom	Gets the position of the bottom border of the form.	int	0
Bounds	Get the position and size of the form.	Rectangle	Rectangle.Empty
ColorMode	Gets or sets the color mode of the form.	FormiumColorMode	FormiumColorMode.SystemPreference
DisableAboutMenu	Gets or sets a value indicating whether the form's About menu is disabled.	bool	false
Enabled	Gets or sets a value that indicates whether the control can respond to user interaction.	bool	true
EnableSplashScreen	Gets or sets a value that indicates whether to enable the form's splash screen.	bool	true
Handle	Get the handle of the form.	IntPtr	IntPtr.Zero
Height	Gets or sets the height of the form.	int	0
Icon	Gets or sets the icon of the form.	Icon	DefaultIcon
IsDisposed	Gets a value indicating whether the form has been released.	bool	false
IsFullscreen	Gets a value indicating whether the form is in full screen state.	bool	false
Left	Gets or sets the position of the left border of the form.	int	0
Location	Gets or sets the location of the form.	Point	Point.Empty
Maximizable	Gets or sets a value indicating whether the form allows maximization.	bool	true
MaximiumSize	Gets or sets the maximum size of the form.	Size	Size.Empty
Minimizable	Gets or sets a value indicating whether the form allows minimization.	bool	true
MinimiumSize	Gets or sets the minimum size of the form.	Size	Size.Empty
Modal	Gets a value indicating whether the form is displayed modally.	bool	false
Owner	Gets the handle of the parent form of the current form.	IWin32Window	null
Right	Gets the position of the right border of the form.	int	0
Services	Gets the form's services container.	IServiceProvider	null
Sizable	Gets or sets a value indicating whether the form allows resizing.	bool	true
Size	Gets or sets the size of the form.	Size	Size.Empty
TitlePattern	Gets or sets the splicing format of the form title.	string	{0} - {1}
Top	Gets or sets the position of the top border of the form.	int	0
TopMost	Gets or sets a value indicating whether the form is displayed on top.	bool	false
UsePageTitle	Gets or sets a value that indicates whether the form uses the page title as the form title.	bool	false
Visible	Gets or sets a value indicating whether the form is visible.	bool	true
Width	Gets or sets the width of the form.	int	0
WindowState	Gets or sets the state of the form.	FormWindowState	FormWindowState.Normal

Methods

Method name	Description	Return value
Activate()	Activate the form.	void
CenterToParent()	Center the form on the parent form.	void
CenterToScreen()	Center the form on the screen.	void
Close()	Close the form.	void
ConfigureWindowStyle(WindowStyleBuilder builder)	Configure the form style.	FormStyle
Dispose()	Disposes the form.	void
Focus()	Sets the form focus.	void
Hide()	Hide the form.	void
InvokeOnUIThread(System.Action action)	Execute a delegate in the UI thread.	void
InvokeOnUIThread(System.Delegate method, params object[] args)	Execute a delegate with a parameter list and return value in the UI thread.	object
InvokeOnUIThread<T>(System.Delegate method, params object[] args)	Execute a delegate with a parameter list and a generic return value in the UI thread.	T
InvokeOnUIThread<T>(System.Func<T> method)	Execute a delegate with a generic return value in the UI thread.	T
Show()	Display the form.	void
Show(System.IntPtr)	Display the form with the specified handle as the parent form.	void
Show(System.Windows.Forms.IWin32Window)	Display the form with the specified handle as the parent form.	void
Show(WinFormium.Formium)	Display the form with the specified handle as the parent form.	void
ShowAboutDialog()	Displays the form's About dialog box.	void
ShowDialog()	Display the form modally and return DialogResult	DialogResult
ShowDialog(System.IntPtr)	Display the form modally and use the specified handle as the parent form.	DialogResult
ShowDialog(System.Windows.Forms.IWin32Window)	Display the form modally and use the specified handle as the parent form.	DialogResult
ShowDialog(WinFormium.Formium)	Display the form modally and use the specified handle as the parent form.	DialogResult

Events

Event name	Description	Parameters
Activated	Occurs when the form is activated.	System.EventArgs
Closing	Occurs when the form is closed.	System.ComponentModel.CancelEventArgs
Closed	Occurs when the form is closed.	System.EventArgs
Deactive	Occurs when a form loses focus.	System.EventArgs
GotFocus	Occurs when a form gains focus.	System.EventArgs
Loaded	Occurs when the form has finished loading.	System.EventArgs
Move	Occurs when the form moves.	System.EventArgs
Resize	Occurs when the form size changes.	System.EventArgs
ResizeBegin	Occurs when the form begins to resize.	System.EventArgs
ResizeEnd	Occurs when the form ends resizing.	System.EventArgs
Shown	Occurs when the form is shown.	System.EventArgs
VisibleChanged	Occurs when the form's visibility changes.	System.EventArgs
WindowStateChanged	Occurs when the form state changes.	System.EventArgs

See also

• Forms
• Browser Features
• Form JavaScript Guide