Form

Namespace: Wisej.Web

Assembly: Wisej.Framework (3.5.0.0)

• Control
  • ScrollableControl
    • ContainerControl
      • Form

Represents a window or dialog box that makes up an application's user interface.

C#

public class Form : ContainerControl, IWisejWindow

VB.NET

Public Class Form
    Inherits ContainerControl
    Implements IWisejWindow

Constructors

Form()

Default constructor.

Form(onClosed)

Initializes a new instance of the Form class with the specified initial settings.

Name	Type	Description
onClosed	Action<Object, EventArgs>	Handler for the Closed event.

Form(controls, onClosed)

Initializes a new instance of the Form class with the specified initial settings.

Name	Type	Description
controls	Control[]	An array of Control objects to be added to the form.
onClosed	Action<Object, EventArgs>	Handler for the Closed event.

Form(location, size, controls)

Initializes a new instance of the Form class with the specified initial settings.

Name	Type	Description
location	Point	The location of the form on the screen.
size	Size	The size of the form.
controls	Control[]	An array of Control objects to be added to the form.

Form(location, size, onClosed)

Initializes a new instance of the Form class with the specified initial settings.

Name	Type	Description
location	Point	The location of the form on the screen.
size	Size	The size of the form.
onClosed	Action<Object, EventArgs>	Handler for the Closed event.

Form(location, size, controls, onClosed)

Initializes a new instance of the Form class with the specified initial settings.

Name	Type	Description
location	Point	The location of the form on the screen.
size	Size	The size of the form.
controls	Control[]	An array of Control objects to be added to the form.
onClosed	Action<Object, EventArgs>	Handler for the Closed event.

Properties

AcceptButton

IButtonControl: Returns or sets the button on the form that is clicked when the user presses the ENTER key. (Default: null)

Assigning the AcceptButton doesn't automatically close the window when the button is pressed. It only assigns the value of the DialogResult property of the form to the value of the DialogResult property of the button. To close the form when the AcceptButton is clicked, you have to call the Close method when the button is pushed.

Active

Boolean: Returns whether the form is the currently active top level window or the active mdi child window.

ActiveForm

Form: Returns the currently active form for this application.

ActiveMdiChild

Form: Returns the currently active multiple-document interface (MDI) child window.

AllowTransparency

Boolean: Returns or sets whether the opacity of the form can be adjusted.

AppearanceKey

String: Sets the appearance key for the theme engine. (Default: null)

AutoClose

Boolean: Automatically closes the form or dialog when the user clicks anywhere on the browser outside of the form. (Default: False)

AutoCloseModalDialog

Boolean: EXPERIMENTAL: Automatically closes the Modal dialog when DialogResult is assigned to a value different than None by code or by a user action, i.e.: AcceptButton click. Since 3.5.6 (Default: False)

You can change the default value across the application using the AutoCloseModalDialogDefault property or related AppContext switch. The default WinForms behavior is to automatically close the modal dialog.

AutoCloseModalDialogDefault

Boolean: EXPERIMENTAL: Default value for the AutoCloseModalDialog property. Since 3.5.6 (Default: False)

The default is false. You can set the value by code or using AppContext switches: AppContext.SetSwitch("FormAutoCloseModalDialog", true);

AutoSize

Boolean: Returns or sets a value that indicates whether the control resizes based on its contents. (Default: False)

AutoSizeMode

AutoSizeMode: Indicates the automatic sizing behavior of the control. (Default: GrowOnly)

AutoValidate

AutoValidate: Returns or sets how the control performs validation when the user changes focus to another control.

CancelButton

IButtonControl: Returns or sets the button control that is clicked when the user presses the ESC key. (Default: null)

Assigning the CancelButton doesn't automatically close the window when the button is pressed. It only assigns the value of the DialogResult property of the form to the value of the DialogResult property of the button. To close the form when the CancelButton is clicked, you have to call the Close method when the button is pushed.

ClientSize

Size: Returns or sets the size of the client area of the form.

CloseBox

Boolean: Returns or sets whether the Close button is displayed in the caption bar of the form. (Default: True)

CloseReason

CloseReason: Returns the reason for the form closing.

ControlBox

Boolean: Returns or sets whether a control box is displayed in the caption bar of the form. (Default: True)

DialogResult

DialogResult: Returns or sets the dialog result for the form.

DisableMergedMenu

Boolean: Enables or disables merging the MdiParent's menu with the active MdiChild form's menu. (Default: False)

FormBorderStyle

