SalApplication
Namespace: PPJ.Runtime.Windows
Assembly: PPJ.Runtime.50 (5.0.0.0)
Hosts a translated SAL Windows Forms application and supplies lifecycle hooks, form tracking, profile storage, tracing, and skin integration.
- C#
- VB.NET
public class SalApplication
Public Class SalApplication
Construct one application instance before entering Run. Startup runs on the first idle notification, followed by automatic form creation. Registered top-level forms keep the application alive; releasing the last form requests application exit.
Example:
public class ExampleApplication : PPJ.Runtime.Windows.SalApplication
{
[System.STAThread]
public static int Main(string[] args)
{
return new ExampleApplication().Run(args);
}
protected override void OnAppCreateAutomaticForms()
{
var form = new System.Windows.Forms.Form { Text = "Customer Browser" };
AddForm(form);
form.Show();
}
}
Constructors
SalApplication()
Registers this application instance and its lifecycle handlers without additional command-line arguments.
SalApplication(args)
Registers this application instance, saves its namespace and arguments, and attaches lifecycle handlers.
| Name | Type | Description |
|---|---|---|
| args | String[] | The command-line arguments, or null. The executable path is stored separately at index zero of the SAL argument array. |
Properties
ApplicationType
Type: Gets the runtime type of the most recently constructed SAL application instance.
CompanyName
String: Gets or sets the company name, initially taken from the entry assembly company attribute and normalized to an empty string when null.
DefaultPrinterSettings
PrinterSettings: Gets or sets the shared printer settings used by the application.
The first read after a null assignment creates settings with all page margins set to 10 and the print-file name set to the executable name without its extension.
FormsScaleFactor
SizeF: Gets or sets the global form scaling factor; an empty size leaves the standard scaling behavior in effect.
Instance
SalApplication: Gets the most recently constructed SAL application instance, or null before one has been constructed.
SkinApplication
Boolean: Gets or sets whether application skinning is enabled for the current thread, updating the skin engine when the application is active.
ThreadModel
ApartmentState: Gets the current thread's OLE apartment state, initializing OLE through Windows Forms when required.
Title
String: Gets or sets the application title.
The initial value comes from the entry assembly title, falling back to the application-domain friendly name. A null assignment becomes an empty string.
TopLevelForms
Form[]: Gets a snapshot array of forms registered with the application, or an empty array if none are tracked.
UseCompatibleTextRendering
Boolean: Gets or sets the Windows Forms default for compatible text rendering.
Set this value before creating application windows, as required by SetCompatibleTextRenderingDefault.
Version
Int32: Gets the framework version encoded as 900 plus ten times the assembly major version plus its minor version.
VisualStyler
VisualStyler: Gets the VisualStyler component associated with the current thread's skin integration.
VisualStyles
Boolean: Gets or sets whether startup should enable Windows visual styles.
Enabling is ignored when the operating system does not report theme support. Setting this flag alone does not restyle existing controls.
XPStyle
Deprecated: This property has been deprecated. Use SalApplication.VisualStyles.
Boolean: Gets or sets the obsolete alias for VisualStyles.
Methods
AddForm(form)
Registers a top-level form and increments the application lifetime count once for that instance.
| Parameter | Type | Description |
|---|---|---|
| form | Form | The form to register. |
Returns: Int32. The resulting lifetime count, or zero when the application is not in run mode.
Non-SAL forms are automatically removed when their native handles are destroyed. Throws:
- ArgumentNullException The application is running and form is null.
ApplySkin(form)
Applies skin integration for a form.
| Parameter | Type | Description |
|---|---|---|
| form | Form | The form to update. |
ApplySkin(control, children)
Applies skin integration for a control and optionally its descendants.
| Parameter | Type | Description |
|---|---|---|
| control | Control | The control to update. |
| children | Boolean | True to include child controls. |
DelayDispose(obj)
Queues an object for disposal during the next application idle notification.
| Parameter | Type | Description |
|---|---|---|
| obj | IDisposable | The non-null object to dispose later. |
Already-disposed Windows Forms controls are skipped. Other objects receive a Dispose call when dequeued.
Disable()
Disables native input for every tracked top-level form whose handle exists.
Returns: Boolean. True after visiting the registered forms.
Enable()
Enables native input for every disabled tracked top-level form whose handle exists.
Returns: Boolean. True after visiting the registered forms.
This does not preserve the reason a form was disabled; all disabled tracked forms are enabled.
EndTrace()
Disables application tracing and releases any open event-log component.
Returns: Boolean. True after resetting the trace configuration.
Find(name, activate)
Finds a visible window belonging to another process with the specified executable name in the current session.
| Parameter | Type | Description |
|---|---|---|
| name | String | The executable name or path; its directory and extension are ignored for comparison. |
| activate | Boolean | True to restore a minimized matching window or bring it to the top. |
Returns: IntPtr. The matching window handle, or zero if no suitable window is found.
GetProfileInt(section, entry, defaultValue, fileName)
Reads an integer from an INI section or the configured registry profile store.
| Parameter | Type | Description |
|---|---|---|
| section | String | The section name. |
| entry | String | The value name. |
| defaultValue | UInt32 | The value to return when the requested entry is absent. |
| fileName | String | The INI file name, or application subkey when registry profiles are enabled. |
Returns: UInt32. The stored value converted to an unsigned integer, or the supplied default.
GetProfileString(section, entry, defaultValue, value, fileName)
Reads a string from an INI section or the configured registry profile store.
| Parameter | Type | Description |
|---|---|---|
| section | String | The section name. |
| entry | String | The value name. |
| defaultValue | String | The value used when the requested entry is absent. |
value  | SalString | Receives the retrieved string. |
| fileName | String | The INI file name, or application subkey when registry profiles are enabled. |
Returns: Int32. The length of the string assigned to value .
INI reads use a fixed buffer with a capacity of 2048 characters.
IdleKick()
Synchronously sends registered idle messages and processes the delayed-disposal queue.
Returns: Boolean. True after idle processing completes.
IdleRegister(ctrl, msg, wParam, lParam)
Registers a control's current native handle to receive a message on each application idle notification.
| Parameter | Type | Description |
|---|---|---|
| ctrl | Control | The target control; accessing its handle may create it. |
| msg | Int32 | The message identifier. |
| wParam | Int32 | The first message parameter. |
| lParam | Int32 | The second message parameter. |
Returns: Boolean. False when the control is null; otherwise, true.
Repeated calls add separate registrations.
IdleUnregister(ctrl)
Removes the first idle registration matching the control's current handle.
| Parameter | Type | Description |
|---|---|---|
| ctrl | Control | The control whose registration should be removed. |
Returns: Boolean. False for a null control or a control without a created handle; otherwise, true, even if no registration exists.
LoadApp(name, args)
Starts an application with normal window presentation without waiting for it to exit.
| Parameter | Type | Description |
|---|---|---|
| name | String | The executable command, quoted as needed for paths containing spaces. |
| args | String | The command-line arguments to append. |
Returns: Boolean. True if process creation and the initial exit-code query succeed; otherwise, false.
LoadAppAndProcessMsgs(name, mode, retCode)
Starts a process and waits for its exit without disabling tracked forms.
| Parameter | Type | Description |
|---|---|---|
| name | String | The executable command line, quoted as needed. |
| mode | Int32 | A SAL Window_* presentation constant. |
| retCode | SalNumber | Receives the process exit code, a Win32 creation error, or zero after a caught exception. |
Returns: Boolean. True if creation, waiting, and the exit-code query complete successfully; otherwise, false.
Despite the legacy name, the current wait loop does not pump Windows Forms messages.
LoadAppAndWait(name, mode, retCode)
Starts a process, disables tracked forms while it runs, and waits for its exit.
| Parameter | Type | Description |
|---|---|---|
| name | String | The executable command line, quoted as needed. |
| mode | Int32 | A SAL Window_* presentation constant. |
| retCode | SalNumber | Receives the process exit code, a Win32 creation error, or zero after a caught exception. |
Returns: Boolean. True if creation, waiting, and the exit-code query complete successfully; otherwise, false.
LoadSkinFile(path)
Enables skinning and loads the specified skin file.
| Parameter | Type | Description |
|---|---|---|
| path | String | The skin file path. |
LoadSkinResource(name)
Enables skinning and loads a skin from application resources.
| Parameter | Type | Description |
|---|---|---|
| name | String | The embedded skin resource name. |
LoadSkinResource(assembly, name)
Enables skinning and loads a skin from the specified assembly.
| Parameter | Type | Description |
|---|---|---|
| assembly | Assembly | The assembly containing the skin resource. |
| name | String | The embedded skin resource name. |
OnAppCreateAutomaticForms()
Creates automatically opened forms after startup completes successfully.
Override to create and show the application's initial forms. The base implementation does nothing.
OnAppExit()
Runs the application exit action and supplies the process exit code.
Returns: Int32. The exit code; the base implementation returns zero.
OnAppStartup()
Runs the application startup action on the first idle notification.
Override to implement SAM_AppStartup. The base implementation does nothing.
OnSqlError(Error)
Receives a SQL failure routed to the global application error handler.
| Parameter | Type | Description |
|---|---|---|
| Error | SalSqlError | The SQL error whose Return property can carry the handler result. |
Override to implement SAM_SqlError. The base implementation does nothing.
OnThreadException(sender, args)
Routes UI-thread exceptions through SAL abort/quit handling, optional event logging, and the unhandled-exception hook.
| Parameter | Type | Description |
|---|---|---|
| sender | Object | The event source, passed as a thread when possible. |
| args | ThreadExceptionEventArgs | The exception to process. |
OnUnhandledException(thread, args)
Displays the standard thread-exception dialog, or terminates the process when interaction is unavailable or the user chooses Abort.
| Parameter | Type | Description |
|---|---|---|
| thread | Thread | The thread supplied by the exception dispatcher; not used by the base implementation. |
| args | ThreadExceptionEventArgs | The unhandled exception. |
Pause(usec)
Waits for the requested interval while sleeping briefly and dispatching Windows Forms messages.
| Parameter | Type | Description |
|---|---|---|
| usec | Int32 | The wait duration in milliseconds, despite the legacy parameter name. Zero or negative values return immediately. |
Message dispatch can reenter application code during the wait.
Quit()
Requests closure of every tracked form and then requests Windows Forms application exit, ignoring repeated quit requests.
RemoveForm(form)
Unregisters a tracked form and requests application exit when the lifetime count reaches zero.
| Parameter | Type | Description |
|---|---|---|
| form | Form | The registered form to remove. |
Returns: Int32. The resulting lifetime count, or zero when form tracking is inactive.
RemoveSkin(form)
Removes skin integration for a form.
| Parameter | Type | Description |
|---|---|---|
| form | Form | The form to update. |
No action is taken when application skinning is disabled.
RemoveSkin(control, children)
Removes skin integration for a control and optionally its descendants.
| Parameter | Type | Description |
|---|---|---|
| control | Control | The control to update. |
| children | Boolean | True to include child controls. |
No action is taken when application skinning is disabled.
Run(args)
Processes startup options and runs the Windows Forms message loop until application exit.
| Parameter | Type | Description |
|---|---|---|
| args | String[] | The command-line arguments to expose through the SAL system variables and process for runtime options. |
Returns: Int32. The process exit code, normally supplied by OnAppExit.
Recognized options include /xp, /noxp, /visualstyles=on, /visualstyles=off, and /log or /log=filename.
SetProfileString(section, entry, value, fileName)
Writes or deletes a string setting in an INI file or the configured registry profile store.
| Parameter | Type | Description |
|---|---|---|
| section | String | The section to update. |
| entry | String | The setting name, or null to delete the section. |
| value | String | The string to store, or null to delete the setting. |
| fileName | String | The INI file name, or application subkey when registry profiles are enabled. |
Returns: Boolean. False for a null section or file name, or an unsuccessful INI write; true after a completed registry operation or successful INI write.
Registry access and deletion exceptions propagate to the caller.
StartTrace(outputType, traceFile, clear)
Selects the destination for subsequent application trace messages.
| Parameter | Type | Description |
|---|---|---|
| outputType | Int32 | One of Sys.TRACE_Event, Sys.TRACE_File, Sys.TRACE_Output, or Sys.TRACE_stdout. |
| traceFile | String | The output path when file tracing is selected. |
| clear | Boolean | True to delete an existing trace file before writing new messages. |
Returns: Boolean. True for a supported output type; otherwise, false.
Trace(severity, text)
Writes a message to the configured trace destination.
| Parameter | Type | Description |
|---|---|---|
| severity | Int32 | The event-log entry type when event logging is selected; ignored by other destinations. |
| text | String | The message to write. |
Returns: Boolean. False when tracing has no active supported destination; otherwise, true after dispatching the message.
UseEventLog(useLog, logAndcontinue)
Configures Windows event logging for unhandled UI-thread exceptions.
| Parameter | Type | Description |
|---|---|---|
| useLog | Boolean | True to write exceptions to the event log. |
| logAndcontinue | Boolean | True to return after logging instead of invoking the unhandled-exception hook. |
Returns: Boolean. True after updating the settings.
UseRegistry(useRegistry, companyName)
Switches profile operations between INI files and the current user's registry.
| Parameter | Type | Description |
|---|---|---|
| useRegistry | Boolean | True to use registry profiles; false to use INI files. |
| companyName | String | The subkey under HKEY_CURRENT_USER\Software; null or empty uses the Windows Forms application company name. |
Returns: Boolean. True if registry profiles were enabled before the call; otherwise, false.
Events
SkinChanged
EventHandler Occurs when the loaded skin changes; the sender is the VisualStyler component.