2 * Copyright (c) 2002 Nokia Corporation and/or its subsidiary(-ies).
4 * This component and the accompanying materials are made available
5 * under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
6 * which accompanies this distribution, and is available
7 * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
9 * Initial Contributors:
10 * Nokia Corporation - initial contribution.
19 #ifndef __AKNDIALOG_H__
20 #define __AKNDIALOG_H__
27 class CAknDialogAttributes;
30 * Base class for different types of @c AknDialogs
32 * Instances of the @c CAikDialog class may be created, and it is possible to
33 * add controls directly to them. However it is more normal to create a
34 * subclass, and to handle the controls appearing on the dialog dynamically.
36 class CAknDialog : public CEikDialog, public MEikMenuObserver
41 * C++ default constructor.
43 IMPORT_C CAknDialog() ;
46 * Handles Symbian 2nd phase construction.
48 * A menu resource MUST be specified - this function will Panic
49 * otherwise. If a menu is not required use @c CEikDialog!
51 * @param aMenuTitleResourceId Title of the menu.
53 IMPORT_C void ConstructL( TInt aMenuTitleResourceId ) ;
58 IMPORT_C ~CAknDialog() ;
63 * Loads, displays, and destroys the dialog.
65 * This function loads the specified dialog from a resource and
66 * displays it. The method then destroys the dialog when it exits,
67 * therefore there is no need for the application program to
70 * @param aResourceId The resource ID of the dialog to load.
71 * @return Zero, unless it is a waiting dialog. For a waiting dialog,
72 * the return value is the ID of the button that closed the
73 * dialog, or zero if it was the cancel button
76 IMPORT_C TInt ExecuteLD( TInt aResourceId ) ;
81 * Prepares the dialog, by constructing it from the specified resource.
83 * @param aResourceId The resource ID of the dialog.
85 IMPORT_C void PrepareLC(TInt aResourceId);
90 * Runs the dialog and returns the ID of the button used to dismiss it.
92 * The dialog is destroyed on exit.
94 * This function is called by the dialog framework (@c ExecuteLD()) to
95 * perform dynamic construction (layout) and to display/destroy the
96 * dialog. Static construction of the dialog must already be complete
97 * before this function is called, e.g. using @c PrepareLC().
99 * The function returns immediately unless @c EEikDialogFlagWait has
100 * been specified in the @c DIALOG resource. If @c EEikDialogFlagWait
101 * is specified, it returns when the dialog exits.
103 * @return The ID of the button used to dismiss the dialog.
105 IMPORT_C TInt RunLD();
107 // From MEikMenuObserver
109 * From @c MEikMenuObserver.
111 * Called by the Uikon framework to handle the emphasising or
112 * de-emphasising of a menu window.
114 * @c CEikMenuBar objects call this on their observer to emphasise
115 * themselves when they are displayed, and de-emphasise themselves when
116 * they stop displaying.
118 * @param aMenuControl The menu control.
119 * @param aEmphasis @c ETrue to emphasize the menu,
120 * @c EFalse otherwise.
122 IMPORT_C virtual void SetEmphasis( CCoeControl* aMenuControl,
127 * @param aResourceId Not used.
128 * @param aMenuPane Not used.
130 IMPORT_C virtual void DynInitMenuPaneL( TInt aResourceId,
131 CEikMenuPane* aMenuPane ) ;
134 * From @c MEikMenuObserver.
138 * @param aCommandId Not used.
140 IMPORT_C virtual void ProcessCommandL( TInt aCommandId ) ;
145 * From @c CCoeControl.
147 * Handles key events.
149 * If a control wishes to process key events, it should implement this
150 * function. The implementation must ensure that the function returns
151 * @c EKeyWasNotConsumed if it does not do anything in response to a
152 * key event, otherwise, other controls or dialogs may be prevented
153 * from receiving the key event. If it is able to process the event
154 * it should return @c EKeyWasConsumed.
156 * When a key event occurs, the control framework calls this function
157 * for each control on the control stack, until one of them can process
158 * the key event (and returns @c EKeyWasConsumed).
160 * Each keyboard key press results in three separate events:
161 * @c EEventKeyDown, @c EEventKey, and @c EEventKeyUp, in that order.
163 * To receive key events, which can be processed by this function,
164 * the application should call @c CCoeAppUi::AddToStackL() to add the
165 * control to the stack. This only applies, however, to controls which
166 * are not components of a compound control. Compound controls should
167 * pass key events to their components as necessary: the components
168 * themselves do not go on the stack.
170 * @param aKeyEvent The key event.
171 * @param aType The type of key event: @c EEventKey, @c EEventKeyUp or
173 * @return Indicates whether or not the key event was used by
176 IMPORT_C TKeyResponse OfferKeyEventL(const TKeyEvent& aKeyEvent,
180 * From @c CCoeControl.
182 * Responds to a change in focus.
184 * This is called whenever the control gains or loses focus, as a
185 * result of a call to @c SetFocus(). A typical use of
186 * @c FocusChanged() is to change the appearance of the control,
187 * for example by drawing a focus rectangle around it.
189 * @param aDrawNow Contains the value that was passed to it by
192 IMPORT_C void FocusChanged(TDrawNow aDrawNow);
195 * From @c CCoeControl.
197 * Handles pointer events.
199 * This function gets called whenever a pointer event occurs in the
200 * control, i.e. when the pointer is within the control's extent,
201 * or when the control has grabbed the pointer. The control should
202 * implement this function to handle pointer events.
204 * Note: events of type @c EButton1Down are processed before
205 * @c HandlePointerEventL() is called, in order to transfer keyboard
206 * focus to the control in which the @c EButton1Down event occurred.
208 * @param aPointerEvent The pointer event
210 IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent);
212 private: // formerly from MTopSetMember<CEikMenuBar>, now reserved
214 IMPORT_C virtual void Reserved_MtsmPosition();
216 IMPORT_C virtual void Reserved_MtsmObject();
223 IMPORT_C void* ExtensionInterface( TUid aInterface );
228 * From @c CEikDialog.
230 * Handles a dialog button press for the specified button.
232 * This function is invoked when the user presses a button in the
233 * button panel. It is not called if the Cancel button is activated
234 * unless the @c EEikDialogFlagNotifyEsc flag has been set.
236 * If there is an Options key then pops up menu, otherwise exits.
238 * The function should be overridden by the derived class, and is
239 * usually used to validate the values of the dialog's controls.
240 * The function should return @c ETrue if it is OK to exit, and
241 * @c EFalse to keep the dialog active. It should always return
242 * @c ETrue if the button with ID @c EEikBidOK was activated.
244 * @param aButtonId The ID of the button that was activated.
245 * @return @c ETrue to validate and exit the dialog,
246 * @c EFalse to keep the dialog active. If @c ETrue, the
247 * dialog will be destroyed automatically by @c ExecuteLD().
248 * The default implementation returns @c ETrue no matter which
251 IMPORT_C virtual TBool OkToExitL( TInt aButtonId ) ;
254 * From @c CEikDialog.
258 IMPORT_C void DisplayMenuL() ;
261 * From @c CEikDialog.
265 IMPORT_C void HideMenu() ;
268 * From @c CEikDialog.
270 * Checks if menu is displayed.
272 * @return @c ETrue if menu is displayed,
273 * @c EFalse otherwise.
275 IMPORT_C TBool MenuShowing() const ;
278 * From @c CEikDialog.
280 * Lays out the dialog's components when the size of the dialog
283 IMPORT_C virtual void SizeChanged();
286 * From @c CEikDialog.
290 * @param aRect Area to be drawn.
292 IMPORT_C virtual void Draw(const TRect &aRect) const;
294 protected: // from MObjectProvider
297 * From @c MObjectProvider.
299 * Gets Mop supply object of the given type.
301 * @param aId Identifier for the supply object.
302 * @return Pointer to the supply object type ID.
304 IMPORT_C TTypeUid::Ptr MopSupplyObject(TTypeUid aId);
308 IMPORT_C virtual void CEikDialog_Reserved_1();
310 IMPORT_C virtual void CEikDialog_Reserved_2();
312 private: // new function
314 IMPORT_C virtual void CAknDialog_Reserved();
316 protected: // new function
319 * Creates or replaces dialog's menu bar.
321 * @param aMenuTitleResourceId Title of the menu bar.
323 void CreateMenuBarL(TInt aMenuTitleResourceId);
331 CEikMenuBar* iMenuBar;
337 EAknDialogFlagDialogDeleted = 1,
338 EAknDialogFlagDefaultSounds = 2,
339 EAknDialogFlagNotConstructed = 4
342 CAknDialogAttributes* iAttributes; // Was TInt iSpare;
344 CAknDialogAttributes* AttributesL();
348 #endif // __AKNDIALOG_H__