FormBorderStyle: Returns or sets the border style of the form. (Default: Sizable)

HasMdiChildren

Boolean: Returns whether this form is an IsMdiContainer and has any Mdi child form.

HasOwnedForms

Boolean: Returns whether this form has any owned form.

HeaderBackColor

Color: Returns or sets the background color of the title bar and frame of the window.

HeaderForeColor

Color: Returns or sets the text color of the title bar of the window.

Icon

Image: Returns or sets the icon (32x32) for the Form.

IconLarge

Image: Returns or sets the large icon (128x128) for the Form.

IconLargeSource

String: Returns or sets the theme name or URL for the large icon to display for the Form.

IconSource

String: Returns or sets the theme name or URL for the icon to display for the Form.

IsClosed

Boolean: Returns whether the Form has been closed.

Modal dialogs are reusable and are not disposed automatically when closed. Use this property to check whether a modal dialog has been closed, and use IsDisposed to check if it has been disposed.

IsDialog

Boolean: Returns whether the Form was created as a modal or modeless dialog using ShowDialog.

IsMdiChild

Boolean: Returns a value indicating whether the form is a multiple-document interface (MDI) child form.

IsMdiContainer

Boolean: Returns or sets whether the form is a container for multiple-document interface (MDI) child forms. (Default: False)

KeepCentered

Boolean: Keeps the form always centered in the browser. (Default: False)

KeepOnScreen

Boolean: Keeps the entire form within the browser view preventing the user from dragging the form, even partially, outside of the view. (Default: False)

LiveResize

Boolean: Returns or sets whether the form is resized while the border is being dragged. (Default: False)

MaximizeBox

Boolean: Returns or sets whether the Maximize button is displayed in the caption bar of the form. (Default: True)

MaximumSize

Size: Returns the maximum size the form can be resized to. (Default: {Width=0, Height=0})

Throws:

• ArgumentOutOfRangeException The values of the height or width within the Size object are less than zero.

MdiChildren

Form[]: Returns an array of forms that represent the multiple-document interface (MDI) child forms that are parented to this form.

MdiClient

MdiClient: Returns the internal MdiClient component.

MdiParent

Form: Returns or sets the current multiple-document interface (MDI) parent form of this form.

Throws:

• Exception The Form assigned to this property is not marked as an MDI container.

MdiTabProperties

MdiTabProperties: Provides properties for the TabControl object used to display the tabbed MDI interface.

Menu

MainMenu: Returns or sets the MainMenu that is displayed in the form. (Default: null)

MergedMenu

MainMenu: Returns the merged menu for the form.

MinimizeBox

Boolean: Returns or sets whether the Minimize button is displayed in the caption bar of the form. (Default: True)

MinimumSize

Size: Returns or sets the minimum size the form can be resized to.

Throws:

• ArgumentOutOfRangeException The values of the height or width within the Size object are less than zero.

Modal

Boolean: Returns whether this form is displayed modally.

Movable

Boolean: Returns or sets whether the form can be moved by dragging.

Opacity

Double: Returns or sets the opacity level of the form. (Default: 1)

OwnedForms

Form[]: Returns an array of Form objects that represent all forms that are owned by this form.

Owner

Form: Returns or sets the form that owns this form.

Throws:

• Exception A top-level window cannot have an owner.

ShowInTaskbar

Boolean: Returns or sets whether the form is displayed in the Desktop taskbar. (Default: True)

ShowModalMask

Boolean: Returns or sets a value that shows the modal mask on the client when this form is displayed. (Default: False)

Modal forms - forms opened using ShowDialog - always show the modal mask by default.

Size

Size: Returns or sets the size of the form.

StartPosition

FormStartPosition: Returns or sets the starting position of the form at run time. (Default: DefaultLocation)

Text

String: Returns or sets the title of the Form window. (Default: "")

Tools

ComponentToolCollection: Returns the instance of ComponentToolCollection associated with this control.

TopLevel

Boolean: Returns or sets whether to display the form as a top-level window.

Throws:

• Exception A Multiple-document interface (MDI) parent form must be a top-level window.

TopMost

Boolean: Returns or sets whether the form should be displayed as a topmost form. (Default: False)

WindowState

FormWindowState: Returns or sets a value that indicates whether form is minimized, maximized, or normal. (Default: Normal)

Methods

Activate()

Activates the form and gives it focus.

AddOwnedForm(ownedForm)

Adds an owned form to this form.

Parameter	Type	Description
ownedForm	Form	The Form that this form will own.

Close()

