Class CQikScrollableContainer

class CQikScrollableContainer : public CQikContainerBase, public MEikScrollBarObserver;

Description

This is a container for CCoeControl-derived controls that adds horizontal and/or vertical scrollbar(s) when needed. To use this container, simply: 1. add the controls to it 2a. add a layout manager, or 2b. position them manually relative the upper left corner of the scrolling page 2b.1 call the MinimumPageSize() method to find the size needed to hold all the controls. Use the SetPageSize() method to set the size of the scrolling page. A margin is added to the size given when a scrollbar is needed (can be changed with the SetBottomRightMargin() method).

Derivation

• MEikScrollBarObserver - This mixin is implemented by classes wishing to receive notification about scroll events from a scroll bar
• MQikRelayoutSensitiveControl - A mixin for controls that have a special behaviour when a view changes layouts
• MQikContainer - A mixin for controls that allows other classes to add and remove controls via a generic API

MEikBorderedControl - Interface for bordered controls

MObjectProvider - An interface that allows an object to be part of a network of object providers

CBase - Base class for all classes to be instantiated on the heap

• CCoeControl - Control base class from which all other controls are derived
• CEikBorderedControl - A control which is drawn surrounded by a rectangular border
• CQikContainerBase - A generic base class for container controls
• CQikScrollableContainer - This is a container for CCoeControl-derived controls that adds horizontal and/or vertical scrollbar(s) when needed

Members

Defined in CQikScrollableContainer:
ActivateL(), AddControlLC(), BeginUpdateLC(), Border(), BottomRightMargin(), CQikScrollableContainer(), CalculateRowInfo(), ComponentControl(), ConstructFromResourceL(), ConstructL(), ConstructL(), ContainerWindow(), Controls(), Controls(), ControlsFitOnPage(), CountComponentControls(), DeleteControl(), Draw(), EndUpdateL(), FocusChanged(), GetColorUseListL(), GetHelpContext(), HandleControlArrayEventL(), HandlePointerBufferReadyL(), HandlePointerEventL(), HandleResourceChange(), HandleScrollEventL(), HasBorder(), InitializeFromResourceL(), InputCapabilities(), LayoutManager(), LayoutManagerOfPage(), MakeVisible(), MinimumPageSize(), MinimumSize(), MopSupplyObject(), OfferKeyEventL(), Page(), PageSize(), PerformLayout(), PersistsAfterRelayout(), PositionChanged(), PrepareForFocusGainL(), PrepareForFocusLossL(), ReleaseControls(), RemoveControl(), RequestRelayout(), ResetAndDestroy(), Scroll(), ScrollBarFrame(), ScrollBarsNeeded(), ScrollOffset(), ScrollTo(), ScrollTo(), ScrollToMakeVisible(), SetAdjacent(), SetBorder(), SetBorder(), SetBottomRightMargin(), SetContainerWindowL(), SetDimmed(), SetLayoutManagerL(), SetNeighbor(), SetPageSize(), SetParent(), SetScrollObserver(), SetTextBaselineSpacing(), SizeChanged(), TextBaselineOffset(), UpdateScrollBarsL(), WriteInternalStateL(), ~CQikScrollableContainer()

Inherited from CBase:
Delete(), Extension_(), operator new()

