Singleton (single-instance) Screens: Difference between revisions

From OpenPetra Wiki
Jump to navigation Jump to search
(Replaced content with "Deprecated: this only applied to the winforms client")
Tag: Replaced
 
Line 1: Line 1:
==Definition==
Deprecated: this only applied to the winforms client
'''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 "<code>Singelton=true</code>" to the line in the <code>UINavigation.yml</code> file that defines the menu entry for the Form. If the Form is opened with the Element '<code>ActionClick</code>' rather than with the Element '<code>ActionOpenScreen</code>', '<code>ActionOpenScreen</code>' needs to be specified in addition to the '<code>ActionClick</code>' Element. Examples: <code>CreateLedger</code>, <code>FindPartners</code> Elements in <code>UINavigation.yml</code>.
* If the Form ''cannot'' be launched from the Main Menu: Add the name of the Form's Class (e.g. '<code>TFrmCountrySetup</code>' for the 'Country Setup' screen) to <code>TFormsList.GSingletonForms</code> at the startup of the application, e.g. in Method '<code>TPetraClientMain.InitialiseClasses</code>'.
 
 
==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 <code>Show()</code> (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 <code>Show()</code> 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 '<code>TFormsList.OpenNewOrExistingForm</code>'. This is used e.g. in '<code>TPartnerMain.FindPartner</code>', 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();
    }
}

Latest revision as of 20:53, 11 May 2022

Deprecated: this only applied to the winforms client