.TH "KParts::BrowserExtension" 3 "28 Jan 2004" "kparts Library" \" -*- nroff -*-
.ad l
.nh
.SH NAME
KParts::BrowserExtension \- The Browser Extension is an extension (yes, no kidding) to \fBKParts::ReadOnlyPart\fP, which allows a better integration of parts with browsers (in particular Konqueror).  

.PP
.SH SYNOPSIS
.br
.PP
\fC#include <browserextension.h>\fP
.PP
Inherits \fBQObject\fP.
.PP
.SS "Public Types"

.in +1c
.ti -1c
.RI "typedef \fBQMap\fP< \fBQCString\fP, \fBQCString\fP > \fBActionSlotMap\fP"
.br
.ti -1c
.RI "typedef \fBQMap\fP< \fBQCString\fP, int > \fBActionNumberMap\fP"
.br
.in -1c
.SS "Signals"

.in +1c
.ti -1c
.RI "void \fBenableAction\fP (const  char *\fBname\fP, bool enabled)"
.br
.RI "\fIEnables or disable a standard action held by the browser. \fP"
.ti -1c
.RI "void \fBopenURLRequest\fP (const  \fBKURL\fP &url, const  \fBKParts::URLArgs\fP &args=\fBKParts::URLArgs\fP())"
.br
.RI "\fIAsks the host (browser) to open \fCurl\fP. \fP"
.ti -1c
.RI "void \fBopenURLRequestDelayed\fP (const  \fBKURL\fP &url, const  \fBKParts::URLArgs\fP &args=\fBKParts::URLArgs\fP())"
.br
.RI "\fIThis signal is emitted when openURLRequest is called, after a 0-seconds timer. \fP"
.ti -1c
.RI "void \fBopenURLNotify\fP ()"
.br
.RI "\fITells the hosting browser that the part opened a new URL (which can be queried via \fBKParts::Part::url\fP(). \fP"
.ti -1c
.RI "void \fBsetLocationBarURL\fP (const  \fBQString\fP &url)"
.br
.RI "\fIUpdates the URL shown in the browser's location bar to \fCurl\fP. \fP"
.ti -1c
.RI "void \fBsetIconURL\fP (const  \fBKURL\fP &url)"
.br
.RI "\fISets the URL of an icon for the currently displayed page. \fP"
.ti -1c
.RI "void \fBcreateNewWindow\fP (const  \fBKURL\fP &url, const  \fBKParts::URLArgs\fP &args=\fBKParts::URLArgs\fP())"
.br
.RI "\fIAsks the hosting browser to open a new window for the given \fCurl\fP. \fP"
.ti -1c
.RI "void \fBcreateNewWindow\fP (const  \fBKURL\fP &url, const  \fBKParts::URLArgs\fP &args, const  \fBKParts::WindowArgs\fP &windowArgs, \fBKParts::ReadOnlyPart\fP *&part)"
.br
.RI "\fIAsks the hosting browser to open a new window for the given \fCurl\fP and return a reference to the content part. \fP"
.ti -1c
.RI "void \fBloadingProgress\fP (int percent)"
.br
.RI "\fISince the part emits the jobid in the \fBstarted\fP() signal, progress information is automatically displayed. \fP"
.ti -1c
.RI "void \fBspeedProgress\fP (int bytesPerSecond)"
.br
.ti -1c
.RI "void \fBinfoMessage\fP (const  \fBQString\fP &)"
.br
.ti -1c
.RI "void \fBpopupMenu\fP (const  \fBQPoint\fP &global, const  \fBKFileItemList\fP &items)"
.br
.RI "\fIEmit this to make the browser show a standard popup menu at the point \fCglobal\fP for the files \fCitems\fP. \fP"
.ti -1c
.RI "void \fBpopupMenu\fP (\fBKXMLGUIClient\fP *client, const  \fBQPoint\fP &global, const  \fBKFileItemList\fP &items)"
.br
.RI "\fIEmit this to make the browser show a standard popup menu at the point \fCglobal\fP for the files \fCitems\fP. \fP"
.ti -1c
.RI "void \fBpopupMenu\fP (const  \fBQPoint\fP &global, const  \fBKURL\fP &url, const  \fBQString\fP &mimeType, mode_t mode=(mode_t)-1)"
.br
.RI "\fIEmit this to make the browser show a standard popup menu at the point \fCglobal\fP for the given \fCurl\fP. \fP"
.ti -1c
.RI "void \fBpopupMenu\fP (\fBKXMLGUIClient\fP *client, const  \fBQPoint\fP &global, const  \fBKURL\fP &url, const  \fBQString\fP &mimeType, mode_t mode=(mode_t)-1)"
.br
.RI "\fIEmit this to make the browser show a standard popup menu at the point \fCglobal\fP for the given \fCurl\fP. \fP"
.ti -1c
.RI "void \fBselectionInfo\fP (const  \fBKFileItemList\fP &items)"
.br
.RI "\fIInform the hosting application about the current selection. \fP"
.ti -1c
.RI "void \fBselectionInfo\fP (const  \fBQString\fP &text)"
.br
.RI "\fIInform the hosting application about the current selection. \fP"
.ti -1c
.RI "void \fBselectionInfo\fP (const  \fBKURL::List\fP &urls)"
.br
.RI "\fIInform the hosting application about the current selection. \fP"
.ti -1c
.RI "void \fBmouseOverInfo\fP (const  \fBKFileItem\fP *item)"
.br
.RI "\fIInform the hosting application that the user moved the mouse over an item. \fP"
.in -1c
.SS "Public Member Functions"

