/*
* 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