S60 3rd Edition API Reference: eiklbx.h Source File

00001 // EIKLBX.H
00002 //
00003 // Copyright (c) 1997-1999 Symbian Ltd.  All rights reserved.
00004 //
00005    
00006 #if !defined(__EIKLBX_H__)
00007 #define __EIKLBX_H__
00008 
00009 //  INCLUDES 
00010 #if !defined(__GDI_H__)
00011 #include <gdi.h>
00012 #endif
00013 
00014 #if !defined(__EIKBCTRL_H__)
00015 #include <eikbctrl.h>
00016 #endif
00017 
00018 #if !defined(__EIKLBO_H__)
00019 #include <eiklbo.h>
00020 #endif
00021 
00022 #if !defined(__EIKSBFRM_H__)
00023 #include <eiksbfrm.h>
00024 #endif
00025 
00026 #if !defined(__EIKLBM_H__)
00027 #include <eiklbm.h>
00028 #endif
00029 
00030 #if !defined(__EIKLBV_H__)
00031 #include <eiklbv.h>
00032 #endif
00033 
00034 #if !defined(__GULBORDR_H__)
00035 #include <gulbordr.h>
00036 #endif
00037 
00038 #if !defined(__EIKLBED_H__)
00039 #include <eiklbed.h>
00040 #endif
00041 
00042 #if !defined(__GULUTIL_H__)
00043 #include <gulutil.h>
00044 #endif
00045 
00046 #if !defined(__LAFPUBLC_H__)
00047 #include <lafpublc.h>
00048 #endif
00049 
00050 //  FORWARD DECLARATIONS
00051 enum TKeyCode;
00052 class RIncrMatcherBase;
00053 class CListItemDrawer;
00054 class CEikScrollBarFrame;
00055 class CEikButtonBase;
00056 class CMatchBuffer;
00057 class CListBoxExt;
00058 class CEikListBox;
00059 
00060 //  CLASS DECLARATION
00061 
00070 class MListBoxItemChangeObserver
00071     {
00072     public:
00078         virtual void ListBoxItemsChanged(CEikListBox* aListBox) = 0;
00079     };
00080 
00081 // CLASS DECLARATION
00082     
00104 class CEikListBox : public CEikBorderedControl, public MEikScrollBarObserver
00105     {
00106 
00107 public:
00108 
00109     friend class CListBoxExt;
00110 
00111 public:
00112 
00116     enum TFlags
00117         {
00118         
00123         EMultipleSelection          = SLafListBox::EMultipleSelection,
00124         
00130         ENoExtendedSelection        = SLafListBox::ENoExtendedSelection,
00131         
00136         EIncrementalMatching        = SLafListBox::EIncrementalMatching,
00137         
00142         EPopout                     = SLafListBox::EPopout,
00143 
00148         ELeftDownInViewRect         = SLafListBox::ELeftDownInViewRect,
00149         
00154         EItemDoubleClicked          = SLafListBox::EItemDoubleClicked,
00155                 
00161         EKeepModel                  = SLafListBox::EKeepModel,
00162         
00168         EScrollBarSizeExcluded      = SLafListBox::EScrollBarSizeExcluded,
00169 
00173         EStateChanged               = SLafListBox::EStateChanged,
00174 
00179         ECreateOwnWindow            = SLafListBox::ECreateOwnWindow,
00180 
00184         ENoFirstLetterMatching      = SLafListBox::ENoFirstLetterMatching,
00185 
00189         EPaintedSelection           = SLafListBox::EPaintedSelection ,
00190 
00195         ELoopScrolling = 0x1000,
00196 
00200         EEnterMarks = 0x2000,       // Avkon multiselection list
00201 
00206         EShiftEnterMarks = 0x4000,  // Avkon markable list
00207 
00212         EViewerFlag = 0x8000,       // combined the two flags to fit to WORD.
00213 
00218         EPageAtOnceScrolling = 0x8000, // Avkon viewers
00219 
00223         EDisableHighlight = 0x8000,  // Avkon viewers       
00224 
00229         ES60StyleMultiselection     = SLafListBox::ES60StyleMultiselection,   
00230         
00234         ES60StyleMarkable           = SLafListBox::ES60StyleMarkable
00235         };
00236     enum {KEikMaxMatchingBufferLength = 2};
00237 
00241     enum TScrollBarOwnerShip
00242         {
00246         ENotOwnedExternally=0x0000,
00250         EOwnedExternally   =0x0001
00251         };
00252 
00253 protected:
00254 
00258     enum TReasonForFocusLost
00259         { 
00263         EFocusLostToExternalControl, 
00267         EFocusLostToInternalEditor 
00268         };
00269 
00270 public:
00274     IMPORT_C ~CEikListBox();
00275 
00279     IMPORT_C CEikListBox();
00292     IMPORT_C void ConstructL(MListBoxModel* aListBoxModel,
00293                              CListItemDrawer* aListItemDrawer,
00294                              const CCoeControl* aParent,
00295                              TInt aFlags = 0);
00296     
00312     IMPORT_C void ConstructL(MListBoxModel* aListBoxModel,
00313                              CListItemDrawer* aListItemDrawer,
00314                              const CCoeControl* aParent, 
00315                              TGulBorder aBorder, 
00316                              TInt aFlags = 0);
00326     IMPORT_C virtual TKeyResponse OfferKeyEventL(const TKeyEvent& aKeyEvent,
00327                                                  TEventCode aType);
00328     
00335     IMPORT_C virtual void HandlePointerEventL(
00336                             const TPointerEvent& aPointerEvent);
00337     
00344     IMPORT_C virtual void SetContainerWindowL(const CCoeControl& aContainer);
00345     
00351     IMPORT_C virtual TSize MinimumSize();
00352     
00359     IMPORT_C virtual void SetDimmed(TBool aDimmed);
00360 
00367     IMPORT_C virtual void HandleScrollEventL(CEikScrollBar* aScrollBar, 
00368                                              TEikScrollEvent aEventType);
00369 
00370     // model/view access functions 
00376     IMPORT_C MListBoxModel* Model() const;
00377 
00383     IMPORT_C CListBoxView* View() const;
00384 
00385     // functions for accessing top/current/bottom item index
00391     IMPORT_C TInt TopItemIndex() const;
00392     
00398     IMPORT_C virtual void SetTopItemIndex(TInt aItemIndex) const;
00399     
00405     IMPORT_C TInt BottomItemIndex() const;
00406     
00412     IMPORT_C TInt CurrentItemIndex() const;   
00413     
00421     IMPORT_C void SetCurrentItemIndex(TInt aItemIndex) const;
00422     
00429     IMPORT_C void SetCurrentItemIndexAndDraw(TInt aItemIndex) const;
00430 
00431     // functions for dealing with the selection state
00437     IMPORT_C const CListBoxView::CSelectionIndexArray* SelectionIndexes() const;
00438     
00445     IMPORT_C void SetSelectionIndexesL(
00446                 CListBoxView::CSelectionIndexArray* aArrayOfSelectionIndexes);
00447     
00451     IMPORT_C void ClearSelection(); 
00452 
00453     // Functions for updating a list box's internal state after its model has
00454     // been updated, all of them will emit item change event to item change
00455     // observers.
00459     IMPORT_C void HandleItemAdditionL();
00460     
00464     IMPORT_C void HandleItemRemovalL();
00465 
00475     IMPORT_C void HandleItemAdditionL(
00476                     CArrayFix<TInt> &aArrayOfNewIndexesAfterAddition);
00477     
00487     IMPORT_C void HandleItemRemovalL(
00488                     CArrayFix<TInt> &aArrayOfOldIndexesBeforeRemoval);
00489     
00493     IMPORT_C void Reset();
00494 
00502     IMPORT_C void AddItemChangeObserverL( MListBoxItemChangeObserver* aObserver );
00511     IMPORT_C TBool RemoveItemChangeObserver( MListBoxItemChangeObserver* aObserver );
00512 
00513     // functions for accessing the item height
00519     IMPORT_C virtual void SetItemHeightL(TInt aHeight);
00520     
00526     IMPORT_C TInt ItemHeight() const;
00527 
00528     // functions for scrollbars
00536     IMPORT_C CEikScrollBarFrame* CreateScrollBarFrameL(TBool aPreAlloc=EFalse);
00537 
00545     IMPORT_C void SetScrollBarFrame(CEikScrollBarFrame* aScrollBarFrame, TScrollBarOwnerShip aOwnerShip);
00546 
00552     IMPORT_C CEikScrollBarFrame* const ScrollBarFrame();
00553 
00557     IMPORT_C virtual void UpdateScrollBarsL();
00558 
00559     // construction support functions
00569     IMPORT_C void CalculatePopoutRect( TInt aTargetItemIndex,
00570                                        TInt aTargetYPos,
00571                                        TRect& aListBoxRect,
00572                                        TInt aMinHeightInNumOfItems = 1 );
00586     IMPORT_C TSize CalcSizeInPixels(TInt aWidthAsNumOfChars, 
00587                                     TInt aHeightAsNumOfItems) const;
00588 
00599     IMPORT_C TInt CalcWidthBasedOnNumOfChars(TInt aNumOfChars) const;
00600     
00610     IMPORT_C TInt CalcHeightBasedOnNumOfItems(TInt aNumOfItems) const;
00611     
00623     IMPORT_C TInt CalcWidthBasedOnRequiredItemWidth(
00624                                 TInt aTextWidthInPixels) const;
00625 
00626     // drawing/scrolling functions
00634     IMPORT_C void DrawItem(TInt aItemIndex) const;
00635 
00641     IMPORT_C void ScrollToMakeItemVisible(TInt aItemIndex) const;
00642 
00643 
00644     // observer support
00650     IMPORT_C void SetListBoxObserver(MEikListBoxObserver* aObserver);
00651 
00652     
00659     IMPORT_C TInt VerticalInterItemGap() const;
00660 
00661     // popouts only
00668     IMPORT_C void SetLaunchingButton(CEikButtonBase* aButton);
00669 
00670     // Editing support
00676     IMPORT_C void SetItemEditor(MEikListBoxEditor* aEditor);
00677     
00681     IMPORT_C void ResetItemEditor();
00687     IMPORT_C MEikListBoxEditor* ItemEditor();
00688     
00700     IMPORT_C virtual void EditItemL(TInt aMaxLength);
00701     
00710     IMPORT_C void StopEditingL(TBool aUpdateModel);
00711 
00712     // functions needed for Avkon shortcuts, 
00713     // passing information from one list to another
00714 
00720     IMPORT_C virtual TInt ShortcutValueForNextList();
00721     
00727     IMPORT_C virtual void SetShortcutValueFromPrevList(TInt aValue);
00728 
00729     // pop-up positioning support
00736     IMPORT_C TRect HighlightRect() const;
00737 
00738 public: // from CCoeControl
00739 
00750     IMPORT_C virtual void GetColorUseListL(
00751                         CArrayFix<TCoeColorUse>& aColorUseList) const; 
00752                         // not available before Release 005u
00753     
00763     IMPORT_C virtual void HandleResourceChange(TInt aType);         
00764                 // not available before Release 005u
00765     
00803     IMPORT_C virtual void ActivateL();
00804     
00812     IMPORT_C TCoeInputCapabilities InputCapabilities() const;
00813 
00814 private:
00818     IMPORT_C void* ExtensionInterface( TUid aInterface );
00819 
00820 protected:
00821     // Shortcuts need access to Incremental matching
00822     // The shortcuts will be used inside OfferkeyEventL().
00823     friend class AknListBoxShortCutsImplementation;
00824     // Avkon layout uses SetVerticalMargin, which is protected.
00825     friend class AknListBoxLayouts;
00826 
00841     IMPORT_C virtual void FocusChanged(TDrawNow aDrawNow);
00842     
00861     IMPORT_C virtual void SizeChanged();
00862 
00867     IMPORT_C virtual void HandleViewRectSizeChangeL();
00868     
00878     IMPORT_C virtual TInt CountComponentControls() const;
00879     
00895     IMPORT_C virtual CCoeControl* ComponentControl(TInt aIndex) const;
00896 
00897     // functions that implement first letter and incremental matching
00901     IMPORT_C void CreateMatchBufferL();  
00902 
00906     IMPORT_C void ClearMatchBuffer() const;
00907 
00913     IMPORT_C void MatchTypedCharL(TUint aCode);
00914 
00919     IMPORT_C void UndoLastChar();
00925     IMPORT_C TBool LastCharMatched() const;
00926 
00927     // functions needed for supporting scrollbars
00932     IMPORT_C virtual void UpdateScrollBarThumbs() const;
00933     
00941     IMPORT_C virtual TInt HorizScrollGranularityInPixels() const;
00942     
00951     IMPORT_C virtual TInt HorizontalNudgeValue() const;
00952     
00960     IMPORT_C virtual void AdjustTopItemIndex() const;
00961 
00962     // navigation support functions
00973     IMPORT_C void SimulateArrowKeyEventL(TKeyCode aKeyCode);
00974     
00983     IMPORT_C virtual void HandleLeftArrowKeyL(CListBoxView::TSelectionMode aSelectionMode);
00984     
00993     IMPORT_C virtual void HandleRightArrowKeyL(CListBoxView::TSelectionMode aSelectionMode);
00994 
00995     // construction support functions
01003     IMPORT_C void RestoreCommonListBoxPropertiesL(TResourceReader& aReader); 
01004 
01015     IMPORT_C virtual void ConstructL(const CCoeControl* aParent, TInt aFlags = 0);
01016     
01024     IMPORT_C virtual void CreateViewL();
01025     
01036     IMPORT_C virtual CListBoxView* MakeViewClassInstanceL();
01037     
01044     IMPORT_C void SetViewRectFromClientRect(const TRect& aClientRect);
01045     
01057     IMPORT_C virtual void RestoreClientRectFromViewRect( TRect& aClientRect) const;
01058 
01066     IMPORT_C virtual TInt AdjustRectHeightToWholeNumberOfItems( TRect& aRect) const;
01067 
01068     // accessor for Laf members
01074     IMPORT_C TMargins8 ListBoxMargins() const;
01075 
01076     // various accessors for private data members
01085     IMPORT_C TInt HorizontalMargin() const;
01086     
01096     IMPORT_C TInt VerticalMargin() const;
01097     
01103     IMPORT_C void SetHorizontalMargin(TInt aMargin);
01104     
01110     IMPORT_C void SetVerticalMargin(TInt aMargin);
01111     
01118     IMPORT_C RIncrMatcherBase* MatchBuffer() const;
01119     
01129     IMPORT_C TInt ViewRectHeightAdjustment() const;
01130     
01136     IMPORT_C TRgb BackColor() const;
01137     
01143     IMPORT_C void SetViewRectHeightAdjustment(TInt aAdjustment);
01144 
01145     // misc functions
01146     
01153     IMPORT_C virtual void ReportListBoxEventL( MEikListBoxObserver::TListBoxEvent aEvent );
01154     
01161     IMPORT_C virtual void Draw(const TRect& aRect) const;
01162     
01167     IMPORT_C void ClearMargins() const;
01168     
01176     IMPORT_C virtual void UpdateCurrentItem(TInt aItemIndex) const;
01177     
01187     IMPORT_C virtual void HandleDragEventL(TPoint aPointerPos);
01188     
01195     IMPORT_C TBool ItemExists(TInt aItemIndex) const;
01196     
01212     IMPORT_C void DrawMatcherCursor() const;
01213 
01219     IMPORT_C static TInt InterItemGap();
01220 
01225     IMPORT_C void UpdateViewColors();
01226 
01231     IMPORT_C void UpdateItemDrawerColors();
01232 
01240     IMPORT_C void FireItemChange();
01241 
01242 
01243 protected:      // functions which deal with extension
01252     IMPORT_C void SetReasonForFocusLostL( TReasonForFocusLost aReasonForFocusLost );
01253 
01259     IMPORT_C TReasonForFocusLost ReasonForFocusLostL();
01260 
01267     IMPORT_C TBool IsMatchBuffer() const;
01268 
01274     void CheckCreateExtensionL();
01275 
01285     TBool CheckCreateExtension();
01286 
01291     void CheckCreateBufferL();
01292 
01298     CMatchBuffer* Buffer() const;
01299 
01300 protected:
01306     IMPORT_C void CreateScrollBarFrameLayout(TEikScrollBarFrameLayout& aLayout) const;
01307     
01308 
01309 public:
01313     IMPORT_C TInt EventModifiers();
01314 
01315     /* 
01316     * Returns ETrue if list has ES60StyleMultiselection flag. 
01317     */
01318     IMPORT_C TBool IsMultiselection();
01319 
01320 #start_since SINCE_3_1_SDK
01321 
01334     IMPORT_C CEikScrollBarFrame* CreateScrollBarFrameL(TBool aPreAlloc, TBool aRemote);
01335 #end_since SINCE_3_1_SDK
01336 #start_since SINCE_3_1_SDK
01337         
01354     IMPORT_C CEikScrollBarFrame* CreateScrollBarFrameL(TBool aPreAlloc, TBool aRemote, TBool aWindowOwning);
01355 #end_since SINCE_3_1_SDK
01356 
01357     
01358 
01359 private:
01360     IMPORT_C virtual void CEikListBox_Reserved(); // listbox use only
01361     void HorizontalScroll(TInt aScrollAmountInPixels);
01362     void DrawItemInView(TInt aItemIndex) const;
01363     void ClearMargins(CWindowGc& aGc) const;
01364     TKeyResponse DoOfferKeyEventL(const TKeyEvent& aKeyEvent,TEventCode aType);
01365     void UpdateScrollBarColors(CEikScrollBar* aScrollBar);
01366     void UpdateScrollBarsColors();
01367 
01368     void HandleItemRemovalWithoutSelectionsL();
01369  
01370 protected:
01372     TInt iListBoxFlags;
01373     
01375     CListBoxView* iView;
01376     
01378     CListItemDrawer* iItemDrawer;
01379     
01381     MListBoxModel* iModel;
01382     
01384     TInt iItemHeight;   
01385     
01387     CEikScrollBarFrame* iSBFrame;
01388     
01390     TScrollBarOwnerShip iSBFrameOwned;
01391     
01395     TInt iRequiredHeightInNumOfItems;
01396     
01400     CEikButtonBase* iLaunchingButton; // only used by popouts
01401     
01403     MEikListBoxObserver* iListBoxObserver;
01404 
01405 private:
01406 
01407     TRgb iBackColor;
01408 //  TInt iHorizontalMargin;
01409 //  TInt iVerticalMargin;
01410     TMargins8 iMargins ;
01411     CListBoxExt* iListBoxExt;
01412     TInt iViewRectHeightAdjustment;
01413     MEikListBoxEditor* iItemEditor;
01414     TBool* iLbxDestroyed;
01415     TBool iLastCharMatched;
01416     TInt iSpare;
01417     };
01418 
01419 
01420 
01435 class CEikSnakingListBox : public CEikListBox  
01436     {
01437 public:
01441     IMPORT_C CEikSnakingListBox();
01442     
01446     IMPORT_C ~CEikSnakingListBox();
01447     
01460     IMPORT_C virtual CListBoxView* MakeViewClassInstanceL();
01461     
01467     IMPORT_C virtual void SetTopItemIndex(TInt aItemIndex) const;
01468     
01474     IMPORT_C TInt ColumnWidth() const;
01475     
01481     IMPORT_C void SetColumnWidth(TInt aColumnWidth);
01482 
01483 public: //from CCoeControl
01484     
01492     IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent);
01493 
01494 protected:
01495     
01504     IMPORT_C virtual void HandleViewRectSizeChangeL();
01505 
01514     IMPORT_C virtual void HandleLeftArrowKeyL(
01515                             CListBoxView::TSelectionMode aSelectionMode);
01516     
01525     IMPORT_C virtual void HandleRightArrowKeyL(
01526                             CListBoxView::TSelectionMode aSelectionMode);
01527     
01537     IMPORT_C virtual TInt HorizontalNudgeValue() const;
01538 
01547     IMPORT_C virtual TInt HorizScrollGranularityInPixels() const;
01548 
01556     IMPORT_C virtual void AdjustTopItemIndex() const;
01557 
01567     IMPORT_C virtual void HandleDragEventL(TPoint aPointerPos);
01568 
01580     IMPORT_C virtual void RestoreClientRectFromViewRect(
01581                                                     TRect& aClientRect) const;
01582 
01590     IMPORT_C virtual TInt AdjustRectHeightToWholeNumberOfItems(
01591                                                         TRect& aRect) const;
01592 
01598     IMPORT_C void MoveToNextOrPreviousItemL(TPoint aPoint);
01599 
01600 protected: //from CCoeControl
01601 
01608     IMPORT_C virtual void SizeChanged();
01609     
01620     IMPORT_C virtual void GetColorUseListL(
01621                     CArrayFix<TCoeColorUse>& aColorUseList) const; 
01622                     // not available before Release 005u
01632     IMPORT_C virtual void HandleResourceChange(TInt aType);         
01633                     // not available before Release 005u
01634 
01635 private: // from CCoeControl
01636     IMPORT_C void Reserved_1();
01637     
01638     IMPORT_C void Reserved_2();
01639 
01640 private:
01644     IMPORT_C void* ExtensionInterface( TUid aInterface );
01645 
01646 private:
01647     IMPORT_C virtual void CEikListBox_Reserved(); // listbox use only
01648     };
01649 
01650 // __EIKLBX_H__
01651 #endif