gecko-dev/gfx2/public/nsITopLevelWindow.idl

/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
 *
 * The contents of this file are subject to the Mozilla Public
 * License Version 1.1 (the "License"); you may not use this file
 * except in compliance with the License. You may obtain a copy of
 * the License at http://www.mozilla.org/MPL/
 * 
 * Software distributed under the License is distributed on an "AS
 * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
 * implied. See the License for the specific language governing
 * rights and limitations under the License.
 * 
 * The Original Code is mozilla.org code.
 * 
 * The Initial Developer of the Original Code is Netscape
 * Communications Corporation. Portions created by Netscape are
 * Copyright (C) 2000 Netscape Communications Corporation. All
 * Rights Reserved.
 * 
 * Contributor(s): 
 *   Stuart Parmenter <pavlov@netscape.com>
 *   Rod Spears <rods@netscape.com>
 *   Kevin McCluskey <kmcclusk@netscape.com>
 *   Mike Pinkerton <pinkerton@netscape.com>
 *   ... and other people
 */

#include "nsISupports.idl"
#include "gfxtypes.idl"

interface nsIImage;
interface nsIWindow;
interface nsIPixmap;

/**
 * nsITopLevelWindow interface
 *
 * @author Stuart Parmenter <pavlov@netscape.com>
 * @version 0.0
 * @see nsIWindow
 * @see "gfx2"
 */
[scriptable, uuid(e820e062-1dd1-11b2-b677-cd3faed4a440)]
interface nsITopLevelWindow : nsISupports
{

  /**
   * border styles
   * @name toplevel_window_border_styles Top-level window Border Styles
   * @attention rename these.  eBorderStyle_ is silly
   */

  //@{
  /// whatever the OS wants... i.e. don't do anything
  const long eBorderStyle_default  = -1;

  /// no border, titlebar, etc.. opposite of all
  const long eBorderStyle_none     = 0;

  /// all window decorations
  const long eBorderStyle_all      = 1 << 0;

  /**
   * enables the border on the window.
   * @note these are only for decoration and are not resize hadles.
   */
  const long eBorderStyle_border   = 1 << 1;

  /**
   * enables the resize handles for the window.
   * @note If this is set, border is implied to also be set
   */
  const long eBorderStyle_resizeh  = 1 << 2;

  /// enables the titlebar for the window
  const long eBorderStyle_title    = 1 << 3;

  /**
   * enables the window menu button on the title bar.  this being
   * on should force the title bar to display
   */
  const long eBorderStyle_menu     = 1 << 4;

  /**
   * enables the minimize button so the user can minimize the window.
   * turned off for tranient windows since they can not be minimized
   * seperate from their parent
   */
  const long eBorderStyle_minimize = 1 << 5;

  /// enables the maxmize button so the user can maximize the window
  const long eBorderStyle_maximize = 1 << 6;

  /// show the close button
  const long eBorderStyle_close    = 1 << 7;
  //@}


  /**
   * Initialize a top level window
   *
   * @param aParent  the parent window
   * @param aX       the x position, in pixels, relative to aParent.
   * @param aY       the y position, in pixels, relative to aParent.
   * @param aWidth   the width, in pixels, of the window.
   * @param aHeight  the height in pixels, of the window.
   * @param aBorder  A bitfield of border styles
   *
   * @attention should you only be able to parent top level windows to
   *            other top level windows?
   *
   * @note This window represents a window that can be drawn into via
   *       a query interface to nsIDrawable.
   * @note This window can also be the parent for nsIWindow objects.
   */
  void init(in nsIWindow aParent,
            in gfx_coord aX,
            in gfx_coord aY,
            in gfx_dimension aWidth,
            in gfx_dimension aHeight,
            in long aBorder);

  /**
   * Minimize, maximize, restore
   *
   * getting:
   * normal   == !(minimize || maximize)
   * minimize == !(normal || maximize)
   * maximize == !(normal || minimize)
   *
   * setting:
   * normal will restore a minimized or maximized window to its "normal" state.
   */
  attribute long sizeState;

  /**
   * Perform platform-dependent sanity check on a potential window position.
   * This is guaranteed to work only for top-level windows.
   *
   * @param aX in: an x position expressed in screen coordinates.
   *           out: the x position constrained to fit on the screen(s).
   * @param aY in an y position expressed in screen coordinates.
   *           out: the y position constrained to fit on the screen(s).
   *
   */
  void constrainPosition(inout gfx_coord aX, inout gfx_coord aY);

  /**
   * Bring the window to the top (infront of all other windows)
   */
  void bringToTop();

  /**
   * Sets the title of the window
   */
  attribute wstring title;

  /* some getbounds like thing that lets you get size+border? */

  /**
   * Sets the icon for this window
   */
  void setIcon(in nsIImage image);


  /**
   * set the window class
   * @attention is this only needed for unix?
   *            It would be nice to have the XP code set this
   */
  attribute string windowClass;

  /**
   * eeeeeek!
   * @attention NEEDS DOCS
   * @warning this may not be implemented on all platforms
   * @exception NS_ERROR_NOT_IMPLEMENTED If this is not implemented.
   */
  void setTransparency(in nsIPixmap mask);
};