|
|
An HTML rendering and browsing widget.
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:
QString url = "http://www.kde.org"; KHTMLWidget *w = new KHTMLWidget(); w->openURL(url); w->resize(500, 400); w->show();
By default the widget behaves as a full browser, so clicking on some link on the page you just opened will lead you to that page. This is inconvenient, if you want to use the widget to display, for example, formatted emails, but don't want the widget to open the site in this window in case someone clicks on an embedded link. In this case just use setFollowsLinks(false). You will then get a signal urlClicked() instead of KHTMLWidget following the links directly.
By default Java and JavaScript support is disabled. You can enable it by using the enableJava() and enableJScript() methods.
Some apps want to write their HTML code directly into the widget instead of it opening a URL. You can also do that in the following way:
QString myHTMLCode = ...; KHTMLWidget *w = new KHTMLWidget(); w->begin(); w->write(myHTMLCode); ... w->end();
You can do as many calls to write as you want. But there are two write()
methods, one accepting a QString one accepting a char
* argument. These
should not get mixed, since the method using the char
* argument does an
additional decoding step to convert the written data to Unicode.
If you derive from KHTMLWidget you must overload the method createFrame()
KHTMLWidget ( QWidget *parent=0, const char *name=0 ) |
Construct a KHTMLWidget
KHTMLWidget ( QWidget *parent, KHTMLWidget *parentWidget, QString name) |
This constructor is used internally to realize frames.
void openURL ( const QString &_url, bool _reload = false, int _xoffset = 0, int _yoffset = 0, const char* _post_data = 0L ) |
Tell the widget to display the HTML page referred to by _url
.
Parameters:
xoffset | , yoffset Show the page at the specified offset after loading it. |
_post_data | Used internally for HTML post request. |
void setFollowsLinks ( bool follow ) |
Should the widget follow links automatically, if you click on them?
Default is true
.
bool followsLinks () |
does the widget follow links automatically?
void enableImages ( bool enable ) |
Should images be loaded automatically? Default is true
.
Not implemented at the moment.
bool imagesEnabled () |
Returns: true
if images will be loaded automatically.
void enableJava ( bool enable ) |
Enable/disable Java.
Default is disabled.
bool javaEnabled () |
Is Java enabled?
void enableJScript ( bool enable ) |
Enable/disable JScript.
Default is disabled.
bool jScriptEnabled () |
Is JScript enabled?
KHTMLWidget* parentFrame () |
Returns: The parent KHTMLWidget of this one or 0L is this is the top level browser. Used for frames.
KHTMLWidget* topFrame () |
Retrieve the top level frame.
Never returns 0L.
KHTMLWidget* findFrame ( const QString &_name ) |
Searche for a KHTMLWidget with a specific name as mentioned in the constructor.
See also: setName(), name()
QString frameName () |
Returns: The name of this frame.
See also: setName(), name(), findView()
KHTMLWidget* createFrame ( QWidget *_parent, QString _name ) |
Create a new instance.
This function is used by newView(). Its only purpose is to create a new instance of this class. If you derived from KHTMLWidget you must overload this function to make sure that all frames are of the same derived class.
KHTMLWidget * getFrame ( QString _name) |
This function is mainly used internally.
It gets the frame with name _name
,
if it exists and is a child of this widget, otherwise return 0.
void begin ( const QString &_url = 0L, int _dx = 0, int _dy = 0 ) |
Clear 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( QString("file:/tmp/test.html" ) );
All child frames and the old documents are removed if you call this method.
Parameters:
_url | 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. |
_dx | The initial horizontal scrollbar value. Usually you don't want to use this. |
_dy | The initial vertical scrollbar value. Usually you don't want to use this. |
void write ( const char * ) |
Write another part of the HTML code to the widget.
You may call this function many times in sequence. But remember: The fewer calls you make, the faster the widget is.
The HTML code is sent through a decoder, which decodes the stream to Unicode.
Attention: Don't mix calls to write( const char *) with calls to write( const QString & ). The result might not be what you want.
void write ( const QString & ) |
Write another part of the HTML code to the widget.
You may call this function many times in sequence. But remember: The fewer calls you make, the faster the widget is.
void end () |
Call this after your last call to write().
void print (QPainter *, int pageHeight, int pageWidth) |
Print current HTML page laid out for the printer.
Not implemented at the moment.
QString selectedText () |
Get the text the user has marked.
bool isTextSelected () |
Has the user selected any text?
Call selectedText() to retrieve the selected text.
Returns: true if there is text selected.
void findTextBegin () |
Initiate a text search.
bool findTextNext ( const QRegExp &exp ) |
Find the next occurrence of the expression.
const QString & url ( const QPoint &_point ) |
Check out whether there is a URL under the pointer and return a pointer to this URL or 0L if there is none.
Parameters:
_point | The point to test for the presence of a URL. The point is relative to this widget. |
int docWidth () |
Returns: The width of the parsed HTML code. Remember that the documents width depends on the width of the widget.
int docHeight () |
Returns: The height of the parsed HTML code. Remember that the document's height depends on the width of the widget.
const QString & url () |
Returns: The URL of this document.
const QString & baseUrl () |
The base URL is usually set by a <BASE URL=...> tag in the document head.
Returns: The base URL of this document.
void setBaseUrl (const QString &base) |
Set the document's base URL.
Mainly used internally.
const QString & baseTarget () |
Returns: The base target of this document. The base target is usually set by a <BASE TARGET=...> tag in the document head.
void setBaseTarget (const QString &target) |
Set the document's base target.
Mainly used internally.
bool gotoAnchor ( const QString &_name ) |
Find the anchor named _name
.
If the anchor is found, the widget scrolls to the closest position.
Returns: true
if the anchor has been found.
void autoScrollY ( int _delay, int _dy ) |
Causes the widget contents to scroll automatically.
Call stopAutoScrollY() to stop. Stops automatically when the top or bottom of the document is reached.
(not implemented)
Parameters:
_delay | Time in milliseconds to wait before scrolling the document again. |
_dy | The amount to scroll the document when _delay elapses. |
bool isAutoScrollingY () |
Is the widget currently auto scrolling.
bool isFrameSet () |
Returns: true
if the currently displayed document is a frame set.
KHTMLWidget* selectedFrame () |
If this widget is the selected one then htmlView() is returned. Otherwise all HTMLFrameSet instances are asked.
Returns: A pointer to the currently selected frame if we are displaying a frameset, otherwise 0L.
void setFontSizes (const int *newFontSizes, const int *newFixedFontSizes=0) |
Set point sizes to be associated with the HTML-sizes used in <FONT SIZE=HTML-Font-Size>
HTML-Font-Sizes range from 1 (smallest) to 7 (biggest).
void fontSizes (int *newFontSizes, int *newFixedFontSizes=0) |
Retrieve point sizes to be associated with the HTML-sizes used in <FONT SIZE=HTML-Font-Size>
HTMl-Font-Sizes range from 1 (smallest) to 7 (biggest).
void resetFontSizes () |
Reset the point sizes to be associated with the HTML-sizes used in <FONT SIZE=HTML-Font-Size> to their default.
HTML-Font-Sizes range from 1 (smallest) to 7 (biggest).
void setStandardFont ( const QString &name ) |
Set the standard font style.
Parameters:
name | The font name to use for standard text. |
void setFixedFont ( const QString &name ) |
Set the fixed font style.
Parameters:
name | The font name to use for fixed text, e.g. the < PRE >; tag. |
bool setCharset (const QString &name, bool override = false) |
Set document charset.
Any <META ...> setting charsets overrides this setting as long as override isn't true.
Not implemented at the moment.
Returns: true
if successful.
void setDefaultBGColor ( const QColor &col ) |
Set the default background color to use when one isn't specified explicitly by <BODY BGCOLOR=...>
void setDefaultTextColors ( const QColor &normal, const QColor &link, const QColor &vlink ) |
Set the default text colors.
void setUnderlineLinks ( bool ul ) |
Set whether links are drawn in underlined text.
void setURLCursor ( const QCursor &c ) |
Set the cursor to use when the cursor is on a link.
const QCursor& urlCursor () |
Retrieve the cursor which is used when the cursor is on a link.
void cancelRequestFile ( HTMLURLRequester *_obj ) |
Cancel a previous requestFile().
void cancelRequestFile ( const QString &_url ) |
Cancel a previous requestFile().
void cancelAllRequests () |
Cancel all file requests.
Called from @see slotCancel().
void saveState ( QDataStream &stream ) |
Function used to save the current HTML page into the datastream.
This only works if the page has a valid URL. Pages filled with the write() method are not saveable, and might give unwanted results.
void restoreState ( QDataStream &stream ) |
Restore a page previously saved with saveState().
DOM::HTMLDocument htmlDocument () |
Hook to get the Document.
Used eg by jscript to manipulate the document. See also the DOM Level 1 recommodation, http://www.w3.org/TR/REC-DOM-Level-1/ f the W3C, http://www.w3.org
KJSProxy * jScript () |
Returns: The JavaScript engine, or 0 if JScript is disabled.
int jobId () |
Returns: The job id of the KIOJob responsible for loading the current document (or 0 if none).
void setMarginWidth (int x) |
Set a margin in x direction.
int marginWidth () |
Returns: The margin Width.
void setMarginHeight (int y) |
Set a margin in y direction.
int marginHeight () |
Returns: The margin height.
void slotStop () |
Stop loading the current document.
void slotReload () |
Reload the current document.
Will not reload frames contained in this document in case it is a frameset.
void slotReloadFrames () |
Reload the current document including all child frames.
void slotFormSubmitted ( const QString &_method, const QString &_url, const char *_data, const QString &_target ) |
Used internally to tell the widget that a form has been submitted.
void slotPost ( int ) |
void error ( int _err, const char* _text ) |
Emitted when cancel is emitted, but with more detailed error description.
void newWindow ( const QString &_url ) |
Emitted if a link is pressed which has an invalid target,
or the target _blank
.
void started ( const QString &_url ) |
Emitted after @see begin() has been called.
void completed () |
Emitted when the page (including all children) has been completely loaded.
void canceled () |
Emitted when the loading of the page has been canceled.
void urlClicked ( const QString &url , const QString &target, int button) |
Emitted when a URL has been clicked.
Only emitted, when @see followLinks() is set to false
.
In this case the app has to handle the request.
void onURL ( const QString &_url ) |
Emitted when the mouse cursor moves on or off a URL.
Parameters:
_url | The URL that the mouse cursor has moved onto; is null if the cursor moved off a URL. |
void popupMenu ( const QString &_url, const QPoint & ) |
Emitted when the user clicks on a URL with the right mouse button.
If the user pressed the right mouse button over a URL than _url
points to this URL, otherwise _url
will be null.
The position is in global coordinates.
void setTitle ( const QString &) |
This signal is emitted whenever the widget wants to change the window's title. Usually this is the text enclosed in <TITLE>....<TITLE>.
void formSubmitted ( const QString &_method, const QString &_url, const char *_data, const QString &_target ) |
Emitted if the user presses the submit button.
Parameters:
_url | The <FORM ACTION=...> value |
_method | The <FORM METHOD=...> value |
void executeScript ( const QString &script ) |
This function is called, when a user action triggers a script.
KHTMLWidget* parentView () |
Returns: the parent KHTMLWidget of this one or 0L is this is the top level browser.
KHTMLWidget* topView () |
Never returns 0L.
void viewportMouseDoubleClickEvent ( QMouseEvent * ) |
This function emits the 'doubleClick' signal when the user double clicks a <A HREF=...> tag.
void viewportMouseMoveEvent (QMouseEvent *) |
This function is called when the user moves the mouse.
void viewportMouseReleaseEvent (QMouseEvent *) |
this function is called when the user releases a mouse button.
bool mouseMoveHook ( QMouseEvent * ) |
This function is hooked into the event processing of the widget.
bool mouseReleaseHook ( QMouseEvent * ) |
This function is hooked into the event processing of the widget.
bool mousePressedHook ( const QString &, const QString & , QMouseEvent *, bool ) |
This function is hooked into the event processing of the widget.
QList<Child> m_lstChildren |
A list containing all direct child views. Usually every frame in a frameset becomes a child view. This list is used to update the contents of all children ( see slotUpdateView ).
bool m_bStartedRubberBand |
This flag is TRUE if we are in the middle of a selection using a rectangular rubber band.
bool m_bRubberBandVisible |
This flag is true if the rubber band is currently visible.
QPainter* m_pRubberBandPainter |
Painter used for the rubber band.
QString m_strSelectedURL |
This is just a temporary variable. It stores the URL the user clicked on, until he releases the mouse again.
mouseMoveHook mousePressedHook
QString m_strWorkingURL |
Once we received the first data of our new HTML page we clear this variable and copy its content to m_strURL
int m_iNextXOffset |
One can pass offsets to openURL to indicate which part of the HTML page should be visible. This variable is used to store the XOffset. It is used when the method begin is called which happens once the first data package of the new HTML page arrives.
int m_iNextYOffset |
One can pass offsets to openURL to indicate which part of the HTML page should be visible. This variable is used to store the XOffset. It is used when the method begin is called which happens once the first data package of the new HTML page arrives.
int m_jobId |
This is the id of the job that fetches the HTML page for us. A value of 0 indicates that we have no running job.
bool m_bParsing |
This flag is set to true after calling the method begin and before end is called.
bool m_bComplete |
This flag is set to false after a call to openURL and set to true once the document is parsed and displayed and if all children ( frames ) are complete, too. On completion the signal completed is emitted and the parent browser ( m_pParentBrowser ) is notified. If an fatal error occurs, this flag is set to true, too.
bool m_bReload |
Tells wether the last call to openURL had the reload flag set or not. This is needed to use the same cache policy for loading images and stuff.
bool m_bEnableImages |
This flag indicates whether images should be loaded automatically. The default value is TRUE. see also: enableImages and imagesEnabled