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