Inherited from CCoeControl:
AccumulatedZoom(), ActivateGc(), BackedUpWindow(), Background(), CapturesPointer(), ClaimPointerGrab(), CloseWindow(), Components(), ControlContext(), ControlEnv(), CopyControlContextFrom(), CreateBackedUpWindowL(), CreateWindowL(), DeactivateGc(), DrawBackground(), DrawDeferred(), DrawForeground(), DrawNow(), DrawableWindow(), EAbsoluteZoom, ERelativeZoom, EnableDragEvents(), FindBackground(), FindFontProvider(), GetColor(), GetGc(), GrabbingComponent(), HandleComponentControlsResourceChange(), HandleRedrawEvent(), HitTest(), IgnoreEventsUntilNextPointerUp(), Index(), InitComponentArrayL(), IsActivated(), IsBackedUp(), IsBeingDestroyed(), IsBlank(), IsDimmed(), IsFocused(), IsNonFocusing(), IsReadyToDraw(), IsVisible(), MaximumWidth(), Observer(), OverrideColorL(), OwnsWindow(), Parent(), Position(), PositionRelativeToScreen(), Rect(), RecursivelyMergedInputCapabilities(), ReportEventL(), Reserved_CCoeControl_10(), Reserved_CCoeControl_11(), Reserved_CCoeControl_12(), Reserved_CCoeControl_13(), ResetGc(), ScreenFont(), SetAllowStrayPointers(), SetBackground(), SetBlank(), SetCanDrawOutsideRect(), SetComponentsToInheritVisibility(), SetControlContext(), SetCornerAndSize(), SetExtent(), SetExtentToWholeScreen(), SetFocus(), SetFocusing(), SetFontProviderL(), SetGc(), SetGloballyCapturing(), SetHitTest(), SetMaximumWidth(), SetMopParent(), SetNonFocusing(), SetObserver(), SetPointerCapture(), SetPosition(), SetRect(), SetSize(), SetSizeWithoutNotification(), SetUniqueHandle(), SetZoomFactorL(), Size(), SystemGc(), TZoomType, TextDrawer(), UniqueHandle(), Window(), ZoomWithType(), iCoeEnv, iContext, iPosition, iSize

Inherited from CEikBorderedControl:
iBorder

Inherited from CQikContainerBase:
BaseConstructL(), ControlsOwnedExternally(), ETypeId, HandlesRelayoutRequests(), HorizontalWrappingEnabled(), IsRelayoutInProgress(), RowBasedMode(), SetDebugMode(), SetHandleRelayoutRequests(), SetHorizontalWrappingEnabled(), SetPersistsAfterRelayout(), SetRelayoutInProgress(), SetRowBasedMode(), SetVerticalWrappingEnabled(), VerticalWrappingEnabled(), anonymous

Inherited from MObjectProvider:
MopGetObject(), MopGetObjectNoChaining()

IMPORT_C CQikScrollableContainer();

Description

Default constructor, it partially build a CQikScrollableContainer. the construction process will be not complete until ConstructL() it's called and executed.

See also:

• ~CQikScrollableContainer()
• ConstructL(TBool aPreAllocScrollBar)
• ConstructL(TBool aPreAllocScrollBar, TBool aComponentsOwnedExternally)

IMPORT_C ~CQikScrollableContainer();

Description

Default Destructor

IMPORT_C void ConstructL(TBool aPreAllocScrollBar);

Description

Second step in construction process.

Parameters

TBool aPreAllocScrollBar ETrue to pre-allocate, otherwise EFalse

See also:

• CQikScrollableContainer()

IMPORT_C void ConstructL(TBool aPreAllocScrollBar, TBool aControlsOwnedExternally);

Description

Second step in construction process.

Parameters

TBool aPreAllocScrollBar ETrue to pre-allocate, otherwise EFalse TBool aControlsOwnedExternally ETrue if component controls are owned externally, otherwise EFalse

See also:

• CQikScrollableContainer()

IMPORT_C CEikScrollBarFrame *ScrollBarFrame();

Description

returns a pointer to the contained ScrollBarFrame

Return value

CEikScrollBarFrame * the pointer to the ScrollBarFrame

IMPORT_C TInt DeleteControl(CCoeControl &aControl);

Description

Delete a control from the scrollable container.

Parameters

CCoeControl &aControl The CCoeControl to be deleted.

Return value

TInt Returns KErrNone or KErrNotFound.

Panic codes

EQikPanicControlOwnedExternally DEBUG_BUILDS: Component controls are owned externally. RELEASE_BUILDS: does nothing.

IMPORT_C void ResetAndDestroy();

Description

Removes and deletes all controls from the scrollable container.

IMPORT_C TSize MinimumPageSize() const;

Description

