Katana_mirror/kdelibs
1
0
Fork 0
mirror of https://bitbucket.org/smil3y/kdelibs.git synced 2025-02-24 02:42:48 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

remove all doxygen pages and add top-level config

Browse source
This commit is contained in:
Ivailo Monev 2014-12-04 20:34:48 +00:00
parent 2a9f7d48de
commit c88b5ef465
31 changed files with 2331 additions and 3716 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

201
Mainpage.dox
View file

@ -1,201 +0,0 @@
/** @mainpage The KDE Library API Reference
<p><b>
Overview |
@ref components |
@ref development |
@ref search
</b></p>
This is the online reference for developing with the KDE libraries
(kdelibs).
The KDE libraries build on the
<a href="http://qt-project.org/">Qt</a> framework to
provide a powerful framework to make writing applications easier,
and provide consistency across the KDE desktop environment.
Among other things, the KDE libraries provide:
- standard user interface elements, on top of those provided by Qt
(<a href="kdeui/html/index.html">KDEUI</a>)
- a standard configuration format and method of reading and writing
configuration data (<a href="kdecore/html/classKConfig.html">KConfig</a>)
- site-independent access to standard directories, for finding resources such
as icons (<a href="kdecore/html/classKStandardDirs.html">KStandardDirs</a>)
- network transparent input and output (<a href="kio/html/index.html">KIO</a>)
- a method of embedding application components in other applications
(<a href="kparts/html/index.html">KParts</a>)
- straightforward multimedia and hardware interaction
(<a href="/kdesupport-api/phonon-apidocs/">Phonon</a> and
<a href="solid/html/index.html">Solid</a>)
- an application scripting framework
(<a href="kross/html/index.html">Kross</a>)
Visit the <a href="http://techbase.kde.org/Development">development section of KDE
Techbase</a> for tutorials, architectural overviews and other useful information.
@authors
Far too many to list. See the copyright notices on the individual files,
as well as the pages for individual components.
@maintainers
There is no single maintainer for kdelibs. Overall direction is governed by the
<a href="https://mail.kde.org/mailman/listinfo/kde-core-devel">kde-core-devel
mailing list</a>. Some of the individual components have their own maintainers:
see the component pages for more information.
@licenses
Libraries: @lgpl<br>
Some helper binaries: @gpl<br>
Some code may have more permissive licenses.
*/
/** @page components Components
<p><b>
@ref index "Overview" |
Components |
@ref development |
@ref search
</b></p>
Below is a brief summary of the various libraries you may want to use
when developing a KDE application.
Note that there is more to kdelibs than these libraries: on the left
is a complete list of kdelibs components. However, in almost all cases
you will only be interested in the ones listed below. The remaining
ones are mostly implementation details that you don't need to worry
about.
There are also several components you can use. Interfaces to most of
these can be found in the <a href="interfaces/html/index.html">interfaces
section</a>, but you should also be aware of KHTMLPart, which
provides a full web browser component.
<dl>
<dt>KDECore</dt>
<dd>Core KDE classes that are not related to the user interface.<br>
[ <a href="kdecore/html/index.html">Documentation</a> |
<a href="kdecore/html/classes.html">Classes</a> ]</dd>
<dt>KIO</dt>
<dd>KDE's network-transparent input/output system: provides
just about every file-management function you'll ever need.<br>
[ <a href="kio/html/index.html">Documentation</a> |
<a href="kio/html/classes.html">Classes</a> ]</dd>
<dt>KDEUI</dt>
<dd>KDE User Interface classes such as widgets.<br>
[ <a href="kdeui/html/index.html">Documentation</a> |
<a href="kdeui/html/classes.html">Classes</a> ]</dd>
<dt>Phonon</dt>
<dd>KDE's multimedia framework.<br>
[ <a href="/kdesupport-api/kdesupport-apidocs/phonon/html/index.html">Documentation</a> |
<a href="/kdesupport-api/kdesupport-apidocs/phonon/html/group__Frontend.html">Classes</a> ]</dd>
<dt>Solid</dt>
<dd>KDE Hardware Discovery and Management classes.<br>
[ <a href="solid/html/index.html">Documentation</a> |
<a href="solid/html/classes.html">Classes</a> ]</dd>
<dt>KParts</dt>
<dd>The KDE component library: provides support for re-usable,
embeddable, extendible components for use in applications.<br>
[ <a href="kparts/html/index.html">Documentation</a> |
<a href="kparts/html/classes.html">Classes</a> ]</dd>
<dt>KNewStuff</dt>
<dd>Upload and download of application data.<br>
[ <a href="knewstuff/html/index.html">Documentation</a> |
<a href="knewstuff/html/classes.html">Classes</a> ]</dd>
<dt>KDEPrint</dt>
<dd>The KDE printing system.<br>
[ <a href="kdeprint/html/index.html">Documentation</a> |
<a href="kdeprint/html/classes.html">Classes</a> ]</dd>
<dt>DNSSD</dt>
<dd>Access to the DNSSD (aka Bonjour, Zeroconf) service publishing
and discovery protocol.<br>
[ <a href="dnssd/html/index.html">Documentation</a> |
<a href="dnssd/html/classes.html">Classes</a> ]</dd>
<dt>Kross</dt>
<dd>Allows scripting to be added to an application in an
interpreter-independent way.<br>
[ <a href="kross/html/index.html">Documentation</a> |
<a href="kross/html/classes.html">Classes</a> ]</dd>
<dt>ThreadWeaver</dt>
<dd>A job-based multi-threading library<br>
[ <a href="threadweaver/html/index.html">Documentation</a> |
<a href="threadweaver/html/classes.html">Classes</a> ]</dd>
<dt>KDESU</dt>
<dd>Run processes remotely or with elevated privileges.<br>
[ <a href="kdesu/html/index.html">Documentation</a> |
<a href="kdesu/html/classes.html">Classes</a> ]</dd>
<dt>KPty</dt>
<dd>A library for interfacing with pseudo terminals.<br>
[ <a href="kpty/html/index.html">Documentation</a> |
<a href="kpty/html/classes.html">Classes</a> ]</dd>
</dl>
*/
/** @page development Development
<p><b>
@ref index "Overview" |
@ref components |
Development |
@ref search
</b></p>
To follow or get involved with the development of the KDE libraries,
join the <a href="https://mail.kde.org/mailman/listinfo/kde-core-devel">kde-core-devel
mailing list</a>.
Instructions for building a development version of KDE can be found in the
<a href="http://techbase.kde.org/Getting_Started">getting started</a> section
of the <a href="http://techbase.kde.org">KDE Techbase</a>.
*/
/** @page search Search
<p><b>
@ref index "Overview" |
@ref components |
@ref development |
Search
</b></p>
You can search for any class in the public API of the KDE libraries
here.
Note: only enter the class name, without any namespace qualifiers.
@htmlonly
<form action="http://api.kde.org/classmapper.php" method="get">
<input type="text" name="class" value="[classname]" style="width:100%;" onClick="this.value='';"/>
<input type="submit" name="go" value="Go" />
<input type=hidden name="module" value="kdelibs">
<input type=hidden name="version" value="4.8">
</form>
@endhtmlonly
If you want to search for any sort of identifier in kdelibs (and other code
in the KDE SVN repository), you can do so using the
<a href="http://lxr.kde.org">KDE Source Cross-Reference</a> tool.
*/
// DOXYGEN_NAME=kdelibs
// DOXYGEN_ENABLE=YES
// vim:ts=4:sw=4:expandtab:filetype=doxygen

40
dnssd/Mainpage.dox
View file

@ -1,40 +0,0 @@
/** @mainpage DNSSD
<p>DNSSD is a library for handling the DNS-based Service Discovery Protocol (DNS-SD),
the layer of <a href="http://www.zeroconf.org">Zeroconf</a> that allows network
services, such as printers, to be discovered without any user intervention or
centralized infrastructure.</p>
Apple's implementation of Zeroconf is
<a href="http://www.apple.com/macosx/technology/bonjour.html">Bonjour</a>.
Apple's developer documentation provides lots of information about Bonjour
in its <a href="http://developer.apple.com/documentation/Cocoa/Conceptual/NetServices/Articles/about.html#//apple_ref/doc/uid/TP40002458-SW1">Bonjour overview</a>.
If you are writing an application that wants to discover services on the network,
use DNSSD::ServiceBrowser. You can also find available service types using ServiceTypeBrowser.
If you want to announce the availability of a service provided by your application,
use DNSSD::PublicService.
DNSSD::DomainBrowser allows you to find domains (other than the local one) recommended
for browsing or publishing to.
Note that DNSSD::ServiceBrowser::isAvailable() provides information about the availability
of the services provided by this library generally, not just for browsing services.
@authors
Jakub Stachowski
@maintainers
Jakub Stachowski
@licenses
@lgpl
*/
// KDE5: get rid of kdeui reference when settings.kcfgc is changed
// DOXYGEN_REFERENCES = kdecore kdeui
// DOXYGEN_SET_PROJECT_NAME = DNSSD
// DOXYGEN_SET_EXCLUDE_PATTERNS += */dnssd/avahi* */dnssd/mdnsd*
// vim:ts=4:sw=4:expandtab:filetype=doxygen

2331
doxygen.conf Normal file
View file

File diff suppressed because it is too large Load diff

50
interfaces/Mainpage.dox
View file

