2 * Copyright (c) 1997-1999 Nokia Corporation and/or its subsidiary(-ies).
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".
9 * Initial Contributors:
10 * Nokia Corporation - initial contribution.
19 #if !defined(__EIKSBFRM_H__)
20 #define __EIKSBFRM_H__
23 #if !defined(__AKNSCRLB_H__)
30 * Enables setting of the frame layout for a scroll bar.
32 class TEikScrollBarFrameLayout
38 * Determines whether the client rectangle or the inclusive rectangle
44 /** The client rectangle remains constant. */
47 /** The inclusive rectangle remains constant. */
48 EInclusiveRectConstant
54 * C++ default constructor.
56 IMPORT_C TEikScrollBarFrameLayout();
59 * Sets all inclusive margins.
61 * @param aMargin The value to use for all inclusive margins.
63 IMPORT_C void SetInclusiveMargin(TInt aMargin);
66 * Sets all client margins. These surround the client rectangle which is
67 * the client area viewport onto the larger canvas to be scrolled.
69 * @param aMargin The value to use for all client margins.
71 IMPORT_C void SetClientMargin(TInt aMargin);
75 /** The inclusive margin (in twips or pixels). */
76 TMargins iInclusiveMargin;
79 * The amount of screen movement performed when the nudge button is
82 TMargins iClientMargin;
85 * The amount of screen movement performed when the nudge button is
88 TSize iClientAreaGranularity;
91 * Determines whether the client rectangle, or the inclusive rectangle,
94 TTilingMode iTilingMode;
98 class CEikCornerWindow;
99 class CEikScrollBarFrameExtension;
102 * The scroll bar frame is a control assemblage manager that relates a control,
103 * or control body, to two scroll bars and a corner window. A corner window is
104 * that part of the screen that is common to both the horizontal, and the
105 * vertical elements of a scroll bar.
107 * This class helps with access to, and set up of, scroll bars and also with
108 * the layout of the scrolled control or control body. A scroll bar frame is
109 * not a control, but it does implement the standard control composite pattern
110 * to manage the assemblage.
112 class CEikScrollBarFrame : public CBase
117 DECLARE_TYPE_ID(0x101F8672)
119 /** Defines the scroll bar’s visibility.*/
120 enum TScrollBarVisibility
122 /** Scroll bar not visible.*/
125 /** Scroll bar visible.*/
128 /** Scroll bar visible if required.*/
132 /** Defines the type of scroll bar.*/
135 /** Scroll bar complete with shaft. Not used.*/
136 ENormalScrollBar =0x0,
138 /** Floating arrow head scroll bar, without shaft. Legacy type. */
141 /** Spanned scroll bar. */
145 /** Defines where the scroll bar is located. */
149 * Scroll bar located at the bottom, or to the right of the scroll bar
155 * Scroll bar located at the top, or to the left of the scroll bar
161 /** Determines how the scroll bar frame manages scroll bars.*/
162 enum TScrollBarManagement
165 * The scroll bar frame creates, destroys and recreates, scroll bars
166 * according to the visibility mode. The scroll bar frame also acts as
167 * an intermediary with its owning control so that the scroll bars can
168 * be treated as component controls.
170 EComponent ,//=SLafScrollBarFrame::EComponent,
173 * The scroll bar frame creates, destroys and recreates, scroll bars
174 * according to the visibility mode. In this case, the scroll bars are
175 * not treated as component controls. Instead, the scroll bars are
176 * geometry managed in windows floating above the control window and
177 * their position is determined in relation to the frame’s position on
180 EFloating ,//=SLafScrollBarFrame::EFloating,
183 * The scroll bar frame uses the central application scroll bar as held
184 * in the environment. This scroll bar is neither owned by the frame
185 * nor treated as a component control of the frame’s owner.
187 EApplicationScrollBar //=SLafScrollBarFrame::EApplicationScrollBar
191 * Defines that is the horizontal or the vertical (spanned) scroll bar
192 * visible. Applicaple only for spanned scroll bars.
194 enum TScrollBarFrameFlags
196 /** Horizontal spanned scroll bar visible. */
199 /** Vertical spanned scroll bar visible. */
203 * Enables nudge buttons in touch devices. This flag MUST
204 * be set before the creation of the doublespan scrollbar.
206 EEnableNudgeButtons = 0x04,
209 * Disables expanded touch area, which is on by default
210 * in touch devices. This flag MUST be set before the
211 * creation of the doublespan scrollbar.
213 EDisableExpandedTouchArea = 0x08
216 enum TMarginsAdjustmentMode
225 * C++ default constructor.
227 CEikScrollBarFrame(){}
230 * Constructor. Constructs a scroll bar frame object.
232 * @param aParentWindow The scroll bar’s parent control.
233 * @param aObserver The scroll bar observer.
234 * @param aPreAlloc Not used.
236 IMPORT_C CEikScrollBarFrame(CCoeControl* aParentWindow,
237 MEikScrollBarObserver* aObserver,
238 TBool aPreAlloc=EFalse);
243 IMPORT_C ~CEikScrollBarFrame();
246 * Constructor. Internal only to Eikcoctl.lib use. Parameter @c aDoubleSpan
247 * offers possibility to optimize scroll bar loading (if @c ETrue,
248 * arrowhead scroll bar will never be loaded).
251 * @param aParentWindow The scroll bar’s parent control.
252 * @param aObserver The scroll bar observer.
253 * @param aPreAlloc Not used.
254 * @param aDoubleSpan If @c ETrue, spanned scroll bar is created.
256 CEikScrollBarFrame(CCoeControl* aParentWindow,
257 MEikScrollBarObserver* aObserver,
262 * Initializes a new @c CEikScrollBarFrameExtension object.
265 * @param aParentWindow The scroll bar’s parent control.
266 * @param aObserver The scroll bar observer.
268 void InitExtension(CCoeControl* aParentWindow,
269 MEikScrollBarObserver* aObserver);
272 * Forces any scroll bars and the corner window if it is visible to be
275 IMPORT_C void DrawScrollBarsNow() const;
278 * Tell scroll bars and the corner window to redraw if it is visible
280 void DrawScrollBarsDeferred() const;
283 * Sets the visibility state for both the horizontal and the vertical scroll
284 * bars. This is used when tiling.
286 * @param aHVisibility Horizontal scroll bar visibility.
287 * @param aVVisibility Vertical scroll bar visibility.
289 IMPORT_C void SetScrollBarVisibilityL(TScrollBarVisibility aHVisibility,
290 TScrollBarVisibility aVVisibility);
293 * Determines the vertical scroll bar’s visibility. @c
294 * CEikScrollBarFrame::ScrollBarVisibility @c
295 * (CEikScrollBar::TOrientation aOrientation) can be used instead of this
298 * @return Visibility for vertical scroll bar.
300 inline TScrollBarVisibility VScrollBarVisibility() const;
303 * Sets scrollbar observers.
305 * @param aObserver The scroll bar observer.
307 IMPORT_C void SetScrollBarFrameObserver(MEikScrollBarObserver* aObserver);
312 * Sets the vertical scrollbar mode. Does not actually draw anything until
313 * the thumb or focus setting functions are called.
315 * @param aVModel Model for the vertical scrollbar.
318 IMPORT_C TBool Tile(TEikScrollBarModel* aVModel);
321 * Tiles the client area and the scroll bars managed by the frame. The
322 * scroll bars are set up according to the scroll bar models; @c aHModel and
323 * @c aVModel. Ownership is not transferred as a result of passing these
324 * parameters as pointers. The result of tiling geometry management is
325 * observable through the two rectangles @c aClientRect and @c
326 * aInclusiveRect. Depending on the tiling layout @c aLayout and the scroll
327 * bar visibility settings, either of these rectangles can be made constant
328 * and the other rectangle adjusted accordingly.
330 * For @c EArrowhead type scrollbar the layout is always fixed, it cannot be
331 * altered by using this method.
333 * For @c EDoublespan type scrollbar the layout can be set also with two
334 * helper methods from the @c AknLayoutUtils class:
337 * AknLayoutUtils::LayoutVerticalScrollBar(
338 * CEikScrollBarFrame* aScrollBarFrame,
339 * const TRect& aControlParent,
340 * const TAknWindowLineLayout& aLayout);
341 * AknLayoutUtils::LayoutHorizontalScrollBar(
342 * CEikScrollBarFrame* aScrollBarFrame,
343 * const TRect& aControlParent,
344 * const TAknWindowLineLayout& aLayout);
347 * @param aHModel Horizontal scroll bar model.
348 * @param aVModel Vertical scroll bar model.
349 * @param aClientRect Client rectangle.
350 * @param aInclusiveRect A rectangle that includes the area to be scrolled
351 * and the scroll bars themselves.
352 * @param aLayout Tiling layout.
354 * @return @c ETrue if the non-constant rectangle is adjusted, otherwise @c
357 IMPORT_C TBool TileL(TEikScrollBarModel* aHModel,
358 TEikScrollBarModel* aVModel,
360 TRect& aInclusiveRect,
361 const TEikScrollBarFrameLayout& aLayout);
364 * Moves the scroll bar thumbs by the specified amounts. This updates the
365 * scroll bars after an external scroll. The values of the parameters should
366 * be supplied in terms of the horizontal and vertical scrolling models
367 * respectively. The scrolling models are presumed not to have changed
370 * @param aDeltaX The amount to move the horizontal scroll bar.
371 * @param aDeltaY The amount to move the vertical scroll bar.
373 IMPORT_C void MoveThumbsBy(TInt aDeltaX, TInt aDeltaY);
376 * Moves the horizontal scroll bar thumb to the position @c aHorizThumbPos.
377 * This function is used to update the scroll bar after an external scroll.
378 * The value of @c aThumbPos should be supplied in terms of the scrolling
379 * model, which is presumed not to have changed spans.
381 * @param aHorizThumbPos The required thumb position.
383 IMPORT_C void MoveHorizThumbTo(TInt aHorizThumbPos);
386 * Moves the vertical scroll bar thumb to the position @c aVertThumbPos.
387 * This function is used to update the scroll bar after an external scroll.
388 * The value of aThumbPos should be supplied in terms of the scrolling
389 * model, which is presumed not to have changed spans.
391 * @param aVertThumbPos The required thumb position.
393 IMPORT_C void MoveVertThumbTo(TInt aVertThumbPos);
396 * Moves the vertical scroll bar thumb to the position @c aFocusPosition.
397 * This function is used to update the scroll bar after an external scroll.
398 * The value of @c aFocusPosition should be supplied in terms of the
399 * scrolling model, which is presumed not to have changed spans.
401 * @param aFocusPosition The required thumb position.
403 IMPORT_C void SetVFocusPosToThumbPos(TInt aFocusPosition);
406 * Returns the breadth of the scroll bar idenitified by @c aOrientation, or
407 * zero if none exists.
409 * @param aOrientation The orientation of the scroll bar for which you wish
410 * to obtain the breadth.
412 * @return The specified scroll bar's breadth. This is zero if none exists.
414 IMPORT_C TInt ScrollBarBreadth(
415 CEikScrollBar::TOrientation aOrientation) const;
417 // scroll bar frame behavior functions
422 * @param aAdjusts Not used.
424 IMPORT_C void SetAdjustsHorizontalModel(TBool aAdjusts);
429 * @param aAdjusts Not used.
431 IMPORT_C void SetAdjustsVerticalModel(TBool aAdjusts);
434 * Sets scrollbar frame flags.
436 * @param aMask Bitmask of the bits that are to be set.
438 inline void SetScrollBarFrameFlags(TInt aMask);
441 * Determines whether the scroll bar specified by aOrientation exists
443 * @param aOrientation The scroll bar’s orientation.
444 * @return @c ETrue if the specified scroll bar exists otherwise @c EFalse.
446 IMPORT_C TBool ScrollBarExists(
447 CEikScrollBar::TOrientation aOrientation) const;
450 * From @c CCoeControl
452 * Gets the number of controls contained in a compound control.
454 * @return The number of component controls contained in this control.
456 IMPORT_C TInt CountComponentControls() const;
459 * From @c CCoeControl
461 * Gets the component specified by index. Within a compound control, each
462 * component control is identified by an index, where the index depends on
463 * the order the controls were added: the first is given an index of 0, the
464 * next an index of 1, and so on.
466 * @return The component control with an index of aIndex
468 IMPORT_C CCoeControl* ComponentControl(TInt aIndex) const;
471 * Returns a pointer to the scroll bar identified by orientation @c
474 * @param aOrientation The orientation of the scroll bar for which you wish
475 * to obtain a pointer.
476 * @return A pointer to the scroll bar with orientation @c aOrientation if
477 * the scrollbar is visible.
479 IMPORT_C CEikScrollBar* GetScrollBarHandle(
480 CEikScrollBar::TOrientation aOrientation) const;
483 * Returns a pointer to the vertical scroll bar.
485 * @return A pointer to the vertical scroll bar.
487 IMPORT_C CEikScrollBar* VerticalScrollBar() const;
490 * Sets the type of horizontal scroll bar. Possible values are @c EArrowHead
491 * and @c EDoubleSpan.
493 * @param aType Type of the scrollbar.
495 IMPORT_C void SetTypeOfHScrollBar(TScrollBarType aType);
498 * Sets the type of vertical scroll bar. Possible values are @c EArrowHead
499 * and @c EDoubleSpan.
501 * @param aType Type of the scrollbar.
503 IMPORT_C void SetTypeOfVScrollBar(TScrollBarType aType);
506 * Returns the control type of the horizontal scroll bar
508 * @return Type of the scrollbar.
510 IMPORT_C TScrollBarType TypeOfHScrollBar() const;
513 * Returns the control type of the vertical scroll bar
515 * @return Type of the scrollbar.
517 IMPORT_C TScrollBarType TypeOfVScrollBar() const;
520 * Checks if the vertical scrollbar type is @c EArrowHead.
522 * @param aFlag Not used.
523 * @return @c ETrue if the type of the scrollbar is @c EArrowHead.
525 IMPORT_C TBool IsArrowHeadScrollBar(TInt aFlag) const;
527 // application scroll bar utilities
530 * This method is used only internally by the @c CEikScrollBar. Disconnects
531 * externally connected scrollbar.
533 * @param aScrollBar Scrollbar to be disconnected.
535 void DisconnectExternalScrollBar(CEikScrollBar* aScrollBar);
538 * This method creates double span type scrollbars into this frame. Old
539 * scrollbars are deleted or disconnected.
542 * @param aWindowOwning Tells wheter created scrollbar should be
543 * a window owning control or not. Selection for this is
544 * relevant especially because skinned scrollbar draws
545 * @param aRemote @c True if this method should instead of creating own
546 * scrollbar try to connect to a remote scrollbar frame and
547 * start using its scrollbars. Connecting is done using
548 * through object provider mechanism, so the object supply
549 * chain must be valid. Also if true, then parameter @c
550 * aWindowOwning will be ignored.
555 * iSBFrame=new(ELeave) CEikScrollBarFrame(this, NULL, ETrue);
556 * iSBFrame->SetScrollBarVisibilityL(CEikScrollBarFrame::EOff,
557 * CEikScrollBarFrame::EAuto);
558 * iSBFrame->CreateDoubleSpanScrollBarsL(ETrue, EFalse);
560 * Note that double span scrollbar types requires different model classes
561 * to be used in places of @c TEikScrollBarModel of this scrollbar frame
562 * API:s other method calls.
564 * Scrollbar type Required model (in places of TEikScrollBarModel)
565 * --------------- ------------------------------------------------
566 * EDoubleSpan TAknDoubleSpanScrollBarModel
567 * EArrowHead TEikScrollBarModel
569 * // model for double span type scrollbar
570 * TAknDoubleSpanScrollBarModel vModel;
571 * // model for double span type scrollbar
572 * TAknDoubleSpanScrollBarModel hModel;
574 * iSBFrame->Tile(vModel, iVRect);
577 IMPORT_C void CreateDoubleSpanScrollBarsL(TBool aWindowOwning,
581 * This method creates double span type scrollbars into this frame. Old
582 * scrollbars are deleted or disconnected.
585 * @param aWindowOwning Tells wheter created scrollbar should be a window
586 * owning control or not. Selection for this is relevant especially
587 * because skinned scrollbar draws its background using its parent
588 * windows background context.
589 * @param aRemote True if this method should instead of creating own
590 * scrollbar try to connect to a remote scrollbar frame and start
591 * using its scrollbars. Connecting is done using through object
592 * provider mechanism, so the object supply chain must be valid. Also
593 * if true, then parameter @c aWindowOwning will be ignored.
594 * @param aVertical If @c ETrue vertical scrollbar will be created to
596 * @param aHorizontal If @c ETrue horizontal scrollbar will be created to
598 * @leave KErrNotFound Parent object doesn't have scrollbar frame.
600 IMPORT_C void CreateDoubleSpanScrollBarsL(TBool aWindowOwning,
606 * Tiles the vertical @c EDouble span type scroll bar managed by the frame.
607 * The scroll bar is set up according to the scroll bar model and given
608 * rectangle which is relative to the parent window of the frame.
611 * @param aVModel Vertical scrollbar model.
612 * @param aVScrollBar Vertical scrollbar rectangle.
614 * For @c EDoublespan type scrollbar the layout can be set also with a
615 * helper method from the @c AknLayoutUtils class:
618 * AknLayoutUtils::LayoutVerticalScrollBar(
619 * CEikScrollBarFrame* aScrollBarFrame,
620 * const TRect& aControlParent,
621 * const TAknWindowLineLayout& aLayout);
624 IMPORT_C void Tile(TEikScrollBarModel* aVModel, TRect& aVScrollBar);
627 * Sets the models of the scrollbars.
630 * @param aHModel The model of the horizontal scrollbar.
631 * @param aVModel The model of the vertical scrollbar.
634 IMPORT_C void Tile(TEikScrollBarModel* aHModel,
635 TEikScrollBarModel* aVModel);
638 * Gets the visibility of given scrollbar orientation.
640 * This method should be used instead of a deprecated method @c
641 * CEikScrollBarFrame::HScrollBarVisibility() and
642 * also can be used instead of @c CEikScrollBarFrame::VScrollBarVisibility()
645 * @param aOrientation The orientation of a scrollbar in the frame.
646 * @return The visibility of requested scrollbar.
648 IMPORT_C TScrollBarVisibility ScrollBarVisibility(
649 CEikScrollBar::TOrientation aOrientation) const;
651 * Sets the background drawing for the double spanned scrollbars
653 * This method can be used to enable or disable the drawing of the scrollbar
654 * background via mop chain.
657 * @param aDrawHorizontal sets the state of the background drawing of
658 * the horizontal scrollbar.
659 * @param aDrawVertical sets the state of the background drawing of
660 * the vertical scrollbar.
661 * @return Success of the call, KErrNotSupported if the scrollbars
662 * are not doublespan scrollbars.
665 IMPORT_C TInt DrawBackground(TBool aDrawHorizontal, TBool aDrawVertical);
668 * Gets the state of the background drawing for the double spanned scrollbars.
670 * This method can be used to get the state of drawing of the scrollbar
671 * background via mop chain.
674 * @param aDrawHorizontal gets the state of the background drawing of
675 * the horizontal scrollbar.
676 * @param aDrawVertical gets the state of the background drawing of
677 * the vertical scrollbar.
678 * @return Success of the call, KErrNotSupported if the scrollbars
679 * are not doublespan scrollbars.
682 IMPORT_C TInt DrawBackgroundState(TBool& aDrawHorizontal, TBool& aDrawVertical);
687 * Gets a pointer to the horizontal scroll bar.
689 * @return A pointer to the horizontal scroll bar.
691 CEikScrollBar* HorizontalScrollBar() const;
694 * Sets scrollbar observers.
696 * @param aObserver The scroll bar observer.
698 MEikScrollBarObserver* ScrollBarFrameObserver();
704 * Sets parent window.
706 * @param aParentWindow A pointer to the parent window.
708 void SetParentWindow(CCoeControl* aParentWindow);
711 * Gets a pointer to the parent window.
713 * @return A pointer to the parent window.
715 CCoeControl* ParentWindow() const;
723 /** Pointer to the @c CAknScrollBar class */
726 /** Enum @c TEikScrollBarModel */
727 TEikScrollBarModel iModel;
729 /** Enum @c TScrollBarVisibility. */
730 TScrollBarVisibility iVisibility;
732 /** Boolean value if external scroll bar is attached. */
733 TBool iExternalScrollBarAttached;
738 void CalcTheoreticalScrollBarVisibility(const TEikScrollBarModel* aVModel);
739 void ApplyModel(SBarData& aSBar);
740 void MakeSBarVisible(SBarData& aSBar, TBool aVisible);
741 void GetScrollBars(TBool aDoubleSpan);
742 CEikCba* GetCurrentCba();
743 void DeleteScrollBars();
744 void CreateArrowHeadScrollBarsL();
746 void CalcTheoreticalScrollBarVisibility(const TEikScrollBarModel* aVModel,
747 const TEikScrollBarModel* aHModel);
756 CEikScrollBarFrameExtension* iExtension;
757 TInt iScrollBarFrameFlags;
759 friend class CEikScrollBarFrameExtension;
762 inline CEikScrollBarFrame::TScrollBarVisibility CEikScrollBarFrame::VScrollBarVisibility() const
763 { return iV.iVisibility; }
764 inline void CEikScrollBarFrame::SetScrollBarFrameFlags(TInt aMask)
765 { iScrollBarFrameFlags|=aMask; }
767 // Cba scroll bar frame (with it's own scrollbar creation methods)
768 class CEikCbaScrollBarFrame : public CEikScrollBarFrame
771 CEikCbaScrollBarFrame(CCoeControl* aParentWindow, MEikScrollBarObserver* aObserver, TBool aPreAlloc=EFalse);
773 void SwitchToArrowHeadScrollBarL(); // @since 3.0