1 /*

     2 * Copyright (c) 2002-2004 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:           

    15 *       Provides the CAknFepUICtrlCandidatePane definition.

    16 *

    17 */

    18 

    19 

    20 

    21 

    22 

    23 

    24 

    25 

    26 

    27 

    28 

    29 

    30 #ifndef __AKN_FEP_CANDIDATE_PANE_H__

    31 #define __AKN_FEP_CANDIDATE_PANE_H__

    32 

    33 #include <e32std.h>

    34 #include <coecntrl.h>

    35 

    36 #include "AknFepUiCtrlContainerChinese.h"

    37 

    38 /**

    39 * TPage holds the start index, end index and start position in buffer of every display page

    40 */

    41 struct TPage

    42     {

    43     TInt iStartIndex;

    44     TInt iEndIndex;

    45     };

    46 

    47 /**

    48  * Pane which displays the Chinese Candidates.

    49  */

    50 class MAknFepUICtrlCandidatePane

    51     {

    52 public:

    53     enum

    54         {

    55         EOneCandidate = 1,

    56         EMaxCandidates = 10,

    57         EMaxPages = 10,

    58         EPhraseLength = 10

    59         };

    60     /**

    61      * each candidate can be in a certain mode, which may affect its layout. Note

    62      * that only stroke is needed at this time (for components), but more modes could be added 

    63      * later if the LAF spec changes.

    64      */

    65     enum TCandidateMode

    66         {

    67         ECandidateModeNormal,

    68         ECandidateModeStroke

    69         };

    70 public:

    71     /**

    72      * Allows the client to set a descriptor pointer into an existing buffer of 

    73      * data, avoiding unnecessary copying of data.

    74      * <p> Note that if the buffer contains less characters than the current

    75      * visible count, then the remaining characters will not be displayed. 

    76      * <p> Note also that if the current selection falls outside the range

    77      * of the size of the new buffer, it will be made not visible. 

    78      * However, the current highlighted state remains, so if the selection 

    79      * is set once more to a valid entry (or if the buffer is set to a length that 

    80      * includes the currently selected position), and the highlight is still enabled,

    81      * the highlight will reappear.

    82      *

    83      * @param aBufferPtr descriptor that contains the candidates for display,

    84      *                              could be a pointer into a subset of a larger descriptor 

    85      *                              that contains all the candidates. Note that only the 

    86      *                              first EMaxCandidates of aBuffer will be used. 

    87      *                              Length must be > 0.

    88      */

    89     virtual void SetCandidateBuffer(const TDesC& aBuffer) = 0;

    90 

    91     /**

    92      * This function sets the highlighted status of the pane for rendering purposes. 

    93      * If the Pane is highlighted it displays the current selected Candidate, 

    94      * plus numbers with each of the other Candidates. 

    95      * 

    96      * @param aHighlighted ETrue if the highlight is to be set

    97      *                                  EFalse if the highlight is to be removed

    98      */

    99     virtual void SetHighlighted(TBool aHighlighted) = 0;

   100 

   101     /**

   102      * enable/disable the rendering of the Horizontal Scroll Arrows. 

   103      *

   104      * @param aValue if ETrue, enable the arrows

   105      *                          if EFalse, disable the arrrows

   106      */

   107     virtual void ShowHorizontalScrollArrows(TBool aValue) = 0;

   108 

   109 

   110     /**

   111      * enable/disable the rendering of the up Scroll Arrows. 

   112      *

   113      * @param aValue if ETrue, enable the arrows

   114      *  if EFalse, disable the arrrows

   115      */

   116     virtual void ShowUpScrollArrows(TBool aValue) = 0;

   117 

   118     /**

   119      * enable/disable the rendering of the down Scroll Arrows. 

   120      *

   121      * @param aValue if ETrue, enable the arrows

   122      *  if EFalse, disable the arrrows

   123      */

   124     virtual void ShowDownScrollArrows(TBool aValue) = 0;

   125     

   126      /**

   127      * enable/disable the rendering of the left Scroll Arrows. 

   128      *

   129      * @param aValue if ETrue, enable the arrows

   130      *  if EFalse, disable the arrrows

   131      */

   132     virtual void ShowLeftScrollArrows(TBool aValue) = 0;

   133     

   134         /**

   135      * enable/disable the rendering of the right Scroll Arrows. 

   136      *

   137      * @param aValue if ETrue, enable the arrows

   138      *  if EFalse, disable the arrrows

   139      */

   140     virtual void ShowRightScrollArrows(TBool aValue) = 0;

   141 

   142     /**

   143      * enable/disable the rendering of the Vertical Scroll Arrows. 

   144      *

   145      * @param aValue if ETrue, enable the arrows

   146      *                          if EFalse, disable the arrrows

   147      */

   148     virtual void ShowVerticalScrollArrows(TBool aValue) = 0;

   149 

   150     /**

   151      * enable/disable the rendering of the candidate ordinal numbers

   152      *

   153      * @param aValue if ETrue, enable the ordinals

   154      *                          if EFalse, disable the ordinals

   155      *

   156      */

   157     virtual void ShowCandidateOrdinals(TBool aValue) = 0;

   158 

   159     /**

   160      * This function returns the number of Candidates that are visible in the pane 

   161      * in its current configuration.

   162      *

   163      * @return number of candidates that are currently visible

   164      */

   165     virtual TInt VisibleCandidateCount() const = 0;

   166 

   167     /**

   168      * Select the first visible item in the candidate buffer

   169      *

   170      * @return ETrue if success, EFalse if no items visible

   171      *

   172      */

   173     virtual TBool SelectFirst() = 0;

   174 

   175     /**

   176      * Select the first visible phrase item in the candidate buffer

   177      *

   178      * @return ETrue if success, EFalse if no items visible

   179      *

   180      */

   181     virtual TBool SelectFirstPhrase() = 0;

   182     

   183     /**

   184      * Select the last visible item in the candidate buffer

   185      *

   186      * @return ETrue if success, EFalse if no items visible

   187      *

   188      */

   189     virtual TBool SelectLast() = 0;

   190 

   191     /**

   192      * Select the last visible phrase item in the candidate buffer

   193      *

   194      * @return ETrue if success, EFalse if no items visible

   195      *

   196      */

   197     virtual TBool SelectLastPhrase() = 0;

   198 

   199     /**

   200      * Select the next visible item

   201      *

   202      * @return ETrue if success, 

   203      *              EFalse if no items visible, or if already on last visible item

   204      */

   205     virtual TBool SelectNext() = 0;

   206     /**

   207      * Select the previous visible item

   208      *

   209      * @return ETrue if success, 

   210      *              EFalse if no items visible, or if already on first visible item

   211      */

   212     virtual TBool SelectPrev() = 0;

   213 

   214     /**

   215      * This function selects the given index. 

   216      * <p> Note that if the new selected index is within the visible count, 

   217      * but falls on a candidate that is not valid (i.e. if it falls outside the

   218      * length of the candidate buffer) then nothing happens and EFalse is returned

   219      *

   220      * @param aIndex If aIndex falls outside length of candidate buffer, 

   221      *                          then return EFalse to indicate failure. 

   222      * @return ETrue if index was valid, EFalse if index not valid

   223      */

   224     virtual TBool SelectIndex(TInt aIndex, TBool selected = ETrue) = 0;

   225 

   226     /**

   227      * This function returns the selected index of the Candidate Pane. 

   228      * 

   229      * @return the index of the selected item. If the Pane is not highlighted it returns 0.

   230      *

   231      */

   232     virtual TInt SelectedIndex() const = 0;

   233     

   234     /**

   235      * This function returns the character at index of the current selection

   236      *

   237      * @return a descrptor containing the character that is currently selected.

   238      *              If the currect selection falls outside the length of the current buffer,

   239      *              then return a null descriptor

   240      *

   241      */

   242     virtual TPtrC CurrentCandidate() const = 0;

   243     /**

   244      * This function returns the phrase at index of the current selection

   245      *

   246      * @return a descrptor containing the character that is currently selected.

   247      *              If the currect selection falls outside the length of the current buffer,

   248      *              then return a null descriptor

   249      *

   250      */

   251     virtual TPtrC CurrentPhraseCandidate() const = 0;

   252     /**

   253 	*	Split phrase candidates into pages 

   254 	*/

   255     virtual void SplitPhraseCandidatesIntoPages() = 0;

   256   

   257     /**

   258 	*	Navigate to next page 

   259 	*/

   260     virtual void NextCandidatePage(void) = 0;

   261    

   262     /**

   263 	*	Navigate to previous page 

   264 	*/

   265     virtual void PreviousCandidatePage(void) = 0;

   266 

   267     /**

   268 	*	Return candidate array 

   269 	*/

   270     virtual CDesCArrayFlat* CandidateArray(void) = 0;

   271 

   272     /**

   273 	*	Set phrase candidate buffer

   274 	*/

   275     virtual void SetCandidateBuffer(void) = 0;

   276 

   277 	/**

   278 	*	Reset candidate pane state and variables

   279 	*/

   280 	virtual void ResetCandidateState() = 0;

   281 	

   282 	/**

   283 	 *	To test whether current page is the first page

   284 	 */

   285 	virtual TBool IsFirstPage() = 0;

   286 	

   287 	/**

   288 	 *	To test whether current page is the last page

   289 	 */

   290 	virtual TBool IsLastPage() = 0;

   291 

   292    /**

   293      *  To set all the cnadidate label invisible(phrase creation)

   294      */

   295     virtual void SetInVisiable() = 0;

   296 

   297 	/**

   298 	 *	To test whether need to get new candidate page

   299 	 */

   300 	virtual TBool NeedGetNewCandidatePage() = 0;

   301     };

   302 

   303 #endif //__AKN_FEP_CANDIDATE_PANE_H__

   304 

   305 // End of file