Public Member Functions | Static Public Attributes | Protected Member Functions | Protected Attributes

CEGUI::ScrollablePane Class Reference

Base class for the ScrollablePane widget. More...

Inheritance diagram for CEGUI::ScrollablePane:
Collaboration diagram for CEGUI::ScrollablePane:

List of all members.

Public Member Functions

 ScrollablePane (const String &type, const String &name)
 Constructor for the ScrollablePane base class.
 ~ScrollablePane (void)
 Destructor for the ScrollablePane base class.
const ScrolledContainergetContentPane (void) const
 Returns a pointer to the window holding the pane contents.
bool isVertScrollbarAlwaysShown (void) const
 Return whether the vertical scroll bar is always shown.
void setShowVertScrollbar (bool setting)
 Set whether the vertical scroll bar should always be shown.
bool isHorzScrollbarAlwaysShown (void) const
 Return whether the horizontal scroll bar is always shown.
void setShowHorzScrollbar (bool setting)
 Set whether the horizontal scroll bar should always be shown.
bool isContentPaneAutoSized (void) const
 Return whether the content pane is auto sized.
void setContentPaneAutoSized (bool setting)
 Set whether the content pane should be auto-sized.
const RectgetContentPaneArea (void) const
 Return the current content pane area for the ScrollablePane.
void setContentPaneArea (const Rect &area)
 Set the current content pane area for the ScrollablePane.
float getHorizontalStepSize (void) const
 Returns the horizontal scrollbar step size as a fraction of one complete view page.
void setHorizontalStepSize (float step)
 Sets the horizontal scrollbar step size as a fraction of one complete view page.
float getHorizontalOverlapSize (void) const
 Returns the horizontal scrollbar overlap size as a fraction of one complete view page.
void setHorizontalOverlapSize (float overlap)
 Sets the horizontal scrollbar overlap size as a fraction of one complete view page.
float getHorizontalScrollPosition (void) const
 Returns the horizontal scroll position as a fraction of the complete scrollable width.
void setHorizontalScrollPosition (float position)
 Sets the horizontal scroll position as a fraction of the complete scrollable width.
float getVerticalStepSize (void) const
 Returns the vertical scrollbar step size as a fraction of one complete view page.
void setVerticalStepSize (float step)
 Sets the vertical scrollbar step size as a fraction of one complete view page.
float getVerticalOverlapSize (void) const
 Returns the vertical scrollbar overlap size as a fraction of one complete view page.
void setVerticalOverlapSize (float overlap)
 Sets the vertical scrollbar overlap size as a fraction of one complete view page.
float getVerticalScrollPosition (void) const
 Returns the vertical scroll position as a fraction of the complete scrollable height.
void setVerticalScrollPosition (float position)
 Sets the vertical scroll position as a fraction of the complete scrollable height.
Rect getViewableArea (void) const
 Return a Rect that described the pane's viewable area, relative to this Window, in pixels.
ScrollbargetVertScrollbar () const
 Return a pointer to the vertical scrollbar component widget for this ScrollablePane.
ScrollbargetHorzScrollbar () const
 Return a pointer to the horizontal scrollbar component widget for this ScrollablePane.
void initialiseComponents (void)
 Initialises the Window based object ready for use.
void destroy (void)
 Internal destroy method which actually just adds the window and any parent destructed child windows to the dead pool.

Static Public Attributes

static const String WidgetTypeName
 Window factory name.
static const String EventNamespace
 Namespace for global events.
static const String EventContentPaneChanged
static const String EventVertScrollbarModeChanged
static const String EventHorzScrollbarModeChanged
static const String EventAutoSizeSettingChanged
static const String EventContentPaneScrolled
static const String VertScrollbarNameSuffix
 Widget name suffix for the vertical scrollbar component.
static const String HorzScrollbarNameSuffix
 Widget name suffix for the horizontal scrollbar component.
static const String ScrolledContainerNameSuffix
 Widget name suffix for the scrolled container component.

Protected Member Functions

void configureScrollbars (void)
 display required integrated scroll bars according to current size of the ScrollablePane view area and the size of the attached ScrolledContainer.
bool isVertScrollbarNeeded (void) const
 Return whether the vertical scrollbar is needed.
bool isHorzScrollbarNeeded (void) const
 Return whether the horizontal scrollbar is needed.
void updateContainerPosition (void)
 Update the content container position according to the current state of the widget (like scrollbar positions, etc).
virtual bool testClassName_impl (const String &class_name) const
 Return whether this window was inherited from the given class name at some point in the inheritance hierarchy.
ScrolledContainergetScrolledContainer () const
 Return a pointer to the ScrolledContainer component widget for this ScrollablePane.
