Developer

API Reference

Border Background Events

Brew Release
Brew MP 1.0.2
See Also
Border Events AEEEvent Widget Events Border Support Events Border Decoration Events Model Events StepEvent
Description
These Events deal with the background that will be placed behind the content of the widget, forming a canvas for the widget to be drawn on. This background can be specified through both colors and images which can all be set to values based on the current state of the widget.
These events fall into two categories:
- Background Fill Properties - These properties deal with the color based background. A widget's background fill can
either be specified as a solid sheet or as a gradient that moves from an initial primary color to a secondary color as the distance from a point or line increases.
- Background Image Properties - These properties deal with the optional image or set of images that can be placed
behind widget content. This image, by default, appears on top of the color based background described previously; however, it can be specified through flags that the image should be under the color based background if that is desired. If the image is known to be completely opaque, it is recommended that the (underlying) background color be specified as RGBA_NONE for efficiency purposes. Likewise, if the image is to be drawn underneath the background color, it is recommended that the background fill color be at least partially transparent so all that work rendering the image isn't for naught.
If the image is smaller than the area of the background, the image may be tiled to fill all of the available space.
Supported Events:
Event                   Description
-----                   ------------------------------------------------------------
EVT_WDG_SETPROPERTY     The border handler responds to this event by attempting to set the property
                        identified by the 'wParam' parameter.  The following properties may be set
                        to any widget which supports borders.
                        PROP_BGCOLOR
                        PROP_ACTIVE_BGCOLOR
                        PROP_INACTIVE_BGCOLOR
                        PROP_SELECTED_BGCOLOR
                        PROP_SACTIVE_BGCOLOR
                        PROP_SINACTIVE_BGCOLOR
                        PROP_TRANSPARENCY    ** Deprecated **
                        PROP_BGTRANSPARENCY  ** Deprecated **
                        PROP_GRADIENT_STYLE
                        PROP_GRADIENT
                        PROP_ACTIVE_GRADIENT
                        PROP_INACTIVE_GRADIENT
                        PROP_SELECTED_GRADIENT
                        PROP_SACTIVE_GRADIENT
                        PROP_SINACTIVE_GRADIENT
                        PROP_BGIMAGE
                        PROP_BGIMAGE_FLAGS
                        PROP_BGIMAGE_PARM
                        PROP_BGIMAGE_ANIMATE
                        PROP_BGIMAGE_TILED_BORDER
                        PROP_BGIMAGE_FRAME
                        PROP_BGIMAGE_ANIMATE_FLAGS
                            IWidget_SetProperty
                            IWidget_SetPropertyEx

EVT_WDG_GETPROPERTY     The border handler responds to this event by attempting to retrieve the
                        property identified by the 'wParam' parameter.  The following properties may
                        be retrieved from any widget which supports borders.
                        PROP_BGCOLOR
                        PROP_ACTIVE_BGCOLOR
                        PROP_INACTIVE_BGCOLOR
                        PROP_SELECTED_BGCOLOR
                        PROP_SACTIVE_BGCOLOR
                        PROP_SINACTIVE_BGCOLOR
                        PROP_TRANSPARENCY    ** Deprecated **
                        PROP_BGTRANSPARENCY  ** Deprecated **
                        PROP_BGIMAGE
                        PROP_BGIMAGE_FLAGS
                        PROP_BGIMAGE_TILED_BORDER
                        PROP_BGIMAGE_ANIMATE_FLAGS
                            IWidget_GetProperty
                            IWidget_GetPropInt
                            IWidget_GetPropPtr
                            IWidget_GetPropRGB

Properties:


Property                      Description
--------                      ------------------------------------------------------------
< Background Fill Properties <
PROP_BGCOLOR                  Sets or retrieves the color that will be used to display the
                              background for all states of the widget.  If the widget uses multiple
                              border colors (through other properties), PROP_BGCOLOR will retrieve
                              the color that is used in the Active, Unselected state (Although it
                              will still set all of the colors when used in the SET capacity).
                                  IWidget_SetBGColor

