The TJvWizard

The TJvWizard makes implementing an application wizard about as simple as it can be, but it suffers from the same problem as a lot of the Jedi library components; a lack of documentation.  There are a lot of hidden Gems in the JVCL if you have the time to find them, and figure out how to use them.  You always have to have it in the back of your mind that a commercial component may be a better solution, both in terms of support and functionality that meets your requirements.

The TJvWizard is not part of the MegaDemo, and the on-line documentation is sparse.  Most of it appears to have been generated, and there is no general usage suggestions.  I’m not a big fan of the JEDI help system, preferring the EMB on-line class centric help format. The format matters little though without the necessary content.

With a plethora of events exposed, it’s challenging to decide what one to use for what purpose.  I thought I would share my findings in the hope that I might make it easier for others to use this component, and because I might forget at some point ;-)

The OnXXXButttonClick events of the TJvWizardInteriorPage class have a Stop boolean parameter passed by reference.  If you leave the wizard buttons enabled, this is a good event to ensure that the data collected on the wizard page is valid before proceeding.  The downside is that you need to provide some visual feedback to the user to explain why clicking on the ‘Next’ button doesn’t take them to the next step in the wizard if the data is invalid.  I use TJvValidators to show error indicators beside UI elements with invalid data.

You can of course disable buttons when entering a page and dynamically update the buttons when OnChange events occur in other controls triggering validations.  The problem with this approach is that if the Back button is used those change events won’t be triggered and the buttons may not be updated appropriately.  Testing all possible navigation pathways for appropriate behaviour is a must.

I use the TJvWizardInteriorPage.OnExitPage event to collect any data from the UI and populate my domain layer, or other structures if I am not relying on the current value of the UI controls.

The TJvWizardInteriorPage.OnEnterPage event is a good place to initialize controls whose content is dependant on the previous wizard page.  The OnPage event may be even better, but I haven’t tried it.  Both the OnEnterPage and OnExitPage events have a FromPage :TJvWizardCustomPage parameter so you can use the transition context to decide if you want to initialize your controls, or leave them be if the Back button has been used.

Finally I use the TJvWizard.OnSelectNextPage and OnSelectPriorPage events to control page transitions, both forward and backward.  My wizards don’t have overly complicated routes.  I have not used the WizardRouteMap components to date.

IMHO the TjvWizard is another JEDI gem, but if you find it hard to use because of a lack of documentation, or are concerned since the last updates appear to be in 2003, there are other choices out there such as the delphiwizardframework.

Leave a Reply