epoc32/include/mw/EPos_CPosLmDisplayData.h
author William Roberts <williamr@symbian.org>
Wed, 31 Mar 2010 12:33:34 +0100 (2010-03-31)
branchSymbian3
changeset 4 837f303aceeb
permissions -rw-r--r--
Current Symbian^3 public API header files (from PDK 3.0.h)
This is the epoc32/include tree with the "platform" subtrees removed, and
all but a selected few mbg and rsg files removed.
williamr@4
     1
/*
williamr@4
     2
* Copyright (c) 2005-2006 Nokia Corporation and/or its subsidiary(-ies). 
williamr@4
     3
* All rights reserved.
williamr@4
     4
* This component and the accompanying materials are made available
williamr@4
     5
* under the terms of "Eclipse Public License v1.0"
williamr@4
     6
* which accompanies this distribution, and is available
williamr@4
     7
* at the URL "http://www.eclipse.org/legal/epl-v10.html".
williamr@4
     8
*
williamr@4
     9
* Initial Contributors:
williamr@4
    10
* Nokia Corporation - initial contribution.
williamr@4
    11
*
williamr@4
    12
* Contributors:
williamr@4
    13
*
williamr@4
    14
* Description:  CPosLmDisplayData class
williamr@4
    15
*
williamr@4
    16
*/
williamr@4
    17
williamr@4
    18
williamr@4
    19
#ifndef CPOSLMDISPLAYDATA_H
williamr@4
    20
#define CPOSLMDISPLAYDATA_H
williamr@4
    21
williamr@4
    22
#include <e32base.h>
williamr@4
    23
williamr@4
    24
const TInt KPosLmNoNewItems = -1;
williamr@4
    25
williamr@4
    26
class CPosLmDisplayItem;
williamr@4
    27
class CPosLmPartialReadParameters;
williamr@4
    28
williamr@4
    29
/**
williamr@4
    30
* Displayable data collection.
williamr@4
    31
*
williamr@4
    32
* A displayable data collection consists of displayable items
williamr@4
    33
* (@ref CPosLmDisplayItem). A displayable data collection either
williamr@4
    34
* consists of landmark items (if a landmark search has been started)
williamr@4
    35
* or category items (if a category search has been started).
williamr@4
    36
* Items of different types cannot be mixed in the collection.
williamr@4
    37
*
williamr@4
    38
* Displayable data is used in @ref CPosLandmarkSearch and
williamr@4
    39
* @ref CPosLmMultiDbSearch to hold search results. The collection is
williamr@4
    40
* populated with new results every time the next search step is executed.
williamr@4
    41
* Displayable items contain full or partial 
williamr@4
    42
* (see @ref CPosLandmarkDatabase::SetPartialReadParameters)
williamr@4
    43
* landmark data or full category data, and can be used to display search
williamr@4
    44
* results already during the search and also after it has completed.
williamr@4
    45
*
williamr@4
    46
* Note: The single class instance may only be used by one search
williamr@4
    47
* instance at a time.
williamr@4
    48
*
williamr@4
    49
*  @lib eposlmsearchlib.lib
williamr@4
    50
*  @since S60 3.0
williamr@4
    51
*/
williamr@4
    52
