CEGUI::Scrollbar Class Reference

Base scroll bar class. More...

Inheritance diagram for CEGUI::Scrollbar:

Inheritance graph
[legend]
Collaboration diagram for CEGUI::Scrollbar:

Collaboration graph
[legend]

List of all members.

Public Member Functions

float getDocumentSize (void) const
 Return the size of the document or data.
float getPageSize (void) const
 Return the page size for this scroll bar.
float getStepSize (void) const
 Return the step size for this scroll bar.
float getOverlapSize (void) const
 Return the overlap size for this scroll bar.
float getScrollPosition (void) const
 Return the current position of scroll bar within the document.
PushButtongetIncreaseButton () const
 Return a pointer to the 'increase' PushButtoncomponent widget for this Scrollbar.
PushButtongetDecreaseButton () const
 Return a pointer to the 'decrease' PushButton component widget for this Scrollbar.
ThumbgetThumb () const
 Return a pointer to the Thumb component widget for this Scrollbar.
virtual void initialiseComponents (void)
 Initialises the Scrollbar object ready for use.
void setDocumentSize (float document_size)
 Set the size of the document or data.
void setPageSize (float page_size)
 Set the page size for this scroll bar.
void setStepSize (float step_size)
 Set the step size for this scroll bar.
void setOverlapSize (float overlap_size)
 Set the overlap size for this scroll bar.
void setScrollPosition (float position)
 Set the current position of scroll bar within the document.
 Scrollbar (const String &type, const String &name)
 Constructor for Scrollbar objects.
virtual ~Scrollbar (void)
 Destructor for Scrollbar objects.

Static Public Attributes

static const String EventNamespace
 Namespace for global events.
static const String WidgetTypeName
 Window factory name.
static const String EventScrollPositionChanged
 Name of the event fired when the scroll bar position value changes.
static const String EventThumbTrackStarted
 Name of the event fired when the user begins dragging the thumb.
static const String EventThumbTrackEnded
 Name of the event fired when the user releases the thumb.
static const String EventScrollConfigChanged
 Name of the event fired when the scroll bar configuration data changes.
static const String ThumbNameSuffix
 Widget name suffix for the thumb component.
static const String IncreaseButtonNameSuffix
 Widget name suffix for the increase button component.
static const String DecreaseButtonNameSuffix
 Widget name suffix for the decrease button component.

Protected Member Functions

void updateThumb (void)
 update the size and location of the thumb to properly represent the current state of the scroll bar
float getValueFromThumb (void) const
 return value that best represents current scroll bar position given the current location of the thumb.
float getAdjustDirectionFromPoint (const Point &pt) const
 Given window location pt, return a value indicating what change should be made to the scroll bar.
bool handleThumbMoved (const EventArgs &e)
 update the size and location of the thumb to properly represent the current state of the scroll bar
bool handleIncreaseClicked (const EventArgs &e)
 handler function for when the increase button is clicked.
bool handleDecreaseClicked (const EventArgs &e)
 handler function for when the decrease button is clicked.
bool handleThumbTrackStarted (const EventArgs &e)
 handler function for when thumb tracking begins
bool handleThumbTrackEnded (const EventArgs &e)
 handler function for when thumb tracking begins
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.
virtual bool validateWindowRenderer (const String &name) const
 Function used in checking if a WindowRenderer is valid for this window.
virtual void onScrollPositionChanged (WindowEventArgs &e)
 Handler triggered when the scroll position changes.
virtual void onThumbTrackStarted (WindowEventArgs &e)
 Handler triggered when the user begins to drag the scroll bar thumb.
virtual void onThumbTrackEnded (WindowEventArgs &e)
 Handler triggered when the scroll bar thumb is released.
virtual void onScrollConfigChanged (WindowEventArgs &e)
 Handler triggered when the scroll bar data configuration changes.
virtual void onMouseButtonDown (MouseEventArgs &e)
 Handler called when a mouse button has been depressed within this window's area.
