1 /*

     2 * Copyright (c) 2006-2007 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:   Definition of a soft key control class. CHuiSoftKeyControl 

    15 *                is a control that displays the soft key labels and handles 

    16 *                soft key input events.

    17 *

    18 */

    19 

    20 

    21 

    22 #ifndef __HUISOFTKEYCONTROL_H__

    23 #define __HUISOFTKEYCONTROL_H__

    24 

    25 

    26 #include <uiacceltk/HuiControl.h>

    27 #include <uiacceltk/HuiSkin.h>

    28 #include <uiacceltk/HuiImage.h>

    29 

    30 /* Forward declarations. */

    31 class CHuiAppLayout;

    32 class CHuiTextVisual;

    33 class CHuiAnchorLayout;

    34 class CHuiImageBrush;

    35 

    36 /** Softkey button positions. */

    37 enum THuiSoftKeyPosition

    38     {

    39     EHuiSoftKeyUpper,

    40     EHuiSoftKeyLower,

    41     EHuiSoftKeyLeft,

    42     EHuiSoftKeyRight

    43     };

    44 

    45 

    46 /**

    47  * @ deprecated: whole SoftKeyControl functionality is deprecated

    48  *

    49  * CHuiSoftKeyControl displays softkey labels and listens for key input.

    50  *

    51  * Soft key controls always recide either on the bottom of the UI

    52  * (in portrait mode) or at the right side of the UI (in landscape mode).

    53  * No other alignments are currently supported in the Toolkit.

    54  *

    55  * Soft keys automatically align and animate themselves when used. When

    56  * mode is changed from portrait to landscape or vice versa the soft

    57  * key controls first exit to the edge where they were aligned and enter

    58  * from the new location edge. The exit-enter animation is also used to

    59  * to change the softkey labels.

    60  *

    61  * The application user can animate the soft keys manually by calling

    62  * methods in CHuiSoftKeyControl: EnterView() and ExitView()

    63  *

    64  * Furthermore animation duration times can be controlled using

    65  * SetAnimationTimes() -method. If user want's to disable the

    66  * animations altogether (?) she/he can set the animation duration

    67  * times to zero.

    68  */

    69 NONSHARABLE_CLASS(CHuiSoftKeyControl) : public CHuiControl

    70 	{

    71 public:

    72 

    73     /** @beginAPI */

    74 

    75     /**

    76 	 * @ deprecated

    77      *

    78 	 * Mask flags to indicate the controlled softkey label.

    79      * These flags can be used as parameter to the EnterView()

    80      * and ExitView() methods.

    81      */

    82     enum THuiSoftkeyLabel

    83         {

    84         ESoftkeyLabelLeft = 0x1,

    85         ESoftkeyLabelRight = 0x2

    86         };

    87 

    88 	/* Constructors and destructor. */

    89 

    90 	/**

    91 	 * @ deprecated

    92      *

    93 	 * Construct a new softkey control.

    94 	 */

    95 	IMPORT_C static CHuiSoftKeyControl* NewL(CHuiEnv& aEnv);

    96 

    97 	/**

    98 	 * @ deprecated

    99      *

   100 	 * Construct a new softkey control and leave it on the cleanup stack.

   101 	 */

   102 	IMPORT_C static CHuiSoftKeyControl* NewLC(CHuiEnv& aEnv);

   103 

   104 	/**

   105 	 * @ deprecated

   106      *

   107      * Second-phase constructor for constructing the control from a resource

   108 	 * definition.

   109 	 *

   110 	 * @param aReader  Resource reader pointing to the beginning of the

   111 	 *                 control's data.

   112 	 */

   113 	//void ConstructFromResourceL(TResourceReader& aReader);

   114 

   115 	/**

   116 	 * @ deprecated

   117      *

   118 	 * Destructor.

   119 	 */

   120 	IMPORT_C virtual ~CHuiSoftKeyControl();

   121 

   122 

   123 	/* Methods. */

   124 

   125 	/**

   126 	 * @ deprecated

   127      *

   128 	 * Sets the text of the button. The method automatically animates the

   129      * soft key control so that the changed button label is first exit from

   130      * the view and later entered back with new label text.

   131 	 *

   132 	 * @param aKeyPos         Position of the key to change.

   133 	 * @param aText           Softkey label text.

   134 	 * @param aAnimateControl If this argument is true, the whole soft key

   135      *                        control animates (exits and enters view).

   136      *                        Otherwise only the altered softkey label

   137      *                        animates.

   138 	 */

   139 	IMPORT_C void SetLabelL(THuiSoftKeyPosition aKeyPos, const TDesC& aText,

   140                             TBool aAnimateControl = EFalse);

   141 

   142     /**

   143 	 * @ deprecated

   144      *

   145      * Sets background image to the softkeys.

   146      *

   147      * @param aImage            The background image.

   148      * @param aLeftBorderWidth  Width of left border section of the background,

   149      *                          in pixels. This determines should background be

   150      *                          expanded to the left, over the edge of the

   151      *                          visual. Set to  zero to draw only inside

   152      *                          the softkey label.

   153      * @param aLeftBorderWidth  Width of right border section of the background,

   154      *                          in pixels. This determines should background be

   155      *                          expanded to the right, over the edge of the

   156      *                          visual. Set to zero to draw only inside

   157      *                          the softkey label.

   158      */

   159     IMPORT_C void SetBackgroundL(THuiImage aImage, TInt aLeftBorderWidth, TInt aRightBorderWidth);

   160 

   161 	/**

   162 	 * @ deprecated

   163      *

   164 	 * Sets the softkey animation duration times. The duration time specifies

   165      * how fast softkeys enter / exit from the view. Both enter and exit

   166      * animation duration times default to 500 milliseconds.

   167 	 *

   168 	 * @param aEnterTransition Time taken for softkey control to enter the view.

   169      *                         Time duration is specified in milliseconds.

   170 	 * @param aExitTransition  Time taken for softkey control to exit the view.

   171      *                         Time duration is specified in milliseconds.

   172 	 */

   173 	IMPORT_C void SetAnimationTimes(TUint aEnterTransition, TUint aExitTransition);

   174 

   175 	/**

   176 	 * @ deprecated

   177      *

   178 	 * Softkey enters view using entering animation.

   179 	 *

   180 	 * @param aLabelMask Bitwise mask parameter constructed of enumerators in

   181      *                   THuiSoftkeyLabel. With this parameter user can define

   182      *                   whether to animate left softkey, right softkey or both

   183      *                   (default).

   184      * @see THuiSoftkeyLabel.

   185 	 */

   186 	IMPORT_C void EnterView(TUint aLabelMask = ESoftkeyLabelLeft | ESoftkeyLabelRight);

   187 

   188 	/**

   189 	 * @ deprecated

   190      *

   191 	 * Soft key exists view using exit animation.

   192 	 *

   193 	 * @param aLabelMask Bitwise mask parameter constructed of enumerators in

   194      * THuiSoftkeyLabel. With this parameter user can define whether to animate

   195      * left softkey, right softkey* or both (default). @see THuiSoftkeyLabel

   196 	 */

   197 	IMPORT_C void ExitView(TUint aLabelMask = ESoftkeyLabelLeft | ESoftkeyLabelRight);

   198 

   199     /**

   200 	 * @ deprecated

   201      *

   202      * Sets the background type of the softkey control. Affects text labels.

   203      * 

   204      * @param aBackgroundType  Background type.

   205      */

   206     IMPORT_C void SetBackgroundType(THuiBackgroundType aBackgroundType);

   207 

   208     /** @endAPI */

   209 

   210 	/**

   211 	 * @ deprecated

   212      *

   213 	 * Event handler.

   214 	 */

   215 	virtual TBool OfferEventL(const THuiEvent& aEvent);

   216 

   217 	/**

   218 	 * @ deprecated

   219      *

   220 	 * Notifies the soft key control of updated layout of its children.

   221 	 * The positioning of the labels is different depending on display

   222 	 * orientation.

   223 	 */

   224 	void VisualLayoutUpdated(CHuiVisual& aVisual);

   225 

   226 

   227 protected:

   228 

   229     /* Constructors. */

   230 

   231 	/**

   232 	 * @ deprecated

   233      *

   234 	 * Constructor.

   235 	 */

   236 	CHuiSoftKeyControl(CHuiEnv& aEnv);

   237 

   238 	/**

   239 	 * @ deprecated

   240      *

   241 	 * Second-phase constructor.

   242 	 */

   243 	void ConstructL();

   244 

   245 

   246 private:

   247 

   248     /* Private methods */

   249 

   250     /**

   251      * Resets the anchor points of the left and right softkey label

   252      * according to the location where softkeys should be rendered.

   253      *

   254      * @param aSkinLocation One of the four locations where softkeys are drawn

   255      * (top, bottom, left, right).

   256      * @param aShown Boolean value indicating whether the softkeys should be

   257      * visible or hidden.

   258      * @param aLabelMask Mask which defines the modified keys (left, right or both labels). @see THuiSoftkeyLabel.

   259      */

   260     void SetAnchorPoints(THuiSkinLocation aSkinLocation,

   261                          TBool aShown = ETrue,

   262                          TUint aLabelMask = ESoftkeyLabelLeft | ESoftkeyLabelRight);

   263 

   264     /**

   265      * Exits the soft key control. Exit is done to the location specified in the parameter.

   266      *

   267      * @param aTarget Location where the soft keys are exited.

   268      * @param aLabelMask Mask which defines the keys to exit (left, right or both labels). @see THuiSoftkeyLabel.

   269      * @return Time for exit transition. This can be zero or current exit transition time

   270      * depending on whether any animation is played or not.

   271      */

   272     TUint ExitView(THuiSkinLocation aTarget,

   273                    TUint aLabelMask = ESoftkeyLabelLeft | ESoftkeyLabelRight);

   274 

   275     /**

   276      * Custom events that drive the animations in soft key control.

   277      */

   278     enum TCustomEvent

   279         {

   280         ECustomEventEnterView = 200,

   281         ECustomEventUpdateLabel,

   282         ECustomEventUpdateLabels

   283         };

   284 

   285 private:

   286 

   287     /** Label of the left key. */

   288     CHuiTextVisual* iLeftLabel;

   289     HBufC* iLeftText;

   290     /** Background brush for the left key. */

   291     CHuiImageBrush * iLeftLabelImageBrush;

   292 

   293     /** Label of the right key. */

   294     CHuiTextVisual* iRightLabel;

   295     HBufC* iRightText;

   296     /** Background brush for the right key. */

   297     CHuiImageBrush * iRightLabelImageBrush;

   298 

   299     /** Grid layout used to align the label visuals */

   300     CHuiAnchorLayout* iLayout;

   301 

   302     /** Current skin location. This is initialized to none. */

   303     THuiSkinLocation iCurrentLocation;

   304 

   305     /** Exit transition duration time in milliseconds */

   306     TUint iExitTransitionTime;

   307 

   308     /** Enter transition duration time in milliseconds */

   309     TUint iEnterTransitionTime;

   310 	};

   311 

   312 #endif  // __HUISOFTKEYCONTROL_H__