.in +1c
.ti -1c
.RI "\fBBrowserExtension\fP (\fBKParts::ReadOnlyPart\fP *\fBparent\fP, const  char *\fBname\fP=0L)"
.br
.RI "\fIConstructor. \fP"
.ti -1c
.RI "virtual void \fBsetURLArgs\fP (const  \fBURLArgs\fP &args)"
.br
.RI "\fISet the parameters to use for opening the next URL. \fP"
.ti -1c
.RI "\fBURLArgs\fP \fBurlArgs\fP () const "
.br
.RI "\fIRetrieve the set of parameters to use for opening the URL (this must be called from openURL() in the part). \fP"
.ti -1c
.RI "virtual int \fBxOffset\fP ()"
.br
.RI "\fIReturns the current x offset. \fP"
.ti -1c
.RI "virtual int \fByOffset\fP ()"
.br
.RI "\fIReturns the current y offset. \fP"
.ti -1c
.RI "virtual void \fBsaveState\fP (\fBQDataStream\fP &stream)"
.br
.RI "\fIUsed by the browser to save the current state of the view (in order to restore it if going back in navigation). \fP"
.ti -1c
.RI "virtual void \fBrestoreState\fP (\fBQDataStream\fP &stream)"
.br
.RI "\fIUsed by the browser to restore the view in the state it was when we left it. \fP"
.ti -1c
.RI "bool \fBisURLDropHandlingEnabled\fP () const "
.br
.RI "\fIReturns whether url drop handling is enabled. \fP"
.ti -1c
.RI "void \fBsetURLDropHandlingEnabled\fP (bool enable)"
.br
.RI "\fIEnables or disables url drop handling. \fP"
.ti -1c
.RI "void \fBsetBrowserInterface\fP (\fBBrowserInterface\fP *impl)"
.br
.ti -1c
.RI "\fBBrowserInterface\fP * \fBbrowserInterface\fP () const "
.br
.ti -1c
.RI "bool \fBisActionEnabled\fP (const  char *\fBname\fP) const "
.br
.in -1c
.SS "Static Public Member Functions"

.in +1c
.ti -1c
.RI "\fBActionSlotMap\fP \fBactionSlotMap\fP ()"
.br
.RI "\fIReturns a map containing the action names as keys and corresponding SLOT()'ified method names as data entries. \fP"
.ti -1c
.RI "\fBActionSlotMap\fP * \fBactionSlotMapPtr\fP ()"
.br
.ti -1c
.RI "\fBBrowserExtension\fP * \fBchildObject\fP (\fBQObject\fP *obj)"
.br
.RI "\fIQueries \fCobj\fP for a child object which inherits from this \fBBrowserExtension\fP class. \fP"
.in -1c
.SS "Protected Member Functions"

