added doc++ comments

layout/html/forms/public/nsIFormControl.h

@@ -25,22 +25,63 @@ class nsIFormManager;
 { 0x282ff440, 0xcd7e, 0x11d1, \
   {0x89, 0xad, 0x00, 0x60, 0x08, 0x91, 0x1b, 0x81} }
 
+/**
+  * Interface which all form controls (e.g. buttons, checkboxes, text,
+  * radio buttons, select, etc) implement. 
+ **/
 class nsIFormControl : public nsISupports {
 public:
-  virtual PRBool GetName(nsString& aResult) = 0;
+  /**
+    * Get the form manager which manages this control.
+    * @return the form manager
+    */
+  virtual nsIFormManager* GetFormManager() const = 0;
 
+  /**
+    * Get the max number of values that this control can have; the actual
+    * number of values may be less.
+    * @return the max number of values
+    */
   virtual PRInt32 GetMaxNumValues() = 0;
 
+  /**
+    * Get the name of this control. Controls without names will not have any
+    * data submitted.
+    * @param aResult the nsString which will be set to the name (out parm)
+    * @return PR_TRUE if there was a name, PR_FALSE otherwise 
+    */
+  virtual PRBool GetName(nsString& aResult) = 0;
+
+  /**
+    * Get the number of references to this control by other objects.
+    * @return the ref count
+    */
+  virtual nsrefcnt GetRefCount() const = 0;
+
+  /**
+    * Get the vaules which this control could submit.
+    * @param aMaxNumValues the maximum number of values to set (in parm)
+    * @param aNumValues the actual number of values set (out parm)
+    * @param aValues an array of nsString which contains the values (out parm
+    * that is allocated by the caller)
+    * @return PR_TRUE if any values were set, PR_FALSE otherwise
+    */
   virtual PRBool GetValues(PRInt32 aMaxNumValues, PRInt32& aNumValues,
                            nsString* aValues) = 0;
 
+  /**
+    * Set this control back to its initial value
+    */
   virtual void Reset() = 0;
 
-  virtual nsIFormManager* GetFormManager() const = 0;
-
+  /**
+    * Set the form manager for this control
+    * @param aFormMan the new form manager
+    * @param aDecrementRef if PR_TRUE, decrement the ref count to the existing
+    * form manager. This facilitates handling circular references.
+    */
   virtual void SetFormManager(nsIFormManager* aFormMan, PRBool aDecrementRef = PR_TRUE) = 0;
 
-  virtual nsrefcnt GetRefCount() const = 0;
 };
 
 #endif /* nsIFormControl_h___ */

layout/html/forms/public/nsIFormManager.h