virtual void onMouseWheel (MouseEventArgs &e)
 Handler called when the mouse wheel (z-axis) position changes within this window's area.

Protected Attributes

float d_documentSize
 The size of the document / data being scrolled thorugh.
float d_pageSize
 The size of a single 'page' of data.
float d_stepSize
 Step size used for increase / decrease button clicks.
float d_overlapSize
 Amount of overlap when jumping by a page.
float d_position
 Current scroll position.


Detailed Description

Base scroll bar class.

This base class for scroll bars does not have any idea of direction - a derived class would add whatever meaning is appropriate according to what that derived class represents to the user.


Member Function Documentation

float CEGUI::Scrollbar::getAdjustDirectionFromPoint ( const Point pt  )  const [protected]

Given window location pt, return a value indicating what change should be made to the scroll bar.

Parameters:
pt Point object describing a pixel position in window space.
Returns:
  • -1 to indicate scroll bar position should be moved to a lower value.
  • 0 to indicate scroll bar position should not be changed.
  • +1 to indicate scroll bar position should be moved to a higher value.

References CEGUI::Window::d_windowRenderer, and CEGUI::ScrollbarWindowRenderer::getAdjustDirectionFromPoint().

Referenced by onMouseButtonDown().

PushButton * CEGUI::Scrollbar::getDecreaseButton (  )  const

Return a pointer to the 'decrease' PushButton component widget for this Scrollbar.

Returns:
Pointer to a PushButton object.
Exceptions:
UnknownObjectException Thrown if the 'decrease' PushButton component does not exist.

References DecreaseButtonNameSuffix, and CEGUI::Window::getName().

Referenced by initialiseComponents().

float CEGUI::Scrollbar::getDocumentSize ( void   )  const [inline]

Return the size of the document or data.

The document size should be thought of as the total size of the data that is being scrolled through (the number of lines in a text file for example).

Note:
The returned value has no meaning within the Gui system, it is left up to the application to assign appropriate values for the application specific use of the scroll bar.
Returns:
float value specifying the currently set document size.

Referenced by CEGUI::Tree::ensureItemIsVisible(), CEGUI::Listbox::ensureItemIsVisible(), CEGUI::ScrollablePane::getHorizontalScrollPosition(), CEGUI::FalagardScrollbar::getValueFromThumb(), CEGUI::ScrollablePane::getVerticalScrollPosition(), CEGUI::Tree::onMouseWheel(), CEGUI::ScrollablePane::onMouseWheel(), CEGUI::MultiLineEditbox::onMouseWheel(), CEGUI::MultiColumnList::onMouseWheel(), CEGUI::Listbox::onMouseWheel(), CEGUI::ScrollablePane::setHorizontalScrollPosition(), CEGUI::ScrollablePane::setVerticalScrollPosition(), and CEGUI::FalagardScrollbar::updateThumb().

PushButton * CEGUI::Scrollbar::getIncreaseButton (  )  const

Return a pointer to the 'increase' PushButtoncomponent widget for this Scrollbar.

Returns:
Pointer to a PushButton object.
Exceptions:
UnknownObjectException Thrown if the increase PushButton component does not exist.

References CEGUI::Window::getName(), and IncreaseButtonNameSuffix.

Referenced by initialiseComponents().

float CEGUI::Scrollbar::getOverlapSize ( void   )  const [inline]

Return the overlap size for this scroll bar.

The overlap size is the amount of data from the end of a 'page' that will remain visible when the position is moved by a page. This is usually used so that the user keeps some context of where they were within the document's data when jumping a page at a time.

Note:
The returned value has no meaning within the Gui system, it is left up to the application to assign appropriate values for the application specific use of the scroll bar.
Returns:
float value specifying the currently set overlap size.

float CEGUI::Scrollbar::getPageSize ( void   )  const [inline]

Return the page size for this scroll bar.

The page size is typically the amount of data that can be displayed at one time. This value is also used when calculating the amount the position will change when you click either side of the scroll bar thumb - the amount the position changes will is (pageSize - overlapSize).