.in +1c
.ti -1c
.RI "virtual void \fBvirtual_hook\fP (int id, void *data)"
.br
.in -1c
.SH "Detailed Description"
.PP 
The Browser Extension is an extension (yes, no kidding) to \fBKParts::ReadOnlyPart\fP, which allows a better integration of parts with browsers (in particular Konqueror). 

Remember that \fBReadOnlyPart\fP only has openURL(KURL), with no other settings. For full-fledged browsing, we need much more than that, including many arguments about how to open this URL (see \fBURLArgs\fP), allowing parts to save and restore their data into the back/forward history, allowing parts to control the location bar URL, to requests URLs to be opened by the hosting browser, etc.
.PP
The part developer needs to define its own class derived from \fBBrowserExtension\fP, to implement the virtual methods [and the standard-actions slots, see below].
.PP
The way to associate the \fBBrowserExtension\fP with the part is to simply create the \fBBrowserExtension\fP as a child of the part (in QObject's terms). The hosting application will look for it automatically.
.PP
Another aspect of the browser integration is that a set of standard actions are provided by the browser, but implemented by the part (for the actions it supports).
.PP
The following standard actions are defined by the host of the view :
.PP
[selection-dependent actions] 
.IP "\(bu" 2
\fCcut\fP : Copy selected items to clipboard and store 'not cut' in clipboard. 
.IP "\(bu" 2
\fCcopy\fP : Copy selected items to clipboard and store 'cut' in clipboard. 
.IP "\(bu" 2
\fCpaste\fP : Paste clipboard into view URL. 
.IP "\(bu" 2
\fCpasteTo(const KURL &)\fP : Paste clipboard into given URL. 
.IP "\(bu" 2
\fCrename\fP : Rename item in place. 
.IP "\(bu" 2
\fCtrash\fP : Move selected items to trash. 
.IP "\(bu" 2
\fCdel\fP : Delete selected items (couldn't call it delete!). 
.IP "\(bu" 2
\fCshred\fP : Shred selected items (secure deletion). 
.IP "\(bu" 2
\fCproperties\fP : Show file/document properties. 
.IP "\(bu" 2
\fCeditMimeType\fP : show file/document's mimetype properties.
.PP
[normal actions] 
.IP "\(bu" 2
\fCprint\fP : Print :-) 
.IP "\(bu" 2
\fCreparseConfiguration\fP : Re-read configuration and apply it. 
.IP "\(bu" 2
\fCrefreshMimeTypes\fP : If the view uses mimetypes it should re-determine them.
.PP
The view defines a slot with the name of the action in order to implement the action. The browser will detect the slot automatically and connect its action to it when appropriate (i.e. when the view is active).
.PP
The selection-dependent actions are disabled by default and the view should enable them when the selection changes, emitting \fBenableAction\fP().
.PP
The normal actions do not depend on the selection. You need to enable 'print' when printing is possible - you can even do that in the constructor.
.PP
A special case is the configuration slots, not connected to any action directly, and having parameters.
.PP
[configuration slot] 
.IP "\(bu" 2
\fCsetSaveViewPropertiesLocally( bool )\fP: If \fCtrue\fP, view properties are saved into .directory otherwise, they are saved globally. 
.PP

.PP
Definition at line 278 of file browserextension.h.
.SH "Constructor & Destructor Documentation"
.PP 
.SS "BrowserExtension::BrowserExtension (\fBKParts::ReadOnlyPart\fP * parent, const char * name = 0L)"
.PP
Constructor. \fBParameters:\fP
.RS 4
\fIparent\fP The \fBKParts::ReadOnlyPart\fP that this extension ... 'extends' :) 
.br
\fIname\fP An optional name for the extension. 
.RE
.PP
Definition at line 326 of file browserextension.cpp.
.PP
References QMap::begin(), QObject::connect(), enableAction(), QMap::end(), QObject::metaObject(), KStdAccel::name(), and openURLRequest().
.SH "Member Function Documentation"
.PP 
.SS "void BrowserExtension::setURLArgs (const \fBURLArgs\fP & args)\fC [virtual]\fP"
.PP
Set the parameters to use for opening the next URL. This is called by the 'hosting' application, to pass parameters to the part. 
.PP
\fBSee also:\fP
.RS 4
\fBURLArgs\fP 
.RE
.PP
Definition at line 363 of file browserextension.cpp.
.PP
Referenced by restoreState().
.SS "\fBURLArgs\fP BrowserExtension::urlArgs () const"
.PP
Retrieve the set of parameters to use for opening the URL (this must be called from openURL() in the part). \fBSee also:\fP
.RS 4
\fBURLArgs\fP 
.RE
.PP
Definition at line 368 of file browserextension.cpp.
.PP
Referenced by restoreState().
.SS "int BrowserExtension::xOffset ()\fC [virtual]\fP"
.PP
Returns the current x offset. For a scrollview, implement this using contentsX(). Definition at line 373 of file browserextension.cpp.
.PP
Referenced by saveState().
.SS "int BrowserExtension::yOffset ()\fC [virtual]\fP"
.PP
Returns the current y offset. For a scrollview, implement this using contentsY(). Definition at line 378 of file browserextension.cpp.
.PP
Referenced by saveState().
.SS "void BrowserExtension::saveState (\fBQDataStream\fP & stream)\fC [virtual]\fP"
.PP
Used by the browser to save the current state of the view (in order to restore it if going back in navigation). If you want to save additionnal properties, reimplement it but don't forget to call the parent method (probably first). Definition at line 383 of file browserextension.cpp.
.PP
References KParts::ReadOnlyPart::url(), xOffset(), and yOffset().
.SS "void BrowserExtension::restoreState (\fBQDataStream\fP & stream)\fC [virtual]\fP"
.PP
Used by the browser to restore the view in the state it was when we left it. If you saved additionnal properties, reimplement it but don't forget to call the parent method (probably first). Definition at line 388 of file browserextension.cpp.
.PP
References KParts::ReadOnlyPart::openURL(), setURLArgs(), urlArgs(), KParts::URLArgs::xOffset, and KParts::URLArgs::yOffset.
.SS "bool BrowserExtension::isURLDropHandlingEnabled () const"
.PP
Returns whether url drop handling is enabled. See \fBsetURLDropHandlingEnabled\fP for more information about this property. Definition at line 403 of file browserextension.cpp.
.SS "void BrowserExtension::setURLDropHandlingEnabled (bool enable)"
.PP
Enables or disables url drop handling. URL drop handling is a property describing whether the hosting shell component is allowed to install an event filter on the part's widget, to listen for URI drop events. Set it to true if you are exporting a \fBBrowserExtension\fP implementation and do not provide any special URI drop handling. If set to false you can be sure to receive all those URI drop events unfiltered. Also note that the implementation as of Konqueror installs the event filter only on the part's widget itself, not on child widgets. Definition at line 408 of file browserextension.cpp.
.SS "bool BrowserExtension::isActionEnabled (const char * name) const"
.PP
\fBReturns:\fP
.RS 4
the status (enabled/disabled) of an action. When the enableAction signal is emitted, the browserextension stores the status of the action internally, so that it's possible to query later for the status of the action, using this method. 
.RE
.PP
Definition at line 461 of file browserextension.cpp.
.PP
References KStdAccel::name().
.SS "\fBBrowserExtension::ActionSlotMap\fP BrowserExtension::actionSlotMap ()\fC [static]\fP"
.PP
Returns a map containing the action names as keys and corresponding SLOT()'ified method names as data entries. This is very useful for the host component, when connecting the own signals with the extension's slots. Basically you iterate over the map, check if the extension implements the slot and connect to the slot using the data value of your map iterator. Checking if the extension implements a certain slot can be done like this:
.PP
.PP
.nf

   extension->\fBmetaObject()\fP->slotNames().contains( actionName + '()' )
 
