widget/nsIBaseWindow.idl

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
   2  *
   3  * This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 #include "nsISupports.idl"
   8 #include "nsrootidl.idl"
   9 /*#include "nsIWidget.idl"  Boy this would be nice.*/
  10
  11 [ptr] native nsIWidget(nsIWidget);
  12 %{ C++
  13 class nsIWidget;
  14 %}
  15
  16 typedef voidPtr nativeWindow;
  17
  18 /**
  19  * The nsIBaseWindow describes a generic window and basic operations that
  20  * can be performed on it.  This is not to be a complete windowing interface
  21  * but rather a common set that nearly all windowed objects support.
  22  */
  23
  24 [scriptable, uuid(ca635529-a977-4552-9b8a-66187e54d882)]
  25 interface nsIBaseWindow : nsISupports
  26 {
  27         /*
  28         Allows a client to initialize an object implementing this interface with
  29         the usually required window setup information.
  30         It is possible to pass null for both parentNativeWindow and parentWidget,
  31         but only docshells support this.
  32
  33         @param parentNativeWindow - This allows a system to pass in the parenting
  34                 window as a native reference rather than relying on the calling
  35                 application to have created the parent window as an nsIWidget.  This
  36                 value will be ignored (should be nullptr) if an nsIWidget is passed in to
  37                 the parentWidget parameter.
  38
  39         @param parentWidget - This allows a system to pass in the parenting widget.
  40                 This allows some objects to optimize themselves and rely on the view
  41                 system for event flow rather than creating numerous native windows.  If
  42                 one of these is not available, nullptr should be passed.
  43
  44         @param x - This is the x co-ordinate relative to the parent to place the
  45                 window.
  46
  47         @param y - This is the y co-ordinate relative to the parent to place the
  48                 window.
  49
  50         @param cx - This is the width   for the window to be.
  51
  52         @param cy - This is the height for the window to be.
  53
  54         @return NS_OK - Window Init succeeded without a problem.
  55                                 NS_ERROR_UNEXPECTED - Call was unexpected at this time.  Most likely
  56                                         due to you calling it after create() has been called.
  57                                 NS_ERROR_INVALID_ARG - controls that require either a parentNativeWindow
  58                                         or a parentWidget may return invalid arg when they do not
  59                                         receive what they are needing.
  60         */
  61         [noscript]void initWindow(in nativeWindow parentNativeWindow,
  62                 in nsIWidget parentWidget,      in long x, in long y, in long cx, in long cy);
  63
  64         /*
  65         Tells the window that intialization and setup is complete.  When this is
  66         called the window can actually create itself based on the setup
  67         information handed to it.
  68
  69         @return NS_OK - Creation was successfull.
  70                                 NS_ERROR_UNEXPECTED - This call was unexpected at this time.
  71                                         Perhaps create() had already been called or not all
  72                                         required initialization had been done.
  73         */
  74         void create();
  75
  76         /*
  77         Tell the window that it should destroy itself.  This call should not be
  78         necessary as it will happen implictly when final release occurs on the
  79         object.  If for some reaons you want the window destroyed prior to release
  80         due to cycle or ordering issues, then this call provides that ability.
  81
  82         @return NS_OK - Everything destroyed properly.
  83                                 NS_ERROR_UNEXPECTED - This call was unexpected at this time.
  84                                         Perhaps create() has not been called yet.
  85         */
  86         void destroy();
  87
  88         /*
  89         Sets the current x and y coordinates of the control.  This is relative to
  90         the parent window.
  91         */
  92         void setPosition(in long x, in long y);
  93
  94   /*
  95   Ditto, with arguments in global desktop pixels rather than (potentially
  96   ambiguous) device pixels
  97   */
  98         void setPositionDesktopPix(in long x, in long y);
  99
 100         /*
 101         Gets the current x and y coordinates of the control.  This is relatie to the
 102         parent window.
 103         */
 104         void getPosition(out long x, out long y);
 105
 106         /*
 107         Sets the width and height of the control.
 108         */
 109         void setSize(in long cx, in long cy, in boolean fRepaint);
 110
 111         /*
 112         Gets the width and height of the control.
 113         */
 114         void getSize(out long cx, out long cy);
 115
 116         /**
 117          * The 'flags' argument to setPositionAndSize is a set of these bits.
 118          */
 119         const unsigned long eRepaint = 1;
 120         const unsigned long eDelayResize = 2;
 121
 122         /*
 123         Convenience function combining the SetPosition and SetSize into one call.
 124         Also is more efficient than calling both.
 125         */
 126         void setPositionAndSize(in long x, in long y, in long cx, in long cy,
 127                 in unsigned long flags);
 128
 129         /*
 130         Convenience function combining the GetPosition and GetSize into one call.
 131         Also is more efficient than calling both.
 132         */
 133         void getPositionAndSize(out long x, out long y, out long cx, out long cy);
 134
 135         /**
 136          * Tell the window to repaint itself
 137          * @param aForce - if true, repaint immediately
 138          *                 if false, the window may defer repainting as it sees fit.
 139          */
 140         void repaint(in boolean force);
 141
 142         /*
 143         This is the parenting widget for the control.  This may be null if the
 144         native window was handed in for the parent during initialization.
 145         If this is returned, it should refer to the same object as
 146         parentNativeWindow.
 147
 148         Setting this after Create() has been called may not be supported by some
 149         implementations.
 150
 151         On controls that don't support widgets, setting this will return a
 152         NS_ERROR_NOT_IMPLEMENTED error.
 153         */
 154         [noscript] attribute nsIWidget parentWidget;
 155
 156         /*
 157         This is the native window parent of the control.
 158
 159         Setting this after Create() has been called may not be supported by some
 160         implementations.
 161
 162         On controls that don't support setting nativeWindow parents, setting this
 163         will return a NS_ERROR_NOT_IMPLEMENTED error.
 164         */
 165         attribute nativeWindow parentNativeWindow;
 166
 167         /*
 168         This is the handle (HWND, GdkWindow*, ...) to the native window of the
 169         control, exposed as a DOMString.
 170
 171         @return DOMString in hex format with "0x" prepended, or empty string if
 172         mainWidget undefined
 173
 174         @throws NS_ERROR_NOT_IMPLEMENTED for non-XULWindows
 175         */
 176         readonly attribute DOMString nativeHandle;
 177
 178         /*
 179         Attribute controls the visibility of the object behind this interface.
 180         Setting this attribute to false will hide the control.  Setting it to
 181         true will show it.
 182         */
 183         attribute boolean visibility;
 184
 185     /*
 186     a disabled window should accept no user interaction; it's a dead window,
 187     like the parent of a modal window.
 188     */
 189     attribute boolean enabled;
 190
 191         /*
 192         Allows you to find out what the widget is of a given object.  Depending
 193         on the object, this may return the parent widget in which this object
 194         lives if it has not had to create its own widget.
 195         */
 196         [noscript] readonly attribute nsIWidget mainWidget;
 197
 198         /*
 199         The number of   device pixels per CSS pixel used on this window's current
 200         screen at the default zoom level.
 201         This is the value returned by GetDefaultScale() of the underlying widget.
 202         Note that this may change if the window is moved between screens with
 203         differing resolutions.
 204         */
 205         readonly attribute double unscaledDevicePixelsPerCSSPixel;
 206
 207         /*
 208         The number of device pixels per display pixel on this window's current
 209         screen. (The meaning of "display pixel" varies across OS environments;
 210         it is the pixel units used by the desktop environment to manage screen
 211         real estate and window positioning, which may correspond to (per-screen)
 212         device pixels, or may be a virtual coordinate space that covers a multi-
 213         monitor, mixed-dpi desktop space.)
 214         This is the value returned by DevicePixelsPerDesktopPixel() of the underlying
 215         widget.
 216         Note that this may change if the window is moved between screens with
 217         differing resolutions.
 218         */
 219         readonly attribute double devicePixelsPerDesktopPixel;
 220
 221         /**
 222         * Give the window focus.
 223         */
 224         void setFocus();
 225
 226         /*
 227         Title of the window.
 228         */
 229         attribute AString title;
 230 };