1 /*

     2 * Copyright (c) 2002-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:  Uses notification framework to show a global list query.

    15 *

    16 */

    17 

    18 #ifndef __AKNGLOBALLISTQUERY_H__

    19 #define __AKNGLOBALLISTQUERY_H__

    20 

    21 #include <AknNotify.h>

    22 #include <AknNotifyStd.h>

    23 #include <bamdesca.h>

    24 

    25 class CAknSDData;

    26 

    27 // Default index for list query

    28 const TInt KGlobalListQueryDefaultIndex = 0;

    29 

    30 _LIT( KGlobalListQueryItemSeparator, "\n");

    31 

    32 /**

    33 * CAknGlobalListQuery

    34 *   Uses notification framework to show a global list query.

    35 *   Usage:

    36 *       Create an active object, start it and pass its TRequestStatus as a

    37 *       parameter to ShowListQueryL. After the user selects one item from

    38 *       the list query, the request status will hold the number of the

    39 *       selected item. If the user selected Cancel, the request status will

    40 *       hold -1.

    41 *

    42 *   Example 1. Show the global list query:

    43 *        CDesCArray* textArray = iCoeEnv->ReadDesCArrayResourceL( R_GLOBAL_LIST_ARRAY );

    44 *        CleanupStack::PushL(textArray);

    45 *        TInt result = -555;

    46 *        if ( iListObserver )

    47 *            {

    48 *            iListObserver->Cancel();

    49 *            delete iListObserver;

    50 *            }

    51 *        iListObserver = new(ELeave) CGlobalListObserver(iEikonEnv);

    52 *        iListObserver->Start();

    53 *        iGlobalListQuery->ShowListQueryL(textArray, iListObserver->iStatus, 4);

    54 *        CleanupStack::PopAndDestroy(); // textArray

    55 *

    56 *   Example 2. Get and handle the result in active object.

    57 *        void CMyActiveObject::RunL() 

    58 *            {

    59 *            TBuf<120> msg = _L("Received: ");

    60 *            msg.AppendNum( iStatus.Int() );

    61 *            iEnv->InfoMsg(msg);

    62 *            Cancel();

    63 *            }

    64 */

    65 NONSHARABLE_CLASS(CAknGlobalListQuery) : public CBase

    66     {

    67     public:

    68         /**

    69         * Two-phased constructor.

    70         */

    71         IMPORT_C static CAknGlobalListQuery* NewL();

    72 

    73         /**

    74         * Two-phased constructor. Leaves the instance to cleanupstack

    75         */

    76         IMPORT_C static CAknGlobalListQuery* NewLC();

    77 

    78         /**

    79         * Destructor

    80         */

    81         IMPORT_C ~CAknGlobalListQuery();

    82 

    83         /**

    84         * Shows global list query synchronously.

    85         *

    86         * @param    aItems  Strings for items

    87         * @param    aStatus TRequestStatus which will be completed when user

    88         *                   selects one item from the list query.

    89         * @param    aIndex  Index which item in the list will be highlighted 

    90         */

    91         IMPORT_C void ShowListQueryL( 

    92             const MDesCArray* aItems,

    93             TRequestStatus& aStatus,

    94             const TInt aIndex = KGlobalListQueryDefaultIndex);

    95 

    96         /**

    97         * Move selection up.

    98         */

    99         IMPORT_C void MoveSelectionUp();

   100 

   101         /**

   102         * Move selection down.

   103         */

   104         IMPORT_C void MoveSelectionDown();

   105 

   106         /**

   107         * Select currently selected item in the list.

   108         */

   109         IMPORT_C void SelectItem();

   110 

   111         /**

   112         * Cancel the list query.

   113         */

   114         IMPORT_C void CancelListQuery();

   115 

   116         /**

   117         * Sets the heading for the query. In order to have effect, the heading must be set before 

   118         * calling ShowListQueryL.

   119         *

   120         * @param    aHeading  Heading string.

   121         * @since 2.1

   122         */

   123         IMPORT_C void SetHeadingL(const TDesC& aHeading);

   124 

   125         /**

   126         * Sets additional information to be sent to secondary display. Takes ownership of object.

   127         * Must be called before sending data to notifier to have effect.

   128         *

   129         * @param aData Data to be sent to cover UI.

   130         * @internal to S60

   131         * @since S60 3.1

   132         */

   133         IMPORT_C void SetSecondaryDisplayData(CAknSDData* aData);

   134         

   135     private:

   136         /**

   137         * Updates list query.

   138         */

   139         IMPORT_C void UpdateListQuery();

   140 

   141     private:

   142         /**

   143         * Default constructor.

   144         */

   145         CAknGlobalListQuery();

   146 

   147         /**

   148         * EPOC constructor.

   149         */

   150         void ConstructL(); 

   151 

   152     private:

   153         // Command id.

   154         TAknGlobalQueryCmd iCmd;

   155         // Notifier handle.

   156         RNotifier iNotify;

   157         // Index to set which item will be selected.

   158         TInt iIndex;

   159         // Buffer to hold the variables passed to server.

   160         CBufFlat *iBuffer;

   161         // Pointer to buffer.

   162         TPtrC8 iBufferPtr;

   163         HBufC* iHeading;

   164         CAknSDData* iAknSDData;

   165         TBuf8<1> iResultBuf; // Not really used, but needed to prevent buffer handling errors.

   166     };

   167 

   168 #endif // __AKNGLOBALLISTQUERY_H__