Note:
The returned value has no meaning within the Gui system, it is left up to the application to assign appropriate values for the application specific use of the scroll bar.
Returns:
float value specifying the currently set page size.

Referenced by CEGUI::Tree::ensureItemIsVisible(), CEGUI::Listbox::ensureItemIsVisible(), CEGUI::FalagardScrollbar::getValueFromThumb(), CEGUI::Tree::onMouseWheel(), CEGUI::ScrollablePane::onMouseWheel(), CEGUI::MultiLineEditbox::onMouseWheel(), CEGUI::MultiColumnList::onMouseWheel(), CEGUI::Listbox::onMouseWheel(), and CEGUI::FalagardScrollbar::updateThumb().

float CEGUI::Scrollbar::getScrollPosition ( void   )  const [inline]

Return the current position of scroll bar within the document.

The range of the scroll bar is from 0 to the size of the document minus the size of a page (0 <= position <= (documentSize - pageSize)).

Note:
The returned value has no meaning within the Gui system, it is left up to the application to assign appropriate values for the application specific use of the scroll bar.
Returns:
float value specifying the current position of the scroll bar within its document.

Referenced by CEGUI::FalagardMultiLineEditbox::cacheCaratImagery(), CEGUI::FalagardMultiLineEditbox::cacheTextLines(), CEGUI::Tree::configureScrollbars(), CEGUI::ScrolledItemListBase::configureScrollbars(), CEGUI::ScrollablePane::configureScrollbars(), CEGUI::MultiLineEditbox::configureScrollbars(), CEGUI::MultiColumnList::configureScrollbars(), CEGUI::Listbox::configureScrollbars(), CEGUI::MultiLineEditbox::ensureCaratIsVisible(), CEGUI::Tree::ensureItemIsVisible(), CEGUI::Listbox::ensureItemIsVisible(), CEGUI::ScrolledItemListBase::ensureItemIsVisibleHorz(), CEGUI::ScrolledItemListBase::ensureItemIsVisibleVert(), CEGUI::ScrollablePane::getHorizontalScrollPosition(), CEGUI::Tree::getItemAtPoint(), CEGUI::MultiColumnList::getItemAtPoint(), CEGUI::Listbox::getItemAtPoint(), CEGUI::MultiLineEditbox::getTextIndexFromPosition(), CEGUI::ScrollablePane::getVerticalScrollPosition(), CEGUI::ScrollablePane::handleContentAreaChange(), CEGUI::Tree::onMouseWheel(), CEGUI::ScrolledItemListBase::onMouseWheel(), CEGUI::ScrollablePane::onMouseWheel(), CEGUI::MultiLineEditbox::onMouseWheel(), CEGUI::MultiColumnList::onMouseWheel(), CEGUI::Listbox::onMouseWheel(), CEGUI::Tree::populateRenderCache(), CEGUI::FalagardMultiColumnList::render(), CEGUI::FalagardListbox::render(), and CEGUI::FalagardScrollbar::updateThumb().

float CEGUI::Scrollbar::getStepSize ( void   )  const [inline]

Return the step size for this scroll bar.

The step size is typically a single unit of data that can be displayed, this is the amount the position will change when you click either of the arrow buttons on the scroll bar. (this could be 1 for a single line of text, for example).

Note:
The returned value has no meaning within the Gui system, it is left up to the application to assign appropriate values for the application specific use of the scroll bar.
Returns:
float value specifying the currently set step size.

Referenced by CEGUI::Tree::onMouseWheel(), CEGUI::ScrollablePane::onMouseWheel(), CEGUI::MultiLineEditbox::onMouseWheel(), CEGUI::MultiColumnList::onMouseWheel(), and CEGUI::Listbox::onMouseWheel().

Thumb * CEGUI::Scrollbar::getThumb (  )  const

Return a pointer to the Thumb component widget for this Scrollbar.