@@ -27,43 +27,95 @@ class nsIFormControl;
   { 0x80, 0x2d, 0x0, 0x60, 0x8, 0x15, 0xa7, 0x91 } }
 
 /** 
- * Abstract form manager interface. Form managers are responsible for
- * the management of form controls. This includes gathering of data
- * for form submission; resetting form controls to their initial state
- * and other programmatic control during form processing.
- */
+  * Abstract form manager interface. Form managers are responsible for
+  * the management of form controls. This includes gathering of data
+  * for form submission, resetting form controls to their initial state,
+  * and other programmatic control during form processing.
+ **/
 class nsIFormManager : public nsISupports {
 public:
-  // callback for reset button controls. 
+  // Event methods
+
+  /**
+    * Reset the values of all of this manager's controls back to their
+    * initial values. This is in response to a reset button being pushed.
+    */
   virtual void OnReset() = 0;
 
-  // callback for text and textarea controls. If there is a single
-  // text/textarea and a return is entered, then this is equavalent to
-  // a submit.
+  /** 
+    * If there is a single text form control, this is identical to OnReset,
+    * otherwise do nothing. This in response to a carriage return being
+    * entered within a text control.
+    */
   virtual void OnReturn() = 0;
 
-  // callback for submit button controls.
+  /**
+    * Submit the values of this manager's controls depending on its action,
+    * method attributes. This in response to a submit button being clicked.
+    */
   virtual void OnSubmit() = 0;
 
-  // callback for tabs on controls that can gain focus. This will
-  // eventually need to be handled at the document level to support
-  // the tabindex attribute.
+  /**
+    * This is tbd and is in repsonse to a tab key being entered in one
+    * of the controls.
+    */
   virtual void OnTab() = 0;
 
-  virtual PRInt32 GetFormControlCount() const = 0;
-
-  virtual nsIFormControl* GetFormControlAt(PRInt32 aIndex) const = 0;
+  // methods accessing controls
 
+  /**
+    * Add a control to end of this manager's list of controls
+    * @param aFormControl the control to add
+    * @return PR_TRUE if the control was successfully added 
+    */
   virtual PRBool AddFormControl(nsIFormControl* aFormControl) = 0;
 
+  /**
+    * Get the number of controls that this manager has in its list
+    * @return the number of controls
+    */
+  virtual PRInt32 GetFormControlCount() const = 0;
+
+  /**
+    * Get the control at a specific position in this manager's list
+    * @param aIndex the position at which to get
+    * @return the control at that position
+    */
+  virtual nsIFormControl* GetFormControlAt(PRInt32 aIndex) const = 0;
+
+  /**
+    * Remove a control from this manager's list
+    * @param aFormControl thc control to remove
+    * @param aChildIsRef if PR_TRUE, the controls ref count will be decremented
+    * otherwise not. This is to facilitate circular references.
+    * @return PR_TRUE if the control was successfully removed.
+    */
   virtual PRBool RemoveFormControl(nsIFormControl* aFormControl, 
                                    PRBool aChildIsRef = PR_TRUE) = 0;
 
-  virtual void SetAttribute(const nsString& aName, const nsString& aValue) = 0;
+  // methods accessing attributes
 
+  /**
+    * Get the named attribute of this manager
+    * @param aName the name of the attribute
+    * @param aResult the value of the attribute 
+    * @return PR_TRUE if there is an attribute with name aName
+    */
   virtual PRBool GetAttribute(const nsString& aName,
                               nsString& aResult) const = 0;
+  /**
+    * Set the named attribute of this manager
+    * @param aName the name of the attribute
+    * @param aValue the value of the attribute
+    */
+  virtual void SetAttribute(const nsString& aName, const nsString& aValue) = 0;
 
+  // misc methods
+
+  /**
+    * Get the number of references to this form manager by other objects.
+    * @return the ref count
+    */
   virtual nsrefcnt GetRefCount() const = 0;
 };
 

layout/html/forms/src/nsFormElement.cpp

@@ -24,6 +24,8 @@
 #include "nsCSSRendering.h"
 #include "nsHTMLIIDs.h"
 
