gecko-dev/widget/nsIBaseWindow.idl

/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
 *
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"
#include "nsrootidl.idl"
/*#include "nsIWidget.idl"  Boy this would be nice.*/

[ptr] native nsIWidget(nsIWidget);
%{C++
#include "Units.h"
#include "mozilla/DimensionRequest.h"

class nsIWidget;
%}

typedef voidPtr nativeWindow;
native DimensionRequest(mozilla::DimensionRequest&&);
native DimensionKind(mozilla::DimensionKind);

/**
 * The nsIBaseWindow describes a generic window and basic operations that
 * can be performed on it.  This is not to be a complete windowing interface
 * but rather a common set that nearly all windowed objects support.
 */

[scriptable, builtinclass, uuid(ca635529-a977-4552-9b8a-66187e54d882)]
interface nsIBaseWindow : nsISupports
{
  /*
  Allows a client to initialize an object implementing this interface with
  the usually required window setup information.
  It is possible to pass null for both parentNativeWindow and parentWidget,
  but only docshells support this.

  @param parentNativeWindow - This allows a system to pass in the parenting
    window as a native reference rather than relying on the calling
    application to have created the parent window as an nsIWidget.  This
    value will be ignored (should be nullptr) if an nsIWidget is passed in to
    the parentWidget parameter.

  @param parentWidget - This allows a system to pass in the parenting widget.
    This allows some objects to optimize themselves and rely on the view
    system for event flow rather than creating numerous native windows.  If
    one of these is not available, nullptr should be passed.

  @param x - This is the x co-ordinate relative to the parent to place the
    window.

  @param y - This is the y co-ordinate relative to the parent to place the
    window.

  @param cx - This is the width  for the window to be.

  @param cy - This is the height for the window to be.

  @return  NS_OK - Window Init succeeded without a problem.
        NS_ERROR_UNEXPECTED - Call was unexpected at this time. Perhaps
          initWindow() had already been called.
        NS_ERROR_INVALID_ARG - controls that require either a parentNativeWindow
          or a parentWidget may return invalid arg when they do not
          receive what they are needing.
  */
  [noscript]void initWindow(in nativeWindow parentNativeWindow,
    in nsIWidget parentWidget,  in long x, in long y, in long cx, in long cy);

  /*
  Tell the window that it should destroy itself.  This call should not be
  necessary as it will happen implictly when final release occurs on the
  object.  If for some reaons you want the window destroyed prior to release
  due to cycle or ordering issues, then this call provides that ability.

  @return  NS_OK - Everything destroyed properly.
        NS_ERROR_UNEXPECTED - This call was unexpected at this time.
          Perhaps create() has not been called yet.
  */
  void destroy();

  /*
  Sets the current x and y coordinates of the control.  This is relative to
  the parent window.
  */
  void setPosition(in long x, in long y);

  /*
  Ditto, with arguments in global desktop pixels rather than (potentially
  ambiguous) device pixels
  */
  void setPositionDesktopPix(in long x, in long y);

  /*
  Gets the current x and y coordinates of the control.  This is relative to the
  parent window.
  */
  void getPosition(out long x, out long y);

%{C++
  mozilla::LayoutDeviceIntPoint GetPosition() {
    int32_t x = 0, y = 0;
    GetPosition(&x, &y);
    return mozilla::LayoutDeviceIntPoint(x, y);
  }
%}

  /*
  Sets the width and height of the control.
  */
  void setSize(in long cx, in long cy, in boolean fRepaint);

  /*
  Gets the width and height of the control.
  */
  void getSize(out long cx, out long cy);

%{C++
  mozilla::LayoutDeviceIntSize GetSize() {
    int32_t w = 0, h = 0;
    GetSize(&w, &h);
    return mozilla::LayoutDeviceIntSize(w, h);
  }
%}

  /**
   * The 'flags' argument to setPositionAndSize is a set of these bits.
   */
  const unsigned long eRepaint = 1;
  const unsigned long eDelayResize = 2;

  /*
  Convenience function combining the SetPosition and SetSize into one call.
  Also is more efficient than calling both.
  */
  void setPositionAndSize(in long x, in long y, in long cx, in long cy,
    in unsigned long flags);

  /*
  Convenience function combining the GetPosition and GetSize into one call.
  Also is more efficient than calling both.
  */
  void getPositionAndSize(out long x, out long y, out long cx, out long cy);

%{C++
  mozilla::LayoutDeviceIntRect GetPositionAndSize() {
    int32_t x = 0, y = 0, w = 0, h = 0;
    GetPositionAndSize(&x, &y, &w, &h);
    return mozilla::LayoutDeviceIntRect(x, y, w, h);
  }
%}

