diff -r 000000000000 -r 15bf7259bb7c uiaccelerator_plat/alf_visual_api/inc/alf/alfroster.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/uiaccelerator_plat/alf_visual_api/inc/alf/alfroster.h Tue Feb 02 07:56:43 2010 +0200 @@ -0,0 +1,374 @@ +/* +* Copyright (c) 2006 Nokia Corporation and/or its subsidiary(-ies). +* All rights reserved. +* This component and the accompanying materials are made available +* under the terms of "Eclipse Public License v1.0" +* which accompanies this distribution, and is available +* at the URL "http://www.eclipse.org/legal/epl-v10.html". +* +* Initial Contributors: +* Nokia Corporation - initial contribution. +* +* Contributors: +* +* Description: Roster +* +*/ + + + +#ifndef C_ALFROSTER_H +#define C_ALFROSTER_H + +#include + +class CAlfDisplay; +class CAlfControlGroup; +class TAlfEvent; +class CAlfControl; +class CAlfVisual; +struct TAlfXYMetric; + + +/** Predefined positions for showing groups. */ +const TInt KAlfRosterShowAtTop = -2; +const TInt KAlfRosterShowAtBottom = -1; + +enum TAlfPointerEventFlags + { + EAlfPointerEventReportDrag = 0x01, + EAlfPointerEventReportLongTap = 0x02, + EAlfPointerEventReportUnhandled = 0x04 + }; + +class CAlfRoster; + +/** + * Observer class that can be used to notify users about changes in the + * relative order of control groups in the roster. + * + * The NotifyControlGroupOrderChanged() method will be called when control + * groups are shown or hidden and as a result the relative order the control groups + * are in is modified. The notification is also called when the first control + * group is shown or when the last control group is hidden. + * + * It is on the user's responsibility to remove the callback object from the + * CAlfRoster objects it has been added into before destroying the callback + * object. + * Usage: + * @code + * // Create a control group. + * CAlfControlGroup& group = iEnv->NewControlGroupL( KPrimaryGroup ); + * + * // Add a control to the group. + * AnchorControl* hello = AnchorControl::ConstructL(*iEnv); + * group.AppendL(*hello); + * + * // Show the control group on the display. + * display.Roster().ShowL(group); + * @endcode + * @see CAlfRoster::AddControlGroupOrderChangedObserverL() + * @see CAlfRoster::RemoveControlGroupOrderChangedObserver() + * + * @lib alfclient.lib + * @since S60 v5.0 + */ +class MAlfControlGroupOrderChangedObserver + { +public: + + /** + * Callback method that is called whenever relative order of the control + * groups is modified. This is a result of calls to CAlfRoster::ShowL() + * or CAlfRoster::Hide(). Notification is called after relative order of control + * groups has changed. User can analyze the observed CAlfRoster object for more + * information about the changes. This observer has to be registered to a CAlfRoster + * object to acquire notifications through this method. + */ + virtual void NotifyControlGroupOrderChanged() = 0; + + }; + +/** + * Roster keeps track of the visible control groups. + * + * @lib alfclient.lib + * @since S60 v3.2 + */ +NONSHARABLE_CLASS( CAlfRoster ): public CBase + { + +public: + + /** + * Constructor + */ + CAlfRoster(); + + /** + * ConstructL + * + * @param aDisplay. Associated display. NULL for shared roster. + */ + void ConstructL(CAlfDisplay* aDisplay); + + /** + * Destructor + */ + virtual ~CAlfRoster(); + + /** + * Shows a control group. + * + * @param aGroup Control group. + * @param aWhere Where to show the group. Index, KAlfRosterShowAtTop, + * or KAlfRosterShowAtBottom. + */ + IMPORT_C void ShowL( CAlfControlGroup& aGroup, + TInt aWhere = KAlfRosterShowAtTop); + + /** + * Hides a control group. + * + * @param aGroup Group. + */ + IMPORT_C void Hide(CAlfControlGroup& aGroup); + + /** + * Finds the index of a control group in the roster. + * + * @param aGroup Control group. + * @return Index. KErrNotFound if not found. + */ + IMPORT_C TInt Find(const CAlfControlGroup& aGroup) const; + + /** + * Removes a control group from the roster. + * + * @param aGroup Control group to remove. NULL does nothing. + */ + void Remove(CAlfControlGroup* aGroup); + + /** + * Returns the number of control groups. + * + * @return Number of control groups. + */ + IMPORT_C TInt Count() const; + + /** + * Returns a control group. + */ + IMPORT_C CAlfControlGroup& ControlGroup(TInt aIndex) const; + + /** + * Finds a control inside the roster. + * + * @param aControlId Identifier of the control to find. + * + * @return Pointer to the control. NULL, if not found. + */ + IMPORT_C CAlfControl* FindControl(TInt aControlId) const; + + /** + * Gives input focus to a control. + */ + IMPORT_C void SetFocus(CAlfControl& aControl); + + /** + * Clears the input focus so that no control has focus. + */ + IMPORT_C void ClearFocus(); + + /** + * Moves an existing control group into a new position in the roster. + * + * @param aGroup Moved group. + * @param aPos Position to move into. + */ + TBool Move(CAlfControlGroup& aGroup, TInt aPos); + + /** + * Appends a new control group on top of the roster. + * + * @param aGroup Control group to add. + */ + void AppendL(CAlfControlGroup& aGroup); + + /** + * Inserts a control group into a specific position in the roster. + * + * @param aGroup Control group. + * @param aPos Position to insert into. + * + * @leave KErrAlreadyExists The control group is already in the roster. + */ + void InsertL(CAlfControlGroup& aGroup, TInt aPos); + + /** + * Called when a key event occurs. The input event is offered to the + * controls in the order defined by the groups. + * + * @param aEvent Received event. + * @return ETrue if event was consumed. + */ + TBool HandleEventL(const TAlfEvent& aEvent); + + /** + * Show an individual visual in the roster. The visual is appended to the + * root level visuals of its group. + * + * @param aVisual Visual to show. + */ + IMPORT_C void ShowVisualL(CAlfVisual& aVisual); + + /** + * Hide an individual visual in the roster. + * + * @param aVisual Visual to hide. + */ + IMPORT_C void HideVisual(CAlfVisual& aVisual); + + /** + * Moves a root visual to the front. Causes layout recalculation. + */ + IMPORT_C void MoveVisualToFront(CAlfVisual& aRootVisual); + + /** + * Adds a pointer event observer. + * + * @param aObserver Observer type. + * @param aControl Control which receives the events. + * @return Error code. + */ + IMPORT_C TInt AddPointerEventObserver( + TAlfPointerEventFlags aObserver, + CAlfControl& aControl ); + + /** + * Removes a pointer event observer. + * + * @param aObserver Observer type. + * @param aControl Control which receives the events. + * @return Error code. + */ + IMPORT_C TInt RemovePointerEventObserver( + TAlfPointerEventFlags aObserver, + CAlfControl& aControl ); + + /** + * Sets pointer event observer flags. See TAlfPointerEventFlags for + * possible combinations. + * + * @param aPointerEventFlags Flags. + * @param aControl Control which receives the events. + * @return Error code. + */ + IMPORT_C TInt SetPointerEventObservers( + TUint aPointerEventFlags, + CAlfControl& aControl ); + + /** + * To be called on the display's roster when the display's focus changes state. + * The roster will remove focus from controls if NULL is passed in. It does this without + * changing its FocusedControl(), which becomes a latent focus. + * When ETrue is passed in, the FocusedConrol() is again given control focus. + * + * @param aDisplay The display losing its focus as a whole + * @param aNewFocusState The new focus state + */ + void DisplayFocusChanged( CAlfDisplay& aDisplay, TBool aNewFocusState ); + + /** + * Access to the control to which the roster will send events first. + * + * @return the roster's currently focused control + */ + CAlfControl* FocusedControl() const; + + /** + * Sets treshold that pointer needs to be moved before starting to send + * drag events. Default treshold is 4 pixels in both X and Y direction. + * Control must be added to some pointer event observer array, before + * calling this function. Also removing control from observer will + * reset this treshold. + * + * NOTE: Not every unit type is feasible. Only these types are supported: + * EAlfUnitPixel, EAlfUnitRelativeToDisplay, EAlfUnitS60 + * + * \code + * Display()->Roster().SetPointerEventObservers( EAlfPointerEventReportDrag, *this ); + * Display()->Roster().SetPointerDragThreshold(*this,TAlfXYMetric(TAlfMetric(0.2,EAlfUnitRelativeToDisplay),TAlfMetric(0.1,EAlfUnitRelativeToDisplay))); + * \endcode + * + * @param aControl Control to which treshold affects. + * @param aXYMetric Treshold in metric units. + * @return Error code. + */ + IMPORT_C TInt SetPointerDragThreshold(const CAlfControl& aControl, const TAlfXYMetric& aXYMetric); + + /** + * Disables long tap events when dragging is going on. Default + * functionality is that long tap event will be delivered simultaneously + * with drag events. Control must be added to some pointer event observer + * array, before calling this function. Also removing control from + * observer will reset this feature. + * + * \code + * Display()->Roster().SetPointerEventObservers( EAlfPointerEventReportDrag, *this ); + * Display()->Roster().DisableLongTapEventsWhenDragging(*this); + * \endcode + * + * @param aControl Control to which disabling affects. + * @param aDisable Boolean to indicate whether feature will be disabled + * or not. + * @return Error code. + */ + IMPORT_C TInt DisableLongTapEventsWhenDragging(const CAlfControl& aControl, TBool aDisable = ETrue); + + /** + * Adds the given MAlfControlGroupOrderChangedObserver object to the observer array of this CAlfRoster. + * + * The observer object will be notified whenever relative order of control groups changes in this CAlfRoster. + * + * @see RemoveControlGroupOrderChangedObserver() + * @see MAlfControlGroupOrderChangedObserver + * + * @param aObserver The MAlfControlGroupOrderChangedObserver object to add to the array of active observers. + * + * @since S60 v5.0 + */ + IMPORT_C void AddControlGroupOrderChangedObserverL(MAlfControlGroupOrderChangedObserver& aObserver); + + /** + * Removes the given MAlfControlGroupOrderChangedObserver object from the observer array of this CAlfRoster. + * + * If the MAlfControlGroupOrderChangedObserver object is not found from the array of observers the call + * is ignored. + * + * @see AddControlGroupOrderChangedObserverL() + * @see MAlfControlGroupOrderChangedObserver + * + * @param aObserver MAlfControlGroupOrderChangedObserver object to be searched from the array of observers + * and removed if found. + * + * @since S60 v5.0 + */ + IMPORT_C void RemoveControlGroupOrderChangedObserver(MAlfControlGroupOrderChangedObserver& aObserver); + +private: + + void ChangeInputFocus(CAlfControl* aControl); + void ReportHostsAboutChangingInputFocus( CAlfControl* aOldFocusControl, CAlfControl* aNewFocusControl ); + void NotifyControlGroupOrderChangedObservers(); + +private: + + // Private data. Owned. + struct TPrivateData; + TPrivateData* iData; + + }; + + +#endif // C_ALFROSTER_H