PROP_ACTIVE_BGCOLOR           Sets or retrieves the color that will be used to display the
                              background when the widget is in the Unselected, Active state.
                                 IWidget_SetActiveBGColor
                                 IWidget_GetActiveBGColor

PROP_INACTIVE_BGCOLOR         Sets or retrieves the color that will be used to display the
                              background when the widget is in the Unselected, Inactive state.
                                  IWidget_SetInactiveBGColor
                                  IWidget_GetInactiveBGColor

PROP_SELECTED_BGCOLOR         Sets or retrieves the color that will be used to display the
                              background when the widget is in either of the Selected states.  If
                              the widget uses multiple selected border colors, PROP_SELECTED_BGCOLOR
                              will retrieve the color that is used by the Active, Selected state
                              (Although it will still set all of the colors in the Selected state
                              when used in the SET capacity).
                                  IWidget_SetSelectedBGColor

PROP_SACTIVE_BGCOLOR          Sets or retrieves the color that will be used to display the
                              background when the widget is in the Selected, Active state.
                                  IWidget_SetSelectedActiveBGColor
                                  IWidget_GetSelectedActiveBGColor

PROP_SACTIVE_BGCOLOR          Sets or retrieves the color that will be used to display the
                              background when the widget is in the Selected, Inactive state.
                                  IWidget_SetSelectedInactiveBGColor
                                  IWidget_GetSelectedInactiveBGColor

PROP_TRANSPARENCY
PROP_BGTRANSPARENCY           These two properties set the transparency that is used in all states
                              of the widget for the background or retrieve the transparency that is
                              being used in the Unselected, Active state.
                                  IWidget_SetTransparency
                                  IWidget_SetBGTransparency
                                  IWidget_GetTransparency
                                  IWidget_GetBGTransparency

PROP_GRADENT_STYLE            Sets or retrieves the gradient fill style.  At this time, all
                              gradients are binary gradients where the start color is specified
                              through one of the BGCOLOR properties and the end color is specified
                              through one of the GRADIENT properties.  The fill style can take on
                              any of the following styles.
                                                       GRADIENT_STYLE_NONE
                                                       -------------------
                              This is the default state of the widget and specifies that a gradient
                              will not be used by the widget.  It will use only the start color and
                              will fill the whole widget with that color.
                                                       GRADIENT_STYLE_VERT
                                                       -------------------
                              This fill style will draw a smoothly changing gradient starting from
                              the top edge of the widget's background and proceeding down across the
                              widget until it reaches the bottom of the widget's background
                              rectangle.
                                                       GRADIENT_STYLE_HORZ
                                                       -------------------
                              This fill style will draw a smoothly changing gradient starting from
                              the left side of the widget's rectangle and proceeding right across
                              the widget until it reaches the right side of the widget's background
                              rectangle.
                                                    GRADIENT_STYLE_CENTERVERT
                                                    -------------------------
                              This fill style will draw a smoothly changing gradient starting from
                              the top of the widget and proceeding down until the center of the
                              widget, where it will take on the end gradient color.  It will then
                              proceed from the middle of the widget to the bottom of the widget in a
                              smooth transition from the end color back to the start color.
                                                    GRADIENT_STYLE_CENTERHORZ
                                                    -------------------------
                              This fill style will draw a smoothly changing gradient starting from
                              the left edge of the widget and proceeding right across the widget
                              until it reaches the center of the widget, where it will take on the
                              end gradient color.  It will then proceed from the middle of the
                              widget to the right edge of the widget in a smooth transition from the
                              end color back to the start color.
                                  IWidget_SetGradientStyle

PROP_GRADIENT                 Sets the color that will be used for the terminal color of a gradient
                              progression in all states.
                                  IWidget_SetGradientColor

PROP_ACTIVE_GRADIENT          Sets the color that will be used for the terminal color of a gradient
                              progression in the Unselected, Active state.
				  IWidget_SetActiveGradientColor

