• Skip to content
  • Skip to link menu
KDE 4.0 API Reference
  • KDE API Reference
  • kdelibs
  • Sitemap
  • Contact Us
 

KHTML

KHTMLPart Class Reference

#include <khtml_part.h>

Inheritance diagram for KHTMLPart:

Inheritance graph
[legend]

List of all members.


Detailed Description

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:

 KUrl url = "http://www.kde.org";
 KHTMLPart *w = new KHTMLPart();
 w->openUrl(url);
 w->view()->resize(500, 400);
 w->show();

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:

 w->setJScriptEnabled(false);
 w->setJavaEnabled(false);
 w->setMetaRefreshEnabled(false);
 w->setPluginsEnabled(false);

You may also wish to disable external references. This will prevent KHTML from loading images, frames, etc, or redirecting to external sites.

 w->setOnlyLocalReferences(true);

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:

 QString myHTMLCode = ...;
 KHTMLPart *w = new KHTMLPart();
 w->begin();
 w->write(myHTMLCode);
 ...
 w->end();

You can do as many calls to write() as you wish. There are two write() methods, one accepting a QString and one accepting a char * argument. You should use one or the other (but not both) since the method using the char * 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:

 KHTMLPart *doc = new KHTMLPart();
 doc->openStream( "text/html", KUrl() );
 doc->writeStream( QCString( "<html><body><p>KHTML Rocks!</p></body></html>" ) );
 doc->closeStream();

HTML Browser Widget

Author:
Lars Knoll (knoll@kde.org)

Definition at line 186 of file khtml_part.h.


Public Types

enum  GUIProfile { DefaultGUI, BrowserViewGUI }
enum  CaretDisplayPolicy { CaretVisible, CaretInvisible, CaretBlink }
enum  FindOptions { FindLinksOnly = 1 * KFind::MinimumUserOption, FindNoPopups = 2 * KFind::MinimumUserOption }
enum  FormNotification { NoNotification = 0, Before, Only, Unused = 255 }

Public Slots

void setActiveNode (const DOM::Node &node)
void stopAnimations ()
QVariant executeScript (const QString &script)
void setCaretMode (bool enable)
void setEditable (bool enable)
void setCaretVisible (bool show)
void submitFormProxy (const char *action, const QString &url, const QByteArray &formData, const QString &target, const QString &contentType=QString(), const QString &boundary=QString())

Signals

void onURL (const QString &url)
void popupMenu (const QString &url, const QPoint &point)
void selectionChanged ()
void nodeActivated (const DOM::Node &)
void docCreated ()
void caretPositionChanged (const DOM::Node &node, long offset)
void formSubmitNotification (const char *action, const QString &url, const QByteArray &formData, const QString &target, const QString &contentType, const QString &boundary)
void configurationChanged ()

Public Member Functions

 KHTMLPart (QWidget *parentWidget=0, QObject *parent=0, GUIProfile prof=DefaultGUI)
 KHTMLPart (KHTMLView *view, QObject *parent=0, GUIProfile prof=DefaultGUI)
