1.1 --- a/epoc32/include/clock.h Tue Nov 24 13:55:44 2009 +0000
1.2 +++ b/epoc32/include/clock.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -1,1 +1,389 @@
1.4 -clock.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 +#if !defined(__CLOCK_H__)
1.21 +#define __CLOCK_H__
1.22 +
1.23 +#if !defined(__E32STD_H__)
1.24 +#include <e32std.h>
1.25 +#endif
1.26 +
1.27 +#if !defined(__E32BASE_H__)
1.28 +#include <e32base.h>
1.29 +#endif
1.30 +
1.31 +#if !defined(__W32STD_H__)
1.32 +#include <w32std.h>
1.33 +#endif
1.34 +
1.35 +//
1.36 +// miscellaneous typedefs
1.37 +//
1.38 +/** @internalComponent */
1.39 +typedef TBuf8<1024> TConstructorBuf8; // implementation class
1.40 +
1.41 +//
1.42 +// miscellaneous enums
1.43 +//
1.44 +
1.45 +/** @internalComponent */
1.46 +enum TDisplayType // implementation class
1.47 + {
1.48 + EDisplayDigital,
1.49 + EDisplayAnalog
1.50 + };
1.51 +
1.52 +/** @internalComponent */
1.53 +enum TAnalogDisplayHandFeatureType // implementation class
1.54 + {
1.55 + EAnalogDisplayHandFeatureLine,
1.56 + EAnalogDisplayHandFeaturePolyLine,
1.57 + EAnalogDisplayHandFeatureCircle
1.58 + };
1.59 +
1.60 +/** Horizontal alignment options for text in a digital clock's display.
1.61 +
1.62 +@see TDigitalDisplayTextSection
1.63 +@publishedAll
1.64 +@released */
1.65 +enum TDigitalDisplayHorizontalTextAlignment
1.66 + {
1.67 + /** Left align text. */
1.68 + EDigitalDisplayHorizontalTextAlignmentLeft,
1.69 + /** Centre align text. */
1.70 + EDigitalDisplayHorizontalTextAlignmentCenter,
1.71 + /** Right align text. */
1.72 + EDigitalDisplayHorizontalTextAlignmentRight
1.73 + };
1.74 +
1.75 +/** Vertical alignment options for text in a digital clock's display.
1.76 +
1.77 +@see TDigitalDisplayTextSection
1.78 +@publishedAll
1.79 +@released */
1.80 +enum TDigitalDisplayVerticalTextAlignment
1.81 + {
1.82 + /** Top align text. */
1.83 + EDigitalDisplayVerticalTextAlignmentTop,
1.84 + /** Centre align text, including the character descent. */
1.85 + EDigitalDisplayVerticalTextAlignmentCenterInclDescent,
1.86 + /** Centre align text, excluding the character descent. */
1.87 + EDigitalDisplayVerticalTextAlignmentCenterExclDescent,
1.88 + /** Bottom align text, including the character descent. */
1.89 + EDigitalDisplayVerticalTextAlignmentBottomInclDescent,
1.90 + /** Bottom align text, excluding the character descent. */
1.91 + EDigitalDisplayVerticalTextAlignmentBottomExclDescent
1.92 + };
1.93 +
1.94 +/** Special characters that can be used in a digital clock display.
1.95 +
1.96 +@see TDigitalDisplayTextSection
1.97 +@publishedAll
1.98 +@released */
1.99 +enum TDigitalDisplayLayoutChar
1.100 + {
1.101 + /** A flashing block to delimit different sections of the display.
1.102 + */
1.103 + /** A flashing block to delimit different sections of the display. */
1.104 + EDigitalDisplayLayoutCharFlashingBlockDelimiter=1
1.105 + };
1.106 +
1.107 +//
1.108 +/** Different types of hand for an analogue clock.
1.109 +
1.110 +@publishedAll
1.111 +@released */
1.112 +enum TAnalogDisplayHandType
1.113 + {
1.114 + /** A hand that performs one revolution every 12 hours. */
1.115 + EAnalogDisplayHandOneRevPer12Hours,
1.116 + /** A hand that performs one revolution every hour. */
1.117 + EAnalogDisplayHandOneRevPerHour,
1.118 + /** A hand that performs one revolution every minute. */
1.119 + EAnalogDisplayHandOneRevPerMinute
1.120 + };
1.121 +
1.122 +//
1.123 +// miscellaneous structs
1.124 +//
1.125 +
1.126 +struct STimeDeviceShadow
1.127 +/** Determines how shadows are added to the clock display.
1.128 +
1.129 +@publishedAll
1.130 +@released */
1.131 + {
1.132 + /** True if shadows should be displayed, else false. */
1.133 + TBool iIsOn;
1.134 + /** Colour of the shadows. */
1.135 + TRgb iColor;
1.136 + /** Offset of shadows from foreground. */
1.137 + TPoint iOffset;
1.138 + };
1.139 +
1.140 +struct SAnalogDisplayAmPm
1.141 +/** Defines the display parameters of the AM/PM display for an analogue clock.
1.142 +
1.143 +@see RAnalogClock
1.144 +@publishedAll
1.145 +@released */
1.146 + {
1.147 + /** Position relative to the clock face. */
1.148 + TPoint iPositionRelativeToFace;
1.149 + /** Size. */
1.150 + TSize iSize;
1.151 + /** Shadow settings. */
1.152 + STimeDeviceShadow iShadow;
1.153 + /** Background colour. */
1.154 + TRgb iBackgroundColor;
1.155 + /** Handle to the font to use. This can be obtained using CFbsFont::Handle().
1.156 +
1.157 + @see CFbsFont::Handle() */
1.158 + TInt iFontHandle;
1.159 + /** Colour for text. */
1.160 + TRgb iTextColor;
1.161 + };
1.162 +
1.163 +//
1.164 +// display-addition classes
1.165 +//
1.166 +
1.167 +
1.168 +class TDisplayAddition
1.169 +/** This class is used in the derivation of TAnalogDisplayHand and TDigitalDisplayTextSection.
1.170 +
1.171 +@internalComponent */
1.172 + {
1.173 +public:
1.174 + const TDesC8& Buf() const;
1.175 +protected:
1.176 + TConstructorBuf8 iBuf;
1.177 + };
1.178 +
1.179 +//
1.180 +
1.181 +class TDigitalDisplayTextSection : public TDisplayAddition
1.182 +/** A text section for a digital clock.
1.183 +
1.184 +@see RDigitalClock
1.185 +@publishedAll
1.186 +@released */
1.187 + {
1.188 +public:
1.189 + IMPORT_C TDigitalDisplayTextSection(TInt aFontHandle, TRgb aTextColor, TDigitalDisplayHorizontalTextAlignment aHorizontalAlignment,
1.190 + TDigitalDisplayVerticalTextAlignment aVerticalAlignment,
1.191 + TInt aHorizontalMargin, TInt aVerticalMargin, const TDesC& aFormat);
1.192 + // N.B. the font passed in to aFontHandle cannot be destroyed until the
1.193 + // RDigitalClock has been completely constructed, including all necessary
1.194 + // calls to RDigitalClock::AddTextSectionL()
1.195 + };
1.196 +
1.197 +//
1.198 +
1.199 +class TAnalogDisplayHand : public TDisplayAddition
1.200 +/** A hand for an analogue clock.
1.201 +
1.202 +A hand is a vector drawing made from a number of features (lines, circles,
1.203 +polylines). These are specified with the hand assumed to be in the 12 o'clock
1.204 +position, with TPoint(0,0) being the center of the clock.
1.205 +
1.206 +@see RAnalogClock
1.207 +@publishedAll
1.208 +@released */
1.209 + {
1.210 +public:
1.211 + IMPORT_C TAnalogDisplayHand(TAnalogDisplayHandType aType);
1.212 + IMPORT_C void AddLine(CGraphicsContext::TPenStyle aPenStyle, TRgb aPenColor, const TSize& aPenSize,
1.213 + const TPoint& aStartPoint, const TPoint& aEndPoint);
1.214 + IMPORT_C void AddPolyLine(CGraphicsContext::TPenStyle aPenStyle, TRgb aPenColor, const TSize& aPenSize,
1.215 + CGraphicsContext::TBrushStyle aBrushStyle, TRgb aBrushColor,
1.216 + TBool aClosed, const CArrayFix<TPoint>* aPointList); // aPointList is not destroyed
1.217 + IMPORT_C void AddCircle(CGraphicsContext::TPenStyle aPenStyle, TRgb aPenColor, const TSize& aPenSize,
1.218 + CGraphicsContext::TBrushStyle aBrushStyle, TRgb aBrushColor,
1.219 + const TPoint& aCircleCenter, TInt aRadius);
1.220 + inline TInt NumFeatures() const
1.221 + /** Gets the number of features added to the hand. */
1.222 + {return *iNumFeaturesPtr;}
1.223 +private:
1.224 + void AppendType(TAnalogDisplayHandFeatureType aType);
1.225 +private:
1.226 + TInt* iNumFeaturesPtr;
1.227 + };
1.228 +
1.229 +//
1.230 +// utility class
1.231 +//
1.232 +
1.233 +class RAnimWithUtils : public RAnim
1.234 +/** Utility class to support clock animation.
1.235 +
1.236 +@publishedAll
1.237 +@released
1.238 +*/
1.239 + {
1.240 +protected:
1.241 + RAnimWithUtils(RAnimDll& aAnimDll, const RWindowBase& aWindow);
1.242 + void AppendToConstructorBufL(const TDesC8& aData);
1.243 + void SendConstructorBufIfCompleteL(TInt aAnimatedObjectType);
1.244 + void SendConstructorBufL(TInt aAnimatedObjectType);
1.245 + TBool ConstructorBufExists() const;
1.246 + TBool ConstructorBufAlreadySent() const;
1.247 + TConstructorBuf8& ConstructorBuf() const;
1.248 + void SetNumAdditionsStillExpected(TInt aNumAdditionsStillExpected);
1.249 +public:
1.250 + IMPORT_C virtual void Close();
1.251 +private:
1.252 + TConstructorBuf8* iConstructorBuf; // on the heap as it is only required for construction
1.253 + TBool iConstructorBufAlreadySent;
1.254 + const RWindowBase& iWindow;
1.255 + TInt iNumAdditionsStillExpected;
1.256 + };
1.257 +
1.258 +//
1.259 +// time-device abstract classes
1.260 +//
1.261 +
1.262 +
1.263 +class RTimeDevice : public RAnimWithUtils
1.264 +/** Sets display parameters for clocks.
1.265 +
1.266 +@publishedAll
1.267 +@released
1.268 +*/
1.269 + {
1.270 +protected:
1.271 + RTimeDevice(RAnimDll& aAnimDll, const RWindowBase& aWindow);
1.272 + void AppendDisplayTypeL(TDisplayType aType);
1.273 + void AppendDigitalDisplayConstructorArgsL(const TPoint& aPosition, const TSize& aSize, const TMargins& aMargins, const STimeDeviceShadow& aShadow,
1.274 + TRgb aBackgroundColor, TInt aNumTextSections);
1.275 + void AppendAnalogDisplayConstructorArgsL(const TPoint& aPosition, const TSize& aSize, const TMargins& aMargins, const STimeDeviceShadow& aShadow,
1.276 + TInt aFaceHandle, TInt aFaceMaskHandle, TInt aNumHands, const SAnalogDisplayAmPm* aAmPm);
1.277 +public:
1.278 + IMPORT_C void SetVisible(TBool aVisible); // can only be called after full construction - by default clocks are invisible
1.279 + IMPORT_C void SetPositionAndSize(const TPoint& aPosition, const TSize& aSize); // can only be called after full construction
1.280 + IMPORT_C void SetPosition(const TPoint& aPosition); // can only be called after full construction
1.281 + IMPORT_C void SetSize(const TSize& aSize); // can only be called after full construction
1.282 + IMPORT_C void UpdateDisplay(); // can only be called after full construction
1.283 + IMPORT_C void Draw(); // can only be called after full construction
1.284 + };
1.285 +
1.286 +//
1.287 +
1.288 +class RClock : public RTimeDevice
1.289 +/** Sets the time for clocks.
1.290 +
1.291 +@publishedAll
1.292 +@released */
1.293 + {
1.294 +protected:
1.295 + RClock(RAnimDll& aAnimDll, const RWindowBase& aWindow);
1.296 + void AppendClockConstructorArgsL(TTimeIntervalSeconds aUniversalTimeOffset);
1.297 +public:
1.298 + IMPORT_C void SetUniversalTimeOffset(TTimeIntervalSeconds aUniversalTimeOffset); // can only be called after full construction
1.299 + };
1.300 +
1.301 +//
1.302 +// time-device concrete classes
1.303 +//
1.304 +
1.305 +class RDigitalClock : public RClock
1.306 +/** A digital clock.
1.307 +
1.308 +A digital clock is composed of one or more text sections, which define
1.309 +how the time information is displayed.
1.310 +
1.311 +@publishedAll
1.312 +@released */
1.313 + {
1.314 +public:
1.315 + IMPORT_C RDigitalClock(RAnimDll& aAnimDll, const RWindowBase& aWindow);
1.316 + IMPORT_C void ConstructL(TTimeIntervalSeconds aUniversalTimeOffset, const TPoint& aPosition, const TSize& aSize, const TMargins& aMargins,
1.317 + const STimeDeviceShadow& aShadow, TRgb aBackgroundColor, TInt aNumTextSections);
1.318 + IMPORT_C void AddTextSectionL(const TDigitalDisplayTextSection& aTextSection);
1.319 + IMPORT_C void SetBackgroundColor(TRgb aBackgroundColor, TRgb aShadowColor); // can only be called after full construction
1.320 + IMPORT_C void SetTextColor(TRgb aTextColor);
1.321 +
1.322 + };
1.323 +
1.324 +//
1.325 +
1.326 +
1.327 +class RAnalogClock : public RClock
1.328 +/** An analogue clock.
1.329 +
1.330 +@see CFbsBitmap::Handle()
1.331 +@publishedAll
1.332 +@released */
1.333 +
1.334 + {
1.335 +public:
1.336 + IMPORT_C RAnalogClock(RAnimDll& aAnimDll, const RWindowBase& aWindow);
1.337 + IMPORT_C void ConstructL(TTimeIntervalSeconds aUniversalTimeOffset, const TPoint& aPosition, const TSize& aSize, const TMargins& aMargins,
1.338 + const STimeDeviceShadow& aShadow, TInt aFaceHandle, TInt aFaceMaskHandle, TInt aNumHands, const SAnalogDisplayAmPm* aAmPm=NULL);
1.339 + // N.B. the bitmap(s) passed in to aFaceHandle and aFaceMaskHandle in these
1.340 + // ConstructL functions cannot be destroyed until the RAnalogClock has been
1.341 + // completely constructed, including all necessary calls to
1.342 + // RAnalogClock::AddHandL() - aFaceMaskHandle may be 0
1.343 + IMPORT_C void AddHandL(const TAnalogDisplayHand& aHand);
1.344 + IMPORT_C void SetBackgroundColor(TRgb aBackgroundColor, TRgb aShadowColor); // can only be called after full construction
1.345 + IMPORT_C void SetTextColor(TRgb aTextColor);
1.346 + IMPORT_C void SetPenColor(const TRgb aPenColor);
1.347 + IMPORT_C void SetBrushColor(const TRgb aBrushColor);
1.348 + };
1.349 +
1.350 +//
1.351 +// message-window class
1.352 +//
1.353 +
1.354 +
1.355 +class RMessageWindow : public RAnimWithUtils
1.356 +/** A configurable window that appears for a brief time to display a message to
1.357 +the user and then disappears.
1.358 +
1.359 +This is the basic class that is used by classes such as CEikonEnv and CEikMsgWin
1.360 +to provide information and message windows. Such higher-level classes would
1.361 +normally be used by client applications rather than RMessageWindow. This class
1.362 +can be used though to implement specialist new classes.
1.363 +
1.364 +Note that this class is in the same library as the Clock API for implementation
1.365 +reasons only.
1.366 +
1.367 +@see CEikMsgWin
1.368 +@see CEikonEnv
1.369 +@publishedAll
1.370 +@released */
1.371 + {
1.372 +public:
1.373 + /** Defines the maximum length of text in the message. */
1.374 + enum
1.375 + {
1.376 + /** Maximum length of text in the message. */
1.377 + EMaxTextLength=80
1.378 + };
1.379 +public:
1.380 + IMPORT_C RMessageWindow(RAnimDll& aAnimDll, const RWindowBase& aWindow);
1.381 + IMPORT_C void ConstructL(TInt aBaselineOffset, TInt aFontHandle, TRgb aBackgroundColor, TRgb aTextColor);
1.382 + IMPORT_C void ConstructL(TInt aBaselineOffset, TInt aFontHandle, TRgb aBackgroundColor, TRgb aTextColor, TRgb aBorderColor);
1.383 + IMPORT_C void StartDisplay(TBool aFlash, TTimeIntervalMicroSeconds32 aInitialDelay, const TDesC& aText);
1.384 + IMPORT_C void StartDisplay(TBool aFlash, TTimeIntervalMicroSeconds32 aInitialDelay, TTimeIntervalMicroSeconds32 aDuration, const TDesC& aText);
1.385 + IMPORT_C void CancelDisplay();
1.386 + IMPORT_C void GetBorders(TMargins& aBorders);
1.387 + IMPORT_C void SetBackgroundColor(TRgb aBackgroundColor);
1.388 + IMPORT_C void SetTextColor(TRgb aTextColor);
1.389 + IMPORT_C void SetBorderColor(TRgb aBorderColor);
1.390 + IMPORT_C void SetPlinthColors(TRgb aTl,TRgb aBr);
1.391 + };
1.392 +
1.393 +#endif