1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/epoc32/include/mw/eiktbar.h Wed Mar 31 12:33:34 2010 +0100
1.3 @@ -0,0 +1,411 @@
1.4 +/*
1.5 +* Copyright (c) 2002-2006 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 "Eclipse Public License v1.0"
1.9 +* which accompanies this distribution, and is available
1.10 +* at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.11 +*
1.12 +* Initial Contributors:
1.13 +* Nokia Corporation - initial contribution.
1.14 +*
1.15 +* Contributors:
1.16 +*
1.17 +* Description: Class declaration for EIKON toolbar control.
1.18 +*
1.19 +*/
1.20 +
1.21 +
1.22 +#ifndef __EIKTBAR_H__
1.23 +#define __EIKTBAR_H__
1.24 +
1.25 +#include <eikctgrp.h>
1.26 +#include <coecobs.h>
1.27 +#include <eikbtgrp.h>
1.28 +#include <eikbtgpc.h>
1.29 +
1.30 +// Forward declarations
1.31 +
1.32 +class MEikCommandObserver;
1.33 +class TEikButtonCoordinator;
1.34 +class CEikCommandButton;
1.35 +class CCoeBrushAndPenContext;
1.36 +
1.37 +/**
1.38 + * A vertical group of controls displayed down the right-hand side of the
1.39 + * screen in an application.
1.40 + *
1.41 + * It contains buttons which are used to issue application commands,
1.42 + * and other controls. A toolband may also be created using this class,
1.43 + * by setting the @c EEikToolBarHorizontal flag and initialising from a
1.44 + * @c TOOLBAND resource.
1.45 + *
1.46 + * @lib eikcoctl.lib
1.47 + * @since S60 0.9
1.48 + */
1.49 +class CEikToolBar : public CEikControlGroup,
1.50 + public MCoeControlObserver,
1.51 + public MEikButtonGroup
1.52 + {
1.53 +public:
1.54 +
1.55 + /**
1.56 + * Destructor.
1.57 + * Deletes the toolbar's brush and pen context and control types.
1.58 + */
1.59 + IMPORT_C ~CEikToolBar();
1.60 +
1.61 + /**
1.62 + * Default C++ constructor.
1.63 + * Creates a new toolbar object, but does not initialise any of
1.64 + * its heap-stored members.
1.65 + */
1.66 + IMPORT_C CEikToolBar();
1.67 +
1.68 + /**
1.69 + * Completes construction of a default-constructed toolbar.
1.70 + *
1.71 + * The command observer interface defines a method for creating custom
1.72 + * controls on the toolbar from user-defined IDs specified in the
1.73 + * resource @c aResourceId.
1.74 + *
1.75 + * IDs for controls which cannot be constructed using
1.76 + * @c EikControlFactory::CreateByTypeL() are passed to this object's
1.77 + * command observer for construction.
1.78 + *
1.79 + * Applications requiring custom controls in their toolbars should
1.80 + * override their AppUI's @c CreateCustomCommandControlL() method,
1.81 + * inherited from @c MEikCommandObserver.
1.82 + *
1.83 + * @param aCommandObserver Sets the command observer for this toolbar.
1.84 + * The observer's @c ProcessCommandL()
1.85 + * function is invoked when a toolbar command
1.86 + * is invoked by the user.
1.87 + * @see MEikCommandObserver::ProcessCommandL().
1.88 + * Typically the observer is the
1.89 + * application's AppUI.
1.90 + *
1.91 + * @param aResourceId The ID of a @c TOOLBAR or @c TOOLBAND
1.92 + * resource structure.
1.93 + *
1.94 + * @param aBoundingRect Defines the rectangle to which the toolbar's
1.95 + * extent must be limited. This is typically given
1.96 + * by @c CEikAppUi::ClientRect(), which returns
1.97 + * the extent of the whole application window,
1.98 + * less the extent of any toolbars that already
1.99 + * exist and are owned by the AppUI.
1.100 + *
1.101 + * @panic EIKCOCTL-36 If the control on the toolbar cannot be
1.102 + * constructed.
1.103 + */
1.104 + IMPORT_C void ConstructL( MEikCommandObserver* aCommandObserver,
1.105 + TInt aResourceId,
1.106 + const TRect& aBoundingRect );
1.107 +
1.108 + /**
1.109 + * Creates a toolbar from a resource definition,
1.110 + * but does not set its extent or activate it.
1.111 + *
1.112 + * This function is used by @c ConstructL(), applications will
1.113 + * not typically need to use it.
1.114 + *
1.115 + * @param aCommandObserver Specifies the object in which
1.116 + * @c HandleCommandL() is called when a toolbar
1.117 + * command is invoked, typically the application's
1.118 + * AppUI.
1.119 + *
1.120 + * @param aResourceId The resource that defines the toolbar.
1.121 + *
1.122 + * @panic EIKCOCTL-36 If the control on the toolbar cannot be
1.123 + * constructed.
1.124 + */
1.125 + IMPORT_C void StaticConstructL( MEikCommandObserver* aCommandObserver,
1.126 + TInt aResourceId );
1.127 +
1.128 + /**
1.129 + * Sets the toolbar's command observer.
1.130 + * Applications will not typically need to use this function.
1.131 + *
1.132 + * @param aCommandObserver The command observer for this toolbar.
1.133 + * When a command is invoked in the toolbar,
1.134 + * @c HandleCommandL() is called in the observer.
1.135 + */
1.136 + IMPORT_C void SetCommandObserver(MEikCommandObserver* aCommandObserver);
1.137 +
1.138 + /**
1.139 + * Sets the button co-ordinator for a group of buttons in a toolbar.
1.140 + *
1.141 + * @param aId Command identifying a toolbar button.
1.142 + * @param aCount The number of buttons in the group.
1.143 + * @param aCoordinator The button coordinator.
1.144 + */
1.145 + IMPORT_C void CoordinateButtons( TInt aId,
1.146 + TInt aCount,
1.147 + TEikButtonCoordinator* aCoordinator );
1.148 +
1.149 + /**
1.150 + * Sets the state of the specified button and draws the button
1.151 + * to show the new state.
1.152 + *
1.153 + * @param aId The command that identifies the button.
1.154 + * @param aState @c ETrue to set the button, @c EFalse to clear the button.
1.155 + */
1.156 + IMPORT_C void SetButtonStateOn(TInt aId,TBool aState);
1.157 +
1.158 + /**
1.159 + * Delays activation of the toolbar when constructed.
1.160 + *
1.161 + * This function sets the toolbar flag @c EEikToolBarDelayActivation.
1.162 + * If this flag is set when @c ConstructL() is called on the toolbar,
1.163 + * the toolbar will be constructed but not activated.
1.164 + *
1.165 + * The application can subsequently activate the toolbar by calling
1.166 + * @c CCoeControl::ActivateL().
1.167 + *
1.168 + * @return @c ETrue to delay activation of the toolbar.
1.169 + */
1.170 + IMPORT_C TBool DelayActivation() const;
1.171 +
1.172 +public: /** From @c CCoeControl. */
1.173 +
1.174 + /**
1.175 + * Second-phase construction from a resource.
1.176 + * This is called by @c StaticConstructL() with an appropriate reader.
1.177 + *
1.178 + * From @c CCoeControl
1.179 + *
1.180 + * @param aReader A resource reader pointing at a @c TOOLBAR or
1.181 + * @c TOOLBAND resource defining the toolbar.
1.182 + * @panic EIKCOCTL-36 If the control on the toolbar cannot be constructed.
1.183 + */
1.184 + IMPORT_C void ConstructFromResourceL(TResourceReader& aReader);
1.185 +
1.186 + /**
1.187 + * Sets the toolbar dimmed or not dimmed.
1.188 + * Dimming usually indicates that user input is not accepted.
1.189 + *
1.190 + * From @c CCoeControl
1.191 + *
1.192 + * @param aDimmed @c ETrue to set as dimmed ,
1.193 + * @c EFalse to set as not dimmed.
1.194 + */
1.195 + IMPORT_C void SetDimmed(TBool aDimmed);
1.196 +
1.197 + /**
1.198 + * Gets the list of logical colours used to draw the control.
1.199 + * Appends the list to @c aColorUseList paired with an explanation
1.200 + * of how the colours are used.
1.201 + *
1.202 + * From @c CCoeControl
1.203 + *
1.204 + * @param[in,out] aColorUseList The list of logical colours.
1.205 + */
1.206 + IMPORT_C void GetColorUseListL(CArrayFix<TCoeColorUse>& aColorUseList) const;
1.207 +
1.208 + /**
1.209 + * Handles a change to the control's resources.
1.210 + *
1.211 + * The types of resources handled are those which are shared across
1.212 + * the environment, e.g. colours or fonts. For colour scheme changes,
1.213 + * @c DrawDeferred() is called in order to redraw the control.
1.214 + *
1.215 + * If overriding this method, the implementation must
1.216 + * include a base call to this method.
1.217 + *
1.218 + * From @c CCoeControl.
1.219 + *
1.220 + * @param aType The type of resource that has changed.
1.221 + */
1.222 + IMPORT_C void HandleResourceChange(TInt aType);
1.223 +
1.224 + /**
1.225 + * Handles pointer events.
1.226 + *
1.227 + * This function gets called whenever a pointer event occurs in the
1.228 + * control, i.e. when the pointer is within the control's extent, or when
1.229 + * the control has grabbed the pointer.
1.230 + *
1.231 + * If overriding this method, the implementation must
1.232 + * include a base call to this method.
1.233 + *
1.234 + * From @c CCoeControl.
1.235 + *
1.236 + * @param aPointerEvent The pointer event.
1.237 + */
1.238 + IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent);
1.239 +
1.240 +public: /** From @c CEikControlGroup. */
1.241 +
1.242 + /**
1.243 + * Adds a control to the control group.
1.244 + *
1.245 + * From @c CEikControlGroup
1.246 + *
1.247 + * @param aControl The control to add to the control group
1.248 + * @param aId The control's ID.
1.249 + * @panic EIKCOCTL-26 If the control does not exist.
1.250 + */
1.251 + IMPORT_C void AddControlL(CCoeControl* aControl,TInt aId);
1.252 +
1.253 + /**
1.254 + * Adds a control wrapped with its ID and length to the control group.
1.255 + *
1.256 + * From @c CEikControlGroup
1.257 + *
1.258 + * @param aGroupControl The wrapped control to add.
1.259 + * @panic EIKCOCTL-26 If the control does not exist.
1.260 + */
1.261 + IMPORT_C void AddControlL(TEikGroupControl& aGroupControl);
1.262 +
1.263 +public: // but not exported
1.264 +
1.265 + /**
1.266 + * Adds a control type to the control type array.
1.267 + *
1.268 + * @internal
1.269 + *
1.270 + * @param aType The control type to be added.
1.271 + */
1.272 + void AddControlTypeL(TInt aType);
1.273 +
1.274 + /**
1.275 + * Removes a control type from the control type array.
1.276 + *
1.277 + * @internal
1.278 + *
1.279 + * @param aIndex Index of the control type to be removed
1.280 + * in the control type array.
1.281 + */
1.282 + void RemoveControlType(TInt aIndex);
1.283 +
1.284 + /**
1.285 + * Used to check if a control is a button type control or not.
1.286 + *
1.287 + * @internal
1.288 + *
1.289 + * @param aIndex Index of the control.
1.290 + * @return @c ETrue, if the control is a button type control.
1.291 + */
1.292 + TBool ControlIsButton(TInt aIndex) const;
1.293 +
1.294 +public: /** From @c MEikButtonGroup. */
1.295 +
1.296 + /**
1.297 + * Sets the toolbar's bounding rectangle.
1.298 + * This function has a different effect on the toolbar's extent,
1.299 + * depending on whether the toolbar is vertical or horizontal.
1.300 + *
1.301 + * For a vertical toolbar, sets the toolbar height to equal the
1.302 + * height of the bounding rectangle.
1.303 + *
1.304 + * For a horizontal toolbar (toolband), sets the toolband width
1.305 + * to equal the width of the bounding rectangle.
1.306 + *
1.307 + * From @c MEikButtonGroup
1.308 + *
1.309 + * @param aBoundingRect The toolbar's bounding rectangle.
1.310 + */
1.311 + IMPORT_C void SetBoundingRect(const TRect& aBoundingRect);
1.312 +
1.313 + /**
1.314 + * Shrinks a rectangle to exclude the toolbar area.
1.315 + * This function reduces the size of the rectangle passed into the
1.316 + * function so that on return, the area occupied by the toolbar or toolband
1.317 + * is removed from the rectangle. It is provided to prevent drawing
1.318 + * over an existing toolbar or toolband.
1.319 + *
1.320 + * From @c MEikButtonGroup
1.321 + *
1.322 + * @param[in,out] aBoundingRect Specifies a rectangle which, on return,
1.323 + * is shrunk to exclude the toolbar’s extent.
1.324 + */
1.325 + IMPORT_C void ReduceRect(TRect& aBoundingRect) const;
1.326 +
1.327 +protected:
1.328 +
1.329 + /**
1.330 + * Writes the internal state of the control and its
1.331 + * components to @c aWriteStream.
1.332 + * Does nothing in release mode.
1.333 + *
1.334 + * Designed to be overridden and base called from subclasses.
1.335 + *
1.336 + * From @c CCoeControl
1.337 + *
1.338 + * @param[in,out] aWriteStream A connected write stream.
1.339 + */
1.340 + IMPORT_C void WriteInternalStateL(RWriteStream& aWriteStream) const;
1.341 +
1.342 +private:
1.343 +
1.344 + CEikCommandButton* ButtonByIndex(TInt aIndex) const;
1.345 + void SetCurrentId(TInt aPosition,TInt aId);
1.346 + TInt CurrentId(TInt aPosition) const;
1.347 + TEikGroupControl& GroupControlByIndex(TInt aIndex) const;
1.348 + TInt IndexFromPosition(TInt aPos) const;
1.349 +
1.350 +private: /** From @c MEikButtonGroup */
1.351 +
1.352 + void SetCommandL( TInt aPosition,
1.353 + TInt aCommandId,
1.354 + const TDesC* aText,
1.355 + const CFbsBitmap* aBitmap,
1.356 + const CFbsBitmap* aMask );
1.357 +
1.358 + void SetCommandL(TInt aPosition,TInt aResourceId);
1.359 + void SetCommandSetL(TInt aResourceId);
1.360 + void AddCommandL( TInt aPosition,
1.361 + TInt aCommandId,
1.362 + const TDesC* aText,
1.363 + const CFbsBitmap* aBitmap,
1.364 + const CFbsBitmap* aMask );
1.365 + void AddCommandToStackL( TInt aPosition,
1.366 + TInt aCommandId,
1.367 + const TDesC* aText,
1.368 + const CFbsBitmap* aBitmap,
1.369 + const CFbsBitmap* aMask );
1.370 + void AddCommandToStackL(TInt aPosition,TInt aResourceId);
1.371 + void AddCommandSetToStackL(TInt aResourceId);
1.372 + void SetDefaultCommand(TInt aCommandId);
1.373 + TSize CalcMinimumSizeL(TInt aResourceId);
1.374 + void RemoveCommandFromStack(TInt aPosition,TInt aCommandId);
1.375 + TInt CommandPos(TInt aCommandId) const;
1.376 + void DimCommand(TInt aCommandId,TBool aDimmed);
1.377 + TBool IsCommandDimmed(TInt aCommandId) const;
1.378 + void MakeCommandVisible(TInt aCommandId,TBool aVisible);
1.379 + TBool IsCommandVisible(TInt aCommandId) const;
1.380 + CCoeControl* AsControl();
1.381 + const CCoeControl* AsControl() const;
1.382 + CCoeControl* GroupControlById(TInt aCommandId) const;
1.383 + CEikCommandButton* GroupControlAsButton(TInt aCommandId) const;
1.384 + TInt CommandId(TInt aCommandPos) const;
1.385 + TInt ButtonCount() const;
1.386 + TUint ButtonGroupFlags() const;
1.387 +
1.388 + void SetMSKCommandObserver(MEikCommandObserver* aCommandObserver);
1.389 + void DimCommandByPosition(TInt aPosition,TBool aDimmed);
1.390 + TBool IsCommandDimmedByPosition(TInt aPosition) const;
1.391 + void MakeCommandVisibleByPosition(TInt aPosition,TBool aVisible);
1.392 + TBool IsCommandVisibleByPosition(TInt aPosition) const;
1.393 + void AnimateCommandByPosition(TInt aPosition);
1.394 +
1.395 +private: /** From @c MCoeControlObserver */
1.396 + IMPORT_C void HandleControlEventL(CCoeControl* aControl,TCoeEvent aEvent);
1.397 +
1.398 +private:
1.399 + IMPORT_C void Reserved_2();
1.400 +
1.401 +private: /** From @c CAknControl */
1.402 +
1.403 + IMPORT_C void* ExtensionInterface( TUid aInterface );
1.404 +private:
1.405 + void BaseConstructL();
1.406 + TInt ControlCount() const;
1.407 +private:
1.408 + TInt iToolBarFlags;
1.409 + MEikCommandObserver* iCommandObserver;
1.410 + CCoeBrushAndPenContext* iBrushAndPenContext;
1.411 + CArrayFix<TInt>* iControlTypes;
1.412 + };
1.413 +
1.414 +#endif // __EIKTBAR_H__