class CPosLmDisplayData : public CBase
williamr@4
    53
    {
williamr@4
    54
    public:
williamr@4
    55
williamr@4
    56
        /**
williamr@4
    57
        * Two-phased constructor.
williamr@4
    58
        *
williamr@4
    59
        * @returns A new instance of this class.
williamr@4
    60
        */
williamr@4
    61
        IMPORT_C static CPosLmDisplayData* NewL();
williamr@4
    62
williamr@4
    63
        /**
williamr@4
    64
        * Destructor.
williamr@4
    65
        */
williamr@4
    66
        virtual ~CPosLmDisplayData();
williamr@4
    67
williamr@4
    68
    public:
williamr@4
    69
williamr@4
    70
        /**
williamr@4
    71
        * Returns the index of the next match found during current asynchronous
williamr@4
    72
        * search operation. If the search is executed synchronously, then all
williamr@4
    73
        * indexes of the matches found during the search are returned one
williamr@4
    74
        * by one.
williamr@4
    75
        *
williamr@4
    76
        * After each search step, the new item indexes are returned in
williamr@4
    77
        * ascending order according to the specified sort preference in
williamr@4
    78
        * the search.
williamr@4
    79
        *
williamr@4
    80
        * @return The item index or @p KPosLmNoNewItems when no new items
williamr@4
    81
        *   are available.
williamr@4
    82
        */
williamr@4
    83
        IMPORT_C TInt NewItemIndex();
williamr@4
    84
williamr@4
    85
        /**
williamr@4
    86
        * Returns the number of items in the collection.
williamr@4
    87
        *
williamr@4
    88
        * @return The number of items.
williamr@4
    89
        */
williamr@4
    90
        IMPORT_C TInt Count() const;
williamr@4
    91
williamr@4
    92
        /**
williamr@4
    93
        * Resets the collection and deletes all contained items.
williamr@4
    94
        */
williamr@4
    95
        IMPORT_C void Reset();
williamr@4
    96
williamr@4
    97
        /**
williamr@4
    98
        * Returns the displayable item specified by index.
williamr@4
    99
        * The index must be strictly less than @ref Count and not less than 0.
williamr@4
   100
        *
williamr@4
   101
        * @param[in] aItemIndex A displayable item index.
williamr@4
   102
        * @return A displayable item.
williamr@4
   103
        *
williamr@4
   104
        * @panic "Landmarks Client"-EPosInvalidIndex
williamr@4
   105
        *   Item index is beyond valid range.
williamr@4
   106
        */
williamr@4
   107
        IMPORT_C CPosLmDisplayItem& DisplayItem( TInt aItemIndex ) const;
williamr@4
   108
williamr@4
   109
        /**
williamr@4
   110
        * Sets the partial read parameters for this display data.
williamr@4
   111
        *
williamr@4
   112
        * Partial read parameters are used to define which landmark data should
williamr@4
   113
        * be read during a landmark search. If no partial read parameters are
williamr@4
   114
        * set, the whole landmark will be read.
williamr@4
   115
        *
williamr@4
   116
        * This function only affects the searches which are started after
williamr@4
   117
        * it is called. The current search is not affected.
williamr@4
   118
        *
williamr@4
   119
        * If landmarks are sorted by name, the name will always be a part of
williamr@4
   120
        * the landmark in the display data, even if it is not requested.
williamr@4
   121
        *
williamr@4
   122
        * Note: Partial read parameters are only used for landmark searches.
williamr@4
   123
        *
williamr@4
   124
        * @param[in] aPartialSettings The partial read parameters.
williamr@4
   125
        */
williamr@4
   126
        IMPORT_C void SetPartialReadParametersL(
williamr@4
   127
            const CPosLmPartialReadParameters& aPartialSettings
williamr@4
   128
        );
williamr@4
   129
williamr@4
   130
        /**
williamr@4
   131
        * Unsets the partial read parameters for this display data.
williamr@4
   132
        *
williamr@4
   133
        * This means that from now on all landmarks added to this display data
williamr@4
   134
        * instance will contain all information.
williamr@4
   135
        *
williamr@4
   136
        * To have any affect, this function must be called before a search is
williamr@4
   137
        * started. If it is called during a search, it will only affect
williamr@4
   138
        * the next search.
williamr@4
   139
        *
williamr@4
   140
        * Note: Partial read parameters will only have effect on landmarks
williamr@4
   141
        * searches.
williamr@4
   142
        */
williamr@4
   143
        IMPORT_C void UnsetPartialReadParameters();
williamr@4
   144
williamr@4
   145
        /** @internal */
williamr@4
   146
        /* Returns the partial read parameters set for this display data.
williamr@4
   147
        *
williamr@4
   148
        * @return Partial read parameters or NULL if not set.
williamr@4
   149
        */
williamr@4
   150
        CPosLmPartialReadParameters* PartialReadParameters() const;
williamr@4
   151
williamr@4
   152
        /** @internal */
williamr@4
   153
        /* Returns a reference to all the displayable items.
williamr@4
   154
        * This array owns its displayable items.
williamr@4
   155
        *
williamr@4
   156
        * @return The items array.
williamr@4
   157
        */
williamr@4
   158
        RPointerArray<CPosLmDisplayItem>& DisplayItems();
williamr@4
   159
williamr@4
   160
        /** @internal */
williamr@4
   161
        /* Returns a reference to the new displayable items.
williamr@4
   162
        * This array does not own its displayable items.
williamr@4
   163
        * New displayable items are always a subset of all displayable items.
williamr@4
   164
        *
williamr@4
   165
        * @return The new item indexes array.
williamr@4
   166
        */
williamr@4
   167
        RPointerArray<CPosLmDisplayItem>& NewDisplayItems();
williamr@4
   168
williamr@4
   169
    private:
williamr@4
   170
williamr@4
   171
        // C++ constructor.
williamr@4
   172
        CPosLmDisplayData();
williamr@4
   173
williamr@4
   174
    private:
williamr@4
   175
williamr@4
   176
        RPointerArray<CPosLmDisplayItem> iDisplayItems;
williamr@4
   177
        RPointerArray<CPosLmDisplayItem> iNewDisplayItems;
williamr@4
   178
        CPosLmPartialReadParameters* iPartialParameters;
williamr@4
   179
williamr@4
   180
    };
williamr@4
   181
williamr@4
   182
#endif      // CPOSLMDISPLAYDATA_H
williamr@4
   183
williamr@4
   184