embedding/browser/webBrowser/nsIEmbeddingSiteWindow.idl

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
   2  *
   3  * ***** BEGIN LICENSE BLOCK *****
   4  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   5  *
   6  * The contents of this file are subject to the Mozilla Public License Version
   7  * 1.1 (the "License"); you may not use this file except in compliance with
   8  * the License. You may obtain a copy of the License at
   9  * http://www.mozilla.org/MPL/
  10  *
  11  * Software distributed under the License is distributed on an "AS IS" basis,
  12  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  13  * for the specific language governing rights and limitations under the
  14  * License.
  15  *
  16  * The Original Code is the Mozilla browser.
  17  *
  18  * The Initial Developer of the Original Code is
  19  * Netscape Communications, Inc.
  20  * Portions created by the Initial Developer are Copyright (C) 1999
  21  * the Initial Developer. All Rights Reserved.
  22  *
  23  * Contributor(s):
  24  *   Adam Lock <adamlock@netscape.com>
  25  *
  26  * Alternatively, the contents of this file may be used under the terms of
  27  * either the GNU General Public License Version 2 or later (the "GPL"), or
  28  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  29  * in which case the provisions of the GPL or the LGPL are applicable instead
  30  * of those above. If you wish to allow use of your version of this file only
  31  * under the terms of either the GPL or the LGPL, and not to allow others to
  32  * use your version of this file under the terms of the MPL, indicate your
  33  * decision by deleting the provisions above and replace them with the notice
  34  * and other provisions required by the GPL or the LGPL. If you do not delete
  35  * the provisions above, a recipient may use your version of this file under
  36  * the terms of any one of the MPL, the GPL or the LGPL.
  37  *
  38  * ***** END LICENSE BLOCK ***** */
  39
  40 #include "nsISupports.idl"
  41
  42 /* THIS IS A PUBLIC EMBEDDING API */
  43
  44 /**
  45  * The nsIEmbeddingSiteWindow is implemented by the embedder to provide
  46  * Gecko with the means to call up to the host to resize the window,
  47  * hide or show it and set/get its title.
  48  *
  49  * @status FROZEN
  50  */
  51 [scriptable, uuid(3E5432CD-9568-4bd1-8CBE-D50ABA110743)]
  52 interface nsIEmbeddingSiteWindow : nsISupports
  53 {
  54     /**
  55      * Flag indicates that position of the top left corner of the outer area
  56      * is required/specified.
  57      *
  58      * @see setDimensions
  59      * @see getDimensions
  60      */
  61     const unsigned long DIM_FLAGS_POSITION   = 1;
  62
  63     /**
  64      * Flag indicates that the size of the inner area is required/specified.
  65      *
  66      * @note The inner and outer flags are mutually exclusive and it is
  67      *       invalid to combine them.
  68      *
  69      * @see setDimensions
  70      * @see getDimensions
  71      * @see DIM_FLAGS_SIZE_OUTER
  72      */
  73     const unsigned long DIM_FLAGS_SIZE_INNER = 2;
  74
  75     /**
  76      * Flag indicates that the size of the outer area is required/specified.
  77      *
  78      * @see setDimensions
  79      * @see getDimensions
  80      * @see DIM_FLAGS_SIZE_INNER
  81      */
  82     const unsigned long DIM_FLAGS_SIZE_OUTER = 4;
  83
  84     /**
  85      * Sets the dimensions for the window; the position & size. The
  86      * flags to indicate what the caller wants to set and whether the size
  87      * refers to the inner or outer area. The inner area refers to just
  88      * the embedded area, wheras the outer area can also include any
  89      * surrounding chrome, window frame, title bar, and so on.
  90      *
  91      * @param flags  Combination of position, inner and outer size flags.
  92      * @param x      Left hand corner of the outer area.
  93      * @param y      Top corner of the outer area.
  94      * @param cx     Width of the inner or outer area.
  95      * @param cy     Height of the inner or outer area.
  96      *
  97      * @return <code>NS_OK</code> if operation was performed correctly;
  98      *         <code>NS_ERROR_UNEXPECTED</code> if window could not be
  99      *           destroyed;
 100      *         <code>NS_ERROR_INVALID_ARG</code> for bad flag combination
 101      *           or illegal dimensions.
 102      *
 103      * @see getDimensions
 104      * @see DIM_FLAGS_POSITION
 105      * @see DIM_FLAGS_SIZE_OUTER
 106      * @see DIM_FLAGS_SIZE_INNER
 107      */
 108     void setDimensions(in unsigned long flags, in long x, in long y, in long cx, in long cy);
 109
 110     /**
 111      * Gets the dimensions of the window. The caller may pass
 112      * <CODE>nsnull</CODE> for any value it is uninterested in receiving.
 113      *
 114      * @param flags  Combination of position, inner and outer size flag .
 115      * @param x      Left hand corner of the outer area; or <CODE>nsnull</CODE>.
 116      * @param y      Top corner of the outer area; or <CODE>nsnull</CODE>.
 117      * @param cx     Width of the inner or outer area; or <CODE>nsnull</CODE>.
 118      * @param cy     Height of the inner or outer area; or <CODE>nsnull</CODE>.
 119      *
 120      * @see setDimensions
 121      * @see DIM_FLAGS_POSITION
 122      * @see DIM_FLAGS_SIZE_OUTER
 123      * @see DIM_FLAGS_SIZE_INNER
 124      */
 125     void getDimensions(in unsigned long flags, out long x, out long y, out long cx, out long cy);
 126
 127     /**
 128      * Give the window focus.
 129      */
 130     void setFocus();
 131
 132     /**
 133      * Visibility of the window.
 134      */
 135     attribute boolean visibility;
 136
 137     /**
 138      * Title of the window.
 139      */
 140     attribute wstring title;
 141
 142     /**
 143      * Native window for the site's window. The implementor should copy the
 144      * native window object into the address supplied by the caller. The
 145      * type of the native window that the address refers to is  platform
 146      * and OS specific as follows:
 147      *
 148      * <ul>
 149      *   <li>On Win32 it is an <CODE>HWND</CODE>.</li>
 150      *   <li>On MacOS this is a <CODE>WindowPtr</CODE>.</li>
 151      *   <li>On GTK this is a <CODE>GtkWidget*</CODE>.</li>
 152      * </ul>
 153      */
 154     [noscript] readonly attribute voidPtr siteWindow;
 155 };