c语言深度剖析(12)—注释符号

1. 似是而非的问题

• 下面的注释是正确的吗？

#include<stdio.h>

int main()
{
    int/**/i;                             //合法int i;

    char* s = "abcdefg     //ijklmn";     //合法引号内的双斜杠

    //Is it a \
     valid comment?                       //合法，上一行以“\”换行。

    in/**/t j;                            //不合法，in t j;

    return 0;
}

2. 注释规则

• 编译器在编译过程中使用空格替换整个注释
• 字符串字面量中的//和/*…*/不代表注释符号
• /*…*/型注释不能被嵌套

3. 有趣的问题

• 你觉得 y=x/*p是什么意思？
• 作者本意：把x除以*p的结果赋值给y
• 编译器：根据贪婪原则，编译器将/*作为一段注释的开始，把/*后的内容都当成注释内容，直到*/为止。
• 改正： y=x / *p，即在/的两侧各加一个空格，以防止/与*结合，编译器误认为注释开始
• 启示：在编译器看来，注释和其它程序元素是平等的。因此，作为工程师，不能轻视注释

4. 失败的注释

4.1 教科书型注释

int main()
{
    r = n / 2;                // r是n的一半
    while ((r - n / r) <= t)  // 循环，仅当r - n/r 不大于t
    {

    }
 
    r = r + n * t;            // 对变量r进行赋值
    n++;                      // 变量n自增1 

    return 0;
}

• 注释用于阐述原因和意图而不是描述程序的运行过程！

4.2 迷惑型的注释

int main()
{
    init();

    //......
    //......

    sad = 0x723;    //R.I.P.L.V.B.

    //......
    //......

    finalize();

    return 0;
}

 

• 本例中，0x723相当于10进制的1827，为纪念贝多芬。Rest In Peace. Ludwig Van Beethoven.（路德维希·凡·贝多芬安息吧！）
• 写注释不是晒心情，必须无二义性，起到对代码进行提示的作用。避免使用缩写。

4.3 忽悠型注释

int main()
{
    //......
    //......

    // Bob 07/24/1995
    /*我知道这个问题很难解决而且现在必须依赖于这个contains函数
     *但我以后会用一种更加直观优雅有意义的方式重写这段代码。
     *现在这么做只是由于时间紧近，但我一定会解决的。
    */

    if (contains(s, "error"))
    {
        exit(1);
    }

    //......
    //......

    return 0;
}

• 注释是对代码的提示，避免臃肿和喧宾夺主。如本例if语句才3行，注释用了5行。

4.4 搞笑型注释

/** 
 *                             _ooOoo_ 
 *                            o8888888o 
 *                            88" . "88 
 *                            (| -_- |) 
 *                            O\  =  /O 
 *                         ____/`---'\____ 
 *                       .'  \\|     |//  `. 
 *                      /  \\|||  :  |||//  \ 
 *                     /  _||||| -:- |||||-  \ 
 *                     |   | \\\  -  /// |   | 
 *                     | \_|  ''\---/''  |   | 
 *                     \  .-\__  `-`  ___/-. / 
 *                   ___`. .'  /--.--\  `. . __ 
 *                ."" '<  `.___\_<|>_/___.'  >'"". 
 *               | | :  `- \`.;`\ _ /`;.`/ - ` : | | 
 *               \  \ `-.   \_ __\ /__ _/   .-` /  / 
 *          ======`-.____`-.___\_____/___.-`____.-'====== 
 *                             `=---=' 
 *          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 
 *                     佛祖保佑        永无BUG 
 *            佛曰: 
 *                   写字楼里写字间，写字间里程序员； 
 *                   程序人员写程序，又拿程序换酒钱。 
 *                   酒醒只在网上坐，酒醉还来网下眠； 
 *                   酒醉酒醒日复日，网上网下年复年。 
 *                   但愿老死电脑间，不愿鞠躬老板前； 
 *                   奔驰宝马贵者趣，公交自行程序员。 
 *                   别人笑我忒疯癫，我笑自己命太贱； 
 *                   不见满街漂亮妹，哪个归得程序员？ 
*/  

• 佛祖是佛学专业的大师，但是没学过编程，因此保佑不了你，你只能靠自己避开bug。

5.小结

• 注释应该精准易懂，防止二义性，错误的注释有害无利
• 注释是对代码的提示，避免臃肿和喧兵夺主
• 一目了然的代码避免加注释
• 不要用缩写来注释代码，这样可能产生误解
• 注释用来阐述原因和意图而不是描述程序的运行机制

6.良好的注释范例

/*
  ========================================================================

  FILE:  Form.c
  
  SERVICES:  

  GENERAL DESCRIPTION: Concrete implementation of RootForm and base IForm
  methods

  ========================================================================
  ========================================================================
    
               Copyright ?1999-2005 QUALCOMM Incorporated 
                     All Rights Reserved.
                   QUALCOMM Proprietary/GTDR
    
  ========================================================================
  ========================================================================
*/


/*==================================================================================
                         XXXXXXX Confidential Proprietary
                   (c) Copyright XXXXXXX - All Rights Reserved

Revision History:
                         Modification
  Author                     Date        CR Number      Major Changes
----------------------   ------------   ------------   ----------------------------
Daniel Rossler            01/18/2007     LIBkk94550    Add check for NULL pointers
                                                       in order to avoid a panic
==================================================================================*/



#include "FormBase.h"

#include "AEESoftkeyWidget.h"
#include "AEEImageWidget.h"
#include "AEEStaticWidget.h"
#include "AEEImageStaticWidget.h"
#include "AEERootContainer.h"
#include "AEEWProperties.h"
#include "AEEVectorModel.h"

#include "AEEWeb.h"

#include "AEERootForm.h"
#include "AEEResFile.h"

#include "FormUtil.h"
#include "AEEDisplayCanvas.h"

