c8-注释符号的重要性

 注释符号：

#include <stdio.h>

int main()
{
	int/*...*/i;
	char* s = "abcdefgh      //hijklmn";

	//Is it a \
	    valid comment?

	in/*...*/t i;   //是错误的

	return 0;
}

漂亮的程序注释：

1. 注释应该准确易懂，防止二义性，避免臃肿。注释是对代码的提示
2. 注释用于阐述原因而不是用于描述程序的运行过程

【告诉读者：文件名，普通描述，版权，历史版本】
/*
  ========================================================================

  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_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);
}