virtual ~KHTMLPart ()
virtual bool openUrl (const KUrl &url)
virtual bool closeUrl ()
virtual void showError (KJob *job)
DOM::HTMLDocument htmlDocument () const
DOM::Document document () const
QString documentSource () const
DOM::Node activeNode () const
KParts::BrowserExtension * browserExtension () const
KParts::BrowserHostExtension * browserHostExtension () const
KHTMLView * view () const
void setJScriptEnabled (bool enable)
bool jScriptEnabled () const
KJS::Interpreter * jScriptInterpreter ()
void setStatusMessagesEnabled (bool enable)
bool statusMessagesEnabled () const
void setMetaRefreshEnabled (bool enable)
bool metaRefreshEnabled () const
QVariant executeScript (const DOM::Node &n, const QString &script)
void setDNDEnabled (bool b)
bool dndEnabled () const
void setJavaEnabled (bool enable)
bool javaEnabled () const
void setPluginsEnabled (bool enable)
bool pluginsEnabled () const
void setAutoloadImages (bool enable)
bool autoloadImages () const
void setOnlyLocalReferences (bool enable)
bool onlyLocalReferences () const
bool isCaretMode () const
bool isEditable () const
void setCaretPosition (DOM::Node node, long offset, bool extendSelection=false)
CaretDisplayPolicy caretDisplayPolicyNonFocused () const
void setCaretDisplayPolicyNonFocused (CaretDisplayPolicy policy)
KUrl baseURL () const
KUrl backgroundURL () const
void scheduleRedirection (int delay, const QString &url, bool lockHistory=true)
virtual void begin (const KUrl &url=KUrl(), int xOffset=0, int yOffset=0)
virtual void write (const char *str, int len=-1)
virtual void write (const QString &str)
virtual void end ()
void paint (QPainter *, const QRect &, int=0, bool *=0)
bool setEncoding (const QString &name, bool override=false)
QString encoding () const
void setUserStyleSheet (const KUrl &url)
void setUserStyleSheet (const QString &styleSheet)
void setStandardFont (const QString &name)
void setFixedFont (const QString &name)
bool gotoAnchor (const QString &name)
bool nextAnchor ()
bool prevAnchor ()
void setURLCursor (const QCursor &c)
QCursor urlCursor () const
void findText ()
void findText (const QString &str, long options, QWidget *parent=0, KFindDialog *findDialog=0)
void findTextBegin ()
bool findTextNext (bool reverse=false)
void setZoomFactor (int percent)
int zoomFactor () const
void setFontScaleFactor (int percent)
int fontScaleFactor () const
virtual QString selectedText () const
QString selectedTextAsHTML () const
DOM::Range selection () const
void selection (DOM::Node &startNode, long &startOffset, DOM::Node &endNode, long &endOffset) const
void setSelection (const DOM::Range &)
bool hasSelection () const
void selectAll ()
void show ()
void hide ()
KParts::PartManager * partManager ()
virtual void saveState (QDataStream &stream)
virtual void restoreState (QDataStream &stream)
DOM::Node nodeUnderMouse () const
DOM::Node nonSharedNodeUnderMouse () const
const KHTMLSettings * settings () const
KHTMLPart * parentPart ()
QStringList frameNames () const
QList< KParts::ReadOnlyPart * > frames () const
KHTMLPart * findFrame (const QString &f)
KHTMLPart * findFrameParent (KParts::ReadOnlyPart *callingPart, const QString &f, khtml::ChildFrame **childFrame=0)
KParts::ReadOnlyPart * currentFrame () const
bool frameExists (const QString &frameName)
KJSProxy * framejScript (KParts::ReadOnlyPart *framePart)
KParts::ReadOnlyPart * findFramePart (const QString &f)
void setJSStatusBarText (const QString &text)
void setJSDefaultStatusBarText (const QString &text)
QString jsStatusBarText () const
QString jsDefaultStatusBarText () const
QString referrer () const
QString pageReferrer () const
QString lastModified () const
void preloadStyleSheet (const QString &url, const QString &stylesheet)
void preloadScript (const QString &url, const QString &script)
bool restored () const
void setFormNotification (FormNotification fn)
FormNotification formNotification () const
KUrl toplevelURL ()
bool isModified () const
void setSuppressedPopupIndicator (bool enable, KHTMLPart *originPart=0)
bool inProgress () const

Protected Types

enum  PageSecurity { NotCrypted, Encrypted, Mixed }

Protected Slots

virtual void slotFinished (KJob *)

Protected Member Functions

KUrl completeURL (const QString &url)
void htmlError (int errorCode, const QString &text, const KUrl &reqUrl)
virtual void customEvent (QEvent *event)
virtual void khtmlMousePressEvent (khtml::MousePressEvent *event)
virtual void khtmlMouseDoubleClickEvent (khtml::MouseDoubleClickEvent *)
virtual void khtmlMouseMoveEvent (khtml::MouseMoveEvent *event)
virtual void khtmlMouseReleaseEvent (khtml::MouseReleaseEvent *event)
virtual void khtmlDrawContentsEvent (khtml::DrawContentsEvent *)
virtual void guiActivateEvent (KParts::GUIActivateEvent *event)
virtual bool openFile ()
virtual bool urlSelected (const QString &url, int button, int state, const QString &_target, const KParts::OpenUrlArguments &args=KParts::OpenUrlArguments(), const KParts::BrowserArguments &browserArgs=KParts::BrowserArguments())
virtual KParts::ReadOnlyPart * createPart (QWidget *parentWidget, QObject *parent, const QString &mimetype, QString &serviceName, QStringList &serviceTypes, const QStringList &params)
bool pluginPageQuestionAsked (const QString &mimetype) const
void setPluginPageQuestionAsked (const QString &mimetype)
void setPageSecurity (PageSecurity sec)
virtual bool doOpenStream (const QString &mimeType)
virtual bool doWriteStream (const QByteArray &data)
virtual bool doCloseStream ()
virtual void startingJob (KIO::Job *)

Properties

bool javaScriptEnabled
bool javaEnabled
bool dndEnabled
bool pluginsEnabled
bool modified
QString encoding
QString lastModified
bool metaRefreshEnabled

Friends