#define FORMSTACK_MIN  10
#define FORMSTACK_GROW 2

/
// RootForm

typedef struct RootForm {
   Form              base;

   IRootContainer *  piContainer;
   AEERect           rcContainer;
   AEERect           rcClient;

   IVectorModel *    piForms;
   ModelListener     mlFormActive;
   ModelListener     mlFormTopmostNonPopup;

   IWidget *         piTitle;
   ImageStaticInfo   titleInfo;
   IWidget *         piSoftkeys;
   IWidget *         piBackground;

   IWidget *         piActiveWidget;  

   IResFile *        piThemeFile;
   const char *      themeFile;
} RootForm;

#define DECL(c) c* me = (c *)po

static __inline IForm *ROOTFORM_TO_IFORM(RootForm *me) {
   return (IForm *)me;
}

static __inline Form *ROOTFORM_TO_FORM(RootForm *me) {
   return (Form *)me;
}

static __inline IRootForm *ROOTFORM_TO_IROOTFORM(RootForm *me) {
   return (IRootForm *)me;
}

static void RootForm_FreeFormEntry(IForm *po)
{
   IFORM_Release(po);
}

static void RootForm_UpdateClientArea(RootForm *me)
{
   WidgetPos pos;
   WExtent titleExtent, skExtent;

   if (me->piSoftkeys) {
      IWIDGET_GetExtent(me->piSoftkeys, &skExtent);
 
      // Adjust softkey position based on current height
      IROOTCONTAINER_GetPos(me->piContainer, me->piSoftkeys, &pos);
      pos.y = me->rcContainer.dy - skExtent.height;
      IROOTCONTAINER_SetPos(me->piContainer, me->piSoftkeys, WIDGET_ZNORMAL, &pos);
   } else {
      SETWEXTENT(&skExtent, 0, 0);
   }

   if (me->piTitle) {
      IWIDGET_GetExtent(me->piTitle, &titleExtent);
   } else {
      SETWEXTENT(&titleExtent, 0, 0);
   }
   
   // Calculate client area
   SETAEERECT(&me->rcClient, 0, titleExtent.height,
              me->rcContainer.dx,
              me->rcContainer.dy - skExtent.height - titleExtent.height);
}


static void RootForm_UpdateTheme(RootForm *me, const char *baseName)
{
   WExtent wextent;

   BUIT_LOG("FORMS EVT: Update Theme Started for %s", baseName);

   if (!me->piThemeFile)
      return;

   if (me->piTitle) {
      IWIDGET_SetProperties(me->piTitle, me->piThemeFile, baseName, "Title", "Properties", 0);
      IWIDGET_GetPreferredExtent(me->piTitle, &wextent);
      wextent.width = me->rcContainer.dx;
      IWIDGET_SetExtent(me->piTitle, &wextent);
   }

   if (me->piSoftkeys) {
      IWIDGET_SetProperties(me->piSoftkeys, me->piThemeFile, baseName, "Softkeys", "Properties", 0);
      IWIDGET_GetPreferredExtent(me->piSoftkeys, &wextent);
      wextent.width = me->rcContainer.dx;
      IWIDGET_SetExtent(me->piSoftkeys, &wextent);
   }

   if (me->piBackground) {
      IWIDGET_SetProperties(me->piBackground, me->piThemeFile, baseName, "Background", "Properties", 0);
   }

   // Update client area since sizes may have changed
   RootForm_UpdateClientArea(me);

   BUIT_LOG("FORMS EVT: Update Theme Finished for %s", baseName);
}

// updates the rootform with the background image, softkey and 
// title text of the TOS form.
static void RootForm_Update(RootForm *me, uint32 dwItemMask, IForm* piForm)
{
   boolean bPopup = 0;

   // get form's popup flag
   bPopup = IFORM_GetIsPopup(piForm);

   // if the form's widget has changed, update the scroll model
   // for the scroll indicator in the softkey widget
   if (dwItemMask & FORMITEM_WIDGET) {
      
      IWidget *piWidget = NULL;
      // get form's widget
      IFORM_GetWidget(piForm, WID_FORM, &piWidget);

      // update the widget and the scroll model
      if (piWidget) {

         // if the active widget has been changed underneath us...
         
         if (me->piActiveWidget && piWidget != me->piActiveWidget) {
            // this block will only be executed when the form widget is changed
            // by the application logic while the form is active
            WidgetPos pos;
            WExtent we;
   
            IWIDGET_MoveFocus(FORM_WIDGET(me), (IWidget*)WIDGET_FOCUS_NONE);
   
            IWIDGET_GetExtent(me->piActiveWidget, &we);
            IWIDGET_SetExtent(piWidget, &we);
   
            // remove the previously active widget from the root container
            if (AEE_SUCCESS == IROOTCONTAINER_GetPos(me->piContainer, me->piActiveWidget, &pos)) {
               IROOTCONTAINER_Remove(me->piContainer, me->piActiveWidget);
            }
            
            // add the new widget to the root container
            IROOTCONTAINER_Insert(me->piContainer, piWidget, WIDGET_ZTOPMOST, &pos);
            // and remember it fondly
            RELEASEIF(me->piActiveWidget);
            me->piActiveWidget = piWidget;
            ADDREFIF(piWidget);

            // set focus to the new widget
            IWIDGET_MoveFocus(FORM_WIDGET(me), piWidget);
         
         } else if (!me->piActiveWidget) {
            me->piActiveWidget = piWidget;
            ADDREFIF(piWidget);
         }

      }

      RELEASEIF(piWidget);
   }


   // if the form's background image has changed...
   // if form is a popup, then retain the background image 
   // from the previous form
   if (dwItemMask & FORMITEM_BACKGROUND && me->piBackground && !bPopup) {      
      IImage *pii = NULL;
      
      // Try to grab the image from the new form.  
      IFORM_GetBGImage(piForm, &pii);

      // If non-existent, try defaulting to the root form
      if (!pii) IFORM_GetBGImage(ROOTFORM_TO_IFORM(me), &pii);
      
      // Apply the result (NULL or otherwise) to our background widget
      IWIDGET_SetImage(me->piBackground, pii);
      RELEASEIF(pii);
   }
   
   // if the form's title text has changed...  retain previous title
   // if we are a popup 

   if ((dwItemMask & FORMITEM_TITLE) && me->piTitle && !bPopup) {
      // Release image. Text is owned by form
      RELEASEIF(me->titleInfo.piImage);
      IFORM_GetTextPtr(piForm, FID_TITLE, &me->titleInfo.pwText);
      IFORM_GetTitleImage(piForm, &me->titleInfo.piImage);

      // Set title info
      IWIDGET_SetImageStaticInfo(me->piTitle, &me->titleInfo, 0);
   }

   // if the form's softkey text has changed...
   if ((dwItemMask & FORMITEM_SOFTKEY) && me->piSoftkeys) {

      IForm* piTopForm = IROOTFORM_GetTopForm(ROOTFORM_TO_IROOTFORM(me));

      AECHAR *pwsz = NULL;
      IWidget *piKey = NULL;

      if (piTopForm == piForm) {
         // set softkey 1 text
         IFORM_GetTextPtr(piForm, FID_SOFTKEY1, &pwsz);
         if (AEE_SUCCESS == IWIDGET_GetSoftkey(me->piSoftkeys, PROP_SOFTKEY1, &piKey)) {
            IWIDGET_SetText(piKey, pwsz, 0);
         }
         RELEASEIF(piKey);
   
         // set softkey 2 text
         IFORM_GetTextPtr(piForm, FID_SOFTKEY2, &pwsz);
         if (AEE_SUCCESS == IWIDGET_GetSoftkey(me->piSoftkeys, PROP_SOFTKEY2, &piKey)) {
            IWIDGET_SetText(piKey, pwsz, 0);
         }
      }
      RELEASEIF(piKey);
   }

   if ((dwItemMask & FORMITEM_THEME_BASENAME)) {
      char *baseName = 0;

      IFORM_GetThemeBaseName(piForm, &baseName);
      RootForm_UpdateTheme(me, baseName);
   }

}