@ -1,50 +0,0 @@
/** @mainpage Interfaces
This section collects interfaces that can be implemented
by components. The interfaces provide well-defined functionality
and make it possible to substitute one component (that implements
a given interface) for another.
Documented interfaces are:
<dl>
<dt>KHexEdit</dt>
<dd>API for a byte editor<br>
[ <a href="../khexedit/html/index.html">Documentation</a> |
<a href="../khexedit/html/classes.html">Classes</a> ]</dd>
<dt>%KIMProxy</dt>
<dd>API for an instant messaging service<br>
[ @ref KIMProxy "Documentation" ]</dd>
<dt>KMediaPlayer</dt>
<dd>API for re-usable media player components<br>
[ <a href="../kmediaplayer/html/index.html">Documentation</a> |
<a href="../kmediaplayer/html/classes.html">Classes</a> ]</dd>
<dt>KRegExpEditor</dt>
<dd>API for a regular expression editor<br>
[ @ref KRegExpEditorInterface "Documentation" ]</dd>
<dt>KSpeech</dt>
<dd>API for a Text-to-Speech service over D-Bus<br>
[ <a href="../kspeech/html/index.html">Documentation</a> |
<a href="../kspeech/html/classes.html">Classes</a> ]</dd>
<dt>Terminal</dt>
<dd>API for a console KPart<br>
[ @ref TerminalInterface "Documentation" ]</dd>
<dt>KTextEditor</dt>
<dd>API for a plain-text editor<br>
[ <a href="../ktexteditor/html/index.html">Documentation</a> |
<a href="../ktexteditor/html/classes.html">Classes</a> ]</dd>
</dl>
*/
// DOXYGEN_REFERENCES = kdecore kdeui kio kparts
// DOXYGEN_EXCLUDE = khexedit kspeech ktexteditor kmediaplayer
// DOXYGEN_SET_RECURSIVE = YES
// DOXYGEN_SET_PROJECT_NAME = Interfaces
// vim:ts=4:sw=4:expandtab:filetype=doxygen

117
interfaces/khexedit/Mainpage.dox
View file

@ -1,117 +0,0 @@
/*
This file is part of the KDE project
Copyright 2007 by Friedrich W. H. Kossebau <kossebau@kde.org>
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2
or any later version published by the Free Software Foundation;
*/
/** @mainpage KHexEdit
@section khe_intro Introduction
The KHexEdit interfaces - also called KHE interfaces - are a set of
well-defined interfaces which a library can implement to provide
byte level editing services. Programs which utilise these interfaces
can thus allow the user to choose which implementation of the hex editor component
to use. At the time of KDE Platform 4.6 the only implementation known is the
<a href="http://utils.kde.org/projects/okteta">Okteta</a> Component
(found in
<a href="http://websvn.kde.org/trunk/KDE/kdesdk/okteta/parts/kbytesedit/">kdesdk/okteta/parts/kbytesedit</a>).
@section khe_howto How to use the KHexEdit Interfaces
This HOWTO will explain step by step how to create a KHexEdit component and
prepare it for usage.
@subsection khe_howto_source The code lines
The following source code tries to create a hexedit component.
If the component could not be created, a simple message label is created.
Otherwise we set the data and configure it to our needs
by using the different interfaces if available.
@code
// used interfaces
#include <khexedit/byteseditinterface.h>
#include <khexedit/valuecolumninterface.h>
#include <khexedit/charcolumninterface.h>
#include <khexedit/clipboardinterface.h>
//
const char *data = 0;
int dataSize = 0;
// create data field and set dataSize
// ...
QWidget *bytesEditWidget = KHE::createBytesEditWidget( parent );
// no hexedit component installed?
if( !bytesEditWidget )
{
bytesEditWidget = new QLabel( parent, i18n("Could not find a hexedit component.") );
}
// component found and widget created
else
{
// fetch the editor interface
KHE::BytesEditInterface *bytesEdit = KHE::bytesEditInterface( bytesEditWidget );
Q_ASSERT( bytesEdit ); // This should not fail!
// now use the editor.
bytesEdit->setData( data, dataSize, -1 );
bytesEdit->setMaxDataSize( dataSize );
bytesEdit->setReadOnly( false );
bytesEdit->setAutoDelete( true );
KHE::ValueColumnInterface *valueColumn = KHE::valueColumnInterface( bytesEditWidget );
if( valueColumn )
{
valueColumn->setCoding( KHE::ValueColumnInterface::BinaryCoding );
valueColumn->setByteSpacingWidth( 2 );
valueColumn->setNoOfGroupedBytes( 4 );
valueColumn->setGroupSpacingWidth( 12 );
}
KHE::CharColumnInterface *charColumn = KHE::charColumnInterface( bytesEditWidget );
if( charColumn )
{
charColumn->setShowUnprintable( false );
charColumn->setSubstituteChar( '*' );
}
KHE::ClipboardInterface *clipboard = KHE::clipboardInterface( bytesEditWidget );
if( clipboard )
{
// Yes, use bytesEditWidget, not clipboard, because that's the QObject, indeed hacky...
connect( bytesEditWidget, SIGNAL(copyAvailable(bool)), this, SLOT(offerCopy(bool)) );
}
}
// now you can use bytesEditWidget like any other widget object...
@endcode
@subsection khe_howto_notes Notes
As the KHexEdit interfaces are header-only, you don't need to link
against any additional libraries.
@authors
Friedrich W. H. Kossebau \<kossebau\@kde.org\>
@maintainers
Friedrich W. H. Kossebau \<kossebau\@kde.org\>
@licenses
@lgpl
*/
// DOXYGEN_REFERENCES = kdecore kdeui kio kparts
// DOXYGEN_SET_PROJECT_NAME = KHexEdit
// vim:ts=4:sw=4:expandtab:filetype=doxygen

19
interfaces/kmediaplayer/Mainpage.dox
View file

@ -1,19 +0,0 @@
/** @mainpage KMediaPlayer
%KMediaPlayer provides an API for re-usable media player components.
<p>
@ref KMediaPlayer::Player "Player" provides all the necessary media
player operations, with an optional GUI to control them.
@authors
Neil Stevens \<neil@qualityassistant.com\> (@ref KMediaPlayer::Player "Player", @ref KMediaPlayer::View "View")<br>
@licenses
@x11 (@ref KMediaPlayer::Player "Player", @ref KMediaPlayer::View "View")<br>
*/
// DOXYGEN_REFERENCES = kdecore kdeui kio kparts
// DOXYGEN_SET_PROJECT_NAME = KMediaPlayer
// DOXYGEN_EXCLUDE += kfileaudiopreview
// vim:ts=4:sw=4:expandtab:filetype=doxygen

1328
interfaces/kspeech/Mainpage.dox
View file

File diff suppressed because it is too large Load diff

635
interfaces/ktexteditor/Mainpage.dox
View file

