|
1 /* |
|
2 * Copyright (c) 2006 Nokia Corporation and/or its subsidiary(-ies). |
|
3 * All rights reserved. |
|
4 * This component and the accompanying materials are made available |
|
5 * under the terms of "Eclipse Public License v1.0" |
|
6 * which accompanies this distribution, and is available |
|
7 * at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
8 * |
|
9 * Initial Contributors: |
|
10 * Nokia Corporation - initial contribution. |
|
11 * |
|
12 * Contributors: |
|
13 * |
|
14 * Description: |
|
15 * |
|
16 */ |
|
17 |
|
18 |
|
19 #ifndef AKNINPUTBLOCK_H |
|
20 #define AKNINPUTBLOCK_H |
|
21 |
|
22 #include <coecntrl.h> |
|
23 #include <eikcmobs.h> |
|
24 |
|
25 // FORWARD DECLARATIONS |
|
26 class CEikButtonGroupContainer; |
|
27 class CEikAppUi; |
|
28 |
|
29 |
|
30 /** |
|
31 * MAknInputBlockCancelHandler is an interface to an object that |
|
32 * can handle the UI framework attempting to cancel a CAknInputBlock. |
|
33 * @since 3.1 |
|
34 */ |
|
35 class MAknInputBlockCancelHandler |
|
36 { |
|
37 public: |
|
38 virtual void AknInputBlockCancel() = 0; |
|
39 }; |
|
40 |
|
41 |
|
42 /** |
|
43 * CAknInputBlock blocks user input, key and pen, from reaching |
|
44 * existing controls, such as softkeys, dialogs or main panes. |
|
45 * It will not block controls higher on the control stack than |
|
46 * ECoeStackPriorityDialog. |
|
47 * It will not block subsequently created dialogs. |
|
48 * It will detect attempts from the UI framework to cancel the |
|
49 * blocked state. |
|
50 * Clients should supply something to handle such cancel requests. |
|
51 * There are three ways that cancel can be signalled: through |
|
52 * an M-class interface, by cancelling an active object, by |
|
53 * deleting a CBase derived object. |
|
54 * All three cancel methods can be active. When a cancel signal |
|
55 * is detected, the handlers will be triggered in the order of |
|
56 * M-class first, then active object cancel, finally CBase delete. |
|
57 * If no cancel hander is supplied, all input is blocked, including |
|
58 * framework attempts to deactivate views and exit the application. |
|
59 * |
|
60 * This is an example of use of all cancel methods with an active object that |
|
61 * blocks with a CActiveSchedulerWait... |
|
62 * CAknInputBlock* inputBlock = CAknInputBlock::NewCancelHandlerLC(this); // notify "this" on cancel |
|
63 * CAOWait* wait = CAOWait::NewL(); // create waiting active object |
|
64 * inputBlock->SetCancelActive(wait); // set it as an active object to cancel |
|
65 * inputBlock->SetCancelDelete(wait); // set it as an object to delete, takes ownership |
|
66 * wait->Start(); |
|
67 * inputBlock->SetCancelHandler(NULL); // Clear the cancel handler so that "this" is not notified by cancel on deletion |
|
68 * CleanupStack::PopAndDestroy(inputBlock); // wait will be cancelled and deleted by inputBlock |
|
69 * |
|
70 * @since 3.1 |
|
71 */ |
|
72 NONSHARABLE_CLASS(CAknInputBlock) : public CCoeControl, public MEikCommandObserver |
|
73 { |
|
74 public: |
|
75 /** |
|
76 * Create a new input blocker with no cancel support. |
|
77 * Cancel handling can be set later with one of the |
|
78 * SetCancel... methods. |
|
79 * Note: while this object exists without cancel support, |
|
80 * view deactivations and application exit requests will not be processed. |
|
81 * @return a new instance of CAknInputBlock on the cleanup stack |
|
82 */ |
|
83 IMPORT_C static CAknInputBlock* NewLC(); |
|
84 /** |
|
85 * Create a new input blocker with M-class cancel support. |
|
86 * @param aHandlerToCancel, a pointer to the M-class instance |
|
87 * to call back on cancel. Does not take ownership. Can be |
|
88 * called with NULL to clear the cancel handler. |
|
89 * @return a new instance of CAknInputBlock on the cleanup stack |
|
90 */ |
|
91 IMPORT_C static CAknInputBlock* NewCancelHandlerLC(MAknInputBlockCancelHandler* aHandlerToCancel); |
|
92 /** |
|
93 * Create a new input blocker with active object cancel support. |
|
94 * @param aActiveObjectToCancel, a pointer to the active object |
|
95 * to cancel. Does not take ownership. Can be called with |
|
96 * NULL to clear the cancel handler. |
|
97 * @return a new instance of CAknInputBlock on the cleanup stack |
|
98 */ |
|
99 IMPORT_C static CAknInputBlock* NewCancelActiveLC(CActive* aActiveObjectToCancel); |
|
100 /** |
|
101 * Create a new input blocker with object delete cancel support. |
|
102 * @param aObjectToDelete, a pointer to the CBase-derived object |
|
103 * to delete on cancel. Take ownership. Can be called with |
|
104 * NULL to clear the cancel handler. |
|
105 * @return a new instance of CAknInputBlock on the cleanup stack |
|
106 */ |
|
107 IMPORT_C static CAknInputBlock* NewCancelDeleteLC(CBase* aObjectToDelete); |
|
108 /** |
|
109 * destructor |
|
110 * This will also call Cancel() |
|
111 */ |
|
112 IMPORT_C ~CAknInputBlock(); |
|
113 |
|
114 /** |
|
115 * Set a cancel handler. |
|
116 * @param aHandlerToCancel, a pointer to the M-class instance |
|
117 * to call back on cancel. Does not take ownership. Can be |
|
118 * called with NULL to clear the cancel handler. |
|
119 */ |
|
120 IMPORT_C void SetCancelHandler(MAknInputBlockCancelHandler* aHandlerToCancel); |
|
121 /** |
|
122 * Set a cancel handler. |
|
123 * @param aActiveObjectToCancel, a pointer to the active object |
|
124 * to cancel. Does not take ownership. Can be called with |
|
125 * NULL to clear the cancel handler. |
|
126 */ |
|
127 IMPORT_C void SetCancelActive(CActive* aActiveObjectToCancel); |
|
128 /** |
|
129 * Set a cancel handler. |
|
130 * @param aObjectToDelete, a pointer to the CBase-derived object |
|
131 * to delete on cancel. Take ownership. Can be called with |
|
132 * NULL to clear the cancel handler. |
|
133 */ |
|
134 IMPORT_C void SetCancelDelete(CBase* aObjectToDelete); |
|
135 |
|
136 /** |
|
137 * Called when the UI framework wants to cancel this input |
|
138 * blocking state, eg on app exit. |
|
139 * May also be called manually to force cancel. |
|
140 * After cancelling, all handers are set to NULL. |
|
141 */ |
|
142 IMPORT_C void Cancel(); |
|
143 |
|
144 private: |
|
145 CAknInputBlock(); |
|
146 void ConstructL(); |
|
147 |
|
148 bool IsCancellable() const; |
|
149 |
|
150 private: // from CCoeControl |
|
151 TKeyResponse OfferKeyEventL(const TKeyEvent& aKeyEvent, TEventCode aType); |
|
152 void FocusChanged(TDrawNow aDrawNow); |
|
153 |
|
154 private: // from MEikCommandObserver |
|
155 void ProcessCommandL(TInt /*aCommandId*/); |
|
156 |
|
157 private: |
|
158 MAknInputBlockCancelHandler* iHandlerToCancel; // not owned |
|
159 CActive* iActiveObjectToCancel; // not owned |
|
160 CBase* iObjectToDelete; // owned |
|
161 CEikAppUi* iAppUi; // not owned |
|
162 CEikButtonGroupContainer* iCba; // owned |
|
163 }; |
|
164 |
|
165 |
|
166 |
|
167 |
|
168 #endif |