khtml_part.h

konqueror3 embedded版本, KDE环境下的当家浏览器的嵌入式版本源码包.

// -*- c-basic-offset: 2 -*-
/* This file is part of the KDE project
 *
 * Copyright (C) 1998, 1999 Torben Weis <[e-mail]>
 *                     1999-2001 Lars Knoll <[e-mail]>
 *                     1999-2001 Antti Koivisto <[e-mail]>
 *                     2000-2001 Simon Hausmann <[e-mail]>
 *                     2000-2001 Dirk Mueller <[e-mail]>
 *                     2000 Stefan Schimanski <[e-mail]>
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Library General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Library General Public License for more details.
 *
 * You should have received a copy of the GNU Library General Public License
 * along with this library; see the file COPYING.LIB.  If not, write to
 * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
 * Boston, MA 02110-1301, USA.
 */
#ifndef __khtml_part_h__
#define __khtml_part_h__

#include "dom/html_document.h"
#include "dom/dom2_range.h"

#include <kparts/part.h>
#include <kparts/browserextension.h>
#include <kdemacros.h>
#include <kfinddialog.h>

#include <qregexp.h>

class KHTMLPartPrivate;
class KHTMLPartBrowserExtension;
class KJSProxy;
class KHTMLView;
class KHTMLSettings;
class KJavaAppletContext;
class KJSErrorDlg;

namespace DOM
{
  class HTMLDocument;
  class HTMLDocumentImpl;
  class DocumentImpl;
  class HTMLTitleElementImpl;
  class HTMLElementImpl;
  class HTMLFrameElementImpl;
  class HTMLIFrameElementImpl;
  class HTMLObjectElementImpl;
  class HTMLFormElementImpl;
  class HTMLAnchorElementImpl;
  class HTMLMetaElementImpl;
  class NodeImpl;
  class Node;
  class HTMLEventListener;
  class EventListener;
}

namespace KJS
{
  class Interpreter;
}

namespace khtml
{
  class DocLoader;
  class RenderPart;
  class RenderPartObject;
  class ChildFrame;
  class MouseEvent;
  class MousePressEvent;
  class MouseDoubleClickEvent;
  class MouseMoveEvent;
  class MouseReleaseEvent;
  class DrawContentsEvent;
  class CachedObject;
  class RenderWidget;
  class CSSStyleSelector;
  class HTMLTokenizer;
  class Decoder;
  class XMLTokenizer;
}

namespace KJS {
    class Window;
    class WindowFunc;
    class ExternalFunc;
    class JSEventListener;
    class JSLazyEventListener;
    class JSNodeFilter;
    class DOMDocument;
    class SourceFile;
    class ScheduledAction;
}

namespace KParts
{
  class PartManager;
  class LiveConnectExtension;
}

namespace KWallet
{
  class Wallet;
}

/**
 * This class is khtml's main class. It features an almost complete
 * web browser, and html renderer.
 *
 * The easiest way to use this class (if you just want to display an HTML
 * page at some URL) is the following:
 *
 * \code
 * KURL url = "http://www.kde.org";
 * KHTMLPart *w = new KHTMLPart();
 * w->openURL(url);
 * w->view()->resize(500, 400);
 * w->show();
 * \endcode
 *
 * Java and JavaScript are enabled by default depending on the user's
 * settings. If you do not need them, and especially if you display
 * unfiltered data from untrusted sources, it is strongly recommended to
 * turn them off. In that case, you should also turn off the automatic
 * redirect and plugins:
 *
 * \code
 * w->setJScriptEnabled(false);
 * w->setJavaEnabled(false);
 * w->setMetaRefreshEnabled(false);
 * w->setPluginsEnabled(false);
 * \endcode
 *
 * You may also wish to disable external references.  This will prevent KHTML
 * from loading images, frames, etc,  or redirecting to external sites.
 *
 * \code
 * w->setOnlyLocalReferences(true);
 * \endcode
 *
 * Some apps want to write their HTML code directly into the widget instead of
 * opening an url. You can do this in the following way:
 *
 * \code
 * QString myHTMLCode = ...;
 * KHTMLPart *w = new KHTMLPart();
 * w->begin();
 * w->write(myHTMLCode);
 * ...
 * w->end();
 * \endcode
 *
 * You can do as many calls to write() as you wish.  There are two
 * write() methods, one accepting a QString and one accepting a
 * @p char @p * argument. You should use one or the other
 * (but not both) since the method using
 * the @p char @p * argument does an additional decoding step to convert the
 * written data to Unicode.
 *
 * It is also possible to write content to the HTML part using the
 * standard streaming API from KParts::ReadOnlyPart. The usage of
 * the API is similar to that of the begin(), write(), end() process
 * described above as the following example shows:
 *
 * \code
 * KHTMLPart *doc = new KHTMLPart();
 * doc->openStream( "text/html", KURL() );
 * doc->writeStream( QCString( "<html><body><p>KHTML Rocks!</p></body></html>" ) );
 * doc->closeStream();
 * \endcode
 *
 * @short HTML Browser Widget
 * @author Lars Knoll ([e-mail])
 *
 */