@ -1,635 +0,0 @@
/*
This file is part of the KDE project
Copyright (c) 2005-2006 by Dominik Haumann <dhdev@gmx.de>
Copyright (c) 2005 by Christoph Cullmann <cullmann@kde.org>
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2
or any later version published by the Free Software Foundation;
*/
/** \mainpage KTextEditor
<p><b>
Overview |
\ref kte_design "Design" |
\ref kte_guidelines "Coding Guidelines" |
\ref kte_port_to_kde4 "Porting to KDE 4" |
\ref kte_howto "Using"
</b></p>
\section kte_intro Introduction
The KTextEditor interfaces - also called KTE interfaces - are a set of
well-defined interfaces which an application or library can implement to provide
advanced plain text editing services. Applications which utilise this interface
can thus allow the user to choose which implementation of the editor component
to use. The only implementation right now is the Kate Editor Component
(Kate Part).
\section kte_general General
- \ref kte_design
- \ref kte_howto
- \ref kte_port_to_kde4
- <a href="http://www.kate-editor.org/support">Contact/Mailing Lists</a>
\section kte_notes Implementation Notes
- \ref kte_guidelines
\section kte_extensions Extension Interfaces
- \ref kte_group_doc_extensions
- \ref kte_group_view_extensions
- \ref kte_group_editor_extensions
- \ref kte_group_plugin_extensions
- \ref kte_group_command_extensions
- \ref kte_group_ccmodel_extensions
\section kte_apiref API Reference
- <a href="classes.html">All Classes</a>
- <a href="annotated.html">Annotated Classes</a>
- <a href="hierarchy.html">Inheritance Hierarchy</a>
<!-- grouped classes -> TODO Grouping -->
@authors
Dominik Haumann \<dhdev@gmx.de\><br>
Christoph Cullmann \<cullmann@kde.org\><br>
Hamish Rodda \<rodda@kde.org\><br>
Joseph Wenninger \<jowenn@kde.org\><br>
Jochen Wilhelmy \<digisnap@cs.tu-berlin.de\><br>
Anders Lund \<anders@alweb.dk\><br>
Matt Broadstone \<mbroadst@gmail.com\>
@maintainers
Dominik Haumann \<dhdev@gmx.de\><br>
Christoph Cullmann \<cullmann@kde.org\><br>
Hamish Rodda \<rodda@kde.org\>
@licenses
@lgpl
*/
/** \page kte_design Overview of the Core Interface Design
<p><b>
\ref index "Overview" |
Design |
\ref kte_guidelines "Coding Guidelines" |
\ref kte_port_to_kde4 "Porting to KDE 4" |
\ref kte_howto "Using"
</b></p>
The core of the KTextEditor interfaces consists of several main interfaces:
- KTextEditor::Factory \n
The Factory provides access to the editor object.
- KTextEditor::Editor \n
The Editor interface allows you to create documents, get a document list,
and a be informed when a new document is created.
- KTextEditor::Document \n
The Document interface represents a single document and enables the creation of
views, access to and manipulation of document contents, and access to document
extension interfaces.
- KTextEditor::View \n
The View provides a widget that displays the contents of a Document, and its
interface allows for manipulation of text selection, position of the cursor and mouse,
text selections, and behaviour of the view. Additionally it provides access to
the view extension interfaces.
The hierarchy can be illustrated as follows:
\image html ktexteditorhierarchy.png "Basic KTextEditor Hierarchy"
\section kte_design_user Notes for KTextEditor Users
To use a KTextEditor implementation you first have to get the
KTextEditor::Editor object. This can be done in several ways and is described
in detail in the following documentation:
- KTextEditor::Factory
- KTextEditor::EditorChooser
\section kte_design_developer Notes for KTextEditor Developers
The KTextEditor::Factory provides access to its KTextEditor::Editor. The
Editor has a list of all opened documents and can create new documents. A
Document's content is visualized by a View. A Document can have any number of
views (or none). When the contents of the document are changed, the change
is reflected in all views.
The Factory \e should always return the same Editor object, as
it does not make sense to load the same editor implementation several times.
Further notes about the Editor implementation can be found in the
\ref editor_notes.
As applications can load different editor implementations via different
factories (for example the kate-part and the yzis-part) the signal
KTextEditor::Editor::documentCreated() contains the responsible Editor as
first argument.
\see KTextEditor::Factory, KTextEditor::Editor, KTextEditor::Document,
KTextEditor::View
\author Dominik Haumann \<dhdev@gmx.de\>
*/
/** \page kte_guidelines Coding Guidelines and API Conventions
<p><b>
\ref index "Overview" |
\ref kte_design "Design" |
Coding Guidelines |
\ref kte_port_to_kde4 "Porting to KDE 4" |
\ref kte_howto "Using"
</b></p>
All KTextEditor interfaces have a consistent design.
- naming follows Qt style. Avoid Java style getters like getSomeData()
for example,
- core interfaces (see \ref kte_design) which inherit QObject declare all
signals as real signals,
- all other interfaces, which do not subclass QObject, must declare their
signals as virtual private member functions. An implementation must
reimplement this virtual member function as a real signal.
- all signals have the sender object as first parameter, for example
all document signals have to look like this:
\code
void signalFromDocument (KTextEditor::Document *doc, ...);
\endcode
This allows easy and consistent query which object did send the signal,
which is important for most applications, as they listen to multiple
documents/views/editors/...
- all interface functions should be virtual, to allow subclasses to
overwrite them, most members should even be pure virtual, beside
additional convenience/helper functions.
The interface KTextEditor::Cursor represents a cursorposition, i.e. a
line/column tuple. The same holds for KTextEditor::Range. As both of this
concepts are much cleaner than tuples, please keep the following guidelines:
- never use line/column tuples in parameter lists, use KTextEditor::Cursor
instead,
- never use Cursor/Cursor tuples for ranges, use KTextEditor::Range
instead of two Cursors.
\author Christoph Cullmann \<cullmann@kde.org\>
\author Dominik Haumann \<dhdev@gmx.de\>
*/
/** \defgroup kte_group_doc_extensions Document Extension Interfaces
A KTextEditor implementation may implement a Document extension interface, but
it does not \e need to. So as a KTextEditor user you have to cast the Document
to the desired interface and then check, whether the cast returns NULL or the
valid interface.
Use qobject_cast to cast a Document \e doc into the
\e DesiredExtensionInterface, example:
\code
// doc is of type KTextEditor::Document*
KTextEditor::DesiredExtensionInterface *iface =
qobject_cast<KTextEditor::DesiredExtensionInterface*>( doc );
if( iface ) {
// the implementation supports the interface
// do stuff
}
else
{
// the implementation does not support the interface
}
\endcode
\see KTextEditor::Document
The following classes are a list of all available Document extension interfaces.
<!-- The classes are defined by the \ingroup doxygen command -->
*/
/** \defgroup kte_group_smart_classes Smart Cursors and Ranges
\ingroup kte_group_doc_extensions
If the KTextEditor implementation supports the KTextEditor::SmartInterface,
there are several \e smart classes available.
In general, instances of the \e smart classes are bound to a specific document, and maintain their
position in that document regardless of changes to the text. They also provide:
- feedback on changes to their position and changes to text related to their position,
- support for the other \e smart interfaces, such as arbitrary highlighting, action binding, etc.
The following is a list of all classes that are available when the document
supports the KTextEditor::SmartInterface:
\warning All Smart interfaces were deprecated and not implemented anymore in
KDE >= 4.6. They were replaced by the \ref kte_group_moving_classes
<!-- The classes are defined by the \ingroup doxygen command -->
*/
/** \defgroup kte_group_moving_classes MovingCursors and MovingRanges
\ingroup kte_group_doc_extensions
If the KTextEditor implementation supports the KTextEditor::MovingInterface,
there are several \e moving classes available.
Instances of the \e moving classes are bound to a specific Document, and
maintain their position in that document regardless of changes to the text.
Changes to MovingRange%s can be caught by using the class MovingRangeFeedback.
The following is a list of all classes that are available when the document
supports the KTextEditor::MovingInterface:
<!-- The classes are defined by the \ingroup doxygen command -->
*/
/** \defgroup kte_group_view_extensions View Extension Interfaces
A KTextEditor implementation may implement a View extension interface, but
it does not \e need to. So as a KTextEditor user you have to cast the View
to the desired interface and then check, whether the cast returns NULL or the
valid interface.
Use qobject_cast to cast a View \e view into the
\e DesiredExtensionInterface, example:
\code
// view is of type KTextEditor::View*
KTextEditor::DesiredExtensionInterface *iface =
qobject_cast<KTextEditor::DesiredExtensionInterface*>( view );
if( iface ) {
// the implementation supports the interface
// do stuff
}
else
{
// the implementation does not support the interface
}
\endcode
\see KTextEditor::View
The following classes are a list of all available View extension interfaces.
<!-- The classes are defined by the \ingroup doxygen command -->
*/
/** \defgroup kte_group_editor_extensions Editor Extension Interfaces
A KTextEditor implementation may implement an Editor extension interface, but
it does not \e need to. So as a KTextEditor user you have to cast the Editor
to the desired interface and then check, whether the cast returns NULL or the
valid interface.
Use qobject_cast to cast a Editor \e editor into the
\e DesiredExtensionInterface, example:
\code
// editor is of type KTextEditor::Editor*
KTextEditor::DesiredExtensionInterface *iface =
qobject_cast<KTextEditor::DesiredExtensionInterface*>( view );
if( iface ) {
// the implementation supports the interface
// do stuff
}
else
{
// the implementation does not support the interface
}
\endcode
\see KTextEditor::Editor
The following classes are a list of all available Editor extension interfaces.
<!-- The classes are defined by the \ingroup doxygen command -->
*/
/** \defgroup kte_group_plugin_extensions Plugin Extension Interfaces
A KTextEditor Plugin can use extension interfaces, but it does not \e need
to. So as a KTextEditor implementator you have to cast the Plugin to the desired
interface and then check, whether the cast returns NULL or the valid interface.
Use qobject_cast to cast a Plugin \e plugin into the
\e DesiredExtensionInterface, example:
\code
// plugin is of type KTextEditor::Plugin*
KTextEditor::DesiredExtensionInterface *iface =
qobject_cast<KTextEditor::DesiredExtensionInterface*>( plugin );
if( iface ) {
// the implementation supports the interface
// do stuff
}
else
{
// the implementation does not support the interface
}
\endcode
\see KTextEditor::Plugin
The following classes are a list of all available Plugin extension interfaces.
<!-- The classes are defined by the \ingroup doxygen command -->
*/
/** \defgroup kte_group_command_extensions Command Extension Interfaces
A KTextEditor command-line Command can use extension interfaces, but it does not
\e need to. So as a KTextEditor implementator you have to cast the Command to
the desired interface and then check, whether the cast returns NULL or the valid
interface.
Use qobject_cast to cast a Command \e cmd into the
\e DesiredExtensionInterface, example:
\code
// cmd is of type KTextEditor::Command*
KTextEditor::DesiredExtensionInterface *iface =
qobject_cast<KTextEditor::DesiredExtensionInterface*>( cmd );
if( iface ) {
// the implementation supports the interface
// do stuff
}
else
{
// the implementation does not support the interface
}
\endcode
\see KTextEditor::Command
The following classes are a list of all available Command extension interfaces.
<!-- The classes are defined by the \ingroup doxygen command -->
*/
/** \defgroup kte_group_ccmodel_extensions CodeCompletionModel Extension Interfaces
A CodeCompletionModel implementation may implement a CodeCompletionModel
extension interface, but it does not \e need to.
\see KTextEditor::CodeCompletionModel
The following classes are a list of all available CodeCompletionModel
extension interfaces.
<!-- The classes are defined by the \ingroup doxygen command -->
*/
/** \page kte_port_to_kde4 Porting to KDE 4
<p><b>
\ref index "Overview" |
\ref kte_design "Design" |
\ref kte_guidelines "Coding Guidelines" |
Porting to %KDE 4 |
\ref kte_howto "Using"
</b></p>
This document describes porting applications using the KTextEditor interfaces
from KDE 3 to KDE 4. This page does not try to be complete; its main goal is
to show what interfaces were removed, changed or added to give some impression
and orientation of what you have to do to port your application to the KDE 4
KTextEditor interfaces.
\section kte_port_intro Introduction
The KTextEditor interfaces changes in KDE 4 are neither binary nor source
compatible to the KTextEditor interfaces included in KDE 3, so programs
written/compiled for the KDE 3 KTextEditor interfaces will not compile
(nor run) under KDE 4. There are no plans to provide a compatibility layer.
The KDE 4 KTextEditor interfaces undergone a heavy cleanup, i.e. obsolete
functions were removed, interfaces were merged and extended. All interface
changes like for example parameter changes of a function are not mentioned in
detail in this page, look into the particular class API documentation. As
already mentioned in the mainpage, all line/column tuples were replaced with a
KTextEditor::Cursor, and all Cursor/Cursor tuples with a KTextEditor::Range.
A KTextEditor::Factory class was introduced to access a specific Editor
implementation, read \ref kte_design for detailed information.
\section kte_port_remove Removed Interfaces
Some interfaces were removed mainly because they described user actions which
implementation and support is up to the KTextEditor part itself, like
printing, copy & paste and word wrapping. Entirely removed interfaces are, in
order:
- all DCOP interfaces
- \p ClipboardInterface
- \p CursorInterface
- \p DynWordWrapInterface
- \p PrintInterface
- \p SelectionExtDCOPInterface
- \p UndoInterface
- \p ViewStatusMsgInterface
- \p WordWrapInterface
\section kte_port_merge Merged Interfaces
The following interfaces were merged, in order:
- \p BlockSelectionInterface, \p SelectionInterface and
\p SelectionInterfaceExt were merged into the KTextEditor::View, so that a
KTextEditor::Document itself does not provide any selection methods anymore.
- \p ConfigInterface was partly merged into the KTextEditor::Editor and now
only contains very basic functions to set/get properties. Session related
config options can be configured in a new interface called
KTextEditor::SessionConfigInterface
- \p DocumentInfoInterface was merged into the KTextEditor::Document
- \p EditInterface was merged into the KTextEditor::Document
- \p EditInterfaceExt was merged into the KTextEditor::Document
- \p EncodingInterface was merged into the KTextEditor::Document
- \p HighlightingInterface was merged into the KTextEditor::Document
- \p MarkInterfaceExtension was merged into the KTextEditor::MarkInterface
- \p PluginViewInterface was merged into the KTextEditor::Plugin
- \p PopupMenuInterface was merged into the KTextEditor::View
- \p ViewCursorInterface was merged into the KTextEditor::View
\section kte_port_rename Interface Changes
The following interfaces were renamed:
- \p KTextEditor::CodeCompletionInterface was changed to support several
clients at once. A client registers a so-called
KTextEditor::CompletionProvider that provides its own completion and argument
hint da.
- \p CompletionEntry was renamed to KTextEditor::CompletionItem
- signal \p modifiedOnDisc() was renamed to
KTextEditor::ModificationInterface::modifiedOnDisk()
\section kte_port_new New Interfaces
The following interfaces are new:
- KTextEditor::CommandInterface, support for command-line commands
- KTextEditor::ModificationInterface, support for handling external modified
files
- KTextEditor::SessionConfigInterface, support for session specific settings
- KTextEditor::SmartInterface, support for smart cursors + ranges, plus their
uses such as arbitrary highlighting and action association
\section kte_port_enhanced_classes Significantly Enhanced Classes
The following classes have been significantly enhanced:
- KTextEditor::Cursor \n
Has been upgraded for greatly increased convenience, and now forms a
cornerstone of the KTextEditor interfaces.
\section kte_port_new_classes New Classes
The following classes are new:
- KTextEditor::SmartCursor \n
A cursor which is bound to a specific KTextEditor::Document, and maintains
its position.
- KTextEditor::SmartCursorWatcher and KTextEditor::SmartCursorNotifier \n
Classes for providing notifications of changes to a SmartCursor.
- KTextEditor::Range \n
A tuple of start + end cursors with many convenience methods
- KTextEditor::SmartRange \n
A KTextEditor::Range which is bound to a specific Document, and maintains its
position.
- KTextEditor::SmartRangeWatcher and KTextEditor::SmartRangeNotifier \n
Classes for providing notifications of changes to a SmartRange.
\section kte_port_plugins Plugin Architecture Changes
The KTextEditor::Plugin interface changed to support more than only one
KTextEditor::Document at a time. A plugin in a KDE 4 KTextEditor implementation
no longer is bound to a single document (i.e. for \e every document a single
instance of the plugin existed). Now, a plugin can handle several documents and
views. Also a plugin now is able to load and save session related config
settings if desired.
\see KTextEditor::Plugin
\author Dominik Haumann \<dhdev@gmx.de\>
\author Hamish Rodda \<rodda@kde.org\>
*/
/** \page kte_howto How to use the KTextEditor Interfaces
<p><b>
\ref index "Overview" |
\ref kte_design "Design" |
\ref kte_guidelines "Coding Guidelines" |
\ref kte_port_to_kde4 "Porting to KDE 4" |
Using
</b></p>
This HOWTO will explain step by step how to load a KTextEditor component and
plug a single View into a KMainWindow.
Tobics:
- \ref kte_howto_header
- \ref kte_howto_source
- \ref kte_howto_notes
\section kte_howto_header The Header File
The following class only contains two pointers to a Document and its View.
\code
#include <kxmlguiwindow.h>
namespace KTextEditor
{
class Document;
class View;
}
class MainWindow : public KXmlGuiWindow
{
Q_OBJECT
public:
MainWindow();
~MainWindow();
private:
KTextEditor::View *m_view;
KTextEditor::Document *m_document;
};
\endcode
\section kte_howto_source The Mainwindow Implementation
The following source code queries for a Editor part by using the EditorChooser.
If the returned Editor is invalid, we simply quit, otherwise we create a new
document and a view and plug it into the mainwindow.
\code
#include "mainwindow.h"
#include <ktexteditor/document.h>
#include <ktexteditor/view.h>
#include <ktexteditor/editor.h>
#include <ktexteditor/editorchooser.h>
#include <kxmlguifactory.h>
#include <kmessagebox.h>
MainWindow::MainWindow ()
: KXmlGuiWindow(),
m_view(0),
m_document(0)
{
KTextEditor::Editor *editor = KTextEditor::EditorChooser::editor();
if (!editor) {
KMessageBox::error(this, i18n("A KDE text-editor component could not be found;\n"
"please check your KDE installation."));
kapp->exit(1);
}
m_document = editor->createDocument(0);
m_view = m_document->createView(this);
setCentralWidget(m_view);
setXMLFile("mainwindowui.rc");
guiFactory()->addClient(m_view);
show ();
}
MainWindow::~MainWindow()
{
if (m_document) {
guiFactory()->removeClient(m_view);
// the document deletes its views itself
delete m_document;
}
}
\endcode
\section kte_howto_notes Notes
In order to compile link against the following libraries:
- ktexteditor
- kdeui
\author Dominik Haumann \<dhdev@gmx.de\>
*/
// DOXYGEN_REFERENCES = kdecore kdeui kio kparts
// DOXYGEN_SET_PROJECT_NAME = KTextEditor
// vim:ts=4:sw=4:expandtab:filetype=doxygen