Calculate the minimum size needed for the scrolling page to hold all the controls added to it, plus a margin to the right and bottom. Scrollbar(s) are added and removed as needed.

Return value

TSize

IMPORT_C void SetPageSize(TSize aSize);

Description

Set the (minimum) size to be used by the scrolling page. Scrollbar(s) are added and removed as needed.

Parameters

TSize aSize The size of the page to be scrolled.

IMPORT_C TSize PageSize() const;

Description

Returns the size of the scrolling page.

Return value

TSize The current size of the scrolling page.

Interface status:

deprecated

Use ContainerWindow() instead

inline const CCoeControl &Page() const;

Description

Returns a reference to the page of the scrolling container. Use this as ContainerWindow for all controls (and their subcontrols) that you add to the scrollable container.

Return value

const CCoeControl & A reference to the control that truly is the container of the controls added to the scrolling container.

IMPORT_C MCoeLayoutManager *LayoutManagerOfPage() const;

Description

Gets the layout manager of the page

Return value

MCoeLayoutManager * The layout manager of the page, or NULL if none.

IMPORT_C TBool ControlsFitOnPage() const;

Description

Predicate function used to tell whether the controls added to the scrollable container fit on the scrolling page, given its current size.

Return value

TBool ETrue if all controls fully fit on the scrolling page. EFalse otherwise.

IMPORT_C void UpdateScrollBarsL();

Description

Updates the (thumb of the) scrollbar(s).

IMPORT_C void ScrollToMakeVisible(const CCoeControl *aControl) const;

Description

Scroll the page to make a control visible

Parameters

const CCoeControl *aControl control to be made visible

See also:

• #Scroll(TInt aDeltaX, TInt aDeltaY)
• #ScrollTo( TPoint aTopLeft )

IMPORT_C TPoint ScrollOffset() const;

Description

Return value

TPoint

IMPORT_C void ScrollTo(TPoint aTopLeft) const;

Description

Scroll the page

Parameters

TPoint aTopLeft point at the top-left of the control

See also:

• #Scroll(TInt aDeltaX, TInt aDeltaY)
• #ScrollToMakeVisible( const CCoeControl* aControl )

IMPORT_C void ScrollTo(TRect aRect) const;

Description

Scrolls the page to make a rect visible

Parameters

TRect aRect The rect to be made visible

IMPORT_C void Scroll(TInt aDeltaX, TInt aDeltaY) const;

Description

Scroll the page

Parameters

TInt aDeltaX amount of scroll on the x axis TInt aDeltaY amount of scroll on the y axis

See also:

• #ScrollToMakeVisible( TPoint aTopLeft )
• #ScrollToMakeVisible( const CCoeControl* aControl )

IMPORT_C void SetBottomRightMargin(TSize aMargin);

Description

Use this method to set the margin that is added to the right and bottom of the scrolling page.

Parameters

TSize aMargin The margin to be added, in pixels.

IMPORT_C TSize BottomRightMargin() const;

Description

Returns the margin added to the right and bottom of the scrolling page.

Return value

TSize The margin added.

IMPORT_C void SetScrollObserver(MEikScrollBarObserver *aObserver);

Description

Sets an external scroll observer if needed. This is normally not the case, since the scrollable container handles all normal scrolling functionality.

Parameters

MEikScrollBarObserver *aObserver An (additional external) MEikScrollBarObserver to inform about scroll events.

IMPORT_C void ScrollBarsNeeded(TBool &aVerticalScrollBar, TBool &aHorizontalScrollBar) const;

Description

set if a scrollbar is needed

Parameters

TBool &aVerticalScrollBar true if a vertical scrollbar is needed TBool &aHorizontalScrollBar true if a horizontal scrollbar is needed

virtual IMPORT_C void ConstructFromResourceL(TResourceReader &aReader);

Description

Reads a QIK_SCROLLABLE_CONTAINER

Parameters

TResourceReader &aReader

See also:

• CCoeControl::ConstructFromResourceL

virtual IMPORT_C TKeyResponse OfferKeyEventL(const TKeyEvent &aKeyEvent, TEventCode aType);

