--- /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 <e32base.h>
+
+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, <code>KAlfRosterShowAtTop</code>,
+ * or <code>KAlfRosterShowAtBottom</code>.
+ */
+ 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. <code>NULL</code>, 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