nsIEmbeddingSiteWindow frozen. Updated documentation. b=99181 r=chak@netscape.com sr=rpotts@netscape.com

embedding/browser/webBrowser/nsIEmbeddingSiteWindow.idl

@@ -27,58 +27,83 @@
 /**
  * The nsIEmbeddingSiteWindow is implemented by the embedder to provide
  * Gecko with the means to call up to the host to resize the window,
- * hide or show it and change/query various other properties.
+ * hide or show it and set/get its title.
+ *
+ * @status FROZEN
  */
 [scriptable, uuid(3E5432CD-9568-4bd1-8CBE-D50ABA110743)]
 interface nsIEmbeddingSiteWindow : nsISupports
 {
-    /*
-     Window dimension flags for controlling what you are getting and setting.
-     Note that the inner and outer flags are mutually exclusive and it
-     is invalid to combine them.
-     */
-
     /**
-     * Position of the top left corner of the outer area.
+     * Flag indicates that position of the top left corner of the outer area
+     * is required/specified.
+     *
+     * @see setDimensions
+     * @see getDimensions
      */
     const unsigned long DIM_FLAGS_POSITION   = 1;
+    
     /**
-     * Size of the inner area.
+     * Flag indicates that the size of the inner area is required/specified.
+     *
+     * @note The inner and outer flags are mutually exclusive and it is
+     *       invalid to combine them.
+     *
+     * @see setDimensions
+     * @see getDimensions
+     * @see DIM_FLAGS_SIZE_OUTER
      */
     const unsigned long DIM_FLAGS_SIZE_INNER = 2;
+
     /**
-     * Size of the outer area.
+     * Flag indicates that the size of the outer area is required/specified.
+     *
+     * @see setDimensions
+     * @see getDimensions
+     * @see DIM_FLAGS_SIZE_INNER
      */
     const unsigned long DIM_FLAGS_SIZE_OUTER = 4;
 
     /**
-     * Sets the dimensions for the window; the position & size. Use the
-     * flags to indicate what you want to set and whether the size
+     * Sets the dimensions for the window; the position & size. The
+     * flags to indicate what the caller wants to set and whether the size
      * refers to the inner or outer area. The inner area refers to just
-     * the embedded area, wheras the outer area includes the embedded
-     * area any surrounding chrome, window frame, title bar etc.
+     * the embedded area, wheras the outer area can also include any 
+     * surrounding chrome, window frame, title bar, and so on.
      *
-     * @param flags  Combination of position, inner and outer size bits.
-     *               Note that the inner and outer size bits are mutually
-     *               exclusive.
-     * @param x      Left hand corner of the outer area
-     * @param y      Top corner of the outer area
-     * @param cx     Width of the inner or outer area 
-     * @param cy     Height of the inner or outer area
+     * @param flags  Combination of position, inner and outer size flags.
+     * @param x      Left hand corner of the outer area.
+     * @param y      Top corner of the outer area.
+     * @param cx     Width of the inner or outer area.
+     * @param cy     Height of the inner or outer area.
      *
-     * @return <code>NS_OK</code> if operation was performed correctly.
+     * @return <code>NS_OK</code> if operation was performed correctly;
      *         <code>NS_ERROR_UNEXPECTED</code> if window could not be
-     *           destroyed.
+     *           destroyed;
      *         <code>NS_ERROR_INVALID_ARG</code> for bad flag combination
      *           or illegal dimensions.
+     *
+     * @see getDimensions
+     * @see DIM_FLAGS_POSITION
+     * @see DIM_FLAGS_SIZE_OUTER
+     * @see DIM_FLAGS_SIZE_INNER
      */
     void setDimensions(in unsigned long flags, in long x, in long y, in long cx, in long cy);
 
     /**
-     * Gets the dimensions of the window. Use flags and pass nsnull if you
-     * are uninterested in certain values.
+     * Gets the dimensions of the window. The caller may pass
+     * <CODE>nsnull</CODE> for any value it is uninterested in receiving.
      *
-     * @see #setDimensions
+     * @param flags  Combination of position, inner and outer size flag .
+     * @param x      Left hand corner of the outer area; or <CODE>nsnull</CODE>.
+     * @param y      Top corner of the outer area; or <CODE>nsnull</CODE>.
+     * @param cx     Width of the inner or outer area; or <CODE>nsnull</CODE>.
+     * @param cy     Height of the inner or outer area; or <CODE>nsnull</CODE>.
+     *
+     * @see setDimensions
+     * @see DIM_FLAGS_POSITION
+     * @see DIM_FLAGS_SIZE_OUTER
+     * @see DIM_FLAGS_SIZE_INNER
      */
     void getDimensions(in unsigned long flags, out long x, out long y, out long cx, out long cy);
 
@@ -98,7 +123,16 @@ interface nsIEmbeddingSiteWindow : nsISupports
     attribute wstring title;
 
     /**
-     * Native window handle returned in a void pointer
+     * Native window for the site's window. The implementor should copy the
+     * native window object into the address supplied by the caller. The
+     * type of the native window that the address refers to is  platform
+     * and OS specific as follows:
+     *
+     * <ul>
+     *   <li>On Win32 it is an <CODE>HWND</CODE>.</li>
+     *   <li>On MacOS this is a <CODE>WindowPtr</CODE>.</li>
+     *   <li>On GTK this is a <CODE>GtkWidget*</CODE>.</li>
+     * </ul>
      */
     [noscript] readonly attribute voidPtr siteWindow;
 };