  /**
   * Allows to request the change of individual dimensions without specifying
   * the other components.
   *
   * @param aRequest - The requested change. A request to change only the width
   *                   may look like:
   *                   {DimensionKind::Outer, Nothing(), Nothing(), Some(20), Nothing()}
   *
   * Note: Inner position is not supported.
   *
   * @see DimensionRequest
   */
  [noscript] void setDimensions(in DimensionRequest aRequest);

  /**
   * Gets the dimensions of the window. The caller may pass nullptr for any
   * value it is uninterested in receiving.
   *
   * @param aDimensionKind  Specifies whether the dimensions are in reference
   *                        to the inner or outer dimensions.
   * @param aX              Left hand corner of the outer area; or nullptr.
   * @param aY              Top corner of the outer area; or nullptr.
   * @param aCX             Width of the inner or outer area; or nullptr.
   * @param aCY             Height of the inner or outer area; or nullptr.
   *
   * Note: Inner position is not supported.
   *
   * @see DimensionRequest
   */
  [noscript] void getDimensions(in DimensionKind aDimensionKind, out long aX, out long aY, out long aCX, out long aCY);

  /**
   * Tell the window to repaint itself
   * @param aForce - if true, repaint immediately
   *                 if false, the window may defer repainting as it sees fit.
   */
  void repaint(in boolean force);

  /*
  This is the parenting widget for the control.  This may be null if the
  native window was handed in for the parent during initialization.
  If this  is returned, it should refer to the same object as
  parentNativeWindow.

  Setting this after Create() has been called may not be supported by some
  implementations.

  On controls that don't support widgets, setting this will return a
  NS_ERROR_NOT_IMPLEMENTED error.
  */
  [noscript] attribute nsIWidget parentWidget;

  /*
  This is the native window parent of the control.

  Setting this after Create() has been called may not be supported by some
  implementations.

  On controls that don't support setting nativeWindow parents, setting this
  will return a NS_ERROR_NOT_IMPLEMENTED error.
  */
  [noscript] attribute nativeWindow parentNativeWindow;

  /*
  This is the handle (HWND, GdkWindow*, ...) to the native window of the
  control, exposed as an AString.

  @return AString in hex format with "0x" prepended, or empty string if
  mainWidget undefined

  @throws NS_ERROR_NOT_IMPLEMENTED for non-XULWindows
  */
  readonly attribute AString nativeHandle;

  /*
  Attribute controls the visibility of the object behind this interface.
  Setting this attribute to false will hide the control.  Setting it to
  true will show it.
  */
  attribute boolean visibility;

  /*
  a disabled window should accept no user interaction; it's a dead window,
  like the parent of a modal window.
  */
  attribute boolean enabled;

  /*
  Allows you to find out what the widget is of a given object.  Depending
  on the object, this may return the parent widget in which this object
  lives if it has not had to create its own widget.
  */
  [noscript] readonly attribute nsIWidget mainWidget;

  /*
  The number of device pixels per CSS pixel used by this window's widget at the
  default full zoom level.
  This is the value returned by GetDefaultScale() of the underlying widget.
  Note that this may change if the window is moved between screens with
  differing resolutions.
  NOTE: This is mostly an implementation detail of
  UnscaledDevicePixelsPerCSSPixel, which is what you probably want to use.
  */
  [noscript, notxpcom, nostdcall] readonly attribute double widgetCSSToDeviceScale;

%{C++
  // The number of device pixels per CSS pixel used on this window's current
  // screen at the default full zoom level.
  //
  // This is the widget scale _plus_ the OS zoom scale if appropriate.
  // Implemented in AppWindow.cpp
  mozilla::CSSToLayoutDeviceScale UnscaledDevicePixelsPerCSSPixel();
%}

  /*
  The number of device pixels per display pixel on this window's current
  screen. (The meaning of "display pixel" varies across OS environments;
  it is the pixel units used by the desktop environment to manage screen
  real estate and window positioning, which may correspond to (per-screen)
  device pixels, or may be a virtual coordinate space that covers a multi-
  monitor, mixed-dpi desktop space.)
  This is the value returned by GetDesktopToDeviceScale() of the underlying
  widget.
  Note that this may change if the window is moved between screens with
  differing resolutions.
  */
  readonly attribute double devicePixelsPerDesktopPixel;

%{C++
  mozilla::DesktopToLayoutDeviceScale DevicePixelsPerDesktopPixel() {
    double s = 1.0;
    GetDevicePixelsPerDesktopPixel(&s);
    return mozilla::DesktopToLayoutDeviceScale(s);
  }

  mozilla::CSSToDesktopScale GetUnscaledCSSToDesktopScale() {
    return UnscaledDevicePixelsPerCSSPixel() / DevicePixelsPerDesktopPixel();
  }
%}

  /*
  Title of the window.
  */
  attribute AString title;
};