KHTML

KHTMLPart Class Reference

#include <khtml_part.h>

Inheritance diagram for KHTMLPart:

[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 195 of file khtml_part.h.


Public Types
enum	CaretDisplayPolicy { CaretVisible, CaretInvisible, CaretBlink }
enum	FindOptions { FindLinksOnly = 1 * KFind::MinimumUserOption, FindNoPopups = 2 * KFind::MinimumUserOption }
enum	FormNotification { NoNotification = 0, Before, Only, Unused = 255 }
enum	GUIProfile { DefaultGUI, BrowserViewGUI }
Public Slots
QVariant	executeScript (const QString &script)
void	setActiveNode (const DOM::Node &node)
void	setCaretMode (bool enable)
void	setCaretVisible (bool show)
void	setEditable (bool enable)
void	stopAnimations ()
void	submitFormProxy (const char *action, const QString &url, const QByteArray &formData, const QString &target, const QString &contentType=QString(), const QString &boundary=QString())
Signals
void	caretPositionChanged (const DOM::Node &node, long offset)
void	configurationChanged ()
void	docCreated ()
void	formSubmitNotification (const char *action, const QString &url, const QByteArray &formData, const QString &target, const QString &contentType, const QString &boundary)
void	nodeActivated (const DOM::Node &)
void	onURL (const QString &url)
void	popupMenu (const QString &url, const QPoint &point)
void	selectionChanged ()
Public Member Functions
DOM::Node	activeNode () const
bool	autoloadImages () const
KUrl	backgroundURL () const
KUrl	baseURL () const
virtual void	begin (const KUrl &url=KUrl(), int xOffset=0, int yOffset=0)
KParts::BrowserExtension *	browserExtension () const
KParts::BrowserHostExtension *	browserHostExtension () const
CaretDisplayPolicy	caretDisplayPolicyNonFocused () const
virtual bool	closeUrl ()
KParts::ReadOnlyPart *	currentFrame () const
bool	dndEnabled () const
DOM::Document	document () const
QString	documentSource () const
DOM::Editor *	editor () const
QString	encoding () const
virtual void	end ()
QVariant	executeScript (const DOM::Node &n, const QString &script)
KHTMLPart *	findFrame (const QString &f)
KHTMLPart *	findFrameParent (KParts::ReadOnlyPart callingPart, const QString &f, khtml::ChildFrame *childFrame=0)
KParts::ReadOnlyPart *	findFramePart (const QString &f)
void	findText (const QString &str, long options, QWidget parent=0, KFindDialog findDialog=0)
void	findText ()
void	findTextBegin ()
bool	findTextNext (bool reverse=false)
int	fontScaleFactor () const
FormNotification	formNotification () const
bool	frameExists (const QString &frameName)
KJSProxy *	framejScript (KParts::ReadOnlyPart *framePart)
QStringList	frameNames () const
QList< KParts::ReadOnlyPart * >	frames () const
bool	gotoAnchor (const QString &name)
bool	hasSelection () const
void	hide ()
DOM::HTMLDocument	htmlDocument () const
bool	inProgress () const
bool	isCaretMode () const
bool	isEditable () const
bool	isModified () const
bool	isPointInsideSelection (int x, int y)
bool	javaEnabled () const
bool	jScriptEnabled () const
KJS::Interpreter *	jScriptInterpreter ()
QString	jsDefaultStatusBarText () const
QString	jsStatusBarText () const
	KHTMLPart (KHTMLView view, QObject parent=0, GUIProfile prof=DefaultGUI)
	KHTMLPart (QWidget parentWidget=0, QObject parent=0, GUIProfile prof=DefaultGUI)
QString	lastModified () const
bool	metaRefreshEnabled () const
bool	nextAnchor ()
DOM::Node	nodeUnderMouse () const
DOM::Node	nonSharedNodeUnderMouse () const
bool	onlyLocalReferences () const
virtual bool	openUrl (const KUrl &url)
QString	pageReferrer () const
void	paint (QPainter , const QRect &, int=0, bool =0)
KHTMLPart *	parentPart ()
KParts::PartManager *	partManager ()
bool	pluginsEnabled () const
void	preloadScript (const QString &url, const QString &script)
void	preloadStyleSheet (const QString &url, const QString &stylesheet)
bool	prevAnchor ()
QString	referrer () const
bool	restored () const
virtual void	restoreState (QDataStream &stream)
virtual void	saveState (QDataStream &stream)
void	scheduleRedirection (int delay, const QString &url, bool lockHistory=true)
void	selectAll ()
virtual QString	selectedText () const
QString	selectedTextAsHTML () const
void	selection (DOM::Node &startNode, long &startOffset, DOM::Node &endNode, long &endOffset) const
DOM::Range	selection () const
void	setAlwaysHonourDoctype (bool b=true)
void	setAutoloadImages (bool enable)
void	setCaretDisplayPolicyNonFocused (CaretDisplayPolicy policy)
void	setCaretPosition (DOM::Node node, long offset, bool extendSelection=false)
void	setDNDEnabled (bool b)
bool	setEncoding (const QString &name, bool override=false)
void	setFixedFont (const QString &name)
void	setFontScaleFactor (int percent)
void	setFormNotification (FormNotification fn)
void	setJavaEnabled (bool enable)
void	setJScriptEnabled (bool enable)
void	setJSDefaultStatusBarText (const QString &text)
void	setJSStatusBarText (const QString &text)
void	setMetaRefreshEnabled (bool enable)
void	setOnlyLocalReferences (bool enable)
void	setPluginsEnabled (bool enable)
void	setSelection (const DOM::Range &)
void	setStandardFont (const QString &name)
void	setStatusMessagesEnabled (bool enable)
void	setSuppressedPopupIndicator (bool enable, KHTMLPart *originPart=0)
const KHTMLSettings *	settings () const
void	setURLCursor (const QCursor &c)
void	setUserStyleSheet (const QString &styleSheet)
void	setUserStyleSheet (const KUrl &url)
void	setZoomFactor (int percent)
void	show ()
virtual void	showError (KJob *job)
bool	statusMessagesEnabled () const
KUrl	toplevelURL ()
QCursor	urlCursor () const
KHTMLView *	view () const
virtual void	write (const QString &str)
virtual void	write (const char *str, int len=-1)
int	zoomFactor () const
virtual	~KHTMLPart ()
Protected Types
enum	PageSecurity { NotCrypted, Encrypted, Mixed }
Protected Slots
virtual void	slotFinished (KJob *)
Protected Member Functions
KUrl	completeURL (const QString &url)
virtual KParts::ReadOnlyPart *	createPart (QWidget parentWidget, QObject parent, const QString &mimetype, QString &serviceName, QStringList &serviceTypes, const QStringList &params)
virtual void	customEvent (QEvent *event)
virtual bool	doCloseStream ()
virtual bool	doOpenStream (const QString &mimeType)
virtual bool	doWriteStream (const QByteArray &data)
virtual void	guiActivateEvent (KParts::GUIActivateEvent *event)
void	htmlError (int errorCode, const QString &text, const KUrl &reqUrl)
virtual void	khtmlDrawContentsEvent (khtml::DrawContentsEvent *)
virtual void	khtmlMouseDoubleClickEvent (khtml::MouseDoubleClickEvent *)
virtual void	khtmlMouseMoveEvent (khtml::MouseMoveEvent *event)
virtual void	khtmlMousePressEvent (khtml::MousePressEvent *event)
virtual void	khtmlMouseReleaseEvent (khtml::MouseReleaseEvent *event)
virtual bool	openFile ()
bool	pluginPageQuestionAsked (const QString &mimetype) const
void	setPageSecurity (PageSecurity sec)
void	setPluginPageQuestionAsked (const QString &mimetype)
virtual void	startingJob (KIO::Job *)
virtual void	timerEvent (QTimerEvent *)
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())
Properties
bool	dndEnabled
QString	encoding
bool	javaEnabled
bool	javaScriptEnabled
QString	lastModified
bool	metaRefreshEnabled
bool	modified
bool	pluginsEnabled