static boolean RootForm_ReplaceWidget(RootForm *me, IWidget **piw, IWidget *piwNew, IWidget *piwBefore)
{
   int        result = AEE_SUCCESS;
   WidgetPos  pos;

   if (*piw) {
      (void) IROOTCONTAINER_GetPos(me->piContainer, *piw, &pos);
      (void) IROOTCONTAINER_Remove(me->piContainer, *piw);
      IWIDGET_Release(*piw);
   }

   if (piwNew) {
      result = IROOTCONTAINER_Insert(me->piContainer, piwNew, piwBefore, &pos);
      
      if (result == AEE_SUCCESS) {
         IWIDGET_AddRef(piwNew);
      } else {
         piwNew = NULL;
      }
   }

   *piw = piwNew;

   // Do an update since extents may have changed
   RootForm_UpdateClientArea(me);

   return (AEE_SUCCESS == result);
}

static int RootForm_SetThemeName(RootForm *me, const char *themeFile)
{
   if (!me->piThemeFile)
      return EBADSTATE;
   
   FREEIF(me->themeFile);
   me->themeFile = STRDUP(themeFile);
   
   IRESFILE_Close(me->piThemeFile);
   if (themeFile)
      return IRESFILE_Open(me->piThemeFile, themeFile);
   else
      return AEE_SUCCESS;
}

static int RootForm_SetDisplay(RootForm *me, IDisplay *piDisplay)
{
   int nErr = AEE_SUCCESS;
   IDisplayCanvas *piCanvas = 0;

   nErr = ISHELL_CreateInstance(FORM_SHELL(me), AEECLSID_DISPLAYCANVAS, (void **)&piCanvas);
      
   if (!nErr) {
      WExtent extent;
      WidgetPos pos;
      

      IDISPLAY_SetClipRect(piDisplay, NULL); // reset the clipping rectangle
      IDISPLAY_GetClipRect(piDisplay, &me->rcContainer);
      SETAEERECT(&me->rcClient, 0, 0, me->rcContainer.dx, me->rcContainer.dy);

      IDISPLAYCANVAS_SetDisplay(piCanvas, piDisplay);
      IROOTCONTAINER_SetCanvas(me->piContainer, (ICanvas *)piCanvas, &me->rcContainer);

      if (me->piTitle) {
         // Set extent, title is already positioned at 0, 0
         IWIDGET_GetExtent(me->piTitle, &extent);
         extent.width = me->rcContainer.dx;
         IWIDGET_SetExtent(me->piTitle, &extent);
      }

      if (me->piBackground) {
         // Set extent, background is already positioned at 0, 0
         extent.width = me->rcContainer.dx;
         extent.height = me->rcContainer.dy;
         IWIDGET_SetExtent(me->piBackground, &extent);
      }

      if (me->piSoftkeys) {
         // Set extent
         IWIDGET_GetExtent(me->piSoftkeys, &extent);
         extent.width = me->rcContainer.dx;
         IWIDGET_SetExtent(me->piSoftkeys, &extent);
         // And position at bottom of screen
         IROOTCONTAINER_GetPos(me->piContainer, me->piSoftkeys, &pos);
         pos.y = me->rcContainer.dy - extent.height;
         IROOTCONTAINER_SetPos(me->piContainer, WIDGET_ZNORMAL, me->piSoftkeys, &pos);
      }
   }

   RELEASEIF(piCanvas);

   return nErr;
}


