//
            // If this distance is greater than or equal to the height of a
            // line of text, we need to check to see if we need to scroll the
            // list box contents.
            //
            if(abs(lLineNum) >= GrFontHeightGet(pListBox->pFont))
            {
                //
                // We have to scroll if this is possible.  How many lines can
                // be visible on the display?
                //
                lVisible = (pListBox->sBase.sPosition.sYMax -
                            pListBox->sBase.sPosition.sYMin) /
                            (long)GrFontHeightGet(pListBox->pFont);

                //
                // If we have fewer strings in the listbox than there are lines
                // on the display, scrolling is not possible so give up now.
                //
                if(lVisible > (long)pListBox->usPopulated)
                {
                    return(1);
                }

                //
                // How many lines of scrolling does the latest pointer position
                // indicate?  A negative value implies downward scrolling (i.e.
                // showing earlier strings).
                //
                lScroll = lLineNum / (long)GrFontHeightGet(pListBox->pFont);

                //
                // What is the farthest we could scroll downwards (i.e. moving
                // the pointer towards the bottom of the screen)?  Note - this
                // will be negative or 0.
                //
                lMaxDown = (pListBox->usStartEntry >= pListBox->usOldestEntry) ?
                           (pListBox->usOldestEntry - pListBox->usStartEntry ) :
                           ((pListBox->usOldestEntry - pListBox->usStartEntry) -
                             pListBox->usMaxEntries);

                //
                // What is the farthest we could scroll upwards?  Note - this
                // will be a positive number.
                //
                lMaxUp = ((long)pListBox->usPopulated - lVisible) + lMaxDown;

                //
                // Determine the actual scroll distance given the maximum
                // distances calculated.
                //
                lScroll = min(lScroll, lMaxUp);
                lScroll = max(lScroll, lMaxDown);

                if(lScroll)
                {
                	long lTemp;
                	
                    //
                    // Adjust the start entry appropriately, taking care to handle
                    // the wrap case.  The use of a temporary variable here is 
                    // required to work around a compiler bug which resulted in an
                    // invalid value of pListBox->usStartEntry following the 
                    // calculation.
                    //
                    lTemp = pListBox->usStartEntry;
                    lTemp += lScroll;
                    lTemp %= (long)pListBox->usMaxEntries;
                    pListBox->usStartEntry = (unsigned short)lTemp;
                
                    //
                    // Remember that we scrolled.
                    //
                    pListBox->usScrolled = 1;

                    //
                    // Adjust the pointer position we record to take into account
                    // the amount we just scrolled.
                    //
                    pListBox->lPointerY -= (lScroll *
                                            GrFontHeightGet(pListBox->pFont));

                    //
                    // Repaint the contents of the widget.
                    //
                    WidgetPaint((tWidget *)pListBox);
                }
            }

            return(1);
        }
    }

    //
    // We don't handle any other messages so return 0 if we get these.
    //
    return(0);
}

//*****************************************************************************
//
//! Handles messages for a listbox widget.
//!
//! \param pWidget is a pointer to the listbox widget.
//! \param ulMsg is the message.
//! \param ulParam1 is the first parameter to the message.
//! \param ulParam2 is the second parameter to the message.
//!
//! This function receives messages intended for this listbox widget and
//! processes them accordingly.  The processing of the message varies based on
//! the message in question.
//!
//! Unrecognized messages are handled by calling WidgetDefaultMsgProc().
//!
//! \return Returns a value appropriate to the supplied message.
//
//*****************************************************************************
long
ListBoxMsgProc(tWidget *pWidget, unsigned long ulMsg, unsigned long ulParam1,
              unsigned long ulParam2)
{
    tListBoxWidget *pListBox;

    //
    // Check the arguments.
    //
    ASSERT(pWidget);

    //
    // Convert the generic pointer to a list box pointer.
    //
    pListBox = (tListBoxWidget *)pWidget;

    //
    // Determine which message is being sent.
    //
    switch(ulMsg)
    {
        //
        // A pointer message has been received.
        //
        case WIDGET_MSG_PTR_DOWN:
        case WIDGET_MSG_PTR_UP:
        case WIDGET_MSG_PTR_MOVE:
            return(ListBoxPointer(pListBox, ulMsg, (long)ulParam1,
                                  (long)ulParam2));

        //
        // The widget paint request has been sent.
        //
        case WIDGET_MSG_PAINT:
        {
            //
            // Handle the widget paint request.
            //
            ListBoxPaint(pWidget);

            //
            // Return one to indicate that the message was successfully
            // processed.
            //
            return(1);
        }

        //
        // An unknown request has been sent.
        //
        default:
        {
            //
            // Let the default message handler process this message.
            //
            return(WidgetDefaultMsgProc(pWidget, ulMsg, ulParam1, ulParam2));
        }
    }
}