17
kactivities/Mainpage.dox
View file

@ -1,17 +0,0 @@
/** @mainpage KActivities
@authors
See the copyright notices on the individual files.
@maintainers
See the MAINTAINER file
@licenses
@lgpl
*/
// DOXYGEN_SET_PROJECT_NAME = KActivities
// DOXYGEN_SET_RECURSIVE = YES
// DOXYGEN_EXCLUDE_PATTERNS = *_p.h */private/* */tests/* */ontologies/* */service/* */scripts/* */workspace/*
// vim:ts=4:sw=4:expandtab:filetype=doxygen

31
kconf_update/Mainpage.dox
View file

@ -1,31 +0,0 @@
/** @mainpage ./kconf_update
kconf_update is a tool designed to update config files. Over time applications
sometimes need to rearrange the way configuration options are stored. Since
such an update shouldn't influence the configuration options that the user
has selected, the application must take care that the options stored in the
old way will still be honored.
What used to happen is that the application looks up both the old and the
new configuration option and then decides which one to use. This method has
several drawbacks:
- The application may need to read more configuration files than strictly
needed, resulting in a slower startup.
- The application becomes bigger with code that will only be used once.
kconf_update addresses these problems by offering a framework to update
configuration files without adding code to the application itself.
See the <a href="http://websvn.kde.org/trunk/KDE/kdelibs/kconf_update/README.kconf_update?view=markup">README file</a> for more information.
@authors
Waldo Bastian \<bastian@kde.org\>
@maintainers
[Unknown/None]
@licenses
@lgpl
*/
// vim:ts=4:sw=4:expandtab:filetype=doxygen

45
kdecore/Mainpage.dox
View file

@ -1,45 +0,0 @@
/** \mainpage The KDE Core Library
All KDE programs use this library to provide basic functionality such
as the configuration system, IPC, internationalization and locale
support, site-independent access to the filesystem and a large number
of other (but no less important) things.
<p>
All KDE applications should link to the kdecore library. Also, using a
KApplication derived class instead of QApplication is almost
mandatory if you expect your application to behave nicely within the
KDE environment.
If you are unsure where to start, have a look at the
<a href="http://techbase.kde.org/Development/Tutorials">tutorials on
TechBase</a> to get you going.
If you know what you are looking for, you should be able to find it in
the <a href="annotated.html">class list</a> or the
<a href="modules.html">modules list</a>.
@authors
Various: see copyrights on individual files for more information
@maintainers
See the
<a href="http://websvn.kde.org/trunk/KDE/kdelibs/kdecore/MAINTAINERS?view=markup">MAINTAINERS</a>
file.
@licenses
Library: @lgpl<br>
Some helper utilities: @gpl
*/
/**
\defgroup KDEMacros KDE Macros
*/
// DOXYGEN_EXCLUDE = malloc kde_file.h
// DOXYGEN_SET_INPUT += @topdir@/kdemacros.h.cmake
// DOXYGEN_SET_INPUT += @topdir@/kdecore/util/kdeversion.h.cmake
// DOXYGEN_SET_PROJECT_NAME = KDECore
// vim:ts=4:sw=4:expandtab:filetype=doxygen

26
kded/Mainpage.dox
View file

@ -1,26 +0,0 @@
/** @mainpage The KDE Daemon
KDED runs in the background and performs a number of small tasks. Some
of these tasks are built in, others are started on demand.
<p>
The chances are you are looking here because you want to write a
KDED module. For that, see KDEDModule in kdecore and the
<a href="http://websvn.kde.org/trunk/KDE/kdelibs/kded/README.kded?view=markup">KDED
README</a>.
@authors
David Faure \<dfaure@kde.org\><br>
Waldo Bastian \<bastian@kde.org\>
@maintainers
[Unknown/None]
@licenses
@lgpl
*/
// DOXYGEN_REFERENCES = kdecore kdeui kio
// DOXYGEN_SET_PROJECT_NAME = KDED
// vim:ts=4:sw=4:expandtab:filetype=doxygen

21
kdesu/Mainpage.dox
View file

@ -1,21 +0,0 @@
/** @mainpage Console-mode authentication
libkdesu provides functionality for building GUI front ends for
(password asking) console mode programs. For example, kdesu and
kdessh use it to interface with su and ssh respectively.
@authors
Geert Jansen \<jansen@kde.org\>
@maintainers
Adriaan de Groot \<groot@kde.org\>
@licenses
@lgpl
*/
// DOXYGEN_REFERENCES = kdecore
// DOXYGEN_SET_PROJECT_NAME = KDEsu
// vim:ts=4:sw=4:expandtab:filetype=doxygen

65
kdeui/Mainpage.dox
View file

