The Wizard Reusable Component

This Component enables you to easily add a Wizard style interface to an application, to provide functionality that mimics the wizards of the Forms Developer builders and other Windows products. The component contains the following Form Builder objects:

Usage Notes

Create the canvases that you want to appear as the pages of your wizard. Lay them out just as you would any other canvas. Ensure that each canvas has type 'Stacked' and that the canvas is assigned to the window WIZ_WINDOW. You can create many wizards in one form; just assign all the canvases to this window. You do not need to create a separate window or wizard object for each wizard that you want to display.

The canvases that you create do not need to be all the same size. The wizard will automatically resize itself to the size of the largest View in the canvases that you use.

If you place items from a single block on different canvases (pages of the wizard), you will need to set the item properties Next Navigation Item and Previous Navigation Item to prevent the user from expectedly navigating from page to page when pressing the [Next Item] key. The wizard will not work as expected if you allow the user to navigate in this way. All page-to-page navigation must be performed using the wizard’s buttons.

To display your wizard, call the package function Wizard_Begin supplying a list of the canvases to use as the wizard pages. In many cases this will be all that you need to do as the default code on the Wiz_Bar buttons will take care of the standard behavior.

For specialized requirements you can call two other routines: Wizard_Show, to display a particular page out of sequence; and Wizard_Finish, to hide the wizard dialog box

Creating a Wizard

To create a wizard:

  1. From the Components page of the reusable_components.olb object library, copy or subclass the wizard object group.
  2. Attach the PL/SQL library wizard.pll, which contains the Wizard package, to your module.
  3. Using the Wizard package, display a sequence of canvases as the pages of a Wizard.
  4. Add application-specific code as necessary to the Back, Next, Finish and Cancel buttons. The component already contains code for these but it will usually be necessary to customize this code for each application.

Wizard Class Routines

Wizard.Wizard_Begin 

Description 

Verifies that there at least two pages to display, that all the pages named in the list exist, and that all are assigned to the Wizard window. Resizes the Wizard to fit the largest view of all the listed canvases. Displays the Wizard window in the center of the screen. Returns TRUE if the Wizard successfully displays.

Syntax

FUNCTION Wizard.Wizard_Begin( Pages        VARCHAR2,
TitleString VARCHAR2,
ShowPageNum BOOLEAN);

Returns

BOOLEAN

Parameters

pages A comma-separated list of canvases to display as pages of Wizard
titlestring Text to display as title of Wizard window.
showpagenum Display the text ‘Page m of n’ on each Wizard page

Wizard.Wizard_Show

Description 

Sets the wizard display to the specified page. The application must also navigate to an item on the specified page. Use this routine to implement conditional page sequences or optional pages in a Wizard.

Hint: minimize the use of Wizard_Show to change the order of presented pages. As far as possible, a Wizard should present a simple, linear sequence of pages to the end user.

Syntax

PROCEDURE Wizard.Wizard_Show(  PageNum      NUMBER);

Parameters

PageNum Number of page to display. The first page is numbered 1.

Wizard.Wizard_Finish

Description 

Hide (close) the Wizard window. It is the developer’s responsibility to navigate to an appropriate item; if the focus is left in an item on one of the Wizard pages, Form Builder will automatically redisplay that item, thus negating the effect of Wizard_Finish.

Syntax

PROCEDURE Wizard.Wizard_Finish;

Wizard.Page_Name

Description 

VARCHAR2 package variable. Contains the name of the page (canvas) currently displayed. Do not modify this value. To change the displayed page, use Wizard.Wizard_Show.

Wizard.Page_Number

Description 

NUMBER package variable. Contains the sequence number of the page (canvas) currently displayed. Do not modify this value. To change the displayed page, use Wizard.Wizard_Show.

Wizard.Page_Count

Description 

NUMBER package variable. Contains the total number of pages (canvases) to display in the Wizard. Do not modify this value.