namespace KParts

Public Types

• class BrowserInterface
• struct URLArgs
• struct WindowArgs
• class OpenURLEvent
• class BrowserExtension
• class BrowserHostExtension
• class BrowserRun
• namespace ComponentFactory
• class DockMainWindow
• class Part
• class Event
• class GUIActivateEvent
• class PartActivateEvent
• class PartSelectEvent
• class Factory
• class GenericFactoryBase
• class GenericFactory
• class HistoryProvider
• class MainWindow
• class PartManager
• class Plugin
• class PartBase
• class ReadOnlyPart
• class ReadWritePart

Public Members

• Forward URLArgsPrivate
• Forward WindowArgsPrivate
• Forward BrowserExtensionPrivate
• Forward DockMainWindowPrivate
• GenericFactoryBase *GenericFactoryBase::s_self
• KInstance *GenericFactoryBase::s_instance
• KAboutData *GenericFactoryBase::s_aboutData
• Forward MainWindowPrivate
• Forward PartPrivate
• Forward PartBasePrivate
• Forward ReadOnlyPartPrivate
• Forward PartManagerPrivate

Detailed Description

vim: et sw=4

The purpose of this interface is to allow a direct communication between a KPart and the hosting browser shell (for example Konqueror) . A shell implementing this interface can propagate it to embedded kpart components by using the setBrowserInterface call of the part's KParts::BrowserExtension object.

This interface looks not very rich, but the main functionality is implemented using the callMethod method for part->shell communication and using Qt properties for allowing a part to to explicitly query information from the shell.

Konqueror in particular, as 'reference' implementation, provides the following functionality through this interface:

Qt properties: Q_PROPERTY( uint historyLength READ historyLength );

Callable methods: void goHistory( int );

URLArgs is a set of arguments bundled into a structure, to allow specifying how a URL should be opened by openURL(). In other words, this is like arguments to openURL(), but without have to change the signature of openURL() (since openURL is a generic KParts method). The parts (with a browser extension) who care about urlargs will use those arguments, others will ignore them.

This can also be used the other way round, when a part asks for a URL to be opened (with openURLRequest or createNewWindow).

The WindowArgs are used to specify arguments to the "create new window" call (see the createNewWindow variant that uses WindowArgs). The primary reason for this is the javascript window.open function.

The Browser Extension is an extension (yes, no kidding) to KParts::ReadOnlyPart, which allows a better integration of parts with browsers (in particular Konqueror). Remember that ReadOnlyPart 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 URLArgs), 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.

The part developer needs to define its own class derived from BrowserExtension, to implement the virtual methods [and the standard-actions slots, see below].

The way to associate the BrowserExtension with the part is to simply create the BrowserExtension as a child of the part (in QObject's terms). The hosting application will look for it automatically.

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).

The following standard actions are defined by the host of the view :

[selection-dependent actions]

• cut : Copy selected items to clipboard and store 'not cut' in clipboard.
• copy : Copy selected items to clipboard and store 'cut' in clipboard.
• paste : Paste clipboard into selected items.
• rename : Rename item in place.
• trash : Move selected items to trash.
• del : Delete selected items (couldn't call it delete!).
• shred : Shred selected items (secure deletion).
• properties : Show file/document properties.
• editMimeType : show file/document's mimetype properties.

[normal actions]

• print : Print :-)
• reparseConfiguration : Re-read configuration and apply it.
• refreshMimeTypes : If the view uses mimetypes it should re-determine them.

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).

The selection-dependent actions are disabled by default and the view should enable them when the selection changes, emitting enableAction().

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.

A special case is the configuration slots, not connected to any action directly, and having parameters.

[configuration slot]

• setSaveViewPropertiesLocally( bool ): If true, view properties are saved into .directory otherwise, they are saved globally.

An extension class for container parts, i.e. parts that contain other parts. For instance a KHTMLPart hosts one part per frame.

This class extends KRun to provide additional functionality for browsers: - "save or open" dialog boxes - "save" functionality - support for HTTP POST (including saving the result to a temp file if opening a separate application) - warning before launching executables off the web - custom error handling (i.e. treating errors as HTML pages) - generation of SSL metadata depending on the previous URL shown by the part

A KPart-aware main window with ability for docking widgets, whose user interface is described in XML.

Inherit your main dock-window from this class and don't forget to call setXMLFile() in the inherited constructor.

It implements all internal interfaces in the case of a KDockMainWindow as host: the builder and servant interface (for menu merging).

Base class for parts.

A "part" is a GUI component, featuring:

• A widget embeddedable in any application.
• GUI elements that will be merged in the "host" user interface (menubars, toolbars... ).

