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   /*
  97   Sets the width and height of the control.
  98   */
  99   void setSize(in long cx, in long cy, in boolean fRepaint);
 100
 101   /*
 102   Gets the width and height of the control.
 103   */
 104   void getSize(out long cx, out long cy);
 105
 106   /**
 107    * The 'flags' argument to setPositionAndSize is a set of these bits.
 108    */
 109   const unsigned long eRepaint = 1;
 110   const unsigned long eDelayResize = 2;
 111
 112   /*
 113   Convenience function combining the SetPosition and SetSize into one call.
 114   Also is more efficient than calling both.
 115   */
 116   void setPositionAndSize(in long x, in long y, in long cx, in long cy,
 117     in unsigned long flags);
 118
 119   /*
 120   Convenience function combining the GetPosition and GetSize into one call.
 121   Also is more efficient than calling both.
 122   */
 123   void getPositionAndSize(out long x, out long y, out long cx, out long cy);
 124
 125   /**
 126    * Tell the window to repaint itself
 127    * @param aForce - if true, repaint immediately
 128    *                 if false, the window may defer repainting as it sees fit.
 129    */
 130   void repaint(in boolean force);
 131
 132   /*
 133   This is the parenting widget for the control.  This may be null if the
 134   native window was handed in for the parent during initialization.
 135   If this  is returned, it should refer to the same object as
 136   parentNativeWindow.
 137
 138   Setting this after Create() has been called may not be supported by some
 139   implementations.
 140
 141   On controls that don't support widgets, setting this will return a
 142   NS_ERROR_NOT_IMPLEMENTED error.
 143   */
 144   [noscript] attribute nsIWidget parentWidget;
 145
 146   /*
 147   This is the native window parent of the control.
 148
 149   Setting this after Create() has been called may not be supported by some
 150   implementations.
 151
 152   On controls that don't support setting nativeWindow parents, setting this
 153   will return a NS_ERROR_NOT_IMPLEMENTED error.
 154   */
 155   attribute nativeWindow parentNativeWindow;
 156
 157   /*
 158   This is the handle (HWND, GdkWindow*, ...) to the native window of the
 159   control, exposed as an AString.
 160
 161   @return AString in hex format with "0x" prepended, or empty string if
 162   mainWidget undefined
 163
 164   @throws NS_ERROR_NOT_IMPLEMENTED for non-XULWindows
 165   */
 166   readonly attribute AString nativeHandle;
 167
 168   /*
 169   Attribute controls the visibility of the object behind this interface.
 170   Setting this attribute to false will hide the control.  Setting it to
 171   true will show it.
 172   */
 173   attribute boolean visibility;
 174
 175     /*
 176     a disabled window should accept no user interaction; it's a dead window,
 177     like the parent of a modal window.
 178     */
 179     attribute boolean enabled;
 180
 181   /*
 182   Allows you to find out what the widget is of a given object.  Depending
 183   on the object, this may return the parent widget in which this object
 184   lives if it has not had to create its own widget.
 185   */
 186   [noscript] readonly attribute nsIWidget mainWidget;
 187
 188   /*
 189   The number of  device pixels per CSS pixel used on this window's current
 190   screen at the default zoom level.
 191   This is the value returned by GetDefaultScale() of the underlying widget.
 192   Note that this may change if the window is moved between screens with
 193   differing resolutions.
 194   */
 195   readonly attribute double unscaledDevicePixelsPerCSSPixel;
 196
 197 %{C++
 198   mozilla::CSSToLayoutDeviceScale UnscaledDevicePixelsPerCSSPixel() {
 199     double s = 1.0;
 200     GetUnscaledDevicePixelsPerCSSPixel(&s);
 201     return mozilla::CSSToLayoutDeviceScale(s);
 202   }
 203 %}
 204
 205   /*
 206   The number of device pixels per display pixel on this window's current
 207   screen. (The meaning of "display pixel" varies across OS environments;
 208   it is the pixel units used by the desktop environment to manage screen
 209   real estate and window positioning, which may correspond to (per-screen)
 210   device pixels, or may be a virtual coordinate space that covers a multi-
 211   monitor, mixed-dpi desktop space.)
 212   This is the value returned by GetDesktopToDeviceScale() of the underlying
 213   widget.
 214   Note that this may change if the window is moved between screens with
 215   differing resolutions.
 216   */
 217   readonly attribute double devicePixelsPerDesktopPixel;
 218
 219 %{C++
 220   mozilla::DesktopToLayoutDeviceScale DevicePixelsPerDesktopPixel() {
 221     double s = 1.0;
 222     GetDevicePixelsPerDesktopPixel(&s);
 223     return mozilla::DesktopToLayoutDeviceScale(s);
 224   }
 225
 226   mozilla::CSSToDesktopScale GetCSSToDesktopScale() {
 227     return UnscaledDevicePixelsPerCSSPixel() / DevicePixelsPerDesktopPixel();
 228   }
 229 %}
 230
 231   /*
 232   Title of the window.
 233   */
 234   attribute AString title;
 235 };