static void RootForm_ApplyTheme(RootForm *me)
{
   int nrForms, i;

   if (!me->piThemeFile) 
      return;
   
   nrForms = IVECTORMODEL_Size(me->piForms);
   for (i = 0; i < nrForms; i++) {
      IForm *piForm;
      char* pTheme = 0;
      IVECTORMODEL_GetAt(me->piForms, i, (void **)&piForm);
      
      IFORM_GetThemeBaseName(ROOTFORM_TO_IFORM(me), &pTheme);
      pTheme = (pTheme) ? pTheme : "(None)";
      
      BUIT_LOG("FORMS EVT: Apply Theme Started for %s", pTheme);
      
      IFORM_ApplyTheme(piForm);
      
      BUIT_LOG("FORMS EVT: Apply Theme Finished for %s", pTheme);
   }

   if (nrForms == 0) {
      char *baseName = 0;
      
      IFORM_GetThemeBaseName(ROOTFORM_TO_IFORM(me), &baseName);
#ifdef FEATURE_MOT_BREW
      if (baseName != NULL) {
          RootForm_UpdateTheme(me, baseName);
      }
#else
      RootForm_UpdateTheme(me, baseName);
#endif /*FEATURE_MOT_BREW*/
   }
}

boolean RootForm_HandleEvent(IRootForm *po, AEEEvent evt, uint16 wParam, uint32 dwParam)
{
   DECL(RootForm);

   if (FORM_WIDGET(me)
      && IWIDGET_HandleEvent(FORM_WIDGET(me), evt, wParam, dwParam))
      return TRUE;

   if (evt == EVT_WDG_GETPROPERTY) {
      switch(wParam) {
      case FID_THEME_FNAME:
         *(const char **)dwParam = me->themeFile;
         return TRUE;

      case FID_THEME_FILE:
         *(IResFile **)dwParam = me->piThemeFile;
         ADDREFIF(me->piThemeFile);
         return TRUE;

      case WID_TITLE:
         *(IWidget **)dwParam = me->piTitle;
         ADDREFIF(me->piTitle);
         return TRUE;

      case WID_SOFTKEYS:
         *(IWidget **)dwParam = me->piSoftkeys;
         ADDREFIF(me->piSoftkeys);
         return TRUE;

      case WID_BACKGROUND:
         *(IWidget **)dwParam = me->piBackground;
         ADDREFIF(me->piBackground);
         return TRUE;

      case WID_FORM:
         IROOTCONTAINER_QueryInterface(me->piContainer, AEEIID_WIDGET, (void **)dwParam);
         return TRUE;

      case WID_CONTAINER:
         *(IContainer **)dwParam = IROOTCONTAINER_TO_ICONTAINER(me->piContainer);
         ADDREFIF(me->piContainer);
         return TRUE;

      default:
         // Fall back on formbase
         return Form_HandleEvent(ROOTFORM_TO_IFORM(me), evt, wParam, dwParam);
      }

   } else if (evt == EVT_WDG_SETPROPERTY) {
      IForm *piForm = 0;

      switch(wParam) {
      case FID_ACTIVE:
         piForm = IROOTFORM_GetTopForm(po);
         if (piForm) {
            // Activate or de-activate the top form
            IFORM_SetProperty(piForm, FID_ACTIVE, dwParam);
         }
         // and invalidate root container on activation
         if ((boolean)dwParam) {
            IROOTCONTAINER_Invalidate(me->piContainer, 0, 0, 0);
         }
         return TRUE;

      case FID_THEME:
         RootForm_ApplyTheme(me);
         return TRUE;

      case FID_THEME_FNAME:
         if (AEE_SUCCESS == RootForm_SetThemeName(me, (const char *)dwParam)) {
            RootForm_ApplyTheme(me);
            return TRUE;
         }
         return FALSE;

      case FID_BACKGROUND:
         // If we have a background widget, set the image into it
         if (me->piBackground) {
            IWIDGET_SetFormImage(me->piBackground, FORM_SHELL(me), (FormRes *)dwParam);
         }
         // Also load the image into our internal form, which will hold it as a default for other forms
         return Form_HandleEvent(ROOTFORM_TO_IFORM(me), evt, wParam, dwParam);

      case FID_DISPLAY:
         return AEE_SUCCESS == RootForm_SetDisplay(me, (IDisplay *)dwParam);

      case FID_WPROPS: {
         WPropDesc *pdesc = (WPropDesc *)dwParam;
         WResPropDesc wd;
                  
         wd.piResFile = me->piThemeFile;
         if (pdesc) {
            wd.args = pdesc->args;
            wd.piWidget = pdesc->piWidget;
         }
         return IWIDGET_SetProperty(pdesc->piWidget, PROP_APPLYWPROPS, (uint32)&wd);
      }

      case WID_TITLE:
         return RootForm_ReplaceWidget(me, &me->piTitle, (IWidget *)dwParam, WIDGET_ZNORMAL);

      case WID_SOFTKEYS:
         return RootForm_ReplaceWidget(me, &me->piSoftkeys, (IWidget *)dwParam, WIDGET_ZNORMAL);

      case WID_BACKGROUND:
         return RootForm_ReplaceWidget(me, &me->piBackground, (IWidget *)dwParam, WIDGET_ZBOTTOMMOST);

      default:
         // Fall back on formbase
         return Form_HandleEvent(ROOTFORM_TO_IFORM(me), evt, wParam, dwParam);
      }
   }

   // Non get/set property events are sent on to the topmost form
   {
      IForm *piForm = IROOTFORM_GetTopForm(po);
      if (!piForm)
         return FALSE;
      else
         return IFORM_HandleEvent(piForm, evt, wParam, dwParam);
   }  
}


static void RootForm_UpdateActiveListenerCB(RootForm *me, FormEvent *pEvent)
{
   if (pEvent->base.evCode == EVT_MDL_FORM_CHANGE) {
      RootForm_Update(me, pEvent->dwItemMask, pEvent->piForm);
   }
}

