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