gecko-dev/docshell/base/nsIDocShell.idl

/* -*- Mode: IDL; tab-width: 4; 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 the Mozilla browser.
 * 
 * The Initial Developer of the Original Code is Netscape
 * Communications, Inc.  Portions created by Netscape are
 * Copyright (C) 1999, Mozilla.  All Rights Reserved.
 * 
 * Contributor(s):
 *   Travis Bogard <travis@netscape.com>
 *   Steve Clark <buster@netscape.com>
 */

#include "nsISupports.idl"
#include "domstubs.idl"
#include "nsIURIContentListener.idl"
#include "nsIURI.idl"
#include "nsIContentViewer.idl"

%{ C++
#include "nsIPresContext.h"
#include "nsIDocumentLoaderObserver.h"
%}

/**
 * The nsIDocShell
 */

[ptr] native nsIPresContext(nsIPresContext);
[ptr] native nsIPresShell(nsIPresShell);

interface nsIChromeEventHandler;
interface nsIDocumentLoaderObserver;
interface nsIDocShellLoadInfo;
interface nsIDocumentCharsetInfo;
interface nsIWebNavigation;

[scriptable, uuid(69E5DE00-7B8B-11d3-AF61-00A024FFC08C)]
interface nsIDocShell : nsISupports
{
	/*
	Loads a given URI.  This will give priority to loading the requested URI
	in the object implementing	this interface.  If it can't be loaded here
	however, the URL dispatcher will go through its normal process of content
	loading.

	@param uri - The URI to load.
	@param loadInfo - This is the extended load info for this load.  This
	    most often will be null, but if you need to do additional setup for
		this load you can get a loadInfo object by calling createLoadInfo.
		Once you have this object you can set the needed properties on it and
		then pass it to loadURI.
	@param aLoadFlags - Flags to modify load behaviour. Flags are defined
	    in nsIWebNavigation.
	*/
	[noscript]void loadURI(in nsIURI uri, in nsIDocShellLoadInfo loadInfo, in unsigned long aLoadFlags);

	/*
	Loads a given stream. This will give priority to loading the requested stream
	in the object implementing this interface. If it can't be loaded here however,
	the URL dispatched will go through its normal process of content loading.

	@param aStream - The input stream that provides access to the data to be loaded.
	@param aURI	   - The URI representing the stream, or null.
	@param aContentType - The type (MIME) of data being loaded.
	@param aContentLen  - The length (in bytes) of the stream.  If you don't know
        the length of the stream this can be -1.
	@param aLoadInfo - This is the extended load info for this load.  This most
		most often will be null, but if you need to do additional setup for this
		load you can get a loadInfo object by calling createLoadInfo.  Once you have
		this object you can set the needed properties on it and then pass it to 
		loadURI.
	*/
	[noscript]void loadStream(in nsIInputStream aStream, in nsIURI aURI,
							  in string aContentType, in long aContentLen,
							  in nsIDocShellLoadInfo aLoadInfo);

	/*
	Creates a DocShellLoadInfo object that you can manipulate and then pass to 
	loadURI.
	*/
	void createLoadInfo(out nsIDocShellLoadInfo loadInfo);

	/*
	Stops a current load.  This simply stops the network portion of the load.
	If you wish to do a complete stop, then you should us the
	nsIWebNavigation::Stop() method. 
	*/
	void stopLoad();

  /* clients may get and set an nsIDocumentLoaderObserver, which will be notified
   * during loadURI, loadURIVia, and setDocument
   */
   attribute nsIDocumentLoaderObserver docLoaderObserver;

	/*
	Presentation context for the currently loaded document.  This may be null.
	*/
	[noscript] readonly attribute nsIPresContext presContext;

	/*
	Presentation context for the currently loaded document.  This may be null.
	*/
	[noscript] readonly attribute nsIPresShell presShell;

	/*
	Content Viewer that is currently loaded for this DocShell.  This may change
	as the underlying content changes.
	*/
	readonly attribute nsIContentViewer contentViewer;

	/*
	This attribute allows chrome to tie in to handle DOM events that may be of
	interest to chrome.
	*/
	attribute nsIChromeEventHandler chromeEventHandler;

	/*
	URI content listener parent.  This is not refcounted and is assumed to be
	nulled out by the parent when the parent is going away.
	*/
	attribute nsIURIContentListener parentURIContentListener;

   /*
	The document charset info.  This is used by a load to determine priorities for 
	charset detection etc.
	*/
	attribute nsIDocumentCharsetInfo documentCharsetInfo;

	/*
	Attribute stating if it should allow plugins or not.
	*/
	attribute boolean allowPlugins;

	/*
	Definitions for the viewModes the docShell can be in.
	*/
	const long viewNormal=0;
	const long viewSource=1;

	/*
	This is the mode that the docShell is in for viewing when a load occurs.
	*/
	attribute long viewMode;

	/**
	* Set/Get the document scale factor.  When setting this attribute, a
	* NS_ERROR_NOT_IMPLEMENTED error may be returned by implementations
	* not supporting zoom.  Implementations not supporting zoom should return
	* 1.0 all the time for the Get operation.  1.0 by the way is the default
	* of zoom.  This means 100% of normal scaling or in other words normal size
	* no zoom. 
	*/
	attribute float zoom;

	/*
	XXX Comment here!
	*/
	attribute long marginWidth;

	/*
	XXX Comment here!
	*/
	attribute long marginHeight;
};