Developer

API Reference

AEECLSID_SliderWidget

Brew Release
Brew MP 1.0.2
See Also
- IWidget Interface
- Model Events
- ISHELL_CreateInstance()
Description
The Slider widget object is a user-interface element that provides a means to control a setting over a predetermined range. Sliders are best used for settings that have continuous variable values, such as display brightness or contrast.
Sliders can be positioned horizontally or vertically. Horizontal layout is recommended.
Sliders do not include text labels. Use a static text widget to create labels for a slider.
Slider widgets use a value model to supply the value for the slider setting.
The slider bar has border support and all border properties can be applied to the slider bar.
It is possible to configure the handle scroll delay, and scroll rate, when the user touches the slider bar. See the slider touch controller for more information.
Slider appearance and color values:
                               
    figure (1)                              ------ Slider "handle"
                                           |
                                           V
                               +-+-+-+-+-+-+               
                               |.|.|.|.|.|.|               
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+   >--|
   |*|*|*|*|*|*|*|*|*|*|*|*|*|*|.|*|*|*|*|.|*|*|*|*|*|*|*|*|*|*|*|*|*|*|      |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+      |
   |*|b|b|b|b|b|b|b|b|b|b|b|b|b|.|*|*|*|*|.|b|b|b|b|b|b|b|b|b|b|b|b|b|*|      |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+      |
   |*|*|*|*|*|*|*|*|*|*|*|*|*|*|.|*|*|*|*|.|*|*|*|*|*|*|*|*|*|*|*|*|*|*|      |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+   >--|
                               |.|.|.|.|.|.|                                  |
                               +-+-+-+-+-+-+                                  Slider "Bar"

The slider widget maintains the following default characteristics, any of which may be overridden by changing the appropriate widget property.
            Background color: (0xED, 0xEC, 0xFE)
                Border color: (0x6E, 0x6E, 0xA0)
         Handle border color: RGB_WHITE
            Maximum position: 10
                 Orientation: horizontal
  Horz Handle Drag Threshold: 40, 40, 60, 60
  Vert Handle Drag Threshold: 60, 60, 40, 40



To create a slider widget, an application would do the following:
      1. Call ISHELL_CreateInstance() with a class ID of AEECLSID_SliderWidget
         to create an instance of the slider widget.
      2. Set properties to control the widget's appearance or function.
      3. Set the extent of the widget.
      4. Place the widget in a container.

Supported Events: The slider widget handles the following set of events:
Event                   Description   
-----                   -----------------------------------------------------
EVT_WDG_SETFOCUS        The slider widget responds to this event by displaying
                        itself in the new focus state and by returning TRUE to
                        indicate that it accepts focus.
                     
EVT_KEY                 The slider widget handles this event when the 'wParam'
                        parameter is one of {AVK_LEFT, AVK_RIGHT} for horizontal
                        orientation, and when one of {AVK_UP, AVK_DOWN} for 
                        vertical orientation. These combinations increment or
                        decrement the position of the slider and its underlying
                        data model value, and return TRUE to indicate that the
                        event was handled.

EVT_WDG_SCROLL          The slider widget responds to this event by displaying
                        its handle in a new position based on the offset value
                        received from the Scroll touch controller and by setting 
                        the value model to the new position value.

EVT_WDG_TRAVERSE:       Slider widget responds to this event by executing a 
                        function on each widget in its container tree, including 
                        itself. The 'dwParam' parameter is a pointer to a TraverseDesc
                        data structure containing a function callback, a callback 
                        context pointer, and the number of levels to descend into the 
                        container hierarchy.  (See the TraverseDesc data structure.)
                        The order of traversal is: the slider widget itself first,
                        and the handle next.

EVT_WDG_SETPROPERTY     This event allows various properties to be set on the
                        slider widget. The properties handled are described below.
                        
EVT_WDG_GETPROPERTY     This event allows various properties to be retrieved from
                        the slider widget. The properties handled are described 
                        below.

Properties:
Property                Description
--------                ------------------------------------------------------------
PROP_SLIDER_MAXPOS      This property gets/sets the value of the maximum position 
                        of the slider handle. The minimum position value is always zero
                        and visually occurs when the slider handle is in the left-most
                        position (for horizontal orientation) or bottom-most position 
                        (for vertical orientation) of the slider range. Correspondingly, 
                        the maximum position value is set by PROP_SLIDER MAXPOS and
                        visually occurs when the handle is in the right-most or
                        top-most position of the slider range.  