static void RootForm_UpdateTopmostNonPopupListenerCB(RootForm *me, FormEvent *pEvent)
{
   uint32 dwItemMask = pEvent->dwItemMask & (FORMITEM_BACKGROUND | FORMITEM_TITLE | FORMITEM_SOFTKEY);

   if (pEvent->base.evCode == EVT_MDL_FORM_CHANGE && dwItemMask) {
      RootForm_Update(me, dwItemMask, pEvent->piForm);
   }
}

static void RootForm_ShowFormWidget(IRootForm *po, IForm *piForm, boolean bShow, boolean bFocus)
{
   DECL(RootForm);
   WidgetPos pos;
   IWidget *piWidget;

   if (!piForm)
      return;

   IFORM_GetWidget(piForm, WID_FORM, &piWidget);
   
   if (!piWidget)
      return;

   // Set visibility 
   IROOTCONTAINER_GetPos(me->piContainer, piWidget, &pos);
   pos.bVisible = bShow;
   IROOTCONTAINER_SetPos(me->piContainer, piWidget, WIDGET_ZNORMAL, &pos);

   // and set focus to the widget
   if (bShow && bFocus) {
      IWIDGET_MoveFocus(FORM_WIDGET(me), piWidget);
   } else {
      IWIDGET_MoveFocus(FORM_WIDGET(me), WIDGET_FOCUS_NONE);
   }
   
   IWIDGET_Release(piWidget);
}


/** Activates a given form.  Previous form should have been
 deactivated before this is called with bActivate set
 */
static void RootForm_ActivateForm(IRootForm *po, IForm *piForm, boolean bActivate)
{
   DECL(RootForm);

   if (!piForm)
      return;

   if (bActivate) {
      // Undo the currently known active widget
      RELEASEIF(me->piActiveWidget);
      IFORM_GetWidget(piForm, WID_FORM, &me->piActiveWidget);
      // Then go update all the items except the forms widget as this is not the 
      // form updating its own widget. Need to update first since theme information
      // affect client area which affects form activation
      RootForm_Update(me, FORMITEM_ALL & ~FORMITEM_WIDGET, piForm);
      // then activate
      IFORM_Activate(piForm);
   } else {
      IFORM_Deactivate(piForm);
   }
}

static int RootForm_GetFormIndex(RootForm *me, IForm **ppiForm) 
{
   IForm *piForm;
   int nrForms;

   nrForms = IVECTORMODEL_Size(me->piForms);

   if (nrForms > 0) {

      if (*ppiForm == FORM_LAST || *ppiForm == FORM_DEFAULT) {

         IVECTORMODEL_GetAt(me->piForms, nrForms - 1, (void **)ppiForm);
         return nrForms - 1;

      } else if (*ppiForm == FORM_FIRST) {

         IVECTORMODEL_GetAt(me->piForms, 0, (void **)ppiForm);
         return 0;

      } else {

         int i;
         for (i = 0; i < nrForms; i++) {
            IVECTORMODEL_GetAt(me->piForms, i, (void **)&piForm);
            if (piForm == *ppiForm)
               return i;
         }

      }
   }

   return -1;
}

static __inline int RootForm_GetFormInsertionIndex(RootForm *me, IForm **ppiForm)
{
   int delta;

   if (*ppiForm == FORM_FIRST)
      return 0;

   if (*ppiForm == FORM_LAST || *ppiForm == FORM_DEFAULT) {
      delta = 1;
   } else {
      delta = 0;
   }

   return RootForm_GetFormIndex(me, ppiForm) + delta;
}

static void RootForm_StackChange(IRootForm *po)
{
   DECL(RootForm);
   IForm* piTopForm = IROOTFORM_GetTopForm(po);
   
   LISTENER_Cancel(&me->mlFormActive);
   LISTENER_Cancel(&me->mlFormTopmostNonPopup);

   // If there are still forms on the stack, then we need to set up several things:
   //   1. The topmost form is the active form
   //   2. All other forms are not active
   //   3. The topmost form is being listened to via mlFormActive
   //   4. The topmost non-popup form is being listened to via mlFormTopmostNonPopup
   //   5. The topmost non-popup form and all popup forms on top of it are shown
   //   6. Forms below the topmost non-popup form are now shown
   if (piTopForm)
   {
      boolean bFoundTopmostNonPopup = FALSE;
      IModel* piModel = NULL;
      IForm*  pif;

      // Logging stack change begin
      BUIT_LOG("FORMS EVT: Stack Change Starting...", 1);

      // Need to deal with the non-active forms first, then the active form
      for (pif = piTopForm; pif; pif = IROOTFORM_GetForm(po, pif, FALSE, FALSE))
      {
         boolean bPopup;

         bPopup = IFORM_GetIsPopup(pif);
         IFORM_GetFormModel(pif, &piModel);
         if (piModel)
         {
            if (pif != piTopForm)
            {
               RootForm_ShowFormWidget(po, pif, (boolean)(bFoundTopmostNonPopup? FALSE : TRUE), FALSE);
               if (IFORM_IsActive(pif))
               {
                  RootForm_ActivateForm(po, pif, FALSE);
               }
            }

            if (!bPopup && !bFoundTopmostNonPopup)
            {
               IMODEL_AddListenerEx(piModel, &me->mlFormTopmostNonPopup, (PFNLISTENER)RootForm_UpdateTopmostNonPopupListenerCB, me);
               if (pif != piTopForm)
                  // Only update if not the topmost form since the
                  // Activate below applies theme again The topmost
                  // non-popup (but not the top!) influences the
                  // background, title ans associated themes
                  RootForm_Update(me, FORMITEM_BACKGROUND | FORMITEM_TITLE | FORMITEM_THEME_BASENAME, pif);
               bFoundTopmostNonPopup = TRUE;
            }
         }
         RELEASEIF(piModel);
      }

      RootForm_ActivateForm(po, piTopForm, TRUE);
      RootForm_ShowFormWidget(po, piTopForm, TRUE, TRUE);
      IFORM_GetFormModel(piTopForm, &piModel);
      if (piModel)
         IMODEL_AddListenerEx(piModel, &me->mlFormActive, (PFNLISTENER)RootForm_UpdateActiveListenerCB, me);
      RELEASEIF(piModel);
      
      // Log that the form is about to be activated - all theme stuff has happened by now)
      BUIT_LOG("FORMS EVT: Stack Change Finished", 1);

   }

    // Notify change in stack
   Form_Notify(ROOTFORM_TO_FORM(me), FORMITEM_STACK);
}


