ICircularSlider

The ICircularSlider class provides a control to represent a circular slider, which allows a user to set, display, or modify a value by rotating the slider arm. The circular slider emulates the actual controls of stereo and video components.

You can use a circular slider to allow users to control the balance, bass, volume, and treble. If they click on one of the tick marks, then the circular slider rotates to the new position. Or they can grab the slider arm with the mouse and rotate it. The circular slider also has plus and minus buttons for moving the slider arm.

Use the ISliderArmHandler class to process the events that are generated as the user is rotating the circular slider or when the user stops rotating the circular slider. This position change event is also generated when the user just clicks on one of the tick marks.

And finally, use the IFocusHandler class to process any focus changes. The following figure shows an ICircularSlider with the default, midpoint, and circular arm styles.
An ICircularSlider with Default, Midpoint, and Circular Arm Styles

The following figure shows an ICircularSlider with the default and proportional ticks styles.
An ICircularSlider with the Default and Proportional Ticks Styles

Portability Considerations

There are restrictions for specifying the color of controls based on the platform and which style of control you use.

OS/2 Considerations

You must install the Multimedia Presentation Manager to use ICircularSlider under the OS/2 2.1 operating system.


ICircularSlider - Member Functions and Data by Group

Constructors & Destructor

You can construct and destruct objects of this class.


[view class]
~ICircularSlider
public:
virtual ~ICircularSlider()

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
ICircularSlider


Overload 1
public:
ICircularSlider( unsigned long Identifier, IWindow* parent, IWindow* owner, const IRectangle& initial = IRectangle ( ), const Style& style = defaultStyle ( ) )

You can construct objects of this class from the following:

identifier
Window identifier of the circular slider you construct.

We recommend that you do one of the following:

  • Assign unique identifiers to all windows in the same frame window. "In the same window" means that the frame window is the first frame in its parent window chain.
  • Assign the client window a window identifier of IC_FRAME_CLIENT_ID.
parent
The parent window of the circular slider you construct. You must specify a parent window. This constructor throws an IInvalidParameter exception if you pass an IWindow* of 0. The parent window is primarily used for visible relationships.
owner
The owner window of the circular slider you construct.
initial
The initial position and size of the circular slider you construct. The initial position is the lower-left corner of the circular slider relative to the lower-left corner of the parent window. Optional.
style
Use the styles provided by ICircularSlider Style to specify the control's styles. Optional.

Supported Platforms

Windows OS/2 AIX
Yes Yes No

OS/2 Considerations

The window identifier is limited to the range 0 through 65535. The owner window is primarily used for routing notification events and unprocessed messages. The OS/2 operating system also uses the owner window chain to inherit colors.


Overload 2
public:
ICircularSlider( unsigned long Identifier, IWindow* parentAndOwner )

You can construct objects of this class from the following:

identifier
Window identifier of the circular slider you construct.

We recommend that you do one of the following:

  • Assign unique identifiers to all windows in the same frame window. "In the same window" means that the frame window is the first frame in its parent window chain.
  • Assign the client window a window identifier of IC_FRAME_CLIENT_ID.
parentAndOwner
The parent and owner window of the circular slider you construct. You must specify a parent window. This constructor throws an IInvalidParameter exception if you pass an IWindow* of 0. The parent window is primarily used for visible relationships.

Supported Platforms

Windows OS/2 AIX
Yes Yes No

OS/2 Considerations

The window identifier is limited to the range 0 through 65535. The owner window is primarily used for routing notification events and unprocessed messages. The OS/2 operating system also uses the owner window chain to inherit colors.


Overload 3
public:
ICircularSlider(const IWindowHandle& handle)

You can construct an object of this class by specifying a window handle.

handle
The window handle of the circular slider control.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Arm Operations

Use these functions to set and query attributes


[view class]
armRange
public:
IRange armRange() const

Returns the range of values over which the arm can be moved. This range contains the minimum and maximum value of the circular slider.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
radius
public:
unsigned long radius() const

Returns the radius of the dial in pixels. This value is indirectly set by sizing the control.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
rotationIncrement
public:
unsigned long rotationIncrement() const

Returns the increment that the arm is rotated. This is the number by which the current value is incremented or decremented when the user selects one of the circular slider increment or decrement buttons.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
setArmRange
public:
ICircularSlider& setArmRange(const IRange& range)

Sets the range of values over which the arm can be rotated. This range contains the minimum and maximum value of the circular slider. The values returned to the circular slider are based on the position of the arm inside of this range. If you set a range of 0 to 100 and the arm is in the middle, then calling value returns 50 as the current value. The circular slider supports a minimum value of -32K and a maximum value of 32K.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
setDecrementBitmaps

Sets the bitmaps used for decrement buttons of the circular slider. They are on the left-hand side of the slider.


Overload 1
public:
ICircularSlider& setDecrementBitmaps( const IResourceId& leftUp, const IResourceId& leftDown )

Use this function to load the bitmaps from the resource file.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Overload 2
public:
ICircularSlider& setDecrementBitmaps( const IBitmapHandle& leftUp, const IBitmapHandle& leftDown )

Use this function if you have bitmap handles.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
setIncrementBitmaps

