Crazy Eddie's GUI System  0.8.4
CEGUI::Scrollbar Class Reference

Base scroll bar class. More...

+ Inheritance diagram for CEGUI::Scrollbar:
+ Collaboration diagram for CEGUI::Scrollbar:

List of all members.

Public Member Functions

float getDocumentSize (void) const
 Return the size of the document or data.
void setDocumentSize (float document_size)
 Set the size of the document or data.
float getPageSize (void) const
 Return the page size for this scroll bar.
void setPageSize (float page_size)
 Set the page size for this scroll bar.
float getStepSize (void) const
 Return the step size for this scroll bar.
void setStepSize (float step_size)
 Set the step size for this scroll bar.
float getOverlapSize (void) const
 Return the overlap size for this scroll bar.
void setOverlapSize (float overlap_size)
 Set the overlap size for this scroll bar.
float getScrollPosition (void) const
 Return the current position of scroll bar within the document.
void setScrollPosition (float position)
 Set the current position of scroll bar within the document.
float getUnitIntervalScrollPosition () const
 return the current scroll position as a value in the interval [0, 1]
void setUnitIntervalScrollPosition (float position)
 set the current scroll position as a value in the interval [0, 1]
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.
void setConfig (const float *const document_size, const float *const page_size, const float *const step_size, const float *const overlap_size, const float *const position)
 Sets multiple scrollbar configuration parameters simultaneously.
void setEndLockEnabled (const bool enabled)
 Enable or disable the 'end lock' mode for the scrollbar.
bool isEndLockEnabled () const
 Returns whether the 'end lock'mode for the scrollbar is enabled.
void scrollForwardsByStep ()
 move scroll position forwards by the current step size
void scrollBackwardsByStep ()
 move scroll position backwards by the current step size
void scrollForwardsByPage ()
 move scroll position forwards by a page (uses appropriate overlap)
void scrollBackwardsByPage ()
 move scroll position backwards by a page (uses appropriate overlap)
 Scrollbar (const String &type, const String &name)
void initialiseComponents (void)
 Initialises the Window based object ready for use.

Static Public Attributes

static const String WidgetTypeName
 Window factory name.
static const String EventNamespace
 Namespace for global events.
static const String EventScrollPositionChanged
static const String EventThumbTrackStarted
static const String EventThumbTrackEnded
static const String EventScrollConfigChanged
static const String ThumbName
 Widget name for the thumb component.
static const String IncreaseButtonName
 Widget name for the increase button component.
static const String DecreaseButtonName
 Widget name 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 Vector2f &pt) const
 Given window location pt, return a value indicating what change should be made to the scroll bar.
bool setScrollPosition_impl (const float position)
bool isAtEnd () const
 return whether the current scroll position is at the end of the range.
float getMaxScrollPosition () const
 return the max allowable scroll position value
bool handleThumbMoved (const EventArgs &e)
 handler function for when thumb moves.
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 validateWindowRenderer (const WindowRenderer *renderer) const
 validate window renderer
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.
void banPropertiesForAutoWindow ()

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.
bool d_endLockPosition
 whether 'end lock' mode is enabled.

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 Vector2f pt) const [protected]

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

Parameters:
ptPoint 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.

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

Returns:
Pointer to a PushButton object.
Exceptions:
UnknownObjectExceptionThrown if the 'decrease' PushButton component does not exist.
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.

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

Returns:
Pointer to a PushButton object.
Exceptions:
UnknownObjectExceptionThrown if the increase PushButton component does not exist.
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.
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.
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.

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

Returns:
Pointer to a Thumb object.
Exceptions:
UnknownObjectExceptionThrown if the Thumb component does not exist.
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.
void CEGUI::Scrollbar::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.

Returns whether the 'end lock'mode for the scrollbar is enabled.

When enabled, and the current position of the scrollbar is at the end of it's travel, the end lock mode of the scrollbar will automatically update the scrollbar position when the document and/or page size change in order that the scroll position will remain at the end of it's travel. This can be used to implement auto-scrolling in certain other widget types.

Returns:
  • true to indicate that the end lock mode is enabled.
  • false to indicate that the end lock mode is disabled.
virtual void CEGUI::Scrollbar::onMouseButtonDown ( MouseEventArgs e) [protected, virtual]

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

Parameters:
eMouseEventArgs object. All fields are valid.

Reimplemented from CEGUI::Window.

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

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

Parameters:
eMouseEventArgs object. All fields are valid.

Reimplemented from CEGUI::Window.

void CEGUI::Scrollbar::setConfig ( const float *const  document_size,
const float *const  page_size,
const float *const  step_size,
const float *const  overlap_size,
const float *const  position 
)

Sets multiple scrollbar configuration parameters simultaneously.

This function is provided in order to be able to minimise the number of internal state updates that occur when modifying the scrollbar parameters.

Parameters:
document_sizePointer to a float value holding the new value to be used for the scroll bar document size. If this is 0 the document size is left unchanged.
page_sizePointer to a float value holding the new value to be used for the scroll bar page size. If this is 0 the page size is left unchanged.
step_sizePointer to a float value holding the new value to be used for the scroll bar step size. If this is 0 the step size is left unchanged.
overlap_sizePointer to a float value holding the new value to be used for the scroll bar overlap size. If this is 0 then overlap size is left unchanged.
positionPointer to a float value holding the new value to be used for the scroll bar current scroll position. If this is 0 then the current position is left unchanged.
Note:
Even if position is 0, the scrollbar position may still change depending on how the other changes affect the scrollbar.
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_sizefloat value specifying the document size.
void CEGUI::Scrollbar::setEndLockEnabled ( const bool  enabled)

Enable or disable the 'end lock' mode for the scrollbar.

When enabled and the current position of the scrollbar is at the end of it's travel, the end lock mode of the scrollbar will automatically update the position when the document and/or page size change in order that the scroll position will remain at the end of it's travel. This can be used to implement auto-scrolling in certain other widget types.

Parameters:
enabled
  • true to indicate that end lock mode should be enabled.
  • false to indicate that end lock mode should be disabled.
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_sizefloat value specifying the overlap size.
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_sizefloat value specifying the page size.
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:
positionfloat value specifying the position of the scroll bar within its document.
bool CEGUI::Scrollbar::setScrollPosition_impl ( const float  position) [protected]

implementation func that updates scroll position value, returns true if value was changed. NB: Fires no events and does no other updates.

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_sizefloat value specifying the step size.

Member Data Documentation

Event fired when the scroll bar configuration data is changed. Handlers are passed a const WindowEventArgs reference with WindowEventArgs::window set to the Scrollbar whose configuration has been changed.

Event fired when the scroll bar position value changes. Handlers are passed a const WindowEventArgs reference with WindowEventArgs::window set to the Scrollbar whose position value had changed.

Event fired when the user releases the scrollbar thumb. Handlers are passed a const WindowEventArgs reference with WindowEventArgs::window set to the Scrollbar whose thumb has been released.

Event fired when the user begins dragging the scrollbar thumb. Handlers are passed a const WindowEventArgs reference with WindowEventArgs::window set to the Scrollbar whose thumb is being dragged.

 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Friends