widget.c

基于TI公司Cortex-M3的uart超级通信开发

//*****************************************************************************
//
// widget.c - Generic widget tree handling code.
//
// Copyright (c) 2008-2009 Luminary Micro, Inc.  All rights reserved.
// Software License Agreement
// 
// Luminary Micro, Inc. (LMI) is supplying this software for use solely and
// exclusively on LMI's microcontroller products.
// 
// The software is owned by LMI and/or its suppliers, and is protected under
// applicable copyright laws.  All rights are reserved.  You may not combine
// this software with "viral" open-source software in order to form a larger
// program.  Any use in violation of the foregoing restrictions may subject
// the user to criminal sanctions under applicable laws, as well as to civil
// liability for the breach of the terms and conditions of this license.
// 
// THIS SOFTWARE IS PROVIDED "AS IS".  NO WARRANTIES, WHETHER EXPRESS, IMPLIED
// OR STATUTORY, INCLUDING, BUT NOT LIMITED TO, IMPLIED WARRANTIES OF
// MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE APPLY TO THIS SOFTWARE.
// LMI SHALL NOT, IN ANY CIRCUMSTANCES, BE LIABLE FOR SPECIAL, INCIDENTAL, OR
// CONSEQUENTIAL DAMAGES, FOR ANY REASON WHATSOEVER.
// 
// This is part of revision 5228 of the Stellaris Graphics Library.
//
//*****************************************************************************

#include "driverlib/debug.h"
#include "grlib/grlib.h"
#include "grlib/widget.h"

//*****************************************************************************
//
//! \addtogroup widget_api
//! @{
//
//*****************************************************************************

//*****************************************************************************
//
// Flags that indicate how messages from the message queue are processed.  They
// can be sent via either a pre-order or post-order search, and can optionally
// be sent to no other widgets once one accepts the message.
//
//*****************************************************************************
#define MQ_FLAG_POST_ORDER      1 //选择信息存储的方式
#define MQ_FLAG_STOP_ON_SUCCESS 2 //是否依次存储成功后即可。

//*****************************************************************************
//
// The size of the message queue.  In order to make the queue pointer
// arithmetic more efficient, this should be a power of two.
//
//*****************************************************************************
#define QUEUE_SIZE              16

#ifdef DEBUG_MSGQ
//*****************************************************************************
//
// In debug builds, keep track of the number of cases where a message was
// lost due to the queue being full.  We count the following occurrences:
//
// 1. All messages discarded due to queue overflow (g_ulMQOverflow)
// 2. Messages other than WIDGET_MSG_PTR_MOVE discarded due to queue
//    overflow (g_ulMQNonMouseOverflow).  In this case, we also remember the
//    last message that was discarded (g_ulMQLastLostMsg).
// 3. The number of calls to WidgetMessageQueueAdd that fail due to the queue
//    mutex already being held.
// 4. The number of cases where WidgetMessageQueueAdd reused an unread
//    WIDGET_MSG_PTR_MOVE message when a second one arrived before the previous
//    one had been processed.
//定义标记量
//*****************************************************************************
unsigned long g_ulMQOverflow = 0;
unsigned long g_ulMQNonMouseOverflow = 0;
unsigned long g_ulMQLastLostMsg = 0;
unsigned long g_ulMQMutexClash = 0;
unsigned long g_ulMQMoveOverwrite = 0;
#endif

//*****************************************************************************
//
// This structure describes the message queue used to hold widget messages.
//定义一个用来存储控件信息的队列结构
//*****************************************************************************
typedef struct
{
    //
    // The flags that describe how this message should be processed; this is
    // defined by the MQ_FLAG_xxx flags.
    //信息如何处理
    unsigned long ulFlags;

    //
    // The widget (or widget tree) to which the message should be sent.
    //信息存储控件
    tWidget *pWidget;

    //
    // The message to be sent.
    //传递的信息
    unsigned long ulMessage;

    //
    // The first parameter to the message.
    //信息第一个参数
    unsigned long ulParam1;

    //
    // The second parameter to the message.
    //信息第二个参数
    unsigned long ulParam2;
}
tWidgetMessageQueue;

