1 /*

     2 * Copyright (c) 2007 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  Definition of menu item filter criteria

    15 *

    16 */

    17 

    18 

    19 #ifndef __MCSMENUFILTER_H__

    20 #define __MCSMENUFILTER_H__

    21 

    22 #include "mcsdef.h"

    23 #include <e32base.h>

    24 

    25 class RWriteStream;

    26 class RReadStream;

    27 

    28 /**

    29  *  Menu item filter criteria.

    30  *  Allows querying items filtered by flags, type and attributes.

    31  *  Wildcards are not supported (neither in attributes, nor in

    32  *  type).

    33  *  @lib mcsmenu.lib

    34  *  @since S60 v5.0

    35  */

    36 NONSHARABLE_CLASS( CMenuFilter ): public CBase

    37     {

    38 

    39 public:

    40 

    41     /**

    42     * Destructor.

    43     * @since S60 v5.0

    44     * @capability None.

    45     * @throws None.

    46     * @panic None.

    47     */

    48     IMPORT_C virtual ~CMenuFilter();

    49 

    50     /**

    51     * Two phased constructor.

    52     * @since S60 v5.0

    53     * @return The created object.

    54     * @capability None.

    55     * @throws System-wide error codes if an error occurs.

    56     * @panic None.

    57     */

    58     IMPORT_C static CMenuFilter* NewL();

    59 

    60     /**

    61     * Two phased constructor.

    62     * @since S60 v5.0

    63     * @return The created object.

    64     * @capability None.

    65     * @throws System-wide error codes if an error occurs.

    66     * @panic None.

    67     */

    68     IMPORT_C static CMenuFilter* NewLC();

    69 

    70 // getters

    71 

    72     /**

    73     * Get flag filter criteria: these flags must be on.

    74     * @since S60 v5.0

    75     * @return Flags that must be on.

    76     * @capability None.

    77     * @throws None.

    78     * @panic None.

    79     */

    80     IMPORT_C TUint32 FlagsOn() const;

    81 

    82     /**

    83     * Get flag filter criteria: these flags must be off.

    84     * @since S60 v5.0

    85     * @return Flags that must be off.

    86     * @capability None.

    87     * @throws None.

    88     * @panic None.

    89     */

    90     IMPORT_C TUint32 FlagsOff() const;

    91 

    92     /**

    93     * Get type filter criteria.

    94     * @since S60 v5.0

    95     * @return Type filter.

    96     * @capability None.

    97     * @throws None.

    98     * @panic None.

    99     */

   100     IMPORT_C TPtrC Type() const;

   101 

   102     /**

   103     * Get number of attribute filter criteria.

   104     * @since S60 v5.0

   105     * @return Number of attribute filter criteria.

   106     * @capability None.

   107     * @throws None.

   108     * @panic None.

   109     */

   110     IMPORT_C TInt NumAttributes() const;

   111 

   112     /**

   113     * Get attribute filter criteria by index. (Attribute must be defined and

   114     * have a certain value, or it must be undefined).

   115     * @since S60 v5.0

   116     * @param aIndex Index of attribute filter criteria.

   117     * @param aAttrName Attribute name is returned here.

   118     * @param aAttrValue Attribute value (if defined) is returned here.

   119     * @return ETrue if attribute aAttrName must be defined and having value

   120     * aAttrValue. EFalse if attribute aAttrName must NOT be defined.

   121     * @capability None.

   122     * @throws None.

   123     * @panic None.

   124     */

   125     IMPORT_C TBool GetAttribute

   126         ( TInt aIndex, TPtrC& aAttrName, TPtrC& aAttrValue ) const;

   127 

   128 // setters

   129 

   130     /**

   131     * Reset filter (==pass all).

   132     * @since S60 v5.0

   133     * @capability None.

   134     * @throws None.

   135     * @panic None.

   136     */

   137     IMPORT_C void Reset();

   138 

   139     /**

   140     * Set on and off flag filter criteria.

   141     * @since S60 v5.0

   142     * @param aFlagsOn These flags must be on. (0=="flag on" filter off)

   143     * @param aFlagsOff These flags must be off. (0=="flag off" filter off)

   144     * @capability None.

   145     * @throws None.

   146     * @panic None.

   147     */

   148     IMPORT_C void SetFlags( TUint32 aFlagsOn, TUint32 aFlagsOff );

   149 

   150     /**

   151     * Set type filter criteria.

   152     * @since S60 v5.0

   153     * @param aType Type filter. (empty==type filter off)

   154     * @capability None.

   155     * @throws None.

   156     * @panic None.

   157     */

   158     IMPORT_C void SetType( const TDesC& aType );

   159 

   160     /**

   161     * Add/replace attribute filter criteria.

   162     * The attribute must exist and have the given value.

   163     * @since S60 v5.0

   164     * @param aAttrName Attribute name. Previous attribute filter with

   165     * the same name is replaced.

   166     * aAttrValue Attribute must have this value.

   167     * @capability None.

   168     * @throws System-wide error codes if an error occurs.

   169     * @panic None.

   170     */

   171     IMPORT_C void HaveAttributeL

   172         ( const TDesC& aAttrName, const TDesC& aAttrValue );

   173 

   174     /**

   175     * Add/replace attribute filter criteria.

   176     * The attribute must not exist.

   177     * @since S60 v5.0

   178     * @param aAttrName Attribute name. Previous attribute filter with

   179     * the same name is replaced.

   180     * @capability None.

   181     * @throws System-wide error codes if an error occurs.

   182     * @panic None.

   183     */

   184     IMPORT_C void DoNotHaveAttributeL( const TDesC& aAttrName );

   185 

   186     /**

   187     * Remove attribute filter criteria.

   188     * @since S60 v5.0

   189     * @param aAttrName Attribute name. Previous attribute filter with

   190     * the same name (if any) is removed.

   191     * @capability None.

   192     * @throws None.

   193     * @panic None.

   194     */

   195     IMPORT_C void RemoveAttribute( const TDesC& aAttrName );

   196 

   197 // not exported public

   198 

   199     /**

   200     * Externalize object.

   201     * @param aStream Stream to externalize into.

   202     */

   203     void ExternalizeL( RWriteStream& aStream ) const;

   204 

   205     /**

   206     * Internalize object.

   207     * @param aStream Stream to externalize from.

   208     */

   209     void InternalizeL( RReadStream& aStream );

   210 

   211 private:

   212 

   213     /**

   214     * Constructor.

   215     */

   216     CMenuFilter();

   217 

   218     /**

   219     * Second-phase constructor.

   220     */

   221     void ConstructL();

   222 

   223 private:    // data

   224 

   225     class TData;

   226     TData* iData; ///< Private data. Own.

   227 

   228     };

   229 

   230 #endif // __MCSMENUFILTER_H__