The CategoryDialog class creates and controls a dialog that has more than one panel. It is similar to the notebook control available in OS/2 or the property sheet available in the Windows 95 user interface.
Depending on the style you choose, you can switch among different pages by either clicking radio buttons or selecting an item from a drop down list. Each page has its own window controls.
CatDlg.cls is the source file of this class.
::requires "oodialog.cls"
The CategoryDialog class is a subclass of UserDialog (see UserDialog Class).
Instances of the CategoryDialog class have the following attributes:
A directory describing the layout and behavior of the dialog. This directory is usually set up in the InitCategories method of the dialog (see InitCategories for more information).
An internal counter
Instances of the CategoryDialog class implement the methods listed in the following table.
Note: In fact, most of the methods do the same as the methods in the parent class, UserDialog, except that they are enabled to work with a category dialog.
| Method... | ...on page |
|---|---|
| AddCategoryComboEntry | AddCategoryComboEntry |
| AddCategoryListEntry | AddCategoryListEntry |
| CategoryComboAddDirectory | CategoryComboAddDirectory |
| CategoryComboDrop | CategoryComboDrop |
| CategoryListAddDirectory | CategoryListAddDirectory |
| CategoryListDrop | CategoryListDrop |
| CategoryPage | CategoryPage |
| ChangeCategoryComboEntry | ChangeCategoryComboEntry |
| ChangeCategoryListEntry | ChangeCategoryListEntry |
| ChangePage | ChangePage |
| CreateCategoryDialog | CreateCategoryDialog |
| CurrentCategory | CurrentCategory |
| DefineDialog | DefineDialog |
| DeleteCategoryComboEntry | DeleteCategoryComboEntry |
| DeleteCategoryListEntry | DeleteCategoryListEntry |
| DisableCategoryItem | DisableCategoryItem |
| EnableCategoryItem | EnableCategoryItem |
| FindCategoryComboEntry | FindCategoryComboEntry |
| FindCategoryListEntry | FindCategoryListEntry |
| FocusCategoryItem | FocusCategoryItem |
| GetCategoryAttrib | GetCategoryAttrib |
| GetCategoryCheckBox | GetCategoryCheckBox |
| GetCategoryComboEntry | GetCategoryComboEntry |
| GetCategoryComboItems | GetCategoryComboItems |
| GetCategoryComboLine | GetCategoryComboLine |
| GetCategoryEntryLine | GetCategoryEntryLine |
| GetCategoryListEntry | GetCategoryListEntry |
| GetCategoryListItems | GetCategoryListItems |
| GetCategoryListLine | GetCategoryListLine |
| GetCategoryMultiList | GetCategoryMultiList |
| GetCategoryRadioButton | GetCategoryRadioButton |
| GetCategoryValue | GetCategoryValue |
| GetCurrentCategoryComboIndex | GetCurrentCategoryComboIndex |
| GetCurrentCategoryListIndex | GetCurrentCategoryListIndex |
| GetSelectedPage | GetSelectedPage |
| HideCategoryItem | HideCategoryItem |
| Init | Init |
| InitCategories | InitCategories |
| InitDialog | InitDialog |
| InsertCategoryComboEntry | InsertCategoryComboEntry |
| InsertCategoryListEntry | InsertCategoryListEntry |
| MoveCategoryItem | MoveCategoryItem |
| NextPage | NextPage |
| PageHasChanged | PageHasChanged |
| PreviousPage | PreviousPage |
| ResizeCategoryItem | ResizeCategoryItem |
| SendMessageToCategoryItem | SendMessageToCategoryItem |
| SetCategoryAttrib | SetCategoryAttrib |
| SetCategoryCheckBox | SetCategoryCheckBox |
| SetCategoryComboLine | SetCategoryComboLine |
| SetCategoryEntryLine | SetCategoryEntryLine |
| SetCategoryItemFont | SetCategoryItemFont |
| SetCategoryListLine | SetCategoryListLine |
| SetCategoryListTabulators | SetCategoryListTabulators |
| SetCategoryMultiList | SetCategoryMultiList |
| SetCategoryRadioButton | SetCategoryRadioButton |
| SetCategoryStaticText | SetCategoryStaticText |
| SetCategoryValue | SetCategoryValue |
| SetCurrentCategoryComboIndex | SetCurrentCategoryComboIndex |
| SetCurrentCategoryListIndex | SetCurrentCategoryListIndex |
| ShowCategoryItem | ShowCategoryItem |
| StartIt | StartIt |
The following methods are used to set up the pages of the dialog and start it.
>>-aCategoryDialog~Init(--+----------+--,--+------+--,--+------+--,--+-------+--,-->
+-DlgData.-+ +-catx-+ +-caty-+ +-catcx-+
>--+--------------------+--,--+----------+--,--+----------+--,--+--------+--,------>
+-"--+-DROPDOWN-+--"-+ +-cattable-+ +-catlabel-+ +-catmax-+
+-TOPLINE--+
+-WIZARD---+
>--+-------+--)---><
+-hFile-+
The Init method initializes the category dialog object.
The arguments are:
A stem variable (do not forget the trailing period) that contains initialization data for some or all dialog items. If the dialog is terminated by means of the OK button, the values of the dialog's data fields are copied to this variable. The ID of the dialog items is used to name the entry within the stem.
The position of the category selection control group (radio buttons or combo box). The defaults are 10 and 4.
This argument sets the length of one item of the control group (calculated if omitted)
This argument determines the style of the category dialog. Without one of the following keywords, the category selection is done by a vertical radio button group:
Creates a drop-down list at the top (useful if there are many categories)
Draws a horizontal radio button group at the top of the client area
Adds Backward and Forward buttons with IDs 11 and 12 to switch between category pages
Without DROPDOWN and TOPLINE the default category selection is done by a vertical radio button group, with the dialog pages to the right of the radio buttons.
This argument can be used to set the category names separated by blanks. If omitted, set the category names in the InitCategories method.
This argument defines the label for the combo box in DROPDOWN style (default is "Page:")
This argument sets the split point of the radio button group in default style, or the number of entries in the combo box drop-down list.
The file name of a header file containing symbolic ID defines for resources.
The following example creates a category dialog, using a combo box as the selection control:
dlg = MyCategoryDialog~new(MyData., , , ,"DROPDOWN", ,
"Movies Cinemas Days Ticket","Dialog panel:")
dlg~createCenter(200,180,"Let's go to the movies")
dlg~execute("SHOWTOP")
...
::class MyCategoryDialog subclass CategoryDialog
::method Movies /* define the Movies page */
...
::method Cinemas /* define the Cinemas page */
...An additional example can be found under the Init method, in the BaseDialog section. This example shows the use of the dialog data stem and header file arguments in more detail.
>>-aCategoryDialog~InitCategories------------------------------><
The InitCategories method is called by Init to set the characteristics of the category dialog.
This method is protected.
The InitCategories should set up the Catalog directory with information about the layout and the behavior of the dialog. The directory entries are:
An array containing the names of the categories. The array is initialized with the names given in the Init method (argument cattable). These names are used as labels for page selection control and as messages sent to the object to define the single pages.
Your subclass must provide a method for each category page--with the same name as the label in this directory--to define the dialog page using LoadItems to load the dialog items from a resource script or Add... methods. Notice that blanks are removed when you call the Define... methods.
If your subclass provides methods with the prefix Init followed by the name of the categories (blanks removed), these methods are called by InitDialog to initialize the dialog (each page is a dialog) that contains the corresponding category.
Unless you already specified the categories with the Init method, you must assign an array to this Catalog entry.
Number of categories
For internal use only
For internal use only
For internal use only
A directory with the following entries:
Name of the font used for the dialog
Size of the font
Style of the dialog (see Create)
Total number of expected dialog items of all category pages (200)
Width of Backward and Forward push buttons (see WIZARD in Init method)
Alternate label of Backward button
Alternate label of Forward button
The next four entries should not be modified:
Horizontal position of the category pages relative to the parent dialog
Vertical position of the category pages relative to the parent dialog
Width of the category pages
Height of the category pages
The following example sets the category names to Text Editor, Compiler, Linker, and Debugger. The subclass of CategoryDialog must define four methods named after them.
::class MyCategoryDialog subclass CategoryDialog
::method InitCategories
self~catalog["names"]= .array~of("Text Editor","Compiler","Linker", ,
"Debugger")
self~catalog["page"]["leftbtntext"] = "&Previous"
self~catalog["page"]["rightbtntext"] = "&Next"
::method TextEditor /* blanks are removed when the message is sent
from DefineDialog */
/* add control to the first page */
.
.
.
::method Compiler
.
.
.
::method InitTextEditor /* called by InitDialog */
/* initialize the first dialog */
.
.
.>>-aCategoryDialog~DefineDialog--------------------------------><
The DefineDialog method is called after the main dialog has been created. This method must not be overwritten in a subclass because it defines the layout of the frame window and calls the definition methods for each category page.
This method is protected.
Assume that you have the categories "Common Data", "Company Data", and "Special". The following methods are automatically called by DefineDialog to add dialog items to the associated page:
to add controls to the first category page.
to add controls to the second category page.
to add controls to the third category page.
See InitCategories for more information.
>>-aCategoryDialog~CategoryPage--------------------------------><
The CategoryPage method adds controls to the base window of a Category Dialog. It is used to define the layout of the parent dialog that contains the single pages.
This method is protected and should not be overwritten or called. Use the InitCategories method to set up the dialog.
>>-aCategoryDialog~CreateCategoryDialog(--x--,--y--,--cx--,--cy--,--> >--+----------+--,--+----------+--,--options--,--expected--)--->< +-fontName-+ +-fontSize-+
The CreateCategoryDialog method creates the category dialog.
This method is protected. It is called by another method and usually does not have to be called manually.
>>-aCategoryDialog~InitDialog----------------------------------><
The InitDialog method is called after the Windows dialog has been created and before the category dialog is to be displayed.
Do not override this method to initialize your category dialog pages but define an Init... method for each of your pages that you want to initialize like adding combo and list box items. If your subclassed dialog defines a method that has the prefix "Init" followed by the name of the category (without blanks), this method is called by InitDialog to handle the initialization of the corresponding page. If you use a method that requires a category specifier, such as AddCategoryComboEntry or GetTreeControl, and you omit the category, OODialog assumes that the dialog item addressed is part of the page that contains the current category.
This method is protected.
Assume that you have the categories "Common Data", "Company Data", and "Special". The following methods are automatically called when provided by the subclass:
to initialize the first category.
to initialize the second category.
to initialize the third category.
See InitCategories for more information.
>>-aCategoryDialog~GetSelectedPage-----------------------------><
The GetSelectedPage method is used internally to return the currently selected page using the combo box or radio buttons (1 indicates the first page).
>>-aCategoryDialog~CurrentCategory-----------------------------><
The CurrentCategory method returns the number of the current dialog page. The first page is numbered 1.
The following example tests the current page number:
if MyCategoryDialog~CurrentCategory=2 then do ...
>>-aCategoryDialog~NextPage------------------------------------><
The NextPage method switches the dialog to the next category page.
>>-aCategoryDialog~PreviousPage--------------------------------><
The PreviousPage method switches the dialog to the previous category page.
>>-aCategoryDialog~ChangePage(--+---------+--)-----------------><
+-NewPage-+
The ChangePage method switches the dialog to another page and returns the new page number. It is also called by selection control to activate the selected page. ChangePage invokes PageHasChanged after the new page is activated.
The only argument is:
The page number of the new page (default is the page selected by the combo box or radio button)
The following example activates the second category page:
MyCategoryDialog~ChangePage(2)
>>-aCategoryDialog~PageHasChanged(--oldpage--,--newpage--)-----><
The PageHasChanged method is invoked by ChangePage when a new page is activated. The default implementation returns without an action. The user can override this method to react to page changes.
The arguments are:
The page number of the previous page
The page number of the new page
>>-aCategoryDialog~StartIt-------------------------------------><
The StartIt method is called by the Execute or ExecuteAsync methods to create a real Windows object based on a dialog template. In the CategoryDialog class the Windows object(s) are created in the DefineDialog method. Therefore, the StartIt method is overridden in this class to change the default behavior of the superclass. (If unchanged the superclass would create a second duplicate Windows object from the dialog template.)
You might override this method in your subclass, but be sure to forward the message to the parent method and to return the result to the caller.
This is a template for overridding this method:
::class MyCatDlg subclass CategoryDialog ::method StartIt say "this is method "StartIt" !" self~StartIt:super() handle = result ... return handle