@ -1,65 +0,0 @@
/*
A dummy source file for documenting the library.
Sirtaj Singh Kang <taj@kde.org>
Distributed under the LGPL.
*/
/** @mainpage The KDE User Interface Library
This library provides standard user interface elements for use in
%KDE applications. If your %KDE application has a GUI, you will almost
certainly link to libkdeui.
<p>
Most applications with single or multiple toplevel widgets
should use the KMainWindow class in this library, which
automatically provides features like session management and simplified
toolbar/menubar/statusbar creation.
A spell-checker library is also provided.
Sonnet offers easy access to International ISpell or ASpell
(at the user's option) as well as a spell-checker GUI
("Add", "Replace", etc.).
You can use Sonnet to
automatically spell-check an ASCII file as well as to implement
online spell-checking and to spell-check proprietary format and
marked up (e.g. HTML, TeX) documents. The relevant methods for
these three procedures are check(), checkWord(), and
checkList(), respectively.
SonnetConfig holds configuration information about Sonnet as well
as acting as an options-setting dialog.
Sonnet usually works asynchronously. If you do not need that, you should
simply use Sonnet::modalCheck(). It won't return until the
passed string is processed or the spell checking canceled.
During modal spell checking your GUI is still repainted, but the user may
only interact with the Sonnet dialog.
@see Sonnet, SonnetConfig
@authors
Various: see the copyright headers of the individual files.
@maintainers
See the
<a href="http://websvn.kde.org/trunk/KDE/kdelibs/kdeui/MAINTAINERS?view=markup">MAINTAINERS</a>
file.
@licenses
@lgpl
*/
/**
\defgroup KDEUIMacros KDEUI Macros
*/
// DOXYGEN_REFERENCES = kdecore
// DOXYGEN_SET_INTERNAL_DOCS = YES
// DOXYGEN_SET_PROJECT_NAME = KDEUI
// DOXYGEN_SET_RECURSIVE = YES
// DOXYGEN_EXCLUDE_PATTERNS = *_p.h */tests/*
// vim:ts=4:sw=4:expandtab:filetype=doxygen

27
kdewebkit/Mainpage.dox
View file

@ -1,27 +0,0 @@
/**
* @mainpage The KDE WebKit Library
*
* This library provides KDE integration of the QtWebKit library. If you are
* using QtWebKit in your KDE application, you are encouraged to use this layer
* instead of using the QtWebKit classes directly.
*
* In particular, you should use KWebView in place of QWebView, KGraphicsWebView
* in place of QGraphicsWebView and KWebPage in place of QWebPage.
* See the documentation for those classes for more information.
*
* @authors
* Various: see the copyright headers of the individual files.
*
* @maintainers
* For support please use the webkit@kde.org mailing list.
*
* @licenses
* @lgpl
*
*/
// DOXYGEN_REFERENCES = kdecore kdeui kio
// DOXYGEN_SET_INTERNAL_DOCS = YES
// DOXYGEN_SET_PROJECT_NAME = KDEWebKit
// DOXYGEN_SET_RECURSIVE = YES
// vim:ts=4:sw=4:expandtab:filetype=doxygen

4
kdewebkit/kwebkitpart/Mainpage.dox
View file

@ -1,4 +0,0 @@
/** @mainpage
*
* Main Doxygen page for KWebKitPart.
*/

39
kfile/Mainpage.dox
View file

@ -1,39 +0,0 @@
/** @mainpage The File Selection Dialog
@section purpose Purpose
The kfile library provides the file selection dialog and its components.
@section desc Description
The file dialog is available to all kde applications by using the KFileDialog class
from the KIO library. This class doesn't contain the actual implementation of the file
dialog, however: it dynamically opens the code that contains the implementation.
The kfile library provides KFileWidget, which is the main widget in the file dialog, as well as
the KDirOperator widget which contains the file views, and other components of the file dialog.
Applications only need to link to libkfile if they need direct access to KFileWidget
or KDirOperator or to the other widgets used by the file dialog, either in order to
modify the behavior of the file dialog, or to reuse its components into the application itself.
Use ${KDE4_KFILE_LIBS} in the target_link_libraries of your CMakeLists.txt
to link to kfile.
@authors
Stephan Kulow<br>
Carsten Pfeiffer<br>
Peter Penz<br>
Aaron J. Seigo<br>
and others
@maintainers
David Faure
@licenses
@lgpl
*/
// DOXYGEN_REFERENCES = kdecore kdeui kio kde3support solid
// DOXYGEN_SET_PROJECT_NAME = KFile
// vim:ts=4:sw=4:expandtab:filetype=doxygen

29
kimgio/Mainpage.dox
View file

@ -1,29 +0,0 @@
/** @mainpage ImageFormat Plugins
Provides imageformat plugins for Qt so that it can read more image file types.
@authors
Sirtaj Singh Kang \<taj@kde.org><br>
Dirk Schoenberger<br>
Torben Weis \<weis@kde.org><br>
Thomas Tanghus \<tanghus@kde.org><br>
Antonio Larossa \<larossa@kde.org\><br>
Sven Wiegand \<SWiegand@tfh-berlin.de><br>
Dominik Seichter \<domseichter@web.de><br>
Nadeem Hasan \<nhasan@kde.org><br>
Melchior Franz \<mfranz@kde.org><br>
Allen Barnett \<allen@lignumcomputing.com><br>
Ignacio Castaño \<castano@ludicon.com><br>
Christoph Hormann \<chris_hormann@gmx.de><br>
Michael Ritzert \<kde@ritzert.de>
@maintainers
[Unknown/None]
@licenses
@lgpl
*/
// DOXYGEN_SET_PROJECT_NAME = KImgIO
// vim:ts=4:sw=4:expandtab:filetype=doxygen

29
kinit/Mainpage.dox
View file

@ -1,29 +0,0 @@
/** @mainpage KDE Initialization Routines
kdeinit is a process launcher somewhat similar to the
famous init used for booting UNIX.
<p>
It launches processes by forking and then loading a
dynamic library which should contain a 'main(...)'
function. This both increases the startup speed and
reduces the memory consumption of KDE applications.
kdeinit4_wrapper, kshell4 and kwrapper4 provide methods
of starting programs via kdeinit4.
@authors
Waldo Bastian \<bastian@kde.org\><br>
Process title changing code taken from the ProFTPD Project, adapted by Alex Merry
@maintainers
[Unknown/None]
@licenses
@gpl<br>
Most code is @lgpl
*/
// DOXYGEN_REFERENCES = kdecore
// DOXYGEN_SET_PROJECT_NAME = KInit
// vim:ts=4:sw=4:expandtab:filetype=doxygen

127
kio/Mainpage.dox
View file

@ -1,127 +0,0 @@
/** @mainpage KIO: Network-enabled File Management
<p><b>
Overview |
@ref filedialog "File Selector"
</b></p>
This library implements almost all the file management functions you
will ever need. In fact, the %KDE file manager, Konqueror also uses
this to provide its network-enabled file management.
The easiest way to use this library from a %KDE application is via the
KIO::NetAccess class (for easy synchronous access) or via the
KIO::Job class (for more complex asynchronous jobs).
This library also implements the %KDE file selector widget (see
@ref filedialog "the page on the file selector widget").
Use ${KDE4_KIO_LIBS} in the target_link_libraries of your CMakeLists.txt
to link to kio.
@authors
Various: see copyright headers in individual files
@maintainers
[Unknown/None]
@licenses
@lgpl
*/
/** @page filedialog KDE File Dialog Widget
<p><b>
@ref index "Overview" |
File Selector
</b></p>
This library provides the KDE file selector widget, its building blocks
and some other widgets that make use of the file selector.
The file dialog provides different views: there is a vertically scrolling
view based on K3ListView, showing things like filename, file size,
permissions etc. in separate columns. And there is a horizontally scrolling
view based on K3IconView. Additionally, there are some compound views,
like a view using the icon-view for files on the right side and another
view for directories on the left. A view, that shows a preview for the
currently selected file (using KIO::PreviewJob to generate previews)
and any other view to show the files is also available.
All those views share a common baseclass, named KFileView, which
defines the interface for inserting files into a view, removing them,
selecting etc.
The one class encapsulating all those views and adding browsing capabilities
to them is KDirOperator. It allows the user to switch between different
views.
KFileTreeView is a K3ListView based widget that displays files and/or
directories as a tree. It does not implement the KFileView interface,
however, so it can't be used with KDirOperator.
Besides the filebrowsing widgets, there is the KPropertiesDialog class,
implementing a dialog showing the name, permissions, icons, meta
information and all kinds of properties of a file, as well as providing a
means to modify them.
The KPropertiesDialog is extensible with plugin-pages via the
KPropsDlgPlugin class.
The KIconDialog class shows a list of icons installed on the system (as
accessible via KIconLoader) and allows the user to select one.
KOpenWithDlg implements a dialog to choose an application from, that is
to be run, e.g. to let the user choose an application to open a file/url
with.
@see KFileDialog:
The class providing the file selector dialog. It combines a KDirOperator,
KUrlBar and several other widgets.
@see KDirOperator:
The class encapsulating different KFileViews, offering file browsing and
file selection. Asynchronous, network transparent reading of directories
is performed via the @ref KIO library.
@see KUrlRequester:
A widget to be used for asking for a filename/path/URL. It consists of a
KLineEdit (or KComboBox) and a button. Activating the button
will open a KFileDialog. Typing in the lineedit is aided with
filename completion.
@see KUrlRequesterDlg:
A dialog to ask for a filename/path/URL, using KUrlRequester.
@see KFileView:
The base class for all views to be used with KDirOperator.
@see KFileIconView:
The KFileView based on K3IconView.
@see KFileDetailView:
The KFileView based on K3ListView.
@see KFilePreview:
The KFileView, combining a widget showing preview for a selected file
and another KFileView for browsing.
@see KUrlBar:
A widget offering a number of clickable entries which represent a URL,
aligned horizontally or vertically. The entries are customizable by the
user both on a per application basis or for all applications (URLs, their
icon and the description can be added, removed or edited by the user).
This is the widget used as "sidebar" in the KFileDialog.
@see KFileMetaInfoWidget:
A widget that allows viewing and editing of meta data of a file, utilizing
KFileMetaInfo.
*/
// DOXYGEN_REFERENCES = kdecore kjs kdeui
// DOXYGEN_EXCLUDE = kssl/kssl
// DOXYGEN_PROJECTNAME = KIO
// vim:ts=4:sw=4:expandtab:filetype=doxygen