class KHTMLView
class DOM::HTMLTitleElementImpl
class DOM::HTMLFrameElementImpl
class DOM::HTMLIFrameElementImpl
class DOM::HTMLObjectBaseElementImpl
class DOM::HTMLObjectElementImpl
class DOM::HTMLAnchorElementImpl
class DOM::HTMLMetaElementImpl
class DOM::NodeImpl
class KHTMLRun
class DOM::HTMLFormElementImpl
class KJS::Window
class KJS::ScheduledAction
class KJS::JSNodeFilter
class KJS::WindowFunc
class KJS::ExternalFunc
class KJS::JSEventListener
class KJS::JSLazyEventListener
class KJS::DOMDocument
class KJS::HTMLElement
class KJS::SourceFile
class KJSProxy
class KHTMLPartBrowserExtension
class DOM::DocumentImpl
class DOM::HTMLDocumentImpl
class KHTMLPartBrowserHostExtension
class khtml::HTMLTokenizer
class khtml::XMLTokenizer
class khtml::RenderWidget
class khtml::CSSStyleSelector
class KHTMLPartIface
class KHTMLPartFunction
class KHTMLPopupGUIClient
class KHTMLPartPrivate

Member Enumeration Documentation

enum KHTMLPart::GUIProfile

Enumerator:
DefaultGUI 
BrowserViewGUI 

Definition at line 240 of file khtml_part.h.

enum KHTMLPart::CaretDisplayPolicy

Enumeration for displaying the caret.

Enumerator:
CaretVisible  caret is displayed
CaretInvisible  caret is not displayed
CaretBlink  caret toggles between visible and invisible

Definition at line 498 of file khtml_part.h.

enum KHTMLPart::FindOptions

Extra Find options that can be used when calling the extended findText().

Enumerator:
FindLinksOnly 
FindNoPopups 

Definition at line 694 of file khtml_part.h.

enum KHTMLPart::FormNotification

Enumerator:
NoNotification 
Before 
Only 
Unused 

Definition at line 987 of file khtml_part.h.

enum KHTMLPart::PageSecurity [protected]

Enumerator:
NotCrypted 
Encrypted 
Mixed 

Definition at line 1158 of file khtml_part.h.


Constructor & Destructor Documentation

KHTMLPart::KHTMLPart ( QWidget *  parentWidget = 0,
QObject *  parent = 0,
GUIProfile  prof = DefaultGUI 
)

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 one parent for the KHTMLView. If the second parent argument is 0L, then parentWidget is used as parent for both objects, the part and the view.

Definition at line 211 of file khtml_part.cpp.

KHTMLPart::KHTMLPart ( KHTMLView *  view,
QObject *  parent = 0,
GUIProfile  prof = DefaultGUI 
)

Constructs a new KHTMLPart.

This constructor is useful if you wish to subclass KHTMLView. If the view passed as first argument to the constructor was built with a null KHTMLPart pointer, then the newly created KHTMLPart will be assigned as the view's part.