Member Enumeration Documentation

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 512 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 713 of file khtml_part.h.

enum KHTMLPart::FormNotification

Enumerator:

NoNotification
Before
Only
Unused

Definition at line 1031 of file khtml_part.h.

enum KHTMLPart::GUIProfile

Enumerator:

DefaultGUI
BrowserViewGUI

Definition at line 254 of file khtml_part.h.

enum KHTMLPart::PageSecurity [protected]

Enumerator:

NotCrypted
Encrypted
Mixed

Definition at line 1202 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 QScrollArea, 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 213 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 482 of file khtml_part.cpp.

Member Function Documentation

DOM::Node KHTMLPart::activeNode ( ) const

Returns the node that has the keyboard focus.

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

KUrl KHTMLPart::backgroundURL ( ) const

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

Definition at line 4162 of file khtml_part.cpp.

KUrl KHTMLPart::baseURL ( ) const

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

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

Returns a pointer to the KParts::BrowserExtension.

Reimplemented from KParts::ReadOnlyPart.

Definition at line 943 of file khtml_part.cpp.

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

Definition at line 948 of file khtml_part.cpp.

KHTMLPart::CaretDisplayPolicy KHTMLPart::caretDisplayPolicyNonFocused ( ) const

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

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

bool KHTMLPart::closeUrl ( ) [virtual]

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

)