virtual bool validateWindowRenderer (const String &name) const
 Function used in checking if a WindowRenderer is valid for this window.
virtual void onContentPaneChanged (WindowEventArgs &e)
 Event trigger method called when some pane content has changed size or location.
virtual void onVertScrollbarModeChanged (WindowEventArgs &e)
 Event trigger method called when the setting that controls whether the vertical scrollbar is always shown or not, is changed.
virtual void onHorzScrollbarModeChanged (WindowEventArgs &e)
 Event trigger method called when the setting that controls whether the horizontal scrollbar is always shown or not, is changed.
virtual void onAutoSizeSettingChanged (WindowEventArgs &e)
 Notification method called whenever the setting that controls whether the content pane is automatically sized is changed.
virtual void onContentPaneScrolled (WindowEventArgs &e)
 Notification method called whenever the content pane is scrolled via changes in the scrollbar positions.
bool handleScrollChange (const EventArgs &e)
 Handler method which gets subscribed to the scrollbar position change events.
bool handleContentAreaChange (const EventArgs &e)
 Handler method which gets subscribed to the ScrolledContainer content change events.
bool handleAutoSizePaneChanged (const EventArgs &e)
 Handler method which gets subscribed to the ScrolledContainer auto-size setting changes.
void addChild_impl (Window *wnd)
 Add given window to child list at an appropriate position.
void removeChild_impl (Window *wnd)
 Remove given window from child list.
void onSized (WindowEventArgs &e)
 Handler called when the window's size changes.
void onMouseWheel (MouseEventArgs &e)
 Handler called when the mouse wheel (z-axis) position changes within this window's area.

Protected Attributes

bool d_forceVertScroll
 true if vertical scrollbar should always be displayed
bool d_forceHorzScroll
 true if horizontal scrollbar should always be displayed
Rect d_contentRect
 holds content area so we can track changes.
float d_vertStep
 vertical scroll step fraction.
float d_vertOverlap
 vertical scroll overlap fraction.
float d_horzStep
 horizontal scroll step fraction.
float d_horzOverlap
 horizontal scroll overlap fraction.
Event::Connection d_contentChangedConn
 Event connection to content pane.
Event::Connection d_autoSizeChangedConn
 Event connection to content pane.

Detailed Description

Base class for the ScrollablePane widget.

The ScrollablePane widget allows child windows to be attached which cover an area larger than the ScrollablePane itself and these child windows can be scrolled into view using the scrollbars of the scrollable pane.


Member Function Documentation

void CEGUI::ScrollablePane::destroy ( void   )  [virtual]

Internal destroy method which actually just adds the window and any parent destructed child windows to the dead pool.

This is virtual to allow for specialised cleanup which may be required in some advanced cases. If you override this for the above reason, you MUST call this base class version.

Note:
You never have to call this method yourself, use WindowManager to destroy your Window objects (which will call this for you).

Reimplemented from CEGUI::Window.

const ScrolledContainer* CEGUI::ScrollablePane::getContentPane ( void   )  const

Returns a pointer to the window holding the pane contents.

The purpose of this is so that attached windows may be inspected, client code may not modify the returned window in any way.

Returns:
Pointer to the ScrolledContainer that is acting as the container for the scrollable pane content. The returned window is const, client code should not modify the ScrolledContainer settings directly.
const Rect& CEGUI::ScrollablePane::getContentPaneArea ( void   )  const

Return the current content pane area for the ScrollablePane.

Returns:
Rect object that details the current pixel extents of the content pane attached to this ScrollablePane.
float CEGUI::ScrollablePane::getHorizontalOverlapSize ( void   )  const

Returns the horizontal scrollbar overlap size as a fraction of one complete view page.

Returns:
float value specifying the overlap size where 1.0f would be the width of the viewing area.
float CEGUI::ScrollablePane::getHorizontalScrollPosition ( void   )  const

Returns the horizontal scroll position as a fraction of the complete scrollable width.

Returns:
float value specifying the scroll position.
float CEGUI::ScrollablePane::getHorizontalStepSize ( void   )  const

Returns the horizontal scrollbar step size as a fraction of one complete view page.

Returns:
float value specifying the step size where 1.0f would be the width of the viewing area.
Scrollbar* CEGUI::ScrollablePane::getHorzScrollbar (  )  const

Return a pointer to the horizontal scrollbar component widget for this ScrollablePane.

Returns:
Pointer to a Scrollbar object.
Exceptions:
UnknownObjectException Thrown if the horizontal Scrollbar component does not exist.
ScrolledContainer* CEGUI::ScrollablePane::getScrolledContainer (  )  const [protected]

Return a pointer to the ScrolledContainer component widget for this ScrollablePane.