class KHTML_EXPORT KHTMLPart : public KParts::ReadOnlyPart
{
  Q_OBJECT
  friend class KHTMLView;
  friend class DOM::HTMLTitleElementImpl;
  friend class DOM::HTMLFrameElementImpl;
  friend class DOM::HTMLIFrameElementImpl;
  friend class DOM::HTMLObjectElementImpl;
  friend class DOM::HTMLAnchorElementImpl;
  friend class DOM::HTMLMetaElementImpl;
  friend class DOM::NodeImpl;
  friend class KHTMLRun;
  friend class DOM::HTMLFormElementImpl;
  friend class khtml::RenderPartObject;
  friend class KJS::Window;
  friend class KJS::ScheduledAction;
  friend class KJS::JSNodeFilter;
  friend class KJS::WindowFunc;
  friend class KJS::ExternalFunc;
  friend class KJS::JSEventListener;
  friend class KJS::JSLazyEventListener;
  friend class KJS::DOMDocument;
  friend class KJS::SourceFile;
  friend class KJSProxy;
  friend class KHTMLPartBrowserExtension;
  friend class DOM::DocumentImpl;
  friend class DOM::HTMLDocumentImpl;
  friend class KHTMLPartBrowserHostExtension;
  friend class khtml::HTMLTokenizer;
  friend class khtml::XMLTokenizer;
  friend class khtml::RenderWidget;
  friend class khtml::CSSStyleSelector;
  friend class KHTMLPartIface;
  friend class KHTMLPartFunction;
  friend class KHTMLPopupGUIClient;

  Q_PROPERTY( bool javaScriptEnabled READ jScriptEnabled WRITE setJScriptEnabled )
  Q_PROPERTY( bool javaEnabled READ javaEnabled WRITE setJavaEnabled )
  Q_PROPERTY( bool autoloadImages READ autoloadImages WRITE setAutoloadImages )
  Q_PROPERTY( bool dndEnabled READ dndEnabled WRITE setDNDEnabled )
  Q_PROPERTY( bool pluginsEnabled READ pluginsEnabled WRITE setPluginsEnabled )
  Q_PROPERTY( bool onlyLocalReferences READ onlyLocalReferences WRITE setOnlyLocalReferences )
  Q_PROPERTY( QCString dcopObjectId READ dcopObjectId )
  Q_PROPERTY( bool modified READ isModified )

public:
  enum GUIProfile { DefaultGUI, BrowserViewGUI /* ... */ };

  /**
   * Constructs a new KHTMLPart.
   *
   * KHTML basically consists of two objects: The KHTMLPart itself,
   * holding the document data (DOM document), and the KHTMLView,
   * derived from QScrollView, in which the document content is
   * rendered in. You can specify two different parent objects for a
   * KHTMLPart, one parent for the KHTMLPart document and on parent
   * for the KHTMLView. If the second @p parent argument is 0L, then
   * @p parentWidget is used as parent for both objects, the part and
   * the view.
   */
  KHTMLPart( QWidget *parentWidget = 0, const char *widgetname = 0,
             QObject *parent = 0, const char *name = 0, GUIProfile prof = DefaultGUI );

  KHTMLPart( KHTMLView *view, QObject *parent = 0, const char *name = 0, GUIProfile prof = DefaultGUI );

  /**
   * Destructor.
   */
  virtual ~KHTMLPart();

  /**
   * Opens the specified URL @p url.
   *
   * Reimplemented from KParts::ReadOnlyPart::openURL .
   */
  virtual bool openURL( const KURL &url );

  /**
   * Stops loading the document and kills all data requests (for images, etc.)
   */
  virtual bool closeURL();