Returns:
Pointer to a Thumb object.
Exceptions:
UnknownObjectException Thrown if the Thumb component does not exist.

References CEGUI::Window::getName(), and ThumbNameSuffix.

Referenced by CEGUI::FalagardScrollbar::getAdjustDirectionFromPoint(), CEGUI::FalagardScrollbar::getValueFromThumb(), initialiseComponents(), and CEGUI::FalagardScrollbar::updateThumb().

float CEGUI::Scrollbar::getValueFromThumb ( void   )  const [protected]

return value that best represents current scroll bar position given the current location of the thumb.

Returns:
float value that, given the thumb widget position, best represents the current position for the scroll bar.

References CEGUI::Window::d_windowRenderer, and CEGUI::ScrollbarWindowRenderer::getValueFromThumb().

Referenced by handleThumbMoved().

bool CEGUI::Scrollbar::handleThumbMoved ( const EventArgs e  )  [protected]

update the size and location of the thumb to properly represent the current state of the scroll bar

return value that best represents current scroll bar position given the current location of the thumb.

Returns:
float value that, given the thumb widget position, best represents the current position for the scroll bar.
Given window location pt, return a value indicating what change should be made to the scroll bar.
Parameters:
pt Point object describing a pixel position in window space.
Returns:
  • -1 to indicate scroll bar position should be moved to a lower value.
  • 0 to indicate scroll bar position should not be changed.
  • +1 to indicate scroll bar position should be moved to a higher value.
handler function for when thumb moves.

References getValueFromThumb(), and setScrollPosition().

Referenced by initialiseComponents().

void CEGUI::Scrollbar::initialiseComponents ( void   )  [virtual]

void CEGUI::Scrollbar::onMouseButtonDown ( MouseEventArgs e  )  [protected, virtual]

Handler called when a mouse button has been depressed within this window's area.

Parameters:
e MouseEventArgs object. All fields are valid.

Reimplemented from CEGUI::Window.

References CEGUI::MouseEventArgs::button, d_overlapSize, d_pageSize, d_position, getAdjustDirectionFromPoint(), CEGUI::EventArgs::handled, CEGUI::LeftButton, CEGUI::MouseEventArgs::position, and setScrollPosition().

void CEGUI::Scrollbar::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.

References d_position, d_stepSize, CEGUI::EventArgs::handled, setScrollPosition(), and CEGUI::MouseEventArgs::wheelChange.

void CEGUI::Scrollbar::setDocumentSize ( float  document_size  ) 

Set the size of the document or data.

The document size should be thought of as the total size of the data that is being scrolled through (the number of lines in a text file for example).

Note:
The value set has no meaning within the Gui system, it is left up to the application to assign appropriate values for the application specific use of the scroll bar.
Parameters:
document_size float value specifying the document size.
Returns:
Nothing.

References d_documentSize, onScrollConfigChanged(), and updateThumb().

Referenced by CEGUI::Tree::configureScrollbars(), CEGUI::ScrolledItemListBase::configureScrollbars(), CEGUI::ScrollablePane::configureScrollbars(), CEGUI::MultiLineEditbox::configureScrollbars(), CEGUI::MultiColumnList::configureScrollbars(), and CEGUI::Listbox::configureScrollbars().

void CEGUI::Scrollbar::setOverlapSize ( float  overlap_size  ) 

Set the overlap size for this scroll bar.

The overlap size is the amount of data from the end of a 'page' that will remain visible when the position is moved by a page. This is usually used so that the user keeps some context of where they were within the document's data when jumping a page at a time.

Note:
The value set has no meaning within the Gui system, it is left up to the application to assign appropriate values for the application specific use of the scroll bar.
Parameters:
overlap_size float value specifying the overlap size.
Returns:
Nothing.

References d_overlapSize, and onScrollConfigChanged().

Referenced by CEGUI::ScrollablePane::configureScrollbars().

void CEGUI::Scrollbar::setPageSize ( float  page_size  ) 

