Reference » Window classes » MScrollBar

Elgrint::MScrollBar class

Declared in WCScrollBar.h

Description

Lets the user shift the content of the window with the help of two MSlideBox selectors (side sliders).
Read more...

MScrollBar

Base class: MWindow

Properties:

Name Description
AutoHideSliders If true, the bar's sliders are visible only when needed.
Draggable If true, the scrolling can be done by dragging the cursor across the scroll bar.
HLineScrollSize Number of pixels to scroll horizontally on Left/Right keys or horizontal mouse wheel turn.
HPageScrollRatio Amount of horizontal scrolling on Ctrl+Left/Right keys.
VLineScrollSize Number of pixels to scroll vertically on Up/Down keys or vertical mouse wheel turn.
VPageScrollRatio Amount of vertical scrolling on PageUp/PageDown keys.

Initializers:

Name Description
MScrollBar(parent,rect) Standard-form constructor. Creates and opens a new scroll bar window.

Mutators:

Name Description
initScroll(size,vLine,hLine,vPageRatio,hPageRatio) Shows the scrolling sliders and the conjunction button, and initializes the scrolling parameters.
makeVisible(rect) Change the scroll's position so that its rect portion becomes visible in the window.
scrollBy(deltaVP,duration) Changes the position of the virtual scroll by the specified delta with optional animation.
scrollTo(newVP) Changes the position of the virtual scroll to the specified point.
setScrollRect(newRect) Changes the size and position of the virtual scroll.
setScrollSize(newSize) Changes the size of the virtual scroll.

Revealers:

Name Description
conjButton() Returns a reference to the sliders' conjunction button.
getMaxScrollVP() Returns the maximum possible Visible Point (scrolling limit).
getScrollSize() Returns the current size of the scroll (in pixels), as set by setScrollSize or setScrollRect.
getScrollVR() Returns the Visible Rectangle (the visible portion of the scroll in scroll coordinates).
hSlider() Returns a reference to the horizontal scrolling slider.
vSlider() Returns a reference to the vertical scrolling slider.

Converters:

Name Description
convScrollToWindow(p) Convert p from scroll coordinates to window coordinates.
convScrollToWindow(r) Convert r from scroll coordinates to window coordinates.
convWindowToScroll(p) Convert p from window coordinates to scroll coordinates.
convWindowToScroll(r) Convert r from window coordinates to scroll coordinates.

Handlers:

Name Description
OnChildListChanged

Refresh the window if a slider has been closed.

OnCursorMoved

"Scroll-by-dragging" support (if Draggable is true).

OnEnablingChanged

Set proper cursor, repaint.

OnFocusChanged

Block refocusing to parent (MWindow's default).

OnKeysEntered

Scroll with keys and mouse wheels.

OnNotice

Scroll on slider selection, repaint.

Details: The nnScrollSizeChanged notice causes a full repaint, and is propagated upward unless its ID is equal to Auto (which is the default value). In other words, to propagate this notice upward, setNoticeID must be called with noticeID not equal to any number except Auto.

OnPaint

Fill background for enabled/disabled states (disabled background is darker) and set proper transform.

OnRectChanging

Autosize

OnResized

Adjust scroll's position (no repaint)

Details

The scroll bar is a container that can contain a lot of content, much more than can fit the window. To accomplish this, this bar defines something called a "virtual scroll".

The virtual scroll is somewhat similar to a child window, except that it's not a real window. But it does have modifiable position and size parameters, like a real window. The size and position of this scroll is returned by getScrollSize and getScrollVR functions. "VR" stands for "Visible Rectangle", which is the visible portion of the scroll, i.e. the intersection of the virtual scroll's rectangle and the scroll bar window, in scroll's coordinates. The scroll coordinates are the coordinates from the top-left corner of the scroll. convScrollToWindow and convWindowToScroll convert the coordinates both ways, if necessary.

The scroll serves as a movable canvas for the entire content of the scroll bar. By moving the scroll, the user can display every part of it inside the window. The scroll can be moved by navigation keys, or using sliders (see below), or by dragging the window content with the cursor (works only if Draggable property is true), or programmatically via scrollTo, scrollBy, and makeVisible functions. Any change in the scroll's position generates a "Scrolled" Notice, and automatically shifts the entire content of the scroll bar (graphics and child windows), so that the position of the content remains the same relatively to the scroll's top-left corner (but not the same relatively to the bar's top-left corner). Moreover, the scroll bar's OnPaint handler sets a proper translational transform (see setDrawTransform), so that all the painting functions work consistently with the shifted content. Of course, for that MScrollBar::OnPaint has to be called before doing any drawing.

With the proper transform, when you implement the OnPaint handler for a class derived from MScrollBar, it's as if you paint on the virtual scroll, not on the scroll bar's window.

However, the scrolling only works within the rectangle of the scroll, regardless of the actual window content. In particular, if the scroll is smaller than the window, then scrolling is effectively disabled, even if there is plenty of content outside of the window boundaries. To include all the relevant content in the scrolled region, the scroll has to be resized properly. The resizing can only be done programmatically, via setScrollSize, initScroll, or setScrollRect (the latter changes size and position together). Any change in scroll size generates a "ScrollSizeChanged" Notice, and the scroll's position is automatically adjusted to prevent over-scrolling (see setScrollRect).

In addition to the content child windows, the scroll bar can optionally contain three special child windows, which allow the user to scroll the window: vertical slider (on the right side), horizontal slider (at the bottom), and conjunction button (in the bottom-right corner). These children are not created by default – the initScroll function needs to be called to create all three (and it sets the scroll's size as well). The sliders (sometimes also called scrollers) are windows of the MSlideBox type. The vertical/horizontal slider's selection determines the y/x coordinate of the scroll respectively. The sliders work only when necessary – if the scroll is smaller than the window, they become disabled or hidden, according to the AutoHideSliders property.

A common problem with sliders is a conjunction square – a small empty area at the bottom-right corner, where the sliders meet. This square remains free, and you can see part of the content in it, which can be confusing at times. MScrollBar solves this problem by filling this empty square with another child window – the "conjunction button". By default, the conjunction button does nothing (filling the square is its only purpose), but it can be used in the derived classes for various purposes, e.g. pressing this button open a context menu.

The sliders and the conjunction button are the only child windows of the scroll bar, which are not moved when the bar is scrolled – all other children (even floating ones) are shifted in sync with the virtual scroll. The vSlider, hSlider, and conjButton functions reveal these special children for custom configuration.

Example

Let us know

Please Contact us to report any errors on this page, or to suggest any improvements.

Miranor Home | About Miranor | About Elgrint | Create account | Login | Account settings | Contact Us | Privacy Policy | Site map

© Copyright 2014 by Miranor. All rights reserved. By using this site you agree to the Terms of Use.

Page last updated on August 10th, 2014.