SalForm

Namespace: PPJ.Runtime.Windows

Assembly: PPJ.Web.50 (5.0.0.0)

• Control
  • ScrollableControl
    • ContainerControl
      • Form
        • SalForm

Base form integrating SAL lifecycle messages, window context, ownership, validation, and browser rendering.

C#

public class SalForm : Form, ISalForm, ISalWindow

VB.NET

Public Class SalForm
    Inherits Form
    Implements ISalForm, ISalWindow

Use SalFormWindow, SalDialogBox, or another specialized subclass for application windows.

Example:

public sealed class CustomerWindow : SalFormWindow
            {
                public CustomerWindow()
                {
                    Text = "Customers";
                    Controls.Add(new SalDataField { Name = "customerName" });
                }
            }

Properties

CultureInfo

CultureInfo: Gets or sets the form culture used by inheriting SAL controls.

Unset runtime values fall back to Sys.CultureInfo. Neutral cultures are rejected. Non-current mutable cultures are stored read-only; assigning null restores fallback behavior.

IconName

String: Gets or sets the embedded icon resource name.

A changed nonempty name loads from the calling assembly at runtime; empty or null clears the icon.

NamedProperties

SalNamedProperties: Gets this window's SAL named-property collection.

ReturnValue

Int32: Gets or sets the numeric SAL result returned by dialog operations.

Methods

BringWindowToTop()

Brings this control to the front, or activates it when it is a top-level or MDI form.

Returns: SalBoolean. True if the translated control exists and is not disposed; otherwise, false.

CenterWindow()

Centers this window within its parent, owner, or available screen area.

Returns: SalBoolean. True if the centering operation is accepted; false for an unavailable control, design mode, or unavailable screen bounds.

ClearCursor(nType)

Restores the default cursor for the requested role.

Parameter	Type	Description
nType	SalNumber	The cursor role: Sys.CURSOR_Window, Sys.CURSOR_DragDrop, or Sys.CURSOR_DisableDrop.

Returns: SalBoolean. True if the operation is accepted by the SAL window implementation; otherwise, false.

Only the window role changes the displayed cursor. Drag/drop roles are accepted for SAL windows without changing a cursor.

Destroy()

Sends the SAL destruction message and disposes the form.

DestroyWindow()

Closes this window when it is a form, or disposes the control.

Returns: SalBoolean. True if the operation is accepted by the SAL window implementation; otherwise, false.

A true result reports that the close or disposal request was made; a form can apply its own closing behavior.

DisableWindow()

Disables input to this control, or clears editability for a table column.

Returns: SalBoolean. True if the operation is accepted by the SAL window implementation; otherwise, false.

Dispose(disposing)

Marks SAL window state disposed, disposes the base form, and removes it from the application form registry.

Parameter	Type	Description
disposing	Boolean	Whether managed resources are being disposed.

DrawMenuBar()

Refreshes the form's SAL main menu.

Returns: SalBoolean. The result of SalWindow.UpdateMainMenu.

EnableWindow()

Enables input to this control, or enables editing for a table column.

Returns: SalBoolean. True if the operation is accepted by the SAL window implementation; otherwise, false.

For text-box controls, this operation also clears the read-only setting.

EndDialog(nReturn)

Parameter	Type	Description
nReturn	SalNumber

Returns: SalBoolean.

Applies the referenced SAL operation to this control.

FindChild(sWindowName)

Searches this window for a child control by name.

Parameter	Type	Description
sWindowName	SalString	The child control name to locate.

Returns: SalWindowHandle. The matching child handle, or a null SAL handle if no child is found.

FormUnitsToPixels(nFormUnits, bVertical)

Converts a length in form units to pixels using this control's form metrics.

Parameter	Type	Description
nFormUnits	SalNumber	The length in form units.
bVertical	SalBoolean	True for a vertical measurement; false for a horizontal measurement.

Returns: SalNumber. The converted pixel length.

GetClassName()

Gets the application class name associated with this control.

Returns: SalString. The application class name, an empty string for runtime-defined classes, or a SAL null string when the control cannot be resolved.

Forms are represented by their base type; nested table-window types are resolved to their non-nested base.

GetControlType()

Gets the SAL window type of this control.

Returns: SalNumber. The SAL Sys.TYPE_* code for the translated control.

GetDefaultButton()

