gecko-dev/gfx2/public/nsIRegion.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) 1999-2000 Netscape Communications Corporation.
 * All Rights Reserved.
 * 
 * Contributor(s): 
 *   Mike Pinkerton <pinkerton@netscape.com>
 *   Stuart Parmenter <pavlov@netscape.com>
 */

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

/**
 * nsIRegion interface
 *
 * @author Stuart Parmenter <pavlov@netscape.com>
 * @version 1.1
 * @see "gfx2"
 **/
[scriptable, uuid(85da5ba0-1dd2-11b2-be02-970202b0f7d5)]
interface nsIRegion : nsISupports
{
  /**
   * Initialize the region to an empty state
   * @note rename to setEmpty() ?
   **/
  void init();

  /**
   * Create a clone of the current region.
   **/
  nsIRegion copy();

  /**
   * copy operator equivalent that takes another region
   *
   * @param      region to copy
   **/
  void setToRegion(in nsIRegion aRegion);

  /**
   * copy operator equivalent that takes a rect
   *
   * @param aX      The x-coordinate of rect to set region to
   * @param aY      The y-coordinate of rect to set region to
   * @param aWidth  The width of rect to set region to
   * @param aHeight The height of rect to set region to
   **/
  void setToRect(in gfx_coord aX,
                 in gfx_coord aY,
                 in gfx_dimension aWidth,
                 in gfx_dimension aHeight);

  /**
   * destructively intersect another region with this one
   *
   * @param      region to intersect
   **/
  void intersectRegion(in nsIRegion aRegion);

  /**
   * destructively intersect a rect with this region
   *
   * @param aX      The x-coordinate of rect to intersect with region
   * @param aY      The y-coordinate of rect to intersect with region
   * @param aWidth  The width of rect to intersect with region
   * @param aHeight The height of rect to intersect with region
   **/
  void intersectRect(in gfx_coord aX,
                     in gfx_coord aY,
                     in gfx_dimension aWidth,
                     in gfx_dimension aHeight);

  /**
   * destructively union another region with this one
   *
   * @param      region to union
   **/
  void unionRegion(in nsIRegion aRegion);

  /**
   * destructively union a rect with this region
   *
   * @param aX      The x-coordinate of rect to union with region
   * @param aY      The y-coordinate of rect to union with region
   * @param aWidth  The width of rect to union with region
   * @param aHeight The height of rect to union with region
   **/
  void unionRect(in gfx_coord aX,
                 in gfx_coord aY,
                 in gfx_dimension aWidth,
                 in gfx_dimension aHeight);

  /**
   * destructively subtract another region with this one
   *
   * @param region to subtract
   **/
  void subtractRegion(in nsIRegion aRegion);

  /**
   * Destructively subtract a rect from this region
   *
   * @param aX      xoffset of rect to subtract with region
   * @param aY      yoffset of rect to subtract with region
   * @param aWidth  width of rect to subtract with region
   * @param aHeight height of rect to subtract with region
   **/
  void subtractRect(in gfx_coord aX,
                    in gfx_coord aY,
                    in gfx_dimension aWidth,
                    in gfx_dimension aHeight);
  
  /**
   * is this region empty?
   *
   * @return returns whether the region is empty
   **/
  boolean isEmpty();

  /**
   * operator == equivalent i.e. do the regions contain exactly
   * the same pixels
   *
   * @param aRegion The region to compare.
   * @return Whether the regions are identical.
   **/
  boolean isEqual(in nsIRegion aRegion);

  /**
   * returns the bounding box of the region i.e. the smallest
   * rectangle that completely contains the region.        
   *
   * @param aX out parameter for xoffset of bounding rect for region
   * @param aY out parameter for yoffset of bounding rect for region
   * @param aWidth out parameter for width of bounding rect for region
   * @param aHeight out parameter for height of bounding rect for region
   **/
  void getBoundingBox(out gfx_coord aX,
                      out gfx_coord aY,
                      out gfx_dimension aWidth,
                      out gfx_dimension aHeight);

  /**
   * Offset the region by (x,y)
   *
   * @param aXOffset The x-coordinate offset.
   * @param aYOffset The y-coordinate offset.
   **/
  void offsetBy(in gfx_coord aXOffset,
                in gfx_coord aYOffset);

  /**
   * does the region intersect the rectangle?
   *
   * @param      rect to check for containment
   * @return     true if the region intersects the rect
   *
   **/
  boolean containsRect(in gfx_coord aX,
                       in gfx_coord aY,
                       in gfx_dimension aWidth,
                       in gfx_dimension aHeight);

  /**
   * Get an array of rectangles that make up this region.
   *
   * @param rects An array of nsRect2 structs that make up the region.
   * @param nrects The number rects that make up this region.
   *
   * @note i'd like to be able to do this without allocating...
   **/
  [noscript] void getRects([array, size_is(nrects)] out nsRect2 rects,
                           out unsigned long nrects);

  /**
   * get the number of rects which make up this region.
   *
   * @return  number containing the number of rects
   *          comprising the region
   *
   **/
  readonly attribute unsigned long numRects;
};