36
kioslave/Mainpage.dox
View file

@ -1,36 +0,0 @@
/** @mainpage KIO Slaves
KIO Slaves are out-of-process worker applications that
perform protocol-specific communications.
See the <a href="../../kio/html/index.html">KIO</a>
documentation for more information.
The following KIO slaves are provided by kdelibs:
- Local file system (%file:/)
- HTTP (%http:/)
- FTP (%ftp:/)
- File metadata (%metainfo:/)
@authors
Rolf Magnus \<ramagnus@kde.org\><br>
Stephan Kulow \<coolo@kde.org\><br>
David Faure \<faure@kde.org\><br>
Waldo Bastian \<bastian@kde.org\><br>
Allan Sandfeld Jensen \<sandfeld@kde.org\><br>
George Staikos \<staikos@kde.org\><br>
Dawit Alemayehu \<adawit@kde.org\><br>
Hamish Rodda \<rodda@kde.org\>
@maintainers
[Unknown/None]
@licenses
@lgpl
*/
// DOXYGEN_REFERENCES = kdecore kio kdeui
// DOXYGEN_SET_RECURSIVE = YES
// DOXYGEN_SET_PROJECT_NAME = KIOSlave
// vim:ts=4:sw=4:expandtab:filetype=doxygen

29
knewstuff/Mainpage.dox
View file

@ -1,29 +0,0 @@
/** \mainpage Collaborative Data Sharing in KDE Applications
The \b KNewStuff3 library adds data sharing capabilities to %KDE
applications.
It uses libattica to access Open Collaboration Services providers.
In addition the static xml from <a href="http://ghns.freedesktop.org/">GHNS</a> is supported.
Application authors should use KNS3::DownloadDialog for downloading with get hot new stuff.
For the upload KNS3::UploadDialog is used.
Related information such as creation of <b>*.knsrc</b> files can be found
on techbase: <a href="http://techbase.kde.org/Development/Tutorials#Get_Hot_New_Stuff">Get Hot New Stuff tutorials</a>.
@authors
Josef Spillner \<spillner@kde.org\>
Jeremy Whiting \<jpwhiting@kde.org\>
Frederik Gladhorn \<gladhorn@kde.org\>
@maintainers
Jeremy Whiting \<jpwhiting@kde.org\>
@licenses
@lgpl
*/
// DOXYGEN_REFERENCES = kdecore kdeui kio
// DOXYGEN_SET_PROJECT_NAME = KNewStuff
// vim:ts=4:sw=4:expandtab:filetype=doxygen

42
kparts/Mainpage.dox
View file

@ -1,42 +0,0 @@
/** @mainpage Framework for KDE Graphical Components
This library implements the framework for KDE parts, which are
elaborate widgets with a user-interface defined in terms of actions
(menu items, toolbar icons). See KParts::Part.
The library also provides a framework for applications that want to
use parts. Such applications need to inherit their main window
from KParts::MainWindow and provide a so-called shell GUI,
which provides a basic skeleton GUI with part-independent functionality/actions.
Some KParts applications won't be specific to a given part, but expect
to be able to embed, for instance, all types of viewers out there. For this
the basic functionality of any viewer has been implemented in
KParts::ReadOnlyPart, which viewer-like parts should inherit from.
The same applies to KParts::ReadWritePart, which is for editor-like parts.
You can add actions to an existing KParts app from "outside", defining
the code for those actions in a shared library. This mechanism is
obviously called plugins, and implemented by KParts::Plugin.
For a complete, and very simple, example of how to use KParts to display
any kind of file (i.e. making a generic viewer), see the documentation for
KParts::ComponentFactory::createPartInstanceFromQuery.
@authors
Simon Hausmann \<hausmann@kde.org\><br>
David Faure \<faure@kde.org\><br>
Kurt Granroth \<granroth@kde.org\><br>
Michael Koch \<koch@kde.org\>
@maintainers
[Unknown/None]
@licenses
@lgpl
*/
// DOXYGEN_REFERENCES = kdecore kdeui kio
// DOXYGEN_SET_PROJECT_NAME = KParts
// vim:ts=4:sw=4:expandtab:filetype=doxygen

26
kpty/Mainpage.dox
View file

@ -1,26 +0,0 @@
/** @mainpage The KDE Pseudo Terminal Library
This library provides primitives to interface with pseudo terminal devices
as well as a KProcess derived class for running child processes and
communicating with them using a pty.
@see KPty, KPtyProcess
@authors
Zack Weinberg \<zack@rabi.phys.columbia.edu\><br>
Lars Doelle \<lars.doelle@on-line.de\><br>
Waldo Bastian \<bastian@kde.org\><br>
Oswald Buddenhagen \<ossi@kde.org\><br>
@maintainers
Oswald Buddenhagen \<ossi@kde.org\><br>
@licenses
@lgpl
*/
// DOXYGEN_REFERENCES = kdecore
// DOXYGEN_SET_INTERNAL_DOCS = YES
// DOXYGEN_SET_PROJECT_NAME = KPty
// vim:ts=4:sw=4:expandtab:filetype=doxygen

131
kross/Mainpage.dox
View file

@ -1,131 +0,0 @@
/** @mainpage Kross - a Scripting Framework for Applications
%Kross is a scripting bridge to embed scripting functionality
into an application. %Kross provides an abstract API to provide
scripting functionality in a interpreter-independent
way. The application that uses %Kross should not need to know
anything about the scripting language being used.
The main parts of %Kross:
- @ref core "The core of Kross"
- @ref modules "The optional Kross modules"
- @ref console "The Kross console application"
- @ref test "The unit and regression tests"
The interpreter backends supported by %Kross:
- @ref kjs "The KDE JavaScript interpreter backend"
- @ref qts "The QtScript interpreter backend"
Links:
- <a href="http://kross.dipe.org">Kross website</a>
- <a href="http://techbase.kde.org/Development/Tutorials/Kross-Tutorial">Kross tutorial on TechBase</a>
- <a href="http://www.kexi-project.org/wiki/wikiview/index.php?Scripting">Scripting in Kexi</a>
- <a href="http://www.koffice.org">KOffice website</a>
@authors
Sebastian Sauer \<mail AT dipe DOT %org\><br>
Cyrille Berger \<cberger AT cberger DOT net\>
@maintainers
[Unknown/None]
@licenses
@lgpl
*/
/** @page components Components
These are the core components of %Kross
@section core The core of Kross
The core of %Kross provides the framework to deal transparently
with interpreter-backends and offers abstract functionality
to deal with scripts.
The Kross::Manager class is a singleton that provides the
main entry point to deal with the %Kross Scripting Framework.
The Kross::Interpreter class is the base for interpreter
implementations. Each scripting backend needs to inheritate
its own interpreter and implement it.
The Kross::InterpreterInfo class provides abstract information
about a Interpreter before the interpreter-backend itself is
loaded.
The Kross::Action class is an abstract container to deal with
scripts like a single standalone scriptfile. Each action holds
a reference to by the matching Kross::Interpreter created
Kross::Script instance.
The Kross::ActionCollectionProxyModel class implements a
QSortFilterProxyModel for a Kross::ActionCollectionModel instance
which implements QAbstractItemModel to provide a model for views
on a Kross::ActionCollection instance.
The Kross::ActionCollection class manages collections of
Kross::Action instances.
@section modules The optional Kross modules
%Kross is able to optional dynamic load modules which provide then
additional functionality for scripts.
@subsection forms The Forms module
Kross::FormModule provides access to UI functionality like dialogs
or widgets.
@subsection kdetranslation The KDE Translation module
Kross::TranslationModule provides access to the
KDE internationalization and translation facilities.
@section console The Kross console application
The %Kross console application provides an executable application
to run by %Kross supported scripts from within the commandline:
@code
kross myscript.js
@endcode
@section test The unit and regression tests
Some internal testcases used to prevent regressions. To build
and run them compile with;
@code
cmake -DKDE4_BUILD_TESTS=1 ...
@endcode
*/
/** @page backends Backends
These are the interpreter backends provided by %Kross.
@section kjs The KDE JavaScript interpreter backend
The KDE JavaScript interpreter backend uses the kjs and kjsembed libraries
(part of kdelibs) to provide a JavaScript backend.
@section qts The QtScript interpreter backend
The QtScript interpreter backend uses the QtScript library
(part of Qt) to provide a JavaScript backend.
*/
// DOXYGEN_REFERENCES = kdecore kdeui
// DOXYGEN_SET_PROJECT_NAME = Kross
// vim:ts=4:sw=4:expandtab:filetype=doxygen

24
kunitconversion/Mainpage.dox
View file

@ -1,24 +0,0 @@
/** @mainpage
@section purpose Purpose
Convert units.
@section desc Description
todo
@authors
Petri Damstén \<damu@iki.fi\>
@maintainers
Petri Damstén \<damu@iki.fi\>
@licenses
@lgpl
*/
// DOXYGEN_SET_PROJECT_NAME = KUnitConversion
// vim:ts=4:sw=4:expandtab:filetype=doxygen

27
kutils/Mainpage.dox
View file

@ -1,27 +0,0 @@
/** @mainpage Some random bits and pieces
Some utility classes for KSettings, KCModule and KPlugin.
Use ${KDE4_KUTILS_LIBS} in the target_link_libraries of your CMakeLists.txt
to link to kutils.
@authors
Matthias Kretz \<kretz@kde.org\><br>
Rafael Fernández López \<ereslibre@kde.org\><br>
Matthias Elter \<elter@kde.org\><br>
Daniel Molkentin \<molkentin@kde.org\><br>
Frans Englich \<frans.englich@telia.com\><br>
Tobias Koenig \<tokoe@kde.org\><br>
Matthias Hoelzer-Kluepfel \<hoelzer@kde.org\>
@maintainers
[Unknown/None]
@licenses
@lgpl
*/
// DOXYGEN_REFERENCES = kdecore kdeui kio
// DOXYGEN_SET_PROJECT_NAME = KUtils
// vim:ts=4:sw=4:expandtab:filetype=doxygen

