Skip to main content
Version: 4.1

Form

Namespace: Wisej.Web

Assembly: Wisej.Framework (4.1.0.0)

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

public class Form : ContainerControl, IWisejWindow

Constructors​

Instance member Form()​

Default constructor.

Instance member Form(onClosed)​

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

NameTypeDescription
onClosedAction<Object, EventArgs>Handler for the Closed event.

Instance member Form(controls, onClosed)​

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

NameTypeDescription
controlsControl[]An array of Control objects to be added to the form.
onClosedAction<Object, EventArgs>Handler for the Closed event.

Instance member Form(location, size, controls)​

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

NameTypeDescription
locationPointThe location of the form on the screen.
sizeSizeThe size of the form.
controlsControl[]An array of Control objects to be added to the form.

Instance member Form(location, size, onClosed)​

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

NameTypeDescription
locationPointThe location of the form on the screen.
sizeSizeThe size of the form.
onClosedAction<Object, EventArgs>Handler for the Closed event.

Instance member Form(location, size, controls, onClosed)​

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

NameTypeDescription
locationPointThe location of the form on the screen.
sizeSizeThe size of the form.
controlsControl[]An array of Control objects to be added to the form.
onClosedAction<Object, EventArgs>Handler for the Closed event.

Properties​

Instance member 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.

Instance member Active​

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

Static member ActiveForm​

Form: Returns the currently active form for this application.

Instance member ActiveMdiChild​

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

Instance member AllowTransparency​

Boolean: Returns or sets whether the opacity of the form can be adjusted. (Default: True)

Instance member AppearanceKey​

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

Instance member AutoClose​

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

Instance member AutoCloseModalDialog​

Boolean: 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.

Static member AutoCloseModalDialogDefault​

Boolean: 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);

Instance member AutoSize​

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

Instance member AutoSizeMode​

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

Instance member AutoValidate​

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

Instance member 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.

Instance member ClientArea​

Rectangle: Returns the client rectangle to use in the designer.

Instance member ClientSize​

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

Instance member CloseBox​

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

Instance member CloseReason​

CloseReason: Returns the reason for the form closing. (Default: None)

Instance member ControlBox​

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

Instance member DialogResult​

DialogResult: Returns or sets the dialog result for the form. (Default: None)

Instance member DisableMergedMenu​

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

Instance member FormBorderStyle​

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

Instance member HasMdiChildren​

Boolean: Returns whether this form is an IsMdiContainer and has any Mdi child form. (Default: False)

Instance member HasOwnedForms​

Boolean: Returns whether this form has any owned form. (Default: False)

Instance member HeaderBackColor​

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

Instance member HeaderForeColor​

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

Instance member Icon​

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

The default value is null.

Instance member IconLarge​

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

The deafult value is null.

Instance member IconLargeSource​

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

The deafult value is null.

Instance member IconSource​

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

The default value is null.

Instance member IsClosed​

Boolean: Returns whether the Form has been closed. (Default: False)

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.

Instance member IsDialog​

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

Instance member IsMdiChild​

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

Instance member IsMdiContainer​

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

Instance member KeepCentered​

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

Instance member 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)

Instance member LiveResize​

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

Instance member MaximizeBox​

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

Instance member MaximizedMargin​

Nullable<Padding>: Gets or sets the margins of the window when it is maximized. (Default: null)

If the value is set to 0,0,0,0 the form will be maximized to fill the container. If the value is reset to null, it will use the value set in the current theme.

Setting a value that is too big may result in the form being displayed incorrectly when maximized.

Instance member MaximumSize​

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

Throws:

Instance member MdiChildren​

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

Default value is Form[0] (an empty array of Forms)

Instance member MdiClient​

MdiClient: Returns the internal MdiClient component. (Default: null)

Instance member MdiParent​

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

Throws:

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

Instance member MdiTabProperties​

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

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

Instance member MergedMenu​

MainMenu: Returns the merged menu for the form. (Default: null)

Instance member MinimizeBox​

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

Instance member MinimumSize​

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

Default value is a Size with Width = 0, Height = 0 Throws:

Boolean: Returns whether this form is displayed modally. (Default: False)

Instance member Movable​

