SalApplication
Namespace: PPJ.Runtime.Windows
Assembly: PPJ.Web.50 (5.0.0.0)
Coordinates the Web SAL application lifecycle, top-level forms, settings, tracing, and client scripting.
- C#
- VB.NET
public class SalApplication
Public Class SalApplication
Example:
using PPJ.Runtime.Windows;
class MyApplication : SalApplication
{
protected override void OnAppStartup()
{
SalApplication.Title = "My application";
}
}
Constructors
SalApplication()
Initializes a new instance of SalApplication.
Properties
ApplicationType
Type: Gets the concrete type of the registered application instance.
CompanyName
String: Gets or sets the application company name.
Null assignments become an empty string.
DefaultPrinterSettings
PrinterSettings: Gets or sets the shared default printing configuration.
First access creates settings with ten-unit margins and the executable base name as PrintFileName. Assigning null causes recreation on the next read.
Instance
SalApplication: Gets the application instance resolved by the SAL instance registry.
Title
String: Gets or sets the application title.
Null assignments become an empty string.
TopLevelForms
Form[]: Gets a snapshot of the registered top-level forms.
Returns an empty array when none have been registered.
Version
Int32: Gets the cached SAL compatibility version of the executing assembly.
Computed as 900 plus ten times the major version plus the minor version.
Methods
AddForm(form)
Registers a top-level form and increments the application reference count once.
| Parameter | Type | Description |
|---|---|---|
| form | Form | The top-level form to register or unregister. |
Returns: Int32. The number of registered forms.
Null forms raise ArgumentNullException.
Disable()
Disables all registered top-level forms.
Returns: Boolean. True.
Enable()
Enables all registered top-level forms.
Returns: Boolean. True.
EndTrace()
Disables tracing and releases its event-log object.
Returns: Boolean. True.
GetProfileInt(section, entry, defaultValue, fileName)
Reads an unsigned integer from an INI file or the configured registry profile.
| Parameter | Type | Description |
|---|---|---|
| section | String | The profile section name. |
| entry | String | The entry name; null for section removal when writing. |
| defaultValue | UInt32 | The value returned when an entry is absent. |
| fileName | String | The INI file path, or application subkey name in registry mode. |
Returns: UInt32. The stored value, or the supplied default when the entry is absent.
GetProfileString(section, entry, defaultValue, value, fileName)
Reads a string from an INI file or the configured registry profile.
| Parameter | Type | Description |
|---|---|---|
| section | String | The profile section name. |
| entry | String | The entry name; null for section removal when writing. |
| defaultValue | String | The value returned when an entry is absent. |
value  | SalString | Receives the stored string or default value. |
| fileName | String | The INI file path, or application subkey name in registry mode. |
Returns: Int32. The character count assigned to the output string.
INI reads use a 2048-character buffer.
InvokeScript(script)
Evaluates JavaScript in the current Web client through the platform application API.
| Parameter | Type | Description |
|---|---|---|
| script | String | The JavaScript source to evaluate in the Web client. |
LoadApp(name, args)
Starts a native process from an application name and argument string without waiting.
| Parameter | Type | Description |
|---|---|---|
| name | String | The application command or executable name. |
| args | String | The command-line arguments appended to the executable name. |
Returns: Boolean. True if the process starts and its exit-code query succeeds; otherwise, false.
Runs on the host executing the application. Failures are traced.
LoadAppAndWait(name, mode, retCode)
Starts a native process and waits for it to exit, then reactivates the previous active form.
| Parameter | Type | Description |
|---|---|---|
| name | String | The application command or executable name. |
| mode | Int32 | A Sys.Window_* display mode. |
| retCode | SalNumber | Receives the process exit code, native creation error, or zero after a caught exception. |
Returns: Boolean. True if creation and the exit-code query succeed; otherwise, false.
Runs on the host executing the application.
OnAppCreateAutomaticForms()
Provides the hook for creating startup forms after OnAppStartup.
The base implementation creates no forms.
OnAppExit()
Provides the application exit hook and exit code.
Returns: Int32. Zero in the base implementation.
OnApplicationExit(sender, args)
Raises the SAL application-exit callback and closes top-level forms.
| Parameter | Type | Description |
|---|---|---|
| sender | Object | The application or thread event sender. |
| args | EventArgs | Startup name/value arguments, or event data for lifecycle and exception callbacks. |
Exceptions during this cleanup are traced.
OnAppStartup()
Provides the application startup hook before automatic forms are created.
The base implementation does nothing.
OnSqlError(Error)
Provides the application-level SQL error hook.
| Parameter | Type | Description |
|---|---|---|
| Error | SalSqlError | The SQL error delivered to the application. |
The base implementation does nothing.
OnThreadException(sender, args)
Routes thread exceptions through SAL abort/quit handling, optional event logging, and OnUnhandledException.
| Parameter | Type | Description |
|---|---|---|
| sender | Object | The application or thread event sender. |
| args | ThreadExceptionEventArgs | Startup name/value arguments, or event data for lifecycle and exception callbacks. |
Abort exceptions are ignored; quit exceptions close the application. Log-and-continue mode returns after logging other exceptions.
OnUnhandledException(thread, args)
Handles an exception not consumed by SAL abort, quit, or event-log processing.
| Parameter | Type | Description |
|---|---|---|
| thread | Thread | The originating thread when supplied by the exception sender. |
| args | ThreadExceptionEventArgs | Startup name/value arguments, or event data for lifecycle and exception callbacks. |
The base implementation rethrows args.Exception while preserving its dispatch information.
Quit()
Closes all registered forms and exits the application once.
Repeated calls while quitting are ignored; exit runs even when form closing throws.
Refresh()
Requests a full browser-page reload for the current Web client.
RemoveForm(form)
Unregisters a top-level form and releases its application reference.
| Parameter | Type | Description |
|---|---|---|
| form | Form | The top-level form to register or unregister. |
Returns: Int32. The remaining registered-form count, or zero when no collection exists.
Releasing the last reference exits the application. A null form raises ArgumentNullException when a form collection exists.
Run(args)
Initializes application metadata, arguments, exception handling, and startup callbacks.
| Parameter | Type | Description |
|---|---|---|
| args | NameValueCollection | Startup name/value arguments, or event data for lifecycle and exception callbacks. |
Returns: Int32. Zero after startup processing.
Sets the process current directory to the application startup path. Calls OnAppStartup followed by OnAppCreateAutomaticForms; if no forms keep the application alive, it exits.
SetProfileString(section, entry, value, fileName)
Writes or removes a profile entry in an INI file or configured registry profile.
| Parameter | Type | Description |
|---|---|---|
| section | String | The profile section name. |
| entry | String | The entry name; null for section removal when writing. |
| value | String | The value to write, or receives the value when reading; null removes an entry when writing. |
| fileName | String | The INI file path, or application subkey name in registry mode. |
Returns: Boolean. True on success; false for null section/file names or a failed INI write.
A null entry removes the section; a null value removes the entry. Registry failures can throw.
StartTrace(outputType, traceFile, clear)
Selects a tracing destination and initializes any event-log or file state.
| Parameter | Type | Description |
|---|---|---|
| outputType | Int32 | The Sys.TRACE_* destination. |
| traceFile | String | The trace-file path when file output is selected. |
| clear | Boolean | Whether to delete the existing trace file before tracing. |
Returns: Boolean. True for a supported output type; otherwise, false.
Supported outputs are TRACE_Event, TRACE_File, TRACE_Output, and TRACE_stdout. Setup failures can throw.
Trace(severity, text)
Writes text to the selected trace destination.
| Parameter | Type | Description |
|---|---|---|
| severity | Int32 | The EventLogEntryType numeric severity for event-log output. |
| text | String | The trace text. |
Returns: Boolean. True after writing; false if tracing is inactive or the output type is unknown.
Severity is used only for event-log output; other destinations receive the text without a severity prefix.
UseEventLog(useLog, logAndcontinue)
Configures logging and continuation for unhandled thread exceptions.
| Parameter | Type | Description |
|---|---|---|
| useLog | Boolean | Whether to log unhandled thread exceptions. |
| logAndcontinue | Boolean | Whether to return after logging instead of invoking OnUnhandledException. |
Returns: Boolean. True.
UseRegistry(useRegistry, companyName)
Selects registry-backed or INI-backed profile storage.
| Parameter | Type | Description |
|---|---|---|
| useRegistry | Boolean | True to use the registry; false to use INI files. |
| companyName | String | The company registry subkey, or empty for the application company. |
Returns: Boolean. The previous registry-enabled state.
Registry entries are stored below HKEY_CURRENT_USER Software, company, file name, and section. An empty company name uses Application.CompanyName.