Set the page size for this scroll bar.

The page size is typically the amount of data that can be displayed at one time. This value is also used when calculating the amount the position will change when you click either side of the scroll bar thumb - the amount the position changes will is (pageSize - overlapSize).

Note:
The value set has no meaning within the Gui system, it is left up to the application to assign appropriate values for the application specific use of the scroll bar.
Parameters:
page_size float value specifying the page size.
Returns:
Nothing.

References d_pageSize, onScrollConfigChanged(), and updateThumb().

Referenced by CEGUI::Tree::configureScrollbars(), CEGUI::ScrolledItemListBase::configureScrollbars(), CEGUI::ScrollablePane::configureScrollbars(), CEGUI::MultiLineEditbox::configureScrollbars(), CEGUI::MultiColumnList::configureScrollbars(), and CEGUI::Listbox::configureScrollbars().

void CEGUI::Scrollbar::setScrollPosition ( float  position  ) 

Set the current position of scroll bar within the document.

The range of the scroll bar is from 0 to the size of the document minus the size of a page (0 <= position <= (documentSize - pageSize)), any attempt to set the position outside this range will be adjusted so that it falls within the legal range.

Note:
The returned value has no meaning within the Gui system, it is left up to the application to assign appropriate values for the application specific use of the scroll bar.
Parameters:
position float value specifying the position of the scroll bar within its document.
Returns:
Nothing.

References d_documentSize, d_pageSize, d_position, onScrollPositionChanged(), and updateThumb().

Referenced by CEGUI::Tree::configureScrollbars(), CEGUI::ScrolledItemListBase::configureScrollbars(), CEGUI::ScrollablePane::configureScrollbars(), CEGUI::MultiLineEditbox::configureScrollbars(), CEGUI::MultiColumnList::configureScrollbars(), CEGUI::Listbox::configureScrollbars(), CEGUI::MultiLineEditbox::ensureCaratIsVisible(), CEGUI::Tree::ensureItemIsVisible(), CEGUI::Listbox::ensureItemIsVisible(), CEGUI::ScrolledItemListBase::ensureItemIsVisibleHorz(), CEGUI::ScrolledItemListBase::ensureItemIsVisibleVert(), CEGUI::ScrollablePane::handleContentAreaChange(), handleDecreaseClicked(), handleIncreaseClicked(), handleThumbMoved(), onMouseButtonDown(), CEGUI::Tree::onMouseWheel(), CEGUI::ScrolledItemListBase::onMouseWheel(), onMouseWheel(), CEGUI::ScrollablePane::onMouseWheel(), CEGUI::MultiLineEditbox::onMouseWheel(), CEGUI::MultiColumnList::onMouseWheel(), CEGUI::Listbox::onMouseWheel(), CEGUI::ScrollablePane::setHorizontalScrollPosition(), and CEGUI::ScrollablePane::setVerticalScrollPosition().

void CEGUI::Scrollbar::setStepSize ( float  step_size  ) 

Set the step size for this scroll bar.

The step size is typically a single unit of data that can be displayed, this is the amount the position will change when you click either of the arrow buttons on the scroll bar. (this could be 1 for a single line of text, for example).

Note:
The value set has no meaning within the Gui system, it is left up to the application to assign appropriate values for the application specific use of the scroll bar.
Parameters:
step_size float value specifying the step size.
Returns:
Nothing.

References d_stepSize, and onScrollConfigChanged().

Referenced by CEGUI::Tree::configureScrollbars(), CEGUI::ScrolledItemListBase::configureScrollbars(), CEGUI::ScrollablePane::configureScrollbars(), CEGUI::MultiLineEditbox::configureScrollbars(), CEGUI::MultiColumnList::configureScrollbars(), and CEGUI::Listbox::configureScrollbars().

virtual bool CEGUI::Scrollbar::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::Scrollbar::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.


Generated on Thu Nov 27 20:34:38 2008 for Crazy Eddies GUI System by  doxygen 1.5.7.1