//*****************************************************************************
//
//! Initializes a listbox widget.
//!
//! \param pWidget is a pointer to the listbox widget to initialize.
//! \param pDisplay is a pointer to the display on which to draw the listbox.
//! \param ppcText is a pointer to an array of character pointers which will
//! hold the strings that the listbox displays.
//! \param usMaxEntries provides the total number of entries in the \e ppcText
//! array.
//! \param usPopulatedEntries provides the number of entries in the \e ppcText
//! array which are populated.
//! \param lX is the X coordinate of the upper left corner of the listbox.
//! \param lY is the Y coordinate of the upper left corner of the listbox.
//! \param lWidth is the width of the listbox.
//! \param lHeight is the height of the listbox.
//!
//! This function initializes the provided listbox widget.
//!
//! \return None.
//
//*****************************************************************************
void
ListBoxInit(tListBoxWidget *pWidget, const tDisplay *pDisplay,
            const char **ppcText, unsigned short usMaxEntries,
            unsigned short usPopulatedEntries, long lX, long lY, long lWidth,
            long lHeight)
{
    unsigned long ulIdx;

    //
    // Check the arguments.
    //
    ASSERT(pWidget);
    ASSERT(pDisplay);

    //
    // Clear out the widget structure.
    //
    for(ulIdx = 0; ulIdx < sizeof(tListBoxWidget); ulIdx += 4)
    {
        ((unsigned long *)pWidget)[ulIdx / 4] = 0;
    }

    //
    // Set the size of the listbox widget structure.
    //
    pWidget->sBase.lSize = sizeof(tListBoxWidget);

    //
    // Mark this widget as fully disconnected.
    //
    pWidget->sBase.pParent = 0;
    pWidget->sBase.pNext = 0;
    pWidget->sBase.pChild = 0;

    //
    // Save the display pointer.
    //
    pWidget->sBase.pDisplay = pDisplay;

    //
    // Set the extents of this listbox.
    //
    pWidget->sBase.sPosition.sXMin = lX;
    pWidget->sBase.sPosition.sYMin = lY;
    pWidget->sBase.sPosition.sXMax = lX + lWidth - 1;
    pWidget->sBase.sPosition.sYMax = lY + lHeight - 1;

    //
    // Use the listbox message handler to process messages to this listbox.
    //
    pWidget->sBase.pfnMsgProc = ListBoxMsgProc;

    //
    // Initialize some of the widget fields that are not accessible via
    // macros.
    //
    pWidget->ppcText = ppcText;
    pWidget->usMaxEntries = usMaxEntries;
    pWidget->usPopulated = usPopulatedEntries;
    pWidget->sSelected = (short)0xFFFF;
}

//*****************************************************************************
//
//! Adds a line of text to a listbox.
//!
//! \param pListBox is a pointer to the listbox widget that is to receive the
//! new text string.
//! \param pcTxt is a pointer to the string that is to be added to the listbox.
//!
//! This function adds a new string to the listbox.  If the listbox has
//! style \b #LISTBOX_STYLE_WRAP and the current string table is full, this
//! function will discard the oldest string and replace it with the one passed
//! here.  If this style flag is absent, the function will return -1 if no
//! empty entries exist in the string table for the widget.
//!
//! The display is not automatically updated as a result of this function call.
//! An application must call WidgetPaint() to update the display after adding
//! a new string to the listbox.
//!
//! \note To replace the string associated with a particular, existing element
//! in the listbox, use ListBoxTextSet().
//!
//! \return Returns the string table index into which the new string has been
//! placed if successful or -1 if the string table is full and
//! \b #LISTBOX_STYLE_WRAP is not set.
//
//*****************************************************************************
long ListBoxTextAdd(tListBoxWidget *pListBox, const char *pcTxt)
{
    unsigned long ulIndex;

    //
    // Is the list box full?
    //
    if(pListBox->usPopulated == pListBox->usMaxEntries)
    {
        //
        // The box is already full.  If the wrap style is not set, fail
        // the call.
        //
        if(!(pListBox->ulStyle & LISTBOX_STYLE_WRAP))
        {
            //
            // The listbox is full and it is not configured to wrap so we can't
            // add another string to it.
            //
            return(-1);
        }
        else
        {
            //
            // We are wrapping so replace the oldest entry in the box.
            //
            ulIndex = pListBox->usOldestEntry;

            //
            // Check to see if we are displaying the oldest entry and, if so,
            // move the start entry on by one to keep the display order
            // correct.
            //
            if(pListBox->usOldestEntry == pListBox->usStartEntry)
            {
                pListBox->usStartEntry++;
                if(pListBox->usStartEntry == pListBox->usMaxEntries)
                {
                    pListBox->usStartEntry = 0;
                }
            }

            //
            // The new oldest entry is the next one.  Update the index and
            // take care to wrap if we reach the end of the string table.
            //
            pListBox->usOldestEntry++;
            if(pListBox->usOldestEntry == pListBox->usMaxEntries)
            {
                pListBox->usOldestEntry = 0;
            }
        }
    }
    else
    {
        //
        // The listbox is not full so add the new string to the first free
        // slot in the string table.
        //
        ulIndex = pListBox->usPopulated;
        pListBox->usPopulated++;
    }

    //
    // Save the new string in the appropriate string table entry.
    //
    pListBox->ppcText[ulIndex] = pcTxt;

    //
    // Tell the caller which string table entry was added.
    //
    return((long)ulIndex);
}

//*****************************************************************************
//
// Close the Doxygen group.
//! @}
//
//*****************************************************************************