Therefore, you might either initialize the view as part of the initialization list of your derived KHTMLPart class constructor:

   MyKHTMLPart() : KHTMLPart( new MyKHTMLView( this ), ...
Or separately build the KHTMLView beforehand:
   KHTMLView * v = KHTMLView( 0L, parentWidget());
   KHTMLPart * p = KHTMLPart( v ); // p will be assigned to v, so that v->part() == p

Definition at line 222 of file khtml_part.cpp.

KHTMLPart::~KHTMLPart (  )  [virtual]

Destructor.

Definition at line 476 of file khtml_part.cpp.


Member Function Documentation

bool KHTMLPart::openUrl ( const KUrl &  url  )  [virtual]

Opens the specified URL url.

Reimplemented from KParts::ReadOnlyPart::openUrl .

The format of the error url is that two variables are passed in the query: error = int kio error code, errText = QString error text from kio and the URL where the error happened is passed as a sub URL.

Reimplemented from KParts::ReadOnlyPart.

Definition at line 569 of file khtml_part.cpp.

bool KHTMLPart::closeUrl (  )  [virtual]

Stops loading the document and kills all data requests (for images, etc.

)

Reimplemented from KParts::ReadOnlyPart.

Definition at line 793 of file khtml_part.cpp.

void KHTMLPart::showError ( KJob *  job  )  [virtual]

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. job is the job that signaled the error situation

Definition at line 1679 of file khtml_part.cpp.

DOM::HTMLDocument KHTMLPart::htmlDocument (  )  const

Returns a reference to the DOM HTML document (for non-HTML documents, returns null).

Definition at line 875 of file khtml_part.cpp.

DOM::Document KHTMLPart::document (  )  const

Returns a reference to the DOM document.

Definition at line 883 of file khtml_part.cpp.

QString KHTMLPart::documentSource (  )  const

Returns the content of the source document.

Definition at line 888 of file khtml_part.cpp.

DOM::Node KHTMLPart::activeNode (  )  const

Returns the node that has the keyboard focus.

Definition at line 6980 of file khtml_part.cpp.

KParts::BrowserExtension * KHTMLPart::browserExtension (  )  const

Returns a pointer to the KParts::BrowserExtension.

Reimplemented from KParts::ReadOnlyPart.

Definition at line 920 of file khtml_part.cpp.

KParts::BrowserHostExtension * KHTMLPart::browserHostExtension (  )  const

Definition at line 925 of file khtml_part.cpp.

KHTMLView * KHTMLPart::view (  )  const

Returns a pointer to the HTML document's view.

Definition at line 930 of file khtml_part.cpp.

void KHTMLPart::setJScriptEnabled ( bool  enable  ) 

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.

Definition at line 954 of file khtml_part.cpp.

bool KHTMLPart::jScriptEnabled (  )  const

Returns true if Javascript support is enabled or false otherwise.

Definition at line 963 of file khtml_part.cpp.

KJS::Interpreter * KHTMLPart::jScriptInterpreter (  ) 

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 every time this happens - one way to detect the need for this is to connect to the docCreated() signal, another is to reimplement the begin() method.

Definition at line 940 of file khtml_part.cpp.

void KHTMLPart::setStatusMessagesEnabled ( bool  enable  ) 

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 also:
KParts::Part::setStatusBarText( const QString & text )

Definition at line 935 of file khtml_part.cpp.

bool KHTMLPart::statusMessagesEnabled (  )  const

Returns true if status messages are enabled.

Definition at line 949 of file khtml_part.cpp.

void KHTMLPart::setMetaRefreshEnabled ( bool  enable  ) 

Enable/disable automatic forwarding by <meta http-equiv="refresh" .

...>

Definition at line 972 of file khtml_part.cpp.

bool KHTMLPart::metaRefreshEnabled (  )  const

Returns true if automatic forwarding is enabled.

QVariant KHTMLPart::executeScript ( const DOM::Node &  n,
const QString &  script 
)

Same as executeScript( const QString & ) except with the Node parameter specifying the 'this' value.

Definition at line 1214 of file khtml_part.cpp.

void KHTMLPart::setDNDEnabled ( bool  b  ) 

Enables or disables Drag'n'Drop support.

A drag operation is started if the users drags a link.

Definition at line 5986 of file khtml_part.cpp.

bool KHTMLPart::dndEnabled (  )  const

Returns whether Dragn'n'Drop support is enabled or not.

void KHTMLPart::setJavaEnabled ( bool  enable  ) 

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.

Definition at line 1275 of file khtml_part.cpp.

bool KHTMLPart::javaEnabled (  )  const

Return true if Java applet support is enabled, false if disabled.

void KHTMLPart::setPluginsEnabled ( bool  enable  ) 

Enables or disables plugins, default is enabled.

Definition at line 1293 of file khtml_part.cpp.

bool KHTMLPart::pluginsEnabled (  )  const

Returns true if plugins are enabled, false if disabled.

void KHTMLPart::setAutoloadImages ( bool  enable  ) 

Specifies whether images contained in the document should be loaded automatically or not.

Note:
Request will be ignored if called before begin().

Definition at line 1355 of file khtml_part.cpp.

bool KHTMLPart::autoloadImages (  )  const

Returns whether images contained in the document are loaded automatically or not.

Note:
that the returned information is unrelieable as long as no begin() was called.

Definition at line 1383 of file khtml_part.cpp.

void KHTMLPart::setOnlyLocalReferences ( bool  enable  ) 

Security option.

Specify whether only file:/ or data:/ urls are allowed to be loaded without user confirmation by KHTML. ( for example referenced by stylesheets, images, scripts, subdocuments, embedded elements ).

This option is mainly intended for enabling the "mail reader mode", where you load untrusted content with a file:/ url.

Please note that enabling this option currently automatically disables Javascript, Java and Plugins support. This might change in the future if the security model is becoming more sophisticated, so don't rely on this behaviour.

( default false - everything is loaded unless forbidden by KApplication::authorizeURLAction).

Definition at line 2595 of file khtml_part.cpp.

bool KHTMLPart::onlyLocalReferences (  )  const

Returns whether only file:/ or data:/ references are allowed to be loaded ( default false ).

See setOnlyLocalReferences.

Definition at line 2590 of file khtml_part.cpp.

bool KHTMLPart::isCaretMode (  )  const

Returns whether caret mode is on/off.

Definition at line 2645 of file khtml_part.cpp.

bool KHTMLPart::isEditable (  )  const

Returns true if the document is editable, false otherwise.

Definition at line 2666 of file khtml_part.cpp.

void KHTMLPart::setCaretPosition (