KHTMLPart Class Reference

#include <khtml_part.h>

Inheritance diagram for KHTMLPart:

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.


Public Types
	DefaultGUI
	BrowserViewGUI
	CaretVisible
	CaretInvisible
	CaretBlink
	FindLinksOnly = 1 * KFindDialog::MinimumUserOption
	FindNoPopups = 2 * KFindDialog::MinimumUserOption
	NoNotification = 0
	Before
	Only
	Unused = 255
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 ()
bool	findTextNext (bool reverse)
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)
void	setSuppressedPopupIndicator (bool enable, KHTMLPart *originPart)
bool	inProgress () const
Protected Types
	NotCrypted
	Encrypted
	Mixed
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 `[]`
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	KHTMLPopupGUIClient
class	KHTMLPartPrivate

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 496 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 703 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 206 of file khtml_part.cpp.

KHTMLPart::~KHTMLPart ( ) [virtual]

Destructor.

Definition at line 468 of file khtml_part.cpp.

Member Function Documentation

DOM::Node KHTMLPart::activeNode ( ) const

Returns the node that has the keyboard focus.

Definition at line 6931 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.

KURL KHTMLPart::backgroundURL ( ) const

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

Definition at line 4113 of file khtml_part.cpp.

void KHTMLPart::begin	(	const KURL &	url = `KURL()`,
		int	xOffset = `0`,
		int	yOffset = `0`
	)			`[virtual]`

Clears the widget and prepares it for new content.

If you want url() to return for example "file:/tmp/test.html", you can use the following code:

 view->begin( KURL("file:/tmp/test.html" ) );

Parameters:

	url	is the url of the document to be displayed. Even if you are generating the HTML on the fly, it may be useful to specify a directory so that any pixmaps are found.
	xOffset	is the initial horizontal scrollbar value. Usually you don't want to use this.
	yOffset	is the initial vertical scrollbar value. Usually you don't want to use this.

All child frames and the old document are removed if you call this method.

Definition at line 1872 of file khtml_part.cpp.

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

Returns a pointer to the KParts::BrowserExtension.

Definition at line 897 of file khtml_part.cpp.

KHTMLPart::CaretDisplayPolicy KHTMLPart::caretDisplayPolicyNonFocused ( ) const

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

Since:: 3.2

Definition at line 2699 of file khtml_part.cpp.

void KHTMLPart::caretPositionChanged	(	const DOM::Node &	node,
		long	offset
	)			`[signal]`

This signal is emitted whenever the caret position has been changed.

The signal transmits the position the DOM::Range way, the node and the zero-based offset within this node.

Parameters:

	node	node which the caret is in. This can be null if the caret has been deactivated.
	offset	offset within the node. If the node is null, the offset is meaningless.

Since:: 3.2

bool KHTMLPart::closeURL ( ) [virtual]

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

)

Reimplemented from KParts::ReadOnlyPart.

Definition at line 770 of file khtml_part.cpp.

KURL KHTMLPart::completeURL ( const QString & url ) [protected]

returns a KURL object for the given url.

Use when you know what you're doing.

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

KParts::ReadOnlyPart * KHTMLPart::createPart	(	QWidget *	parentWidget,
		const char *	widgetName,
		QObject *	parent,
		const char *	name,
		const QString &	mimetype,
		QString &	serviceName,
		QStringList &	serviceTypes,
		const QStringList &	params
	)			`[protected, virtual]`

This method is called when a new embedded object (include html frames) is to be created.

Reimplement it if you want to add support for certain embeddable objects without registering them in the KDE wide registry system (KSyCoCa) . Another reason for re-implementing this method could be if you want to derive from KTHMLPart and also want all html frame objects to be a object of your derived type, in which case you should return a new instance for the mimetype 'text/html' .

Definition at line 4645 of file khtml_part.cpp.

KParts::ReadOnlyPart * KHTMLPart::currentFrame ( ) const

Return the current frame (the one that has focus) Not necessarily a direct child of ours, framesets can be nested.

Returns "this" if this part isn't a frameset.

Definition at line 5271 of file khtml_part.cpp.

bool KHTMLPart::dndEnabled ( ) const

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

bool KHTMLPart::doCloseStream ( ) [protected, virtual]

Implements the streaming API of KParts::ReadOnlyPart.

Definition at line 2039 of file khtml_part.cpp.

DOM::Document KHTMLPart::document ( ) const

Returns a reference to the DOM document.

Definition at line 860 of file khtml_part.cpp.

QString KHTMLPart::documentSource ( ) const

Returns the content of the source document.

Since:: 3.4

Definition at line 865 of file khtml_part.cpp.

bool KHTMLPart::doOpenStream ( const QString & mimeType ) [protected, virtual]

Implements the streaming API of KParts::ReadOnlyPart.

Definition at line 2022 of file khtml_part.cpp.

bool KHTMLPart::doWriteStream ( const QByteArray & data ) [protected, virtual]

Implements the streaming API of KParts::ReadOnlyPart.

Definition at line 2033 of file khtml_part.cpp.

QString KHTMLPart::encoding ( ) const

Returns the encoding the page currently uses.

Note that the encoding might be different from the charset.

Definition at line 2482 of file khtml_part.cpp.

void KHTMLPart::end ( ) [virtual]

Call this after your last call to write().

Definition at line 2007 of file khtml_part.cpp.

QVariant KHTMLPart::executeScript ( const QString & script ) [slot]

Execute the specified snippet of JavaScript code.

Returns true if JavaScript was enabled, no error occurred and the code returned true itself or false otherwise.

Deprecated:: , use executeString( DOM::Node(), script)

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

KHTMLPart * KHTMLPart::findFrame ( const QString & f )

Finds a frame by name.

Returns 0L if frame can't be found.

Definition at line 5252 of file khtml_part.cpp.

KHTMLPart * KHTMLPart::findFrameParent	(	KParts::ReadOnlyPart *	callingPart,
		const QString &	f,
		khtml::ChildFrame **	childFrame = `0`
	)

Recursively finds the part containing the frame with name f and checks if it is accessible by callingPart Returns 0L if no suitable frame can't be found.

Returns parent part if a suitable frame was found and frame info in *childFrame

Since:: 3.3

Definition at line 5211 of file khtml_part.cpp.

KParts::ReadOnlyPart * KHTMLPart::findFramePart ( const QString & f )

Finds a frame by name.

Returns 0L if frame can't be found.

Definition at line 5265 of file khtml_part.cpp.

void KHTMLPart::findText	(	const QString &	str,
		long	options,
		QWidget *	parent = `0`,
		KFindDialog *	findDialog = `0`
	)

Starts a new search, but bypasses the user dialog.

Parameters:

str

The string to search for.

KHTMLPart Class Reference

Detailed Description

Public Types

Public Slots

Signals

Public Member Functions

Protected Types

Protected Member Functions

Properties

Friends

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation