widget/public/nsIBaseWindow.idl

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
   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  *   Travis Bogard <travis@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 #include "nsrootidl.idl"
  42 /*#include "nsIWidget.idl"  Boy this would be nice.*/
  43
  44 [ptr] native nsIWidget(nsIWidget);
  45 %{ C++
  46 class nsIWidget;
  47 %}
  48
  49 typedef voidPtr nativeWindow;
  50
  51 /**
  52  * The nsIBaseWindow describes a generic window and basic operations that
  53  * can be performed on it.  This is not to be a complete windowing interface
  54  * but rather a common set that nearly all windowed objects support.
  55  */
  56
  57 [scriptable, uuid(046BC8A0-8015-11d3-AF70-00A024FFC08C)]
  58 interface nsIBaseWindow : nsISupports
  59 {
  60         /*
  61         Allows a client to initialize an object implementing this interface with
  62         the usually required window setup information.
  63
  64         @param parentNativeWindow - This allows a system to pass in the parenting
  65                 window as a native reference rather than relying on the calling
  66                 application to have created the parent window as an nsIWidget.  This
  67                 value will be ignored (should be nsnull) if an nsIWidget is passed in to
  68                 the parentWidget parameter.  One of the two parameters however must be
  69                 passed.
  70
  71         @param parentWidget - This allows a system to pass in the parenting widget.
  72                 This allows some objects to optimize themselves and rely on the view
  73                 system for event flow rather than creating numerous native windows.  If
  74                 one of these is not available, nsnull should be passed and a
  75                 valid native window should be passed to the parentNativeWindow parameter.
  76
  77         @param x - This is the x co-ordinate relative to the parent to place the
  78                 window.
  79
  80         @param y - This is the y co-ordinate relative to the parent to place the
  81                 window.
  82
  83         @param cx - This is the width   for the window to be.
  84
  85         @param cy - This is the height for the window to be.
  86
  87         @return NS_OK - Window Init succeeded without a problem.
  88                                 NS_ERROR_UNEXPECTED - Call was unexpected at this time.  Most likely
  89                                         due to you calling it after create() has been called.
  90                                 NS_ERROR_INVALID_ARG - controls that require either a parentNativeWindow
  91                                         or a parentWidget may return invalid arg when they do not
  92                                         receive what they are needing.
  93         */
  94         [noscript]void initWindow(in nativeWindow parentNativeWindow,
  95                 in nsIWidget parentWidget,      in long x, in long y, in long cx, in long cy);
  96
  97         /*
  98         Tells the window that intialization and setup is complete.  When this is
  99         called the window can actually create itself based on the setup
 100         information handed to it.
 101
 102         @return NS_OK - Creation was successfull.
 103                                 NS_ERROR_UNEXPECTED - This call was unexpected at this time.
 104                                         Perhaps create() had already been called or not all
 105                                         required initialization had been done.
 106         */
 107         void create();
 108
 109         /*
 110         Tell the window that it should destroy itself.  This call should not be
 111         necessary as it will happen implictly when final release occurs on the
 112         object.  If for some reaons you want the window destroyed prior to release
 113         due to cycle or ordering issues, then this call provides that ability.
 114
 115         @return NS_OK - Everything destroyed properly.
 116                                 NS_ERROR_UNEXPECTED - This call was unexpected at this time.
 117                                         Perhaps create() has not been called yet.
 118         */
 119         void destroy();
 120
 121         /*
 122         Sets the current x and y coordinates of the control.  This is relative to
 123         the parent window.
 124         */
 125         void setPosition(in long x, in long y);
 126
 127         /*
 128         Gets the current x and y coordinates of the control.  This is relatie to the
 129         parent window.
 130         */
 131         void getPosition(out long x, out long y);
 132
 133         /*
 134         Sets the width and height of the control.
 135         */
 136         void setSize(in long cx, in long cy, in boolean fRepaint);
 137
 138         /*
 139         Gets the width and height of the control.
 140         */
 141         void getSize(out long cx, out long cy);
 142
 143         /*
 144         Convenience function combining the SetPosition and SetSize into one call.
 145         Also is more efficient than calling both.
 146         */
 147         void setPositionAndSize(in long x, in long y, in long cx, in long cy,
 148                 in boolean fRepaint);
 149
 150         /*
 151         Convenience function combining the GetPosition and GetSize into one call.
 152         Also is more efficient than calling both.
 153         */
 154         void getPositionAndSize(out long x, out long y, out long cx, out long cy);
 155
 156         /**
 157          * Tell the window to repaint itself
 158          * @param aForce - if true, repaint immediately
 159          *                 if false, the window may defer repainting as it sees fit.
 160          */
 161         void repaint(in boolean force);
 162
 163         /*
 164         This is the parenting widget for the control.  This may be null if only the
 165         native window was handed in for the parent during initialization.  If this
 166         is returned, it should refer to the same object as parentNativeWindow.
 167
 168         Setting this after Create() has been called may not be supported by some
 169         implementations.
 170
 171         On controls that don't support widgets, setting this will return a
 172         NS_ERROR_NOT_IMPLEMENTED error.
 173         */
 174         [noscript] attribute nsIWidget parentWidget;
 175
 176         /*
 177         This is the native window parent of the control.
 178
 179         Setting this after Create() has been called may not be supported by some
 180         implementations.
 181
 182         On controls that don't support setting nativeWindow parents, setting this
 183         will return a NS_ERROR_NOT_IMPLEMENTED error.
 184         */
 185         attribute nativeWindow parentNativeWindow;
 186
 187         /*
 188         Attribute controls the visibility of the object behind this interface.
 189         Setting this attribute to false will hide the control.  Setting it to
 190         true will show it.
 191         */
 192         attribute boolean visibility;
 193
 194     /*
 195     a disabled window should accept no user interaction; it's a dead window,
 196     like the parent of a modal window.
 197     */
 198     attribute boolean enabled;
 199
 200     /** set blurSuppression to true to suppress handling of blur events.
 201      *  set it false to re-enable them. query it to determine whether
 202      *  blur events are suppressed. The implementation should allow
 203      *  for blur events to be suppressed multiple times.
 204      */
 205     attribute boolean blurSuppression;
 206
 207         /*
 208         Allows you to find out what the widget is of a given object.  Depending
 209         on the object, this may return the parent widget in which this object
 210         lives if it has not had to create its own widget.
 211         */
 212         [noscript] readonly attribute nsIWidget mainWidget;
 213
 214         /**
 215         * Give the window focus.
 216         */
 217         void setFocus();
 218
 219         /*
 220         Title of the window.
 221         */
 222         attribute wstring title;
 223 };