Returns:
Pointer to a ScrolledContainer object.
Exceptions:
UnknownObjectException Thrown if the scrolled container component does not exist.
float CEGUI::ScrollablePane::getVerticalOverlapSize ( void   )  const

Returns the vertical scrollbar overlap size as a fraction of one complete view page.

Returns:
float value specifying the overlap size where 1.0f would be the height of the viewing area.
float CEGUI::ScrollablePane::getVerticalScrollPosition ( void   )  const

Returns the vertical scroll position as a fraction of the complete scrollable height.

Returns:
float value specifying the scroll position.
float CEGUI::ScrollablePane::getVerticalStepSize ( void   )  const

Returns the vertical scrollbar step size as a fraction of one complete view page.

Returns:
float value specifying the step size where 1.0f would be the height of the viewing area.
Scrollbar* CEGUI::ScrollablePane::getVertScrollbar (  )  const

Return a pointer to the vertical scrollbar component widget for this ScrollablePane.

Returns:
Pointer to a Scrollbar object.
Exceptions:
UnknownObjectException Thrown if the vertical Scrollbar component does not exist.
Rect CEGUI::ScrollablePane::getViewableArea ( void   )  const

Return a Rect that described the pane's viewable area, relative to this Window, in pixels.

Returns:
Rect object describing the ScrollablePane's viewable area.
void CEGUI::ScrollablePane::initialiseComponents ( void   )  [virtual]

Initialises the Window based object ready for use.

Note:
This must be called for every window created. Normally this is handled automatically by the WindowManager.
Returns:
Nothing

Reimplemented from CEGUI::Window.

bool CEGUI::ScrollablePane::isContentPaneAutoSized ( void   )  const

Return whether the content pane is auto sized.

Returns:
  • true to indicate the content pane will automatically resize itself.
  • false to indicate the content pane will not automatically resize itself.
bool CEGUI::ScrollablePane::isHorzScrollbarAlwaysShown ( void   )  const

Return whether the horizontal scroll bar is always shown.

Returns:
  • true if the scroll bar will be shown even if it is not required.
  • false if the scroll bar will only be shown when it is required.
bool CEGUI::ScrollablePane::isHorzScrollbarNeeded ( void   )  const [protected]

Return whether the horizontal scrollbar is needed.

Returns:
  • true if the scrollbar is either needed or forced via setting.
  • false if the scrollbar should not be shown.
bool CEGUI::ScrollablePane::isVertScrollbarAlwaysShown ( void   )  const

Return whether the vertical scroll bar is always shown.

Returns:
  • true if the scroll bar will be shown even if it is not required.
  • false if the scroll bar will only be shown when it is required.
bool CEGUI::ScrollablePane::isVertScrollbarNeeded ( void   )  const [protected]

Return whether the vertical scrollbar is needed.

Returns:
  • true if the scrollbar is either needed or forced via setting.
  • false if the scrollbar should not be shown.
virtual void CEGUI::ScrollablePane::onAutoSizeSettingChanged ( WindowEventArgs e  )  [protected, virtual]

Notification method called whenever the setting that controls whether the content pane is automatically sized is changed.

Parameters:
e WindowEventArgs object.
Returns:
Nothing.
virtual void CEGUI::ScrollablePane::onContentPaneChanged ( WindowEventArgs e  )  [protected, virtual]

Event trigger method called when some pane content has changed size or location.

Parameters:
e WindowEventArgs object.
Returns:
Nothing.
virtual void CEGUI::ScrollablePane::onContentPaneScrolled ( WindowEventArgs e  )  [protected, virtual]

Notification method called whenever the content pane is scrolled via changes in the scrollbar positions.

Parameters:
e WindowEventArgs object.
Returns:
Nothing.
virtual void CEGUI::ScrollablePane::onHorzScrollbarModeChanged ( WindowEventArgs e  )  [protected, virtual]

Event trigger method called when the setting that controls whether the horizontal scrollbar is always shown or not, is changed.

Parameters:
e WindowEventArgs object.
Returns:
Nothing.
void CEGUI::ScrollablePane::onMouseWheel ( MouseEventArgs e  )  [protected, virtual]

Handler called when the mouse wheel (z-axis) position changes within this window's area.

Parameters:
e MouseEventArgs object. All fields are valid.

Reimplemented from CEGUI::Window.

void CEGUI::ScrollablePane::onSized ( WindowEventArgs e  )  [protected, virtual]

Handler called when the window's size changes.

Parameters:
e WindowEventArgs object whose 'window' pointer field is set to the window that triggered the event. For this event the trigger window is always 'this'.

Reimplemented from CEGUI::Window.

virtual void CEGUI::ScrollablePane::onVertScrollbarModeChanged ( WindowEventArgs e  )  [protected, virtual]