100
plasma/Mainpage.dox
View file

@ -1,100 +0,0 @@
/** @mainpage Plasma libraries
libplasma is the core of the Plasma desktop. It provides a framework of graphical
widgets (Plasma::Applet) that can be organised into managed groupings
(Plasma::Containment), such as a desktop or panel. It also provides a data
abstraction layer (Plasma::DataEngine) and a corresponding service interaction
layer (Plasma::Service) to make implementing widgets easier and a
system of callouts (Plasma::AbstractRunner) that provide responses to queries,
from running an application to performing a quick calculation.
The <a href="http://doc.trolltech.com/latest/graphicsview.html">Qt Graphics View
framework</a> and the <a href="http://api.kde.org/4.x-api/kdelibs-apidocs/">KDE
libraries</a> provide the underpinning for libplasma. As a result, it should
work anywhere that Qt and KDE do.
Although libplasma is developed for the use of the Plasma desktop shell in
KDE 4, it is general enough to be useful in other applications.
<a href="http://amarok.kde.org">Amarok</a> is using it for its context
view, allowing for pluggable widgets to display and interact with the music
collection, such as "current track" and "tag cloud" widgets.
libplasma itself only provides a framework, and the widgets, containments,
data engines and runners are all implemented as plugins. However, the framework
is designed to make implementing these plugins as easy as possible, including
providing scripting support.
Other important classes are:
- Plasma::Corona: the canvas that containments are placed on
- Plasma::View: a QWidget for displaying a containment
- Plasma::Theme: provides theming support
- Plasma::Animator: provides animations for things like elements appearing
and disappearing
- Plasma::Delegate: provides an item delegate for Qt's
<a href="http://doc.trolltech.com/latest/model-view-programming.html">Model /
View framework</a> for menu items.
- Plasma::ToolTipManager: allows widgets have (themed) tooltips displayed when the
mouse is hovered over them
- Plasma::Dialog: displays a themed application dialog
- Plasma::Extender: provides detachable sections to Plasma::Applet
- Plasma::GLApplet: provides an OpenGL-rendered Plasma::Applet
- Plasma::PackageStructure: provides descriptions of packages containing plugins
for libplasma
- Plasma::PopupApplet: provides a simple way of implementing a Plasma::Applet
consisting of an icon that shows a popup when clicked
- Plasma::Svg and Plasma::FrameSvg: provides themable, cached SVGs
- Plasma::Wallpaper: provides pluggable backgrounds for containments
- Plasma::AppletScript, Plasma::DataEngineScript, Plasma::RunnerScript and
Plasma::ScriptEngine: provide scripting interfaces for plugins
- Various themed QGraphicsWidgets for use in creating a Plasma::Applet
The
<a href="http://techbase.kde.org/Development/Tutorials/Plasma">Plasma tutorials</a>
on TechBase provide a good introduction to writing plugins, such as widgets and
data engines, for libplasma-based applications.
@authors
Aaron Seigo \<aseigo@kde.org\><br>
Alessandro Diaferia \<alediaferia@gmail.com\><br>
Alex Merry \<kde@randomguy3.me.uk\><br>
Alexander Wiedenbruch \<wirr01@gmail.com\><br>
Alexis Ménard \<darktears31@gmail.com\><br>
André Duffeck \<andre@duffeck.de\><br>
Andrew Lake \<jamboarder@yahoo.com\><br>
Artur de Souza \<asouza@kde.org\><br>
Bertjan Broeksema \<b.broeksema@kdemail.net\><br>
Chani Armitage \<chanika@gmail.com\><br>
Davide Bettio \<davide.bettio@kdemail.net\><br>
Dan Meltzer \<hydrogen@notyetimplemented.com\><br>
Fredrik Höglund \<fredrik@kde.org\><br>
Ivan Cukic \<ivan.cukic+kde@gmail.com\><br>
John Tapsell \<tapsell@kde.org\><br>
Jordi Polo \<mumismo@gmail.com\><br>
Kevin Ottens \<ervin@kde.org\><br>
Montel Laurent \<montel@kde.org\><br>
Marco Martin \<notmart@gmail.com\><br>
Matt Broadstone \<mbroadst@gmail.com\><br>
Petri Damsten \<damu@iki.fi\><br>
Rafael Fernández López \<ereslibre@kde.org\><br>
Riccardo Iaconelli \<riccardo@kde.org\><br>
Richard J. Moore \<rich@kde.org\><br>
Rob Scheepmaker \<r.scheepmaker@student.utwente.nl\><br>
Robert Knight \<robertknight@gmail.com\><br>
Sebastian Kuegler \<sebas@kde.org\><br>
Siraj Razick \<siraj@kde.net\><br>
Zack Rusin \<zack@kde.org\>
@maintainers
Aaron Seigo \<aseigo@kde.org\>
@licenses
@lgpl
*/
// DOXYGEN_SET_PROJECT_NAME = Plasma
// DOXYGEN_SET_RECURSIVE = YES
// DOXYGEN_EXCLUDE_PATTERNS = *_p.h */private/* */tests/*
// vim:ts=4:sw=4:expandtab:filetype=doxygen

152
solid/Mainpage.dox
View file

@ -1,152 +0,0 @@
/** \mainpage Solid
%Solid is a device integration framework. It provides a way of querying and
interacting with hardware independently of the underlying operating system.
Currently the following backends are implemented on Linux:
<ul>
<li><a href="http://www.freedesktop.org/wiki/Software/hal">HAL</a></li>
<li><a href="http://www.freedesktop.org/wiki/Software/udisks">udisks</a></li>
<li><a href="http://upower.freedesktop.org/">upower</a></li>
<li><a href="http://www.kernel.org/pub/linux/utils/kernel/hotplug/udev.html">udev</a></li>
</ul>
See the documentation for the Solid namespace, and the
<a href="http://techbase.kde.org/Development/Tutorials/Solid_Tutorials">tutorial
on TechBase</a>.
Examples:
- \ref tutorial1
- \ref tutorial2
- \ref tutorial3
- \ref tutorial4
- \ref tutorial5
Just for fun: \ref song
\authors
Kevin Ottens \<ervin@kde.org\><br>
Lukas Tinkl \<ltinkl@redhat.com\><br>
Pino Toscano \<pino@kde.org\><br>
Alex Fiestas \<alex@eyeos.org\><br>
Rafael Fernández López \<ereslibre@kde.org\><br>
Alex Merry \<alex.merry@kdemail.net\><br>
Mario Bensi \<mbensi@ipsquad.net\><br>
Harald Fernengel \<harry@kdevelop.org\>
<b>Maintainers</b>:<br>
Kevin Ottens \<ervin@kde.org\>
\licenses
\lgpl
*/
/** \page tutorial1 Tutorial 1
<p><b>
\ref index "Back to Overview" |
Tutorial 1 |
\ref tutorial2 |
\ref tutorial3 |
\ref tutorial4 |
\ref tutorial5
</b></p>
\includelineno tutorial1/tutorial1.cpp
*/
/** \page tutorial2 Tutorial 2
<p><b>
\ref index "Back to Overview" |
\ref tutorial1 |
Tutorial 2 |
\ref tutorial3 |
\ref tutorial4 |
\ref tutorial5
</b></p>
\includelineno tutorial2/tutorial2.cpp
*/
/** \page tutorial3 Tutorial 3
<p><b>
\ref index "Back to Overview" |
\ref tutorial1 |
\ref tutorial2 |
Tutorial 3 |
\ref tutorial4 |
\ref tutorial5
</b></p>
\includelineno tutorial3/tutorial3.cpp
*/
/** \page tutorial4 Tutorial 4
<p><b>
\ref index "Back to Overview" |
\ref tutorial1 |
\ref tutorial2 |
\ref tutorial3 |
Tutorial 4 |
\ref tutorial5
</b></p>
\includelineno tutorial4/tutorial4.cpp
*/
/** \page tutorial5 Tutorial 5
<p><b>
\ref index "Back to Overview" |
\ref tutorial1 |
\ref tutorial2 |
\ref tutorial3 |
\ref tutorial4 |
Tutorial 5
</b></p>
\includelineno tutorial5/tutorial5.cpp
*/
/** \page song A Solid Song
<p><b>\ref index "Back to Overview"</b></p>
And for HAL's sake, each mistake, ah, you forgave<br>
And soon both of us learned to trust<br>
Not run away, it was no time to play;<br>
We built it up and built it up and committed it.
<p>
And now it's solid,<br>
%Solid as a rock;<br>
That's what this code is,<br>
That's what we've got, oh, mmm?
%Solid (Oh),<br>
%Solid as a rock;<br>
And nothing's changed it (Ooh),<br>
The code is still hot, hot, hot, hot, hot, hot, hot, hot
*/
// DOXYGEN_SET_EXAMPLE_PATH += @topdir@/solid/examples
// DOXYGEN_EXCLUDE = solid/backends solid/ifaces tests
// DOXYGEN_SET_PROJECT_NAME = Solid
// vim:ts=4:sw=4:expandtab:filetype=doxygen

30
sonnet/Mainpage.dox
View file

@ -1,30 +0,0 @@
/** @mainpage Sonnet
%Sonnet is the %KDE language processing architecture.
<p>
This directory only contains plugins. The core functionality of
%Sonnet is contained in kdecore, and the user-interface
components in kdeui.
See the Sonnet namespace in kdecore, and Sonnet::ConfigDialog,
Sonnet::Dialog and Sonnet::Highlighter in kdeui.
TechBase has a
<a href="http://techbase.kde.org/Development/Tutorials/Sonnet/SonnetTutorial">tutorial
on Sonnet</a>.
@authors
Zack Rusin \<zack@kde.org\><br>
Jacob R Rideout \<kde@jacobrideout.net\>
@maintainers
Zack Rusin \<zack@kde.org\>
@licenses
@lgpl
*/
// DOXYGEN_REFERENCES = kdecore kdeui
// DOXYGEN_SET_PROJECT_NAME = Sonnet
// vim:ts=4:sw=4:expandtab:filetype=doxygen

269
threadweaver/Mainpage.dox
View file

