Open topic with navigation

PLUSManagedGui: Using a Splash Screen

The PLUSManagedGui component includes support for displaying a customizable splash screen image (PNG images using alpha-transparency are supported). Splash screens are fairly ubiquitous, and their purpose is to inform the user that the application is initializing.  Using a splash screen is especially useful when applications perform initialization that takes some time before showing the user interface.

Update the Form Constructor

Since you already implemented some additional code in your constructor to initialize objects as required to use PLUSManagedGui, your constructor will need to be updated to first hide the form to prevent it from being displayed prematurely, and it will also need to show the splash screen after the objects are initialized. An example of this modified constructor code is below.

C#

public MainForm()
{

//Hide the main form initially (so the user only sees the splash screen).
Hide();

//Initialize the form's components (this is required for your form to function properly).
InitializeComponent();

//Initialize the License and LicenseGui objects.
m_License = new SampleLicense(licensingGui1);
licensingGui1.ApplicationLicense = (License)m_License;

//Display the splash screen.
licensingGui1.ShowDialog(LicensingGuiDialog.SplashScreen);

}

VB.NET

Public Sub New()

//Hide the main form initially (so the user only sees the splash screen).
Hide()

'Initialize the License and LicenseGui objects.
InitializeComponent()

'Initialize the License and LicenseGui objects.
m_License = New SampleLicense(licensingGui1)
licensingGui1.ApplicationLicense = m_License

'Display the splash screen.
licensingGui1.ShowDialog(LicensingGuiDialog.SplashScreen)

End Sub

Implement Initialization Logic

To initialize the application's licensing objects, the application will need to:

1. Load the license file.
2. Validate the license file (and aliases, if needed).
3. Store the validation result to minimize the number of times the license is validated.

This code would resemble the following:

C#

private void InitializeApplicationSettings(object sender, EventArgs e)
{

m_LastLicenseValidationResult = m_License.LoadFile(Path.Combine(Path.GetDirectoryName(Application.ExecutablePath), "LicenseFile.xml"));
if (m_LastLicenseValidationResult)

m_LastLicenseValidationResult = m_License.Validate();

//TODO: Add your application's initialization logic here.

}

VB.NET

Private Sub InitializeApplicationSettings(sender> As Object, e As EventArgs)

m_LastLicenseValidationResult = m_License.LoadFile(Path.Combine(Path.GetDirectoryName(Application.ExecutablePath), "LicenseFile.xml"))
If m_LastLicenseValidationResult Then

m_LastLicenseValidationResult = m_License.Validate()

End If

'TODO: Add your application's initialization logic here.

End Sub

Please keep in mind that the example logic here is simplified, and lacks support for advanced licensing features such as support for downloadable and volume license files.

Implement Completion Logic

Any logic that should be run when the initialization logic has completed should be implemented in its own method. In many (if not most) cases, this may only include showing the application's primary form or dialog. Here is an example of what this code can look like.

C#

private void SplashWorkCompleted(object sender, EventArgs e)
{

//Show the main form.
Show();

}

VB.NET

Private Sub SplashWorkCompleted(sender As Object, e As EventArgs)

'Show the main form.
Show()

End Sub

Next, open the form in the designer, click on the form (but not any of the controls on the form), click the lightning bolt icon in the properties pane, and double-click on the Shown event to create a handler. Then, add the code similar to the following in the event handler.

C#

private void MainForm_Shown(object sender, EventArgs e)
{

//TODO: Here is where you need to update controls on your form to reflect the updated license status as needed.

//Check the license validation result.
if (!m_LastLicenseValidationResult)
{

//If license validation failed, show the license management form when the application starts.
licensingGui1.ShowDialog(LicensingGuiDialog.LicenseManagement);

}

}

VB.NET

Private SubMainForm_Shown(sender As Object, e As EventArgs) Handles MyBase.Shown

'TODO: Here is where you need to update controls on your form to reflect the updated license status as needed.

'Check the license validation result.
If Not m_LastLicenseValidationResult Then

'If license validation failed, show the license management form when the application starts.
licensingGui1.ShowDialog(LicensingGuiDialog.LicenseManagement)

End If

End Sub

Wire Event Handlers

Once your initialization logic is implemented, you will need to proceed to wire method to handle an event.  The easiest way to do this is to click on the LicensingGui component in the designer, click the lightning bolt icon in the properties pane, and select the newly created InitializeApplicationSettings method from the drop-down list for the SplashDoWork event. Also select the SplashWorkComplete method for the SplashWorkCompleteEvent.

Additional Configuration

The PLUSManagedGui component's LicensingGui object has several properties you can configure for customizing the look and feel of the splash screen. These properties are outlined in the table below, and are all configurable by selecting the LicensingGui component on your form's designer.