PROP_INACTIVE_GRADIENT        Sets the color that will be used for the terminal color of a gradient
                              progression in the Unselected, Inactive state.
			          IWidget_SetInactiveGradientColor

PROP_SELECTED_GRADIENT        Sets the color that will be used for the terminal color of a gradient
                              progression in both of the Selected states.
			          IWidget_SetSelectedGradientColor

PROP_SACTIVE_GRADIENT         Sets the color that will be used for the terminal color of a gradient
                              progression in the Selected, Active state.
                                  IWidget_SetSelectedActiveGradientColor

PROP_SINACTIVE_GRADIENT       Sets the color that will be used for the terminal color of a gradient
                              progression in the Selected, Inactive state.
                                  IWidget_SetSelectedInactiveGradientColor
PROP_BGIMAGE                  Sets or retrieves the background image that will be used by the
                              widget.  This image has many properties that can be set on it, which
                              are described in greater detail in the properties that follow.
                                  IWidget_SetBGImage
                                  IWidget_GetBGImage
PROP_BGIMAGE_FLAGS            Sets or retrieves a set of flag masks that dictate how the background
                              image will behave.  PROP_BGIMAGE needs to be set prior to using this
                              property as the background image flags are stored on a per background
                              image basis.
                                                       BGIF_HASSELECTIMAGE
                                                       -------------------
                              When this flag is set, the background image consists of a pair of
                              images of precisely the same size.  The first image will be displayed
                              by the widget when the widget is in its unselected state -- the second
                              image is displayed when the image is selected.  By default this flag
                              is off: indicating that the image contains only a single item to be
                              displayed, regardless of the current selection state.
                                                            BGIF_TILED
                                                            ----------
                              This flag indicates that the background image should be tiled inside
                              the widget's extent.  The image will fill the full extent of the
                              widget.  If the image does not propportionately fit inside the extent,
                              the image will be clipped to fit.
                                                         BGIF_IMAGEUNDER
                                                         ---------------
                              This flag indicates that the background image will be drawn underneath
                              the background fill color, if any.  If this flag is set and the
                              background fill color is also set, the background fill should have
                              some degree of transparency.  Otherwise the background image will not
                              be visible.  By default, this flag is off, indicating that the
                              background image is drawn over the background fill color.
                                                          IDF_ALIGN_LEFT
                                                          --------------
                              This flag indicates that the background image will be drawn so that
                              the left edge of the image will be aligned to the inner left edge of
                              the widget.
                                                         IDF_ALIGN_RIGHT
                                                         ---------------
                              This flag indicates that the background image will be drawn so that
                              the right edge of the image will be aligned to the inner right edge of
                              the widget.
                                                         IDF_ALIGN_CENTER
                                                         ----------------
                              This flag indicates that the background image will be drawn so that
                              the image is horizontally centered within the widget.
                                                          IDF_ALIGN_TOP
                                                          -------------
                              This flag indicates that the background image will be drawn so that
                              the top edge of the image will be aligned to the inner top edge of the
                              widget.
                                                         IDF_ALIGN_BOTTOM
                                                         ----------------
                              This flag indicates that the background image will be drawn so that
                              the bottom edge of the image will be aligned to the inner bottom edge
                              of the widget.
                                                         IDF_ALIGN_MIDDLE
                                                         ----------------
                              This flag indicates that the background image will be drawn so that
                              the image is vertically centered within the widget
                                  IWidget_SetBGImageFlags
                                  IWidget_GetBGImageFlags

PROP_BGIMAGE_PARM             Ease of use property to set IImage parameters for the background image
                              using IImage_SetParms.  In order to retrieve parameters, PROP_BGIMAGE
                              must be used first to retrieve the IImage pointer and then parameters
                              can be queried as normal.  It is not recommended that parameters be
                              applied directly to his IImage pointer as the border will not receive
                              notification of any changes to the image, so the widget will not be
                              properly invalidated.
                                  IWidget_SetBGImageParms
