//! - \b #JW_STYLE_OUTLINE to indicate that the JPEG widget should be outlined.
//! - \b #JW_STYLE_BUTTON to indicate that the JPEG widget should act as a
//!   button and that calls should be made to pfnOnClick when it is pressed or
//!   released (depending upon the state of \b #JW_STYLE_RELEASE_NOTIFY).
//!   If absent, the widget acts as a canvas which allows the image, if larger
//!   than the widget display area to be scrolled by dragging a finger on the
//!   touchscreen.  In this case, the pfnOnScroll callback will be called when
//!   any scrolling is needed.
//! - \b #JW_STYLE_TEXT to indicate that the JPEG widget should have text drawn
//!   on it (using \e pFont and \e pcText).
//! - \b #JW_STYLE_FILL to indicate that the JPEG widget should have its
//!   background filled with color (specified by \e ulFillColor).
//! - \b #JW_STYLE_SCROLL to indicate that the JPEG widget should be redrawn
//!   automatically each time the pointer is moved (touchscreen is dragged)
//!   rather than waiting for the gesture to end then redrawing once.  A client
//!   may chose to omit this style flag and call WidgetPaint() from within the
//!   pfnOnScroll callback at a rate deemed acceptable for the application.
//! - \b #JW_STYLE_LOCKED to indicate that the JPEG widget should ignore all
//!   user input and merely display the image.  If this flag is set,
//!   #JW_STYLE_SCROLL is ignored.
//! - \b #JW_STYLE_RELEASE_NOTIFY to indicate that the callback should be made
//!   when the button-style widget is released.  If absent, the callback is
//!   called when the widget is initially pressed.  This style flag is ignored
//!   unless \b #JW_STYLE_BUTTON is specified.
//!
//! \return Nothing; this is not a function.
//
//*****************************************************************************
#define JPEGWidgetStruct(pParent, pNext, pChild, pDisplay, lX, lY, lWidth,\
                         lHeight, ulStyle, ulFillColor, ulOutlineColor,   \
                         ulTextColor, pFont, pcText, pucImage, ulImgLen,  \
                         ucBorderWidth, pfnOnClick, pfnOnScroll, psInst)  \
        {                                                                 \
            {                                                             \
                sizeof(tJPEGWidget),                                      \
                (tWidget *)(pParent),                                     \
                (tWidget *)(pNext),                                       \
                (tWidget *)(pChild),                                      \
                pDisplay,                                                 \
                {                                                         \
                    lX,                                                   \
                    lY,                                                   \
                    (lX) + (lWidth) - 1,                                  \
                    (lY) + (lHeight) - 1                                  \
                },                                                        \
                JPEGWidgetMsgProc,                                        \
            },                                                            \
            ulStyle,                                                      \
            ulFillColor,                                                  \
            ulOutlineColor,                                               \
            ulTextColor,                                                  \
            pFont,                                                        \
            pcText,                                                       \
            pucImage,                                                     \
            ulImgLen,                                                     \
            ucBorderWidth,                                                \
            pfnOnClick,                                                   \
            pfnOnScroll,                                                  \
            psInst                                                        \
        }