Description

Handles key events Called by the Epoc framework.

Parameters

const TKeyEvent &aKeyEvent TEventCode aType

Return value

TKeyResponse Indicates whether or not the key event was used by this control

virtual IMPORT_C void MakeVisible(TBool aVisible);

Description

Sets this control as visible or invisible. This causes the control to disappear or reappear

Parameters

TBool aVisible ETrue to make the control visible, EFalse to make it invisible

virtual IMPORT_C const CCoeControl &ContainerWindow() const;

Description

Gets the page

Return value

const CCoeControl &

See also:

• CQikContainerBase::ContainerWindow

virtual IMPORT_C void InitializeFromResourceL(TResourceReader &aReader, MQikControlProvider &aProvider);

Description

Reads a QIK_SCROLLABLE_CONTAINER_SETTINGS and creates controls, layout manager, and layout data accordingly.

Parameters

TResourceReader &aReader MQikControlProvider &aProvider

See also:

• CQikContainerBase::InitializeFromResourceL

virtual IMPORT_C void SetLayoutManagerL(MCoeLayoutManager *aLayout);

Description

Sets the layout manager of the page

Parameters

MCoeLayoutManager *aLayout

See also:

• CCoeControl::SetLayoutManagerL

IMPORT_C MCoeLayoutManager *LayoutManager() const;

Description

Returns NULL since the scrollable container cannot have its own layout manager. Use LayoutManagerOfPage() if you want to get the layout manager of the page.

Return value

MCoeLayoutManager *

See also:

• LayoutManagerOfPage

virtual IMPORT_C TSize MinimumSize();

Description

Return value

TSize

See also:

• CCoeControl::MinimumSize

protected: virtual IMPORT_C void HandleScrollEventL(CEikScrollBar *aScrollBar, TEikScrollEvent aEventType);

Description

handles scroll events, performing the scrolling Called by the Epoc framework.

Parameters

CEikScrollBar *aScrollBar scrollbar where the event occurred TEikScrollEvent aEventType the event's type

protected: virtual IMPORT_C void SizeChanged();

Description

Resizes and repositions the parts of the scrollable container.

See also:

• CCoeControl::SizeChanged

protected: virtual IMPORT_C TInt CountComponentControls() const;

Description

Return value

TInt

See also:

• CCoeControl::CountComponentControls

protected: virtual IMPORT_C CCoeControl *ComponentControl(TInt aIndex) const;

Description

Gets the specified component of a compound control Called by the Epoc framework.

Parameters

TInt aIndex The index of the control to be returned.

Return value

CCoeControl * A pointer to one of the control's sub-controls.

protected: virtual IMPORT_C void WriteInternalStateL(RWriteStream &aWriteStream) const;

Description

Writes the internal state of the control and its components to aStream. Does nothing in release mode. Designed to be overridden and base called by subclasses.

Parameters

RWriteStream &aWriteStream

virtual IMPORT_C void BeginUpdateLC();

Description

This method should be called before updates to the layout, and/or addition/removal of controls. The cleanup stack item pushed to the cleanup stack by this method is popped by EndUpdateL() so you should always call them in pairs and not pop the cleanup item yourself.

See also:

• EndUpdateL
• CQikContainerBase::BeginUpdateLC()

virtual IMPORT_C void EndUpdateL();

Description

This method should be called when updates to the layout is done after BeginUpdateLC() is called. This method makes sure that a relayout is performed, and might also peform transitions effects and similar operations depending on the device.

See also:

• BeginUpdateLC
• CQikContainerBase::EndUpdateL()

virtual IMPORT_C CCoeControlArray &Controls();

Description

Returns a list of the controls in the container.

Return value

CCoeControlArray & A list of controls.

See also:

• CQikContainerBase::Controls()

virtual IMPORT_C const CCoeControlArray &Controls() const;

Description

Returns a list of the controls in the container.

Return value

const CCoeControlArray & A list of controls.

See also:

• CQikContainerBase::Controls()

virtual IMPORT_C TTypeUid::Ptr MopSupplyObject(TTypeUid aId);