Reimplemented from KParts::ReadOnlyPart.

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

void KHTMLPart::configurationChanged ( ) [signal]

Emitted whenever the configuration has changed.

KParts::ReadOnlyPart * KHTMLPart::createPart	(	QWidget *	parentWidget,
		QObject *	parent,
		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 4748 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 5379 of file khtml_part.cpp.

void KHTMLPart::customEvent ( QEvent * event ) [protected, virtual]

Reimplemented from KParts::Part.

Definition at line 6150 of file khtml_part.cpp.

bool KHTMLPart::dndEnabled ( ) const

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

void KHTMLPart::docCreated ( ) [signal]

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

Implements the streaming API of KParts::ReadOnlyPart.

Definition at line 2029 of file khtml_part.cpp.

DOM::Document KHTMLPart::document ( ) const

Returns a reference to the DOM document.

Definition at line 906 of file khtml_part.cpp.

QString KHTMLPart::documentSource ( ) const

Returns the content of the source document.

Definition at line 911 of file khtml_part.cpp.

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

Implements the streaming API of KParts::ReadOnlyPart.

Definition at line 2012 of file khtml_part.cpp.

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

Implements the streaming API of KParts::ReadOnlyPart.

Definition at line 2023 of file khtml_part.cpp.

DOM::Editor * KHTMLPart::editor ( ) const

Returns the instance of the attached html editor interface.

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

void KHTMLPart::end ( ) [virtual]

Call this after your last call to write().

Definition at line 1983 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 1233 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 1238 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 5360 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

Definition at line 5319 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 5373 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.
	options	Find options.
	parent	Parent used for centering popups like "string not found".
	findDialog	Optionally, you can supply your own dialog.

Definition at line 3001 of file khtml_part.cpp.

void KHTMLPart::findText ( )

Starts a new search by popping up a dialog asking the user what he wants to search for.

Definition at line 2959 of file khtml_part.cpp.

void KHTMLPart::findTextBegin ( )

Initiates a text search.

Definition at line 2781 of file

KHTML

KHTMLPart Class Reference

Detailed Description

Public Types

Public Slots

Signals

Public Member Functions

Protected Types

Protected Slots

Protected Member Functions

Properties

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation