Wiley.Symbian.OS.C.plus.plus.for.Mobile.Phones.Aug.2007 (779890), страница 84
Текст из файла (страница 84)
You mayoverride the behavior if you need to take a more specific action. Theparameter passed to the function is normally the ID of the relevant control,but may be zero if the user is attempting to transfer to a disabled page ina multi-page dialog.Change of StateControls may notify their observers of significant state changes byreporting an EEventStateChanged event. In UIQ, the HandleControlEventL() method handles the control events. In S60, theframework calls the dialog’s HandleControlStateChangeL() function, passing the ID of the relevant control. The default implementationof this function is empty, but may be overridden to perform any requiredaction.46416.4DIALOGSSingle-Page DialogsMost simple dialogs are single-page dialogs. In order to create a dialog, wehave to follow some simple steps.
First, we create the DIALOG resourcein the resource file. For UIQ, the dialog resource is named QIK_DIALOG.Then, we extend our dialog class, from CEikDialog if we are developingfor S60 and from CQikSimpleDialog if we are developing for UIQ.The last step is to launch the dialog.As the Noughts and Crosses application does not have simple pagedialogs, we use the username and password dialog from the QDialogsexample in the UIQ version 3 SDK, as illustrated in Figure 16.8.Figure 16.8 UIQ single-page dialogThe first step is to define the dialog resource:RESOURCE QIK_DIALOG r_dialogs_user_password_dialog{title = STRING_r_dialogs_user_password_dialog_title;configurations ={QIK_DIALOG_CONFIGURATION{ui_config_mode = KQikPenStyleTouchPortrait;container = r_dialogs_user_password_dialog_container;command_list = r_dialogs_user_password_dialog_commands;}};controls = r_dialogs_user_password_dialog_controls;}We define the title, a configuration and a controls collection to bepart of our dialog.
One important aspect to notice at this point isthe title definition; it is defined as an rls_string. This techniqueis very useful when you want to develop applications that supportinternationalization.MULTI-PAGE DIALOGS465The controls collection is a QIK_CONTROL_COLLECTION resourcedefined as follows:RESOURCE QIK_CONTROL_COLLECTION r_dialogs_user_password_dialog_controls{items ={QIK_CONTROL{unique_handle = EDialogsUserPasswordDialogEdwin;type = EEikCtEdwin;control = r_dialogs_user_password_dialog_edwin;},QIK_CONTROL{unique_handle = EDialogsUserPasswordDialogSecretEditor;type = EEikCtSecretEd;control = r_dialogs_user_password_dialog_secret_editor;}};}As you can see, we have a list of control items. For each controlthat is part of our dialog, we specify the control type and the controldefinition.
The first control is an Edwin resource and the second controlis a SecretEd resourceWe then extend our class from CQikSimpleDialog, to handle ourdialog:class CDialogsUserPasswordDialog : public CQikSimpleDialog{public:static TInt RunDlgLD(TDes& aUsername, TDes& aPassword);∼CDialogsUserPasswordDialog();private:CDialogsUserPasswordDialog(TDes& aUsername, TDes& aPassword);void ConstructL();};The minimum amount of code we have to write is for dialog initialization. As our dialog doesn’t have to initialize anything, we do not haveto write any code for this, so our constructor is empty.
Additional codecan be added, for example, code to handle dialog commands or code tohandle control events.Our dialog is ready to be used. We create a CDialogUserPasswordDialog object and call its ExecuteLD() method:userPasswordDialog->ExecuteLD(R_DIALOGS_USER_PASSWORD_DIALOG);46616.5DIALOGSMulti-Page DialogsIf you need to use a dialog that has more lines than can comfortably fitthe screen of a Symbian OS phone, you can split the dialog into a numberof pages and display it as a multi-page dialog. It obviously makes senseto ensure, if at all possible, that the items on each page are more closelyrelated to each other than they are to the items on other pages. Each pageof a multi-page dialog has a label tab, used to navigate from page to page.UIQ VariantFigure 16.9 shows an example from a synchronization application running on a UIQ phone.Figure 16.9 A multi-page dialog on UIQTo create a dialog from a resource file, we use the ViewConstructFromResourceL() method of CQikViewDialog.
The method takestwo parameters: the ID of a QIK_VIEW_CONFIGURATION resource andthe ID for a QIK_CONTROL_COLLECTION resource.The configuration resource looks like this:RESOURCE QIK_VIEW_CONFIGURATIONSr_dialogs_multi_page_dialog_ui_configurations{configurations ={QIK_VIEW_CONFIGURATION{ui_config_mode = KQikPenStyleTouchPortrait;command_list = r_dialogs_multi_page_dialog_commands;view = r_dialogs_multi_page_dialog_layout;},QIK_VIEW_CONFIGURATION{ui_config_mode = KQikPenStyleTouchLandscape;command_list = r_dialogs_multi_page_dialog_commands;view = r_dialogs_multi_page_dialog_layout;MULTI-PAGE DIALOGS467},...QIK_VIEW_CONFIGURATION{...},};}The most important element in the QIK_VIEW_CONFIGURATION isthe view element, which defines a QIK_VIEW.
In this case, it is anotherresource that links to the dialog pages:RESOURCE QIK_VIEW r_dialogs_multi_page_dialog_layout{pages = r_dialogs_multi_page_dialog_layout_pages;}The dialog pages look like this:RESOURCE QIK_VIEW_PAGES r_dialogs_multi_page_dialog_layout_pages{pages ={QIK_VIEW_PAGE{page_id = EDialogsMultiPageDialogPage1;tab_caption = STRING_r_dialogs_multi_page_dialog_page1;container_unique_handle =EDialogsMultiPageDialogPage1ScrollableContainerCtrl;page_content = r_dialogs_multi_page_dialog_page_control;},QIK_VIEW_PAGE{page_id = EDialogsMultiPageDialogPage2;tab_caption = STRING_r_dialogs_multi_page_dialog_page2;container_unique_handle =EDialogsMultiPageDialogPage2ScrollableContainerCtrl;page_content = r_dialogs_multi_page_dialog_page_control;}};}Each page has a content specified by the page_content element.For each page, the content is an array of controls, so the page_contentelement is linked to a scrollable container:RESOURCE QIK_SCROLLABLE_CONTAINER_SETTINGSr_dialogs_multi_page_dialog_page_control{controls ={468DIALOGSQIK_CONTAINER_ITEM_CI_LI{type = ...;control = ...;},QIK_CONTAINER_ITEM_CI_LI{type = ...;control = ...;},...};}The collection resource used to create the dialog is defined by thefollowing code:RESOURCE QIK_CONTROL_COLLECTION r_dialogs_multi_page_dialog_controls{items ={QIK_CONTROL{unique_handle =EDialogsMultiPageDialogPage1ScrollableContainerCtrl;type = EQikCtScrollableContainer;control = r_dialogs_multi_page_dialog_scrollable_container;},QIK_CONTROL{unique_handle =EDialogsMultiPageDialogPage2ScrollableContainerCtrl;type = EQikCtScrollableContainer;control = r_dialogs_multi_page_dialog_scrollable_container;},QIK_CONTROL{unique_handle = EDialogsMultiPageDialogLabelCtrl;type = EEikCtLabel;control = r_dialogs_multi_page_dialog_label;}};}S60 VariantFigure 16.10 shows a multi-page dialog running on an S60 phone.From a programming point of view, most of the differences betweensingle- and multi-page dialogs lie in the dialog’s resource file definitions.A multi-page dialog can be created by using the following resource:RESOURCE DIALOG r_aknexform_double_and_single_line_form{MULTI-PAGE DIALOGS469flags = EEikDialogFlagNoDrag | EEikDialogFlagFillAppClientRect |EEikDialogFlagNoTitleBar | EEikDialogFlagNoBorder |EEikDialogFlagCbaButtons;buttons = R_AVKON_SOFTKEYS_OPTIONS_BACK;pages = r_aknexform_double_and_single_line_form_pages;}Figure 16.10 A multi-page dialog on S60This is a fairly standard, but modeless (no EEikDialogFlagWaitflag) S60 DIALOG resource.
It has an associated menu and so uses Optionsand Back buttons, rather than OK and Cancel, but that does not affect thedescription of the dialog itself.The most important change is that the resource includes a pageselement rather than the items array that is used for single-page dialogs.The pages item specifies the identifier of a second resource:RESOURCE ARRAY r_aknexform_double_and_single_line_form_pages{items ={PAGE{id = EAknExPagePhone;text = "Phone";form = r_aknexform_double_line_text_number_field_form;},PAGE{id = EAknExPageEmail;text = "Email";form = r_aknexform_text_number_field_form;},PAGE{id = EAknExFPageConnection;470DIALOGStextform},PAGE{id =textform}};= "Connection";= r_aknexform_double_line_icon_form;EAknExPageSecurity;= "Security";= r_aknexform_double_line_text_number_with_icon_form;}This is an ARRAY resource, whose elements are PAGE resource structs.The content of this struct varies with the UI, but the first two elements, apage ID and the text to be displayed in the tab for that page, are commonto all UIs.
Like the IDs for individual dialog lines, page IDs should notbe zero and should be unique within that dialog. The IDs used in thisexample are defined, in the application’s HRH file, as follows:enum TAknExFormPageControlIds{EAknExPagePhone = 1,EAknExPageEmail,EAknExPageConnection,EAknExPageSecurity,...};All PAGE structs contain at least one item that specifies a furtherresource and you may specify either a lines or a form item. As a quickreference, the STRUCT PAGE is as follows:STRUCT PAGE // S60{WORD id = 0;LTEXT text;LTEXT bmpfile = "";WORD bmpid = 0xffff;WORD bmpmask;LLINK lines = 0;LLINK form = 0;WORD flags = 0;}Use the lines element if you want to create a standard multi-linedialog.
The resource it specifies is simply an array of DLG_LINE items,exactly like the array used to specify the lines of a single-page dialog:RESOURCE ARRAY r_dialog_page_lines_array{MULTI-PAGE DIALOGS471items ={DLG_LINE{...},...DLG_LINE{...}};}We also have the option to use the form element to specify that thepage is to be handled as a form. In this case, the referenced resource mustbe a FORM struct which specifies, in addition to an array of DLG_LINEstructs, a form-specific flags item. The resource used for the first page ofthe multi-page dialog in the form example application (slightly truncatedto improve clarity) is:RESOURCE FORM r_aknexform_double_line_text_number_field_form{flags = EEikFormUseDoubleSpacedFormat;items ={DLG_LINE{type = EEikCtEdwin;prompt = qtn_aknexform_form_label_edwin;id = EAknExFormDlgCtrlIdAccessPoint;itemflags = EEikDlgItemTakesEnterKey | EEikDlgItemOfferAllHotKeys;control = EDWIN{flags = EEikEdwinNoHorizScrolling | EEikEdwinResizable;width = AKNEXFORM_EDWIN_WIDTH;lines = AKNEXFORM_EDWIN_LINES;maxlength = EAknExFormEdwinMaxLength;...};tooltip = qtn_aknexform_hint_text_edwin;},DLG_LINE{type = EEikCtNumberEditor;prompt = qtn_aknexform_form_label_number;id = EAknExFormDlgCtrlIdPacketData;itemflags = EEikDlgItemTakesEnterKey | EEikDlgItemOfferAllHotKeys;control = NUMBER_EDITOR{min = AKNEXFORM_NUMBER_EDITOR_MIN_VALUE01;max = AKNEXFORM_NUMBER_EDITOR_MAX_VALUE01;};472DIALOGStooltip = qtn_aknexform_hint_text_number;}};}The control IDs must be unique across all pages of the dialog and mustbe non-zero.
The form example application defines them, in its HRH file,in the following way:enum TAknExFormDialogControlIds{EAknExFormDlgCtrlIdAccessPoint = 0x100,...EAknExFormDlgCtrlIdPacketData,...};Apart from avoiding the possibility of confusion in the mind of theprogrammer, there is no particular reason to keep page IDs and controlIDs distinct from each other.Once you have mastered the construction of resources for a multipage dialog, there is very little else you need to know in order touse them. There are a few additional dialog functions to be aware of,such as ActivePageId() and SetPageDimmedNow(). In addition,PageChanged() is called immediately after focus is transferred to acontrol on a different page.