Description

Supports CQikContainerBase , MQikContainer , and MQikRelayoutSensitiveControl .

Parameters

TTypeUid aId

Return value

TTypeUid::Ptr

See also:

• CCoeControl::MopSupplyObject

virtual IMPORT_C TBool RequestRelayout(const CCoeControl *aChildControl);

Description

Handles the request if CQikContainerBase::HandleRelayoutRequests() .

Parameters

const CCoeControl *aChildControl

Return value

TBool

See also:

• CCoeControl::RequestRelayout
• CQikContainerBase::HandleRelayoutRequests

virtual IMPORT_C void GetColorUseListL(CArrayFix< TCoeColorUse > &aColorUseList) const;

Description

Gets a list of logical colours employed in the drawing of the control paired with an explanation of how they are used.

Appends the list to aColorUseList .

Parameters

CArrayFix< TCoeColorUse > &aColorUseList List of logical colours with an explanation of how they are used.

See also:

• CCoeControl::GetColorUseListL()

virtual IMPORT_C void HandleResourceChange(TInt aType);

Description

Handles a change to the control's resources which are shared across the environment.

Parameters

TInt aType The type of resource that has changed.

See also:

• CCoeControl::HandleResourceChange()

virtual IMPORT_C void PrepareForFocusGainL();

Description

Notifier called upon before the control gains focus.

See also:

• CCoeControl::PrepareForFocusGainL()

virtual IMPORT_C void PrepareForFocusLossL();

Description

Notifier called upon before the control loses focus.

See also:

• CCoeControl::PrepareForFocusLossL()

virtual IMPORT_C TBool HasBorder() const;

Description

Tests if the control has a border.

Return value

TBool ETrue if the control has a border, EFalse if the control does not have a border. The default implementation of this function returns EFalse.

See also:

• CCoeControl::HasBorder()

virtual IMPORT_C void SetAdjacent(TInt aAdjacent);

Description

Sets the control's appearance when it is next to other controls.

Parameters

TInt aAdjacent Typically a value defined in TGulAdjacent.

See also:

• CCoeControl::SetAdjacent()

virtual IMPORT_C void SetDimmed(TBool aDimmed);

Description

Sets the control to be dimmed.

Parameters

TBool aDimmed ETrue to dim the control, EFalse to set the control as not dimmed.

See also:

• CCoeControl::SetDimmed()

virtual IMPORT_C void SetContainerWindowL(const CCoeControl &aContainer);

Description

Sets the control's containing window by copying it from aContainer.

Parameters

const CCoeControl &aContainer The compound control that is the container for this control

See also:

• CCoeControl::SetContainerWindowL()

virtual IMPORT_C void ActivateL();

Description

Sets the control as ready to be drawn.

See also:

• CCoeControl::ActivateL()

virtual IMPORT_C void SetNeighbor(CCoeControl *aNeighbor);

Description

Sets an associated control.

Parameters

CCoeControl *aNeighbor A control to be used by this function.

See also:

• CCoeControl::SetNeighbor()

virtual IMPORT_C void GetHelpContext(TCoeHelpContext &aContext) const;

Description

Gets the control's help context.

Parameters

TCoeHelpContext &aContext The control's help context

See also:

• CCoeControl::GetHelpContext()

virtual IMPORT_C TInt SetParent(CCoeControl *aParent);

Description

Sets aParent as the parent of this control.

Parameters

CCoeControl *aParent The control to set as this control's parent.

Return value

TInt KErrNone if successful, otherwise another of the system error codes.

See also:

• CCoeControl::SetParent()

virtual IMPORT_C TInt TextBaselineOffset(const TSize &aSize) const;

Description

Gets the offset to the first text baseline relative to the top of the control.

Parameters

const TSize &aSize The offset of the baseline may depend on the size of the control. This argument specifies the size to use when computing the baseline offset.

Return value

TInt The offset of the baseline from the top of the control.

See also:

• CCoeControl::TextBaselineOffset()

