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 #include "Units.h"
  14 #include "mozilla/DimensionRequest.h"
  15
  16 class nsIWidget;
  17 %}
  18
  19 typedef voidPtr nativeWindow;
  20 native DimensionRequest(mozilla::DimensionRequest&&);
  21 native DimensionKind(mozilla::DimensionKind);
  22
  23 /**
  24  * The nsIBaseWindow describes a generic window and basic operations that
  25  * can be performed on it.  This is not to be a complete windowing interface
  26  * but rather a common set that nearly all windowed objects support.
  27  */
  28
  29 [scriptable, builtinclass, uuid(ca635529-a977-4552-9b8a-66187e54d882)]
  30 interface nsIBaseWindow : nsISupports
  31 {
  32   /*
  33   Allows a client to initialize an object implementing this interface with
  34   the usually required window setup information.
  35   It is possible to pass null for both parentNativeWindow and parentWidget,
  36   but only docshells support this.
  37
  38   @param parentNativeWindow - This allows a system to pass in the parenting
  39     window as a native reference rather than relying on the calling
  40     application to have created the parent window as an nsIWidget.  This
  41     value will be ignored (should be nullptr) if an nsIWidget is passed in to
  42     the parentWidget parameter.
  43
  44   @param parentWidget - This allows a system to pass in the parenting widget.
  45     This allows some objects to optimize themselves and rely on the view
  46     system for event flow rather than creating numerous native windows.  If
  47     one of these is not available, nullptr should be passed.
  48
  49   @param x - This is the x co-ordinate relative to the parent to place the
  50     window.
  51
  52   @param y - This is the y co-ordinate relative to the parent to place the
  53     window.
  54
  55   @param cx - This is the width  for the window to be.
  56
  57   @param cy - This is the height for the window to be.
  58
  59   @return  NS_OK - Window Init succeeded without a problem.
  60         NS_ERROR_UNEXPECTED - Call was unexpected at this time. Perhaps
  61           initWindow() had already been called.
  62         NS_ERROR_INVALID_ARG - controls that require either a parentNativeWindow
  63           or a parentWidget may return invalid arg when they do not
  64           receive what they are needing.
  65   */
  66   [noscript]void initWindow(in nativeWindow parentNativeWindow,
  67     in nsIWidget parentWidget,  in long x, in long y, in long cx, in long cy);
  68
  69   /*
  70   Tell the window that it should destroy itself.  This call should not be
  71   necessary as it will happen implictly when final release occurs on the
  72   object.  If for some reaons you want the window destroyed prior to release
  73   due to cycle or ordering issues, then this call provides that ability.
  74
  75   @return  NS_OK - Everything destroyed properly.
  76         NS_ERROR_UNEXPECTED - This call was unexpected at this time.
  77           Perhaps create() has not been called yet.
  78   */
  79   void destroy();
  80
  81   /*
  82   Sets the current x and y coordinates of the control.  This is relative to
  83   the parent window.
  84   */
  85   void setPosition(in long x, in long y);
  86
  87   /*
  88   Ditto, with arguments in global desktop pixels rather than (potentially
  89   ambiguous) device pixels
  90   */
  91   void setPositionDesktopPix(in long x, in long y);
  92
  93   /*
  94   Gets the current x and y coordinates of the control.  This is relative to the
  95   parent window.
  96   */
  97   void getPosition(out long x, out long y);
  98
  99 %{C++
 100   mozilla::LayoutDeviceIntPoint GetPosition() {
 101     int32_t x = 0, y = 0;
 102     GetPosition(&x, &y);
 103     return mozilla::LayoutDeviceIntPoint(x, y);
 104   }
 105 %}
 106
 107   /*
 108   Sets the width and height of the control.
 109   */
 110   void setSize(in long cx, in long cy, in boolean fRepaint);
 111
 112   /*
 113   Gets the width and height of the control.
 114   */
 115   void getSize(out long cx, out long cy);
 116
 117 %{C++
 118   mozilla::LayoutDeviceIntSize GetSize() {
 119     int32_t w = 0, h = 0;
 120     GetSize(&w, &h);
 121     return mozilla::LayoutDeviceIntSize(w, h);
 122   }
 123 %}
 124
 125   /**
 126    * The 'flags' argument to setPositionAndSize is a set of these bits.
 127    */
 128   const unsigned long eRepaint = 1;
 129   const unsigned long eDelayResize = 2;
 130
 131   /*
 132   Convenience function combining the SetPosition and SetSize into one call.
 133   Also is more efficient than calling both.
 134   */
 135   void setPositionAndSize(in long x, in long y, in long cx, in long cy,
 136     in unsigned long flags);
 137
 138   /*
 139   Convenience function combining the GetPosition and GetSize into one call.
 140   Also is more efficient than calling both.
 141   */
 142   void getPositionAndSize(out long x, out long y, out long cx, out long cy);
 143
 144 %{C++
 145   mozilla::LayoutDeviceIntRect GetPositionAndSize() {
 146     int32_t x = 0, y = 0, w = 0, h = 0;
 147     GetPositionAndSize(&x, &y, &w, &h);
 148     return mozilla::LayoutDeviceIntRect(x, y, w, h);
 149   }
 150 %}
 151
 152   /**
 153    * Allows to request the change of individual dimensions without specifying
 154    * the other components.
 155    *
 156    * @param aRequest - The requested change. A request to change only the width
 157    *                   may look like:
 158    *                   {DimensionKind::Outer, Nothing(), Nothing(), Some(20), Nothing()}
 159    *
 160    * Note: Inner position is not supported.
 161    *
 162    * @see DimensionRequest
 163    */
 164   [noscript] void setDimensions(in DimensionRequest aRequest);
 165
 166   /**
 167    * Gets the dimensions of the window. The caller may pass nullptr for any
 168    * value it is uninterested in receiving.
 169    *
 170    * @param aDimensionKind  Specifies whether the dimensions are in reference
 171    *                        to the inner or outer dimensions.
 172    * @param aX              Left hand corner of the outer area; or nullptr.
 173    * @param aY              Top corner of the outer area; or nullptr.
 174    * @param aCX             Width of the inner or outer area; or nullptr.
 175    * @param aCY             Height of the inner or outer area; or nullptr.
 176    *
 177    * Note: Inner position is not supported.
 178    *
 179    * @see DimensionRequest
 180    */
 181   [noscript] void getDimensions(in DimensionKind aDimensionKind, out long aX, out long aY, out long aCX, out long aCY);
 182
 183   /**
 184    * Tell the window to repaint itself
 185    * @param aForce - if true, repaint immediately
 186    *                 if false, the window may defer repainting as it sees fit.
 187    */
 188   void repaint(in boolean force);
 189
 190   /*
 191   This is the parenting widget for the control.  This may be null if the
 192   native window was handed in for the parent during initialization.
 193   If this  is returned, it should refer to the same object as
 194   parentNativeWindow.
 195
 196   Setting this after Create() has been called may not be supported by some
 197   implementations.
 198
 199   On controls that don't support widgets, setting this will return a
 200   NS_ERROR_NOT_IMPLEMENTED error.
 201   */
 202   [noscript] attribute nsIWidget parentWidget;
 203
 204   /*
 205   This is the native window parent of the control.
 206
 207   Setting this after Create() has been called may not be supported by some
 208   implementations.
 209
 210   On controls that don't support setting nativeWindow parents, setting this
 211   will return a NS_ERROR_NOT_IMPLEMENTED error.
 212   */
 213   [noscript] attribute nativeWindow parentNativeWindow;
 214
 215   /*
 216   This is the handle (HWND, GdkWindow*, ...) to the native window of the
 217   control, exposed as an AString.
 218
 219   @return AString in hex format with "0x" prepended, or empty string if
 220   mainWidget undefined
 221
 222   @throws NS_ERROR_NOT_IMPLEMENTED for non-XULWindows
 223   */
 224   readonly attribute AString nativeHandle;
 225
 226   /*
 227   Attribute controls the visibility of the object behind this interface.
 228   Setting this attribute to false will hide the control.  Setting it to
 229   true will show it.
 230   */
 231   attribute boolean visibility;
 232
 233   /*
 234   a disabled window should accept no user interaction; it's a dead window,
 235   like the parent of a modal window.
 236   */
 237   attribute boolean enabled;
 238
 239   /*
 240   Allows you to find out what the widget is of a given object.  Depending
 241   on the object, this may return the parent widget in which this object
 242   lives if it has not had to create its own widget.
 243   */
 244   [noscript] readonly attribute nsIWidget mainWidget;
 245
 246   /*
 247   The number of device pixels per CSS pixel used by this window's widget at the
 248   default full zoom level.
 249   This is the value returned by GetDefaultScale() of the underlying widget.
 250   Note that this may change if the window is moved between screens with
 251   differing resolutions.
 252   NOTE: This is mostly an implementation detail of
 253   UnscaledDevicePixelsPerCSSPixel, which is what you probably want to use.
 254   */
 255   [noscript, notxpcom, nostdcall] readonly attribute double widgetCSSToDeviceScale;
 256
 257 %{C++
 258   // The number of device pixels per CSS pixel used on this window's current
 259   // screen at the default full zoom level.
 260   //
 261   // This is the widget scale _plus_ the OS zoom scale if appropriate.
 262   // Implemented in AppWindow.cpp
 263   mozilla::CSSToLayoutDeviceScale UnscaledDevicePixelsPerCSSPixel();
 264 %}
 265
 266   /*
 267   The number of device pixels per display pixel on this window's current
 268   screen. (The meaning of "display pixel" varies across OS environments;
 269   it is the pixel units used by the desktop environment to manage screen
 270   real estate and window positioning, which may correspond to (per-screen)
 271   device pixels, or may be a virtual coordinate space that covers a multi-
 272   monitor, mixed-dpi desktop space.)
 273   This is the value returned by GetDesktopToDeviceScale() of the underlying
 274   widget.
 275   Note that this may change if the window is moved between screens with
 276   differing resolutions.
 277   */
 278   readonly attribute double devicePixelsPerDesktopPixel;
 279
 280 %{C++
 281   mozilla::DesktopToLayoutDeviceScale DevicePixelsPerDesktopPixel() {
 282     double s = 1.0;
 283     GetDevicePixelsPerDesktopPixel(&s);
 284     return mozilla::DesktopToLayoutDeviceScale(s);
 285   }
 286
 287   mozilla::CSSToDesktopScale GetUnscaledCSSToDesktopScale() {
 288     return UnscaledDevicePixelsPerCSSPixel() / DevicePixelsPerDesktopPixel();
 289   }
 290 %}
 291
 292   /*
 293   Title of the window.
 294   */
 295   attribute AString title;
 296 };