Singleton (single-instance) Screens

Definition

Singleton screens are screens which should be opened only once by the user, i.e. at most only one instance of such a screen must be open; in case a user attempts to open another instance of such a screen, the already opened screen should be activated instead of a new instance of the screen. There is only one exception to that rule: a Modal instance of a screen that is a Singleton is allowed to be opened in addition to an already opened non-Modal instance (example for that: Partner Find screen).

Declaring a Screen to be a Singleton Screen

Nothing needs to be done to a Form Class or the YAML file for it to make the Form Class a singleton. Rather, one of the two following approaches needs to be followed.

• If the Form can be launched from the Main Menu: add the Element "Singelton=true" to the line in the UINavigation.yml file that defines the menu entry for the Form. If the Form is opened with the Element 'ActionClick' rather than with the Element 'ActionOpenScreen', 'ActionOpenScreen' needs to be specified in addition to the 'ActionClick' Element. Examples: CreateLedger, FindPartners Elements in UINavigation.yml.
• If the Form cannot be launched from the Main Menu: Add the name of the Form's Class (e.g. 'TFrmCountrySetup' for the 'Country Setup' screen) to TFormsList.GSingletonForms at the startup of the application, e.g. in Method 'TPetraClientMain.InitialiseClasses'.

Opening of a Singleton Screen

Once a Singleton Forms is defined (in one of the two ways mentioned above) any such Form that is simply launched with Show() (after constructing an instance of it) will activate an already running instance of itself and close immediately on its own if there was a running instance, and if there was no running instance it will simply open like any other Form.

While this approach works, there is a disadvantage involved: If there is 'expensive' set-up code in the Constructor of the Form (esp. loading of data from the PetraServer) then this will have happened already before the Show() method is issued and therefore avoidable overhead was generated. Therefore there is another means for a developer to open a Form or return the running instance of a Singleton Form, which does not require the Constructor of the Form to be run: use the static Method 'TFormsList.OpenNewOrExistingForm'. This is used e.g. in 'TPartnerMain.FindPartner', which also demonstrates the parametrisation of the Form only in case it wasn't already opened:

public static void FindPartner(Form AParentForm)
{
    bool FormWasAlreadyOpened;

    TPartnerFindScreen frm = (TPartnerFindScreen)TFormsList.OpenNewOrExistingForm(
        typeof(Ict.Petra.Client.MPartner.Gui.TPartnerFindScreen), AParentForm, 
        out FormWasAlreadyOpened, false);

    if (!FormWasAlreadyOpened)
    {
        frm.SetParameters(false, -1);
        frm.Show();
    }
}