//*****************************************************************************
//
//! Declares an initialized variable containing a JPEG button data structure.
//!
//! \param sName is the name of the variable to be declared.
//! \param pParent is a pointer to the parent widget.
//! \param pNext is a pointer to the sibling widget.
//! \param pChild is a pointer to the first child widget.
//! \param pDisplay is a pointer to the display on which to draw the push
//! button.
//! \param lX is the X coordinate of the upper left corner of the JPEG widget.
//! \param lY is the Y coordinate of the upper left corner of the JPEG widget.
//! \param lWidth is the width of the JPEG widget.
//! \param lHeight is the height of the JPEG widget.
//! \param ulStyle is the style to be applied to the JPEG widget.
//! \param ulFillColor is the color used to fill in the JPEG widget.
//! \param ulOutlineColor is the color used to outline the JPEG widget.
//! \param ulTextColor is the color used to draw text on the JPEG widget.
//! \param pFont is a pointer to the font to be used to draw text on the push
//! button.
//! \param pcText is a pointer to the text to draw on this JPEG widget.
//! \param pucImage is a pointer to the compressed image to draw on this JPEG
//! widget.
//! \param ulImgLen is the length of the data pointed to by pucImage.
//! \param ucBorderWidth is the width of the border to paint if
//! \e JW_STYLE_OUTLINE is specified.
//! \param pfnOnClick is a pointer to the function that is called when the JPEG
//! button is pressed or released.
//! \param psInst is a pointer to a read/write tJPEGInst structure that the
//! widget can use for workspace.
//!
//! This macro provides an initialized JPEG button widget data structure, which
//! can be used to construct the widget tree at compile time in global
//! variables (as opposed to run-time via function calls).
//!
//! A JPEG button displays an image centered within the widget area and
//! sends OnClick messages to the client whenever a user presses or releases
//! the touchscreen within the widget area (depending upon the state of the
//! \e #JW_STYLE_RELEASE_NOTIFY style flag).  A JPEG button does not support
//! image scrolling.
//!
//! \e ulStyle is the logical OR of the following:
//!
//! - \b #JW_STYLE_OUTLINE to indicate that the JPEG widget should be outlined.
//! - \b #JW_STYLE_TEXT to indicate that the JPEG widget should have text drawn
//!   on it (using \e pFont and \e pcText).
//! - \b #JW_STYLE_FILL to indicate that the JPEG widget should have its
//!   background filled with color (specified by \e ulFillColor).
//! - \b #JW_STYLE_SCROLL to indicate that the JPEG widget should be redrawn
//!   automatically each time the pointer is moved (touchscreen is dragged)
//!   rather than waiting for the gesture to end then redrawing once.  A client
//!   may chose to omit this style flag and call WidgetPaint() from within the
//!   pfnOnScroll callback at a rate deemed acceptable for the application.
//! - \b #JW_STYLE_LOCKED to indicate that the JPEG widget should ignore all
//!   user input and merely display the image.  If this flag is set,
//!   #JW_STYLE_SCROLL is ignored.
//! - \b #JW_STYLE_RELEASE_NOTIFY to indicate that the callback should be made
//!   when the button-style widget is released.  If absent, the callback is
//!   called when the widget is initially pressed.  This style flag is ignored
//!   unless \b #JW_STYLE_BUTTON is specified.
//!
//! \return Nothing; this is not a function.
//
//*****************************************************************************
#define JPEGButton(sName, pParent, pNext, pChild, pDisplay, lX, lY, lWidth,  \
                   lHeight, ulStyle, ulFillColor, ulOutlineColor,            \
                   ulTextColor, pFont, pcText, pucImage, ulImgLen,           \
                   ucBorderWidth, pfnOnClick, psInst)                        \
        tJPEGWidget sName =                                                  \
            JPEGWidgetStruct(pParent, pNext, pChild, pDisplay, lX, lY,       \
                             lWidth, lHeight, (ulStyle | JW_STYLE_BUTTON),   \
                             ulFillColor, ulOutlineColor, ulTextColor, pFont,\
                             pcText, pucImage, ulImgLen, ucBorderWidth,      \
                             pfnOnClick, 0, psInst)

//*****************************************************************************
//
//! Declares an initialized variable containing a JPEG canvas data structure.
//!
//! \param sName is the name of the variable to be declared.
//! \param pParent is a pointer to the parent widget.
//! \param pNext is a pointer to the sibling widget.
//! \param pChild is a pointer to the first child widget.
//! \param pDisplay is a pointer to the display on which to draw the push
//! button.
//! \param lX is the X coordinate of the upper left corner of the JPEG widget.
//! \param lY is the Y coordinate of the upper left corner of the JPEG widget.
//! \param lWidth is the width of the JPEG widget.
//! \param lHeight is the height of the JPEG widget.
//! \param ulStyle is the style to be applied to the JPEG widget.
//! \param ulFillColor is the color used to fill in the JPEG widget.
//! \param ulOutlineColor is the color used to outline the JPEG widget.
//! \param ulTextColor is the color used to draw text on the JPEG widget.
//! \param pFont is a pointer to the font to be used to draw text on the push
//! button.
//! \param pcText is a pointer to the text to draw on this JPEG widget.
//! \param pucImage is a pointer to the compressed image to draw on this JPEG
//! widget.
//! \param ulImgLen is the length of the data pointed to by pucImage.
//! \param ucBorderWidth is the width of the border to paint if JW_STYLE_OUTLINE
//! is specified.
//! \param pfnOnScroll is a pointer to the function that is called when the
//! user drags a finger or stylus across the widget area.  The values reported
//! as parameters to the callback indicate the number of pixels of offset
//! from center that will be applied to the image next time it is redrawn.
//! \param psInst is a pointer to a read/write tJPEGInst structure that the
//! widget can use for workspace.
//!
//! This macro provides an initialized JPEG canvas widget data structure, which
//! can be used to construct the widget tree at compile time in global
//! variables (as opposed to run-time via function calls).
//!
//! A JPEG canvas widget acts as an image display surface.  User input via the
//! touch screen controls the image positioning, allowing scrolling of a large
//! image within a smaller area of the display.  Image redraw can either be
//! carried out automatically whenever scrolling is required or can be delegated
//! to the application via the OnScroll callback which is called whenever the
//! user requests an image position change.
//!
//! \e ulStyle is the logical OR of the following:
//!
//! - \b #JW_STYLE_OUTLINE to indicate that the JPEG widget should be outlined.
//! - \b #JW_STYLE_TEXT to indicate that the JPEG widget should have text drawn
//!   on it (using \e pFont and \e pcText).
//! - \b #JW_STYLE_FILL to indicate that the JPEG widget should have its
//!   background filled with color (specified by \e ulFillColor).
//! - \b #JW_STYLE_SCROLL to indicate that the JPEG widget should be redrawn
//!   automatically each time the pointer is moved (touchscreen is dragged)
//!   rather than waiting for the gesture to end then redrawing once.  A client
//!   may chose to omit this style flag and call WidgetPaint() from within the
//!   pfnOnScroll callback at a rate deemed acceptable for the application.
//! - \b #JW_STYLE_LOCKED to indicate that the JPEG widget should ignore all
//!   user input and merely display the image.  If this flag is set,
//!   #JW_STYLE_SCROLL is ignored.
//!
//! \return Nothing; this is not a function.
//
//*****************************************************************************
#define JPEGCanvas(sName, pParent, pNext, pChild, pDisplay, lX, lY, lWidth,  \
                   lHeight, ulStyle, ulFillColor, ulOutlineColor,            \
                   ulTextColor, pFont, pcText, pucImage, ulImgLen,           \
                   ucBorderWidth, pfnOnScroll, psInst)                       \
        tJPEGWidget sName =                                                  \
            JPEGWidgetStruct(pParent, pNext, pChild, pDisplay, lX, lY,       \
                             lWidth, lHeight, (ulStyle & ~(JW_STYLE_BUTTON | \
                             JW_STYLE_RELEASE_NOTIFY)), ulFillColor,         \
                             ulOutlineColor, ulTextColor, pFont, pcText,     \
                             pucImage, ulImgLen, ucBorderWidth, 0,           \
                             pfnOnScroll, psInst)