PROP_SLIDER_HANDLEBORDERCOLOR
                        This property gets/sets the RGB value of the border area around
                        the slider handle. In figure (1), this color is represented
                        by the '.' character. The other slider colors are determined by 
                        standard border properties.

PROP_LAYOUTSTYLE        This property gets/sets the current layout style of the slider
                        widget. The layout style value passed in the 'dwParam' 
                        parameter may be one of two values: LAYOUT_VERT for vertical 
                        orientation, or LAYOUT_HORZ for horizontal orientation. 
                        Vertical orientation means that the slider handle moves 
                        vertically with the minimum value being at the bottom of the 
                        slider range and the maximum value being at the top of the 
                        range. Horizontal orientation means that the slider handle 
                        moves horizontally with the minimum value being at the left 
                        side of the slider range and the maximum value being at the 
                        right side of the range.
                        
PROP_INACTIVE_BORDERCOLOR
PROP_ACTIVE_BORDERCOLOR
PROP_SINACTIVE_BORDERCOLOR
PROP_SACTIVE_BORDERCOLOR
PROP_BORDERCOLOR        These properties determine the color of the border of the 
                        slider range and the handle fill area. This color is 
                        represented by the '*' character in figure (1). There are
                        different properties and colors for each of the four 
                        possible selected/active states. PROP_BORDERCOLOR is a shortcut
                        property for setting all four state values to the same
                        color.
                        

PROP_INACTIVE_BGCOLOR
PROP_ACTIVE_BGCOLOR
PROP_SINACTIVE_BGCOLOR
PROP_SACTIVE_BGCOLOR
PROP_BGCOLOR            These properties determine the color of the inside of the 
                        slider range. This color is represented by the 'b' character 
                        in figure (1). There are different properties and colors for 
                        each of the four possible selected/active states. PROP_BGCOLOR 
                        is a shortcut property for setting all four state values to the 
                        same color.

PROP_FLAGS              
                        Sets/Gets flags that effect how the slider widget will behave.
                        
                        SLWF_VAL_BOUNDARY_CHECK
                        -----------------------
                        When this flag is set the sliderwidget will start policing 
                        the position value when the value is set in the value model. If the
                        position value is set to a value less than 0, it will be reset to 0, and
                        if the position is set to a value greater than Max Position, it 
                        will be reset to Max Position. Slider widget attaches a PFNADAPTSET
                        callback to the value model to do this. If the view overrides this
                        PFNADAPTSET callback, then policing is not guaranteed.

PROPEX_WIDGETELEMDRAGTRSHLD
                        This property sets/gets the drag threshold values of the slider widget 
                        for the passed element type. 

PROPEX_SLIDERHANDLE_WIDGET      
                        This property contains the widget of the slider handle. Slider 
                        widget creates a default borderwidget for slider handle, but an 
                        external widget can also be set/get using this property. 
                        Note: the height of the slider handle will always be the specified
                        height of the slider for the horizontal layout style, and  the width of
                        the slider handle will always be the specified width of the slider
                        for the vertical layout style. the "bar" part of the slider will always
                        be 6 pixels smaller than the slider width/height(3 on either side). 

Required Model: IValueModel

Model Data:
   
   uint32  modelData;

The slider widget relies on a value model that presents its data as an unsigned integer in the range of zero to 'MaxPos', which is the maximum position value and is set by the property: PROP_SLIDER_MAXPOS.
For example, if 'MaxPos' is set to the value (4), there are five possible values and corresponding positions for the slider handle: (0,1,2,3,4). Continuing with the above example, if the modelData is set to '1', the slider handle will be positioned offset from the left side at one-fifth of the length of the slider:
   
      +-+
   <| |<========
      +-+
   0   1   2   3   4


Instantiaion
The slider widget is instantiated by passing AEECLSID_SliderWidget into ISHELL_CreateInstance.
Cleanup
The slider widget is reference counted. When you are done with your reference to the slider widget, you should Release that reference. Any slider widget specific cleanup will be handled for you when all references are released.
Default Interface Name
Comment
None
  • Follow