Returns: SalWindowHandle.

Applies the referenced SAL operation to this control.

GetFirstChild(nTypeMask)

Finds the first child matching a SAL window-type mask.

Parameter	Type	Description
nTypeMask	SalNumber	The SAL window types to include; zero matches no controls.

Returns: SalWindowHandle. The first matching child handle, or a null SAL handle when none matches.

Ordinary controls use tab order; table columns use their creation order, and MDI forms use their child-form collection.

GetFont(sName, nSize, nEnhancement)

Reads the control font's family, point size, and style flags.

Parameter	Type	Description
sName	SalString	Receives the font family name.
nSize	SalNumber	Receives the size in points.
nEnhancement	SalNumber	Receives the combined Sys.FONT_Enh* style flags.

Returns: SalBoolean. True if a font was available; otherwise, false.

GetLocation(nX, nY)

Reads this control's location in form units.

Parameter	Type	Description
nX	SalNumber	Receives the horizontal location.
nY	SalNumber	Receives the vertical location.

Returns: SalBoolean. Always true; an unresolved control produces zero coordinates.

GetName(sText)

Copies this control's name to the supplied variable.

Parameter	Type	Description
sText	SalString	Receives the control name when the operation succeeds.

Returns: SalBoolean. True if the operation is accepted by the SAL window implementation; otherwise, false.

GetName()

Gets this control's name.

Returns: SalString. The control name, or an empty string if the control cannot be resolved.

GetNextChild(nTypeMask)

Finds the next sibling matching a SAL window-type mask.

Parameter	Type	Description
nTypeMask	SalNumber	The SAL window types to include; zero matches no controls.

Returns: SalWindowHandle. The next matching control handle, or a null SAL handle when none matches.

GetParent()

Gets the SAL parent form, owner, or table container for this control.

Returns: SalWindowHandle. The parent window handle, or a null SAL handle if no parent can be resolved.

GetProperty(sName, sValue)

Reads a SAL named property into a supplied variable.

Parameter	Type	Description
sName	SalString	The property name.
sValue	SalString	Receives the value only when the property is found.

Returns: SalBoolean. True if a non-null property value was found; otherwise, false.

GetProperty(sName)

Gets the value of a SAL named property.

Parameter	Type	Description
sName	SalString	The property name.

Returns: SalString. The property value, or a SAL null string if the value is unavailable.

GetSize(nWidth, nHeight)

Reads this control's size in form units.

Parameter	Type	Description
nWidth	SalNumber	Receives the width.
nHeight	SalNumber	Receives the height.

Returns: SalBoolean. Always true; an unresolved control produces a zero size.

GetStatusBarText(sText, nMaxLen)

Copies a bounded status-bar caption.

Parameter	Type	Description
sText	SalString	Receives the status text when available.
nMaxLen	SalNumber	The maximum number of characters to return.

Returns: SalNumber. The result length reported by SalWindow.GetStatusBarText.

GetStatusBarText(nMaxLen)

Reads a bounded status-bar caption.

Parameter	Type	Description
nMaxLen	SalNumber	The maximum number of characters to return.

Returns: SalString. The text returned by the SAL status-bar helper.

GetText(sText, nMaxLen)

Copies this control's displayed text or long-string value to a SAL string.

Parameter	Type	Description
sText	SalString	Receives the retrieved text.
nMaxLen	SalNumber	The maximum character count for ordinary text; ignored for a Sys.DT_LongString value.

Returns: SalNumber. The number of characters copied, or zero when no text is available.

GetText(nMaxLen)

Gets this control's displayed text or long-string value.

Parameter	Type	Description
nMaxLen	SalNumber	The maximum character count for ordinary text; ignored for a Sys.DT_LongString value.

Returns: SalString. The retrieved text, or an empty string if the control cannot be resolved.

GetWindowColor(nColorIndex)

Reads a window or cell color as a Win32 color value.

Parameter	Type	Description
nColorIndex	SalNumber	The Sys.COLOR_Index* color component to read.

Returns: SalNumber. The color encoded as a Win32 color value, or zero if the control is unavailable.

GetWindowState()

Gets the visibility and form-state classification of this window.

Returns: SalNumber. A Sys.Window_* state code; visible non-form controls report Sys.Window_Normal.

HideWindow()

Hides this control or table column.