Closes the form.

PointToClient(point)

Computes the location of the specified screen point into client coordinates.

Parameter	Type	Description
point	Point	The screen coordinate Point to convert.

Returns: Point. A Point that represents the converted Point, point , in client coordinates.

PointToScreen(point)

Computes the location of the specified client point into screen coordinates.

Parameter	Type	Description
point	Point	The client coordinate Point to convert.

Returns: Point. A Point that represents the converted Point, point , in screen coordinates.

Refresh(refreshChildren)

Forces the control to update the corresponding client widget. When in DesignMode it forces a full redraw of the designer surface for this control and optionally of its children, including the non-client areas such as the caption of forms or panels.

Parameter	Type	Description
refreshChildren	Boolean	True to also refresh all the children of this control.

RemoveOwnedForm(ownedForm)

Removes an owned form from this form.

Parameter	Type	Description
ownedForm	Form	A Form representing the form to remove from the list of owned forms for this form.

Show(onclose)

Shows the form to the user.

Parameter	Type	Description
onclose	Action<Form, DialogResult>	Optional async handler for the close event; called when the form/dialog has been closed. It's the equivalent of handling the event.

Forms are disposed immediately when they are closed and cannot be shown again. The optional onclose parameter is an asynchronous callback handler invoked when the form is closed. It is similar to handling the FormClosed event.

form.Show((sender, result) => {
  
  // this code is executed when the form is closed.
  // sender is a reference to the form being closed.
  // result contains the value of form.DialogResult.
});

Throws:

• InvalidOperationException The form being shown is already visible; or the form being shown is not a top-level window; or the form being shown as a dialog box is already a modal form.

Show(owner, onclose)

Shows the form with the specified owner to the user.

Parameter	Type	Description
owner	Form	A Form that is related to this instance. This form is added to the OwnedForms collection of the owner form.
onclose	Action<Form, DialogResult>	Optional async handler for the close event; called when the form/dialog has been closed. It's the equivalent of handling the event.

Forms are disposed immediately when they are closed and cannot be shown again. The optional onclose parameter is an asynchronous callback handler invoked when the form is closed. It is similar to handling the FormClosed event.

form.Show((sender, result) => {
  
  // this code is executed when the form is closed.
  // sender is a reference to the form being closed.
  // result contains the value of form.DialogResult.
});

Throws:

• InvalidOperationException The form being shown is already visible; or The form specified in the owner parameter is the same as the form being shown; or the form being shown is disabled; or the form being shown is not a top-level window; or the form being shown as a dialog box is already a modal form.

ShowDialog(onclose)

Shows the form as a modal dialog box. When the onclose is specified, the dialog is modal only in the browser.

Parameter	Type	Description
onclose	Action<Form, DialogResult>	Optional async handler for the close event; called when the form/dialog has been closed. It's the equivalent of handling the event.

Returns: DialogResult. One of the DialogResult values.

When using ShowDialog, the dialog instance is not automatically disposed when the dialog is closed because dialogs are reusable. To make sure that memory is released properly, you must dispose the instance in your code or use the typical using pattern. Dialogs that are closed, but not disposed and not referenced by the application will be disposed by the Garbage Collector when it kicks in.

using (var dialog and new MyDialog())
{
  dialog.ShowDialog();
}

Modal dialogs suspend the code execution on the server side effectively replicating the full modal workflow employed by desktop applications. However, when the optional onclose parameter is specified, the dialog is modal only in the browser and doesn't suspend the server thread. Which is similar to the typical asynchronous modal pattern used in javascript.

dialog.ShowDialog((sender, result) => {
  
  // this code is executed when the dialog is closed.
  // sender is a reference to the dialog being closed.
  // result contains the value of dialog.DialogResult.
  
  // you may dispose it here:
  sender.Dispose();
});

// this code is executed immediately, unlike the real modal workflow.

Throws:

• InvalidOperationException The form being shown is already visible; or the form being shown is disabled; or the form being shown is not a top-level window; or the form being shown as a dialog box is already a modal form.

ShowDialog(owner, onclose)

Shows the form as a modal dialog box with the specified owner. When the onclose is specified, the dialog is modal only in the browser.

Parameter	Type	Description
owner	Form	A Form that is related to this instance. This form is added to the OwnedForms collection of the owner form.
onclose	Action<Form, DialogResult>	Optional async handler for the close event; called when the form/dialog has been closed. It's the equivalent of handling the event. When the onclose event handler is specified, the modal dialog doesn't suspend the execution on the server but it's still shown as a modal dialog on the client.