About the widget Note that KParts::Part does not inherit QWidget. This is due to the fact that the "visual representation" will probably not be a mere QWidget, but an elaborate one. That's why when implementing your KParts::Part (or derived) you should call KParts::Part::setWidget() in your constructor.

About the GUI elements Those elements trigger actions, defined by the part (action()). The layout of the actions in the GUI is defined by an XML file (setXMLFile()).

See also ReadOnlyPart and ReadWritePart, which define the framework for a "viewer" part and for an "editor"-like part. Use Part directly only if your part doesn't fit into those.

Base class for all KParts events.

This event is sent to a Part when its GUI has been activated or deactivated. This is related to PartActivateEvent, but the difference is that GUIActivateEvent happens later (when the GUI is actually built), only for parts that have GUI elements, and only if using KParts::MainWindow.

See also: KParts::Part::guiActivateEvent()

This event is sent by the part manager when the active part changes. Each time the active part changes, it will send first a PartActivateEvent with activated=false, part=oldActivePart, widget=oldActiveWidget and then another PartActivateEvent with activated=true, part=newPart, widget=newWidget.

See also: partActivateEvent

This event is sent when a part is selected or deselected.

See also: setSelectionPolicy

A generic factory object to create a Part.

Factory is an abstract class. Reimplement the createPartObject() method to give it functionality.

See also: KLibFactory.

A template for a KParts::Factory implementation. It implements the pure virtual createPartObject method by instantiating the template argument when requested through the className field. In addition it is a container for a part's KInstance object, by providing a static KInstance *instance() method.

The template argument has to inherit from KParts::Part and has to implement two methods: 1) There needs to be a public constructor with the following signature: MyPart( QWidget *parentWidget, const char *widgetName, QObject *parent, const char *name )

2) It needs to provide one static method to create a KAboutData object per request, holding information about the component's name, its authors, license, etc. The signature of that static method has to be KAboutData *createAboutData()

The template will take care of memory management of the KInstance and the KAboutData object.

For advanced use you can also inherit from the template and re-implement additionally the virtual KInstance *createInstance() method, for example in case you want to extend the paths of your instance's KStandardDirs object.

If a KParts::ReadOnlyPart is requested through this factory and the template argument implements a KParts::ReadWritePart then setReadWrite( false ) will automatically be called in createPartObject.

Basic class to manage a history of "items". This class is only meant for fast lookup, if an item is in the history or not.

May be subclassed to implement a persistent history for example. For usage with khtml, just create your provider and call the HistoryProvider constructor _before_ you do any khtml stuff. That way, khtml, using the self()-method, will use your subclassed provider.

A KPart-aware main window, whose user interface is described in XML.

Inherit your main window from this class and don't forget to call setXMLFile() in the inherited constructor.

It implements all internal interfaces in the case of a KMainWindow as host: the builder and servant interface (for menu merging).

The part manager is an object which knows about a collection of parts (even nested ones) and handles activation/deactivation.

Applications that want to embed parts without merging GUIs only use a KParts::PartManager. Those who want to merge GUIs use a KParts::MainWindow for example, in addition to a part manager.

Parts know about the part manager to add nested parts to it. See also KParts::Part::manager() and KParts::Part::setManager().

A plugin is the way to add actions to an existing KParts application, or to a Part.

The XML of those plugins looks exactly like of the shell or parts, with one small difference: The document tag should have an additional attribute, named "library", and contain the name of the library implementing the plugin.

If you want this plugin to be used by a part, you need to install the rc file under the directory "data" (KDEDIR/share/apps usually)+"/instancename/kpartplugins/" where instancename is the name of the part's instance.

Base class for all parts.

Base class for any "viewer" part.

This class takes care of network transparency for you, in the simplest way (synchronously). To use the built-in network transparency, you only need to implement openFile(), not openURL(). To prevent network transparency, or to implement it another way (e.g. asynchronously), override openURL().

KParts Application can use the signals to show feedback while the URL is being loaded.

ReadOnlyPart handles the window caption by setting it to the current URL (set in openURL(), and each time the part is activated). If you want another caption, set it in openFile() and (if the part might ever be used with a part manager) in guiActivateEvent()

Base class for an "editor" part.

This class handles network transparency for you. Anything that can open a URL, allow modifications, and save (to the same URL or a different one).

A read-write part can be set to read-only mode, using setReadWrite().

Part writers : Any part inheriting ReadWritePart should check isReadWrite before allowing any action that modifies the part. The part probably wants to reimplement setReadWrite, disable those actions. Don't forget to call the parent setReadWrite.