int RootForm_InsertForm(IRootForm *po, IForm *piForm, IForm *pifBefore)
{
   DECL(RootForm);
   IWidget *piWidget = 0;
   IWidget *piwBefore = 0;
   IForm *pifCurrent;
   int nrForms, formIndex, nErr;

   if (!piForm)
      return EBADPARM;

   // Make sure we can insert, get the index we want to insert at
   formIndex = RootForm_GetFormInsertionIndex(me, &pifBefore);

   if (formIndex < 0)
      return EBADPARM;

   nrForms = IVECTORMODEL_Size(me->piForms);
   pifCurrent = IROOTFORM_GetTopForm(po);

   // Get widget to insert
   IFORM_GetWidget(piForm, WID_FORM, &piWidget);

   // Get widget insertion point. 
   if (formIndex == nrForms || !nrForms) {
      piwBefore = WIDGET_ZTOPMOST;
   } else if (pifBefore == FORM_FIRST) {
      if (me->piBackground != NULL) {
     
         // If we have a background widget, try to insert the form's widget
         // above the background widget
         piwBefore = IROOTCONTAINER_GetWidget(me->piContainer, me->piBackground, TRUE, FALSE);
         if (piwBefore) {
            // Add a reference, so it can be released below.
            IWIDGET_AddRef(piwBefore);
         }
      } 

      if (!piwBefore) {
         // No background widget, insert the form's widget at the bottom.
         piwBefore = WIDGET_ZBOTTOMMOST;
      }

   } else {
      IFORM_GetWidget(pifBefore, WID_FORM, &piwBefore);
   }

   // Make sure we have space for the new form
   nErr = IVECTORMODEL_EnsureCapacity(me->piForms, MAX(FORMSTACK_MIN, nrForms + 1), FORMSTACK_GROW);

   // Now insert
   if (!nErr && piWidget && piwBefore) {
      WidgetPos pos;

      // Not really needed here since Activate does this to, but since
      // we need to give a position on insert we may as well do it
      // right
      pos.x = me->rcClient.x; 
      pos.y = me->rcClient.y;
      pos.bVisible = (piwBefore == WIDGET_ZTOPMOST);
      
      // Insert widget into widget stack
      nErr = IROOTCONTAINER_Insert(me->piContainer, piWidget, piwBefore, &pos);
   }

   if (!nErr) {
      char* pTheme = 0;

      // Add form to formstack
      IVECTORMODEL_InsertAt(me->piForms, formIndex, piForm);
      IFORM_AddRef(piForm);

      // Set rootform
      IFORM_SetProperty(piForm, FID_ROOT, (uint32)po);

      // Log info
      IFORM_GetThemeBaseName(ROOTFORM_TO_IFORM(me), &pTheme);
      pTheme = (pTheme) ? pTheme : "(None)";

      BUIT_LOG("FORMS EVT: Insert Set Theme Started for %s", pTheme);

      // Set theme on new form
      IFORM_ApplyTheme(piForm);

      BUIT_LOG("FORMS EVT: Insert Set Theme Finished for %s", pTheme);
      //RootForm_Update(me, FORMITEM_THEME, piForm);

      RootForm_StackChange(po);

}

   RELEASEIF(piWidget);
   if (piwBefore != WIDGET_ZTOPMOST && piwBefore != WIDGET_ZBOTTOMMOST)
      RELEASEIF(piwBefore);
   return nErr;
}

int RootForm_RemoveForm(IRootForm *po, IForm *piForm)
{
   DECL(RootForm);
   IWidget *piWidget = 0;
   IForm *piF = 0;
   int nrForms = 0;
   int formIndex;
   boolean bOnlyPopups = 1;

   if (me->piForms)
      nrForms = IVECTORMODEL_Size(me->piForms);

   if (piForm == FORM_ALL) {
      while (nrForms > 0) {
         IROOTFORM_RemoveForm(po, FORM_LAST);
         nrForms = IVECTORMODEL_Size(me->piForms);
      }

   } else {
      formIndex = RootForm_GetFormIndex(me, &piForm);
      
      if (formIndex < 0)
         return EBADPARM;
      
      IFORM_GetWidget(piForm, WID_FORM, &piWidget);
      
      if (piWidget) {
         IROOTCONTAINER_Remove(me->piContainer, piWidget);
      }
      
      // Hide form widget
      RootForm_ShowFormWidget(po, piForm, FALSE, FALSE);
      // Deactivate form
      RootForm_ActivateForm(po, piForm, FALSE);
      // Tell it of rootform departure
      IFORM_SetProperty(piForm, FID_ROOT, 0);
      // Delete it from the stack
      IVECTORMODEL_DeleteAt(me->piForms, formIndex);

      RootForm_StackChange(po);

      RELEASEIF(piWidget);

      // Now many forms do we now have?
      nrForms = IVECTORMODEL_Size(me->piForms);
   }

   // Cycle through remaining forms to determine type
   for (piF = IROOTFORM_GetTopForm(po); piF && bOnlyPopups; piF = IROOTFORM_GetForm(po, piF, FALSE, FALSE))
   {
      bOnlyPopups &= IFORM_GetIsPopup(piF);
   }  


   if ((0 == nrForms) || bOnlyPopups)
   {
      // If we don't have any more forms, or the only forms we do have are popups, 
      // ensure the title has been cleaned (the title memory is owned by the last full screen form, 
      // which may no longer exist).
      if (me->piTitle) {
         // Release image. Text is owned by form
         RELEASEIF(me->titleInfo.piImage);
         me->titleInfo.pwText = NULL;

         // Set title info
         IWIDGET_SetImageStaticInfo(me->piTitle, &me->titleInfo, 0);
      }
   }

   if (0 == nrForms) {
      
      // There are no more forms, ensure the softkey labels
      // have been cleaned (the softkey memory is owned by the form, which may no 
      // longer exist).
      if (me->piSoftkeys) {
         IWidget *piKey = NULL;

         (void) IWIDGET_GetSoftkey(me->piSoftkeys, PROP_SOFTKEY1, &piKey);
         if (piKey) {
            IWIDGET_SetText(piKey, NULL, 0);
            IWIDGET_Release(piKey);
            piKey = NULL;
         }

         (void) IWIDGET_GetSoftkey(me->piSoftkeys, PROP_SOFTKEY2, &piKey);
         if (piKey) {
            IWIDGET_SetText(piKey, NULL, 0);
            IWIDGET_Release(piKey);
            piKey = NULL;
         }

      }
   } else {
      RootForm_Update(me, FORMITEM_THEME_BASENAME, IROOTFORM_GetTopForm(po));
   }

   return AEE_SUCCESS;
}


