Abstract Class Scroller with Demo and Documentation

There are 2 demos in this file. The first is relatively simple. The second is more complicated and the code might be more difficult to understand. The documentation follows the second example.

First demo

    

Scroller is an very general abstract class that provides scroll bar support. Three extensions are provided: ScrollBar, SimpleScrollBar and Slider for the other scrollable devices.

This demo illustrates all three along with some of the options that are provided. The bars may have either vertical or horizontal or orientation. There are options for labels and hashmarks. The table below shows the type of bar and which options were are used.

Unfortunately dragging the scroll button on scroll bars probably will not work on touch screens. While the operating system typically passes taps on to the application as clicks, it captures the swiping actions and does not let applications see them without using special techniques which unfortunately are often system dependent. Consequently, there is an option to have scrollbars to respond to clicks (and hence taps). The horizontal green bar uses this option.

The sketch code is in the file ScrollerDemo.pde. The Scroller code is in the file Dragger.pde.

ScrollBarClass Options
Horizontal Red ScrollBar The constructor specifies red for the buttons. It uses showLabels(64) and showHashmarks(32) in the setup method. It also uses displayOneLabel(255) in the draw method in order to provide the "255" label.
Horizontal Green SimpleScrollBar It uses the showValue() in the setup method. setProcessClicks(true) makes the bar respond to clicks.
Horizontal Blue Slider The constructor specifies the max value 0 and min value 255 to reverse the ScrollBar. It uses the showLabels(64) in the setup method. It also uses displayOneLabel(255) in the draw method in order to provide the "255" label.
Vertical Red ScrollBar The constructor specifies light red for the buttons.
Vertical Green SimpleScrollBar It uses the showLabels(64) and showHashmarks(32) in the setup method. That method also specifies that the button will have shades of green (setButtonFillColors(#00FF00, #00CC00)). It also uses displayOneLabel(255) in the draw method in order to provide the "255" label.
Vertical Blue Slider The constructor specifies the max value 0 and min value 255 to reverse the ScrollBar. The setup method uses showHashmarks(32), showLabels(255) which draws labels at 0 and 255, and showValue(). Also, when this bar is dragged the code in the mousePressed() method sets the dragger's outside limit to 20 which means drags will terminate if the mouse is moved more than 20 pixels outside a ScrollBar. This setting applies to all the ScrollBars untill it is changed. (The default is 100 pixels.)

Second demo

    

There are 13 scrollers in this demo. You will have to scroll the sketch to see some of them.

In the upper left corner there are three ScrollBars that control the color of the rectangle surrounding them. Below them are two more that convert Fahrenheit and Celsius temperatures. To make things interesting they move in upper directions. Moving either scroll button moves the other one.

On the top right, there are two ScrollBars, a Slider, and a SimpleScrollBar. Together they illustrate the flexibility of the Scroller. The upper ScrollBar sets the minimum value of the SimpleScrollBar, the lower one sets the maximum. The Slider adjusts the length of the SimpleScrollBar's scroll button. The SimpleScrollBar is reversed.

Below them is another SimpleScrollBar and Slider. They don't have any really purpose other than to illustrate possibilities.

The final two ScrollBars are part of ScrollSketch and scroll the whole sketch.

The sketch code is in the file ScrollerDemo2.pde. The Scroller code is in the file Dragger.pde.

ScrollBarClass Options
Red, green, and blue horizontal ScrollBar Alt three use the simpler 6 parameter constructor and all three use setButtonFillColors to set the scroll button color. If you adjust the ScrollBars to lighten the rectangle, you will see that the blue bar also uses showLabels(64) and ShowHashmarks(32). It also uses displayOneLabel(255) in the draw method to add the 255 label.
Vertical Fahrenheit Aqua ScrollBar Use the 10 parameter constructor to set the button colors to aqua. It uses the one parameter showHashmarks and showLabels so the marks and labels start at minVal = 0. It also uses showValue().
Vertical Celsius ScrollBar Uses the simpler 6 parameter constructor with the max set -17.78 and min set 100, reversing its direction. It uses the showValue() and showLabels(50,0) The 0 says to start the labels at 0 instead of the odd ball -17.78 value.
Horizontal Minimum ScrollBar It uses the 10 parameter constructor with the button color set #FF00FF. It uses the showLabels(50) and showValue() options
Horizontal maximum ScrollBar Use the simpler 6 parameter constructor. It uses the showHashmarks(25) and showLabels(50) options
Vertical scroll button size. Slider It uses the showHashmarks(25) and showLabels(50) options.
Vertical resulting value SimpleScrollBar Uses a formula to set the size of the scroll button to percentage specified "ScrollButton Size" Slider using the setSizes(...) method. It uses the showLabels(50) option and the starting value is set at 0 using setValue(0).
Horizontal SimpleScrollBar (No options.)
Horizontal Slider It uses many options including setBarColors(#000000, #808080),
showHashmarks(10),
showLabels(50),
showValue(),
setButtonBorderColor(#008000),
setButtonFillColors(#00FF00, #00CC00).
Horizontal and Vertical ScrollBars on bottom and right side ScrollSketch (No options but setUpScrollSketch(false) (false means "no menu") has to be used in the setup() method.)

It only takes one Dragger object to handle all the ScrollBars because only one dragging operation can occur at a time..

Documentation

abstract class Scroller
extends Draggable
which extends ClickablePanel
which extends Clickable

The abstract Scroller class can be extended to provide various types of scrollbars. It has with many options. The bar includes a draggable scroll button and optional up/right and down/left buttons. It provides labeling and other options. See the customizing options for a description of those options. There one rather general purpose constructor.

Note: The optional up/right and down/left buttons in a ScrollBar will work automatically when the scrollbar is set up properly using the ReadyForDrag(...) and moved() methods in the normal fashion. It is not necessary to use the getClickedItem() method to get the ScrollBar to respond correctly.

Additional fields

static final int BUTTON_SIZE = 20 - Height/width of up & down buttons.
int scrollBtnPos - The y value of upper end of the scroll button or x value of left end of the scroll button depending on the orientation of the scroll button.
int scrollBtnSize - The height or width of the scroll button.
int upDownBtnSize - The height or width of the up/down buttons.
int scrollLength - The distance the scroll button can moved.
int scrollMin - The upper most or left most position of scroll button.
float val - Value corresponding to the current scroll button location.
float minVal, maxVal, valRange - Value limits and range.
float smallerVal - Minimum of mimVal and maxVal. (maxVal < minVal is OK.)
float biggerVal - Maximum of mimVal and maxVal (maxVal < minVal is OK.)
color scrollBtnFillColor, scrollBtnBorderColor - Fill and border colors of button. Use 0x00FFFFFF for transparent.
Button scrollBtn - The ScrollBar's scroll button.
Button upBtn, downBtn - The down/left and up/right buttons.
Clickable canBeDragged - The button if it is currently draggable.
boolean vertical - Orientation of the bar.
float hashStart, hashSpacing - First value and increment for hash markings.
boolean hashShow - Show hashmarks if true.
float labelsStart, labelsSpacing - First value and increment for labels.
boolean labelsShow - Show labels if true.
boolean valueShow - Show current value if true.
int upDownDivisor - movement divisor for up/down buttons.
int circleAdjust - Adjustment need in location for circular scroll btn. Required because circles use center locations instead of edge locations.
**Scroller(boolean verticalOrientation, int leftX, int topY, int theWidth, int theHeight,
                    int btnSize, String theLabel,
                    color stdColor, color btnFillColor,
                    float minValue, float maxValue)
- Constructor for Scroller. The scroll button must be added by the class that extends the Scroller allowing a variety of implementations. Likewise The up/down or left/right buttons can optionally added by the extending classes. In addition, one can reset the following as appropriate:
  • call setScrollValues(size of button, true/false(has up/down buttons)
  • create desired buttons.
  • call setValue(desired initial value)
  • scrollBtnSize = setSizes(desired scroll button height or width)
In addition set the following as appropriate:
        scrollMin: The minimal value of scrollBtnPos.
        scrollLength: The distance the scroll button can travel. For vertical bars, it can be calculated as height - combined height of the buttons.
        calculate scrollBtnPos = calcLoc(desired initial value of scrollBar).
Parameters:
boolean verticalOrientation: true for vertical, false for horizontal
int leftX, int topY: Location of ScrollBar panel.
int theWidth, int theHeight: Size of ScrollBar panel.
String theLabel: Label for ScrollBar (not shown).
color stdColor: Color of ScrollBar panel.
color btnFillColor: Fill color of button.
float minValue: Value corresponding to bottom or left side of the panel.
float maxValue: Value corresponding to top or right side of the panel.
          minValueX > maxValueX is OK
Methods for setting customizing options
The first is called from draw() (or a submethod). The remaining ones are called from setup()
** void displayOneLabel(float value, boolean rightSide)
- Write a label with the given value beside the scroll bar. If rightSide is true, then it is on the right side or bottom, if not it is on the left side or top. The value is rounded to two decimal places (but may appear 0 or 1 decimal places). Called from draw() or submethod.
** void setButtonFillColors(color fillColor, color overFillColor)
- Set the colors (standard and "over") of the button.
** void setButtonBorderColor(color borderColor)
- Sets the scrollBtn's border color
** void setBarColors(color stdColor, color overStdColor)
- Set the colors of the scroll bar.
** void setValue(float value)
- Sets value corresponding to the location of the scrollButton and the location that corresponds to it. The value is restricted to legal values as specified by the minVal and maxVal.
** void setMinValue(float minValue)
- Set the minimum value of the Scroller and adjusts the scroll button. This value is used at the bottom or left end of the scroll bar. (Recall minValue > maxValue is legal.) After setting a new min and/or max value, use calcMinMaxRelatedValues() to set some internal values.
** void setMaxValue(float maxValue)
- Set the maximum value of the Scroller and adjusts the scroll button. This value is used at the top or right end of the scroll bar. (Recall minValue > maxValue is legal.) After setting a new min and/or max value, use calcMinMaxRelatedValues() to set some internal values.
** void showLabels(float spacing, float start)
- Adds labels showing the value to the right or bottom of the meter. First label is at start. Note: This version is designed for situations where the minimal value is not a nice number. Should be called in setup().
** void showLabels(float spacing)
- Adds labels showing the value to the right or bottom of the meter. First label is at minValue. Note: This version is designed for situations where the minimal value is a nice number. Should be called in setup().
** void showHashmarks(float spacing, float start)
- Adds hashmarks to the right or bottom of the meter. First hash is at start. Note: This version is designed for situations where the minimal value is not a nice number. Should be called in setup().
** void showHashmarks(float spacing)
- Adds hashmarks to the right or bottom of the meter. First hash is at minValue. Note: This version is designed for situations where the minimal value is a nice number. Should be called in setup().
** void showValue()
- Adds the value of the meter at the appropriate location. If showLabels is also used, this label will appear on the left or top of the bar. This prevents the value label from overlapping the other labels. If the showLabels is not used, the labels will appear on the right or bottom of the bar.
Other methods
** void calcMinMaxRelatedValues()
- Calculates valRange, smallerVal, and biggerVal. That is, the values related to the max and min values.
** void setScrollValues()
- Set scroll values. They include the button size and whether the bar has up/right and down/left buttons. Values are determined by the scrollbutton and the upBtn (if it exists).
** void setSizes(int theSize)
- Set size (height/width) of scrollBtn and calculate scrollMin and ScrollLength. Must be called by extending classes after creating any and all buttons in order to complete the construction. Can be called by the user sketch to reset the scroll button size. "theSize" is the height or width (depending on the orientation) of the scroll button and can be as small as -1 in which case the button is just a line and cannot be dragged.
** void adjustForCircleScrollBtn(boolean b)
- Sets a value(half of w) to add to location of a circular scroll button to correct for its shape. This is needed because the x or y represents the center of the circle instead of the left or top of the figure as it does for regular buttons.
** void setVisible(boolean b)
- Sets the Scroller as being visible true or false. The scroll bar is non-functional when visible is false.
** void setEnabled(boolean b)
- Sets the Scroller as being enabled true or false.
** void setScrollable(boolean canScroll)
- Sets the Scroller and all its parts to scroll or not scroll when the whole sketch scrolls.
* void display()
- Displays the Scroller panel and its button(s).
* boolean isOver()
- Determines if the cursor is over any part of the Scroller and sets the over field to true and returns true if so. Always returns false if stillSearching_ is false.
* boolean checkForClick()
- Checks to see if any part of the Scroller has been clicked. If so, it updates the current "value" as needed and sets "clicked" to true and then returns true. Processes the up and down buttons if they are not null. setScrollBtnPos checks to make sure the position is legal. It is called by mouseReleased().
* boolean hasBeenClicked()
- Determines if the Scroller has been clicked. If so, return true after "clicked" is set to false. It is called by draw() or a submethod.
** boolean readyForDrag(Dragger theTracker)
- Determines if the Scroller button has experienced a mousePressed event and could be dragged. Ignores clicks on the bar outside of the scroll button. Sets the position of the scroll button and then sets the minimumForDrag to 0 and the drag boundaries to those of the Scroller. It is called by mousePressed().
** boolean moved(Dragger theTracker)
- If the scroll button is the current draggable item, it moves the button and returns true. It is called by mouseDragged().
# int calcLoc()
- Calculates and returns the location that corresponds to the position of scroll button. The value is restricted to legal values as specified by the minVal and maxVal. Does not change values or locations.
# void calcValue()
- Calculates and stores val (the value) using location of scrollBtn.
** float getValue()
- Returns the current value of the Scroller.
** float getMaxValue()
- Returns the max (top or right) value of the Scroller.
** float getMinValue()
- Returns the min (bottom or left) value of the Scroller.
# int getButtonPos()
- Returns the location (top or left end) of button
# void displayHashMarks()
- Called by display() when showHashmarks is true. It displays hashmarks on the right side or bottom of the Scroller.
# void displayLabels()
- Called by display() when showLabels is true. It displays labels on the right side or bottom of the Scroller.
# void displayValue()
- Called by display() when showValue is true. It displays the current value of the ScrollBar. The value is written on the left or top of the bar if showLabels has been selected. Otherwise, it is on the right or bottom of the bar.
# void displayBtnLine()
- Draws on marker line in middle of the scroll button to help it show the value more clearly when called by display().
# void setScrollBtnPos(int loc)
- Makes sure that loc is in the right range, assigns the value to scroll button as appropriate, and recalculates the value.

Method use codes:

** This constructor or method is designed to be called in the user sketch.

* This method is normally not called in the user's sketch unless the Clickable item was not been included in a ClickableGroup. ClickableGroup automatically uses the method as needed. Exception: This method may be needed if the user is extending Clickable with a new class.

# This constructor or method is rarely used in the user program. In Java, it would probably marked "private". Clickable, ScrollBar, and some other abstract constructors would never be called directly by the user sketch because they do nothing useful unless the user is extending a class.


Inherited from DraggablePanel

Fields
upDownDivisor

Constructors
DraggablePanel, DraggablePanel

Methods
checkForClick, moved, readyForDrag


Inherited from ClickablePanel

Fields
clickX, clickY, invisible, wholeSkectch

Constructors
ClickablePanel, ClickablePanel, ClickablePanel

Methods
adjustPanel, checkForClick, display, drawOnPanel, getClickX, getClickY, getPanelX, getPanelY, isOver, setClickX, setClickY, setColor


Inherited from Clickable

Fields
NOTHING_CLICKED, COMBO_BUTTON, DISABLED_COLOR, borderColor, c, clicked, clickedItemNum, colorState, enabled, h, label, over, overC, scrollable, selected, selectedItemNum, visible, w, x, y

Constructors
Clickable

Methods
checkForClick, display, doNotSelect, getClickedItemNum, getColorState, getH, getItem, getLabel, getSelected, getSelectedItem, getSelectedItemLabel, getSelectedItemNum, getW, getX, getY, hasBeenClicked, hideSomething, isOver, setBorderColor, setColorState, setH, setLabel, setScrollable, setSelected, setSelectedItemNum, setEnabled, setVisible, setW, setX, setY, sX, sY

Return to the top of the page

Revised: 04/11/2014