Returns: SalBoolean. The visibility state before the operation, or false if the control cannot be resolved.

InvalidateWindow()

Invalidates this control and its child controls for repainting.

Returns: SalBoolean. True if the operation is accepted by the SAL window implementation; otherwise, false.

IsDerivedFromClass(tClass)

Tests this control's runtime type against an application base type.

Parameter	Type	Description
tClass	Type	The type to test, including the framework's emulated inheritance relationships.

Returns: SalBoolean. True if the runtime type derives from the requested type; otherwise, false.

IsEnabled()

Determines whether this control accepts input.

Returns: SalBoolean. The enabled state, or the editable flag for a table column; false if the control cannot be resolved.

IsVisible()

Determines whether this control is visible.

Returns: SalBoolean. The visible state, or the visibility flag for a table column; false if the control cannot be resolved.

KillTimer(nIDEvent)

Stops an existing timer owned by this control.

Parameter	Type	Description
nIDEvent	SalNumber	The identifier used when the timer was started.

Returns: SalBoolean. True if the timer was found and stopped; otherwise, false.

The timer remains registered and can be restarted by SetTimer.

MoveWindow(nXOffset, nYOffset)

Moves this control by an offset expressed in form units.

Parameter	Type	Description
nXOffset	SalNumber	The horizontal offset to add to the current position.
nYOffset	SalNumber	The vertical offset to add to the current position.

Returns: SalBoolean. True if the operation is accepted by the SAL window implementation; otherwise, false.

OnActivated(e)

Raises the inherited event and sends SAM_Activate with an active-state value of one.

Parameter	Type	Description
e	EventArgs	The activation event.

OnCreateControl()

Registers runtime top-level/MDI forms and sends SAL creation before inherited creation.

Designer creation uses the base implementation. Creating a second-base form throws InvalidOperationException.

OnDeactivate(e)

Reports deactivation and validates eligible non-dialog, non-MDI-child forms.

Parameter	Type	Description
e	EventArgs	The deactivation event.

Sends SAM_Activate with zero. Avoids recursive validation and reactivates the form if validation fails while it is not closing.

OnDragDrop(e)

Processes the SAL drop notification before raising the inherited event.

Parameter	Type	Description
e	DragEventArgs	The event data passed to both handlers.

OnDragEnd(e)

Ends SAL drag handling before raising the inherited drag-end event.

Parameter	Type	Description
e	EventArgs	The event data passed to both handlers.

OnDragEnter(e)

Processes the SAL drag-enter notification before raising the inherited event.

Parameter	Type	Description
e	DragEventArgs	The event data passed to both handlers.

OnDragLeave(e)

Processes the SAL drag-leave notification before raising the inherited event.

Parameter	Type	Description
e	EventArgs	The event data passed to both handlers.

OnDragOver(e)

Processes SAL drag feedback before raising the inherited drag-over event.

Parameter	Type	Description
e	DragEventArgs	The event data passed to both handlers.

OnDragStart(e)

Starts SAL drag handling before raising the inherited drag-start event.

Parameter	Type	Description
e	EventArgs	The event data passed to both handlers.

OnFormClosed(e)

Raises the inherited event, sends SAL destruction, and arranges dialog disposal.

Parameter	Type	Description
e	FormClosedEventArgs	The completed close event.

For top-level modal/modeless dialogs, posts server disposal if the client never saw the form; otherwise requests browser destruction.

OnFormClosing(e)

Raises the inherited event and processes a user-initiated SAM_Close message.

Parameter	Type	Description
e	FormClosingEventArgs	The cancellable close event.

Skips SAL close dispatch while already closing or closed. An explicit message result controls cancellation unless message processing already marked the form closed.

OnGotFocus(e)

Dispatches SAL focus-gained processing before raising the inherited focus event.

Parameter	Type	Description
e	EventArgs	The focus event data.

OnHelpRequested(e)

Sends the SAL help request before raising the inherited event.

Parameter	Type	Description
e	HelpEventArgs	The help event data.

OnLoad(e)

Sends SAL creation-complete messages before the inherited runtime load event.

Parameter	Type	Description
e	EventArgs	The load event data.

OnLostFocus(e)

Dispatches SAL focus-lost processing before raising the inherited focus event.

Parameter	Type	Description
e	EventArgs	The focus event data.