Event trigger method called when the setting that controls whether the vertical scrollbar is always shown or not, is changed.

Parameters:
e WindowEventArgs object.
Returns:
Nothing.
void CEGUI::ScrollablePane::setContentPaneArea ( const Rect area  ) 

Set the current content pane area for the ScrollablePane.

Note:
If the ScrollablePane is configured to auto-size the content pane this call will have no effect.
Parameters:
area Rect object that details the pixel extents to use for the content pane attached to this ScrollablePane.
Returns:
Nothing.
void CEGUI::ScrollablePane::setContentPaneAutoSized ( bool  setting  ) 

Set whether the content pane should be auto-sized.

Parameters:
setting 
  • true to indicate the content pane should automatically resize itself.
  • false to indicate the content pane should not automatically resize itself.
Returns:
Nothing.
void CEGUI::ScrollablePane::setHorizontalOverlapSize ( float  overlap  ) 

Sets the horizontal scrollbar overlap size as a fraction of one complete view page.

Parameters:
overlap float value specifying the overlap size, where 1.0f would be the width of the viewing area.
Returns:
Nothing.
void CEGUI::ScrollablePane::setHorizontalScrollPosition ( float  position  ) 

Sets the horizontal scroll position as a fraction of the complete scrollable width.

Parameters:
position float value specifying the new scroll position.
Returns:
Nothing.
void CEGUI::ScrollablePane::setHorizontalStepSize ( float  step  ) 

Sets the horizontal scrollbar step size as a fraction of one complete view page.

Parameters:
step float value specifying the step size, where 1.0f would be the width of the viewing area.
Returns:
Nothing.
void CEGUI::ScrollablePane::setShowHorzScrollbar ( bool  setting  ) 

Set whether the horizontal scroll bar should always be shown.

Parameters:
setting 
  • true if the horizontal scroll bar should be shown even when it is not required.
  • false if the horizontal scroll bar should only be shown when it is required.
Returns:
Nothing.
void CEGUI::ScrollablePane::setShowVertScrollbar ( bool  setting  ) 

Set whether the vertical scroll bar should always be shown.

Parameters:
setting 
  • true if the vertical scroll bar should be shown even when it is not required.
  • false if the vertical scroll bar should only be shown when it is required.
Returns:
Nothing.
void CEGUI::ScrollablePane::setVerticalOverlapSize ( float  overlap  ) 

Sets the vertical scrollbar overlap size as a fraction of one complete view page.

Parameters:
overlap float value specifying the overlap size, where 1.0f would be the height of the viewing area.
Returns:
Nothing.
void CEGUI::ScrollablePane::setVerticalScrollPosition ( float  position  ) 

Sets the vertical scroll position as a fraction of the complete scrollable height.

Parameters:
position float value specifying the new scroll position.
Returns:
Nothing.
void CEGUI::ScrollablePane::setVerticalStepSize ( float  step  ) 

Sets the vertical scrollbar step size as a fraction of one complete view page.

Parameters:
step float value specifying the step size, where 1.0f would be the height of the viewing area.
Returns:
Nothing.
virtual bool CEGUI::ScrollablePane::testClassName_impl ( const String class_name  )  const [inline, protected, virtual]

Return whether this window was inherited from the given class name at some point in the inheritance hierarchy.

Parameters:
class_name The class name that is to be checked.
Returns:
true if this window was inherited from class_name. false if not.

Reimplemented from CEGUI::Window.

References CEGUI::Window::testClassName_impl().

virtual bool CEGUI::ScrollablePane::validateWindowRenderer ( const String name  )  const [inline, protected, virtual]

Function used in checking if a WindowRenderer is valid for this window.

Returns:
Returns true if the given WindowRenderer class name is valid for this window. False if not.

Reimplemented from CEGUI::Window.


Member Data Documentation

Event fired when the auto size setting for the pane is changed. Handlers are passed a const WindowEventArgs reference with WindowEventArgs::window set to the ScrollablePane whose auto size setting has been changed.

Event fired when an area on the content pane has been updated. Handlers are passed a const WindowEventArgs reference with WindowEventArgs::window set to the ScrollablePane whose content pane has been updated.

Event fired when the pane gets scrolled. Handlers are passed a const WindowEventArgs reference with WindowEventArgs::window set to the ScrollablePane that has been scrolled.

Event fired when the horizontal scroll bar 'force' setting is changed. Handlers are passed a const WindowEventArgs reference with WindowEventArgs::window set to the ScrollablePane whose horizontal scroll bar mode has been changed.

Event fired when the vertical scroll bar 'force' setting is changed. Handlers are passed a const WindowEventArgs reference with WindowEventArgs::window set to the ScrollablePane whose vertical scroll bar mode has been changed.