1 /*

     2 * Copyright (c) 2009 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:  Model Interface with utilities for scrollbar widget.

    15 *

    16 */

    17 

    18 #ifndef ALF_SCROLLBARMODEL_H

    19 #define ALF_SCROLLBARMODEL_H

    20 

    21 // Widget Model and Exported API includes

    22 #include <alf/ialfscrollbarmodel.h>

    23 

    24 // OsnCore includes

    25 #include <osn/alfptrvector.h>

    26 #include <osn/ustring.h>

    27 

    28 // Namespace

    29 using namespace osncore;

    30 

    31 namespace Alf

    32     {

    33 

    34 //Forward Declarations

    35 class AlfModel;

    36 class AlfScrollBarWidget;

    37 

    38 

    39 

    40 /**

    41  *  ScrollBar model implementation.

    42  *

    43  *  Implements utility methods to create and update

    44  *  the data hierarchy of a scrollbar.

    45  */

    46 class AlfScrollBarModel : public IAlfScrollBarModel

    47     {

    48 public:

    49 

    50     /**

    51      * Constructor.

    52      */

    53     AlfScrollBarModel(IAlfVariantType* aDataSource = NULL);

    54 

    55     /**

    56      * Destructor.

    57      */

    58     ~AlfScrollBarModel();

    59     

    60     /** From base class IAlfModel

    61      *

    62      */

    63 

    64     /**

    65      *  Add a new observer to be notified of any changes in the model.

    66      *

    67      *  @param    aObserver   The model change observer to be added.

    68      *  @return void

    69      *  @since S60 ?S60_version

    70      */

    71     void addModelChangeObserver(IAlfModelChangeObserver& aObserver);

    72 

    73     /**

    74      *  Remove an observer which is added to get notified of any changes

    75      *  in the model.

    76      *

    77      *  @param aObserver The model change observer to be removed.

    78      *  @return void

    79      *  @since S60 ?S60_version

    80      */

    81     void removeModelChangeObserver(IAlfModelChangeObserver& aObserver);

    82 

    83     /**

    84      *  API to change the model completely at one short. 

    85      *  

    86      *  @see IAlfModel

    87      *  @param    aData    The new data.

    88      *  @return void

    89      *  @since S60 ?S60_version

    90      */

    91     void setData(IAlfVariantType* aData);

    92 

    93     /**

    94      * Change a given  of data fields in the model . All model change

    95      * observers are notified about the change.

    96      *

    97      * @param aNumContainerIndices The number of indices in aContainerIndices.

    98      * @param aContainerIndices    The container indices to find the correct 

    99      *                             location in the data hierarchy.The ownership 

   100      *                             is transferred. 

   101      * @param aData                The new data to be set.

   102      * @since S60 ?S60_version

   103      */

   104     void updateData(int  aNumContainerIndices,

   105         int* aContainerIndices,

   106         IAlfVariantType* aData);

   107 

   108     /**

   109      * Add a  number of data fields in the model data. All model change

   110      * observers are notified about the change.

   111      *

   112      * @param aNumContainerIndices The number of indices in aContainerIndices.

   113      * @param aContainerIndices    The container indices to find the correct 

   114      *                             location in the data hierarchy.The ownership

   115      *                             is transferred. 

   116      * @param aData                The new data.

   117      * @return void

   118      * @since S60 ?S60_version

   119      */

   120     void addData(int aNumContainerIndices,

   121         int* aContainerIndices,

   122         IAlfVariantType* aData);

   123 

   124     /**

   125      * Remove a  number of data fields in the model data. All model change

   126      * observers are notified about the change.

   127      *

   128      * @param aNumContainerIndices The number of indices in aContainerIndices.

   129      * @param aContainerIndices    The container indices to find the correct 

   130      *                             location in the data hierarchy.The ownership

   131      *                             is transferred.

   132      * @return void

   133      * @since S60 ?S60_version

   134      */

   135     void removeData(int aNumContainerIndices, int* aContainerIndices);

   136 

   137     /**

   138      *  API for executing batch operations

   139      *

   140      *  @param aOperationsArray    An RPOinterArray containing the list of 

   141      *                             operations to be executed in batch.

   142      *  @return void

   143      *  @since S60 ?S60_version

   144      */

   145     void executeOperations(AlfPtrVector<AlfModelOperation>&  aOperationsArray);

   146 

   147     /**

   148      *  API for executing one operation at a Time

   149      *

   150      *  @param aOperation          An Operation to be executed on the model.

   151      *  @since S60 ?S60_version

   152      */

   153     void executeOperation(AlfModelOperation* aOperation);

   154 

   155     /**

   156      *  Clears the Model.

   157      *

   158      *  @return void

   159      *  @since S60 ?S60_version

   160      */

   161     void clearModel();

   162 

   163     /**

   164     *  Get the root data object of this model.

   165     *

   166     *  @return The root data object.

   167     *  @since S60 ?S60_version

   168     */

   169     IAlfVariantType* data() const;

   170     

   171     //  From base class IAlfInterfaceBase

   172     

   173     IAlfInterfaceBase* makeInterface(const IfId& aType);

   174 

   175     //  From base class IAlfScrollBarModel     

   176 

   177 	/**

   178 	 * Create the default data structure for a ScrollBar widget.

   179 	 * 

   180 	 * @param       aTotalLengthInSteps

   181 	 * @param       aViewLengthInSteps

   182 	 * @param       aViewStartPosition

   183 	 *

   184 	 *

   185 	 * @return      void

   186 	 * @exception   std::bad_alloc

   187 	 * @since       S60 ?S60_version

   188 	 */  

   189     void initializeData(int aTotalLengthInSteps,

   190            int aViewLengthInSteps,

   191            int aViewStartPosition);

   192 

   193     /**

   194      * Sets the TotalLength for the Scrollbar. Does not notify observers about this.

   195      * 

   196      * @param aTotalLength  TotalLength value

   197      *

   198      * @return void.

   199      * @since S60 ?S60_version

   200      */

   201     void setTotalLength(int aTotalLength);

   202 

   203     /**

   204      * Sets the View Length for the Scrollbar. Does not notify observers 

   205      * about this.

   206      *

   207      * @param aViewSize 

   208      * 

   209      * @return void.

   210      * @since S60 ?S60_version

   211      */

   212     void setViewLength(int aViewSize);

   213 

   214     /**

   215      * Sets the View Start Position for the Scrollbar. Does not notify 

   216      * observers about this.

   217      *

   218      * @param aViewStartPosition

   219      * 

   220      * @return void.

   221      * @since S60 ?S60_version

   222      */

   223     void setViewStartPosition(int aViewStartPosition);

   224 

   225     /**

   226          * Sets the TotalLength for the Scrollbar. Does not notify observers about this.

   227          *

   228          * @param aTotalLength              TotalLength value

   229          * @param aViewLength       view length value

   230          * @param aViewStartPosition view start position  

   231          *

   232          * @return void.

   233          * @since S60 ?S60_version

   234          */

   235     void changeData(int aTotalLength,int aViewLength, int aViewStartPosition);   

   236         

   237     /**

   238      * Length of the document or viewable data.

   239      *

   240      * Arbitrary units are used, but the same units as the rest of the model.

   241      * This length is best current estimate of the length of the entire 

   242      * viewable data in this model's direction.(i.e, vertical, horizontal).

   243      * It represents physical extent (e.g. could be pixels), not logical

   244      * size of the data. It is understood to represent the physical laid out 

   245      * size of the data if it were possible to view it all at once.

   246      *

   247      * @return length in arbitrary units of the viewable data

   248      * @since S60 ?S60_version

   249      */

   250     int getTotalLength() const;

   251 

   252     /**

   253      * Length of the view.

   254      *

   255      * For horizontal models, this is the width of the view.

   256      * For veritcal, this is the height of the view.

   257      *

   258      * Note the units are arbitrary but uniform with the rest of the model.

   259      * Note that this measure is proportional to the physical width or height

   260      * of the view. This metric is sometimes called the Thumb size.

   261      *

   262      * @return position of the start of the view

   263      * @since S60 ?S60_version

   264      */

   265     int getViewLength() const;

   266     /**

   267      * Position in arbitrary units of the start of the currently viewed data.

   268      *

   269      * For horizontal models, this is the position of the left of the view 

   270      * relative to the far left end of the document.

   271      * For vertical, this is the position of the top of the view from the top

   272      * of the viewable data.

   273      *

   274      * Note the units are arbitrary but uniform with the rest of the model.

   275      * Position is in physical space as if the entire data were laid out.

   276      * This metric is sometimes called the Thumb position.

   277      *

   278      * @return position of the start of the view

   279      * @since S60 ?S60_version

   280      */

   281     int getViewStartPosition() const;

   282        

   283     /**

   284      * Updates the model according to the values passed.

   285      *

   286      * @param       aTotalLengthInSteps

   287      * @param       aViewLength

   288      * @param       aViewStartPosition

   289      *

   290      * @return void.

   291      * @since S60 ?S60_version

   292      *

   293      */

   294     void updateScrollBarModel(int aTotalLengthInSteps,

   295             int aViewLength,

   296             int aViewStartPosition);

   297      /**

   298      * Updates visualization of scrollbar according 

   299      * to the model values.

   300      */  

   301     void updateScrollBarVisualization(); 

   302     

   303     /**

   304      * Stores the scrollbar widget pointer in model

   305      */

   306     void storeWidget(AlfScrollBarWidget* aWidget);

   307     

   308 private:

   309     

   310     /** 

   311      * This function validates view length passed and changes it if required

   312      * 

   313      * @param aViewLength - in/out param

   314      *

   315      * @return bool false, if the data was not valid and changes were made

   316      *              else returns true     

   317      */

   318     bool validateViewLength(int & aViewLength);

   319 

   320     /** 

   321      * This function validates view start position passed and changes it if

   322      *  required

   323      *

   324      * @param aViewStartPos - in/out param

   325      *

   326      * @return bool false, if the data was not valid and changes were made

   327      *              else returns true     

   328      */

   329     bool validateViewStartPos(int & aViewStartPos);

   330     

   331     /** 

   332      * This function validates total length passed and changes it if 

   333      * required. This validation can change aViewLength, aViewStartPos

   334      * too if reuired.

   335      * 

   336      * @param aTotalLength - in/out param

   337      * @param aViewLength - in/out param

   338      * @param aViewStartPos - in/out param

   339      *

   340      * @return bool false, if the data was not valid and changes were made

   341      *              else returns true

   342      */

   343     bool validateAllData(int & aTotalLength, 

   344         int & aViewLength, 

   345         int & aViewStartPos);

   346 

   347     /**

   348      * Private method to create the ScrollBar Widget.

   349      *

   350      * @param     aDataSource  Model for the ScrollBar

   351      * @return    void

   352      * @since S60 ?S60_version

   353      * 

   354      */

   355     void construct ( IAlfVariantType* aDataSource );

   356     

   357 	/*

   358      * pointer to scrollbarmodelData.

   359      */ 

   360     struct ScrollbarModelDataImpl *mModelData;

   361 

   362     AlfModel* mModel;  //Owned

   363     AlfScrollBarWidget* mScrollWidget;

   364     }; // class AlfScrollBarModel

   365 

   366     } // End of namespace Alf

   367 

   368 #endif // ALF_SCROLLBARMODEL_H

   369 //End Of File