OnMdiChildActivate(e)

Raises the inherited event and refreshes the main menu for the active MDI child.

Parameter	Type	Description
e	EventArgs	The activation event.

OnWebEvent(e)

Handles browser form events in SAL context and simulates WinSDK notifications.

Parameter	Type	Description
e	WisejEventArgs	The browser event.

A close event disposes a previously destroyed form when needed. Other events go to the inherited handler.

OnWebRender(config)

Assigns the SAL form client class after inherited rendering unless the form is closed.

Parameter	Type	Description
config	Object	The mutable browser configuration.

PixelsToFormUnits(nNumPixels, bVertical)

Converts a pixel length to form units using this control's form metrics.

Parameter	Type	Description
nNumPixels	SalNumber	The pixel length to convert.
bVertical	SalBoolean	True for a vertical measurement; false for a horizontal measurement.

Returns: SalNumber. The converted length in form units.

PostMessage(nMsg, nMywParam, nMylParam)

Queues a SAL window action for later dispatch on the application context.

Parameter	Type	Description
nMsg	SalNumber	The SAL or application-defined message code.
nMywParam	SalNumber	The first message parameter.
nMylParam	SalNumber	The second message parameter.

Returns: SalBoolean. True if the action was queued; false if the control is unavailable or disposed.

Print()

Requests browser printing of this form.

SendMessage(nMsg, nMywParam, nMylParam)

Dispatches a SAL window action synchronously and returns its result.

Parameter	Type	Description
nMsg	SalNumber	The SAL or application-defined message code.
nMywParam	SalNumber	The first message parameter.
nMylParam	SalNumber	The second message parameter.

Returns: SalNumber. The action's return value, or zero if the target is unavailable or disposed.

SendMessageToChildren(nMsg, nMywParam, nMylParam)

Dispatches a SAL message to this control's children.

Parameter	Type	Description
nMsg	SalNumber	The SAL or application-defined message code.
nMywParam	SalNumber	The first message parameter.
nMylParam	SalNumber	The second message parameter.

Returns: SalBoolean. The result of child-message dispatch; false if the parent is unavailable or disposed.

SetContextMenu(sMenuName, nFlags)

Creates and assigns a context menu for this control.

Parameter	Type	Description
sMenuName	SalString	The name used to resolve the menu type.
nFlags	SalNumber	Use Sys.CM_TableCell to target the associated table column; other values target the control.

Returns: SalBoolean. True if the menu was created; false if the control or menu type is unavailable or menu creation fails.

SetContextMenu(menuType, nFlags)

Creates and assigns a context menu for this control.

Parameter	Type	Description
menuType	Type	The type of the menu to create.
nFlags	SalNumber	Use Sys.CM_TableCell to target the associated table column; other values target the control.

Returns: SalBoolean. True if the menu was created; false if the control or menu type is unavailable or menu creation fails.

SetCursor(nResourceId, nType)

Assigns a predefined cursor to the requested role.

Parameter	Type	Description
nResourceId	Int32	A supported Sys.CURSOR_* cursor identifier.
nType	SalNumber	The cursor role: Sys.CURSOR_Window, Sys.CURSOR_DragDrop, or Sys.CURSOR_DisableDrop.

Returns: SalBoolean. True if the operation is accepted by the SAL window implementation; otherwise, false.

Only the window role changes the displayed cursor. Drag/drop roles are accepted for SAL windows without changing a cursor.

SetCursor(sBlob, nType)

Requests a cursor from binary data; this web implementation does not support binary cursor loading.

Parameter	Type	Description
sBlob	SalString	The binary cursor data.
nType	SalNumber	The cursor role: Sys.CURSOR_Window, Sys.CURSOR_DragDrop, or Sys.CURSOR_DisableDrop.

Returns: SalBoolean. Always false.

SetCursorFile(sFile, nType)

Loads a cursor from a file and assigns it to the requested role.

Parameter	Type	Description
sFile	SalString	The cursor file path.
nType	SalNumber	The cursor role: Sys.CURSOR_Window, Sys.CURSOR_DragDrop, or Sys.CURSOR_DisableDrop.

Returns: SalBoolean. True if loading and assignment succeed; otherwise, false.

Only the window role changes the displayed cursor. Drag/drop roles are accepted for SAL windows without changing a cursor.