Boolean: Returns or sets whether the form can be moved by dragging. (Default: True)

Instance member Opacity​

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

Instance member OwnedForms​

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

Default value is Form[0] (an empty array of Forms)

Instance member Owner​

Form: Returns or sets the form that owns this form. (Default: null)

Throws:

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

Instance member ShowInTaskbar​

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

Instance member 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.

Instance member Size​

Size: Returns or sets the size of the form.

Instance member StartPosition​

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

Instance member Text​

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

Instance member Tools​

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

Instance member TopLevel​

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

Throws:

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

Instance member TopMost​

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

Instance member WindowState​

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

Methods​

Instance member Activate()​

Activates the form and gives it focus.

Instance member AddOwnedForm(ownedForm)​

Adds an owned form to this form.

ParameterTypeDescription
ownedFormFormThe Form that this form will own.

Protected member CenterToScreen()​

Centers the window on the current browser size.

Instance member Close()​

Closes the form.

Protected member Dispose(disposing)​

Deactivate and remove the disposed window from the open form collections.

ParameterTypeDescription
disposingBooleantrue when this method is called by the application rather than a finalizer.

Protected member OnActivated(e)​

Fires the Activated event.

ParameterTypeDescription
eEventArgsA EventArgs that contains the event data.

Protected member OnAddReferences(items)​

Adds references components to the list. Referenced components can be added individually or as a reference to a collection.

ParameterTypeDescription
itemsIListContainer for the referenced components or collections.

Protected member OnBindingContextChanged(e)​

Fires the BindingContextChanged event.

ParameterTypeDescription
eEventArgsAn EventArgs that contains the event data.

Protected member OnClosed(e)​

Fires the Closed event.

ParameterTypeDescription
eEventArgsThe EventArgs that contains the event data.

Protected member OnClosing(e)​

Fires the Closing event.

ParameterTypeDescription
eCancelEventArgsA CancelEventArgs that contains the event data.

Protected member OnControlAdded(e)​

Fires the ControlAdded event.

ParameterTypeDescription
eControlEventArgsA ControlEventArgs that contains the event data.

Protected member OnCreateControl()​

Raised when the control is created.

Protected member OnDeactivate(e)​

Fires the Deactivate event.

ParameterTypeDescription
eEventArgsThe EventArgs that contains the event data.

Protected member OnEnabledChanged(e)​

ParameterTypeDescription
eEventArgsA EventArgs that contains the event data.

Protected member OnFormClosed(e)​

Raises the FormClosed event.

ParameterTypeDescription
eFormClosedEventArgsA FormClosedEventArgs that contains the event data.

Protected member OnFormClosing(e)​

Raises the FormClosing event.

ParameterTypeDescription
eFormClosingEventArgsA FormClosingEventArgs that contains the event data.

Protected member OnHelpButtonClicked(e)​

Fires the HelpButtonClicked event.

ParameterTypeDescription
eEventArgsA EventArgs that contains the event data.

Protected member OnLayout(e)​

Fires the Layout event.

ParameterTypeDescription
eLayoutEventArgsA LayoutEventArgs that contains the event data.

Protected member OnLoad(e)​

Fires the Load event.

ParameterTypeDescription
eEventArgsA EventArgs that contains the event data.

Protected member OnLocationChanged(e)​

Fires the LocationChanged event.

ParameterTypeDescription
eEventArgs

Protected member OnMaximizedMarginChanged(e)​

Fires the MaximizedMarginChanged event.

ParameterTypeDescription
eEventArgsThe EventArgs that contains the event data.

Protected member OnMaximumSizeChanged(e)​

Fires the MaximumSizeChanged event.

ParameterTypeDescription
eEventArgsThe EventArgs that contains the event data.

Protected member OnMdiChildActivate(e)​

Fires the MdiChildActivate event.

ParameterTypeDescription
eEventArgsThe EventArgs that contains the event data.

Protected member OnMdiChildAdded(e)​

Fires the MdiChildAdded event.

ParameterTypeDescription
eControlEventArgsThe EventArgs that contains the event data.

Protected member OnMdiChildRemoved(e)​

Fires the MdiChildRemoved event.

ParameterTypeDescription
eControlEventArgsThe EventArgs that contains the event data.