void RootForm_GetClientRect(IRootForm *po, IXYContainer **ppo, AEERect *rc)
{
   DECL(RootForm);

   if (rc) {
      *rc = me->rcClient;
   }

   if (ppo && me->piContainer) {
      *ppo = IROOTCONTAINER_TO_IXYCONTAINER(me->piContainer);
      IROOTCONTAINER_AddRef(me->piContainer);
   }
}

IForm *RootForm_GetForm(IRootForm *po, IForm *pifRef, boolean bNext, boolean bWrap)
{
   DECL(RootForm);
   IForm *piForm = 0;
   int nrForms, formIndex;
   
   if (me->piForms == NULL)
      return NULL;

   nrForms = IVECTORMODEL_Size(me->piForms);

   if (pifRef == NULL) {
      formIndex = bNext ? 0 : nrForms - 1;
      IVECTORMODEL_GetAt(me->piForms, formIndex, (void **)&piForm);
      return piForm;
   }

   formIndex = RootForm_GetFormIndex(me, &pifRef);

   if (formIndex < 0)
      return NULL;

   formIndex += bNext ? 1 : -1;
   if (formIndex < 0) {
      formIndex = bWrap ? nrForms - 1 : -1;
   } else if (formIndex >= nrForms) {
      formIndex = bWrap ? 0 : - 1;
   }
   
   if (formIndex < 0)
      return NULL;

   IVECTORMODEL_GetAt(me->piForms, formIndex, (void **)&piForm);
   return piForm;
}

int RootForm_ResolveForm(IRootForm *po, char const *szFormUrl, IForm **ppiForm)
{
   DECL(RootForm);
   IWebUtil *piWebUtil = 0;
   AEECLSID formClsId;
   int result;
   UrlParts parts;
   char *path = 0;

   if (!ppiForm || !szFormUrl)
      return EBADPARM;

   // Assume failure
   *ppiForm = 0;

   // Parse the URL
   result = ISHELL_CreateInstance(FORM_SHELL(me), AEECLSID_WEBUTIL, (void **) &piWebUtil);

   if (result == 0) 
      result = IWEBUTIL_ParseUrl(piWebUtil, szFormUrl, &parts);

      // Check the scheme
   if (result == 0
       && (!UP_HASSCHM(&parts) || STRNCMP(parts.cpcSchm,FORM_URL_SCHEME,sizeof(FORM_URL_SCHEME)-1)))
       result = ESCHEMENOTSUPPORTED;

      // Do we have a path?
   if (result == 0
       && (!UP_HASPATH(&parts) || UP_PATHLEN(&parts) <= 0))
      result = ESCHEMENOTSUPPORTED;

   // Extract the path (we need it to be NULL terminated)
   if (result == 0 
       && 0 == (path = MALLOC(UP_PATHLEN(&parts)+1)))
      result = ENOMEMORY;

   if (result == 0) {
      STRNCPY(path, parts.cpcHost, UP_PATHLEN(&parts)+1);

      // Does a handler exist for this path, of type AEEIID_FORM?
      if (0 == (formClsId = ISHELL_GetHandler(FORM_SHELL(me), AEEIID_FORM, path)))
         // Nope...
         result = ESCHEMENOTSUPPORTED;
   }

   if (result == 0)
      // Got the actual class id, lets create the form
      result = ISHELL_CreateInstance(FORM_SHELL(me), formClsId, (void **) ppiForm);

   //
   // TODO: We could use IWEBUTIL_ParseFormFields() to parse parts.cpcSrch 
   //       for known Form properties and apply them here...

   RELEASEIF(piWebUtil);
   FREEIF(path);

   return result;
}

void RootForm_Dtor(RootForm *me)
{
   IROOTFORM_RemoveForm(ROOTFORM_TO_IROOTFORM(me), FORM_ALL);

   RELEASEIF(me->piTitle);
   RELEASEIF(me->piSoftkeys);
   RELEASEIF(me->piContainer);
   RELEASEIF(me->piBackground);
   RELEASEIF(me->titleInfo.piImage);
   RELEASEIF(me->piForms);
   RELEASEIF(me->piActiveWidget);
   RELEASEIF(me->piThemeFile);
   FREEIF(me->themeFile);

   Form_Dtor(&me->base);  
}

uint32 RootForm_Release(IRootForm *po)
{
   DECL(RootForm);
   
   if (FORM_NREFS(me) == 1)
      RootForm_Dtor(me);

   return Form_Release(IROOTFORM_TO_IFORM(po));
}