SetFocus()

Requests keyboard focus for this control.

Returns: SalWindowHandle. The previously focused control's handle, or a null SAL handle when no previous control exists or this target is ineligible.

Hidden or disabled controls and table columns are ineligible.

SetFont(sName, nSize, nEnhancement)

Creates and assigns a font to this control.

Parameter	Type	Description
sName	SalString	The font family name.
nSize	SalNumber	The font size in points.
nEnhancement	SalNumber	The combined Sys.FONT_Enh* style flags.

Returns: SalBoolean. True if the font was created and assigned; otherwise, false.

SetLocation(nX, nY)

Sets this control's location in form units.

Parameter	Type	Description
nX	SalNumber	The new horizontal coordinate.
nY	SalNumber	The new vertical coordinate.

Returns: SalBoolean. True if the operation is accepted by the SAL window implementation; otherwise, false.

For forms, this also selects manual startup positioning.

SetProperty(sName, sValue, nLength)

Assigns a SAL named property after limiting the value's length.

Parameter	Type	Description
sName	SalString	The property name.
sValue	SalString	The value to assign.
nLength	SalNumber	The number of leading characters to retain.

Returns: SalBoolean. True if the translated control implements the SAL window contract; otherwise, false.

SetSize(nWidth, nHeight)

Sets this control's dimensions in form units.

Parameter	Type	Description
nWidth	SalNumber	The new width.
nHeight	SalNumber	The new height.

Returns: SalBoolean. True if the operation is accepted by the SAL window implementation; otherwise, false.

SetStatusBarText(sText)

Parameter	Type	Description
sText	SalString

Returns: SalBoolean.

Applies the referenced SAL operation to this control.

SetText(sText)

Assigns the control's text.

Parameter	Type	Description
sText	SalString	The text to display.

Returns: SalBoolean. True if the operation is accepted by the SAL window implementation; otherwise, false.

SetTimer(nIDEvent, nElapseMilliSec)

Starts or restarts a timer that sends SAL timer actions to this control.

Parameter	Type	Description
nIDEvent	SalNumber	The timer identifier sent in the first parameter of each Sys.SAM_Timer action.
nElapseMilliSec	SalNumber	The interval between ticks, in milliseconds.

Returns: SalBoolean. True if the operation is accepted by the SAL window implementation; otherwise, false.

SetVisibleCore(value)

Applies visibility while preserving SAL creation state.

Parameter	Type	Description
value	Boolean	The requested visibility.

Second-base instances remain hidden. Runtime creation records whether the form began hidden.

SetWindowColor(nColorIndex, nColor)

Assigns a window or table-cell color.

Parameter	Type	Description
nColorIndex	SalNumber	The Sys.COLOR_Index* component to change.
nColor	SalNumber	The SAL color value to translate and assign.

Returns: SalBoolean. True for a supported color index and resolved control; otherwise, false.

Cell colors apply only to table columns. Window colors on table windows also update their grid styles.

Show(parent)

Shows a modeless form with SAL ownership and MDI behavior.

Parameter	Type	Description
parent	Control	The owning or MDI container control, translated through SAL second-base handling.

Dialog-box classes are shown in the taskbar. Non-dialog forms become MDI children when the parent is an MDI container, hiding their status bar; other owned forms are hidden from the taskbar.

ShowAsChild(parent, rect, border)

Embeds the form using bounds expressed in form units.

Parameter	Type	Description
parent	Control	The containing control; a form's client-area accessory is used when available.
rect	RectangleF	Location and size in form units. A width or height of -1 preserves that dimension.
border	Boolean	Whether to display a fixed border.

Converts bounds relative to the parent and calls the pixel-bounds overload. MDI containers cannot be embedded.

ShowAsChild(parent, rect, border)

Embeds and shows the form as a child control.

Parameter	Type	Description
parent	Control	The containing control; a form's client-area accessory is used when available.
rect	Rectangle	Pixel bounds. A width or height of -1 preserves that dimension.
border	Boolean	True for a fixed border; false for no border.

Disables top-level behavior, removes the menu and control box, enables tab navigation, and brings the child to the front. Throws InvalidOperationException for an MDI container.

ShowDialog()

Shows the form as a dialog with no explicit parent.

Returns: Int32. The ReturnValue observed after the underlying ShowDialog call.

