1.1 --- a/epoc32/include/coecntrl.h Tue Nov 24 13:55:44 2009 +0000
1.2 +++ b/epoc32/include/coecntrl.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -1,1 +1,418 @@
1.4 -coecntrl.h
1.5 +// Copyright (c) 1997-2009 Nokia Corporation and/or its subsidiary(-ies).
1.6 +// All rights reserved.
1.7 +// This component and the accompanying materials are made available
1.8 +// 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
1.9 +// which accompanies this distribution, and is available
1.10 +// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.11 +//
1.12 +// Initial Contributors:
1.13 +// Nokia Corporation - initial contribution.
1.14 +//
1.15 +// Contributors:
1.16 +//
1.17 +// Description:
1.18 +//
1.19 +
1.20 +#ifndef __COECNTRL_H__
1.21 +#define __COECNTRL_H__
1.22 +
1.23 +#include <e32std.h>
1.24 +#include <e32base.h>
1.25 +#include <w32std.h>
1.26 +#include <gulalign.h>
1.27 +#include <coedef.h>
1.28 +#include <coecobs.h>
1.29 +#include <coehelp.h>
1.30 +#include <coeinput.h>
1.31 +#include <coemop.h>
1.32 +#include <coemain.h>
1.33 +#include <coefont.h>
1.34 +#include <coetextdrawer.h>
1.35 +#include <coecontrolarray.h>
1.36 +
1.37 +#include <coecoloruse.h> // class TCoeColorUse
1.38 +
1.39 +class TResourceReader;
1.40 +class CCoeEnv;
1.41 +class MCoeControlContext;
1.42 +class RCoeDynamicDataStorage;
1.43 +
1.44 +class MCoeLayoutManager;
1.45 +class TCoeZoomWithType;
1.46 +class CCoeFontProvider;
1.47 +
1.48 +// forward declarations.
1.49 +class CCoeControl;
1.50 +class CCoeTextDrawerBase;
1.51 +
1.52 +/** Interface to be used if a control elects to be a background drawer.
1.53 +
1.54 +Parent controls can elect to take responsibility for drawing the background for their child
1.55 +controls. To achieve this, they should aggregate an object that implements this interface.
1.56 +CCoeControl::SetBackground() accepts the object and sets it as the background drawer
1.57 +
1.58 +@see CCoeControl::EnableWindowTransparency()
1.59 +@publishedAll
1.60 +@released
1.61 +*/
1.62 +class MCoeControlBackground
1.63 + {
1.64 +public:
1.65 + /** Draw the background for a given control.
1.66 + The text drawer that shall be used to draw text on the specific background can be
1.67 + fetched through the GetTextDrawer() method.
1.68 +
1.69 + @param aGc Graphics context used for drawing
1.70 + @param aControl The control being drawn (may be a child of the drawer)
1.71 + @param aRect The area to be redrawn
1.72 +
1.73 + @publishedAll
1.74 + @released
1.75 + */
1.76 + virtual void Draw(CWindowGc& aGc, const CCoeControl& aControl, const TRect& aRect) const = 0;
1.77 + /**
1.78 + This function retrieves the text drawer associated with the background.
1.79 + @param aTextDrawer The text drawer associated with the background. This may be null. The default implementation
1.80 + always sets this to 0.
1.81 + @param aDrawingControl The control that is requesting the text drawer.
1.82 + */
1.83 + IMPORT_C virtual void GetTextDrawer(CCoeTextDrawerBase*& aTextDrawer, const CCoeControl* aDrawingControl) const;
1.84 +protected:
1.85 + IMPORT_C MCoeControlBackground();
1.86 +private:
1.87 + IMPORT_C virtual void MCoeControlBackground_Reserved1();
1.88 + IMPORT_C virtual void MCoeControlBackground_Reserved2();
1.89 + IMPORT_C virtual void MCoeControlBackground_Reserved3();
1.90 + IMPORT_C virtual void MCoeControlBackground_Reserved4();
1.91 + IMPORT_C virtual void MCoeControlBackground_Reserved5();
1.92 +private:
1.93 + TInt iMCoeControlBackground_Reserved1();
1.94 + };
1.95 +
1.96 +/** Abstract interface for defining a control's hit region.
1.97 +
1.98 +This could be implemented by a CCoeControl-derived class to
1.99 +define hit region checking. The object is installed by calling CCoeControl::SetHitTest().
1.100 +
1.101 +The hit region is the area inside the control's rectangle in which pointer events are handled.
1.102 +It can be any shape, not necessarily rectangular.
1.103 +
1.104 +@publishedAll
1.105 +@released
1.106 +*/
1.107 +class MCoeControlHitTest
1.108 + {
1.109 +public:
1.110 + /** Tests whether a pointer event occurred inside the control's hit region.
1.111 + This function is called by CCoeControl::HandlePointerEventL().
1.112 +
1.113 + @param aPoint The position of the pointer event.
1.114 + @return ETrue if the specified point lies inside the hit region, EFalse if not.
1.115 +
1.116 + @publishedAll
1.117 + @released
1.118 + */
1.119 + virtual TBool HitRegionContains(const TPoint& aPoint, const CCoeControl& aControl) const = 0;
1.120 +protected:
1.121 + IMPORT_C MCoeControlHitTest();
1.122 +private:
1.123 + IMPORT_C virtual void MCoeControlHitTest_Reserved1();
1.124 + IMPORT_C virtual void MCoeControlHitTest_Reserved2();
1.125 +private:
1.126 + TInt iMCoeControlHitTest_Reserved1;
1.127 + };
1.128 +
1.129 +
1.130 +/**
1.131 +Control base class from which all other controls are derived.
1.132 +
1.133 +@publishedAll
1.134 +@released
1.135 +*/
1.136 +class CCoeControl : public CBase, public MObjectProvider
1.137 + {
1.138 +public:
1.139 + enum TZoomType
1.140 + {
1.141 + EAbsoluteZoom, // absolute
1.142 + ERelativeZoom // relative to parent's zoom
1.143 + };
1.144 +public:
1.145 + // Construction and destruction
1.146 + IMPORT_C CCoeControl();
1.147 + IMPORT_C CCoeControl(CCoeEnv* aCoeEnv);
1.148 + IMPORT_C ~CCoeControl();
1.149 + IMPORT_C TBool ComponentArrayExists() const;
1.150 +public: // Virtuals (see more related non-virtuals further down)
1.151 + // Key input
1.152 + IMPORT_C virtual TKeyResponse OfferKeyEventL(const TKeyEvent& aKeyEvent,TEventCode aType);
1.153 + // Visual state
1.154 + IMPORT_C virtual void MakeVisible(TBool aVisible);
1.155 + IMPORT_C virtual void SetDimmed(TBool aDimmed);
1.156 + // Construction
1.157 + IMPORT_C virtual void SetContainerWindowL(const CCoeControl& aContainer);
1.158 + IMPORT_C virtual void ConstructFromResourceL(TResourceReader& aReader);
1.159 + IMPORT_C virtual void ActivateL();
1.160 + // Focus
1.161 + IMPORT_C virtual void PrepareForFocusLossL();
1.162 + IMPORT_C virtual void PrepareForFocusGainL();
1.163 + // Control proximity
1.164 + IMPORT_C virtual void SetAdjacent(TInt aAdjacent);
1.165 + IMPORT_C virtual void SetNeighbor(CCoeControl* aNeighbor);
1.166 + IMPORT_C virtual TBool HasBorder() const; // deprecated from 9.2
1.167 + // Control size
1.168 + IMPORT_C virtual TSize MinimumSize();
1.169 + // Resource change handling
1.170 + IMPORT_C virtual void HandleResourceChange(TInt aType);
1.171 + // Logical color use (for Java)
1.172 + IMPORT_C virtual void GetColorUseListL(CArrayFix<TCoeColorUse>& aColorUseList) const;
1.173 + // User help
1.174 + IMPORT_C virtual void GetHelpContext(TCoeHelpContext& aContext) const;
1.175 + // Text input
1.176 + IMPORT_C virtual TCoeInputCapabilities InputCapabilities() const;
1.177 +public:
1.178 + // Environment
1.179 + inline CCoeEnv* ControlEnv() const;
1.180 + // Container window
1.181 + IMPORT_C RDrawableWindow* DrawableWindow() const;
1.182 + IMPORT_C TBool OwnsWindow() const;
1.183 + IMPORT_C TBool IsBackedUp() const;
1.184 + IMPORT_C void SetContainerWindowL(RWindow& aWindow); // deprecated from 9.2
1.185 + IMPORT_C void SetContainerWindowL(RBackedUpWindow& aWindow); // deprecated from 9.2
1.186 + // Control parent
1.187 + IMPORT_C CCoeControl* Parent();
1.188 + IMPORT_C const CCoeControl* Parent() const;
1.189 + IMPORT_C virtual TInt SetParent(CCoeControl* aParent);
1.190 + // Size and position
1.191 + IMPORT_C TRect Rect() const;
1.192 + IMPORT_C void SetRect(const TRect& aRect);
1.193 + IMPORT_C void SetExtent(const TPoint& aPosition,const TSize& aSize);
1.194 + IMPORT_C void SetExtentToWholeScreen();
1.195 + IMPORT_C TSize Size() const;
1.196 + IMPORT_C void SetSize(const TSize& aSize);
1.197 + IMPORT_C TPoint Position() const;
1.198 + IMPORT_C TPoint PositionRelativeToScreen() const;
1.199 + IMPORT_C void SetPosition(const TPoint& aPosition);
1.200 + IMPORT_C TInt MaximumWidth() const;
1.201 + IMPORT_C TInt SetMaximumWidth(TInt aMaxWidth);
1.202 + // Layout
1.203 + IMPORT_C MCoeLayoutManager* LayoutManager() const;
1.204 + IMPORT_C virtual void SetLayoutManagerL(MCoeLayoutManager* aLayout);
1.205 + IMPORT_C virtual TBool RequestRelayout(const CCoeControl* aChildControl);
1.206 + // Visibility
1.207 + IMPORT_C TBool IsVisible() const;
1.208 + IMPORT_C void SetComponentsToInheritVisibility(TBool aInherit=ETrue);
1.209 + // Dimmed
1.210 + IMPORT_C TBool IsDimmed() const;
1.211 + // State observer
1.212 + IMPORT_C void SetObserver(MCoeControlObserver* aObserver);
1.213 + IMPORT_C MCoeControlObserver* Observer() const;
1.214 + // Focus
1.215 + IMPORT_C TBool IsFocused() const;
1.216 + IMPORT_C void SetFocus(TBool aFocus,TDrawNow aDrawNow=ENoDrawNow);
1.217 + IMPORT_C void SetNonFocusing();
1.218 + IMPORT_C void SetFocusing(TBool aFocusing);
1.219 + IMPORT_C TBool IsNonFocusing() const;
1.220 + // Drawing (see also Draw() below)
1.221 + IMPORT_C void DrawNow() const;
1.222 + IMPORT_C void DrawNow(const TRect &aRect) const;
1.223 + IMPORT_C void DrawDeferred() const;
1.224 + IMPORT_C CWindowGc& SystemGc() const;
1.225 + IMPORT_C TInt SetCustomGc(CWindowGc* aGraphicsContext);
1.226 + IMPORT_C CWindowGc* CustomGc() const;
1.227 + // Control context (background color etc). Deprecated (use MCoeControlBackground)
1.228 + IMPORT_C void SetControlContext(MCoeControlContext* aContext); // deprecated from 9.2
1.229 + IMPORT_C void CopyControlContextFrom(const CCoeControl* aControl); // deprecated from 9.2
1.230 + IMPORT_C MCoeControlContext* ControlContext() const; // deprecated from 9.2
1.231 + // Pointer events
1.232 + IMPORT_C void SetPointerCapture(TBool aCapture=ETrue);
1.233 + IMPORT_C void ClaimPointerGrab(TBool aSendUpEvent=ETrue);
1.234 + IMPORT_C void IgnoreEventsUntilNextPointerUp();
1.235 + IMPORT_C void SetGloballyCapturing(TBool aGlobal);
1.236 + // Pointer hit test
1.237 + IMPORT_C TInt SetHitTest(const MCoeControlHitTest* aHitTestControl);
1.238 + IMPORT_C const MCoeControlHitTest* HitTest() const;
1.239 + // Logical colors
1.240 + IMPORT_C void OverrideColorL(TInt aLogicalColor,TRgb aColor);
1.241 + IMPORT_C TBool GetColor(TInt aLogicalColor,TRgb& aColor) const;
1.242 + // Control background
1.243 + IMPORT_C void DrawBackground(const TRect& aRect) const;
1.244 + IMPORT_C void DrawForeground(const TRect& aRect) const;
1.245 + IMPORT_C const MCoeControlBackground* Background() const;
1.246 + IMPORT_C const MCoeControlBackground* FindBackground() const;
1.247 + IMPORT_C void SetBackground(const MCoeControlBackground* aBackground);
1.248 + // Zooming
1.249 + IMPORT_C void SetZoomFactorL(TInt aZoomFactor, TZoomType aZoomType = ERelativeZoom);
1.250 + IMPORT_C TZoomFactor AccumulatedZoom() const;
1.251 + IMPORT_C const TCoeZoomWithType* ZoomWithType() const;
1.252 + // Font provider (see ScreenFont() below)
1.253 + IMPORT_C const CCoeFontProvider& FindFontProvider() const;
1.254 + IMPORT_C void SetFontProviderL(const CCoeFontProvider& aFontProvider);
1.255 + // Text baseline (virtuals)
1.256 + IMPORT_C virtual TInt TextBaselineOffset(const TSize& aSize) const;
1.257 + IMPORT_C virtual void SetTextBaselineSpacing(TInt aSpacing);
1.258 + // Input capabilities
1.259 + IMPORT_C TCoeInputCapabilities RecursivelyMergedInputCapabilities() const;
1.260 + // Interface access
1.261 + IMPORT_C void SetMopParent(MObjectProvider* aParent);
1.262 + // Instance identification
1.263 + IMPORT_C TInt UniqueHandle() const;
1.264 + IMPORT_C TInt SetUniqueHandle(TInt aUniqueHandle);
1.265 +public: // Pointer events (virtuals)
1.266 + IMPORT_C virtual void HandlePointerEventL(const TPointerEvent& aPointerEvent);
1.267 +protected: // Virtuals. Override to handle these events.
1.268 + IMPORT_C virtual void HandlePointerBufferReadyL(); // See HandlePointerEventL()
1.269 + // Change of focus
1.270 + IMPORT_C virtual void FocusChanged(TDrawNow aDrawNow);
1.271 + // Change of size and position
1.272 + IMPORT_C virtual void SizeChanged();
1.273 + IMPORT_C virtual void PositionChanged();
1.274 +public:
1.275 + // Component control access
1.276 + IMPORT_C virtual TInt CountComponentControls() const;
1.277 + IMPORT_C virtual CCoeControl* ComponentControl(TInt aIndex) const;
1.278 + IMPORT_C TInt Index(const CCoeControl* aControl) const;
1.279 +protected:
1.280 + // Control state
1.281 + IMPORT_C TBool IsActivated() const;
1.282 + IMPORT_C TBool IsBeingDestroyed() const;
1.283 + // Component ownership
1.284 + IMPORT_C void InitComponentArrayL();
1.285 + IMPORT_C CCoeControlArray& Components();
1.286 + IMPORT_C const CCoeControlArray& Components() const;
1.287 + // Container window
1.288 + IMPORT_C RWindow& Window() const;
1.289 + IMPORT_C RBackedUpWindow& BackedUpWindow() const;
1.290 + IMPORT_C void CloseWindow();
1.291 + IMPORT_C void CreateWindowL();
1.292 + IMPORT_C void CreateWindowL(const CCoeControl* aParent);
1.293 + IMPORT_C void CreateWindowL(RWindowTreeNode& aParent);
1.294 + IMPORT_C void CreateWindowL(RWindowGroup* aParent);
1.295 + IMPORT_C void CreateBackedUpWindowL(RWindowTreeNode& aParent);
1.296 + IMPORT_C void CreateBackedUpWindowL(RWindowTreeNode& aParent,TDisplayMode aDisplayMode);
1.297 + IMPORT_C void EnableWindowTransparency();
1.298 + // Size and position
1.299 + IMPORT_C void SetCornerAndSize(TGulAlignment aCorner,const TSize& aSize);
1.300 + IMPORT_C void SetSizeWithoutNotification(const TSize& aSize);
1.301 + // Font access
1.302 + IMPORT_C const CFont& ScreenFont(const TCoeFont& aFont) const;
1.303 + // Text drawer
1.304 + IMPORT_C CCoeTextDrawerBase& TextDrawer(TInt aKey = KErrNotFound) const;
1.305 + // Pointer events
1.306 + IMPORT_C void EnableDragEvents();
1.307 + IMPORT_C void HandleRedrawEvent(const TRect& aRect) const;
1.308 + IMPORT_C void SetAllowStrayPointers();
1.309 + IMPORT_C CCoeControl* GrabbingComponent() const;
1.310 + IMPORT_C TBool CapturesPointer() const;
1.311 + // Drawing
1.312 + IMPORT_C TBool IsReadyToDraw() const;
1.313 + IMPORT_C TBool IsBlank() const;
1.314 + IMPORT_C void SetBlank();
1.315 + IMPORT_C void SetCanDrawOutsideRect();
1.316 + IMPORT_C void ActivateGc() const;
1.317 + IMPORT_C void DeactivateGc() const;
1.318 + IMPORT_C void ResetGc() const;
1.319 + // State events
1.320 + IMPORT_C void ReportEventL(MCoeControlObserver::TCoeEvent aEvent);
1.321 + // Resource changes
1.322 + IMPORT_C void HandleComponentControlsResourceChange(TInt aType);
1.323 + // Copy Constructor and Assignment Operator
1.324 + inline CCoeControl(const CCoeControl& aControl);
1.325 + inline CCoeControl& operator=(const CCoeControl& aControl);
1.326 +protected:
1.327 + friend class CCoeControlArray;
1.328 + IMPORT_C virtual void HandleControlArrayEventL(CCoeControlArray::TEvent aEvent, const CCoeControlArray* aArray, CCoeControl* aControl, TInt aControlId);
1.329 +private: // reserved
1.330 + IMPORT_C virtual void Reserved_CCoeControl_10();
1.331 + IMPORT_C virtual void Reserved_CCoeControl_11();
1.332 + IMPORT_C virtual void Reserved_CCoeControl_12();
1.333 + IMPORT_C virtual void Reserved_CCoeControl_13();
1.334 +private:
1.335 + IMPORT_C virtual void GetTextDrawer(CCoeTextDrawerBase*& aTextDrawer, const CCoeControl* aDrawingControl, TInt aKey) const;
1.336 +private: // reserved
1.337 + IMPORT_C virtual void Reserved_CCoeControl_8();
1.338 + IMPORT_C virtual void Reserved_CCoeControl_9();
1.339 +protected: // from MObjectProvider
1.340 + IMPORT_C TTypeUid::Ptr MopSupplyObject(TTypeUid aId);
1.341 +private: // from MObjectProvider
1.342 + IMPORT_C MObjectProvider* MopNext();
1.343 +private:
1.344 + // Drawing (override this to draw)
1.345 + IMPORT_C virtual void Draw(const TRect& aRect) const;
1.346 +protected:
1.347 + // Debugging
1.348 + IMPORT_C virtual void WriteInternalStateL(RWriteStream& aWriteStream) const;
1.349 +private: // reserved
1.350 + IMPORT_C virtual void Reserved_2();
1.351 +public: // but not exported
1.352 + void ProcessPointerEventL(const TPointerEvent& aPointerEvent);
1.353 + void ProcessPointerBufferReadyL();
1.354 + void RecursivelyMergeInputCapabilities(TCoeInputCapabilities& aInputCapabilities) const;
1.355 + void WriteInternalStateNowL(RWriteStream& aWriteStream) const;
1.356 + void NotifyFontChange(const CCoeFontProvider* aFontProvider);
1.357 + void RemoveFromParent();
1.358 + void RefetchPixelMappingL();
1.359 +public: // deprecated
1.360 + inline TInt SetGc(CWindowGc* aGraphicsContext) const;
1.361 + inline CWindowGc* GetGc() const;
1.362 +private:
1.363 + friend class CCoeRedrawer;
1.364 + void DrawComponents(const TRect& aRect) const;
1.365 + void DrawWindowOwningComponentsNow() const;
1.366 + void DrawWindowOwningComponentsNow(const TRect &aRect) const;
1.367 + void SetGrabbed(TBool aGrabbed);
1.368 + TBool IsGrabbed() const;
1.369 + void DoMakeVisible(TBool aVisible);
1.370 + void CheckPointerEventPurge() const;
1.371 + void RecursivelyMergeTextDrawers(CCoeTextDrawerBase*& aTextDrawer, const CCoeControl* aDrawingControl, TInt aKey) const;
1.372 + CCoeControl* WindowOwningParent();
1.373 + const CCoeControl* WindowOwningParent() const { return const_cast<CCoeControl*>(this)->WindowOwningParent(); }
1.374 + const CCoeControl* SearchParent(const CCoeControl* aParentToFind) const;
1.375 + TInt SetZoomWithType(TCoeZoomWithType* aZoomWithType);
1.376 + TCoeZoomWithType* GetZoomWithType() const;
1.377 + TInt SetFontProvider(const CCoeFontProvider* aFontProvider);
1.378 + const CCoeFontProvider* GetFontProvider() const;
1.379 + TInt FindColor(TInt aLogicalColor) const;
1.380 + void ActivateGcRecursive() const;
1.381 + void DeactivateGcRecursive() const;
1.382 + void ReportControlStateChange(MCoeControlStateObserver::TCoeState aType);
1.383 +public:
1.384 + IMPORT_C void EnableReportControlStateChange(TBool aState);
1.385 +
1.386 +protected:
1.387 + CCoeEnv* iCoeEnv;
1.388 + MCoeControlContext* iContext; // deprecated
1.389 + TPoint iPosition;
1.390 + TSize iSize;
1.391 +private:
1.392 + TInt iFlags;
1.393 + RDrawableWindow* iWin;
1.394 + RCoeDynamicDataStorage* iData;
1.395 + MObjectProvider* iMopParent;
1.396 + };
1.397 +
1.398 +
1.399 +/**
1.400 +Gets the control environment object for this control.
1.401 +
1.402 +@return The control's control environment object.
1.403 +*/
1.404 +inline CCoeEnv* CCoeControl::ControlEnv() const
1.405 + { return(iCoeEnv); }
1.406 +
1.407 +/**
1.408 +Deprecated. See CCoeControl::SetCustomGc().
1.409 +@deprecated
1.410 +*/
1.411 +inline TInt CCoeControl::SetGc(CWindowGc* aGraphicsContext) const
1.412 + { return const_cast<CCoeControl*>(this)->SetCustomGc(aGraphicsContext); }
1.413 +
1.414 +/**
1.415 +Deprecated. See CCoeControl::CustomGc().
1.416 +@deprecated
1.417 +*/
1.418 +inline CWindowGc* CCoeControl::GetGc() const
1.419 + { return CustomGc(); }
1.420 +
1.421 +
1.422 +#endif // __COECNTRL_H__