//*****************************************************************************
//
// The root of the widget tree.  This is the widget used when no parent is
// specified when adding a widget, or when no widget is specified when sending
// a message.  The parent and sibling of this widget are always zero.  This
// should not be directly referenced by applications; WIDGET_ROOT should be
// used instead.
//控件树的根，表示一个虚拟的控件
//*****************************************************************************
tWidget g_sRoot =
{
    sizeof(tWidget),
    0,
    0,
    0,
    0,
    {
        0,
        0,
        0,
        0,
    },
    WidgetDefaultMsgProc
};

//*****************************************************************************
//
// The widget that has captured pointer messages.  When a pointer down message
// is accepted by a widget, that widget is saved in this variable and all
// subsequent pointer move and pointer up messages are sent directly to this
// widget.
//存储树中某个被按下的控件
//*****************************************************************************
static tWidget *g_pPointerWidget = 0;

//*****************************************************************************
//
// The message queue that holds messages that are waiting to be processed.
//控件信息队列
//*****************************************************************************
static volatile tWidgetMessageQueue g_pMQ[QUEUE_SIZE];

//*****************************************************************************
//
// The offset to the next message to be read from the message queue.  The
// message queue is empty when this has the same value as g_ulMQWrite.
//
//*****************************************************************************
static unsigned long g_ulMQRead = 0;

//*****************************************************************************
//
// The offset to the next message to be written to the message queue.  The
// message queue is full when this value is one less than g_ulMQRead (modulo
// the queue size).
//
//*****************************************************************************
static volatile unsigned long g_ulMQWrite = 0;

//*****************************************************************************
//
// The mutex used to protect access to the message queue.
//保护信息队列的使用
//*****************************************************************************
static unsigned char g_ucMQMutex = 0;

//*****************************************************************************
//
//! Initializes a mutex to the unowned state.
//!
//! \param pcMutex is a pointer to mutex that is to be initialized.
//!
//! This function initializes a mutual exclusion semaphore (mutex) to its
//! unowned state in preparation for use with WidgetMutexGet() and
//! WidgetMutexPut().  A mutex is a two state object typically used to
//! serialize access to a shared resource.  An application will call
//! WidgetMutexGet() to request ownership of the mutex.  If ownership is
//! granted, the caller may safely access the resource then release the mutex
//! using WidgetMutexPut() once it is finished.  If ownership is not granted,
//! the caller knows that some other context is currently modifying the shared
//! resource and it must not access the resource at that time.
//!
//! Note that this function must not be called if the mutex passed in \e pcMutex
//! is already in use since this will have the effect of releasing the lock even
//! if some caller currently owns it.
//!
//! \return None.
//初始化保护
//*****************************************************************************
void
WidgetMutexInit(unsigned char *pcMutex)
{
    //
    // Catch NULL pointers in a debug build.
    //
    ASSERT(pcMutex);

    //
    // Clear the mutex location to set it to the unowned state.
    //
    *pcMutex = 0;
}