ShowDialog(parent)

Shows the form as a dialog using SAL owner resolution.

Parameter	Type	Description
parent	Control	The control used to determine the dialog owner.

Returns: Int32. The ReturnValue observed after the underlying ShowDialog call.

ShowDialog(parent, closeHandler)

Shows a dialog and optionally reports its SAL result when it closes.

Parameter	Type	Description
parent	Control	The control used to determine the dialog owner.
closeHandler	Action<Int32>	Optional callback receiving ReturnValue when the dialog closes.

Returns: Int32. The current ReturnValue after the underlying ShowDialog call.

An ownerless dialog is shown in the taskbar. An MDI container throws InvalidOperationException. Use ShowDialogAsync when the caller must await closure.

ShowDialogAsync(parent)

Shows the dialog and completes a task when its close callback runs.

Parameter	Type	Description
parent	Control	The control used to determine the dialog owner.

Returns: Task<Int32>. A task whose result is the dialog's ReturnValue at closure.

ShowStatusBar(bShow)

Parameter	Type	Description
bShow	SalBoolean

Returns: SalBoolean.

Applies the referenced SAL operation to this control.

ShowToolBar(bShow)

Parameter	Type	Description
bShow	SalBoolean

Returns: SalBoolean.

Applies the referenced SAL operation to this control.

ShowWindow()

Shows this control or table column.

Returns: SalBoolean. The visibility state before the operation, or false if the control cannot be resolved.

TrackPopupMenu(sMenuName, nFlags, nX, nY, callback)

Creates and displays a popup menu, disposing it after it closes.

Parameter	Type	Description
sMenuName	SalString	The name used to resolve the menu type.
nFlags	SalNumber	Popup flags controlling right alignment and use of the current cursor coordinates. Center alignment and context-menu flags are not supported.
nX	SalNumber	The horizontal screen coordinate in pixels, unless the cursor-X flag is set.
nY	SalNumber	The vertical screen coordinate in pixels, unless the cursor-Y flag is set.
callback	Action<ContextMenu>	An optional callback invoked when the menu closes, before it is disposed.

Returns: SalBoolean. True if the menu was created and shown; otherwise, false.

TrackPopupMenu(menuType, nFlags, nX, nY, callback)

Creates and displays a popup menu, disposing it after it closes.

Parameter	Type	Description
menuType	Type	The menu type to instantiate.
nFlags	SalNumber	Popup flags controlling right alignment and use of the current cursor coordinates. Center alignment and context-menu flags are not supported.
nX	SalNumber	The horizontal screen coordinate in pixels, unless the cursor-X flag is set.
nY	SalNumber	The vertical screen coordinate in pixels, unless the cursor-Y flag is set.
callback	Action<ContextMenu>	An optional callback invoked when the menu closes, before it is disposed.

Returns: SalBoolean. True if the menu was created and shown; otherwise, false.

UpdateWindow()

Requests an update of this control.

Returns: SalBoolean. True if the operation is accepted by the SAL window implementation; otherwise, false.

Events

WindowActions

WindowActionsEventHandler Occurs when the control receives a SAL or application-defined window action.

Inherited By

Name	Description
SalDialogBox	A SAL form configured as a fixed-size dialog.
SalFormTableWindow	Hosts an embedded SAL table as a form and exposes its row, column, and population operations.
SalFormWindow	A scrollable SAL application form.
SalMDIWindow	A SAL multiple-document container with an automatic-child initialization hook.
SalRibbonBarBase	Base SAL form that creates ribbon and status-bar accessories.
SalRibbonBarForm	A ribbon-enabled SAL form that hosts a single control or embedded child form.
SalRibbonBarMDI	A ribbon-enabled SAL multiple-document container.
SalQuickTabsDialog	Provides a dialog with a built-in fill-docked QuickTabs frame.
SalQuickTabsForm	Provides a form with a built-in fill-docked QuickTabs frame.
SalQuickTabsParent	Provides overridable callbacks for a child QuickTabs frame.
SalQuickTabsParentDialog	Provides a dialog-style host for QuickTabs callbacks.
SalQuickTabsParentForm	Provides a form host for QuickTabs callbacks.
VisSplitterWindow
XSalToolbox

Implements

Name	Description
ISalWindow	Provides SAL window actions, named properties, and access to a window's runtime implementation.