virtual IMPORT_C void SetTextBaselineSpacing(TInt aSpacing);

Description

Sets the spacing between text baselines.

Parameters

TInt aSpacing The baseline spacing i.e. the space in pixels between the text baselines.

See also:

• CCoeControl::SetTextBaselineSpacing()

virtual IMPORT_C TCoeInputCapabilities InputCapabilities() const;

Description

Returns the controls input capabilities.

Return value

TCoeInputCapabilities The controls input capabilities.

See also:

• CCoeControl::InputCapabilities()

virtual IMPORT_C void AddControlLC(CCoeControl *aControl, TInt aComponentId=KErrNotFound);

Description

Parameters

CCoeControl *aControl TInt aComponentId

See also:

• MQikContainer::AddControlLC

virtual IMPORT_C TInt RemoveControl(CCoeControl &aControl);

Description

Parameters

CCoeControl &aControl

Return value

TInt

See also:

• MQikContainer::RemoveControl

virtual IMPORT_C TBool PersistsAfterRelayout() const;

Description

Return value

TBool

See also:

• MQikRelayoutSensitiveControl::PersistsAfterRelayout

virtual IMPORT_C void ReleaseControls(RQikReleasedControlsArray &aReleasedControls);

Description

Parameters

RQikReleasedControlsArray &aReleasedControls

See also:

• MQikRelayoutSensitiveControl::ReleaseControls

virtual IMPORT_C void SetBorder(TGulBorder::TBorderType aBorderType);

Description

Sets the border type from enum.

Parameters

TGulBorder::TBorderType aBorderType New value for the border type.

See also:

• MEikBorderedControl::SetBorder()

virtual IMPORT_C void SetBorder(TInt aBorderType);

Description

Sets the border type from value.

Parameters

TInt aBorderType New value for the border type.

See also:

• MEikBorderedControl::SetBorder()

virtual IMPORT_C TGulBorder Border() const;

Description

Gets the border type.

Return value

TGulBorder The border type.

See also:

• MEikBorderedControl::Border()

protected: virtual IMPORT_C void HandlePointerEventL(const TPointerEvent &aPointerEvent);

Description

Forwards the HandlePointerEventL to appropriate component control. Also handles drag above/below window.

Parameters

const TPointerEvent &aPointerEvent

See also:

• ClosestFocusingControl
• CCoeControl::HandlePointerEventL()

protected: virtual IMPORT_C void HandleControlArrayEventL(CCoeControlArray::TEvent aEvent, const CCoeControlArray *aArray, CCoeControl *aControl, TInt aControlId);

Description

Handles events generated by the CCoeControlArray. From CCoeControl .

Parameters

CCoeControlArray::TEvent aEvent The type of the event const CCoeControlArray *aArray The array that generated the event CCoeControl *aControl The control affected by the event TInt aControlId The id of the control affected by the event

See also:

• CCoeControl::HandleControlArrayEventL()

protected: virtual IMPORT_C void Draw(const TRect &aRect) const;

Description

Parameters

const TRect &aRect

See also:

• CCoeControl::Draw()

protected: virtual IMPORT_C void CalculateRowInfo(const TSize &aVisibleSize);

Description

Calculates the row information given the visible size of the container, and notifies the layout manager and component controls (which are MQikRowAwareControl) of the change.

Parameters

const TSize &aVisibleSize The size of the visible area

protected: virtual IMPORT_C void PerformLayout();

Description

Handle a relayout request. Is called asynchronously when RequestRelayout() has been called and HandleRelayoutRequests() is ETrue.

See also:

• RequestRelayout
• HandleRelayoutRequests

protected: virtual IMPORT_C void HandlePointerBufferReadyL();

Description

Handles pointer buffer ready events.

See also:

• CCoeControl::HandlePointerBufferReadyL()

protected: virtual IMPORT_C void FocusChanged(TDrawNow aDrawNow);

Description

Responds to a change in focus.

Parameters

TDrawNow aDrawNow Contains the value that was passed to it by SetFocus().

See also:

• CCoeControl::FocusChanged()