.PP
.PP
(note that \fCactionName\fP is the iterator's key value if already iterating over the action slot map, returned by this method)
.PP
Connecting to the slot can be done like this:
.PP
.PP
.nf

   connect( yourObject, SIGNAL( yourSignal() ),
            extension, mapIterator.data() )
 
.PP
.PP
(where 'mapIterator' is your \fBQMap<QCString,QCString>\fP iterator) Definition at line 468 of file browserextension.cpp.
.PP
References actionSlotMapPtr().
.SS "\fBBrowserExtension::ActionSlotMap\fP * BrowserExtension::actionSlotMapPtr ()\fC [static]\fP"
.PP
\fBReturns:\fP
.RS 4
a pointer to the static action-slot map. Preferred method to get it. The map is created if it doesn't exist yet 
.RE
.PP
Definition at line 473 of file browserextension.cpp.
.PP
Referenced by actionSlotMap().
.SS "\fBBrowserExtension\fP * BrowserExtension::childObject (\fBQObject\fP * obj)\fC [static]\fP"
.PP
Queries \fCobj\fP for a child object which inherits from this \fBBrowserExtension\fP class. Convenience method. Definition at line 515 of file browserextension.cpp.
.PP
References QObject::children().
.SS "void KParts::BrowserExtension::enableAction (const char * name, bool enabled)\fC [signal]\fP"
.PP
Enables or disable a standard action held by the browser. See class documentation for the list of standard actions. Referenced by BrowserExtension().
.SS "void KParts::BrowserExtension::openURLRequest (const \fBKURL\fP & url, const \fBKParts::URLArgs\fP & args = \fBKParts::URLArgs\fP())\fC [signal]\fP"
.PP
Asks the host (browser) to open \fCurl\fP. To set a reload, the x and y offsets, the service type etc., fill in the appropriate fields in the \fCargs\fP structure. Hosts should not connect to this signal but to \fBopenURLRequestDelayed\fP. Referenced by BrowserExtension().
.SS "void KParts::BrowserExtension::openURLRequestDelayed (const \fBKURL\fP & url, const \fBKParts::URLArgs\fP & args = \fBKParts::URLArgs\fP())\fC [signal]\fP"
.PP
This signal is emitted when openURLRequest is called, after a 0-seconds timer. This allows the caller to terminate what it's doing first, before (usually) being destroyed. Parts should never use this signal, hosts should only connect to this signal. 
.SS "void KParts::BrowserExtension::openURLNotify ()\fC [signal]\fP"
.PP
Tells the hosting browser that the part opened a new URL (which can be queried via \fBKParts::Part::url\fP(). This helps the browser to update/create an entry in the history. The part may \fInot\fP emit this signal together with \fBopenURLRequest\fP(). Emit \fBopenURLRequest\fP() if you want the browser to handle a URL the user asked to open (from within your part/document). This signal however is useful if you want to handle URLs all yourself internally, while still telling the hosting browser about new opened URLs, in order to provide a proper history functionality to the user. An example of usage is a html rendering component which wants to emit this signal when a child frame document changed its URL. Conclusion: you probably want to use \fBopenURLRequest\fP() instead. 
.SS "void KParts::BrowserExtension::setLocationBarURL (const \fBQString\fP & url)\fC [signal]\fP"
.PP
Updates the URL shown in the browser's location bar to \fCurl\fP. 
.SS "void KParts::BrowserExtension::setIconURL (const \fBKURL\fP & url)\fC [signal]\fP"
.PP
Sets the URL of an icon for the currently displayed page. 
.SS "void KParts::BrowserExtension::createNewWindow (const \fBKURL\fP & url, const \fBKParts::URLArgs\fP & args = \fBKParts::URLArgs\fP())\fC [signal]\fP"
.PP
Asks the hosting browser to open a new window for the given \fCurl\fP. The \fCargs\fP argument is optional additionnal information for the browser, 
.PP
\fBSee also:\fP
.RS 4
\fBKParts::URLArgs\fP 
.RE
.PP

.SS "void KParts::BrowserExtension::createNewWindow (const \fBKURL\fP & url, const \fBKParts::URLArgs\fP & args, const \fBKParts::WindowArgs\fP & windowArgs, \fBKParts::ReadOnlyPart\fP *& part)\fC [signal]\fP"
.PP
Asks the hosting browser to open a new window for the given \fCurl\fP and return a reference to the content part. The request for a reference to the part is only fullfilled/processed if the serviceType is set in the \fCargs\fP . (otherwise the request cannot be processed synchroniously. 
.SS "void KParts::BrowserExtension::loadingProgress (int percent)\fC [signal]\fP"
.PP
Since the part emits the jobid in the \fBstarted\fP() signal, progress information is automatically displayed. However, if you don't use a \fBKIO::Job\fP in the part, you can use \fBloadingProgress\fP() and \fBspeedProgress\fP() to display progress information. 
.SS "void KParts::BrowserExtension::speedProgress (int bytesPerSecond)\fC [signal]\fP"
.PP
\fBSee also:\fP
.RS 4
\fBloadingProgress\fP 
.RE
.PP

.SS "void KParts::BrowserExtension::popupMenu (const \fBQPoint\fP & global, const \fBKFileItemList\fP & items)\fC [signal]\fP"
.PP
Emit this to make the browser show a standard popup menu at the point \fCglobal\fP for the files \fCitems\fP. 
.SS "void KParts::BrowserExtension::popupMenu (\fBKXMLGUIClient\fP * client, const \fBQPoint\fP & global, const \fBKFileItemList\fP & items)\fC [signal]\fP"
.PP
Emit this to make the browser show a standard popup menu at the point \fCglobal\fP for the files \fCitems\fP. The GUI described by \fCclient\fP is being merged with the popupmenu of the host 
.SS "void KParts::BrowserExtension::popupMenu (const \fBQPoint\fP & global, const \fBKURL\fP & url, const \fBQString\fP & mimeType, mode_t mode = (mode_t)-1)\fC [signal]\fP"
.PP
Emit this to make the browser show a standard popup menu at the point \fCglobal\fP for the given \fCurl\fP. Give as much information about this URL as possible, like the \fCmimeType\fP and the file type (\fCmode\fP: S_IFREG, S_IFDIR...) 
.SS "void KParts::BrowserExtension::popupMenu (\fBKXMLGUIClient\fP * client, const \fBQPoint\fP & global, const \fBKURL\fP & url, const \fBQString\fP & mimeType, mode_t mode = (mode_t)-1)\fC [signal]\fP"
.PP
Emit this to make the browser show a standard popup menu at the point \fCglobal\fP for the given \fCurl\fP. Give as much information about this URL as possible, like the \fCmimeType\fP and the file type (\fCmode\fP: S_IFREG, S_IFDIR...) The GUI described by \fCclient\fP is being merged with the popupmenu of the host 
.SS "void KParts::BrowserExtension::selectionInfo (const \fBKFileItemList\fP & items)\fC [signal]\fP"
.PP
Inform the hosting application about the current selection. Used when a set of files/URLs is selected (with full information about those URLs, including size, permissions etc.) 
.SS "void KParts::BrowserExtension::selectionInfo (const \fBQString\fP & text)\fC [signal]\fP"
.PP
Inform the hosting application about the current selection. Used when some text is selected. 
.SS "void KParts::BrowserExtension::selectionInfo (const \fBKURL::List\fP & urls)\fC [signal]\fP"
.PP
Inform the hosting application about the current selection. Used when a set of URLs is selected. 
.SS "void KParts::BrowserExtension::mouseOverInfo (const \fBKFileItem\fP * item)\fC [signal]\fP"
.PP
Inform the hosting application that the user moved the mouse over an item. Used when the mouse is on an URL. 

.SH "Author"
.PP 
Generated automatically by Doxygen for kparts Library from the source code.
