idlefw/plugins/shortcutplugin/inc/caiscuttarget.h
author Dremov Kirill (Nokia-D-MSW/Tampere) <kirill.dremov@nokia.com>
Thu, 17 Dec 2009 08:54:17 +0200
changeset 0 79c6a41cd166
permissions -rw-r--r--
Revision: 200949 Kit: 200951

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