@ -1,269 +0,0 @@
/** \mainpage ThreadWeaver
<p><b>
Overview |
\ref UseCases |
\ref Why |
\ref MainComponents "Main Components"
</b></p>
ThreadWeaver is a helper for multithreaded programming. It uses a job-based
interface to queue tasks and execute them in an efficient way.
You simply divide the workload into jobs, state the dependencies between the jobs
and ThreadWeaver will work out the most efficient way of dividing the work between
threads within a set of resource limits.
For more information, see \ref UseCases, \ref Why and \ref MainComponents.
\section Tests Example Code
<p>Example code is available in the
<a href="http://lxr.kde.org/source/kde/kdelibs/threadweaver/Examples/">Examples</a>
directory. The Construction
program shows how to use ThreadWeaver in imperative (not event oriented)
programs. The Jobs program provides a GUI example and displays the
interaction with the weaver state and it's signals. The Simple
Multithreaded Image Viewer (SMIV) example shows the use of job
dependencies.</p>
\authors
Mirko Boehm
\maintainers
Mirko Boehm
\licenses
\lgpl
*/
/** \page UseCases Use Cases
<p><b>
\ref index "Overview" |
Use Cases |
\ref Why |
\ref MainComponents "Main Components"
</b></p>
<p>ThreadWeaver provides a solution to a number (but not all)
multithreading problems. Let's have a look:</p>
<ul> <li>How do you implement a single operation that takes a lot of CPU
power, but is hard to handle in chunks (Example: scale an image) when
you want your GUI to remain responsive? Encapsulate the operation in a
class object derived from Job instead of a method and put it in the
static instance (Weaver::instance). Connect to the Job's done() signal
to receive a notification when it is completed.</li>
<li>How do you implement a CPU intensive operation while time-critical
operations are executed (load and decode an MP3 while another one is fed
to the audio device): Implement both the file loading operation and the
play operation in a job and queue both at the same time. There is also a
synchronous sleep method in the Job class if a job needs to be delayed
for a number of milliseconds after it is taken over by a thread.</li>
<li>How do you implement many small operations where the cost of each
individual one is hard to estimate (loading two hundred icons from an
NFS drive): Create a common or a number of specialized job
classes. Queue all of them. Either connect to the individual done signal
to process every item when it has been finished or connect to
Weaver::jobsDone() to receive a notification when all of the jobs are
done.</li>
<li>How do you implement an operation with complex control flow and
dependencies in the execution order (load, parse and display an HTML
document with embedded media): Create jobs for the individual steps you
need to perform. Try to split the whole operation in as many
independent, parallelizable parts as possible. Now declare the execution
dependencies. A job will only be executed when all jobs it depends on
are finished. This way every individual operation will be executed as
soon as it becomes possible. Connect to the final jobs done() signal to
be notified when all parts of the whole operations have been
executed. If necessary (if there is more than one final object), create a
dummy job object that depends on all of them to have one central end
point of execution.</li> </ul>
<p>As you can see, ThreadWeaver can provide solutions for simple, but
also for complex cases. For an example on how job dependencies can be
modeled and used to create elegant, streamlined solutions for control
flow modeling, see the Simple Multithreaded Image Viewer (SMIV) example
in the Tests directory.</p>
<p>ThreadWeaver focuses on operations that can be implemented in
Jobs. To create solutions where a thread is supposed to constantly run
to perform an ongoing operation that, for example, spans the whole
application live, it has to be verified that it is the right
approach. It is possible to add very long or neverending operations to
the queue, but it will constantly bind a thread to that operation. It
might still make sense to use ThreadWeaver, as the creation, handling
and destruction of the threads is already taken care of, but the minimum
inventory size (thread count) should be increased accordingly to provide
for enough threads to process the other jobs.</p>
*/
/** \page Why Why Multithreading?
<p><b>
\ref index "Overview" |
\ref UseCases |
Why Multithreading? |
\ref MainComponents "Main Components"
</b></p>
<p>In the past, multithreading has been considered a powerful tool that
is hard to handle (some call it the work of the devil). While there may
be some truth to this, newer tools have made the job of the software
developer much easier when creating parallel implementations of
algorithms. At the same time, the necessity to use multiple threads to
create performant applications has become more and more
clear. Technologies like Hyperthreading and multiple core processors can
only be used if processors have to schedule processing power to
multiple, concurrently running processes or threads.</p>
<p>Event driven programs especially bear the issue of latency, which is
more important for the user's impression of application performance than
other factors. But the responsiveness of the user interface relies
mainly on the ability of the application to process events, an ability
that is much limited in case the application is executing processing
power expensive, lengthy operations. This leads, for example, to delayed
or sluggish processing of necessary paint events. Even if this does not
at all influence the total time necessary to perform the operation the
user requested, is is annoying and not state of the art. </p>
<p>There are different approaches to solve this issue. The crudest one
may be to process single or multiple events while performing a lengthy
operation, which may or may not work sufficiently, but is at least sure
to ruin all efforts of Separation of Concerns. Concerns can simply not
be separated if the developer has to intermingle instructions with event
handling where he does not even know about the kind of events that are
processed. </p>
<p>Another approach is to use event-controlled asynchronous
operations. This is sufficient in most cases, but still causes a number
of issues. Any operation that carries the possibility of taking a long
time or blocking may still stop event processing for a while. Such risks
are hard to assess, and especially hard to test in laboratory
environments where networks are fast and reliable and the system I/O
load is generally low. Network operations may fail. Hard disks may be
suspended. The I/O subsystem may be so busy that transfering 2 kByte may
take a couple of seconds. </p>
<p>Processing events in objects that are executed in other threads is
another approach. It has it's own issues that come with parallel
programming, but it makes sure the main event loop returns as soon as
possible. Usually this approach is combined with a state pattern to
synchronize the GUI with the threaded event processing. </p>
<p>Which one of these approaches is suitable for a specific case has to
be assessed by the application developers. There is no silver
bullet. All have specific strengths, weaknesses and issues. The
ThreadWeaver library provides the means to implement multithreaded job
oriented solutions. </p>
<p>To create performant applications, the application designers have to
leverage the functionality provided by the hardware platform as good as
possible. While code optimizations only lead to so much improvement,
application performance is usually determined by network and I/O
throughput. The CPU time needed is usually negligible. At the same time,
the different hardware subsystems usually are independent in modern
architectures. Network, I/O and memory interfaces can transfer data all
at the same time, and the CPU is able to process instructions while all
these subsystems are busy. The modern computer is not a traditional
uniprocessor (think of GPUs, too). This makes it necessary to use all
these parallel subsystems at the same time as much as possible to
actually use the possibilities modern hardware provides, which is very
hard to achieve in a single thread.</p>
<p>Another very important issue is application processing
flow. Especially GUI applications to not follow the traditional
imperative programming pattern. Execution flow is more network-like,
with chunks of code that depend on others to finish processing before
they can touch their data. Tools to represent those
networks to set up your applications order of execution are rare, and
usually leave it to the developers to code the execution order of the
instructions. This solutions are usually not flexible and do not adapt
to the actual usage of the CPU nodes and computer
subsystems. ThreadWeaver provides means to represent code execution
dependencies and relies on the operating systems scheduler to actually
distribute the work load. The result is an implementation that is very
close to the original application semantics, and usually improved
performance and scalability in different real-life scenarios. </p>
<p>The more tasks are handled in parallel, the more memory is
necessary. There is a permanent CPU - memory tradeoff which limits the
number of parallel operations to the extend where memory that needs to
be swapped in and out slows down the operations. Therefore memory usage
needs to be equalized to allow the processors to operate without being
slowed down. This means parallel operations need to be scheduled to a
limit to balance CPU and memory usage. ThreadWeaver provides the means
for that. </p>
<p>In general, ThreadWeaver tries to make to task of creating
multithreaded, performant applications as simple as
possible. Programmers should be relieved of synchronization, execution
dependendancy and load balancing issues as much as possible. The API
tends to be clean, extensible and easy to understand. </p>
*/
/** \page MainComponents Main Components of ThreadWeaver
<p><b>
\ref index "Overview" |
\ref UseCases |
\ref Why |
Main Components
</b></p>
<p>ThreadWeaver is a Job queue. It executes jobs in threads it
internally manages. The minimum and maximum number of threads provided
by a Weaver is set by the user. Jobs are regular QObjects, which allows
users to connect to the done() signal to be notified when the Job has
been executed. The Weaver class provides objects that handle a number of
threads called the inventory. Users usually acquire a reference to a
WeaverInterface object. </p>
<p>Jobs may depend on other jobs. A job will only execute if all jobs it
depends on are already finished. In this, dependencies reorder job
execution. If no dependencies are declared, jobs are executed in
queueing order. Multiple dependencies are possible, which allows the
creation of complex flow graphs that are automatically executed by the
Weaver. It is important, though, to avoid circular dependencies. Two
jobs that depend on each other in both directions will simply never be
executed, since the dependencies will never resolve.</p>
<p>Threads are created on demand and do not exit until the containing
weaver is deleted. Threads have an eager policy in trying to execute
jobs out of the queue. The managing Weaver blocks them if no jobs are
availabe.</p>
<p>WeaverObservers are used to receive more informative events about the
thread states and job execution. They can be used to provide progress or
debugging information or to implement GUIs to show the thread
activity. Observers can be attached to Weavers and will disconnect
automatically when they are deleted.</p>
\section Job Execution
<p>In general, jobs are executed in the order they are queued, if they
have no unresolved dependencies. This behaviour can be used to balance
I/O, network and CPU load. The SMIV example shows how this can be done.
</p>
\section Emitting Signals from Jobs
<p>To notify the application's GUI of progress or other events, it may
be desirable to emit signals from the Job objects that can be connected
to the main thread. Since the job will be executed in another thread,
such signals are delivered asynchronously.</p>
<p>The Job class in the ThreadWeaver library itself contains such a
helper class that can be used as a reference for this approach.</p>
*/
// DOXYGEN_SET_PROJECT_NAME = ThreadWeaver
// DOXYGEN_EXCLUDE = Examples Experimental Tests Docs Scripts WeaverGui
// vim:ts=4:sw=4:expandtab:filetype=doxygen