The Range Slider: JRangeSlider, release 2.

Derived from: public BView

Declared in: <JRangeSlider.h>

Important note! This is not a BeBook File. I borrowed the titles because they are well known to Be programmers and gives good stamina for a class description. May someone at Be flame me for borrowing the look and feel of the BeBook, but I think this makes it easier for programmers to quickly find the information he/she wants.

---

Overview

JRangeSlider is an object that displays an knob in a container, similar to s BSrollBar. The difference is that this gadget provides buttons within the knob to change the size as well as the position.

The Function

The slider functions in a quite intuitive fashion, but with some small additions for more functionality. The behaviour when using the primary mouse button is what you expect from the BScrollBar, with the addition that when dragging the small extra buttons on the top and bottom of the knob, it resizes. The secondary mouse button adds some more functionlity. When pressing SMB on the arrows up and down, you fine adjust the upper or lower position of the knob, whether you press the pair above or below the slider. Using SMB on the container makes the upper or lower position jump to the mouse depending on if you press above or below the knob. You can also move the whole knob with pressing the resize buttons with SMB. That is handy if the knob is so small that the drag area has disappeared.

The Update Mechanism

The slider calls one of three hook functions when the user moves the knob: UpperPositionChanged(), LowerPositionChanged() or BothUpperAndLowerPositionsChanged(). The names reveal the structure of this knob. In constrast to the BScrollBar, the it is not defined by position and size but rather an Upper Position and a Lower Position. These are the values of the positions of the knob within the container. The maximum and minimum values are set in the constructor.

NOTE! This object does not support any archiving or targeting! (yet)

The Appearance

The standard look of this slider is 'Be-like' although it's not a copy of the looks of the Be GUI. If somebody would like to change the appearance of the slider, there's three hook functions that render the slider: DrawInRect(), DrawOutRect() and DrawArrowIn(). They provide a way to customly design your own look.

There's also a few colors defined used to draw the boxes, creating an illusion of 3D. These are public and can be changed to whatever colors you want. Email me if you want the detalis on what color's used where.

Hook Functions

Constructor and Destructor

JRangeSlider()

      JRangeSlider(BRect frame,
      	const char *name, float MinValue,
         float MaxValue,float LowerPosition,
         float UpperPosition, orientation posture, 
         float ArrowStep = 5)

MinValue and MaxValue is determines what range is to be associated to the container. If MaxValue < MinValue the're swapped. If the're equal, the're set to 0 and 256 respectively.

The upper and lower position is given by UpperPosition and LowerPosition. These values should be in the range given by MinValue and MaxValue. If they are not, they will be limited to that region. If the constructor cannot work out the appearance from the parameters (it does some effort to squeeze it in) it will fail by throwing an exception.

The ArrowStep argument, gives the increment with which the slider moves when using the arrows.

The other arguments, frame and name, are the same as for other BViews:

The frame rectangle locates the slider within its parent view. For consistency in the user interface, a horizontal scroll bar should be B_H_SCROLL_BAR_HEIGHT coordinate units high, and a vertical scroll bar should be B_V_SCROLL_BAR_WIDTH units wide.

The JRangeSlider name identifies it and permits it to be located by the FindView() function. It can be NULL.

Member Functions

bool	SetUpperPosition( float NewUpperPosition )	
bool	SetLowerPosition( float NewLowerPosition )	

These functions sets the upper and lower position of the knob. They are bounded into the interval [MinValue,MaxValue]. These functions does not call UpperPositionChanged() and LowerPositioChanged() respectively. It does call the Draw() function to redraw the applicable parts of the slider.

void	SetTimeBetweenUpdates(	int32 argDelayTime )

This function controls the time that is elapsed (at minimum) between two calls to the hook functions UpperPositionChanged(), LowerPositionChanged() and BothUpperAndLowerPositionsChanged() in microseconds. Default is 30 000 us. Be recommennds no less value that 20 000 us, IIRC.

void	SetArrowStep( float NewArrowStep )		

This sets the variable ArrowStep. That variables gives the size of the step taken when one presses an arrow button.

virtual void		DrawInRect(	BRect argRect, bool	argActivated);
virtual void		DrawOutRect(BRect argRect, bool argActivated);
virtual void		DrawArrowIn(BRect argRect, int32 argDirection, bool argActivated); 

The argRect parameter is the rectangle which contain the area to be drawn.

The argActivated parameter is to indicate to draw the activated version of the area. If it is true, the user has just activated the area and the slider wants to redraw it in the activated fashion. This is done calling these functions with this parameter true.

Implementation detail: When an arrow-button is pressed, the rectangle is drawn first by a call to DrawOutRect, THEN the arrow is drawn by the DrawArrowIn() function.

virtual void		UpperPositionChanged( float argNewUpperPosition );
virtual	void		LowerPositionChanged( float argNewLowerPosition );
virtual void		BothUpperAndLowerPositionsChanged( float argNewUpperPosition, float argNewLowerPosition  );

Legal Stuff

Copyright © 1997 Thorbjörn Jemander. All rights reserved.

Last change made the 24 October, 1997.

Be is a registered trademark; BeOS, BeBox, BeWare, GeekPort, the Be logo, and the BeOS logo are trademarks of Be, Inc.