Returns: DialogResult. One of the DialogResult values.

When using ShowDialog, the dialog instance is not automatically disposed when the dialog is closed because dialogs are reusable. To make sure that memory is released properly, you must dispose the instance in your code or use the typical using pattern. Dialogs that are closed, but not disposed and not referenced by the application will be disposed by the Garbage Collector when it kicks in.

using (var dialog and new MyDialog())
{
  dialog.ShowDialog();
}

Modal dialogs suspend the code execution on the server side effectively replicating the full modal workflow employed by desktop applications. However, when the optional onclose parameter is specified, the dialog is modal only in the browser and doesn't suspend the server thread. Which is similar to the typical asynchronous modal pattern used in javascript.

dialog.ShowDialog((sender, result) => {
  
  // this code is executed when the dialog is closed.
  // sender is a reference to the dialog being closed.
  // result contains the value of dialog.DialogResult.
  
  // you may dispose it here:
  sender.Dispose();
});

// this code is executed immediately, unlike the real modal workflow.

Throws:

• ArgumentException The form specified in the owner parameter is the same as the form being shown.
• InvalidOperationException The form being shown is already visible; or The form specified in the owner parameter is the same as the form being shown; or the form being shown is disabled; or the form being shown is not a top-level window; or the form being shown as a dialog box is already a modal form.

ShowDialogAsync(owner)

Asynchronously shows the form as an awaitable modal dialog box.

Parameter	Type	Description
owner	Form	An optional Form that is related to this instance. This form is added to the OwnedForms collection of the owner form.

Returns: Task<DialogResult>. An awaitable Task that contains the DialogResult value returned asynchronous when the user closes the modal dialog.

When using ShowDialog, the dialog instance is not automatically disposed when the dialog is closed because dialogs are reusable. To make sure that memory is released properly, you must dispose the instance in your code or use the typical using pattern. Dialogs that are closed, but not disposed and not referenced by the application will be disposed by the Garbage Collector when it kicks in.

using (var dialog and new MyDialog())
{
    var result = await dialog.ShowDialog();
}

Asynchronous Modal dialogs don't suspend the code execution on the server side but can be "awaited" in "async" methods effectively replicating the full modal workflow employed by desktop applications in an asynchronous environment.

private async void button_Click(object sender, EventArgs e)
{
    var result = await dialog.ShowDialog();

    // this code is executed when the dialog is closed.
    // result contains the value of dialog.DialogResult.

    // you may dispose the dialog here:
    dialog.Dispose();
}

Throws:

• InvalidOperationException The form being shown is already visible; or the form being shown is disabled; or the form being shown is not a top-level window; or the form being shown as a dialog box is already a modal form.

Events

Activated

EventHandler Fired when the form is activated in code or by the user.

Deactivate

EventHandler Fired when the form loses focus and is no longer the active form.

FormClosed

FormClosedEventHandler Occurs after the form is closed.

FormClosing

FormClosingEventHandler Occurs before the form is closed.

HelpButtonClicked

EventHandler Fired when the Help button is clicked.

Load

EventHandler Fired before a form is displayed for the first time.

MaximumSizeChanged

EventHandler Fired when the value of the MaximumSize property has changed.

MdiChildActivate

EventHandler Fired when a multiple-document interface (MDI) child form is activated.

MdiChildAdded

ControlEventHandler Fired when a multiple-document interface (MDI) child form is added to the mdi parent.

MdiChildRemoved

ControlEventHandler Fired when a multiple-document interface (MDI) child form is removed from the mdi parent.

MinimumSizeChanged

EventHandler Fired when the value of the MinimumSize property has changed.

Shown

EventHandler Fired whenever the form is first displayed.

ToolClick

ToolClickEventHandler Fired when a ComponentTool is clicked.

WindowStateChanged

EventHandler Fired when the value of the WindowStateChanged property has changed.

Inherited By

Name	Description
FileDialogUI	UI implementation for the FileDialog class.
FolderBrowserDialogUI	UI implementation for the FolderDialog class.

Implements

Name	Description
IBindableComponent	Bindable components implement this interface.
IContainerControl	Provides the functionality for a control to act as a parent for other controls.
IDropTarget	Controls that support drag & drop operations implement this interface.
IWisejComponent	All wisej components implement this interface.
IWisejControl	All wisej controls derived from the Control class must implement this interface.
IWisejWindow	All wisej top-level windows implement this interface.
IWisejSerializable	Allows an object to serialize itself.