KHTMLPart Class Reference

This class is khtml's main class. HTML Browser Widget. More...

#include <khtml_part.h>

Inheritance diagram for KHTMLPart:

[legend]Collaboration diagram for KHTMLPart:


Public Types
enum	GUIProfile { DefaultGUI, BrowserViewGUI }
enum	CaretDisplayPolicy { CaretVisible, CaretInvisible, CaretBlink }
enum	FindOptions { FindLinksOnly = 1 * KFindDialog::MinimumUserOption, FindNoPopups = 2 * KFindDialog::MinimumUserOption }
enum	FormNotification { NoNotification = 0, Before, Only, Unused = 255 }
Public Slots
void	setActiveNode (const DOM::Node &node)
void	stopAnimations ()
QCString	dcopObjectId () const
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::null, const QString &boundary=QString::null)
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)
Public Member Functions
	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)
virtual	~KHTMLPart ()
virtual bool	openURL (const KURL &url)
virtual bool	closeURL ()
virtual void	showError (KIO::Job *job)
DOM::HTMLDocument	htmlDocument () const
DOM::Document	document () const
QString	documentSource () const
DOM::Node	activeNode () const
KParts::BrowserExtension *	browserExtension () const
KParts::LiveConnectExtension *	liveConnectExtension (const khtml::RenderPart *) 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
KJavaAppletContext *	javaContext ()
KJavaAppletContext *	createJavaContext ()
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)
void	enableJScript (bool e)
void	enableJava (bool e)
void	enablePlugins (bool e)
void	autoloadImages (bool e)
void	enableMetaRefresh (bool e)
bool	setCharset (const QString &, bool)
KURL	baseURL () const
QString	baseTarget () 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 (const QString &str, bool forward, bool caseSensitive, bool isRegExp)
bool	findTextNext ()
void	setZoomFactor (int percent)
int	zoomFactor () 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
QPtrList< 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)
Protected Types
enum	PageSecurity { NotCrypted, Encrypted, Mixed }
Protected Member Functions
KURL	completeURL (const QString &url)
void	htmlError (int errorCode, const QString &text, const KURL &reqUrl)
virtual void	customEvent (QCustomEvent *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 void	urlSelected (const QString &url, int button, int state, const QString &_target, KParts::URLArgs args=KParts::URLArgs())
virtual KParts::ReadOnlyPart *	createPart (QWidget parentWidget, const char widgetName, QObject parent, const char name, 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 ()
Properties
bool	javaScriptEnabled
bool	javaEnabled
bool	autoloadImages
bool	dndEnabled
bool	pluginsEnabled
bool	onlyLocalReferences
QCString	dcopObjectId
bool	modified
Friends
class	KHTMLView
class	DOM::HTMLTitleElementImpl
class	DOM::HTMLFrameElementImpl
class	DOM::HTMLIFrameElementImpl
class	DOM::HTMLObjectElementImpl
class	DOM::HTMLAnchorElementImpl
class	DOM::HTMLMetaElementImpl
class	DOM::NodeImpl
class	KHTMLRun
class	DOM::HTMLFormElementImpl
class	khtml::RenderPartObject
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::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	KHTMLPartPrivate

Detailed Description

This class is khtml's main class. HTML Browser Widget.

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();

Author:: Lars Knoll (knoll@kde.org)

Definition at line 184 of file khtml_part.h.

Member Enumeration Documentation

enum KHTMLPart::CaretDisplayPolicy

Enumeration for displaying the caret.

Parameters:

Visible caret is displayed

Invisible caret is not displayed

Blink caret toggles between visible and invisible

Since:
3.2

Definition at line 482 of file khtml_part.h.

enum KHTMLPart::FindOptions

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

Since:
3.3

Definition at line 685 of file khtml_part.h.

Constructor & Destructor Documentation

KHTMLPart::KHTMLPart ( QWidget * parentWidget = 0,

const char * widgetname = 0,

QObject * parent = 0,

const char * name = 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 on 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 204 of file khtml_part.cpp.

KHTMLPart::~KHTMLPart ( ) [virtual]

Destructor.

Definition at line 448 of file khtml_part.cpp.
References closeURL(), KGlobal::config(), QObject::disconnect(), parentPart(), KConfigBase::setGroup(), and KConfigBase::writeEntry().

Member Function Documentation

bool KHTMLPart::openURL ( const KURL & url ) [virtual]

Opens the specified URL url.
Reimplemented from KParts::ReadOnlyPart::openURL .
Reimplemented from KParts::ReadOnlyPart.
Definition at line 546 of file khtml_part.cpp.
References QToolTip::add(), KProtocolManager::cacheControl(), closeURL(), KParts::ReadOnlyPart::completed(), QObject::connect(), QValueList::count(), QObject::disconnect(), endl(), QValueList::first(), KIO::get(), gotoAnchor(), KURL::host(), htmlError(), KIO::http_post(), KXMLGUIClient::instance(), QString::isEmpty(), KURL::join(), kdDebug(), parentPart(), KURL::path(), QValueList::pop_front(), KURL::prettyURL(), KURL::protocol(), KURL::queryItem(), QToolTip::remove(), KURL::setPath(), KURL::split(), KParts::ReadOnlyPart::started(), QString::startsWith(), KIO::stat(), QString::toInt(), toplevelURL(), KParts::ReadOnlyPart::url(), KURL::url(), KProtocolManager::userAgentForHost(), and KParts::Part::widget().
Referenced by restoreState(), and setEncoding().

bool KHTMLPart::closeURL ( ) [virtual]

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

Reimplemented from KParts::ReadOnlyPart.
Definition at line 750 of file khtml_part.cpp.
References KProtocolManager::cacheControl(), KHTMLPageCache::cancelEntry(), KHTMLPageCache::cancelFetch(), QObject::disconnect(), end(), endl(), kdDebug(), nodeActivated(), KURL::prettyURL(), and KHTMLPageCache::self().
Referenced by openURL(), restoreState(), setEncoding(), and ~KHTMLPart().

void KHTMLPart::showError ( KIO::Job * 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 1659 of file khtml_part.cpp.
References endl(), htmlError(), and kdDebug().

DOM::HTMLDocument KHTMLPart::htmlDocument ( ) const

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

Definition at line 832 of file khtml_part.cpp.

DOM::Document KHTMLPart::document ( ) const

Returns a reference to the DOM document.

Definition at line 840 of file khtml_part.cpp.
Referenced by selection().

QString KHTMLPart::documentSource ( ) const

Returns the content of the source document.

Since:
3.4

Definition at line 845 of file khtml_part.cpp.
References QFile::close(), KIO::NetAccess< T, K >::download(), encoding(), KHTMLPageCache::isComplete(), KURL::isLocalFile(), QFile::open(), QTextStream::read(), KIO::NetAccess< T, K >::removeTempFile(), KHTMLPageCache::saveData(), KHTMLPageCache::self(), and QTextStream::setCodec().

DOM::Node KHTMLPart::activeNode ( ) const

Returns the node that has the keyboard focus.

Definition at line 6668 of file khtml_part.cpp.

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

Returns a pointer to the KParts::BrowserExtension.

Definition at line 877 of file khtml_part.cpp.

KHTMLView * KHTMLPart::view ( ) const

Returns a pointer to the HTML document's view.

Definition at line 887 of file khtml_part.cpp.
Referenced by caretDisplayPolicyNonFocused(), findTextNext(), khtmlMouseMoveEvent(), setCaretDisplayPolicyNonFocused(), setCaretMode(), setCaretPosition(), setCaretVisible(), and setEditable().

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 911 of file khtml_part.cpp.
References KHTMLView::clear(), and jScriptEnabled().

bool KHTMLPart::jScriptEnabled ( ) const

Returns true if Javascript support is enabled or false otherwise.

Definition at line 920 of file khtml_part.cpp.
References onlyLocalReferences().
Referenced by setJScriptEnabled().

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 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.
Definition at line 897 of file khtml_part.cpp.

void KHTMLPart::setStatusMessagesEnabled ( bool enable )

Enable/disable statusbar messages.

Definition at line 892 of file khtml_part.cpp.

bool KHTMLPart::statusMessagesEnabled ( ) const

Returns true if status messages are enabled.

Definition at line 906 of file khtml_part.cpp.

void KHTMLPart::setMetaRefreshEnabled ( bool enable )

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

Definition at line 929 of file khtml_part.cpp.

bool KHTMLPart::metaRefreshEnabled ( ) const

Returns true if automatic forwarding is enabled.

Definition at line 934 of file khtml_part.cpp.

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 1161 of file khtml_part.cpp.
References endl(), kdDebug(), QObject::name(), and QVariant::toString().
Referenced by executeScript().

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 5709 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 1219 of file khtml_part.cpp.

bool KHTMLPart::javaEnabled ( ) const

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

KJavaAppletContext * KHTMLPart::javaContext ( )

Returns the java context of the applets.
If no applet exists, 0 is returned.
Definition at line 1238 of file khtml_part.cpp.

KJavaAppletContext * KHTMLPart::createJavaContext ( )

Returns the java context of the applets.
If no context exists yet, a new one is created.
Definition at line 1243 of file khtml_part.cpp.

void KHTMLPart::setPluginsEnabled ( bool enable )

Enables or disables plugins, default is enabled.

Definition at line 1248 of file khtml_part.cpp.

bool KHTMLPart::pluginsEnabled ( ) const

Returns true if plugins are enabled/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 1310 of file khtml_part.cpp.
References KXMLGUIClient::actionCollection(), QPtrList::append(), KXMLGUIClient::plugActionList(), and KXMLGUIClient::unplugActionList().
Referenced by begin().

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.

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 2545 of file khtml_part.cpp.

bool KHTMLPart::onlyLocalReferences ( ) const

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

See also:
setOnlyLocalReferences.

Referenced by jScriptEnabled().

bool KHTMLPart::isCaretMode ( ) const

Returns whether caret mode is on/off.

Since:
3.2

Definition at line 2595 of file khtml_part.cpp.
Referenced by KHTMLView::layout(), setCaretMode(), setCaretVisible(), and setEditable().

bool KHTMLPart::isEditable ( ) const

Returns true if the document is editable, false otherwise.

Since:
3.2

Definition at line 2616 of file khtml_part.cpp.
Referenced by khtmlMouseMoveEvent(), khtmlMousePressEvent(), KHTMLView::layout(), setCaretMode(), setCaretVisible(), and setEditable().

void KHTMLPart::setCaretPosition ( DOM::Node node,

long offset,

bool extendSelection = false

)

Sets the caret to the given position.
If the given location is invalid, it will snap to the nearest valid location. Immediately afterwards a caretPositionChanged signal containing the effective position is emitted
Parameters:

node node to set to

offset zero-based offset within the node

extendSelection If true, a selection will be spanned from the last caret position to the given one. Otherwise, any existing selection will be deselected.

Since:
3.2

Definition at line 2621 of file khtml_part.cpp.
References endl(), KHTMLView::ensureCaretVisible(), DOM::Node::handle(), k_funcinfo, kdDebug(), DOM::Node::nodeName(), DOM::DOMString::string(), and view().

KHTMLPart::CaretDisplayPolicy KHTMLPart::caretDisplayPolicyNonFocused ( ) const

Returns the current caret policy when the view is not focused.

Since:
3.2

Definition at line 2635 of file khtml_part.cpp.
References KHTMLView::caretDisplayPolicyNonFocused(), and view().

void KHTMLPart::setCaretDisplayPolicyNonFocused ( CaretDisplayPolicy policy )

Sets the caret display policy when the view is not focused.
Whenever the caret is in use, this property determines how the caret should be displayed when the document view is not focused.
The default policy is CaretInvisible.
Parameters:

policy new display policy

Since:
3.2

Definition at line 2644 of file khtml_part.cpp.
References KHTMLView::setCaretDisplayPolicyNonFocused(), and view().

KURL KHTMLPart::backgroundURL ( ) const

Returns the URL for the background Image (used by save background).

Definition at line 3908 of file khtml_part.cpp.

void KHTMLPart::scheduleRedirection ( int delay,

const QString & url,

khtml Library API Documentation

KHTMLPart Class Reference

Public Types

Public Slots

Signals

Public Member Functions

Protected Types

Protected Member Functions

Properties

Friends

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation