1. 似是而非的问题
（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. 注释规则
（1）编译器在编译过程中使用空格替换整个注释
（2）字符串字面量中的//和/*…*/不代表注释符号
（3）/*…*/型注释不能被嵌套
3. 有趣的问题
（1）你觉得 y=x/*p是什么意思？
作者本意：把x除以*p的结果赋值给y
编译器：根据贪婪原则，编译器将/*作为一段注释的开始，把/*后的内容都当成注释内容，直到*/为止。
改正： y=x / *p，即在/的两侧各加一个空格，以防止/与*结合，编译器误认为注释开始
启示：在编译器看来，注释和其它程序元素是平等的。因此，作为工程师，不能轻视注释
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; }
▲注释用于阐述原因和意图而不是描述程序的运行过程！
（2）迷惑型的注释
int main() { init(); //...... //...... sad = 0x723; //R.I.P.L.V.B. //...... //...... finalize(); return 0; }
本例中，0x723相当于10进制的1827，为纪念贝多芬。Rest In Peace. Ludwig Van Beethoven.（路德维希·凡·贝多芬安息吧！）
▲写注释不是晒心情，必须无二义性，起到对代码进行提示的作用。避免使用缩写。
（3）忽悠型注释
int main() { //...... //...... //Bob 07/24/1995 /*我知道这个问题很难解决而且现在必须依赖于这个contains函数 *但我以后会用一种更加直观优雅有意义的方式重写这段代码。 *现在这么做只是由于时间紧近，但我一定会解决的。 */ if (contains(s, "error")) { exit(1); } //...... //...... return 0; }
▲注释是对代码的提示，避免臃肿和喧宾夺主。如本例if语句才3行，注释用了5行。
（4）搞笑型注释
佛祖是佛学专业的大师，但是没学过编程，因此保佑不了你，你只能靠自己避开bug。
5. 小结
（1）注释应该准确易懂，防止二义性，错误的注释有害无利
（2）注释是对代码的提示，避免臃肿和喧宾夺主。
（3）一目了然的代码避免加注释
（4）不要用缩写来注释代码，这样可能会产生误解
（5）注释用于阐述原因和意图，而不是描述程序的运行过程。
【良好的注释范例】
/* ======================================================================== 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; }