+// this file is obsolete and will be removed
+
 static NS_DEFINE_IID(kStyleMoleculeSID, NS_STYLEMOLECULE_SID);
 
 enum FormElementType {

layout/html/forms/src/nsHTMLForms.h

@@ -24,46 +24,97 @@ class nsIFormManager;
 
 // Form and Form Controls
 
+/** 
+  * Construct an object implementing nsIFormManager 
+  * @param aInstancePtrResult the address at which to place the
+  * address of the new instance.
+  * @param aTag the html tag which corresponds to the nsIFormManager
+  * @return NS_OK if the object was successfully constructed. 
+  */
 extern nsresult
 NS_NewHTMLForm(nsIFormManager** aInstancePtrResult,
                nsIAtom* aTag);
 
+/** 
+  * Construct an object with behavior of an html input button
+  * @param aInstancePtrResult the address at which to place the
+  * address of the new instance.
+  * @param aTag the html tag which corresponds to the nsIFormManager
+  * @param aManager the form manager which will manage the constructed object
+  * @return NS_OK if the object was successfully constructed. 
+  */
 extern nsresult
 NS_NewHTMLInputButton(nsIHTMLContent** aInstancePtrResult,
                       nsIAtom* aTag, nsIFormManager* aManager);
 
+/** 
+  * Construct an nsIHTMLContent with behavior of an html reset button
+  * @see NS_NewHTMLInputButton for parameter and return values
+  */
 extern nsresult
 NS_NewHTMLInputReset(nsIHTMLContent** aInstancePtrResult,
                      nsIAtom* aTag, nsIFormManager* aManager);
 
+/** 
+  * Construct an nsIHTMLContent with behavior of an html submit button
+  * @see NS_NewHTMLInputButton for parameter and return values
+  */
 extern nsresult
 NS_NewHTMLInputSubmit(nsIHTMLContent** aInstancePtrResult,
                       nsIAtom* aTag, nsIFormManager* aManager);
 
+/** 
+  * Construct an nsIHTMLContent with behavior of an html checkbox 
+  * @see NS_NewHTMLInputButton for parameter and return values
+  */
 extern nsresult
 NS_NewHTMLInputCheckbox(nsIHTMLContent** aInstancePtrResult,
                         nsIAtom* aTag, nsIFormManager* aManager);
 
+/** 
+  * Construct an nsIHTMLContent with behavior of an html input file
+  * @see NS_NewHTMLInputButton for parameter and return values
+  */
 extern nsresult
 NS_NewHTMLInputFile(nsIHTMLContent** aInstancePtrResult,
                     nsIAtom* aTag, nsIFormManager* aManager);
 
+/** 
+  * Construct an nsIHTMLContent with behavior of an html input hidden
+  * @see NS_NewHTMLInputButton for parameter and return values
+  */
 extern nsresult
 NS_NewHTMLInputHidden(nsIHTMLContent** aInstancePtrResult,
                       nsIAtom* aTag, nsIFormManager* aManager);
 
+/** 
+  * Construct an nsIHTMLContent with behavior of an html input image
+  * @see NS_NewHTMLInputButton for parameter and return values
+  */
 extern nsresult
 NS_NewHTMLInputImage(nsIHTMLContent** aInstancePtrResult,
                      nsIAtom* aTag, nsIFormManager* aManager);
 
+/** 
+  * Construct an nsIHTMLContent with behavior of an html input password
+  * @see NS_NewHTMLInputButton for parameter and return values
+  */
 extern nsresult
 NS_NewHTMLInputPassword(nsIHTMLContent** aInstancePtrResult,
                         nsIAtom* aTag, nsIFormManager* aManager);
 
+/** 
+  * Construct an nsIHTMLContent with behavior of an html input radio
+  * @see NS_NewHTMLInputButton for parameter and return values
+  */
 extern nsresult
 NS_NewHTMLInputRadio(nsIHTMLContent** aInstancePtrResult,
                      nsIAtom* aTag, nsIFormManager* aManager);
 
+/** 
+  * Construct an nsIHTMLContent with behavior of an html input text
+  * @see NS_NewHTMLInputButton for parameter and return values
+  */
 extern nsresult
 NS_NewHTMLInputText(nsIHTMLContent** aInstancePtrResult,
                     nsIAtom* aTag, nsIFormManager* aManager);

layout/html/forms/src/nsInput.h

@@ -27,48 +27,115 @@ class nsIView;
 class nsString;
 
 /**
- * nsInput represents an html Input element. This is a base class for
- * the various Input types (button, checkbox, file, hidden, password,
- * reset, radio, submit, text)
- */
+  * nsInput represents an html Input element. This is a base class for
+  * the various Input types (button, checkbox, file, hidden, password,
+  * reset, radio, submit, text)
+  */
 class nsInput : public nsHTMLTagContent {
 public:
+  /** 
+    * main constructor
+    * @param aTag the html tag associated with this object
+    * @param aManager the form manager to manage this input
+    */
   nsInput(nsIAtom* aTag, nsIFormManager* aManager);
 
+  /**
+    * @see nsISupports QueryInterface
+    */
   NS_IMETHOD QueryInterface(REFNSIID aIID, void** aInstancePtr);
 
+  /**
+    * @see nsISupports Release
+    */
   NS_IMETHOD_(nsrefcnt) Release(void);
 
+  /**
+    * @see nsIContentDelegate CreateFrame
+    */
   virtual nsIFrame* CreateFrame(nsIPresContext* aPresContext,
                                 PRInt32 aIndexInParent,
                                 nsIFrame* aParentFrame);
 
-  virtual void SetAttribute(nsIAtom* aAttribute, const nsString& aValue);
+  // nsIFormControl methods
 
+  /**
+    * @see nsIFormControl GetFormManager
+    */
+  virtual nsIFormManager* GetFormManager() const;
+
+  /**
+    * @see nsIFormControl GetFormManager
+    */
+  virtual PRInt32 GetMaxNumValues();
+
+  /**
+    * @see nsIFormControl GetFormManager
+    */
+  virtual PRBool GetName(nsString& aName);
+
+  /**
+    * @see nsIFormControl GetFormManager
+    */
+  virtual PRBool GetValues(PRInt32 aMaxNumValues, PRInt32& aNumValues,
+                           nsString* aValues);
+
+  /**
+    * @see nsIFormControl GetFormManager
+    */
+  virtual void Reset();
+
+  /**
+    * @see nsIFormControl GetFormManager
+    */
+  virtual void SetFormManager(nsIFormManager* aFormMan, PRBool aDecrementRef = PR_TRUE);
+
+  // attribute methods
+
+  /**
+    * Get a named attribute of this input
+    * @param aAttribute the name of the attribute
+    * @param aValue the value of the attribute
+    * @return eContentAttr_HasValue if there is a value, eContentAttr_NoValue
+    * if there is an attribute but no value, or eContentAttr_HasValue
+    * if there is no attribute.
+    */
   virtual nsContentAttr GetAttribute(nsIAtom* aAttribute,
                                      nsHTMLValue& aValue) const;
 
-  // nsIFormControl
-  virtual PRBool GetName(nsString& aName);
-  virtual PRInt32 GetMaxNumValues();
-  virtual PRBool GetValues(PRInt32 aMaxNumValues, PRInt32& aNumValues,
-                           nsString* aValues);
-  virtual void Reset();
-  virtual void SetFormManager(nsIFormManager* aFormMan, PRBool aDecrementRef = PR_TRUE);
-  virtual nsIFormManager* GetFormManager() const;
+  /**
+    * Set the named attribute of this input
+    * @param aAttribute the name of the attribute
+    * @param aValue the value of the attribute
+    */
+  virtual void SetAttribute(nsIAtom* aAttribute, const nsString& aValue);
 
-  static nsIView* GetAncestorWithWindow(nsIView* aView);
-  
-  void SetWidget(nsIWidget* aWidget);
 
+  // misc methods
+
+  /**
+    * Get the number of references to this input
+    * @return the number of references
+   **/
+  virtual nsrefcnt GetRefCount() const;
+
+  /**
+    * Get the widget associated with this input
+    * @return the widget, not a copy
+   **/
   nsIWidget* GetWidget();
 
+  /**
+    * Set the widget associated with this input
+    * @param aWidget the widget
+   **/
+  void SetWidget(nsIWidget* aWidget);
+
+  // this should not be public
   static PRInt32 GetOuterOffset() {
     return offsetof(nsInput,mControl);
   }
 
-  virtual nsrefcnt GetRefCount() const;
-
 protected:
   virtual         ~nsInput();
 

layout/html/forms/src/nsInputFile.h

@@ -23,6 +23,8 @@
 class nsIAtom;
 class nsString;
 
+// this class definition will move to nsInputFile.cpp
+
 class nsInputFile : public nsInput {
 public:
   nsInputFile (nsIAtom* aTag, nsIFormManager* aManager);

layout/html/forms/src/nsInputFrame.h

@@ -19,18 +19,16 @@
 #ifndef nsInputFrame_h___
 #define nsInputFrame_h___
 
-//#include "nsHTMLParts.h"
 #include "nsHTMLTagContent.h"
 #include "nsISupports.h"
 #include "nsIWidget.h"
-class nsIView;
-//#include "nsIRenderingContext.h"
-//#include "nsIPresContext.h"
-//#include "nsIStyleContext.h"
 #include "nsLeafFrame.h"
-//#include "nsCSSRendering.h"
-//#include "nsHTMLIIDs.h"
 
+class nsIView;
+
+/**
+  * Enumeration of possible mouse states used to detect mouse clicks
+  */
 enum nsMouseState {
   eMouseNone,
   eMouseEnter,
@@ -38,45 +36,109 @@ enum nsMouseState {
   eMouseUp
 };
 
+/** 
+  * nsInputFrame is the base class for frames of form controls. It
+  * provides a uniform way of creating widgets, resizing, and painting.
+  * @see nsLeafFrame and its base classes for more info
+  */
 class nsInputFrame : public nsLeafFrame {
 public:
+  /**
+    * Main constructor
+    * @param aContent the content representing this frame
+    * @param aIndexInParent the position in the parent frame's children which this frame occupies
+    * @param aParentFrame the parent frame
+    */
   nsInputFrame(nsIContent* aContent,
                PRInt32 aIndexInParent,
                nsIFrame* aParentFrame);
 
+  // nsLeafFrame overrides
+
+  /** 
+    * Respond to a gui event
+    * @see nsIFrame::HandleEvent
+    */
+  virtual nsEventStatus HandleEvent(nsIPresContext& aPresContext, 
+                                    nsGUIEvent* aEvent);
+  /**
+    * Draw this frame within the context of a presentation context and rendering context
+    * @see nsIFrame::Paint
+    */
   virtual void Paint(nsIPresContext& aPresContext,
                      nsIRenderingContext& aRenderingContext,
                      const nsRect& aDirtyRect);
 
+  /**
+    * Respond to the request to resize and/or reflow
+    * @see nsIFrame::ResizeReflow
+    */
   virtual ReflowStatus  ResizeReflow(nsIPresContext*  aCX,
                                      nsReflowMetrics& aDesiredSize,
                                      const nsSize&    aMaxSize,
                                      nsSize*          aMaxElementSize);
 
-  virtual const nsIID GetCID(); // make this pure virtual
+  // New Behavior
 
-  virtual const nsIID GetIID(); // make this pure virtual
+  /**
+    * Get the class id of the widget associated with this frame
+    * @return the class id
+    */
+  virtual const nsIID GetCID(); 
 
+  /**
+    * Get the interface id of widget associated with this frame
+    * @return the interface id
+    */
+  virtual const nsIID GetIID(); 
+
+  /**
+    * Get the widget associated with this frame
+    * @param aView the view associated with the frame. It is a convience parm.
+    * @param aWidget the address of address of where the widget will be placed.
+    * This method doses an AddRef on the widget.
+    */
   virtual nsresult GetWidget(nsIView* aView, nsIWidget** aWidget);
 
-  virtual void InitializeWidget(nsIView *aView) = 0;  // initialize widget in ResizeReflow
-
-  virtual void PreInitializeWidget(nsIPresContext* aPresContext, 
-	                               nsSize& aBounds); // make this pure virtual
-
-  virtual nsEventStatus HandleEvent(nsIPresContext& aPresContext, 
-                             nsGUIEvent* aEvent);
+  /**
+    * Perform opertations after the widget associated with this frame has been
+    * fully constructed.
+    */
+  virtual void InitializeWidget(nsIView *aView) = 0;  
 
+  /**
+    * Respond to a mouse click (e.g. mouse enter, mouse down, mouse up)
+    */
   virtual void MouseClicked() {}
 
+  /**
+    * Perform operations before the widget associated with this frame has been
+    * constructed.
+    * @param aPresContext the presentation context
+    * @param aBounds the bounds of this frame. It will be set by this method.
+    */
+  virtual void PreInitializeWidget(nsIPresContext* aPresContext, 
+	                                 nsSize& aBounds); 
+
 protected:
+
   virtual ~nsInputFrame();
+
+  /**
+    * Get the size that this frame would occupy without any constraints
+    * @param aPresContext the presentation context
+    * @param aDesiredSize the size desired by this frame, to be set by this method
+    * @param aMaxSize the maximum size available for this frame
+    */
   virtual void GetDesiredSize(nsIPresContext* aPresContext,
                               nsReflowMetrics& aDesiredSize,
                               const nsSize& aMaxSize);
+  /**
+    * Return PR_TRUE if the bounds of this frame have been set
+    */
   PRBool BoundsAreSet();
 
-  nsSize   mCacheBounds;
+  nsSize       mCacheBounds;
   nsMouseState mLastMouseState;
 };
 

layout/html/forms/src/nsInputHidden.h

@@ -1,50 +0,0 @@
-/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
- *
- * The contents of this file are subject to the Netscape Public License
- * Version 1.0 (the "NPL"); you may not use this file except in
- * compliance with the NPL.  You may obtain a copy of the NPL at
- * http://www.mozilla.org/NPL/
- *
- * Software distributed under the NPL is distributed on an "AS IS" basis,
- * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the NPL
- * for the specific language governing rights and limitations under the
- * NPL.
- *
- * The Initial Developer of this code under the NPL is Netscape
- * Communications Corporation.  Portions created by Netscape are
- * Copyright (C) 1998 Netscape Communications Corporation.  All Rights
- * Reserved.
- */
-
-#ifndef nsInputHidden_h___
-#define nsInputHidden_h___
-
-#include "nsInput.h"
-class nsIAtom;
-class nsString;
-
-class nsInputHidden : public nsInput {
-public:
-  nsInputHidden (nsIAtom* aTag, nsIFormManager* aManager);
-
-  virtual nsIFrame* CreateFrame(nsIPresContext* aPresContext,
-                                PRInt32 aIndexInParent,
-                                nsIFrame* aParentFrame);
-
-  virtual void SetAttribute(nsIAtom* aAttribute, const nsString& aValue);
-
-  virtual nsContentAttr GetAttribute(nsIAtom* aAttribute,
-                                     nsHTMLValue& aResult) const;
-
-protected:
-  virtual ~nsInputHidden();
-
-  virtual void GetType(nsString& aResult) const;
-
-  // XXX save code and subclass from nsInputButton?
-  nsString* mValue;
-  PRInt32 mWidth;
-  PRInt32 mHeight;
-};
-
-#endif

layout/html/forms/src/nsInputImage.h

@@ -23,6 +23,8 @@
 class nsIAtom;
 class nsString;
 
+// this class definition will move to nsInputImage.cpp
+
 class nsInputImage : public nsInput {
 public:
   nsInputImage (nsIAtom* aTag, nsIFormManager* aManager);

layout/html/forms/src/nsInputPassword.h

@@ -1,40 +0,0 @@
-/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
- *
- * The contents of this file are subject to the Netscape Public License
- * Version 1.0 (the "NPL"); you may not use this file except in
- * compliance with the NPL.  You may obtain a copy of the NPL at
- * http://www.mozilla.org/NPL/
- *
- * Software distributed under the NPL is distributed on an "AS IS" basis,
- * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the NPL
- * for the specific language governing rights and limitations under the
- * NPL.
- *
- * The Initial Developer of this code under the NPL is Netscape
- * Communications Corporation.  Portions created by Netscape are
- * Copyright (C) 1998 Netscape Communications Corporation.  All Rights
- * Reserved.
- */
-
-#ifndef nsInputPassword_h___
-#define nsInputPassword_h___
-
-#include "nsInputText.h"
-class nsIAtom;
-class nsString;
-
-class nsInputPassword : public nsInputText {
-public:
-  nsInputPassword (nsIAtom* aTag, nsIFormManager* aManager);
-
-  virtual nsIFrame* CreateFrame(nsIPresContext* aPresContext,
-                                PRInt32 aIndexInParent,
-                                nsIFrame* aParentFrame);
-
-protected:
-  virtual ~nsInputPassword();
-};
-
-#endif
-
-

layout/html/forms/src/nsInputRadio.cpp

@@ -92,7 +92,7 @@ nsInputRadioFrame::InitializeWidget(nsIView *aView)
 // nsInputRadio
 
 nsInputRadio::nsInputRadio(nsIAtom* aTag, nsIFormManager* aManager)
-  : nsInputCheckbox(aTag, aManager) 
+  : nsInput(aTag, aManager) 
 {
 }
 

layout/html/forms/src/nsInputRadio.h

@@ -19,11 +19,13 @@
 #ifndef nsInputRadio_h___
 #define nsInputRadio_h___
 
-#include "nsInputCheckbox.h"
+// this class defintion will be moved into nsInputRadio.cpp
+
+#include "nsInput.h"
 class nsIAtom;
 class nsString;
 
-class nsInputRadio : public nsInputCheckbox {
+class nsInputRadio : public nsInput {
 public:
   nsInputRadio (nsIAtom* aTag, nsIFormManager* aManager);
 

layout/html/forms/src/nsInputText.h

@@ -25,6 +25,8 @@ class nsIAtom;
 class nsString;
 class nsView;
 
+// this class definition will move to nsInputText.cpp
+
 class nsInputText : public nsInput {
 public:
   nsInputText (nsIAtom* aTag, nsIFormManager* aManager);