//*****************************************************************************
//
//! Attempts to acquire a mutex.
//!
//! \param pcMutex is a pointer to mutex that is to be acquired.
//!
//! This function attempts to acquire a mutual exclusion semaphore (mutex) on
//! behalf of the caller.  If the mutex is not already held, 0 is returned to
//! indicate that the caller may safely access whichever resource the mutex is
//! protecting.  If the mutex is already held, 1 is returned and the caller
//! must not access the shared resource.
//!
//! When access to the shared resource is complete, the mutex owner should call
//! WidgetMutexPut() to release the mutex and relinquish ownership of the
//! shared resource.
//!
//! \return Returns 0 if the mutex is acquired successfully or 1 if it is
//! already held by another caller.
//获取保护信息
//*****************************************************************************
#if defined(ewarm) || defined(DOXYGEN)
unsigned long
WidgetMutexGet(unsigned char *pcMutex)
{
    //
    // Acquire the mutex if possible.
    //
    __asm("    mov     r1, #1\n"
          "    ldrexb  r2, [r0]\n"
          "    cmp     r2, #0\n"
          "    it      eq\n"
          "    strexb  r2, r1, [r0]\n"
          "    mov     r0, r2\n");

    //
    // "Warning[Pe940]: missing return statement at end of non-void function"
    // is suppressed here to avoid putting a "bx lr" in the inline assembly
    // above and a superfluous return statement here.
    //
#pragma diag_suppress=Pe940
}
#pragma diag_default=Pe940
#endif
#if defined(codered) || defined(gcc) || defined(sourcerygxx)
unsigned long __attribute__((naked))
WidgetMutexGet(unsigned char *pcMutex)
{
    unsigned long ulRet;

    //
    // Acquire the mutex if possible.
    //
    __asm("    mov      r1, #1\n"
          "    ldrexb   r2, [r0]\n"
          "    cmp      r2, #0\n"
          "    it       eq\n"
          "    strexbeq r2, r1, [r0]\n"
          "    mov      r0, r2\n"
          "    bx       lr\n"
          : "=r" (ulRet));

    //
    // The return is handled in the inline assembly, but the compiler will
    // still complain if there is not an explicit return here (despite the fact
    // that this does not result in any code being produced because of the
    // naked attribute).
    //
    return(ulRet);
}
#endif
#if defined(rvmdk) || defined(__ARMCC_VERSION)
__asm unsigned long
WidgetMutexGet(unsigned char *pcMutex)
{
    mov         r1, #1
    ldrexb      r2, [r0]
    cmp         r2, #0
    it          eq
    strexbeq    r2, r1, [r0]
    mov         r0, r2
    bx          lr
}
#endif

//*****************************************************************************
//
//! Release a mutex.
//!
//! \param pcMutex is a pointer to mutex that is to be released.
//!
//! This function releases a mutual exclusion semaphore (mutex), leaving it in
//! the unowned state.
//!
//! \return None.
//释放保护
//*****************************************************************************
void
WidgetMutexPut(unsigned char *pcMutex)
{
    //
    // Release the mutex.
    //
    *pcMutex = 0;
}

//*****************************************************************************
//
// Determines if a widget exists in the tree below a given point.
//
// \param pWidget is a pointer to the widget tree.
// \param pFind is a pointer to the widget that is being searched for.
//
// This function searches the widget tree below pWidget to determine whether
// or not the widget pointed to by \e pFind exists in the subtree.
//
// \return Returns 1 if \e pFind exists in the subtree or 0 if it does not.
//查找pWidget中是否包含pFind控件
//
//采用的是自底向上查找方法，先将指针指向最后一层，然后判断最后一层是否
//含有该控件，含有，返回1，否则 然后再依次向上，直到查找完最后一个父控件pWidget。
//
//
//
//*****************************************************************************
static long
WidgetIsInTree(tWidget *pWidget, tWidget *pFind)
{
    tWidget *pTemp;

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

    //
    // Loop through the tree under the widget until every widget is searched.
    //最外层循环先将指针指向底
    for(pTemp = pWidget; pTemp != pWidget->pParent; )
    {
        //
        // See if this widget has a child.
        //判断是否为最底层
        if(pTemp->pChild)
        {
            //
            // Go to this widget's child first.
            //
            pTemp = pTemp->pChild;
        }

        //
        // This widget does not have a child, so either a sibling or a parent
        // must be checked.  When moving back to the parent, another move must
        // be performed as well to avoid getting stuck in a loop (since the
        // parent's children have already been searched.
        //
        else
        {
            //
            // Loop until returning to the parent of the starting widget.  This
            // loop will be explicitly broken out of if an intervening widget
            // is encountered that has not been searched.
            //
            while(pTemp != pWidget->pParent)
            {
                if(pTemp == pFind)//判断是否与寻找控件相同
                {
                    return(1);
                }

                //
                // See if this widget has a sibling.
                //指向其同层的兄弟控件
                if(pTemp->pNext)
                {
                    //
                    // Visit the sibling of this widget.
                    //
                    pTemp = pTemp->pNext;

                    //
                    // Since this widget has not been searched yet, break out
                    // of the controlling loop.
                    //
                    break;
                }
                else
                {
                    //同层查找完毕，指向其上一层