//*****************************************************************************
//
//! Sets the function to call when the JPEG image is scrolled.
//!
//! \param pWidget is a pointer to the JPEG widget to modify.
//! \param pfnOnScrll is a pointer to the function to call.
//!
//! This function sets the function to be called when this widget is scrolled
//! by dragging a finger or stylus over the image area (assuming that
//! \b #JW_STYLE_BUTTON is clear).
//!
//! \return None.
//
//*****************************************************************************
#define JPEGWidgetScrollCallbackSet(pWidget, pfnOnScrll)  \
        do                                                \
        {                                                 \
            tJPEGWidget *pW = pWidget;                    \
            pW->pfnOnScroll = pfnOnScrll;                 \
        }                                                 \
        while(0)

//*****************************************************************************
//
//! Sets the function to call when the button-style widget is pressed.
//!
//! \param pWidget is a pointer to the JPEG widget to modify.
//! \param pfnOnClik is a pointer to the function to call.
//!
//! This function sets the function to be called when this widget is
//! pressed (assuming \b #JW_STYLE_BUTTON is set).  The supplied function is
//! called when the button is pressed if \b #JW_STYLE_RELEASE_NOTIFY is clear
//! or when the button is released if this style flag is set.
//!
//! \return None.
//
//*****************************************************************************
#define JPEGWidgetClickCallbackSet(pWidget, pfnOnClik)  \
        do                                              \
        {                                               \
            tJPEGWidget *pW = pWidget;                  \
            pW->pfnOnClick = pfnOnClik;                 \
        }                                               \
        while(0)

//*****************************************************************************
//
//! Sets the fill color of a JPEG widget.
//!
//! \param pWidget is a pointer to the JPEG widget to be modified.
//! \param ulColor is the 24-bit RGB color to use to fill the JPEG widget.
//!
//! This function changes the color used to fill the JPEG widget on the
//! display.  The display is not updated until the next paint request.
//!
//! \return None.
//
//*****************************************************************************
#define JPEGWidgetFillColorSet(pWidget, ulColor) \
        do                                       \
        {                                        \
            tJPEGWidget *pW = pWidget;           \
            pW->ulFillColor = ulColor;           \
        }                                        \
        while(0)


//*****************************************************************************
//
//! Disables background color fill for JPEG widget.
//!
//! \param pWidget is a pointer to the JPEG widget to modify.
//!
//! This function disables background color fill for a JPEG widget.  The display
//! is not updated until the next paint request.
//!
//! \return None.
//
//*****************************************************************************
#define JPEGWidgetFillOff(pWidget)              \
        do                                      \
        {                                       \
            tJPEGWidget *pW = pWidget;          \
            pW->ulStyle &= ~(JW_STYLE_FILL);    \
        }                                       \
        while(0)

//*****************************************************************************
//
//! Enables background color fill for a JPEG widget.