/*
* Copyright (c) 2007-2009 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: Interface class for AP2
*
*/
/**
* @file ActivePalette2UI.h
* Interface class for AP2
*/
#ifndef _ACTIVE_PALETTE_2_UI_H
#define _ACTIVE_PALETTE_2_UI_H
#include <e32std.h>
class CCoeControl;
class CHuiControl;
class CBitmapContext;
class MActivePalette2Observer;
class TActivePalette2NavigationKeys;
class TActivePalette2ItemVisible;
/**
* The interface for the Active Palette. The ActivePalette2Factory is used to instantiate
* objects that provide this interface.
*/
class MActivePalette2UI
{
public:
/**
* Installs an item to the AP.
* @param aItemVisible The ID and visibility of the new item
* @param aPluginUid The UID of the plugin to handle this item
* @param aCustomDataDes Descriptor data to pass to the plugin
* @return Standard error code
*/
virtual TInt InstallItemL(const TActivePalette2ItemVisible& aItemVisible,
const TUid& aPluginUid,
const TDesC8& aCustomDataDes) = 0;
/**
* Installs an item to the AP.
* @param aItemVisible The ID and visibility of the new item
* @param aPluginUid The UID of the plugin to handle this item
* @param aCustomDataInt Integer data to pass to the plugin
* @return Standard error code
*/
virtual TInt InstallItemL(const TActivePalette2ItemVisible& aItemVisible,
const TUid& aPluginUid,
TInt aCustomDataInt = 0) = 0;
/**
* Installs an item to the AP.
* @param aItemVisible The ID and visibility of the new item
* @param aPluginUid The UID of the plugin to handle this item
* @param aCustomDataInt Integer data to pass to the plugin
* @param aCustomDataDes Descriptor data to pass to the plugin
* @return Standard error code
*/
virtual TInt InstallItemL(const TActivePalette2ItemVisible& aItemVisible,
const TUid& aPluginUid,
TInt aCustomDataInt,
const TDesC8& aCustomDataDes) = 0;
/**
* Removes an item
* @param aItemId The resource ID of the item to install
* @return Standard error code
*/
virtual TInt RemoveItem(TInt aItemId) = 0;
/**
* Sets the visibility of an item
* @param aItemId The item's ID
* @param aIsVisible The visibility state
* @return Standard error code
*/
virtual TInt SetItemVisibility(TInt aItemId, TBool aIsVisible) = 0;
/**
* Find out the visibility of a specified item
* @param aItemId The item's ID
* @param aIsVisible On return, indicates the visibility of the item
* @return Standard error code
*/
virtual TInt GetItemVisibility(TInt aItemId, TBool& aIsVisible) const = 0;
/**
* Gets the list of currently installed items.
* The list will include all items, both visible and invisible.
* @see SetItemList()
*
* @param aItemVisibleList On return, will contain the item list.
* @return Standard error code
*/
virtual TInt GetItemList(RArray<TActivePalette2ItemVisible>& aItemVisibleList) const = 0;
/**
* Sets the order and visibility of installed items.
* aItemVisibleList may be incomplete (i.e. not all installed item IDs must be present).
* In this case, the non-specified items will be shuffled down to the end of the AP,
* whilst retaining their relative order.
* If the item that was in focus before the call is still visible, it retains the focus,
* else the first visible item gains focus.
*
* @see GetItemList()
*
* @param aItemVisibleList The list describing the order and visibility of the items
* @return Standard error code
*/
virtual TInt SetItemList(const RArray<TActivePalette2ItemVisible>& aItemVisibleList) = 0;
/**
* Sends a message to the specified item's handling plugin
* @param aItemId The item's ID
* @param aMessageId Message ID
* @param aDataDes Custom data passed as a descriptor
* @return Error code
*/
virtual TInt SendMessage(TInt aItemId, TInt aMessageId, const TDesC8& aDataDes) = 0;
/**
* Sends a message to the specified item's handling plugin
* @param aItemId The item's ID
* @param aMessageId Message ID
* @param aDataInt Custom data passed as an integer
* @return Standard error code
*/
virtual TInt SendMessage(TInt aItemId, TInt aMessageId, TInt aDataInt) = 0;
/**
* Gets the currently focussed item
* @param aItemId On return, will contain the ID of the item in focus
* @return Standard error code
*/
virtual TInt GetCurrentItem(TInt& aItemId) const = 0;
/**
* Sets the currently focussed item
* @param aItemId The ID of the item to focus
* @return Standard error code
*/
virtual TInt SetCurrentItem(TInt aItemId) = 0;
/**
* Hides or shows the palette.
* After calling this function, and until the transition (if any) is complete, the AP will
* not accept any user input.
*
* @see SetPaletteVisibilityAnimationDuration()
* @see GetPaletteVisibilityAnimationDuration()
*
* @param aVisible If ETrue, shows the AP, otherwise hides it
* @param aAnimated Whether the transition should be animated. If not, the change is made as soon
* as aDelayedStartMilliseconds has passed
* @param aDelayedStartMilliseconds An optional pause before the transition begins.
* @return Standard error code
*/
virtual TInt SetPaletteVisibility(TBool aVisible, TBool aAnimated, TInt aDelayedStartMilliseconds = 0) = 0;
/**
* Sets the duration of the SetPaletteVisibility animation.
*
* @see SetPaletteVisibility()
* @see GetPaletteVisibilityAnimationDuration()
*
* @param aTimeInMilliseconds How long the animation should take, in milliseconds
* @return Standard error code
*/
virtual TInt SetPaletteVisibilityAnimationDuration(TInt aTimeInMilliseconds) = 0;
/**
* Gets the duration of the SetPaletteVisibility animation.
*
* @see SetPaletteVisibility()
* @see SetPaletteVisibilityAnimationDuration()
*
* @param aTimeInMilliseconds On return, will contain how long the animation will take, in milliseconds
* @return Standard error code
*/
virtual TInt GetPaletteVisibilityAnimationDuration(TInt& aTimeInMilliseconds) const = 0;
/**
* Move the AP.
* @param aTopLeft Point specifying where to move the AP to
*/
virtual void LocateTo(const TPoint& aTopLeft) = 0;
/**
* Returns the top left point of the AP
* @return A TPoint indicating the top left point of the AP
*/
virtual TPoint Location() const = 0;
/**
* Returns the underlying CCoeControl, if any.
* @return A valid CCoeControl pointer if the underlying implementation is a CCoeControl; NULL otherwise.
*/
virtual CCoeControl* CoeControl() = 0;
/**
* Returns the underlying CHuiControl, if any.
* @return A valid CHuiControl pointer if the underlying implementation is a CHuiControl; NULL otherwise.
*/
virtual CHuiControl* HuiControl() = 0;
/**
* Sets the graphics context to draw to.
* If called with aGc being non-NULL, the AP will be rendered to the supplied context
* in future drawing operations. If called with NULL, the screen's GC will be used instead.
* Calls to this will only have an effect if a CCoeControl-based AP has been created.
*
* @see RenderActivePalette()
*
* @param aGc The graphics context to draw to
*/
virtual void SetGc(CBitmapContext* aGc = NULL) = 0;
/**
* Forces the AP to draw itself to the supplied aRect.
* Uses the context previously set by SetGc, if any; uses the screen's context otherwise.
* Calls to this will only have an effect if a CCoeControl-based AP has been created.
*
* @see SetGc()
*
* @param aRect The rect to render to
*/
virtual void RenderActivePalette(const TRect& aRect) const = 0;
/**
* Sets the active palette observer used for callbacks. Calls to this function replace the previously
* set observer. SetObserver(NULL) may be called to remove the previously set observer without specifying
* a new observer
*
* @param aObserver The new observer to use
*/
virtual void SetObserver(MActivePalette2Observer* aObserver) = 0;
/**
* Gets a list of available external plugins.
*
* @param aPluginList On return, will contain a list a valid plugin UIDs
* @return Standard error code
*/
virtual TInt GetAvailablePlugins(RArray<TUid>& aPluginList) const = 0;
/**
* Sets the keys the user will press to navigate the AP. This sets the scancodes responded to when
* CCoeControl::OfferKeyEvent, CHuiControl::OfferEvent or similar are called.
*
* @param aNavigationKeys The new navigation keys
*/
virtual void SetNavigationKeys(const TActivePalette2NavigationKeys& aNavigationKeys) = 0;
/**
* Destructor. Will clean up all installed plugins.
*/
virtual ~MActivePalette2UI() {};
};
#endif // _ACTIVE_PALETTE_2_UI_H