Sets the bitmaps used for increment buttons of the circular slider. They are on the right-hand side of the slider.


Overload 1
public:
ICircularSlider& setIncrementBitmaps( const IBitmapHandle& rightUp, const IBitmapHandle& rightDown )

Use this function if you have bitmap handles.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Overload 2
public:
ICircularSlider& setIncrementBitmaps( const IResourceId& rightUp, const IResourceId& rightDown )

Use this function to load the bitmaps from the resource file.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
setRotationIncrement
public:
ICircularSlider& setRotationIncrement( unsigned long increment )

Sets the scroll increment. This is the number by which the current value of the circular slider is incremented or decremented when the user selects one of the circular slider increment or decrement buttons.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
setTickSpacing
public:
ICircularSlider& setTickSpacing(unsigned long tick)

Sets the tick mark increment of the control. This represents the value between the tick marks around the circular slider.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
setValue
public:
ICircularSlider& setValue(long value)

Sets the value of the circular slider. This value must be within the current range. The position of the arm is rotated to this value.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
tickSpacing
public:
unsigned long tickSpacing() const

Returns the increment used to draw the tick marks. This represents the value between the tick marks around the circular slider.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
value
public:
long value() const

Returns the current value of the circular slider. This value is based on where the arm is within the current range.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Minimum Size Calculation

These members are called when the circular slider is put into a canvas. The canvas uses the minimum size to calculate how small the circular slider can be when it is displayed.


[view class]
calcMinimumSize
protected:
virtual ISize calcMinimumSize() const

Returns an ISize that indicates the minimum size that the circular slider can be. This is used by the ICanvas hierarchy of classes. The minimum size also uses the current font and circular slider text in its calculations.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Notification Members

This INotificationId string is used for all notifications that ICircularSlider provides to its observers.


[view class]
trackId
public:
static INotificationId const trackId

Notification identifier provided to observers when the circular slider is manipulated with the mouse. ICircularSlider provides the current value in the INotificationEvent::eventData field of the INotificationEvent.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
valueId
public:
static INotificationId const valueId

Notification identifier provided to observers when the value of the circular slider control changes. ICircularSlider provides the new value in the INotificationEvent::eventData field of the INotificationEvent.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Observer Notification

Observer notification members implement the public INotifier protocol for the ICircularSlider class.


[view class]
enableNotification
public:
virtual ICircularSlider& enableNotification( bool enable = true )

Enables the circular slider control to send notifications to any observer objects.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Styles

Use these style members to set and query circular slider styles, the default style for this class, and to convert the style into a form that is recognizable to the underlying GUI. You can use these styles with the styles in the IWindow Styles class.


[view class]
convertToGUIStyle
public:
virtual unsigned long convertToGUIStyle( const IBitFlag& style, bool extendedOnly = false ) const

Converts a style object into a value appropriate for the presentation system. The default action is to return the base GUI styles for the platform. Extended styles, those defined by the application and the Open Class Library, are returned if you set extendedOnly to true.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
defaultStyle
public:
static Style defaultStyle()

Returns the current default style. This is the same as classDefaultStyle unless setDefaultStyle has been called.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
setDefaultStyle
public:
static void setDefaultStyle(const Style& style)

Sets the default style for all subsequent circular sliders.

This member function is not thread safe. In a multithreaded application, it should only be called when a conflict is not possible. A conflict can arise if you set the default style on one thread at the same time that it is being queried on another. In this situation, the query would take place while the style is in an unknown state.

When you create a window class and do not specifically specify window styles in the constructor, the Open Class Library queries the default style. Therefore, the only safe place to call this member function is when no other application threads that create windows are active.

Another way to avoid a conflict in a multithreaded application is to specifically specify window styles on window construction, rather than calling this member function.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
buttons
public:
static const Style buttons

Displays increment and decrement buttons.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
circularArm
public:
static const Style circularArm

Draws a small circle for the arm, rather than a line.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
classDefaultStyle
public:
static const Style classDefaultStyle

Specifies the original default style for this class, which is IWindow::visible.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
displayValue
public:
static const Style displayValue

Displays the value on the dial.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
full360
public:
static const Style full360

Permits the rotational range to extend 360 degrees. This forces the displayValue style to be off, which keeps the slider arm from corrupting the number value.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
jumpToPointer
public:
static const Style jumpToPointer

Causes the circular slider to change immediately (jump) to the value indicated by the position of the mouse. If this style is not present, then the circular slider rotates by the rotational increment to the value indicated by the position of the mouse

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
label
public:
static const Style label

Displays title text below the dial.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
midpoint
public:
static const Style midpoint

Makes the midpoint tick mark larger. This tick mark is not visible if the noTicks style is set.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
noTicks
public:
static const Style noTicks

Turns off the tick marks.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
proportionalTicks
public:
static const Style proportionalTicks

Allows the length of the tick marks to be calculated as a percentage of the radius; otherwise, they are set to a fixed length.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


ICircularSlider - Inherited Member Functions and Data

Inherited Public Functions

IControl
INotifier
ITextControl
IWindow

Inherited Public Data

IWindow
INotifier
ITextControl

Inherited Protected Functions

IWindow
INotifier
IControl
ITextControl

Inherited Protected Data