/*
* Copyright (c) 2005-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: Base class for all shortcut targets.
*
*/
#ifndef CAISCUTTARGET_H
#define CAISCUTTARGET_H
#include <e32base.h>
#include "taiscutparser.h"
#include "aiscutdefs.h"
#include <AknsItemID.h>
class CAiScutEngine;
class CGulIcon;
_LIT(KBitmapFile, "aiscutplugin.mif");
/**
* Base class for shortcut targets
*
* @since S60 v3.2
*/
class CAiScutTarget : public CBase
{
public:
virtual ~CAiScutTarget();
/**
* Returns the shortcut definition string.
*
* @since S60 v3.2
* @return Shortcut definition string
*/
virtual TPtrC Definition() const = 0;
/**
* Returns the shortcut target caption.
* Caption can be either a descriptor or a resource id.
* If the return value has a non-zero value, it is the resource id.
* Zero indicates that the descriptor reference parameter is used.
* Default implementation returns KErrNotSupported;
*
* Getting the target caption and icon utilizes the "lazy evaluation" idiom
* which means they are created only when they are first needed. This is because
* there are (atleast) two scenarios where they are never needed:
* 1. The active theme does not support shortcut captions or icons.
* 2. Shortcuts launched using LaunchByValue are never published.
*
* @since S60 v3.2
* @param aDes On return, the descriptor if used
* @return The resource id or zero to indicate that the descriptor is used.
*/
virtual TInt GetCaption( TPtrC& aDes, TAiScutAppTitleType aTitleType ) const;
/**
* Returns the shortcut target icon.
* Icon can be either an icon pointer or a resource id.
* If the return value has a non-zero value, it is the resource id.
* Zero indicates that the icon pointer is used.
* Default implementation returns the icon that has possibly
* been set with @c SetOverrideIcon() and returns
* KErrNotSupported if no override icon has been set.
*
* Uses the "lazy evaluation" idiom to get the icon. See Caption()
*
* @since S60 v3.2
* @param aIcon On return, the icon pointer if used
* @return The resource id or zero to indicate that the icon pointer is used.
*/
virtual TInt GetIcon( CGulIcon*& aIcon ) const;
/**
* Returns the shortcut icon that can be published to softkeys
* Icon can be either an icon pointer or a resource id.
* If the return value has a non-zero value, it is the resource id.
* Zero indicates that the icon pointer is used.
* Default implementation returns the icon that has possibly
* been set with @c SetSoftkeyIcon() and returns
* KErrNotSupported if no softkey icon has been set.
*
* Uses the "lazy evaluation" idiom to get the icon. See Caption()
*
* @since S60 v3.2
* @param aIcon On return, the icon pointer if used
* @return The resource id or zero to indicate that the icon pointer is used.
*/
virtual TInt GetSoftkeyIcon( CGulIcon*& aIcon ) const;
/**
* Returns the shortcut icon that can be published to toolbar
* Icon can be either an icon pointer or a resource id.
* If the return value has a non-zero value, it is the resource id.
* Zero indicates that the icon pointer is used.
* Default implementation returns the icon that has possibly
* been set with @c SetSoftkeyIcon() and returns
* KErrNotSupported if no softkey icon has been set.
*
* Uses the "lazy evaluation" idiom to get the icon. See Caption()
*
* @since S60 v3.2
* @param aIcon On return, the icon pointer if used
* @return The resource id or zero to indicate that the icon pointer is used.
*/
virtual TInt GetToolbarIcon( CGulIcon*& aIcon ) const;
/**
* Checks if the shortcut target is accessible.
*
* @since S60 v3.2
* @param aCheckType Specifies which kind of shortcuts should check its access
* @return ETrue if accessible, EFalse if not
*/
virtual TBool IsAccessibleL( TInt aCheckType ) = 0;
/**
* Launches the shortcut.
*
* @since S60 v3.2
*/
virtual void LaunchL() = 0;
/**
* Launches the shortcut.
*
* @since S60 v5.1
* @param aMessage A message to pass
*/
virtual void LaunchL(const TDesC8& aMessage) { (void)aMessage; };
/**
* Return application uid this target launches.
*
* @since S60 v3.2
*/
virtual TUid AppUid() const = 0;
/**
* Return an additional id this target may use when
* launching. Default implementation return TUid(-1)
*
* @since S60 v3.2
*/
virtual TUid AdditionalUid() const;
/**
* Return shortcut type.
*
* @since S60 v3.2
*/
TShortcutType Type() const;
/**
* Starts a full screen effect.
*/
void BeginEffectL();
/**
* Set the icon that overrides the shortcut default
* icon. Instead of fetching the icon from for example an
* application the icon defined here can be used. The shortcut
* can use the @c GetIcon() to fetch the
* icon defined here. Currently we support
* icon loading from skin or from MIF/MBM-file.
* The file must reside under z:\resource altough
* it can be under some subdirectory.
*
* @since S60 v3.2
* @param aIcon The overriding icon
*/
void SetOverrideIcon(TAiScutIcon aIcon);
/**
* Set the icon that is to be published to softkeys
* The @c GetSoftkeyIcon() can be used to fetch the
* icon defined here. Currently we support
* icon loading from skin or from MIF/MBM-file.
* The file must reside under z:\resource altough
* it can be under some subdirectory.
*
* @since S60 v3.2
* @param aIcon The softkey icon
*/
void SetSoftkeyIcon(TAiScutIcon aIcon);
/**
* Set the icon that is to be published to touch toolbar
* The @c GetSoftkeyIcon() can be used to fetch the
* icon defined here. Currently we support
* icon loading from skin or from mif-file.
* The mif-file must reside under z:\resource altough
* it can be under some subdirectory.
*
* @since S60 v5.0
* @param aIcon The softkey icon
*/
void SetToolbarIcon(TAiScutIcon aIcon);
protected:
CAiScutTarget( CAiScutEngine& aEngine, TShortcutType aType );
private:
/**
* Returns the icon defined in aIconToLoads. Loads the icon
* from MIF/MBM-file or from skin.
*
* @return KErrNone if no error
*/
TInt GetIcon(const TAiScutIcon &aIconToLoad, CGulIcon *&aIcon ) const;
/**
* Loads an icon defined in aIconToLoad from skin
*
* @return KErrNone if no error
*/
void LoadIconFromSkinL(const TAiScutIcon &aIconToLoad, CGulIcon*& aIcon) const;
/**
* Loads an icon defined in aIconToLoad from MIF/MBM-file
* The file must reside under z:\resource. It can be under
* some subdirectory.
*
* @return KErrNone if no error
*/
void LoadIconFromFileL(const TAiScutIcon &aIconToLoad, CGulIcon*& aIcon) const;
protected: // data
/**
* Reference to shortcut plug-in engine.
*/
CAiScutEngine& iEngine;
/**
* Shortcut type.
*/
TShortcutType iType;
/**
* Icon that is meant to override the default icon
*/
TAiScutIcon iOverrideIcon;
/**
* Icon that is to be published to softkeys
*/
TAiScutIcon iSoftkeyIcon;
/**
* Icon that is to be published to toolbar
*/
TAiScutIcon iToolbarIcon;
};
#endif // CAISCUTTARGET_H
// End of File.