int RootForm_QueryInterface(IRootForm *po, AEECLSID clsid, void **ppo)
{
   if (clsid == AEEIID_ROOTFORM) {
      *ppo = po;
      Form_AddRef(IROOTFORM_TO_IFORM(po));
      return AEE_SUCCESS;
   }

   return Form_QueryInterface(IROOTFORM_TO_IFORM(po), clsid, ppo);
}

int RootForm_Construct(RootForm *me, AEEVTBL(IRootForm) *pvt, IModule *piModule, IShell *piShell)
{
   int result;
   WExtent extent;
   WidgetPos pos;
   IDisplay *piDisplay = 0;
   ICanvas *piCanvas = 0;

   Form_Ctor(&me->base, (AEEVTBL(IForm) *)pvt, piModule, piShell, 
             (PFNHANDLER)RootForm_HandleEvent);

   pos.x = 0;
   pos.y = 0;
   pos.bVisible = TRUE;
   SETWEXTENT(&extent, 0, 0);

   // Form overrides
   pvt->Release         = RootForm_Release;
   pvt->QueryInterface  = RootForm_QueryInterface;
   // RootForm definitions
   pvt->InsertForm      = RootForm_InsertForm;
   pvt->RemoveForm      = RootForm_RemoveForm;
   pvt->GetClientRect   = RootForm_GetClientRect;
   pvt->GetForm         = RootForm_GetForm;
   pvt->ResolveForm     = RootForm_ResolveForm;

   result = ISHELL_CreateInstance(piShell, AEECLSID_VECTORMODEL, (void **)&me->piForms);

   if (result == 0) {
      IVECTORMODEL_SetPfnFree(me->piForms, (PFNNOTIFY)RootForm_FreeFormEntry);

      result = ISHELL_CreateInstance(piShell, AEECLSID_DISPLAY, (void **)&piDisplay);
   }

   if (result == 0)
      result = ISHELL_CreateInstance(piShell, AEECLSID_ROOTCONTAINER, (void **)&me->piContainer);

   if (result == 0)
      result = IROOTCONTAINER_QueryInterface(me->piContainer, AEEIID_WIDGET, (void **)&me->base.piWidget);

   if (result == 0)
      result = ISHELL_CreateInstance(piShell, AEECLSID_RESFILE, (void **)&me->piThemeFile);

   if (result == 0)
      result = ISHELL_CreateInstance(piShell, AEECLSID_IMAGEWIDGET, (void **)&me->piBackground);

   if (result == 0) {
      IWIDGET_SetFlags(me->piBackground, IDF_ALIGN_RIGHT | IDF_ALIGN_BOTTOM);

      // Insert, extent will be fixed up in SetDisplay below
      result = IROOTCONTAINER_Insert(me->piContainer, me->piBackground, WIDGET_ZBOTTOMMOST, &pos);
   }

   if (result == 0)
      // Construct title
      result = ISHELL_CreateInstance(piShell, AEECLSID_IMAGESTATICWIDGET, (void **)&me->piTitle);

   if (result == 0) {
      extent.height = 15;
      // Set title font to bold by default.  Apps and themes can override it.
      IWIDGET_SetFontClass(me->piTitle, AEECLSID_FONTSYSBOLD);

      IWIDGET_SetShadowOffsetY(me->piTitle, 0);
      IWIDGET_SetBorderWidth(me->piTitle, 0);
      IWIDGET_SetExtent(me->piTitle, &extent);
      // Add to container
      result = IROOTCONTAINER_Insert(me->piContainer, me->piTitle, WIDGET_ZTOPMOST, &pos);
   }

   if (result == 0)
      // Construct Softkeys
      result = ISHELL_CreateInstance(piShell, AEECLSID_SOFTKEYWIDGET, (void **)&me->piSoftkeys);

   if (result == 0) {
      IWIDGET_SetShadowOffsetY(me->piSoftkeys, -1);
      IWIDGET_SetBorderWidth(me->piSoftkeys, 0);
      IWIDGET_SetExtent(me->piSoftkeys, &extent);
      IWIDGET_SetLeftPadding(me->piSoftkeys, 2);
      IWIDGET_SetRightPadding(me->piSoftkeys, 2);

      // Insert at 0, 0. Correct positioning will happen in SetDisplay
      result = IROOTCONTAINER_Insert(me->piContainer, me->piSoftkeys, WIDGET_ZTOPMOST, &pos);
   }

   if (result == 0)
      result = RootForm_SetDisplay(me, piDisplay);

   if (result == 0) {   
      char* pTheme = 0;
      IFORM_SetThemeBaseName(ROOTFORM_TO_IFORM(me), "Root");

      IFORM_GetThemeBaseName(ROOTFORM_TO_IFORM(me), &pTheme);
      pTheme = (pTheme) ? pTheme : "(None)";

      BUIT_LOG("FORMS EVT: Construct Set Theme Started for %s", pTheme);

      IROOTFORM_SetThemeFileName(ROOTFORM_TO_IROOTFORM(me), "theme.bar");

      BUIT_LOG("FORMS EVT: Construct Set Theme Finished for %s", pTheme);

   } else {
      RootForm_Dtor(me);
   }

   RELEASEIF(piDisplay);
   RELEASEIF(piCanvas);
   
   return result;
}


int RootForm_New(IRootForm **ppo, IModule *piModule, IShell *piShell)
{
   RootForm *me = MALLOCREC_VTBL(RootForm, IRootForm);
   int result;

   *ppo = (IRootForm *)me;

   if (!me)
      return ENOMEMORY;

   result = RootForm_Construct(me, GETVTBL(me, IRootForm), piModule, piShell);
   
   if (result != 0) {
      *ppo = NULL;
      FREE(me);
   }
   
   return result;
}