Protected member OnMinimumSizeChanged(e)​

Fires the MinimumSizeChanged event.

ParameterTypeDescription
eEventArgsA EventArgs that contains the event data.

Protected member OnMouseClick(e)​

Fires the MouseClick event.

ParameterTypeDescription
eMouseEventArgsA MouseEventArgs that contains the event data.

Protected member OnShown(e)​

Fires the Shown event.

ParameterTypeDescription
eEventArgsA EventArgs that contains the event data.

Protected member OnToolClick(e)​

Fires the ToolClick event.

ParameterTypeDescription
eToolClickEventArgsA ToolClickEventArgs that contains the event data.

Protected member OnWebEvent(e)​

Processes the event from the client.

ParameterTypeDescription
eWisejEventArgsEvent arguments.

Protected member OnWebRender(config)​

Renders the client component.

ParameterTypeDescription
configObjectDynamic configuration object.

Protected member OnWebUpdate(state)​

Updates the client component using the state information.

ParameterTypeDescription
stateObjectDynamic state object.

Protected member OnWindowStateChanged(e)​

Fires the WindowStateChanged event.

ParameterTypeDescription
eEventArgsA EventArgs that contains the event data.

Instance member PointToClient(point)​

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

ParameterTypeDescription
pointPointThe screen coordinate Point to convert.

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

Instance member PointToScreen(point)​

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

ParameterTypeDescription
pointPointThe client coordinate Point to convert.

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

Instance member 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.

ParameterTypeDescription
refreshChildrenBooleanTrue to also refresh all the children of this control.

Instance member RemoveOwnedForm(ownedForm)​

Removes an owned form from this form.

ParameterTypeDescription
ownedFormFormA Form representing the form to remove from the list of owned forms for this form.

Instance member Show(onclose)​

Shows the form to the user.

ParameterTypeDescription
onclose optionalAction<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.

Instance member Show(owner, onclose)​

Shows the form with the specified owner to the user.

ParameterTypeDescription
ownerFormA Form that is related to this instance. This form is added to the OwnedForms collection of the owner form.
onclose optionalAction<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.

Instance member ShowDialog(onclose)​

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

ParameterTypeDescription
onclose optionalAction<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.

Instance member 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.

ParameterTypeDescription
ownerFormA Form that is related to this instance. This form is added to the OwnedForms collection of the owner form.
onclose optionalAction<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.

Instance member ShowDialogAsync(owner)​

Asynchronously shows the form as an awaitable modal dialog box.

ParameterTypeDescription
owner optionalFormAn 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.

Protected member SizeFromClientSize(clientSize)​

Converts the client size into the window size.

ParameterTypeDescription
clientSizeSize

Returns: Size.

Events​

Instance member Activated​

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

Instance member Deactivate​

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

Instance member FormClosed​

FormClosedEventHandler Occurs after the form is closed.

Instance member FormClosing​

FormClosingEventHandler Occurs before the form is closed.

Instance member HelpButtonClicked​

EventHandler Fired when the Help button is clicked.

Instance member Load​

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

Instance member MaximizedMarginChanged​

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

Instance member MaximumSizeChanged​

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

Instance member MdiChildActivate​

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

Instance member MdiChildAdded​

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

Instance member MdiChildRemoved​

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

Instance member MinimumSizeChanged​

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

Instance member Shown​

EventHandler Fired whenever the form is first displayed.

Instance member ToolClick​

ToolClickEventHandler Fired when a ComponentTool is clicked.

Instance member WindowStateChanged​

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

Inherited By​

NameDescription
FileDialogUIUI implementation for the FileDialog class.
FolderBrowserDialogUIUI implementation for the FolderDialog class.

Implements​

NameDescription
IUserDataProvides access to the UserData and Tag properties associated to the component implementing this interface.
IBindableComponentBindable components implement this interface.
IContainerControlProvides the functionality for a control to act as a parent for other controls.
IDropTargetControls that support drag & drop operations implement this interface.
IWisejComponentAll wisej components implement this interface.
IWisejControlAll wisej controls derived from the Control class must implement this interface.
IWisejWindowAll wisej top-level windows implement this interface.
IWisejSerializableAllows an object to serialize itself.