PROP_BGIMAGE_ANIMATE          Starts or stops the animation of a background image.  (Set Only)
                                  IWidget_SetBGImageAnimate
PROP_BGIMAGE_ANIMATE_FLAGS    Sets or retrieves flags related to the background image animation.
                                                        AF_ENABLE_EVT_STEP
                                                        ------------------
                              This flag notifies the widget that it should send StepEvents out
                              through the widget's ViewModel.
                                                         AF_ANIMATE_ONCE
                                                         ---------------
                              This flag causes image animation to stop on the last frame after one
                              animation sequence has completed rather than the default behavior
                              which is to continue looping through the animation until the animation
                              has been explicitly stopped through PROP_BGIMAGE_ANIMATE.
                                  IWidget_SetBGImageAnimateFlags
                                  IWidget_GetBGImageAnimateFlags

PROP_BGIMAGE_TILED_BORDER     Enables or disables border tiling and sets the dimensions of the left,
                              top, right, and bottom borders.  Tiling is described in greater detail
                              below in the section entitled "Background Image Tiling."
                                  IWidget_SetBGImageTiledBorder

PROP_BGIMAGE_FRAME            Sets the currently displayed frame in a multiple frame image.  Frames
                              are numbered from zero to the total number of frames minus one.
                              Setting this property has the side effect of stopping image animation.
                                  IWidget_SetBGImageFrame

Background Image Tiling:


Tiling of the background image is supported by providing the ability to copy (tile) a source image multiple times across a larger region. Tiling can be as simple as multiple copies of the source, or it can be a sequence of tiles in a bordered tile pattern.
The following diagram shows a source image that consists of a 3x3 grid of colored squares.
   +---+---+---+
   | 1 | 2 | 3 |
   +---+---+---+
   | 4 | 5 | 6 |
   +---+---+---+
   | 7 | 8 | 9 |
   +---+---+---+

If the tile source image were to simply fill a widget background, the result would be the following:
   +---+---+---+---+---+---+
   | 1 | 2 | 3 | 1 | 2 | 3 |
   +---+---+---+---+---+---+
   | 4 | 5 | 6 | 4 | 5 | 6 |
   +---+---+---+---+---+---+
   | 7 | 8 | 9 | 7 | 8 | 9 |
   +---+---+---+---+---+---+
   | 1 | 2 | 3 | 1 | 2 | 3 |
   +---+---+---+---+---+---+
   | 4 | 5 | 6 | 4 | 5 | 6 |
   +---+---+---+---+---+---+
   | 7 | 8 | 9 | 7 | 8 | 9 |
   +---+---+---+---+---+---+

In addition to this simple tiling, border tiling is supported, which can preserve the border of a source image. This tiling method is specified with the PROP_BGIMAGE_TILED_BORDER property, which passes a BGImageTiledBorder data structure. This structure specifies the width or height in pixels of each border tile. To reset border tiling to simple tiling, set the PROP_BGIMAGE_TILED_BORDER passing a BGImageTiledBorder data structure will all data members set to zero.
Using a sensibly defined BGImageTiledBorder structure for the sample 'image' used above, the following tiling pattern would appear (where arrows point in the direction of tiles that may be clipped if inadequate space is provided for all of the tiles to be laid out correctly).
   +---+---+---+---+---+---+
   | 1 | 2 | 2 | 2 | 2 < 3 |
   +---+---+---+---+---+---+
   | 4 | 5 | 5 | 5 | 5 < 6 |
   +---+---+---+---+---+---+
   | 4 | 5 | 5 | 5 | 5 < 6 |
   +---+---+---+---+---+---+
   | 4 | 5 | 5 | 5 | 5 < 6 |
   +---+---+---+---+---+---+
   | 4 | 5 | 5 | 5 | 5 < 6 |
   +^^^+^^^+^^^+^^^+^^^+^^^+
   | 7 | 8 | 8 | 8 | 8 < 9 |
   +---+---+---+---+---+---+
  • Follow