  /**
   * Called when a certain error situation (i.e. connection timed out) occurred.
   * The default implementation either shows a KIO error dialog or loads a more
   * verbose error description a as page, depending on the users configuration.
   * @p job is the job that signaled the error situation
   */
  virtual void showError( KIO::Job* job );

  /**
   * Returns a reference to the DOM HTML document (for non-HTML documents, returns null)
   */
  DOM::HTMLDocument htmlDocument() const;

  /**
   * Returns a reference to the DOM document.
   */
  DOM::Document document() const;

  /**
   * Returns the content of the source document.
   * @since 3.4
   */
   QString documentSource() const;

  /**
   * Returns the node that has the keyboard focus.
   */
  DOM::Node activeNode() const;

  /**
   * Returns a pointer to the KParts::BrowserExtension.
   */
  KParts::BrowserExtension *browserExtension() const;
  KParts::LiveConnectExtension *liveConnectExtension( const khtml::RenderPart *) const;
  KParts::BrowserHostExtension *browserHostExtension() const;

  /**
   * Returns a pointer to the HTML document's view.
   */
  KHTMLView *view() const;

  /**
   * Enable/disable Javascript support. Note that this will
   * in either case permanently override the default usersetting.
   * If you want to have the default UserSettings, don't call this
   * method.
   */
  void setJScriptEnabled( bool enable );

  /**
   * Returns @p true if Javascript support is enabled or @p false
   * otherwise.
   */
  bool jScriptEnabled() const;

  /**
   * Returns the JavaScript interpreter the part is using. This method is
   * mainly intended for applications which embed and extend the part and
   * provides a mechanism for adding additional native objects to the
   * interpreter (or removing the built-ins).
   *
   * One thing people using this method to add things to the interpreter must
   * consider, is that when you start writing new content to the part, the
   * interpreter is cleared. This includes both use of the
   * begin( const KURL &, int, int ) method, and the openURL( const KURL & )
   * method. If you want your objects to have a longer lifespan, then you must
   * retain a KJS::Object yourself to ensure that the reference count of your
   * custom objects never reaches 0. You will also need to re-add your
   * bindings everytime this happens - one way to detect the need for this is
   * to connect to the docCreated() signal, another is to reimplement the
   * begin() method.
   */
  KJS::Interpreter *jScriptInterpreter();

  /**
   * Enable/disable statusbar messages.
   * When this class wants to set the statusbar text, it emits
   * setStatusBarText(const QString & text)
   * If you want to catch this for your own statusbar, note that it returns
   * back a rich text string, starting with "<qt>".  This you need to
   * either pass this into your own QLabel or to strip out the tags
   * before passing it to QStatusBar::message(const QString & message)
   *
   * @see KParts::Part::setStatusBarText( const QString & text )
   */
  void setStatusMessagesEnabled( bool enable );

  /**
   * Returns @p true if status messages are enabled.
   */
  bool statusMessagesEnabled() const;

  /**
   * Enable/disable automatic forwarding by &lt;meta http-equiv="refresh" ....&gt;
   */
  void setMetaRefreshEnabled( bool enable );

  /**
   * Returns @p true if automatic forwarding is enabled.
   */
  bool metaRefreshEnabled() const;

  /**
   * Same as executeScript( const QString & ) except with the Node parameter
   * specifying the 'this' value.
   */
  QVariant executeScript( const DOM::Node &n, const QString &script );

  /**
   * Enables or disables Drag'n'Drop support. A drag operation is started if
   * the users drags a link.
   */
  void setDNDEnabled( bool b );

  /**
   * Returns whether Dragn'n'Drop support is enabled or not.
   */
  bool dndEnabled() const;

  /**
   * Enables/disables Java applet support. Note that calling this function
   * will permanently override the User settings about Java applet support.
   * Not calling this function is the only way to let the default settings
   * apply.
   */
  void setJavaEnabled( bool enable );

  /**
   * Return true if Java applet support is enabled, false if disabled
   */
  bool javaEnabled() const;

  /**
   * Returns the java context of the applets. If no applet exists, 0 is returned.
   */
  KJavaAppletContext *javaContext();

  /**
   * Returns the java context of the applets. If no context exists yet, a
   * new one is created.
   */
  KJavaAppletContext *createJavaContext();

  /**
   * Enables or disables plugins, default is enabled
   */
  void setPluginsEnabled( bool enable );

  /**
   * Returns true if plugins are enabled/disabled.
   */
  bool pluginsEnabled() const;

  /**
   * Specifies whether images contained in the document should be loaded