From 722ce1efbac31c61b1d4b13f7e075c9f311e3e73 Mon Sep 17 00:00:00 2001 From: Darrell Anderson Date: Sun, 2 Mar 2014 20:05:33 +0100 Subject: Finish renaming tdevelop components --- doc/Makefile.am | 2 +- doc/api/Architecture.dox | 16 +- doc/api/FutureTasks.dox | 2 +- doc/api/HighPriTasks.dox | 2 +- doc/api/HowToAddApplicationTemplates.dox | 12 +- doc/api/HowToAddGenericBuildTools.dox | 2 +- doc/api/HowToAddPlugins.dox | 10 +- doc/api/HowToAddProgrammingLanguages.dox | 10 +- doc/api/HowToDocument.dox | 4 +- doc/extras/CMakeLists.txt | 2 +- doc/extras/Makefile.am | 2 +- doc/extras/w3c/CMakeLists.txt | 2 +- doc/extras/w3c/Makefile.am | 2 +- doc/kde_app_devel/CMakeLists.txt | 12 - doc/kde_app_devel/Makefile.am | 3 - doc/kde_app_devel/appwizard.png | Bin 46091 -> 0 bytes doc/kde_app_devel/index.docbook | 1549 -------------- doc/kde_app_devel/kscribblefiles.png | Bin 16708 -> 0 bytes doc/kdearch/Makefile.am | 2 - doc/kdearch/affine-general.png | Bin 3182 -> 0 bytes doc/kdearch/affine-rotate.png | Bin 1941 -> 0 bytes doc/kdearch/affine-scale.png | Bin 1419 -> 0 bytes doc/kdearch/affine-shear.png | Bin 1422 -> 0 bytes doc/kdearch/affine-translate.png | Bin 1444 -> 0 bytes doc/kdearch/brushstyles.png | Bin 9874 -> 0 bytes doc/kdearch/canvas.png | Bin 24979 -> 0 bytes doc/kdearch/capflat.png | Bin 267 -> 0 bytes doc/kdearch/capround.png | Bin 441 -> 0 bytes doc/kdearch/capsquare.png | Bin 185 -> 0 bytes doc/kdearch/index.docbook | 3337 ------------------------------ doc/kdearch/joinbevel.png | Bin 529 -> 0 bytes doc/kdearch/joinmiter.png | Bin 569 -> 0 bytes doc/kdearch/joinround.png | Bin 597 -> 0 bytes doc/kdearch/konqi-mirrored.png | Bin 27633 -> 0 bytes doc/kdearch/konqi-normal.png | Bin 27757 -> 0 bytes doc/kdearch/konqi-rotated.png | Bin 28953 -> 0 bytes doc/kdearch/konqi-sheared.png | Bin 25644 -> 0 bytes doc/kdearch/kview-menu.png | Bin 4204 -> 0 bytes doc/kdearch/opengl.png | Bin 4818 -> 0 bytes doc/kdearch/penstyles.png | Bin 2854 -> 0 bytes doc/kdearch/whatsthis.png | Bin 3509 -> 0 bytes doc/kdevdesigner/CMakeLists.txt | 9 - doc/kdevdesigner/Makefile.am | 3 - doc/kdevdesigner/index.docbook | 65 - doc/platform/Mainpage.dox | 12 +- doc/std/CMakeLists.txt | 4 +- doc/std/Makefile.am | 4 +- doc/std/kdev3api.toc | 45 - doc/std/tdev3api.toc | 45 + doc/tde_app_devel/CMakeLists.txt | 12 + doc/tde_app_devel/Makefile.am | 2 + doc/tde_app_devel/appwizard.png | Bin 0 -> 46091 bytes doc/tde_app_devel/index.docbook | 1549 ++++++++++++++ doc/tde_app_devel/kscribblefiles.png | Bin 0 -> 16708 bytes doc/tdearch/Makefile.am | 2 + doc/tdearch/affine-general.png | Bin 0 -> 3182 bytes doc/tdearch/affine-rotate.png | Bin 0 -> 1941 bytes doc/tdearch/affine-scale.png | Bin 0 -> 1419 bytes doc/tdearch/affine-shear.png | Bin 0 -> 1422 bytes doc/tdearch/affine-translate.png | Bin 0 -> 1444 bytes doc/tdearch/brushstyles.png | Bin 0 -> 9874 bytes doc/tdearch/canvas.png | Bin 0 -> 24979 bytes doc/tdearch/capflat.png | Bin 0 -> 267 bytes doc/tdearch/capround.png | Bin 0 -> 441 bytes doc/tdearch/capsquare.png | Bin 0 -> 185 bytes doc/tdearch/index.docbook | 3337 ++++++++++++++++++++++++++++++ doc/tdearch/joinbevel.png | Bin 0 -> 529 bytes doc/tdearch/joinmiter.png | Bin 0 -> 569 bytes doc/tdearch/joinround.png | Bin 0 -> 597 bytes doc/tdearch/konqi-mirrored.png | Bin 0 -> 27633 bytes doc/tdearch/konqi-normal.png | Bin 0 -> 27757 bytes doc/tdearch/konqi-rotated.png | Bin 0 -> 28953 bytes doc/tdearch/konqi-sheared.png | Bin 0 -> 25644 bytes doc/tdearch/kview-menu.png | Bin 0 -> 4204 bytes doc/tdearch/opengl.png | Bin 0 -> 4818 bytes doc/tdearch/penstyles.png | Bin 0 -> 2854 bytes doc/tdearch/whatsthis.png | Bin 0 -> 3509 bytes doc/tdevassistant/CMakeLists.txt | 9 + doc/tdevassistant/Makefile.am | 3 + doc/tdevassistant/index.docbook | 65 + doc/tdevdesigner/CMakeLists.txt | 9 + doc/tdevdesigner/Makefile.am | 3 + doc/tdevdesigner/index.docbook | 65 + doc/tdevelop/app-files.docbook | 202 +- doc/tdevelop/commands.docbook | 16 +- doc/tdevelop/getting-started.docbook | 22 +- doc/tdevelop/index.docbook | 2 +- doc/tdevelop/kdevdesigner.png | Bin 69839 -> 0 bytes doc/tdevelop/nutshell.docbook | 2 +- doc/tdevelop/plugin-tools.docbook | 36 +- doc/tdevelop/project-advanced.docbook | 4 +- doc/tdevelop/setup.docbook | 34 +- doc/tdevelop/survey-manual.docbook | 2 +- doc/tdevelop/tdevdesigner.png | Bin 0 -> 69839 bytes doc/tdevelop/tdevelop-install.docbook | 2 +- doc/tdevelop/tdevelop-scripting.docbook | 4 +- doc/tdevelop/tdevelop-survey.docbook | 2 +- 97 files changed, 5309 insertions(+), 5233 deletions(-) delete mode 100644 doc/kde_app_devel/CMakeLists.txt delete mode 100644 doc/kde_app_devel/Makefile.am delete mode 100644 doc/kde_app_devel/appwizard.png delete mode 100644 doc/kde_app_devel/index.docbook delete mode 100644 doc/kde_app_devel/kscribblefiles.png delete mode 100644 doc/kdearch/Makefile.am delete mode 100644 doc/kdearch/affine-general.png delete mode 100644 doc/kdearch/affine-rotate.png delete mode 100644 doc/kdearch/affine-scale.png delete mode 100644 doc/kdearch/affine-shear.png delete mode 100644 doc/kdearch/affine-translate.png delete mode 100644 doc/kdearch/brushstyles.png delete mode 100644 doc/kdearch/canvas.png delete mode 100644 doc/kdearch/capflat.png delete mode 100644 doc/kdearch/capround.png delete mode 100644 doc/kdearch/capsquare.png delete mode 100644 doc/kdearch/index.docbook delete mode 100644 doc/kdearch/joinbevel.png delete mode 100644 doc/kdearch/joinmiter.png delete mode 100644 doc/kdearch/joinround.png delete mode 100644 doc/kdearch/konqi-mirrored.png delete mode 100644 doc/kdearch/konqi-normal.png delete mode 100644 doc/kdearch/konqi-rotated.png delete mode 100644 doc/kdearch/konqi-sheared.png delete mode 100644 doc/kdearch/kview-menu.png delete mode 100644 doc/kdearch/opengl.png delete mode 100644 doc/kdearch/penstyles.png delete mode 100644 doc/kdearch/whatsthis.png delete mode 100644 doc/kdevdesigner/CMakeLists.txt delete mode 100644 doc/kdevdesigner/Makefile.am delete mode 100644 doc/kdevdesigner/index.docbook delete mode 100644 doc/std/kdev3api.toc create mode 100644 doc/std/tdev3api.toc create mode 100644 doc/tde_app_devel/CMakeLists.txt create mode 100644 doc/tde_app_devel/Makefile.am create mode 100644 doc/tde_app_devel/appwizard.png create mode 100644 doc/tde_app_devel/index.docbook create mode 100644 doc/tde_app_devel/kscribblefiles.png create mode 100644 doc/tdearch/Makefile.am create mode 100644 doc/tdearch/affine-general.png create mode 100644 doc/tdearch/affine-rotate.png create mode 100644 doc/tdearch/affine-scale.png create mode 100644 doc/tdearch/affine-shear.png create mode 100644 doc/tdearch/affine-translate.png create mode 100644 doc/tdearch/brushstyles.png create mode 100644 doc/tdearch/canvas.png create mode 100644 doc/tdearch/capflat.png create mode 100644 doc/tdearch/capround.png create mode 100644 doc/tdearch/capsquare.png create mode 100644 doc/tdearch/index.docbook create mode 100644 doc/tdearch/joinbevel.png create mode 100644 doc/tdearch/joinmiter.png create mode 100644 doc/tdearch/joinround.png create mode 100644 doc/tdearch/konqi-mirrored.png create mode 100644 doc/tdearch/konqi-normal.png create mode 100644 doc/tdearch/konqi-rotated.png create mode 100644 doc/tdearch/konqi-sheared.png create mode 100644 doc/tdearch/kview-menu.png create mode 100644 doc/tdearch/opengl.png create mode 100644 doc/tdearch/penstyles.png create mode 100644 doc/tdearch/whatsthis.png create mode 100644 doc/tdevassistant/CMakeLists.txt create mode 100644 doc/tdevassistant/Makefile.am create mode 100644 doc/tdevassistant/index.docbook create mode 100644 doc/tdevdesigner/CMakeLists.txt create mode 100644 doc/tdevdesigner/Makefile.am create mode 100644 doc/tdevdesigner/index.docbook delete mode 100644 doc/tdevelop/kdevdesigner.png create mode 100644 doc/tdevelop/tdevdesigner.png (limited to 'doc') diff --git a/doc/Makefile.am b/doc/Makefile.am index 8275eb30..440f3684 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,2 +1,2 @@ -SUBDIRS = tdevelop std extras kde_app_devel kdevdesigner +SUBDIRS = tdevelop std extras tde_app_devel tdevdesigner diff --git a/doc/api/Architecture.dox b/doc/api/Architecture.dox index ae4ef73d..52c1447a 100644 --- a/doc/api/Architecture.dox +++ b/doc/api/Architecture.dox @@ -40,7 +40,7 @@ parts to distinguish, mainly: - src = The core part of KDevelop - lib/interfaces = Plugin handler interface classes - - parts = The various parts using the KParts framework ( KDevPlugin children ) + - parts = The various parts using the KParts framework ( TDevPlugin children ) - languages = \ref language-parts - buildtools = \ref buildtool-parts - vcs = \ref vcs-parts @@ -67,12 +67,12 @@ There are two types of possible main window objects: pre-arranged access tabs around user areas. . -Both main window classes inherit from the KDevMainWindow class which provides +Both main window classes inherit from the TDevMainWindow class which provides access to common window features. \subsubsection toplevel The TopLevel Object -There is only one toplevel object of class KDevMainWindow in KDevelop. It can +There is only one toplevel object of class TDevMainWindow in KDevelop. It can be accessed through the static function TopLevel::getInstance() (see the TopLevel class). @@ -83,7 +83,7 @@ be viewed according to their functionalities as follows. \subsubsection language-parts Programming Language Support Parts -These parts implement a KDevLanguageSupport Class interface. +These parts implement a TDevLanguageSupport Class interface. To add support for a new programming language check the \ref howToAddProgrammingLanguages page (doc/api/HowToAddProgrammingLanguages.dox file). Take a look at \ref LangSupportStatus (doc/api/LangSupportStatus.dox file) to see the current status/features of the programming languages currently supported by KDevelop. @@ -135,7 +135,7 @@ Take a look at \ref LangSupportStatus (doc/api/LangSupportStatus.dox file) to se \subsubsection buildtool-parts Build tools Parts -These parts implement a KDevProject Class interface. +These parts implement a TDevProject Class interface. - buildtools/ada = Ada build tool - (see AdaProjectPart) @@ -166,7 +166,7 @@ These parts implement a KDevProject Class interface. \subsubsection vcs-parts VCS (Version Control System) Parts -These parts implement a KDevVersionControl Class interface. +These parts implement a TDevVersionControl Class interface. - vcs/cervisia = Cervisia Support - (see CervisiaPlugin) @@ -211,7 +211,7 @@ Take a look at \ref EditorsSupportStatus (doc/api/EditorsSupportStatus.dox file) Some of the parts are considered global - that is, they effect the entire operation of KDevelop. -These parts implement a KDevPlugin Class interface. +These parts implement a TDevPlugin Class interface. - parts/appwizard = New Project Wizard - see AppWizardPart @@ -264,7 +264,7 @@ These parts implement a KDevPlugin Class interface. \subsubsection project-specific-parts Project Specific Parts -These parts implement a KDevPlugin Class interface. +These parts implement a TDevPlugin Class interface. - parts/astyle = Source code formatter - (see AStylePart) diff --git a/doc/api/FutureTasks.dox b/doc/api/FutureTasks.dox index 1d7f7f26..763537f3 100644 --- a/doc/api/FutureTasks.dox +++ b/doc/api/FutureTasks.dox @@ -129,7 +129,7 @@ the same border as other items (impossible) - Browser tool bar should truncate long menu entries so it doesn't take so much space (already implemented?) - - Extend KDevPlugin-API in order to have a preferred border for at + - Extend TDevPlugin-API in order to have a preferred border for at least the selection parts (Automake Manager, Class Browser, File Groups, etc...) diff --git a/doc/api/HighPriTasks.dox b/doc/api/HighPriTasks.dox index 062b3b06..7bcbaf1f 100644 --- a/doc/api/HighPriTasks.dox +++ b/doc/api/HighPriTasks.dox @@ -12,7 +12,7 @@ This way the .tdevelop file can be shared in teams of developers. -\section KDevelop2compat KDevelop 2 compatibility +\section TDevelop2compat KDevelop 2 compatibility (These are things that must be accomplished before we can say that KDevelop 3 >= tdevelop 2.x UI-wise and functionality-wise!) diff --git a/doc/api/HowToAddApplicationTemplates.dox b/doc/api/HowToAddApplicationTemplates.dox index f53ce4f8..1da5a3e5 100644 --- a/doc/api/HowToAddApplicationTemplates.dox +++ b/doc/api/HowToAddApplicationTemplates.dox @@ -27,7 +27,7 @@ applications like kedit as well as plugins for example for tdevelop or noatun.\n \section templates_1 I. Example: How To Create a Simple KDE Application Template "KHello" -You can find this template in $TDEDIR/share/apps/kdevappwizard/template-khello. +You can find this template in $TDEDIR/share/apps/tdevappwizard/template-khello. \subsection templates_1_1 I.1. Step 1: Basic Skeleton @@ -64,7 +64,7 @@ wizard will replace: - \%{YEAR} ........ by the year . -All this can be found in $TDEDIR/share/apps/kdevappwizard/template-common/tdevelop.pm. +All this can be found in $TDEDIR/share/apps/tdevappwizard/template-common/tdevelop.pm. \subsubsection templates_1_2a I.2.1. The Source Files The files template-khello/app.cpp, template-khello/app.h and @@ -135,22 +135,22 @@ if [ `id -u` = 0 ]; then # we are root so install the template into the global kde directory kde_dir=`tde-config --prefix` else - # we are a user so install it into $HOME/.trinity/share/apps/kdevappwizard directory + # we are a user so install it into $HOME/.trinity/share/apps/tdevappwizard directory kde_dir=`tde-config --localprefix` echo "Note: It would be better to install as root. Press CTRL+C to abort" fi # use usual path or another one? -echo "Install dir [${kde_dir}/share/apps/kdevappwizard]:" +echo "Install dir [${kde_dir}/share/apps/tdevappwizard]:" read newdir -if [ "$newdir"a = a ]; then newdir="${kde_dir}/share/apps/kdevappwizard/"; fi +if [ "$newdir"a = a ]; then newdir="${kde_dir}/share/apps/tdevappwizard/"; fi # make sure the directories exist if [ ! -e "${newdir}/template-khello" ]; then mkdir -p "${newdir}/template-khello" ; fi; if [ ! -e "${newdir}/templates" ]; then mkdir -p "${newdir}/templates" ; fi; if [ ! -e "${newdir}" ]; then mkdir -p "$newdir" ; fi; -if [ ! -e "${newdir}/template-common" ]; then ln -s "${kde_prefix}/share/apps/kdevappwizard/template-common" "${newdir}/template-common" ; fi; +if [ ! -e "${newdir}/template-common" ]; then ln -s "${kde_prefix}/share/apps/tdevappwizard/template-common" "${newdir}/template-common" ; fi; # install now cp -R --target-directory "$newdir" template-khello diff --git a/doc/api/HowToAddGenericBuildTools.dox b/doc/api/HowToAddGenericBuildTools.dox index b073cf0f..d713082a 100644 --- a/doc/api/HowToAddGenericBuildTools.dox +++ b/doc/api/HowToAddGenericBuildTools.dox @@ -6,7 +6,7 @@ This part offers build tool facilities using project files in xml format (dtd is located in buildtools/generic/kdevxmlproject.dtd). Those xml files can be converted into makefiles, ant xml files or simply shell scripts using build system plugins. -Build system plugin is an object that implements KDevBuildSystem interface. +Build system plugin is an object that implements TDevBuildSystem interface. Build system plugins are located in buildtools/generic/buildsystem. \section sectionStep1 Step 1: Make your plugin loadable diff --git a/doc/api/HowToAddPlugins.dox b/doc/api/HowToAddPlugins.dox index fa7f74e2..b0b282db 100644 --- a/doc/api/HowToAddPlugins.dox +++ b/doc/api/HowToAddPlugins.dox @@ -8,7 +8,7 @@ For a plugin foo, create a file foo.desktop which contains KDevelop/Part in its list of ServiceTypes. - - See parts/doctreeview/kdevdoctreeview.desktop for an example. + - See parts/doctreeview/tdevdoctreeview.desktop for an example. . If you install this file into \$(kde_servicesdir), your plugin will automatically be loaded. @@ -80,9 +80,9 @@ See parts/doctreeview/doctreeviewfactory.cpp for an example. \section implementPart Step 3: Implement your part. -Your part must be derived from KDevPlugin. +Your part must be derived from TDevPlugin. - - KDevPlugin takes two arguments: + - TDevPlugin takes two arguments: - 1) A parent argument. This also comes from createPartObject(). - 2) A name, which in turn is given to the QObject @@ -93,7 +93,7 @@ Your part must be derived from KDevPlugin. \subsection accessIDE How to access other IDE components A part can access other components of the IDE via some accessors -of KDevPlugin: +of TDevPlugin: - The application core via core(), - the build tools via project(), @@ -155,7 +155,7 @@ to write it back. \subsection sessionAccess Project session file (*.kdevses) -The base class of all TDevelop plugins is KDevPlugin. It provides two virtual methods +The base class of all TDevelop plugins is TDevPlugin. It provides two virtual methods restorePartialProjectSession(..) and savePartialProjectSession(..) that you should reimplement in your special plugin to attach to session loading and saving. diff --git a/doc/api/HowToAddProgrammingLanguages.dox b/doc/api/HowToAddProgrammingLanguages.dox index a5840885..5dd44fda 100644 --- a/doc/api/HowToAddProgrammingLanguages.dox +++ b/doc/api/HowToAddProgrammingLanguages.dox @@ -6,7 +6,7 @@ \section LSupport List of things to have "complete" support of a given language in KDevelop - - Implement interface KDevLanguageSupport + - Implement interface TDevLanguageSupport - \ref sectionClassWizard - \ref sectionAttributeMethodWizard - \ref sectionQtUiSubclassing - (if the language has Qt bindings) @@ -43,7 +43,7 @@ Take a look at \ref LangSupportStatus (doc/api/LangSupportStatus.dox file) to se \section sectionLanguageSupport Language Support Any language support should be written as a tdevelop part and implement -KDevLanguageSupport interface (lib/interfaces/kdevlanguagesupport.h). +TDevLanguageSupport interface (lib/interfaces/tdevlanguagesupport.h). Implementing methods: - virtual Features features(); @@ -54,7 +54,7 @@ Should be enough for a language support to start working. KDevelop ships with KDevLang project template. It is a simple language support prototype that can be used when developing language support plugins with KDevelop. To use it, start a New Project and select: C++->KDevelop->KDevelop Language Support Plugin in the application wizard. -The template is located in languages/cpp/app_templates/kdevlang, you can change it there if you need. +The template is located in languages/cpp/app_templates/tdevlang, you can change it there if you need. You should look at languages/ruby for a simple language support @@ -177,7 +177,7 @@ write a Debugger . KDevelop already provides GDB support \subsection sectionCompilerPlugins Compiler plugins There is an ability to create compiler plugin for KDevelop. Compiler plugin provides the compiler configuration dialog which implements command line compiler options. -Compiler plugins must implement KDevCompilerOptions interface. +Compiler plugins must implement TDevCompilerOptions interface. \section MiscInf Other Info @@ -226,7 +226,7 @@ currently provides several build tools. They are: - see GenericProjectPart at buildtools/generic - Offers build tool facilities using project files in xml format (dtd is located in buildtools/generic/kdevxmlproject.dtd). Those xml files can be converted into makefiles, ant xml files or simply shell scripts using build system plugins. - Build system plugin is an object that implements KDevBuildSystem interface. Build system plugins are located in buildtools/generic/buildsystem. + Build system plugin is an object that implements TDevBuildSystem interface. Build system plugins are located in buildtools/generic/buildsystem. . - QMake build tool - see TrollProjectPart at buildtools/qmake diff --git a/doc/api/HowToDocument.dox b/doc/api/HowToDocument.dox index d606a8bf..65cd7c31 100644 --- a/doc/api/HowToDocument.dox +++ b/doc/api/HowToDocument.dox @@ -3,7 +3,7 @@ */ /** \page howToDocument How to document KDevelop parts -You should add a README and a README.dox file to your part (KDevPlugin). +You should add a README and a README.dox file to your part (TDevPlugin). On the README file put this text: \verbatim @@ -31,7 +31,7 @@ implements your part. On the area marked with ... you can add optional informations. Here is an example of that: -\verbinclude languages/cpp/app_templates/kdevpart/README.dox +\verbinclude languages/cpp/app_templates/tdevpart/README.dox All these infos are optional and you should only add the link to the bugzilla database if YOUR_COMPONENT_NAME has been defined in that database. diff --git a/doc/extras/CMakeLists.txt b/doc/extras/CMakeLists.txt index dd7c977f..a358cf07 100644 --- a/doc/extras/CMakeLists.txt +++ b/doc/extras/CMakeLists.txt @@ -14,5 +14,5 @@ add_subdirectory( w3c ) install( FILES sdl.toc opengl.toc - DESTINATION ${DATA_INSTALL_DIR}/kdevdocumentation/tocs + DESTINATION ${DATA_INSTALL_DIR}/tdevdocumentation/tocs ) diff --git a/doc/extras/Makefile.am b/doc/extras/Makefile.am index 0e7893c4..deb28a1a 100644 --- a/doc/extras/Makefile.am +++ b/doc/extras/Makefile.am @@ -1,6 +1,6 @@ SUBDIRS=w3c -tocdir = ${kde_datadir}/kdevdocumentation/tocs +tocdir = ${kde_datadir}/tdevdocumentation/tocs toc_DATA = sdl.toc opengl.toc #indexdir = ${kde_datadir}/devdoctreeview/indices diff --git a/doc/extras/w3c/CMakeLists.txt b/doc/extras/w3c/CMakeLists.txt index 7424e5fd..9681021f 100644 --- a/doc/extras/w3c/CMakeLists.txt +++ b/doc/extras/w3c/CMakeLists.txt @@ -12,5 +12,5 @@ install( FILES w3c-dom-level2-html.toc w3c-svg.toc w3c-uaag10.toc - DESTINATION ${DATA_INSTALL_DIR}/kdevdocumentation/tocs + DESTINATION ${DATA_INSTALL_DIR}/tdevdocumentation/tocs ) diff --git a/doc/extras/w3c/Makefile.am b/doc/extras/w3c/Makefile.am index 19518e8d..68a489f8 100644 --- a/doc/extras/w3c/Makefile.am +++ b/doc/extras/w3c/Makefile.am @@ -1,3 +1,3 @@ -tocdir = ${kde_datadir}/kdevdocumentation/tocs +tocdir = ${kde_datadir}/tdevdocumentation/tocs toc_DATA = w3c-dom-level2-html.toc w3c-svg.toc w3c-uaag10.toc diff --git a/doc/kde_app_devel/CMakeLists.txt b/doc/kde_app_devel/CMakeLists.txt deleted file mode 100644 index 243887d5..00000000 --- a/doc/kde_app_devel/CMakeLists.txt +++ /dev/null @@ -1,12 +0,0 @@ -################################################# -# -# (C) 2010-2011 Serghei Amelian -# serghei (DOT) amelian (AT) gmail.com -# -# Improvements and feedback are welcome -# -# This file is released under GPL >= 2 -# -################################################# - -tde_create_handbook( DESTINATION kde_app_devel ) diff --git a/doc/kde_app_devel/Makefile.am b/doc/kde_app_devel/Makefile.am deleted file mode 100644 index 41691557..00000000 --- a/doc/kde_app_devel/Makefile.am +++ /dev/null @@ -1,3 +0,0 @@ -KDE_LANG = en -KDE_DOCS = AUTO - diff --git a/doc/kde_app_devel/appwizard.png b/doc/kde_app_devel/appwizard.png deleted file mode 100644 index adbadb35..00000000 Binary files a/doc/kde_app_devel/appwizard.png and /dev/null differ diff --git a/doc/kde_app_devel/index.docbook b/doc/kde_app_devel/index.docbook deleted file mode 100644 index 2d913c0b..00000000 --- a/doc/kde_app_devel/index.docbook +++ /dev/null @@ -1,1549 +0,0 @@ - -KDevelop"> - - - -]> - - - - -The &tdevelop; Programming Handbook - -2002-12-05 -2.0 - - - -Ralf -Nolden -
Ralf.Nolden@post.rwth-aachen.de
 - - -Caleb -Tennis -
caleb@aei-tech.com
 - - - - -1999 -Ralf Nolden - - -2002 -Caleb Tennis - - - - -&FDLNotice; - - -The User Guide to C++ Application Design for the Trinity Desktop Environment (TDE) with -the &tdevelop; IDE - - - -KDE -KDevelop -IDE -development -programming - - - - - -Introduction - -As Unix Systems are becoming more and more popular to even beginners working with computer machines -due to its advantages in regards of stability and functionality, most are somehow disappointed, because -those applications don't have a consistent look and each one behaves different from another. With KDE, -developers have an almost perfect way to create first-class applications for Unix desktop systems to get -a wider user community by the mere quality their applications have to offer. Therefore, KDE becomes more -and more popular as a base for programming design, and developers want to take advantage of the -possibilities that the system has to offer. - - - -What you should know already - -For making the best use of this programming handbook, we assume that you already know about the -C++ programming language; if not, you should make yourself familiar with that first. Information about -C++ is available through various sources either in printed form at your local bookstore or by tutorials -found on the Internet. Knowledge about the design of Graphical User Interfaces is not required, as this -handbook tries to cover the application design for KDE programs, which also includes an introduction into -the Qt toolkit as well as the KDE libraries and the design of User Interfaces. Also, you should have made -yourself comfortable with &tdevelop; by reading The User Manual to &tdevelop;, which contains a descriptive -review of the functionality provided by the IDE. - - - - -About this Handbook - -This handbook has been written to give developers an introduction into KDE application development by -using the KDevelop Integrated Development Environment. - - -The following chapters therefore give an introduction on how to create projects, explains the sourcecode -already generated and shows how to extend the given sources on various topics such as toolbars, menu bars -and view areas. - - -Then the dialogeditor is discussed in detail, explaining how widgets are created and covers widget -properties settings in detail for all provided widgets. - - -Finally, you will learn about several topics that will complete your knowledge in regards of project design -and helps you work out additional issues besides coding such as adding API documentation and extending -online-manuals. - - -In the next chapter - -We'll take a look at the Qt and KDE libraries, showing basic concepts and why things are the way they are. -Also, we will discuss how to create the tutorial applications provided with the Qt toolkit by using -tdevelop;, so beginners can already see first results with a few steps, and thereby will learn how to make -use of some of &tdevelop;'s best features. - - - - -In the following chapters - -You will learn how to: - -create an application with the KAppWizard -What the project skeleton already provides -What the code already create means -How to create your own views -How to extend your application's functionality by dialog, menu bars, and toolbars -How to make your application user friendly by providing help functions -How to write online documentation - - - - - - - -Additional Information - -Additional information about Qt/KDE programming is available by various sources: - -Programming with Qt by Matthias Kalle Dalheimer -The User Manual to KDevelop, provided with the TDevelop IDE -The Online Reference to the Qt library -The KDE Developer web site - - - -Additionally, you should look for help by subscribing to the various mailing lists, whose addresses -are available on the mentioned web sites, and on the Usenet newsgroups dedicated to users of KDE and -Unix Systems as well as about the C and C++ programming language. - - -For obtaining help about the TDevelop IDE, you should send requests to our mailinglist at -kdevelop@kdevelop.org. Mind that the KDevelop team is dedicated to provide the means to enable you to -program applications and therefore is not intended as a technical support team in cases where the -applications you're developing don't work due to implementation errors or misconfigurations of your -operating system. By this, we ask all users to take advantage of the mailinglist in any case you're running -into problems with the use of the IDE itself, as well as for bug reports and suggestions for improving the -functionality of the development environment. - - - - - - -The KDE and Qt Libraries - -The Norwegian company TrollTech (http://www.trolltech.com) -provides a so-called GUI toolkit, named Qt. GUI means "Graphical User Interface", and therefore, Qt-based -applications represent themselves with buttons, windows etc, allowing user input by visualizing the functions -an application provides. Such a toolkit is needed for developing graphical applications that run on the X-Window -interface on Unix Systems, because X does not contain a pre-defined user interface itself. Although other -toolkits are also available to create User Interfaces, Qt offers some technical advantages that make -application design very easy. Additionally, the Qt toolkit is also available for Microsoft Windows systems, -which allows developers to provide their applications for both platforms. - - -The KDE Team (http://www.kde.org) joined together with the goal -to make using Unix Systems more friendly, and decided to use the Qt toolkit for the development of a window -manager on X-Windows, plus a variety of tools included with the KDE packages. The K Desktop Environment -therefore contains the window manager kwm, the file manager kfm and the launch panel kpanel as the main -components plus a variety of first-class utilities and applications. After KDE was out, a lot of developers -turned their eyes towards the new environment and what it has to offer them. The KDE libraries are providing -essential methods and classes that make all applications designed with them look similar and consistent, -so the user has the great advantage that he only has to get accustomed with an application's specific -usage, not with handling dialogs or buttons. Also, KDE programs integrate themselves into the desktop and -are able to interact with the file manager via drag'n drop, offer session management and many more, if all -features offered by the KDE libraries are used. Both, the Qt toolkit and the KDE libraries, are implemented -in the C++ programming language; therefore applications that make use of these libraries are also mostly -written in C++. In the following chapter, we'll make a short trip through the libraries to see what already -is provided and how Qt and TDE applications are created in general. - - -Both, the Qt toolkit and the KDE libraries, are implemented in the C++ programming language; -therefore applications that make use of these libraries are also mostly written in C++. In the following -chapter, we'll make a short trip through the libraries to see what already is provided and how Qt and KDE -applications are created in general. - - - -The Qt GUI Toolkit - -As said, the Qt library is a toolkit that offers graphical elements that are used for creating GUI -applications and are needed for X-Window programming. Additionally, the toolkit offers: - -A complete set of classes and methods ready to use even for non-graphical programming issues -A good solution towards user interaction by virtual methods and the signal/slot mechanism -A set of predefined GUI-elements, called "widgets", that can be used easily for creating the visible elements -Additional completely pre-defined dialogs that are often used in applications such as progress and file dialogs - - - -Therefore knowing the Qt classes is very essential, even if you only want to program KDE-applications. -To have an impression on the basic concept how GUI-applications are constructed and compiled, we'll first -have a look at a sample Qt-only program; then we'll extend it to a KDE program. - - - -The first Qt Application - -As usual, programs in C++ have to contain a main() function, which is the starting point for application -execution. As we want them to be graphically visible in windows and offering user interaction, -we first have to know, how they can show themselves to the user. For an example, we'll have a look -at the first tutorial included with the Qt Online Reference Documentation and explain the basic execution -steps; also why and how the application window appears: - -#include <qapplication.h> -#include <qpushbutton.h> - -int main( int argc, char **argv ) -{ -QApplication a( argc, argv ); - -QPushButton hello( "Hello world!", 0 ); -hello.resize( 100, 30 ); - -a.setMainWidget( &hello ); -hello.show(); -return a.exec(); -} - - - -This application merely paints a window containing a button with "Hello world" as its text. As for -all Qt-based applications, you first have to create an instance of the class QApplication, represented by -variable a. - - -Next, the program creates an instance of the class QPushButton called hello, this will be the button. -The constructor of hello gets a string as a parameter, which is the contents of the widget visible as -the buttons text. - - -Then the resize() method is called on the hello button. This changes the default size a widget -(which is in this case the QPushButton) has when created to the length of 100 pixels and the height of -30 pixels. Finally, the setMainWidget() method is called for a and the show() method for hello. The -QApplication is finally executed by a.exec(), enters the main event loop and waits until it has to return -an integer value to the overlaying Operating System signaling that the application is exited. - - - - -The Reference Documentation for Qt - -Now, let's have a quick look at the reference documentation of the Qt library. To do this, start -&tdevelop; and select "Qt" from the tree in the Documentation tab. The documentation browser opens -and shows you the start page of the Qt reference. This will be your first place to get information -about Qt, it's classes and the available functions they provide. Also, the above program is the first -that is included in the tutorials section. To get to the classes we want to have a look at, -QApplication and QPushButton, select "Alphabetical Class List" -and search for the according names. Follow either of them to have a look at the class documentation. - - -Alternatively, you can use the online documentation from Trolltech's Qt Documentation - - -For QApplication, you will see the constructor and all other methods that this -class provides. If you follow a link, you will get more information about the usage and meaning of the -methods, which is very useful when you sometimes can't detect the correct use or want to have an example. -This also counts for the KDE library documentation, which uses a similar documentation type; therefore -this is almost all you have to know about using the class-references with the documentation browser. - - -Interpretation of the Sample - -Starting with QApplication, you will find all the methods used in our first example: - -the constructor QApplication() -the setMainWidget() method -the exec() method - - - -The interpretation why we use these methods is very simple: - -Create an instance of the class QApplication with the constructor, -so we can make use of the GUI elements provided by Qt -Create a widget which will be the contents of our program window -Set the widget as the main widget for a -Execute the a instance of QApplication - - - -The second object of our program is the pushbutton, an instance of the class QPushButton. -From the two constructors given to create an instance, we used the second: this accepts a text, -which is the label contents of the button; here, it is the string "Hello world!". Then we called the -resize() method to change the size of the button according to it's contents - -the button has to be larger to make the string completely visible. - - -But what about the show() method? Now, you see that like most other widgets, -QPushButton is based on a single inheritance, the documentation says, Inherits -QButton. Follow the link to the QButton class. -This shows you a lot of other widgets that are inherited by QPushButton, -which we'll use later to explain the signal/slot mechanism. Anyway, the show() -method is not listed, therefore, it must be a method that is provided by inheritance as well. The class -that QButton inherits is QWidget. Just follow the link -again, and you will see a whole bunch of methods that the QWidget class provides; including -the show() method. Now we understand what was done in the sample with the button: - -Create an instance of QPushButton, use the second constructor to set the button text -Resize the widget to its contents -Set the widget as the main widget of the QApplication instance a -Tell the widget to display itself on the screen by calling show(), an inherited method from QWidget - - - -After calling the exec() method, the application is visible to the user, -showing a window with the button showing "Hello world!". Note: GUI programs behave somewhat differently -than procedural applications. The main thing here is that the application enters a so-called -"main event loop". This means that the program has to wait for user actions and then react to it, also -that for a Qt application, the program has to be in the main event loop to start the event handling. -The next section tells you in short what this means to the programmer and what Qt offers to process -user events. - - -For already advanced users: The button has no parent declared in the constructor, therefore it -is a top-level widget alone and runs in a local event loop which doesn't need to wait for the main -event loop. See the QWidget class documentation and The KDE Library Reference Guide - - - - - - -User Interaction - -After reading the last sections, you should already know: - -What the Qt-library provides in terms of GUI applications -How a program using Qt is created and -Where and how to find information about classes that you want to use with the documentation browser - - - -Now we'll turn to give the application "life" by processing user events. Generally, the user has two ways -to interact with a program: the mouse and the keyboard. For both ways, a graphical user interface has to -provide methods that detect actions and methods that do something as a reaction to these actions. - - -The Window system therefore sends all interaction events to the according application. The -QApplication then sends them to the active window as a QEvent -and the widgets themselves have to decide what to do with them. A widget receives the event and processes -QWidget::event(QEvent*), which then decides which event has been executed -and how to react; event() is therefore the main event handler. Then, -the event() method passes the event to so-called event filters -that determine what happened and what to do with the event. If no filter signs responsible for the -event, the specialized event handlers are called. Thereby we can decide between: - - -Keyboard events -- TAB and Shift-TAB keys: - -virtual void focusInEvent(QFocusEvent *) -virtual void focusOutEvent(QFocusEvent *) - - - - -All other keyboard input: - -virtual void keyPressEvent(QKeyEvent *) -virtual void keyReleaseEvent(QKeyEvent *) - - - - -Mouse movements: - -virtual void mouseMoveEvent(QMouseEvent *) -virtual void enterEvent(QEvent *) -virtual void leaveEvent(QEvent *) - - - - -Mouse button actions - -virtual void mousePressEvent(QMouseEvent *) -virtual void mouseReleaseEvent(QMouseEvent *) -virtual void mouseDoubleClickEvent(QMouseEvent *) - - - - -Window events containing the widget - -virtual void moveEvent(QMoveEvent *) -virtual void resizeEvent(QResizeEvent *) -virtual void closeEvent(QCloseEvent *) - - - - - - -Note that all event functions are virtual and protected; therefore you can re-implement the events -that you need in your own widgets and specify how your widget has to react. QWidget -also contains some other virtual methods that can be useful in your programs; anyway, it is sufficient -to know about QWidget very well. - - - -Object Interaction by Signals and Slots - -Now we're coming to the most obvious advantages of the Qt toolkit: the signal/slot mechanism. -This offers a very handy and useful solution to object interaction, which usually is solved by -callback functions for X-Window toolkits. As this communication requires a strict programming and -sometimes makes user interface creation very difficult (as referred by the Qt documentation and explained -in Programming with Qt by K.Dalheimer), Troll Tech invented a new system where objects can emit signals -that can be connected to methods declared as slots. For the C++ part of the programmer, he only has to know -some things about this mechanism: - - -the class declaration of a class using signals/slots has to contain the Q_OBJECT macro at the beginning -(without a semicolon); and have to be derved from the QObject class - - -a signal can be emitted by the keyword emit, e.g. emit signal(parameters); from within any member function -of a class that allows signals/slots - - - -all signals used by the classes that are not inherited have to be added to the class declaration by a -signals section - - -all methods that can be connected with a signal are declared in sections with the additional keyword slot, -e.g. public slots: within the class declaration - - -the meta-object compiler moc has to run over the header file to expand the macros and to produce the -implementation (which is not necessary to know). The output files of moc are compiled also by the C++ compiler. - - - - -Another way to use signals without deriving from QObject is to use the -QSignal class- see the reference documentation for more information and example -usage. In the following, we assume you're deriving from QObject. - - -This way, your class is able to send signals anywhere and to provide slots that signals can connect -to. By using the signals, you don't have to care about who's receiving it- you just have to emit the -signal and whatever slot you want to connect to it can react to the emission. Also the slots can be used -as normal methods during implementation. - - -Now, to connect a signal to a slot, you have to use the connect() methods that -are provided by QObject or, where available, special methods that objects provide -to set the connection for a certain signal. - - - -Sample Usage - -To explain the way how to set up object-interaction, we'll take our first example again and extend it by a -simple connection: - -#include <qapplication.h> -#include <qpushbutton.h> - -int main( int argc, char **argv ) -{ -QApplication a( argc, argv ); - -QPushButton hello( "Hello world!" , 0); -hello.resize( 100, 30 ); - -a.setMainWidget( &hello ); - -QObject::connect(&hello, SIGNAL( clicked() ), &a, SLOT( quit() )); - -hello.show(); -return a.exec(); -} - - - -You see, the only addition to give the button more interaction is to use a connect() - method: connect(&hello, SIGNAL( clicked() ), &a, SLOT( quit() )); -is all you have to add. What is the meaning now? The class declaration of QObject says about the -connect() method: - - -bool connect ( const QObject * sender, const char * signal, const QObject * receiver, const char * member ) - - -This means you have to specify a QObject instance pointer that is the sender -of the signal, meaning that it can emit this signal as first parameter; then you have to specify the signal -that you want to connect to. The last two parameters are the receiver object that provides a slot, followed -by the member function which actually is the slot that will be executed on signal emission. - - -By using signals and slots, your program's objects can interact with each other easily without explicitly -depending on the type of the receiver object. You will learn more about using this mechanism for productive -usage later in this handbook. More information about the Signals/Slot mechanism can also be found in -The KDE Library Reference Guide -and the Qt online reference. - - - - - - -What KDE provides - -The KDE 3.x libraries - -The main KDE libraries you'll be using for creating your own TDE applications are: - - -the tdecore library, containing all classes that are non-visible elements to provide application functionality - - -the tdeui library, containing user interface elements like menubars, toolbars, etc. - - -the tdefile library, containing the file selection dialogs - - - - -Additionally, for specific solutions KDE offers the following libraries: - - -the tdefx library, containing pixmaps, image effects the TDEStyle extension to QStyle - - -the tdehtml library, containing KDE's html component - - -the kjs library, containing KDE's Javascript support - - -the tdeio library, containing low level access to network files - - -the tdeparts library, containing support for re-usable embeddable extendable applications - - - - -Next we'll have a look at what is needed to turn out first Qt Application into a KDE one. - - - -Example KDE Application - -In the following, you will see that writing a KDE application is not much more difficult than a -Qt application. For the use of KDE's features, you just have to use some other classes, and you're almost -done. As an example, we'll discuss the changed version of the Qt example from above: - -#include <tdeapplication.h> -#include <qpushbutton.h> - -int main( int argc, char **argv ) -{ -TDEApplication a( argc, argv ); - -QPushButton hello( "Hello world!", 0 ); -hello.resize( 100, 30 ); - -a.setTopWidget( &hello ); - -QObject::connect(&hello, SIGNAL( clicked() ), &a, SLOT( quit() )); - -hello.show(); -return a.exec(); -} - - - -You see that first we have changed from QApplication to TDEApplication -. Further, we had to change the previously used setMainWidget() method -to setTopWidget, which TDEApplication uses to set the main -widget. That's it! Your first KDE application is ready - you only have to tell the compiler the KDE -include path and the linker to link in the tdecore library with -ltdecore. - - -As you now know what at least the main() function provides generally and how an -application gets visible and allows user and object interaction, we'll go on with the next chapter, -where our first application is made with &tdevelop;. There you can also test everything which was -mentioned before and see the effects. - - -What you should have looked into additionally until now is the reference documentation for Qt, -especially the QApplication, QWidget and QObject - class and the tdecore library documentation for the TDEApplication class. -The KDE Library Reference handbook -also covers a complete description about the invocation of the QApplication and -TDEApplication constructors including command-line argument processing. - - - - - - - -Creating New Applications - - -The Application Wizard - -&tdevelop;'s Application Wizard is intended to let you start working on new project with &tdevelop;. Therefore -all of your projects are first created by the wizard, and then you can start building them and extend what is -already provided by the source skeleton. You can choose from several project types according to your project goals: - - -KDE Application Framework: includes source code for a complete frame structre of a standard KDE application - - -QMake Project: Creates an application framework based around Trolltech's qmake configuration system - - -Simple hello world program: Creates a C++ terminal based program with no GUI support - - -A multitude of other program skeletons - - - - -In this chapter we'll see how the Application Wizard can be invoked and what has to be done to generate -a KDE application project. This will also be the initial step of our coverage, where we will create the -initial version of a sample project. For all other project types the steps are usualyl the same, but you -may not have as many options available. - - - - -Invoking the Application Wizard and Project Generation - -Starting the Application Wizard and the First Page - -To start with your KDE application, open &tdevelop;. From the Project menu, selection New Project. The -Application Wizard starts, and you'll see the selection tree on the first page containing available project -types that can be created. Choose the C++ subtree, then KDE, then Application Framework. - - -For our sample project, we are going to create the application KScribble. Enter this as the application -name, and change any other information at the bottom of this screen that may need it. Then, select Next. - - -Application Wizard - - - - -Version control information - -On this screen you have the ability to decide if your project will use a version control system like -CVS. For our sample project we will not use source control, so make sure the selection box reads None -and select Next. - - - -Header and Source Templates - -The next two pages show example headers that will go at the top of each of the header and source files that -you create using &tdevelop;. For now, just leave these as the default, and select Next, then Finish. If the -Finish button is not activated, you haven't set all of the options correct. Use the Back button to return -to earlier menus and correct any mistakes. - - - -Finishing Up - -Upon completion, the Application Wizard should close and the messages window should popup displaying -information about the tasks that &tdevelop; is currently doing. At the end of all of the tasks, you -should see **** Success *****. This means the application framework was successfully loaded. - - - - - -The First Build - -After our project is generated, we'll first make a trip through the source code to get a general understanding -of how the application framework looks. This won't only help us get started, but we'll know where to change -what in later steps. - - -This chapter makes the assumption that you understand the basic navigation of &tdevelop;. Consult the -KDevelop User Manual for information if you need it. - - -The Automake manager shows the project files as follows: - - -Files in our project - - - -Before diving into the sources, we'll let &tdevelop; build an run our new application. To do this, select -Build Project from the Build menu, or press F8. The output window opens and displays output messages during -the compilation phase. - -1 cd /home/caleb/kscribble && WANT_AUTOCONF_2_5=1 WANT_AUTOMAKE_1_6=1 gmake k -2 gmake all-recursive -3 gmake[1]: Entering directory `/home/caleb/kscribble' -4 Making all in doc -5 gmake[2]: Entering directory `/home/caleb/kscribble/doc' -6 Making all in . -7 gmake[3]: Entering directory `/home/caleb/kscribble/doc' -8 gmake[3]: Nothing to be done for `all-am'. -9 gmake[3]: Leaving directory `/home/caleb/kscribble/doc' -10 Making all in en -11 gmake[3]: Entering directory `/home/caleb/kscribble/doc/en' -12 /usr/local/trinity/bin/meinproc --check --cache index.cache.bz2 /home/caleb/kscribble/doc/en/index.docbook -13 gmake[3]: Leaving directory `/home/caleb/kscribble/doc/en' -14 gmake[2]: Leaving directory `/home/caleb/kscribble/doc' -15 Making all in po -16 gmake[2]: Entering directory `/home/caleb/kscribble/po' -17 gmake[2]: Nothing to be done for `all'. -18 gmake[2]: Leaving directory `/home/caleb/kscribble/po' -19 Making all in src -20 gmake[2]: Entering directory `/home/caleb/kscribble/src' -21 source='main.cpp' object='main.o' libtool=no \ -22 depfile='.deps/main.Po' tmpdepfile='.deps/main.TPo' \ -23 depmode=gcc3 /bin/sh /home/caleb/kscribble/admin/depcomp \ -24 g++ -DHAVE_CONFIG_H -I. -I/home/caleb/kscribble/src -I.. -I/usr/local/trinity/include - -I/usr/lib/qt/include -I/usr/X11R6/include -DQT_THREAD_SUPPORT -D_REENTRANT -Wnon-virtual-dtor - -Wno-long-long -Wundef -Wall -pedantic -W -Wpointer-arith -Wmissing-prototypes -Wwrite-strings - -ansi -D_XOPEN_SOURCE=500 -D_BSD_SOURCE -Wcast-align -Wconversion -O2 -fno-exceptions -fno-check-new - -c -o main.o `test -f 'main.cpp' || echo '/home/caleb/kscribble/src/'`main.cpp -25 /usr/lib/qt/bin/moc /home/caleb/kscribble/src/kscribble.h -o kscribble.moc -26 source='kscribble.cpp' object='kscribble.o' libtool=no \ -27 depfile='.deps/kscribble.Po' tmpdepfile='.deps/kscribble.TPo' \ -28 depmode=gcc3 /bin/sh /home/caleb/kscribble/admin/depcomp \ -29 g++ -DHAVE_CONFIG_H -I. -I/home/caleb/kscribble/src -I.. -I/usr/local/trinity/include - -I/usr/lib/qt/include -I/usr/X11R6/include -DQT_THREAD_SUPPORT -D_REENTRANT -Wnon-virtual-dtor - -Wno-long-long -Wundef -Wall -pedantic -W -Wpointer-arith -Wmissing-prototypes -Wwrite-strings - -ansi -D_XOPEN_SOURCE=500 -D_BSD_SOURCE -Wcast-align -Wconversion -O2 -fno-exceptions -fno-check-new - -c -o kscribble.o `test -f 'kscribble.cpp' || echo '/home/caleb/kscribble/src/'`kscribble.cpp -30 kscribble.cpp: In member function `void KScribble::setupActions()' -31 kscribble.cpp:107: warning: unused variable `TDEAction*custom' -32 /usr/lib/qt/bin/moc /home/caleb/kscribble/src/kscribbleview.h -o kscribbleview.moc -33 source='kscribbleview.cpp' object='kscribbleview.o' libtool=no \ -34 depfile='.deps/kscribbleview.Po' tmpdepfile='.deps/kscribbleview.TPo' \ -35 depmode=gcc3 /bin/sh /home/caleb/kscribble/admin/depcomp \ -36 g++ -DHAVE_CONFIG_H -I. -I/home/caleb/kscribble/src -I.. -I/usr/local/trinity/include - -I/usr/lib/qt/include -I/usr/X11R6/include -DQT_THREAD_SUPPORT -D_REENTRANT -Wnon-virtual-dtor - -Wno-long-long -Wundef -Wall -pedantic -W -Wpointer-arith -Wmissing-prototypes -Wwrite-strings -ansi - -D_XOPEN_SOURCE=500 -D_BSD_SOURCE -Wcast-align -Wconversion -O2 -fno-exceptions -fno-check-new -c - -o kscribbleview.o `test -f 'kscribbleview.cpp' || echo '/home/caleb/kscribble/src/'`kscribbleview.cpp -37 kscribbleview.cpp: In member function `void KScribbleView::print(QPainter*, -38 int, int)': -39 kscribbleview.cpp:79: warning: unused parameter `QPainter*p' -40 kscribbleview.cpp:79: warning: unused parameter `int height' -41 kscribbleview.cpp:79: warning: unused parameter `int width' -42 /usr/lib/qt/bin/moc /home/caleb/kscribble/src/pref.h -o pref.moc -43 source='pref.cpp' object='pref.o' libtool=no \ -44 depfile='.deps/pref.Po' tmpdepfile='.deps/pref.TPo' \ -45 depmode=gcc3 /bin/sh /home/caleb/kscribble/admin/depcomp \ -46 g++ -DHAVE_CONFIG_H -I. -I/home/caleb/kscribble/src -I.. -I/usr/local/trinity/include - -I/usr/lib/qt/include -I/usr/X11R6/include -DQT_THREAD_SUPPORT -D_REENTRANT -Wnon-virtual-dtor - -Wno-long-long -Wundef -Wall -pedantic -W -Wpointer-arith -Wmissing-prototypes -Wwrite-strings - -ansi -D_XOPEN_SOURCE=500 -D_BSD_SOURCE -Wcast-align -Wconversion -O2 -fno-exceptions -fno-check-new - -c -o pref.o `test -f 'pref.cpp' || echo '/home/caleb/kscribble/src/'`pref.cpp -47 /usr/local/trinity/bin/dcopidl /home/caleb/kscribble/src/kscribbleiface.h > kscribbleiface.kidl || - ( rm -f kscribbleiface.kidl ; /bin/false ) -48 /usr/local/trinity/bin/dcopidl2cpp --c++-suffix cpp --no-signals --no-stub kscribbleiface.kidl -49 source='kscribbleiface_skel.cpp' object='kscribbleiface_skel.o' libtool=no \ -50 depfile='.deps/kscribbleiface_skel.Po' tmpdepfile='.deps/kscribbleiface_skel.TPo' \ -51 depmode=gcc3 /bin/sh /home/caleb/kscribble/admin/depcomp \ -52 g++ -DHAVE_CONFIG_H -I. -I/home/caleb/kscribble/src -I.. -I/usr/local/trinity/include - -I/usr/lib/qt/include -I/usr/X11R6/include -DQT_THREAD_SUPPORT -D_REENTRANT -Wnon-virtual-dtor - -Wno-long-long -Wundef -Wall -pedantic -W -Wpointer-arith -Wmissing-prototypes -Wwrite-strings - -ansi -D_XOPEN_SOURCE=500 -D_BSD_SOURCE -Wcast-align -Wconversion -O2 -fno-exceptions -fno-check-new - -c -o kscribbleiface_skel.o `test -f 'kscribbleiface_skel.cpp' || - echo '/home/caleb/kscribble/src/'`kscribbleiface_skel.cpp -53 /bin/sh ../libtool --silent --mode=link --tag=CXX g++ -Wnon-virtual-dtor -Wno-long-long -Wundef -Wall - -pedantic -W -Wpointer-arith -Wmissing-prototypes -Wwrite-strings -ansi -D_XOPEN_SOURCE=500 - -D_BSD_SOURCE -Wcast-align -Wconversion -O2 -fno-exceptions -fno-check-new -o kscribble -R - /usr/local/trinity/lib -R /usr/lib/qt/lib -R /usr/X11R6/lib -L/usr/X11R6/lib -L/usr/lib/qt/lib - -L/usr/local/trinity/lib main.o kscribble.o kscribbleview.o pref.o kscribbleiface_skel.o -ltdeio -54 source='kscribble_client.cpp' object='kscribble_client.o' libtool=no \ -55 depfile='.deps/kscribble_client.Po' tmpdepfile='.deps/kscribble_client.TPo' \ -56 depmode=gcc3 /bin/sh /home/caleb/kscribble/admin/depcomp \ -57 g++ -DHAVE_CONFIG_H -I. -I/home/caleb/kscribble/src -I.. -I/usr/local/trinity/include - -I/usr/lib/qt/include -I/usr/X11R6/include -DQT_THREAD_SUPPORT -D_REENTRANT -Wnon-virtual-dtor - -Wno-long-long -Wundef -Wall -pedantic -W -Wpointer-arith -Wmissing-prototypes -Wwrite-strings - -ansi -D_XOPEN_SOURCE=500 -D_BSD_SOURCE -Wcast-align -Wconversion -O2 -fno-exceptions -fno-check-new - -c -o kscribble_client.o `test -f 'kscribble_client.cpp' || echo - '/home/caleb/kscribble/src/'`kscribble_client.cpp -58 /bin/sh ../libtool --silent --mode=link --tag=CXX g++ -Wnon-virtual-dtor -Wno-long-long -Wundef - -Wall -pedantic -W -Wpointer-arith -Wmissing-prototypes -Wwrite-strings -ansi -D_XOPEN_SOURCE=500 - -D_BSD_SOURCE -Wcast-align -Wconversion -O2 -fno-exceptions -fno-check-new -o kscribble_client -R - /usr/local/trinity/lib -R /usr/lib/qt/lib -R /usr/X11R6/lib -L/usr/X11R6/lib -L/usr/lib/qt/lib - -L/usr/local/trinity/lib kscribble_client.o -ltdecore -59 gmake[2]: Leaving directory `/home/caleb/kscribble/src' -60 gmake[2]: Entering directory `/home/caleb/kscribble' -61 gmake[2]: Nothing to be done for `all-am'. -62 gmake[2]: Leaving directory `/home/caleb/kscribble' -63 gmake[1]: Leaving directory `/home/caleb/kscribble' -64 *** Success *** - - - -As you can see, we've put line numbers in front of each line which won't appear on your output but it makes it -easier to describe what is happening during the build. First of all, gmake works recursively. This means -that it starts from the directory it is invoked and goes into the subdirectories first, one at a time, then -returns to the directory it was started, processes it, then finishes. - - -Our first line of interest is 24. Notice on this line that g++, which is our C++ compiler, gets called by make -to compile the first source code file in our project - in this case main.cpp. Many extra command line options -are also being used with the g++ compiler; some of which are defaults and some of which can be configured -via &tdevelop;. - - -Before the next file (kscribble.cpp, line 29) is compiled, the moc (meta object compiler) is first -invoked on kscribble.h (line 25). This is because KScribble classes use signals/slots, so the -Q_OBJECT macro must be expanded, and the moc does this for us. The resultant file, kscribble.moc, is -used by kscribble.cpp via an #include statement inside of the file. - - - - -The source skeleton - -To conceptualize how a KDE application works, we'll first have a very close look at the source -skeleton already provided by the Application Wizard. As we already saw, we're having a set of source -and header files that build the initial code for the application and make it ready-to-run. Therefore, -the easiest way to explain the code is to follow the implementation line by line as it is processed -during executing the program until it enters the main event loop and is ready to accept user input. -Then, we'll have a look at the functionality that enables user interaction and how certain things work. -This is probably the best way to explain the framework and, as it is similar to almost all KDE -applications, will enable you to read source codes from other projects as well; additionally, you will -know where to change what part of the code to make your applications behave the way they are designed for. - - - -The main() function - -As the application begins its execution with entering the main() function, -this will be the start for our code examination. The main() function of -KScribble is implemented in the file main.cpp and can also be found using the Class Browser -by selecting the "Global Functions" folder. - -1 int main(int argc, char **argv) -2 { -3 TDEAboutData about("kscribble", I18N_NOOP("KScribble"), version, description, -4 TDEAboutData::License_GPL, "(C) 2002 Your Name", 0, 0, "you@you.com"); -5 about.addAuthor( "Your Name", 0, "you@you.com" ); -6 TDECmdLineArgs::init(argc, argv, &about); -7 TDECmdLineArgs::addCmdLineOptions(options); -8 TDEApplication app; -9 -10 // register ourselves as a dcop client -11 app.dcopClient()->registerAs(app.name(), false); -12 -13 // see if we are starting with session management -14 if (app.isRestored()) -15 RESTORE(KScribble) -16 else -17 { -18 // no session.. just start up normally -19 TDECmdLineArgs *args = TDECmdLineArgs::parsedArgs(); -20 if (args->count() == 0) -21 { -22 KScribble *widget = new KScribble; -23 widget->show(); -24 } -25 else -26 { -27 int i = 0; -28 for (; i < args->count(); i++) -29 { -30 KScribble *widget = new KScribble; -31 widget->show(); -32 widget->load(args->url(i)); -33 } -34 } -35 args->clear(); -36 } -37 -38 return app.exec(); -39 } - - - -Now, what happens first is the usual creation of a TDEApplication object, but we've -added some KDE methods that set program and author information for this application. - - - -User Application Start - -... (not written yet) - - - -The Constructor - -Let's have a look at the constructor and see how this instance is called - -1 KScribble::KScribble() -2 : TDEMainWindow( 0, "KScribble" ), -3 m_view(new KScribbleView(this)), -4 m_printer(0) -5 { -6 // accept dnd -7 setAcceptDrops(true); -8 -9 // tell the TDEMainWindow that this is indeed the main widget -10 setCentralWidget(m_view); -11 -12 // then, setup our actions -13 setupActions(); -14 -15 // and a status bar -16 statusBar()->show(); -17 -18 // allow the view to change the statusbar and caption -19 connect(m_view, SIGNAL(signalChangeStatusbar(const QString&)), -20 this, SLOT(changeStatusbar(const QString&))); -21 connect(m_view, SIGNAL(signalChangeCaption(const QString&)), -22 this, SLOT(changeCaption(const QString&))); -23 -24 } - - - -Notice that KScribble inherits the TDEMainWindow class - a -commonly used base class for TDE applications. We initialize a class called KScribbleView -as our central widget, create a KStatusBar via the statusBar() -method (line 16), and connect some signals and slots together. - - - - - - - -Application View Design - -Introduction - -When developing an application with a graphical user interface, the main work takes place in -providing a so-called "view" for the application. A view generally is a widget that displays the data -of a document and provides methods to manipulate the document contents. This can be done by the user via -the events he emits by the keyboard or the mouse; more complex operations are often processed by toolbars -and menubars which interact with the view and the document. The statusbar then provides information about -the document, view or application status. As an example, we look at how an editor is constructed and where -we can find which part. - - -An editor generally is supposed to provide an interface to view and/or change the contents of a text -document for the user. If you start Kate, you see the visual interface as the following: - - -The menubar: providing complex operations as well as opening, saving and closing files and -exiting the application. - - -The toolbar: offers icons which allow quicker access for most needed functions, - - -The statusbar: displays the status of the cursor position by the current row and column, - - -The view in the center of the window, displaying a document and offering a cursor connected to -the keyboard and the mouse to operate on the data. - - - - -Now it's easy to understand that a view is the most unique part of the application and the design -of the view decides about the usability and acceptability of an application. This means that one of -the first steps in development is to determine the purpose of the application and what kind of view -design would match best to allow any user to work with the application with a minimum of work -learning how to handle the user interface. - - -For some purposes like text editing and displaying HTML files, views are provided by the Qt and KDE -libraries; we will discuss certain aspects of these high-level widgets in the next section. -But for most applications new widgets have to be designed and implemented. It is that what makes a -programmer also a designer and where his abilities on creativity are asked. Nevertheless, you should -watch for intuitivity first. Remember, a lot of users won't accept an application that isn't: - - -graphically nice. - - -offering a lot of features - - -easy to handle - - -fast to learn how to use it - - - - -Needless to say that stability is a major design goal. Nobody can prevent bugs, but a minimum can -be reached at least by clever design goals and wide use of object-oriented design. C++ makes programming -a joy if you know how to exploit it's capabilities- inheritance, information hiding and reusablitity of -already existing code. - - -When creating a KDE or Qt project, you always have to have a view that inherits QWidget, either by -direct inheritance or because the library widget you want to use inherits QWidget. Therefore, the -Application Wizard already constructed a view that is an instance of a class yourappView, which -inherits QWidget already. - - -This chapter therefore describes how to use library widgets for creating views of KDE or -Qt applications that are generated with &tdevelop;, then we look at the libraries and what kind of -views are already offered. - - - -Using Library Views - -When your application design has been set up, you first should look for already existing code that -will make your life a lot easier. A part of this search is to look for a widget that can be used as -a view or at least as a part of it; either directly or by inheritance. The KDE and Qt libraries already -contain a set of widgets that can be used for this purpose. To use them, you have two options: - - -Remove the new view class and create an instance of a library widget; then set this as the view, - - -Change the inheritance of the provided view class to the class of the library widget to use. - - - - -In either way, it is important to know that if the application framework is currently not linked -against the library that contains the widget, the linker will fail. After you decided to use a -certain widget, look for the library to link to; then open "Project"->"Options" from the &tdevelop; -menubar. Switch to the "Linker Options" page and look for the checkmarks indicating the libraries -that are currently used. If the library of your view widget is already checked, you can leave the -project options untouched and start doing the necessary changes due to your choice. If not, and the -linker options offer to add the library by a check box, check it and press "OK" to leave the project -options dialog again. In any other case, add the library in the edit line below with the -l option. -For libraries that your application has to search for before preparing the Makefiles by the -configure script on the end-user machine, add the according search macro to the configure.in file -located at the root directory of your project and add the macro to the edit line. Mind that you have -to run "Build"->"Autoconf and automake" and "Build"->"Configure" before the Makefiles contain the -correct expansion for the library macro. - - -Also, if the include files for the library to add are not in the current include path -(which can be seen by the -I options in the output window on "Make"), you have to add the path to the -Project Options dialog -"Compiler Options" page with the -I option or the according automake macro at -the edit line for "Additional Options". - - -Qt Views - -Looking at the first page of the Qt online documentation, you will find a link to -"Widget Screenshots" where you can have a look at how the widgets Qt contains look like. -These are ready to use and can be combined together to form complex widgets to create application -views or dialogs. In the following, we'll discuss some of these which are very usable for creating -application views, but keep in mind that the KDE libraries sometimes contain other widgets for the -same purpose; those will be reviewed in the next section. - - -Here are a set of hints for what purpose you could use which Qt component: - - -If your view area isn't big enough to display all your data, the user must be enabled to scroll -over the document with bars on the left and bottom of the view. For this, Qt provides the class -QScrollView, which offers a scrollable child area. As explained, you could -inherit your own widget from QScrollView or use an instance to manage your -document's view widget. - - -to create a ScrollView yourself, inherit the View widget from QWidget -and add vertical and horizontal QScrollBars . -(This is done by KDE`s TDEHTMLView widget.) - - -For text processing, use QTextEdit. This class provides a complete -text editor widget that is already capable to cut, copy and paste text and is managed by a scrollview. - - -Use QTable to display data that is arranged in a table. -As QTable is managed by scrollbars as well, it offers a good solution for -table calculation applications. - - -To display two different widgets or two widget instances at the same time, use QSplitter -. This allows to tile views by horizontal or vertical dividers. -KMail is a good example what this would look like- the main view is separated by a -splitter vertically, the right window then is divided again horizontally. - - -QListView displays information in a list and tree. -This is useful for creating file trees or any other hierarchical information you want to interact with. - - - - -You see that Qt alone offers a whole set of widgets which are ready to use so you don't have to invent -new solutions if these match your needs. The sideffect when using standard widgets is that users already -know how to handle them and only have to concentrate on the displayed data. - - - -KDE Views - -The KDE libraries were invented to make designing applications for the K Desktop Environment easier -and capable of more functionality than what Qt alone is offering. The tdeui library offers: - - -TDEListView: a more powerful version of QListView - - -TDEIconView: a graphical viewer of icon files - - - - -The tdehtml library, on the other hand, offers a complete HTML-interpreting widget that is ready to use. -It is scrollable already, so you don't even have to take care for that. A possible use could be to -integrate it as a preview widget for an HTML editor; used by applications such as Konqueror to display HTML files. - - - - -Creating your own Views - -Not yet written - - - - - -Configuring Menubars and Toolbars - -Introduction - -Menubars and toolbars are one of the most important parts of an application to provide methods to -work with a document structure. As a general rule, you should make all functions available by the menubar. -Those methods that should not be available at a current stage of the application process should be -disabled. - - -Further, an application can only contain one menubar, but several toolbars. -Toolbars on the other hand should contain only the most frequently used commands by pixmap -icons or provide quick access methods like combos to select values. - - - -How does it work? - -Our application inherits the TDEMainWindow class, which automatically handles creating -a menu bar and tool bars for us. In the KScribble::setupActions() method there is -a call to TDEMainWindow::createGUI(). This method loads a resource file, in this -case kscribbleui.rc, to initialize menus at startup. Note that kscribbleui.rc is listed as one of the -project files in the Automake Manager. Opening that file up reveals this: - -1 <!DOCTYPE kpartgui SYSTEM "kpartgui.dtd"> -2 <kpartgui name="kscribble" version="1"> -3 <MenuBar> -4 <Menu name="custom"><text>C&ustom</text> -5 <Action name="custom_action" /> -6 </Menu> -7 </MenuBar> -8 </kpartgui> - - - -Explanation... - - -Another way to modify the contents of the menu and tool bars is to directly manipulate them through the -methods provided by their class. For example, the menuBar() method returns the -KMenuBar widget that the menubar for our program. Looking at the documentation for -KMenuBar and its inheritor class QMenuBar, you will find -a large number of insertItem() methods which allow you to add items to the -menu bar. - - -TDEMainWindow's methods statusBar() and -toolBar() will also provide you with applicable widgets. - - - -Keyboard Accelerator Configuration - -A very professional thing you should always add to your application are keyboard accelerators. -Those are mainly used by experienced users that want to work fast with their applications and -are willing to learn shortcuts. For this, the KDE libraries provide the class -TDEAction, which provides the keyboard accelerator keys and access to global configured -standard keyboard accelerators. - - -By default, frame applications generated by &tdevelop; only use standard keyboard accelerators -such as F1 for accessing online-help, Ctrl+N for New File etc. - - -If your application contains a lot of accelerators, you should make them configurable -by an Options-menu; either it could be combined with other application configuration in a QWidget -or stand alone. The KDE library already provides a KKeyChooser -for use in tab dialogs, whereas KKeyDialog provides a ready-to use -key-configuration dialog. - - - - - - - -Help Functions - -Introduction - -A very important part of the development process is to provide help functionality to the user -wherever possible. Most developers tend to delay this, but you should remember that a normal user -isn't necessarily a Unix expert. He may come from the the dark side of computer software usage offering -all sweets that a user may need to work himself into using an application even without ever touching the -manuals. Therefore, the KDE and Qt library provide all means usually considered making an application -professional in the eyes of the normal user by help functions that are ready to use. -Within the application, those are: - -Tool-Tips -Statusbar help -What's this...? buttons - - -Additionally, the application should provide means to access a HTML-based online manual directly -using the standard help key F1. This context based help system is provided automatically through the -TDEMainWindow class, though as the author you must provide the content. - - -As &tdevelop; also offers all types of help as well as the KDE framework generated by the -application wizard already contains support for this, this chapter will help you find out where -and how to add your help functionality. - -During the development of your application you should try to be consistent whatever you're doing; -therefore you should do the necessary steps directly while extending the code. This will prevent you -from diving into the code again and figuring out what your application does or what you intended by -certain parts of the code. - - - - -Tool-Tips - -A very easy means of providing help are tool-tips. Those are small help messages popping up while -the user moves the mouse over a widget that provides a tool-tip and disappears when the mouse moves away. -The most popular usage of tool-tips is made in toolbars where your tool-tips should be kept as small -as possible because toolbars can be configured to display their contents in various ways: -either displaying the button, button with text on the right, button with text below, text only. -This possibility should be made configurable by the user, but isn't a must-be. The text is shown -as a tool-tip anyway and a toolbar usually consists of buttons and other widgets like lineedits and -combo boxes. For a complete reference, see the TDEToolBar class reference located -in the tdeui library. - - -As an example, we have a look at the "New File" button in a generic application: - - -There, the part i18n("New File") provides a tool-tip message. It is enclosed by the i18n() -macro provided by kapp.h to translate the tool-tip towards the currently selected language. - - -Tool-tips can also be added to any custom widget by using the QToolTip -provided by Qt. An example of that would be: - - - -Extending the Statusbar - -As the applications that inherit TDEMainWindow contain a statusbar as well, -it also offers a set of statusbar messages already for all menu and toolbar items. A statusbar -help message is a short message that extends the meaning of a tool-tip or can be seen as a replacement -for a tool-tip over menubar items and is (as the name suggests) displayed in the statusbar when the user -enters a menu and highlights the menu entry. - - - -The <guibutton>What's This...?</guibutton> Button - -The What's This...? button provides help windows with the intention -that the user wants to get help about a certain widget within the working view or a toolbar item. -It is placed in the toolbar and gets activated once the user hits the button. The cursor changes -to an arrow cursor with a question mark like the button itself looks like. The the user can press on -a visible widget item and gets a help window. As an exercise, you could try this behavior with the -What's this...? button within &tdevelop;. - - -To add the What's This...? help to one of your widgets, use the static method -QWhatsThis::add(QWidget *widget, const QString &text) - - - - - -Documentation - -Introduction - -Due to the fact that projects often lack a complete set of user documentation, -all &tdevelop; projects contain a pre-build handbook that can be easily adapted; -therefore fulfiling another goal of KDE: providing enough online-help to support users that -are not familiar with an application. This chapter therefore introduces you on how to extend -the provided documentation template and what you have to do to make it available to the user. - - - -User Documentation - -The documentation for your project lies in projectdir/doc/en, or perhaps another directory if English -isn't your native language. Therein lies a file, index.docbook, in which the documentation is stored. -The format for editing this file is explained on -KDE's documentation website. - - - -Programmer Documentation - -Another important part of the documentation is including a descriptive help for your class interfaces. -This will allow you and other programmers to use your classes by reading the HTML class documentation -that can be created with KDoc. &tdevelop; supports the use of KDoc completely by creating the -KDE-library documentation, also your application frameworks are already documented. To work yourself -into the provided code, it would be a good start to read the included documentation online. -The following describes what to do to get the API documentation, where &tdevelop; helps you add it -and what kind of special tags KDoc provides. - - - - - -Internationalization - -Introdction - -i18n is an internationalization system that is used to offer internationalized versions of an -application or project. The difficulty with writing applications is that they only support the -language they originally are composed with; visually this can be seen on labels, menu entries and the -like. The goal of the internationalization is to provide applications and library functions in the -language of the user; therefore enabling users that are not native speakers the original language to make -use of the provided functionality and feel more comfortable. - - - - - - -Credits - - -(... to be written ...) - - - - - - - -Bibliography - - - -<ulink url="info://make/Top">GNU Make Manual</ulink> - -Richard M.Stallman -RolandMcGrath - - - - -<ulink url="info://automake/Top">GNU Automake</ulink> - -DavidMacKenzie -TomTromey - - - - -<ulink url="info://autoconf/Top">GNU Autoconf</ulink> - -DavidMacKenzie -BenElliston - - - - -<ulink url="info://gcc/Top">Using the GNU Compiler Collection</ulink> -Richard M.Stallman - - - -<ulink url="info://libtool/Top">GNU Libtool</ulink> - -GordonMatzigkeit -AlexandreOliva -ThomasTanner -Gary V.Vaughan - - - - -GNU Autoconf, Automake, and Libtool -1st edition -October 2000 - -Gary V.Vaughan -BenElliston -TomTromey -Ian LanceTaylor - -New Riders Publishing -ISBN 1578701902 - - - - -Advanced Programming in the UNIX(R) Environment -1st edition -June 1992 -W. RichardStevens -Addison-Wesley Pub Co -ISBN 0201563177 - - - -Thinking in C++, Volume 1: Introduction to Standard C++ -2nd Edition -April 15, 2000 -BruceEckel -Prentice Hall -ISBN 0139798099 - - - -Open Source Development with CVS -2nd Edition -October 12, 2001 - -KarlFogel -MosheBar - -The Coriolis Group -ISBN 158880173X - - - -Programming PHP -1st edition -March 2002 - -RasmusLerdorf -KevinTatroe - -O'Reilly & Associates -ISBN 1565926102 - - - -Programming Python -2nd Edition -March 2001 -MarkLutz -O'Reilly & Associates -ISBN 0596000855 - - - -Gui Programming With Python : Using the Qt Toolkit -Bk&Cd-r edition -January 2002 -BoudewijnRempt -Opendocs Llc -ISBN 0970033044 - - - -Programming Perl -The Camel book -3rd Edition -July 2000 - -LarryWall -TomChristiansen -JonOrwant - -O'Reilly & Associates -ISBN 0596000278 - - - -Learning Perl -The Lama book -3rd Edition -July 15, 2001 - -Randal L.Schwartz -TomPhoenix - -O'Reilly & Associates -ISBN 0596001320 - - - - -&underFDL; - - - - - diff --git a/doc/kde_app_devel/kscribblefiles.png b/doc/kde_app_devel/kscribblefiles.png deleted file mode 100644 index 1591b3cf..00000000 Binary files a/doc/kde_app_devel/kscribblefiles.png and /dev/null differ diff --git a/doc/kdearch/Makefile.am b/doc/kdearch/Makefile.am deleted file mode 100644 index 171f575c..00000000 --- a/doc/kdearch/Makefile.am +++ /dev/null @@ -1,2 +0,0 @@ -KDE_LANG = en -KDE_DOCS = AUTO diff --git a/doc/kdearch/affine-general.png b/doc/kdearch/affine-general.png deleted file mode 100644 index 8e59d5e5..00000000 Binary files a/doc/kdearch/affine-general.png and /dev/null differ diff --git a/doc/kdearch/affine-rotate.png b/doc/kdearch/affine-rotate.png deleted file mode 100644 index 7192ed9c..00000000 Binary files a/doc/kdearch/affine-rotate.png and /dev/null differ diff --git a/doc/kdearch/affine-scale.png b/doc/kdearch/affine-scale.png deleted file mode 100644 index 0b52fd4c..00000000 Binary files a/doc/kdearch/affine-scale.png and /dev/null differ diff --git a/doc/kdearch/affine-shear.png b/doc/kdearch/affine-shear.png deleted file mode 100644 index 1ed5fbd8..00000000 Binary files a/doc/kdearch/affine-shear.png and /dev/null differ diff --git a/doc/kdearch/affine-translate.png b/doc/kdearch/affine-translate.png deleted file mode 100644 index 87265e30..00000000 Binary files a/doc/kdearch/affine-translate.png and /dev/null differ diff --git a/doc/kdearch/brushstyles.png b/doc/kdearch/brushstyles.png deleted file mode 100644 index b6df50ca..00000000 Binary files a/doc/kdearch/brushstyles.png and /dev/null differ diff --git a/doc/kdearch/canvas.png b/doc/kdearch/canvas.png deleted file mode 100644 index dd83dae9..00000000 Binary files a/doc/kdearch/canvas.png and /dev/null differ diff --git a/doc/kdearch/capflat.png b/doc/kdearch/capflat.png deleted file mode 100644 index 5e1c92ce..00000000 Binary files a/doc/kdearch/capflat.png and /dev/null differ diff --git a/doc/kdearch/capround.png b/doc/kdearch/capround.png deleted file mode 100644 index 0e66eaac..00000000 Binary files a/doc/kdearch/capround.png and /dev/null differ diff --git a/doc/kdearch/capsquare.png b/doc/kdearch/capsquare.png deleted file mode 100644 index 35724a72..00000000 Binary files a/doc/kdearch/capsquare.png and /dev/null differ diff --git a/doc/kdearch/index.docbook b/doc/kdearch/index.docbook deleted file mode 100644 index 97dee33d..00000000 --- a/doc/kdearch/index.docbook +++ /dev/null @@ -1,3337 +0,0 @@ - - - -]> - - - - -KDE Architecture Overview - - - - - - -Bernd -Gehrmann -
bernd@kdevelop.org
 - - - - -2001 -2002 -Bernd Gehrmann - - -&FDLNotice; - - -This documentation gives an overview of the KDE Development Platform - - - -KDE -architecture -development -programming - - - - - -Library structure - - -Libraries by name - - - - -tdecore - -The tdecore library is the basic application framework for every KDE based -program. It provides access to the configuration system, command line -handling, icon loading and manipulation, some special kinds inter-process -communication, file handling and various other utilities. - - - - -tdeui - -The tdeui library provides many widgets and standard -dialogs which Qt doesn't have or which have more features than their Qt -counterparts. It also includes several widgets which are subclassed -from Qt ones and are better integrated with the KDE desktop by -respecting user preferences. - - - - -tdeio - -The tdeio library contains facilities for asynchronous, -network transparent I/O and access to mimetype handling. It also provides the -KDE file dialog and its helper classes. - - - - -kjs - -The kjs library provides an implementation of JavaScript. - - - - -tdehtml - -The tdehtml library contains the TDEHTML part, a HTML browsing -widget, DOM API and parser, including interfaces to Java and JavaScript. - - - - - - - - - -Grouped classes - - -Core application skeleton - classes needed by almost every application. - - - - - -<ulink url="kdeapi:tdecore/TDEApplication">TDEApplication</ulink> - -Initializes and controls a KDE application. - - - - -<ulink url="kdeapi:tdecore/KUniqueApplication">KUniqueApplication</ulink> - -Makes sure only one instance of an application can run simultaneously. - - - -<ulink url="kdeapi:tdecore/TDEAboutData">TDEAboutData</ulink> - -Holds information for the about box. - - - -<ulink url="kdeapi:tdecore/TDECmdLineArgs">TDECmdLineArgs</ulink> - -Command line argument processing. - - - - - - -Configuration settings - access to KDE's hierarchical configuration -database, global settings and application resources. - - - - -<ulink url="kdeapi:tdecore/TDEConfig">TDEConfig</ulink> - -Provides access to KDE's configuration database. - - - -<ulink url="kdeapi:tdecore/KSimpleConfig">KSimpleConfig</ulink> - -Access to simple, non-hierarchical configuration files. - - - -<ulink url="kdeapi:tdecore/KDesktopFile">KDesktopFile</ulink> - -Access to .desktop files. - - - -<ulink url="kdeapi:tdecore/TDEGlobalSettings">TDEGlobalSettings</ulink> - -Convenient access to not application-specific settings. - - - - - - -File and URL handling - decoding of URLs, temporary files etc. - - - - -<ulink url="kdeapi:tdecore/KURL">KURL</ulink> - -Represents and parses URLs. - - - -<ulink url="kdeapi:tdecore/KTempFile">KTempFile</ulink> - -Creates unique files for temporary data. - - - -<ulink url="kdeapi:tdecore/KSaveFile">KSaveFile</ulink> - -Allows to save files atomically. - - - - - - -Interprocess communication - DCOP helper classes and subprocess invocation. - - - - -<ulink url="kdeapi:tdecore/TDEProcess">TDEProcess</ulink> - -Invokes and controls child processes. - - - -<ulink url="kdeapi:tdecore/KShellProcess">KShellProcess</ulink> - -Invokes child processes via a shell. - - - -<ulink url="kdeapi:tdesu/PtyProcess">PtyProcess</ulink> - -Communication with a child processes through a pseudo terminal. - - - -<ulink url="kdeapi:tdecore/KIPC">KIPC</ulink> - -Simple IPC mechanism using X11 ClientMessages. - - - -<ulink url="kdeapi:dcop/DCOPClient">DCOPClient</ulink> - -DCOP messaging. - - - -<ulink url="kdeapi:tdecore/KDCOPPropertyProxy">KDCOPPropertyProxy</ulink> - -A proxy class publishing Qt properties through DCOP. - - - -<ulink url="kdeapi:tdeui/KDCOPActionProxy">KDCOPActionProxy</ulink> - -A proxy class publishing a DCOP interface for actions. - - - - - - -Utility classes - memory management, regular expressions, string manipulation, -random numbers - - - - -<ulink url="kdeapi:tdecore/KRegExp">KRegExp</ulink> - -POSIX regular expression matching. - - - -<ulink url="kdeapi:tdecore/KStringHandler">KStringHandler</ulink> - -An extravagant interface for string manipulation. - - - -<ulink url="kdeapi:tdecore/TDEZoneAllocator">TDEZoneAllocator</ulink> - -Efficient memory allocator for large groups of small objects. - - - -<ulink url="kdeapi:tdecore/KRandomSequence">KRandomSequence</ulink> - -Pseudo random number generator. - - - - - - -Keyboard accelerators - classes helping to establish consistent key bindings -throughout the desktop. - - - - -<ulink url="kdeapi:tdecore/TDEAccel">TDEAccel</ulink> - -Collection of keyboard shortcuts. - - - -<ulink url="kdeapi:tdecore/TDEStdAccel">TDEStdAccel</ulink> - -Easy access to the common keyboard shortcut keys. - - - -<ulink url="kdeapi:tdecore/TDEGlobalAccel"></ulink> - -Collection of system-wide keyboard shortcuts. - - - - - - -Image processing - icon loading and manipulating. - - - - -<ulink url="kdeapi:tdecore/TDEIconLoader">TDEIconLoader</ulink> - -Loads icons in a theme-conforming way. - - - -<ulink url="kdeapi:tdecore/TDEIconTheme">TDEIconTheme</ulink> - -Helper classes for TDEIconLoader. - - - -<ulink url="kdeapi:tdecore/KPixmap">KPixmap</ulink> - -A pixmap class with extended dithering capabilities. - - - -<ulink url="kdeapi:tdeui/KPixmapEffect">KPixmapEffect</ulink> - -Pixmap effects like gradients and patterns. - - - -<ulink url="kdeapi:tdeui/KPixmapIO">KPixmapIO</ulink> - -Fast QImage to QPixmap conversion. - - - - - - -Drag and Drop - drag objects for colors and URLs. - - - - -<ulink url="kdeapi:tdecore/KURLDrag">KURLDrag</ulink> - -A drag object for URLs. - - - -<ulink url="kdeapi:tdeui/KColorDrag">KColorDrag</ulink> - -A drag object for colors. - - - -<ulink url="kdeapi:tdecore/KMultipleDrag">KMultipleDrag</ulink> - -Allows to construct drag objects from several others. - - - - - - -Auto-Completion - - - - -<ulink url="kdeapi:tdecore/TDECompletion">TDECompletion</ulink> - -Generic auto-completion of strings. - - - -<ulink url="kdeapi:tdeio/KURLCompletion">KURLCompletion</ulink> - -Auto-completion of URLs. - - - -<ulink url="kdeapi:tdeio/KShellCompletion">KShellCompletion</ulink> - -Auto-completion of executables. - - - - - - -Widgets - widget classes for list views, rules, color selection etc. - - - - -<ulink url="kdeapi:tdeui/TDEListView">TDEListView</ulink> - -A variant of QListView that honors KDE's system-wide settings. - - - -<ulink url="kdeapi:tdeui/TDEListView">TDEListBox</ulink> - -A variant of QListBox that honors KDE's system-wide settings. - - - -<ulink url="kdeapi:tdeui/TDEListView">TDEIconView</ulink> - -A variant of QIconView that honors KDE's system-wide settings. - - - -<ulink url="kdeapi:tdeui/TDEListView">KLineEdit</ulink> - -A variant of QLineEdit with completion support. - - - -<ulink url="kdeapi:tdeui/KComboBox">KComboBox</ulink> - -A variant of QComboBox with completion support. - - - -<ulink url="kdeapi:tdeui/TDEFontCombo">TDEFontCombo</ulink> - -A combo box for selecting fonts. - - - -<ulink url="kdeapi:tdeui/KColorCombo">KColorCombo</ulink> - -A combo box for selecting colors. - - - -<ulink url="kdeapi:tdeui/KColorButton">KColorButton</ulink> - -A button for selecting colors. - - - -<ulink url="kdeapi:tdeui/KURLCombo">KURLCombo</ulink> - -A combo box for selecting file names and URLs. - - - -<ulink url="kdeapi:tdefile/KURLRequester">KURLRequester</ulink> - -A line edit for selecting file names and URLs. - - - -<ulink url="kdeapi:tdeui/KRuler">KRuler</ulink> - -A ruler widget. - - - -<ulink -url="kdeapi:tdeui/KAnimWidget">KAnimWidget</ulink> - -animations. - - - -<ulink url="kdeapi:tdeui/KNumInput">KNumInput</ulink> - -A widget for inputting numbers. - - - -<ulink url="kdeapi:tdeui/KPasswordEdit">KPasswordEdit</ulink> - -A widget for inputting passwords. - - - - - - -Dialogs - full-featured dialogs for file, color and font selection. - - - - -<ulink url="kdeapi:tdefile/KFileDialog">KFileDialog</ulink> - -A file selection dialog. - - - -<ulink url="kdeapi:tdeui/KColorDialog">KColorDialog</ulink> - -A color selection dialog. - - - -<ulink url="kdeapi:tdeui/TDEFontDialog">TDEFontDialog</ulink> - -A font selection dialog. - - - -<ulink url="kdeapi:tdefile/TDEIconDialog">TDEIconDialog</ulink> - -An icon selection dialog. - - - -<ulink url="kdeapi:tdeui/KKeyDialog">KKeyDialog</ulink> - -A dialog for editing keyboard bindings. - - - -<ulink url="kdeapi:tdeui/KEditToolBar">KEditToolBar</ulink> - -A dialog for editing toolbars. - - - -<ulink url="kdeapi:tdeui/KTipDialog">KTipDialog</ulink> - -A Tip-of-the-day dialog. - - - -<ulink url="kdeapi:tdeui/TDEAboutDialog">TDEAboutDialog</ulink> - -An about dialog. - - - -<ulink url="kdeapi:tdeui/KLineEditDlg">KLineEditDlg</ulink> - -A simple dialog for entering text. - - - -<ulink url="kdeapi:tdefile/KURLRequesterDlg">KURLRequesterDlg</ulink> - -A simple dialog for entering URLs. - - - -<ulink url="kdeapi:tdeui/KMessageBox">KMessageBox</ulink> - -A dialog for signaling errors and warnings. - - - -<ulink url="kdeapi:tdeui/KPasswordDialog">KPasswordDialog</ulink> - -A dialog for inputting passwords. - - - - - - -Actions and XML GUI - - - - -<ulink url="kdeapi:tdeui/TDEAction">TDEAction</ulink> - -Abstraction for an action that can be plugged into menu bars and tool bars. - - - -<ulink url="kdeapi:tdeui/TDEActionCollection">TDEActionCollection</ulink> - -A set of actions. - - - -<ulink url="kdeapi:tdeui/KXMLGUIClient">KXMLGUIClient</ulink> - -A GUI fragment consisting of an action collection and a DOM tree representing their location in the GUI. - - - -<ulink url="kdeapi:tdeparts/KPartManager">KPartManager</ulink> - -Manages the activation of XMLGUI clients. - - - - - - -Plugins and Components - - - - -<ulink url="kdeapi:tdecore/KLibrary">KLibrary</ulink> - -Represents a dynamically loaded library. - - - -<ulink url="kdeapi:tdecore/KLibrary">KLibLoader</ulink> - -Shared library loading. - - - -<ulink url="kdeapi:tdecore/KLibFactory">KLibFactory</ulink> - -Object factory in plugins. - - - -<ulink url="kdeapi:tdeio/KServiceType">KServiceType</ulink> - -Represents a service type. - - - -<ulink url="kdeapi:tdeio/KService">KService</ulink> - -Represents a service. - - - -<ulink url="kdeapi:tdeio/KMimeType">KMimeType</ulink> - -Represents a MIME type. - - - -<ulink url="kdeapi:tdeio/KServiceTypeProfile">KServiceTypeProfile</ulink> - -User preferences for MIME type mappings. - - - -<ulink url="kdeapi:tdeio/KServiceTypeProfile">TDETrader</ulink> - -Querying for services. - - - - - - - - - - - - -Graphics - - -Low-level graphics with QPainter - - -Rendering with QPainter - - -Qt's low level imaging model is based on the capabilities provided by X11 and -other windowing systems for which Qt ports exist. But it also extends these by -implementing additional features such as arbitrary affine transformations for -text and pixmaps. - - - -The central graphics class for 2D painting with Qt is -QPainter. It can -draw on a -QPaintDevice. -There are three possible paint devices implemented: One is -QWidget -which represents a widget on the screen. The second is -QPrinter which -represents a printer and produces Postscript output. The third it -the class -QPicture which -records paint commands and can save them on disk and play them back -later. A possible storage format for paint commands is the W3C standard -SVG. - - - -So, it is possible to reuse the rendering code you use for displaying a -widget for printing, with the same features supported. Of course, in -practice, the code is used in a slightly different context. Drawing -on a widget is almost exclusively done in the paintEvent() method -of a widget class. - - - -void FooWidget::paintEvent() -{ - QPainter p(this); - // Setup painter - // Use painter -} - - - -When drawing on a printer, you have to make sure to use QPrinter::newPage() -to finish with a page and begin a new one - something that naturally is not -relevant for painting widgets. Also, when printing, you may want to use the -device metrics -in order to compute coordinates. - - - - - - -Transformations - - -By default, when using QPainter, it draws in the natural coordinate -system of the device used. This means, if you draw a line along the horizontal -axis with a length of 10 units, it will be painted as a horizontal line -on the screen with a length of 10 pixels. However, QPainter can apply arbitrary -affine transformations before actually rendering shapes and curves. An -affine transformation maps the x and y coordinates linearly into x' and -y' according to - - - - - - - -The 3x3 matrix in this equation can be set with QPainter::setWorldMatrix() and -is of type QWMatrix. -Normally, this is the identity matrix, i.e. m11 and m22 are one, and the -other parameters are zero. There are basically three different groups of -transformations: - - - - - -Translations - -These move all points of an object by a fixed amount in -some direction. A translation matrix can be obtained by calling -method m.translate(dx, dy) for a QWMatrix. This corresponds to the -matrix - - - - - - - - - - -Scaling - -These stretch or shrink the coordinates of an object, making -it bigger or smaller without distorting it. A scaling transformation -can be applied to a QWMatrix by calling m.scale(sx, sy). This corresponds -to the matrix - - - - - - - - -By setting one of the parameters to a negative value, one can -achieve a mirroring of the coordinate system. - - - - - -Shearing - -A distortion of the coordinate system with two -parameters. A shearing transformation can be applied by calling -m.shear(sh, sv), corresponding to the matrix - - - - - - - - - - -Rotating - -This rotates an object. A rotation transformation can be -applied by calling m.rotate(alpha). Note that the angle has to be given -in degrees, not as mathematical angle! The corresponding matrix is - - - - - - - - -Note that a rotation is equivalent with a combination of -scaling and shearing. - - - - - - - -Here are some pictures that show the effect of the elementary -transformation to our masquot: - - - - - - - - - - - - - - - - - - - - -a) Normal -b) Rotated by 30 degrees -c) Sheared by 0.4 -d) Mirrored - - - - - - -Transformations can be combined by multiplying elementary matrices. Note that -matrix operations are not commutative in general, and therefore the combined -effect of of a concatenation depends on the order in which the matrices are -multiplied. - - - - - - -Setting stroking attributes - - -The rendering of lines, curves and outlines of polygons can be modified by -setting a special pen with QPainter::setPen(). The argument of this function is a -QPen object. The properties -stored in it are a style, a color, a join style and a cap style. - - - -The pen style is member of the enum -Qt::PenStyle. -and can take one of the following values: - - - - - - - -The join style is a member of the enum -Qt::PenJoinStyle. -It specifies how the junction between multiple lines which are attached to each -other is drawn. It takes one of the following values: - - - - - - - - - - - - - - - - - -a) MiterJoin -c) BevelJoin -b) RoundJoin - - - - - - -The cap style is a member of the enum -Qt::PenCapStyleand specifies how the end points of lines are drawn. It takes one of the values -from the following table: - - - - - - - - - - - - - - - - - -a) FlatCap -b) SquareCap -c) RoundCap - - - - - - - - - -Setting fill attributes - - -The fill style of polygons, circles or rectangles can be modified by setting -a special brush with QPainter::setBrush(). This function takes a -QBrush object as argument. -Brushes can be constructed in four different ways: - - - - -QBrush::QBrush() - This creates a brush that does not fill shapes. - - -QBrush::QBrush(BrushStyle) - This creates a black brush with one of the default -patterns shown below. - - -QBrush::QBrush(const QColor &, BrushStyle) - This creates a colored brush -with one of the patterns shown below. - - -QBrush::QBrush(const QColor &, const QPixmap) - This creates a colored -brush with the custom pattern you give as second parameter. - - - - -A default brush style is from the enum -Qt::BrushStyle. -Here is a picture of all predefined patterns: - - - - - - - -A further way to customize the brush behavior is to use the function -QPainter::setBrushOrigin(). - - - - - - -Color - - -Colors play a role both when stroking curves and when filling shapes. In Qt, -colors are represented by the class -QColor. Qt does not support -advanced graphics features like ICC color profiles and color correction. Colors -are usually constructed by specifying their red, green and blue components, as -the RGB model is the way pixels are composed of on a monitor. - - - -It is also possible to use hue, saturation and value. This HSV representation is -what you use in the Gtk color dialog, e.g. in GIMP. There, the hue corresponds -to the angle on the color wheel, while the saturation corresponds to the -distance from the center of the circle. The value can be chosen with a separate -slider. - - - - - - -Other settings - - -Normally, when you paint on a paint device, the pixels you draw replace those -that were there previously. This means, if you paint a certain region with -a red color and paint the same region with a blue color afterwards, only -the blue color will be visible. Qt's imaging model does not support -transparency, i.e. a way to blend the painted foreground with the background. -However, there is a simple way to combine background and foreground with -boolean operators. The method QPainter::setRasterOp() sets the used operator, -which comes from the enum -RasterOp. - - - -The default is CopyROP which ignores the background. Another popular choice is -XorROP. If you paint a black line with this operator on a colored image, then -the covered area will be inverted. This effect is for example used to create -the rubberband selections in image manipulation programs known as -"marching ants". - - - - - - -Drawing graphics primitives - - -In the following we list the elementary graphics elements supported by -QPainter. Most of them exist in several overloaded versions which take a -different number of arguments. For example, methods that deal with rectangles -usually either take a -QRect as argument or a set -of four integers. - - - - -Drawing a single point - drawPoint(). - - -Drawing lines - drawLine(), drawLineSegments() and drawPolyLine(). - - -Drawing and filling rectangles - drawRect(), drawRoundRect(), -fillRect() and eraseRect(). - - -Drawing and filling circles, ellipses and parts or them - -drawEllipse(), drawArc(), drawPie and drawChord(). - - -Drawing and filling general polygons - drawPolygon(). - - -Drawing bezier curves - drawQuadBezier() [drawCubicBezier in Qt 3.0]. - - - - - - - -Drawing pixmaps and images - - -Qt provides two very different classes to represent images. - - - -QPixmap directly corresponds -to the pixmap objects in X11. Pixmaps are server-side objects and may - on a -modern graphics card - even be stored directly in the card's memory. This makes -it very efficient to transfer pixmaps to the screen. Pixmaps also act as -an off-screen equivalent of widgets - the QPixmap class is a subclass of -QPaintDevice, so you can draw on it with a QPainter. Elementary drawing -operations are usually accelerated by modern graphics. Therefore, a common usage -pattern is to use pixmaps for double buffering. This means, instead of painting -directly on a widget, you paint on a temporary pixmap object and use the -bitBlt -function to transfer the pixmap to the widget. For complex repaints, this helps -to avoid flicker. - - - -In contrast, QImage objects -live on the client side. Their emphasis in on providing direct access to the -pixels of the image. This makes them of use for image manipulation, and things -like loading and saving to disk (QPixmap's load() method takes QImage as -intermediate step). On the other hand, painting an image on a widget is a -relatively expensive operation, as it implies a transfer to the X server, -which can take some time, especially for large images and for remote servers. -Depending on the color depth, the conversion from QImage to QPixmap may also -require dithering. - - - - - - -Drawing text - - -Text can be drawn with one of the overloaded variants of the method -QPainter::drawText(). These draw a QString either at a given point or in a given -rectangle, using the font set by QPainter::setFont(). There is also a parameter -which takes an ORed combination of some flags from the enums -Qt::AlignmentFlags -and -Qt::TextFlags - - - -Beginning with version 3.0, Qt takes care of the complete text layout even for -languages written from right to left. - - - -A more advanced way to display marked up text is the -QSimpleRichText -class. Objects of this class can be constructed with a piece of text using -a subset of the HTML tags, which is quite rich and provides even tables. -The text style can be customized by using a -QStyleSheet (the -documentation of the tags can also be found here). Once the rich text object has -been constructed, it can be rendered on a widget or another paint device with -the QSimpleRichText::draw() method. - - - - - - - - -Structured graphics with QCanvas - - -QPainter offers a powerful imaging model for painting on widgets and pixmaps. -However, it can also be cumbersome to use. Each time your widget receives -a paint event, it has to analyze the QPaintEvent::region() or -QPaintEvent::rect() which has to be redrawn. Then it has to setup a -QPainter and paint all objects which overlap with that region. For example, -image a vector graphics program which allows to drag objects like polygons, -circles and groups of them around. Each time those objects move a bit, the -widget's mouse event handler triggers a paint event for the whole area covered -by the objects in their old position and in their new position. Figuring -out the necessary redraws and doing them in an efficient way can be difficult, -and it may also conflict with the object-oriented structure of the program's -source code. - - - -As an alternative, Qt contains the class -QCanvas in which -you put graphical objects like polygons, text, pixmaps. You may also provide -additional items by subclassing -QCanvasItem or -one of its more specialized subclasses. A canvas can be shown on the screen by -one or more widgets of the class -QCanvasView which -you have to subclass in order to handle user interactions. Qt takes care of -all repaints of objects in the view, whether they are caused by the widget -being exposed, new objects being created or modified or other things. By using -double buffering, this can be done in an efficient and flicker-free way. - - - -Canvas items can overlap each other. In this case, the visible one depends on -the z order which can be assigned by QCanvasItem::setZ(). Items can also be -made visible or invisible. You can also provide a background to be drawn -"behind" all items and a foreground. For associating mouse events with objects, -in the canvas, there is the method QCanvas::collisions() which returns a list -of items overlapping with a given point. Here we show a screenshot of a canvas -view in action: - - - - - - - -Here, the mesh is drawn in the background. Furthermore, there is a -QCanvasText item and a violet QCanvasPolygon. The butterfly is a -QCanvasPixmap. It has transparent areas, so you can see the underlying -items through it. - - - -A tutorial on using QCanvas for writing sprite-based games can be -found here. - - - - - - -3D graphics with OpenGL - - -Low-level interface - - -The de facto standard for rendering 3D graphics today is -OpenGL. Implementations of this -specification come with Microsoft Windows, Mac OS X and XFree86 and often -support the hardware acceleration features offered by modern graphics cards. -OpenGL itself only deals with rendering on a specified area of the framebuffer -through a GL context and does not have any interactions -with the toolkit of the environment - - - -Qt offers the widget QGLWidget -which encapsulates a window with an associated GL context. Basically, you use it -by subclassing it and reimplementing some methods. - - - - - -Instead of reimplementing paintEvent() and using QPainter to draw the widget's -contents, you override paintGL() and use GL commands to render a scene. QLWidget -will take care of making its GL context the current one before paintGL() is -called, and it will flush afterwards. - - - -The virtual method initializeGL() is called once before the first time resizeGL() -or paintGL() are called. This can be used to construct display lists for objects, -and make any initializations. - - - -Instead of reimplementing resizeEvent(), you override resizeGL(). This can -be used to set the viewport appropriately. - - - -Instead of calling update() when the state of the scene has changed - for example -when you animate it with a timer -, you should call updateGL(). This will trigger -a repaint. - - - - - -In general, QGLWidget behaves just like any other widget, i.e. for example -you can process mouse events as usual, resize the widget and combine it with -others in a layout. - - - - - - - -Qt contains some examples of QGLWidget usage in its demo -example. A collection of tutorials can be found -here, -and more information and a reference of OpenGL is available on the -OpenGL homepage. - - - - - - -High-level interfaces - - -OpenGL is a relatively low-level interface for drawing 3D graphics. In the same -way QCanvas gives the programmer a higher-level interface which details with -objects and their properties, there are also high-level interfaces for 3D graphics. -One of the most popular is Open Inventor. Originally a technology developed by SGI, -there is today also the open source implementation -Coin, complemented by a toolkit binding to Qt -called SoQt. - - - -The basic concept of Open Inventor is that of a scene. -A scene can be loaded from disk and saved in a special format closely related -to VRML. A scene consists of a -collection of objects called nodes. Inventor already -provides a rich collection of reusable nodes, such as cubes, cylinders and -meshes, furthermore light sources, materials, cameras etc. Nodes are -represented by C++ classes and can be combined and subclassed. - - - -An introduction to Inventor can be found -here -(in general, you can substitute all mentions of SoXt by SoQt in this article). - - - - - - - - - - - -User interface - - -The action pattern - - - - - - - -Defining menus and toolbars in XML - - -Introduction - - -While the action pattern -allows to encapsulate actions triggered by the user in an object which can be -"plugged" somewhere in the menu bars or toolbars, it does not by itself solve -the problem of constructing the menus themselves. In particular, you have to -build all popup menus in C++ code and explicitly insert the actions in a -certain order, under consideration of the style guide for standard actions. -This makes it pretty difficult to allow the user to customize the menus or -change shortcuts to fit his needs, without changing the source code. - - - -This problem is solved by a set of classes called XMLGUI. -Basically, this separates actions (coded in C++) from their appearance in menu -bars and tool bars (coded in XML). Without modifying any source code, menus -can be simply customized by adjusting an XML file. Furthermore, it helps -to make sure that standard actions (such as -FileOpen -or HelpAbout) -appear in the locations suggested by the style guide. XMLGUI is especially -important for modular programs, where the items appearing in the menu bar may -come from many different plugins or parts. - - - -KDE's class for toplevel windows, -TDEMainWindow, -inherits -KXMLGUIClient -and therefore supports XMLGUI out of the box. All actions created within it must -have the client's actionCollection() as parent. A call to -createGUI() will then build the whole set of menu and tool -bars defined the applications XML file (conventionally with the suffix -ui.rc). - - - - - - -An example: Menu in KView - - -In the following, we take KDE's image view KView as -example. It has a ui.rc file named -kviewui.rc which is installed with the -Makefile.am snippet - - - -rcdir = $(kde_datadir)/kview -rc_DATA = kviewui.rc - - - -Here is an excerpt from the kviewui.rc file. For -simplicity, we show only the definition of the View menu. - - - -<!DOCTYPE kpartgui> -<kpartgui name="kview"> - <MenuBar> - <Menu name="view" > - <Action name="zoom50" /> - <Action name="zoom100" /> - <Action name="zoom200" /> - <Action name="zoomMaxpect" /> - <Separator/> - <Action name="fullscreen" /> - </Menu> - </MenuBar> -</kpartgui> - - - -The corresponding part of the setup in C++ is: - - - - KStdAction::zoomIn ( this, SLOT(slotZoomIn()), actionCollection() ); - KStdAction::zoomOut ( this, SLOT(slotZoomOut()), actionCollection() ); - KStdAction::zoom ( this, SLOT(slotZoom()), actionCollection() ); - new TDEAction ( i18n("&Half size"), ALT+Key_0, - this, SLOT(slotHalfSize()), - actionCollection(), "zoom50" ); - new TDEAction ( i18n("&Normal size"), ALT+Key_1, - this, SLOT(slotDoubleSize()), - actionCollection(), "zoom100" ); - new TDEAction ( i18n("&Double size"), ALT+Key_2, - this, SLOT(slotDoubleSize()), - actionCollection(), "zoom200" ); - new TDEAction ( i18n("&Fill Screen"), ALT+Key_3, - this, SLOT(slotFillScreen()), - actionCollection(), "zoomMaxpect" ); - new TDEAction ( i18n("Fullscreen &Mode"), CTRL+SHIFT+Key_F, - this, SLOT(slotFullScreen()), - actionCollection(), "fullscreen" ); - - - -The View menu resulting from this GUI definition looks like -in this screenshot: - - - - - - - -The XML file begins with a document type declaration. The DTD for kpartgui can -be found in the tdelibs sources in tdeui/kpartgui.dtd. The -outermost element of the file contains the instance name of the application as -attribute. It can also contain a version number in the form "version=2". This -is useful when you release new versions of an application with a changed menu -structure, e.g. with more features. If you bump up the version number of the -ui.rc file, KDE makes sure that any customized version of -the file is discarded and the new file is used instead. - - - -The next line, <MenuBar>, contains a declaration of a -menu bar. You can also insert any number of <ToolBar> -declarations in order to create some tool bars. The menu contains a submenu -with the name "view". This name is already predefined, and thus you see a -translated version of the word "View" in the screenshot. If you declare your -own submenus, you have to add the title explicitly. For example, -KView has a submenu with the title "Image" which is -declared as follows: - - - -<Menu name="image" > - <text>&amp;Image</text> - ... -</Menu> - - - -In KDE's automake framework, such titles are automatically extracted and put -into the application's .po -file , so it is considered by translators. Note that you have to write the -accelerator marker "&" in the form XML compliant form "&amp;". - - - -Let us come back to the example. KView's -View menu contains a couple of custom actions: -zoom50, zoom100, -zoom200, zoomMaxpect and -fullscreen, declared with a -<Action> element. The separator in the -screenshots corresponds to the <Separator> element. - - - -You will note that some menu items do not not have a corresponding element in -the XML file. These are standard actions. Standard -actions are created by the class -KStdAction. -When you create such actions in your application (such as in the C++ example -above), they will automatically be inserted in a prescribed position, and -possibly with an icon and a shortcut key. You can look up these locations in -the file tdeui/ui_standards.rc in the tdelibs sources. - - - - - - -An example: Toolbars in Konqueror - - -For the discussion of toolbars, we switch to -Konqueror's GUI definition. This excerpt defines -the location bar, which contains the input field for URLs. - - - -<ToolBar name="locationToolBar" fullWidth="true" newline="true" > - <text>Location Toolbar</text> - <Action name="clear_location" /> - <Action name="location_label" /> - <Action name="toolbar_url_combo" /> - <Action name="go_url" /> -</ToolBar> - - - -The first thing we notice is that there are a lot more attributes than for -menu bars. These include: - - - - - -fullWidth: Tells XMLGUI that the toolbar has the same width as the - toplevel window. Af this is "false", the toolbar only takes as much space as - necessary, and further toolbars are put in the same row. - - - -newline: This is related to the option above. If newline is "true", -the toolbar starts a new row. Otherwise it may be put in the row together -with the previous toolbar. - - - -noEdit: Normally toolbars can be customized by the user, -e.g. in SettingsConfigure -Toolbars in -Konqueror. Setting this option to "true" marks this -toolbar as not editable. This is important for toolbars which are filled with -items at runtime, e.g. Konqueror's bookmark toolbar. - - - -iconText: Tells XMLGUI to show the text of the action next to the -icon. Normally, the text is only shown as a tooltip when the mouse cursor -remains over the icon for a while. Possible values for this attribute are -"icononly" (shows only the icon), "textonly" (shows only the text), -"icontextright" (shows the text on the right side of the icon) and -"icontextbottom" (shows the text beneath the icon). - - - - -hidden: If this is "true", the toolbar is not visible initially -and must be activated by some menu item. - - - - -position: The default for this attribute is "top", meaning that the -toolbar is positioned under the menu bar. For programs with many tools, -such as graphics programs, it may be interesting to replace this with -"left", "right" or "bottom". - - - - - - - - -Dynamical menus - - -Obviously, an XML can only contain a static description of a user interface. -Often, there are menus which change at runtime. For example, -Konqueror's Location menu -contains a set of items Open with Foo with the -applications able to load a file with a given MIME type. Each time the -document shown changes, the list of menu items is updated. XMLGUI is prepared -to handle such cases with the notion of action lists. -An action list is declared as one item in the XML file, but consists of -several actions which are plugged into the menu at runtime. The above example -is implemented with the following declaration in -Konqueror's XML file: - - - -<Menu name="file"> - <text>&amp;Location</text> - ... - <ActionList name="openwith"> - ... -</Menu> - - - -The function KXMLGUIClient::plugActionList() is then used -to add actions to be displayed, whereas the function -KXMLGuiClient::unplugActionList() removes all -plugged actions. The routine responsible for updating looks as follows: - - - -void MainWindow::updateOpenWithActions() -{ - unplugActionList("openwith"); - openWithActions.clear(); - for ( /* iterate over the relevant services */ ) { - TDEAction *action = new TDEAction( ...); - openWithActions.append(action); - } - plugActionList("openwith", openWithActions); -} - - - -Note that in contrast to the static actions, the ones created here are -not constructed with the action collection as parent, and -you are responsible for deleting them for yourself. The simplest way to achievethis -is by using openWithActions.setAutoDelete(true) in the above -example. - - - - - - -Context menus - - -The examples above only contained cases where a main window's menubar and -toolbars were created. In the cases, the processes of constructing these -containers is completely hidden from you behind the -createGUI() call (except if you have custom containers). -However, there are cases, where you want to construct other containers and -populate them with GUI definitions from the XML file. One such example are -context menus. In order to get a pointer to a context menu, you have to -ask the client's factory for it: - - - -void MainWindow::popupRequested() -{ - QWidget *w = factory()->container("context_popup", this); - QPopupMenu *popup = static_cast<QPopupMenu *>(w); - popup->exec(QCursor::pos()); -} - - - -The method KXMLGUIFactory::container() used above looks -whether it finds a container in the XML file with the given name. Thus, a -possible definition could look as follows: - - - -... -<Menu name="context_popup"> - <Action name="file_add"/> - <Action name="file_remove"/> -</Menu> -... - - - - - - - - -Providing online help - - -Making a program easy and intuitive to use involves a wide range of -facilities which are usually called online help. Online help has several, -partially conflicting goals: on the one, it should give the user answers -to the question "How can I do a certain task?", on the other hand it -should help the user exploring the application and finding features he -doesn't yet know about. It is important to recognize that this can only -be achieved by offering several levels of help: - - - - - -Tooltips are tiny labels that pop up over user interface elements when -the mouse remains there longer. They are especially important for tool- -bars, where icons are not always sufficient to explain the purpose of -a button. - - - -"What's this?" help is usually a longer and richer explanation of a widget -or a menu item. It is also more clunky to use: In dialogs, it can be invoked -in two ways: either by pressing -ShiftF1 or by clicking -on the question mark in the title bar (where the support of the latter depends -on the window manager). The mouse pointer then turns into an arrow with a -question mark, and the help window appears when a user interfact element has -been clicked. "What's this?" help for menu items is usually activated by a -button in the toolbar which contains an arrow and a question mark. - - - -The problem with this approach is that the user can't see whether a widget -provides help or not. When the user activates the question mark button and -doesn't get any help window when clicking on a user interface element, he -will get frustrated very quickly. - - - -The advantage of "What's this?" help windows as provided by Qt and KDE is that -they can contain rich text, -i.e. the may contain different fonts, bold and italic text and even images and tables. - - - -An example of "What's this?" help: - - - - - - - - - -Finally, every program should have a manual. A manual is normally viewed in -KHelpCenter by activating the -Help menu. That means, a complete additional application -pops up and diverts the user from his work. Consequently, consulting the -manual should only be necessary if other facilities like tooltips and what's -this help are not sufficient. Of course, a manual has the advantage that it -does not explain single, isolated aspects of the user interface. Instead, it -can explain aspects of the application in a greater context. Manuals for KDE -are written using the DocBook markup -language. - - - - - -From the programmer's point of view, Qt provides an easy to use API for online -help. To assign a tooltip to widget, use the -QToolTip class. - - - -QToolTip::add(w, i18n("This widget does something.")) - - - -If the menu bars and tool bars are created using the -action pattern, the string used as tooltip is derived from the first argument -of the TDEAction constructor: - - - -action = new TDEAction(i18n("&Delete"), "editdelete", - SHIFT+Key_Delete, actionCollection(), "del") - - - -Here it is also possible to assign a text which is shown in the status bar when the -respective menu item is highlighted: - - - -action->setStatusText(i18n("Deletes the marked file")) - - - -The API for "What's this?' help is very similar. In dialogs, use the following -code: - - - -QWhatsThis::add(w, i18n("<qt>This demonstrates <b>Qt</b>'s" - " rich text engine.<ul>" - "<li>Foo</li>" - "<li>Bar</li>" - "</ul></qt>")) - - - -For menu items, use - - - -action->setWhatsThis(i18n("Deletes the marked file")) - - - -The invocation of KHelpCenter is encapsulated in the -TDEApplication -class. In order to show the manual of your application, just use - - - -kapp->invokeHelp() - - - -This displays the first page with the table of contents. When you want to -display only a certain section of the manual, you can give an additional -argument to invokeHelp() determining the anchor which -the browser jumps to. - - - - - - - - - -Components and services - - -KDE services - - -What are KDE services? - - -The notion of a service is a central concept in KDE's -modular architecture. There is no strict technical implementation connected -with this term - services can be plugins in the form of shared libraries, -or they can be programs controlled via DCOP. -By claiming to be of a certain service type, a service -promises to implement certain APIs or features. In C++ terms, one can think -of a service type as an abstract class, and a service as an implementation -of that interface. - - - -The advantage of this separation is clear: An application utilizing a service -type does not have to know about possible implementations of it. It just uses -the APIs associated with the service type. In this way, the used service can be -changed without affecting the application. Also, the user can configure which -services he prefers for certain features. - - - -Some examples: - - - - - -The HTML rendering engine used in Konqueror is an -embedable component that implements the service types -KParts/ReadOnlyPart and Browser/View. - - -In TDevelop HEAD, most functionality is packaged in -plugins with the service type TDevelop/Part. At startup, -all services with this type are loaded, such that you can extend the IDE in a -very flexible way. - - -In the icon view, Konqueror displays - if enabled - -thumbnail pictures of images, HTML pages, PDF and text files. This ability can -be extended. If you want it to display preview pictures of your own data files -with some MIME type, you can implement a service with service type -ThumbCreator. - - - - - -Obviously, a service is not only characterized by the service types it -implements, but also by some properties. For example, a -ThumbCreator does not only claim to implement the C++ class with the type -ThumbCreator, it also has a list of MIME types it is -responsible for. Similarly, TDevelop parts have the programming language they -support as a property. When an application requests a service type, it can -also list constraints on the properties of the service. In the above example, -when TDevelop loads the plugins for a Java project, it asks only for the -plugins which have Java as the programming language property. For this -purpose, KDE contains a full-blown CORBA-like trader with -a complex query language. - - - - - - -Defining service types - - -New service types are added by installing a description of them into the -directory TDEDIR/share/servicetypes. In an automake -framework, this can be done with this Makefile.am -snippet: - - - -kde_servicetypesdir_DATA = tdeveloppart.desktop -EXTRA_DIST = $(kde_servicetypesdir_DATA) - - - -The definition tdeveloppart.desktop of a -TDevelop part looks as follows: - - - -[Desktop Entry] -Type=ServiceType -X-TDE-ServiceType=TDevelop/Part -Name=TDevelop Part - -[PropertyDef::X-TDevelop-Scope] -Type=QString - -[PropertyDef::X-TDevelop-ProgrammingLanguages] -Type=QStringList - -[PropertyDef::X-TDevelop-Args] -Type=QString - - - -In addition to the usual entries, this example demonstrates how you declare -that a service has some properties. Each property definition corresponds -to a group [PropertyDef::name] in the configuration file. In -this group, the Type entry declares the type of the property. -Possible types are everything that can be stored in a -QVariant. - - - - - - -Defining shared library services - - -Service definitions are stored in the directory -TDEDIR/share/services: - - - -kde_servicesdir_DATA = kdevdoxygen.desktop -EXTRA_DIST = $(kde_servicesdir_DATA) - - - -The content of the following example file -kdevdoxygen.desktop defines the -KDevDoxygen plugin with the service type -TDevelop/Part: - - - -[Desktop Entry] -Type=Service -Comment=Doxygen -Name=KDevDoxygen -ServiceTypes=TDevelop/Part -X-TDE-Library=libkdevdoxygen -X-TDevelop-ProgrammingLanguages=C,C++,Java -X-TDevelop-Scope=Project - - - -In addition to the usual declarations, an important entry is -X-TDE-Library. This contains the name of the libtool -library (without the .la extension). It also fixes -(with the prefix init_ prepended) the name of the exported -symbol in the library which returns an object factory. For the above example, -the library must contain the following function: - - - -extern "C" { - void *init_libkdevdoxygen() - { - return new DoxygenFactory; - } -}; - - - -The type of the factory class DoxygenFactory depends on -the specific service type the service implements. In our example of a TDevelop -plugin, the factory must be a KDevFactory (which -inherits KLibFactory). More common examples are -KParts::Factory -which is supposed to produce -KParts::ReadOnlyPart -objects or in most cases the generic -KLibFactory. - - - - - - -Using shared library services - - -In order to use a shared library service in an application, you need to obtain a -KService object -representing it. This is discussed in the -section about MIME types (and in a section about the -trader to be written :-) - - - -With the KService object at hand, you can very simply -load the library and get a pointer to its factory object: - - - -KService *service = ... -QString libName = QFile::encodeName(service->library()); -KLibFactory *factory = KLibLoader::self()->factory(libName); -if (!factory) { - QString name = service->name(); - QString errorMessage = KLibLoader::self()->lastErrorMessage(); - KMessageBox::error(0, i18n("There was an error loading service %1.\n" - "The diagnostics from libtool is:\n%2") - .arg(name).arg(errorMessage); -} - - - -From this point, the further proceeding depends again on the service type. For -generic plugins, you create objects with the method -KLibFactory::create(). -For KParts, you must cast the factory pointer to the more specific KParts::Factory and use -its create() method: - - - -if (factory->inherits("KParts::Factory")) { - KParts::Factory *partFactory = static_cast<KParts::Factory*>(factory); - QObject *obj = partFactory->createPart(parentWidget, widgetName, - parent, name, "KParts::ReadOnlyPart"); - ... -} else { - cout << "Service does not implement the right factory" << endl; -} - - - - - - -Defining DCOP services - - -A DCOP service is usually implemented as a program that is started up when it is -needed. It then goes into a loop and listens for DCOP connections. The program -may be an interactive one, but it may also run completely or for a part of its -lifetime as a daemon in the background without the user noticing it. An example -for such a daemon is tdeio_uiserver, which implements user interaction -such as progress dialog for the TDEIO library. The advantage of such a centralized -daemon in this context is that e.g. the download progress for several different -files can be shown in one window, even if those downloads were initiated from -different applications. - - - -A DCOP service is defined differently from a shared library service. Of course, -it doesn't specify a library, but instead an executable. Also, DCOP services -do not specify a ServiceType line, because usually they are started by their -name. As additional properties, it contains two lines: - - - -X-DCOP-ServiceType specifies the way the service is -started. The value Unique says that the service must not be -started more than once. This means, if you try to start this service (e.g. via - -TDEApplication::startServiceByName(), KDE looks whether it is already -registered with DCOP and uses the running service. If it is not registered yet, -KDE will start it up and wait until is registered. Thus, you can immediately -send DCOP calls to the service. In such a case, the service should be implemented -as a -KUniqueApplication. - - - -The value Multi for X-DCOP-ServiceType says that multiple -instances of the service can coexist, so every attempt to start the service -will create another process. As a last possibility the value None -can be used. In this case, a start of the service will not wait until it -is registered with DCOP. - - - -X-TDE-StartupNotify should normally be set to false. Otherwise, when -the program is started, the task bar will show a startup notification, or, depending -on the user's settings, the cursor will be changed. - - - -Here is the definition of tdeio_uiserver: - - - -[Desktop Entry] -Type=Service -Name=tdeio_uiserver -Exec=tdeio_uiserver -X-DCOP-ServiceType=Unique -X-TDE-StartupNotify=false - - - - - - -Using DCOP services - - -A DCOP service is started with one of several methods in the TDEApplication -class: - - - -DCOPClient *client = kapp->dcopClient(); -client->attach(); -if (!client->isApplicationRegistered("tdeio_uiserver")) { - QString error; - if (TDEApplication::startServiceByName("tdeio_uiserver", QStringList(), &error)) - cout << "Starting kioserver failed with message " << error << endl; -} -... -QByteArray data, replyData; -QCString replyType; -QDataStream arg(data, IO_WriteOnly); -arg << true; -if (!client->call("tdeio_uiserver", "UIServer", "setListMode(bool)", - data, replyType, replyData)) - cout << "Call to tdeio_uiserver failed" << endl; -... - - - -Note that the example of a DCOP call given here uses explicit marshalling -of arguments. Often you will want to use a stub generated by dcopidl2cpp -instead, because it is much simpler and less error prone. - - - -In the example given here, the service was started "by name", i.e. the -first argument to TDEApplication::startServiceByName() is -the name is appearing in the Name line of the desktop -file. An alternative is to use -TDEApplication::startServiceByDesktopName(), which takes -the file name of its desktop file as argument, i.e. in this case -"tdeio_uiserver.desktop". - - - -All these calls take a list of URLs as a second argument, which is given -to the service on the command line. The third argument is a pointer to a -QString. If starting the service fails, this argument -is set to a translated error message. - - - - - - - - -MIME types - - -What are MIME types? - - -MIME types are used to describe the content type of files or data -chunks. Originally they were introduced in order to allow sending around image -or sound files etc. by e-mail (MIME stands for "Multipurpose Internet Mail -Extensions"). Later this system was also used by web browsers to determine how -to present data sent by a web server to the user. For example, an HTML page -has a MIME type "text/html", a postscript file "application/postscript". In -KDE, this concept is used at a variety of places: - - - - - -In Konqueror's icon view, files are represented by -icons. Each MIME type has a certain associated icon shown here. - - - -When you click onto a file icon or a file name in -Konqueror, either the file is shown in an embedded -view, or an application associated with the file type is opened. - - - -When you drag and drop some data from one application to another (or -within the same application), the drop target may choose to accept only -certain data types. Furthermore, it will handle image data different -from textual data. - - - -Clipboard data has a MIME type. Traditionally, X programs only handle -pixmaps or texts, but with Qt, there are no restrictions on the data type. - - - - - -From the above examples, it is clear that MIME handling is a complex issue. -First, it is necessary to establish a mapping from file names to MIME types. -KDE goes one step further in allowing even file contents to be mapped to -MIME types, for cases in which the file name is not available. Second, it -is necessary to map MIME types to applications or libraries which can view -or edit a file with a certain type, or create a thumbnail picture for it. - - - -There is a variety of APIs to figure out the MIME type of data or files. In -general, there is a certain speed/reliability trade-off you have to make. You -can find out the type of a file by examining only its file name (i.e. in most -cases the file name extension). For example, a file -foo.jpg is normally "image/jpeg". In cases where the -extension is stripped off this is not safe, and you actually have to look at -the contents of the file. This is of course slower, in particular for files -that have to be downloaded via HTTP first. The content-based method is based -on the file TDEDIR/share/mimelnk/magic and therefore -difficult to extend. But in general, MIME type information can easily be made -available to the system by installing a .desktop file, and -it is efficiently and conveniently available through the KDE libraries. - - - - - - -Defining MIME types - - -Let us define a type "application/x-foo" for our new -foobar program. To this end, you have to write a -file foo.desktop and install it into -TDEDIR/share/mimelnk/application. (This is the usual -location, which may differ between distributions). This can be done by adding -this to the Makefile.am: - - - -mimedir = $(kde_mimedir)/application -mime_DATA = foo.desktop -EXTRA_DIST = $(mime_DATA) - - - -The file foo.desktop should look as follows: - - - -[Desktop Entry] -Type=MimeType -MimeType=application/x-foo -Icon=fooicon -Patterns=*.foo; -DefaultApp=foobar -Comment=Foo Data File -Comment[de]=Foo Datei - - - -The "Comment" entry is supposed to be translated. Since the -.desktop file specifies an icon, you should also install -an icon fooicon.png, which represents the file e.g. in -Konqueror. - - - -In the KDE libraries, such a type definition is mapped to an instance of the -class KMimeType. -Use this like in the following example: - - - -KMimeType::Ptr type = KMimeType::mimeType("application/x-foo"); -cout << "Type: " << type->name() < endl; -cout << "Icon: " << type->icon() < endl; -cout << "Comment: " << type->icon() < endl; -QStringList patterns = type->patterns(); -QStringList::ConstIterator it; -for (it = patterns.begin(); it != patterns.end(); ++it) - cout << "Pattern: " << (*it) << endl; - - - - - - -Determining the MIME type of data - - -The fast method for determining the type of a file is -KMimeType::findByURL(). This looks for the URL string and -in most cases determines the type from the extension. For certain protocols -(e.g. http, man, info), this mechanism is not used. For example, CGI scripts -on web servers written in Perl often have the extension -.pl, which would indicate a -"text/x-perl" type. However, we file delivered by the -server is the output of this script, which is normally HTML. For such a case, -KMimeType::findByURL() returns the MIME type -"application/octet-stream" (available through -KMimeType::defaultMimeType()), which indicates a failure -to find out the type. - - - -KMimeType::Ptr type = KMimeType::findByURL("/home/bernd/foobar.jpg"); -if (type->name() == KMimeType::defaultMimeType()) - cout << "Could not find out type" << endl; -else - cout << "Type: " << type->name() << endl; - - - -(this method has some more arguments, but these are undocumented, so simply -forget about them.) - - - -You may want to find out a MIME from the contents of file instead of -the file name. This is more reliable, but also slower, as it requires -reading a part of the file. This is done with the -KMimeMagic -class, which has different error handling: - - - -KMimeMagicResult *result = KMimeMagic::self()->findFileType("/home/bernd/foobar.jpg"); -if (!result || !result->isValid()) - cout << "Could not find out type" << endl; -else - cout << "Type: " << result->mimeType() << endl; - - - -As a variant of this function, you can also determine the type of a memory -chunk. This is e.g. used in Kate in order to find -out the highlighting mode: - - - -QByteArray array; -... -KMimeMagicResult *result = KMimeMagic::self()->findBufferType(array); -if (!result || !result->isValid()) - cout << "Could not find out type" << endl; -else - cout << "Type: " << result->mimeType() << endl; - - - -Of course, even KMimeMagic is only able to determine a file type from the -contents of a local file. For remote files, there is a further possibility: - - - -KURL url("http://developer.kde.org/favicon.ico"); -QString type = TDEIO::NetAccess::mimetype(url); -if (type == KMimeType::defaultMimeType()) - cout << "Could not find out type" << endl; -else - cout << "Type: " << type << endl; - - - -This starts a TDEIO job to download a part of the file and check this. -Note that this function is perhaps quite slow and blocks the program. Normally -you will only want to use this if KMimeType::findByURL() -has returned "application/octet-stream". - - - -On the other hand, if you do not want to block your application, you can also -explicitly start the TDEIO job and connect to some of its signals: - - - -void FooClass::findType() -{ - KURL url("http://developer.kde.org/favicon.ico"); - TDEIO::MimetypeJob *job = TDEIO::mimetype(url); - connect( job, SIGNAL(result(TDEIO::Job*)), - this, SLOT(mimeResult(TDEIO::Job*)) ); -} - -void FooClass::mimeResult(TDEIO::Job *job) -{ - if (job->error()) - job->showErrorDialog(); - else - cout << "MIME type: " << ((TDEIO::MimetypeJob *)job)->mimetype() << endl; -} - - - - - - -Mapping a MIME type to an application or service - - -When an application is installed, it installs a .desktop -file which contains a list of MIME types this application can load. Similarly, -components like KParts make this information available by their service -.desktop files. So in general, there are several programs -and components which can process a given MIME type. You can obtain such a list -from the class KServiceTypeProfile: - - - -KService::OfferList offers = KServiceTypeProfile::offers("text/html", "Application"); -KService::OfferList::ConstIterator it; -for (it = offers.begin(); it != offers.end(); ++it) { - KService::Ptr service = (*it); - cout << "Name: " << service->name() << endl; -} - - - -The return value of this function is a list of service offers. A -KServiceOffer object packages a KService::Ptr together -with a preference number. The list returned by -KServiceTypeProfile::offers() is ordered by the user's -preference. The user can change this by calling "keditfiletype -text/html" or choosing Edit File Type on -Konqueror's context menu on a HTML file. - - - -In the above example, an offer list of the applications supporting -text/html was requested. This will - among others - contain -HTML editors like Quanta Plus. You can also replace -the second argument "Application" by -"KParts::ReadOnlyPart". In that case, you get a list of -embedable components for presenting HTML content, for example TDEHTML. - - - -In most cases, you are not interested in the list of all service offers -for a combination of MIME type and service type. There is a convenience -function which gives you only the service offer with the highest preference: - - - -KService::Ptr offer = KServiceTypeProfile::preferredService("text/html", "Application"); -if (offer) - cout << "Name: " << service->name() << endl; -else - cout << "No appropriate service found" << endl; - - - -For even more complex queries, there is a full-blown CORBA-like -trader. - - - -In order to run an application service with some URLs, use -KRun: - - - -KURL::List urlList; -urlList << "http://www.ietf.org/rfc/rfc1341.txt?number=1341"; -urlList << "http://www.ietf.org/rfc/rfc2046.txt?number=2046"; -KRun::run(offer.service(), urlList); - - - - - - -Miscellaneous - - -In this section, we want to list some APIs which are loosely related -to the previous discussion. - - - -Getting an icon for a URL. This looks for the type of the URL -and returns the associated icon. - - - -KURL url("ftp://ftp.kde.org/pub/incoming/wibble.c"); -QString icon = KMimeType::iconForURL(url); - - - -Running a URL. This looks for the type of the URL and starts the -user's preferred program associated with this type. - - - -KURL url("http://dot.kde.org"); -new KRun(url); - - - - - - - - -Network transparency - - -Introduction - - -In the age of the world wide web, it is of essential importance that desktop -applications can access resources over the internet: they should be able to -download files from a web server, write files to an ftp server or read mails -from a web server. Often, the ability to access files regardless of their -location is called network transparency. - - - -In the past, different approaches to this goals were implemented. The old NFS -file system is an attempt to implement network transparency on the level of -the POSIX API. While this approach works quite well in local, closely coupled -networks, it does not scale for resources to which access is unreliable and -possibly slow. Here, asynchronicity is important. While -you are waiting for your web browser to download a page, the user interface -should not block. Also, the page rendering should not begin when the page is -completely available, but should updated regularly as data comes in. - - - -In the KDE libraries, network transparency is implemented in the TDEIO API. The -central concept of this architecture is an IO job. A job -may copy, or delete files or similar things. Once a job is started, it works -in the background and does not block the application. Any communication from -the job back to the application - like delivering data or progress information -- is done integrated with the Qt event loop. - - - -Background operation is achieved by starting ioslaves to -perform certain tasks. ioslaves are started as separate processes and are -communicated with through UNIX domain sockets. In this way, no multi-threading -is necessary and unstable slaves can not crash the application that uses them. - - - -File locations are expressed by the widely used URLs. But in KDE, URLs do not -only expand the range of addressable files beyond the local file system. It -also goes in the opposite direction - e.g. you can browse into tar archives. -This is achieved by nesting URLs. For example, a file in a tar archive on -a http server could have the URL - - - -http://www-com.physik.hu-berlin.de/~bernd/article.tgz#tar:/paper.tex - - - - - - -Using TDEIO - - -In most cases, jobs are created by calling functions in the TDEIO namespace. -These functions take one or two URLs as arguments, and possible other -necessary parameters. When the job is finished, it emits the signal -result(TDEIO::Job*). After this signal has been emitted, the job -deletes itself. Thus, a typical use case will look like this: - - - -void FooClass::makeDirectory() -{ - SimpleJob *job = TDEIO::mkdir(KURL("file:/home/bernd/tdeiodir")); - connect( job, SIGNAL(result(TDEIO::Job*)), - this, SLOT(mkdirResult(TDEIO::Job*)) ); -} - -void FooClass::mkdirResult(TDEIO::Job *job) -{ - if (job->error()) - job->showErrorDialog(); - else - cout << "mkdir went fine" << endl; -} - - - -Depending on the type of the job, you may connect also to other -signals. - - - -Here is an overview over the possible functions: - - - - -TDEIO::mkdir(const KURL &url, int permission) - -Creates a directory, optionally with certain permissions. - - - -TDEIO::rmdir(const KURL &url) - -Removes a directory. - - - -TDEIO::chmod(const KURL &url, int permissions) - -Changes the permissions of a file. - - - -TDEIO::rename(const KURL &src, const KURL &dest, - bool overwrite) - -Renames a file. - - - -TDEIO::symlink(const QString &target, const KURL &dest, - bool overwrite, bool showProgressInfo) - -Creates a symbolic link. - - - -TDEIO::stat(const KURL &url, bool showProgressInfo) - -Finds out certain information about the file, such as size, modification -time and permissions. The information can be obtained from -TDEIO::StatJob::statResult() after the job has finished. - - - -TDEIO::get(const KURL &url, bool reload, bool showProgressInfo) - -Transfers data from a URL. - - - -TDEIO::put(const KURL &url, int permissions, bool overwrite, - bool resume, bool showProgressInfo) - -Transfers data to a URL. - - - -TDEIO::http_post(const KURL &url, const QByteArray &data, - bool showProgressInfo) -Posts data. Special for HTTP. - - - -TDEIO::mimetype(const KURL &url, bool showProgressInfo) - -Tries to find the MIME type of the URL. The type can be obtained from -TDEIO::MimetypeJob::mimetype() after the job has finished. - - - -TDEIO::file_copy(const KURL &src, const KURL &dest, int permissions, - bool overwrite, bool resume, bool showProgressInfo) - -Copies a single file. - - - -TDEIO::file_move(const KURL &src, const KURL &dest, int permissions, - bool overwrite, bool resume, bool showProgressInfo) - -Renames or moves a single file. - - - -TDEIO::file_delete(const KURL &url, bool showProgressInfo) - -Deletes a single file. - - - -TDEIO::listDir(const KURL &url, bool showProgressInfo) - -Lists the contents of a directory. Each time some new entries are known, the -signal TDEIO::ListJob::entries() is emitted. - - - -TDEIO::listRecursive(const KURL &url, bool showProgressInfo) - -Similar to the listDir() function, but this one is recursive. - - - -TDEIO::copy(const KURL &src, const KURL &dest, bool showProgressInfo) - -Copies a file or directory. Directories are copied recursively. - - - -TDEIO::move(const KURL &src, const KURL &dest, bool showProgressInfo) - -Moves or renames a file or directory. - - - -TDEIO::del(const KURL &src, bool shred, bool showProgressInfo) - -Deletes a file or directory. - - - - - - - - - -Directory entries - - -Both the TDEIO::stat() and TDEIO::listDir() jobs return their results as a type -UDSEntry, UDSEntryList resp. The latter is defined as QValueList<UDSEntry>. -The acronym UDS stands for "Universal directory service". The principle behind -it is that the a directory entry only carries the information which an ioslave -can provide, not more. For example, the http slave does not provide any -information about access permissions or file owners. -Instead, a UDSEntry is a list of UDSAtoms. Each atom provides a specific piece -of information. It consists of a type stored in m_uds and either an integer -value in m_long or a string value in m_str, depending on the type. - - - -The following types are currently defined: - - - - - -UDS_SIZE (integer) - Size of the file. - - - -UDS_USER (string) - User owning the file. - - - -UDS_GROUP (string) - Group owning the file. - - - -UDS_NAME (string) - File name. - - - -UDS_ACCESS (integer) - Permission rights of the file, as e.g. stored -by the libc function stat() in the st_mode field. - - - -UDS_FILE_TYPE (integer) - The file type, as e.g. stored by stat() in the -st_mode field. Therefore you can use the usual libc macros like S_ISDIR to -test this value. Note that the data provided by ioslaves corresponds to -stat(), not lstat(), i.e. in case of symbolic links, the file type here is -the type of the file pointed to by the link, not the link itself. - - - -UDS_LINK_DEST (string) - In case of a symbolic link, the name of the file -pointed to. - - - -UDS_MODIFICATION_TIME (integer) - The time (as in the type time_t) when the -file was last modified, as e.g. stored by stat() in the st_mtime field. - - - -UDS_ACCESS_TIME (integer) - The time when the file was last accessed, as -e.g. stored by stat() in the st_atime field. - - - -UDS_CREATION_TIME (integer) - The time when the file was created, as e.g. -stored by stat() in the st_ctime field. - - - -UDS_URL (string) - Provides a URL of a file, if it is not simply the -the concatenation of directory URL and file name. - - - -UDS_MIME_TYPE (string) - MIME type of the file - - - -UDS_GUESSED_MIME_TYPE (string) - MIME type of the file as guessed by the -slave. The difference to the previous type is that the one provided here -should not be taken as reliable (because determining it in a reliable way -would be too expensive). For example, the KRun class explicitly checks the -MIME type if it does not have reliable information. - - - - - -Although the way of storing information about files in a -UDSEntry is flexible and practical from the ioslave -point of view, it is a mess to use for the application programmer. For -example, in order to find out the MIME type of the file, you have to iterate -over all atoms and test whether m_uds is -UDS_MIME_TYPE. Fortunately, there is an API which is a lot -easier to use: the class KFileItem. - - - - - - -Synchronous usage - - -Often, the asynchronous API of TDEIO is too complex to use and therefore -implementing full asynchronicity is not a priority. For example, in a program -that can only handle one document file at a time, there is little that can be -done while the program is downloading a file anyway. For these simple cases, -there is a mucher simpler API in the form of a set of static functions in -TDEIO::NetAccess. For example, in order to copy a file, use - - - -KURL source, target; -source = ...; -target = ... -TDEIO::NetAccess::copy(source, target); - - - -The function will return after the complete copying process has finished. Still, -this method provides a progress dialog, and it makes sure that the application -processes repaint events. - - - -A particularly interesting combination of functions is -download() in combination with -removeTempFile(). The former downloads a file from given -URL and stores it in a temporary file with a unique name. The name is stored -in the second argument. If the URL is local, the file is -not downloaded, and instead the second argument is set to the local file -name. The function removeTempFile() deletes the file -given by its argument if the file is the result of a former download. If that -is not the case, it does nothing. Thus, a very easy to use way of loading -files regardless of their location is the following code snippet: - - - -KURL url; -url = ...; -QString tempFile; -if (TDEIO::NetAccess::download(url, tempFile) { - // load the file with the name tempFile - TDEIO::NetAccess::removeTempFile(tempFile); -} - - - - - - -Meta data - - -As can be seen above, the interface to IO jobs is quite abstract and does not -consider any exchange of information between application and IO slave that -is protocol specific. This is not always appropriate. For example, you may give -certain parameters to the HTTP slave to control its caching behavior or -send a bunch of cookies with the request. For this need, the concept of meta -data has been introduced. When a job is created, you can configure it by adding -meta data to it. Each item of meta data consists of a key/value pair. For -example, in order to prevent the HTTP slave from loading a web page from its -cache, you can use: - - - -void FooClass::reloadPage() -{ - KURL url("http://www.kdevelop.org/index.html"); - TDEIO::TransferJob *job = TDEIO::get(url, true, false); - job->addMetaData("cache", "reload"); - ... -} - - - -The same technique is used in the other direction, i.e. for communication from -the slave to the application. The method -Job::queryMetaData() asks for the value of the certain -key delivered by the slave. For the HTTP slave, one such example is the key -"modified", which contains a (stringified representation of) -the date when the web page was last modified. An example how you can use this -is the following: - - - -void FooClass::printModifiedDate() -{ - KURL url("http://developer.kde.org/documentation/kde2arch/index.html"); - TDEIO::TransferJob *job = TDEIO::get(url, true, false); - connect( job, SIGNAL(result(TDEIO::Job*)), - this, SLOT(transferResult(TDEIO::Job*)) ); -} - -void FooClass::transferResult(TDEIO::Job *job) -{ - QString mimetype; - if (job->error()) - job->showErrorDialog(); - else { - TDEIO::TransferJob *transferJob = (TDEIO::TransferJob*) job; - QString modified = transferJob->queryMetaData("modified"); - cout << "Last modified: " << modified << endl; -} - - - - - - -Scheduling - - -When using the TDEIO API, you usually do not have to cope with the details of -starting IO slaves and communicating with them. The normal use case is to -start a job and with some parameters and handle the signals the jobs emits. - - - -Behind the curtains, the scenario is a lot more complicated. When you create a -job, it is put in a queue. When the application goes back to the event loop, -TDEIO allocates slave processes for the jobs in the queue. For the first jobs -started, this is trivial: an IO slave for the appropriate protocol is started. -However, after the job (like a download from an http server) has finished, it -is not immediately killed. Instead, it is put in a pool of idle slaves and -killed after a certain time of inactivity (current 3 minutes). If a new request -for the same protocol and host arrives, the slave is reused. The obvious -advantage is that for a series of jobs for the same host, the cost for creating -new processes and possibly going through an authentication handshake is saved. - - - -Of course, reusing is only possible when the existing slave has already finished -its previous job. when a new request arrives while an existing slave process is -still running, a new process must be started and used. In the API usage in the -examples above, there are no limitation for creating new slave processes: if you -start a consecutive series of downloads for 20 different files, then TDEIO will -start 20 slave processes. This scheme of assigning slaves to jobs is called -direct. It not always the most appropriate scheme, as it -may need much memory and put a high load on both the client and server machines. - - - -So there is a different way. You can schedule jobs. If -you do this, only a limited number (currently 3) of slave processes for a -protocol will be created. If you create more jobs than that, they are put in a -queue and are processed when a slave process becomes idle. This is done as -follows: - - - -KURL url("http://developer.kde.org/documentation/kde2arch/index.html"); -TDEIO::TransferJob *job = TDEIO::get(url, true, false); -TDEIO::Scheduler::scheduleJob(job); - - - -A third possibility is connection oriented. For example, -for the IMAP slave, it does not make any sense to start multiple processes for -the same server. Only one IMAP connection at a time should be enforced. In -this case, the application must explicitly deal with the notion of a slave. It -has to deallocate a slave for a certain connection and then assign all jobs -which should go through the same connection to the same slave. This can again -be easily achieved by using the TDEIO::Scheduler: - - - -KURL baseUrl("imap://bernd@albert.physik.hu-berlin.de"); -TDEIO::Slave *slave = TDEIO::Scheduler::getConnectedSlave(baseUrl); - -TDEIO::TransferJob *job1 = TDEIO::get(KURL(baseUrl, "/INBOX;UID=79374")); -TDEIO::Scheduler::assignJobToSlave(slave, job1); - -TDEIO::TransferJob *job2 = TDEIO::get(KURL(baseUrl, "/INBOX;UID=86793")); -TDEIO::Scheduler::assignJobToSlave(slave, job2); - -... - -TDEIO::Scheduler::disconnectSlave(slave); - - - -You may only disconnect the slave after all jobs assigned to it are guaranteed -to be finished. - - - - - - -Defining an ioslave - - -In the following we discuss how you can add a new ioslave to the system. -In analogy to services, new ioslaves are advertised to the system by -installing a little configuration file. The following Makefile.am -snippet installs the ftp protocol: - - - -protocoldir = $(kde_servicesdir) -protocol_DATA = ftp.protocol -EXTRA_DIST = $(mime_DATA) - - - -The contents of the file ftp.protocol is as follows: - - - -[Protocol] -exec=tdeio_ftp -protocol=ftp -input=none -output=filesystem -listing=Name,Type,Size,Date,Access,Owner,Group,Link, -reading=true -writing=true -makedir=true -deleting=true -Icon=ftp - - - -The "protocol" entry defines for which protocol this slave -is responsible. "exec" is (in contrast what you would -expect naively) the name of the library that implements the slave. When the -slave is supposed to start, the "tdeinit" executable is -started which in turn loads this library into its address space. So in -practice, you can think of the running slave as a separate process although it -is implemented as library. The advantage of this mechanism is that it saves a -lot of memory and reduces the time needed by the runtime linker. - - - -The "input" and "output" lines are not used currently. - - - -The remaining lines in the .protocol file define which -abilities the slave has. In general, the features a slave must implement are -much simpler than the features the TDEIO API provides for the application. The -reason for this is that complex jobs are scheduled to a couple of subjobs. For -example, in order to list a directory recursively, one job will be started for -the toplevel directory. Then for each subdirectory reported back, new subjobs -are started. A scheduler in TDEIO makes sure that not too many jobs are active -at the same time. Similarly, in order to copy a file within a protocol that -does not support copying directly (like the ftp: protocol), -TDEIO can read the source file and then write the data to the destination -file. For this to work, the .protocol must advertise the -actions its slave supports. - - - -Since slaves are loaded as shared libraries, but constitute standalone programs, -their code framework looks a bit different from normal shared library plugins. -The function which is called to start the slave is called -kdemain(). This function does some initializations and -then goes into an event loop and waits for requests by the application using -it. This looks as follows: - - - -extern "C" { int kdemain(int argc, char **argv); } - -int kdemain(int argc, char **argv) -{ - TDELocale::setMainCatalogue("tdelibs"); - TDEInstance instance("tdeio_ftp"); - (void) TDEGlobal::locale(); - - if (argc != 4) { - fprintf(stderr, "Usage: tdeio_ftp protocol " - "domain-socket1 domain-socket2\n"); - exit(-1); - } - - FtpSlave slave(argv[2], argv[3]); - slave.dispatchLoop(); - return 0; -} - - - - - - -Implementing an ioslave - - -Slaves are implemented as subclasses of TDEIO::SlaveBase -(FtpSlave in the above example). Thus, the actions listed in the -.protocol correspond to certain virtual functions in -TDEIO::SlaveBase the slave implementation must -reimplement. Here is a list of possible actions and the corresponding virtual -functions: - - - - -reading - Reads data from a URL -void get(const KURL &url) - -writing - Writes data to a URL and create the file if it does not exist yet. -void put(const KURL &url, int permissions, bool overwrite, bool resume) - -moving - Renames a file. -void rename(const KURL &src, const KURL &dest, bool overwrite) - -deleting - Deletes a file or directory. -void del(const KURL &url, bool isFile) - -listing - Lists the contents of a directory. -void listDir(const KURL &url) - -makedir - Creates a directory. -void mkdir(const KURL &url, int permissions) - - - - -Additionally, there are reimplementable functions not listed in the .protocol -file. For these operations, TDEIO automatically determines whether they are supported -or not (i.e. the default implementation returns an error). - - - - -Delivers information about a file, similar to the C function stat(). -void stat(const KURL &url) - -Changes the access permissions of a file. -void chmod(const KURL &url, int permissions) - -Determines the MIME type of a file. -void mimetype(const KURL &url) - -Copies a file. -copy(const KURL &url, const KURL &dest, int permissions, bool overwrite) - -Creates a symbolic link. -void symlink(const QString &target, const KURL &dest, bool overwrite) - - - - -All these implementation should end with one of two calls: If the operation -was successful, they should call finished(). If an error has occurred, -error() should be called with an error code as first argument and a -string in the second. Possible error codes are listed as enum -TDEIO::Error. The second argument is usually the URL in -question. It is used e.g. in TDEIO::Job::showErrorDialog() -in order to parameterize the human-readable error message. - - - -For slaves that correspond to network protocols, it might be interesting to -reimplement the method SlaveBase::setHost(). This is -called to tell the slave process about the host and port, and the user name -and password to log in. In general, meta data set by the application can be -queried by SlaveBase::metaData(). You can check for the -existence of meta data of a certain key with -SlaveBase::hasMetaData(). - - - - - - -Communicating back to the application - - -Various actions implemented in a slave need some way to communicate data back -to the application using the slave process: - - - - - -get() sends blocks of data. This is done with -data(), which takes a QByteArray -as argument. Of course, you do not need to send all data at once. If you send -a large file, call data() with smaller data blocks, so -the application can process them. Call finished() when -the transfer is finished. - - - -listDir() reports information about the entries of a -directory. For this purpose, call listEntries() with a -TDEIO::UDSEntryList as argument. Analogously to -data(), you can call this several times. When you are -finished, call listEntry() with the second argument set -to true. You may also call totalSize() to report the -total number of directory entries, if known. - - - -stat() reports information about a file like size, MIME -type, etc. Such information is packaged in a -TDEIO::UDSEntry, which will be discussed below. Use -statEntry() to send such an item to the application. - - - -mimetype() calls mimeType() with a -string argument. - - - -get() and copy() may want to provide -progress information. This is done with the methods -totalSize(), processedSize(), -speed(). The total size and processed size are reported -as bytes, the speed as bytes per second. - - - -You can send arbitrary key/value pairs of meta data with -setMetaData(). - - - - - - - - -Interacting with the user - - -Sometimes a slave has to interact with the user. Examples include informational -messages, authentication dialogs and confirmation dialogs when a file is about -to be overwritten. - - - - - -infoMessage() - This is for informational feedback, such -as the message "Retrieving data from <host>" from the http slave, which -is often displayed in the status bar of the program. On the application side, -this method corresponds to the signal -TDEIO::Job::infoMessage(). - - - -warning() - Displays a warning in a message box with -KMessageBox::information(). If a message box is still -open from a former call of warning() from the same slave process, nothing -happens. - - - -messageBox() - This is richer than the previous -method. It allows to open a message box with text and caption and some -buttons. See the enum SlaveBase::MessageBoxType for reference. - - - -openPassDlg() - Opens a dialog for the input of user name -and password. - - - - - - - - - - - - - -Licensing - -&underFDL; -&underGPL; - - - - diff --git a/doc/kdearch/joinbevel.png b/doc/kdearch/joinbevel.png deleted file mode 100644 index 584b6bd4..00000000 Binary files a/doc/kdearch/joinbevel.png and /dev/null differ diff --git a/doc/kdearch/joinmiter.png b/doc/kdearch/joinmiter.png deleted file mode 100644 index e5d94b13..00000000 Binary files a/doc/kdearch/joinmiter.png and /dev/null differ diff --git a/doc/kdearch/joinround.png b/doc/kdearch/joinround.png deleted file mode 100644 index 9a8bbe93..00000000 Binary files a/doc/kdearch/joinround.png and /dev/null differ diff --git a/doc/kdearch/konqi-mirrored.png b/doc/kdearch/konqi-mirrored.png deleted file mode 100644 index 5145c0ee..00000000 Binary files a/doc/kdearch/konqi-mirrored.png and /dev/null differ diff --git a/doc/kdearch/konqi-normal.png b/doc/kdearch/konqi-normal.png deleted file mode 100644 index c16e1475..00000000 Binary files a/doc/kdearch/konqi-normal.png and /dev/null differ diff --git a/doc/kdearch/konqi-rotated.png b/doc/kdearch/konqi-rotated.png deleted file mode 100644 index 157e82dd..00000000 Binary files a/doc/kdearch/konqi-rotated.png and /dev/null differ diff --git a/doc/kdearch/konqi-sheared.png b/doc/kdearch/konqi-sheared.png deleted file mode 100644 index ee645f87..00000000 Binary files a/doc/kdearch/konqi-sheared.png and /dev/null differ diff --git a/doc/kdearch/kview-menu.png b/doc/kdearch/kview-menu.png deleted file mode 100644 index 0e57e721..00000000 Binary files a/doc/kdearch/kview-menu.png and /dev/null differ diff --git a/doc/kdearch/opengl.png b/doc/kdearch/opengl.png deleted file mode 100644 index 2489777d..00000000 Binary files a/doc/kdearch/opengl.png and /dev/null differ diff --git a/doc/kdearch/penstyles.png b/doc/kdearch/penstyles.png deleted file mode 100644 index 7e976bcd..00000000 Binary files a/doc/kdearch/penstyles.png and /dev/null differ diff --git a/doc/kdearch/whatsthis.png b/doc/kdearch/whatsthis.png deleted file mode 100644 index 4bdba093..00000000 Binary files a/doc/kdearch/whatsthis.png and /dev/null differ diff --git a/doc/kdevdesigner/CMakeLists.txt b/doc/kdevdesigner/CMakeLists.txt deleted file mode 100644 index db314d97..00000000 --- a/doc/kdevdesigner/CMakeLists.txt +++ /dev/null @@ -1,9 +0,0 @@ -################################################# -# -# Improvements and feedback are welcome -# -# This file is released under GPL >= 2 -# -################################################# - -tde_create_handbook( DESTINATION kdevdesigner ) diff --git a/doc/kdevdesigner/Makefile.am b/doc/kdevdesigner/Makefile.am deleted file mode 100644 index 41691557..00000000 --- a/doc/kdevdesigner/Makefile.am +++ /dev/null @@ -1,3 +0,0 @@ -KDE_LANG = en -KDE_DOCS = AUTO - diff --git a/doc/kdevdesigner/index.docbook b/doc/kdevdesigner/index.docbook deleted file mode 100644 index c903aa65..00000000 --- a/doc/kdevdesigner/index.docbook +++ /dev/null @@ -1,65 +0,0 @@ - -KDevDesigner"> - - - -]> - - - - - -
-The &kdevdesigner; Handbook - - -The &kdevdesigner; Handbook - - -&tde-authors; - - - -&tde-release-version; -Reviewed: &tde-release-date; - - -&tde-copyright-date; -&tde-team; - - - - - - -&kdevdesigner; is a GUI designer environment for &tde;. - - - - -TDE - - - - - -We Apologize -No documentation has yet been written for &kdevdesigner;. - -If you need help, please check The &tde; -web site, submit questions to the -&tde; mail lists, or file a bug report at the -&tde; bug tracker. - -If you are interested in helping, please consider writing the help file. -Submitting a basic text file is acceptable as the &tde-team; will convert the text. - -Thank you for helping and thank you for your patience. - -&underFDL; - - - -&documentation.index; -
diff --git a/doc/platform/Mainpage.dox b/doc/platform/Mainpage.dox index 29f6deb0..ae377ddf 100644 --- a/doc/platform/Mainpage.dox +++ b/doc/platform/Mainpage.dox @@ -81,11 +81,11 @@ KDevelop Technotes. \section langapi Programming Language Support API -- Language Support Interfaces Library - (classes)\n +- Language Support Interfaces Library + (classes)\n Interfaces for KDevelop language support facilities. -- Debugger Support Library - (classes)\n +- Debugger Support Library + (classes)\n Classes to implement debugger support for a programming language. . @@ -110,8 +110,8 @@ KDevelop Technotes. \section shellapi Shell API -- Generic Shell - (classes)\n +- Generic Shell + (classes)\n The Shell - a profile-based implementation of TDevelop plugin architecture. - Shell Profiles Library (classes)\n diff --git a/doc/std/CMakeLists.txt b/doc/std/CMakeLists.txt index 3c034ee5..edb0d2a8 100644 --- a/doc/std/CMakeLists.txt +++ b/doc/std/CMakeLists.txt @@ -11,6 +11,6 @@ install( FILES - kdev3api.toc - DESTINATION ${DATA_INSTALL_DIR}/kdevdocumentation/tocs + tdev3api.toc + DESTINATION ${DATA_INSTALL_DIR}/tdevdocumentation/tocs ) diff --git a/doc/std/Makefile.am b/doc/std/Makefile.am index 07f12cde..7b636e47 100644 --- a/doc/std/Makefile.am +++ b/doc/std/Makefile.am @@ -1,5 +1,5 @@ -tocdir = ${kde_datadir}/kdevdocumentation/tocs -toc_DATA = kdev3api.toc +tocdir = ${kde_datadir}/tdevdocumentation/tocs +toc_DATA = tdev3api.toc #indexdir = ${kde_datadir}/devdoctreeview/indices #index_DATA = diff --git a/doc/std/kdev3api.toc b/doc/std/kdev3api.toc deleted file mode 100644 index ef1c82dc..00000000 --- a/doc/std/kdev3api.toc +++ /dev/null @@ -1,45 +0,0 @@ - - -KDevelop API Documentation - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/doc/std/tdev3api.toc b/doc/std/tdev3api.toc new file mode 100644 index 00000000..ef1c82dc --- /dev/null +++ b/doc/std/tdev3api.toc @@ -0,0 +1,45 @@ + + +KDevelop API Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/tde_app_devel/CMakeLists.txt b/doc/tde_app_devel/CMakeLists.txt new file mode 100644 index 00000000..83e96ce9 --- /dev/null +++ b/doc/tde_app_devel/CMakeLists.txt @@ -0,0 +1,12 @@ +################################################# +# +# (C) 2010-2011 Serghei Amelian +# serghei (DOT) amelian (AT) gmail.com +# +# Improvements and feedback are welcome +# +# This file is released under GPL >= 2 +# +################################################# + +tde_create_handbook( DESTINATION tde_app_devel ) diff --git a/doc/tde_app_devel/Makefile.am b/doc/tde_app_devel/Makefile.am new file mode 100644 index 00000000..171f575c --- /dev/null +++ b/doc/tde_app_devel/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = AUTO diff --git a/doc/tde_app_devel/appwizard.png b/doc/tde_app_devel/appwizard.png new file mode 100644 index 00000000..adbadb35 Binary files /dev/null and b/doc/tde_app_devel/appwizard.png differ diff --git a/doc/tde_app_devel/index.docbook b/doc/tde_app_devel/index.docbook new file mode 100644 index 00000000..e212e4e6 --- /dev/null +++ b/doc/tde_app_devel/index.docbook @@ -0,0 +1,1549 @@ + +TDevelop"> + + + +]> + + + + +The &tdevelop; Programming Handbook + +2002-12-05 +2.0 + + + +Ralf +Nolden +
Ralf.Nolden@post.rwth-aachen.de
 + + +Caleb +Tennis +
caleb@aei-tech.com
 + + + + +1999 +Ralf Nolden + + +2002 +Caleb Tennis + + + + +&FDLNotice; + + +The User Guide to C++ Application Design for the Trinity Desktop Environment (TDE) with +the &tdevelop; IDE + + + +KDE +TDevelop +IDE +development +programming + + + + + +Introduction + +As Unix Systems are becoming more and more popular to even beginners working with computer machines +due to its advantages in regards of stability and functionality, most are somehow disappointed, because +those applications don't have a consistent look and each one behaves different from another. With KDE, +developers have an almost perfect way to create first-class applications for Unix desktop systems to get +a wider user community by the mere quality their applications have to offer. Therefore, KDE becomes more +and more popular as a base for programming design, and developers want to take advantage of the +possibilities that the system has to offer. + + + +What you should know already + +For making the best use of this programming handbook, we assume that you already know about the +C++ programming language; if not, you should make yourself familiar with that first. Information about +C++ is available through various sources either in printed form at your local bookstore or by tutorials +found on the Internet. Knowledge about the design of Graphical User Interfaces is not required, as this +handbook tries to cover the application design for KDE programs, which also includes an introduction into +the Qt toolkit as well as the KDE libraries and the design of User Interfaces. Also, you should have made +yourself comfortable with &tdevelop; by reading The User Manual to &tdevelop;, which contains a descriptive +review of the functionality provided by the IDE. + + + + +About this Handbook + +This handbook has been written to give developers an introduction into KDE application development by +using the TDevelop Integrated Development Environment. + + +The following chapters therefore give an introduction on how to create projects, explains the sourcecode +already generated and shows how to extend the given sources on various topics such as toolbars, menu bars +and view areas. + + +Then the dialogeditor is discussed in detail, explaining how widgets are created and covers widget +properties settings in detail for all provided widgets. + + +Finally, you will learn about several topics that will complete your knowledge in regards of project design +and helps you work out additional issues besides coding such as adding API documentation and extending +online-manuals. + + +In the next chapter + +We'll take a look at the Qt and KDE libraries, showing basic concepts and why things are the way they are. +Also, we will discuss how to create the tutorial applications provided with the Qt toolkit by using +tdevelop;, so beginners can already see first results with a few steps, and thereby will learn how to make +use of some of &tdevelop;'s best features. + + + + +In the following chapters + +You will learn how to: + +create an application with the KAppWizard +What the project skeleton already provides +What the code already create means +How to create your own views +How to extend your application's functionality by dialog, menu bars, and toolbars +How to make your application user friendly by providing help functions +How to write online documentation + + + + + + + +Additional Information + +Additional information about Qt/KDE programming is available by various sources: + +Programming with Qt by Matthias Kalle Dalheimer +The User Manual to TDevelop, provided with the TDevelop IDE +The Online Reference to the Qt library +The KDE Developer web site + + + +Additionally, you should look for help by subscribing to the various mailing lists, whose addresses +are available on the mentioned web sites, and on the Usenet newsgroups dedicated to users of KDE and +Unix Systems as well as about the C and C++ programming language. + + +For obtaining help about the TDevelop IDE, you should send requests to our mailinglist at +kdevelop@kdevelop.org. Mind that the TDevelop team is dedicated to provide the means to enable you to +program applications and therefore is not intended as a technical support team in cases where the +applications you're developing don't work due to implementation errors or misconfigurations of your +operating system. By this, we ask all users to take advantage of the mailinglist in any case you're running +into problems with the use of the IDE itself, as well as for bug reports and suggestions for improving the +functionality of the development environment. + + + + + + +The KDE and Qt Libraries + +The Norwegian company TrollTech (http://www.trolltech.com) +provides a so-called GUI toolkit, named Qt. GUI means "Graphical User Interface", and therefore, Qt-based +applications represent themselves with buttons, windows etc, allowing user input by visualizing the functions +an application provides. Such a toolkit is needed for developing graphical applications that run on the X-Window +interface on Unix Systems, because X does not contain a pre-defined user interface itself. Although other +toolkits are also available to create User Interfaces, Qt offers some technical advantages that make +application design very easy. Additionally, the Qt toolkit is also available for Microsoft Windows systems, +which allows developers to provide their applications for both platforms. + + +The KDE Team (http://www.kde.org) joined together with the goal +to make using Unix Systems more friendly, and decided to use the Qt toolkit for the development of a window +manager on X-Windows, plus a variety of tools included with the KDE packages. The K Desktop Environment +therefore contains the window manager kwm, the file manager kfm and the launch panel kpanel as the main +components plus a variety of first-class utilities and applications. After KDE was out, a lot of developers +turned their eyes towards the new environment and what it has to offer them. The KDE libraries are providing +essential methods and classes that make all applications designed with them look similar and consistent, +so the user has the great advantage that he only has to get accustomed with an application's specific +usage, not with handling dialogs or buttons. Also, KDE programs integrate themselves into the desktop and +are able to interact with the file manager via drag'n drop, offer session management and many more, if all +features offered by the KDE libraries are used. Both, the Qt toolkit and the KDE libraries, are implemented +in the C++ programming language; therefore applications that make use of these libraries are also mostly +written in C++. In the following chapter, we'll make a short trip through the libraries to see what already +is provided and how Qt and TDE applications are created in general. + + +Both, the Qt toolkit and the KDE libraries, are implemented in the C++ programming language; +therefore applications that make use of these libraries are also mostly written in C++. In the following +chapter, we'll make a short trip through the libraries to see what already is provided and how Qt and KDE +applications are created in general. + + + +The Qt GUI Toolkit + +As said, the Qt library is a toolkit that offers graphical elements that are used for creating GUI +applications and are needed for X-Window programming. Additionally, the toolkit offers: + +A complete set of classes and methods ready to use even for non-graphical programming issues +A good solution towards user interaction by virtual methods and the signal/slot mechanism +A set of predefined GUI-elements, called "widgets", that can be used easily for creating the visible elements +Additional completely pre-defined dialogs that are often used in applications such as progress and file dialogs + + + +Therefore knowing the Qt classes is very essential, even if you only want to program KDE-applications. +To have an impression on the basic concept how GUI-applications are constructed and compiled, we'll first +have a look at a sample Qt-only program; then we'll extend it to a KDE program. + + + +The first Qt Application + +As usual, programs in C++ have to contain a main() function, which is the starting point for application +execution. As we want them to be graphically visible in windows and offering user interaction, +we first have to know, how they can show themselves to the user. For an example, we'll have a look +at the first tutorial included with the Qt Online Reference Documentation and explain the basic execution +steps; also why and how the application window appears: + +#include <qapplication.h> +#include <qpushbutton.h> + +int main( int argc, char **argv ) +{ +QApplication a( argc, argv ); + +QPushButton hello( "Hello world!", 0 ); +hello.resize( 100, 30 ); + +a.setMainWidget( &hello ); +hello.show(); +return a.exec(); +} + + + +This application merely paints a window containing a button with "Hello world" as its text. As for +all Qt-based applications, you first have to create an instance of the class QApplication, represented by +variable a. + + +Next, the program creates an instance of the class QPushButton called hello, this will be the button. +The constructor of hello gets a string as a parameter, which is the contents of the widget visible as +the buttons text. + + +Then the resize() method is called on the hello button. This changes the default size a widget +(which is in this case the QPushButton) has when created to the length of 100 pixels and the height of +30 pixels. Finally, the setMainWidget() method is called for a and the show() method for hello. The +QApplication is finally executed by a.exec(), enters the main event loop and waits until it has to return +an integer value to the overlaying Operating System signaling that the application is exited. + + + + +The Reference Documentation for Qt + +Now, let's have a quick look at the reference documentation of the Qt library. To do this, start +&tdevelop; and select "Qt" from the tree in the Documentation tab. The documentation browser opens +and shows you the start page of the Qt reference. This will be your first place to get information +about Qt, it's classes and the available functions they provide. Also, the above program is the first +that is included in the tutorials section. To get to the classes we want to have a look at, +QApplication and QPushButton, select "Alphabetical Class List" +and search for the according names. Follow either of them to have a look at the class documentation. + + +Alternatively, you can use the online documentation from Trolltech's Qt Documentation + + +For QApplication, you will see the constructor and all other methods that this +class provides. If you follow a link, you will get more information about the usage and meaning of the +methods, which is very useful when you sometimes can't detect the correct use or want to have an example. +This also counts for the KDE library documentation, which uses a similar documentation type; therefore +this is almost all you have to know about using the class-references with the documentation browser. + + +Interpretation of the Sample + +Starting with QApplication, you will find all the methods used in our first example: + +the constructor QApplication() +the setMainWidget() method +the exec() method + + + +The interpretation why we use these methods is very simple: + +Create an instance of the class QApplication with the constructor, +so we can make use of the GUI elements provided by Qt +Create a widget which will be the contents of our program window +Set the widget as the main widget for a +Execute the a instance of QApplication + + + +The second object of our program is the pushbutton, an instance of the class QPushButton. +From the two constructors given to create an instance, we used the second: this accepts a text, +which is the label contents of the button; here, it is the string "Hello world!". Then we called the +resize() method to change the size of the button according to it's contents - +the button has to be larger to make the string completely visible. + + +But what about the show() method? Now, you see that like most other widgets, +QPushButton is based on a single inheritance, the documentation says, Inherits +QButton. Follow the link to the QButton class. +This shows you a lot of other widgets that are inherited by QPushButton, +which we'll use later to explain the signal/slot mechanism. Anyway, the show() +method is not listed, therefore, it must be a method that is provided by inheritance as well. The class +that QButton inherits is QWidget. Just follow the link +again, and you will see a whole bunch of methods that the QWidget class provides; including +the show() method. Now we understand what was done in the sample with the button: + +Create an instance of QPushButton, use the second constructor to set the button text +Resize the widget to its contents +Set the widget as the main widget of the QApplication instance a +Tell the widget to display itself on the screen by calling show(), an inherited method from QWidget + + + +After calling the exec() method, the application is visible to the user, +showing a window with the button showing "Hello world!". Note: GUI programs behave somewhat differently +than procedural applications. The main thing here is that the application enters a so-called +"main event loop". This means that the program has to wait for user actions and then react to it, also +that for a Qt application, the program has to be in the main event loop to start the event handling. +The next section tells you in short what this means to the programmer and what Qt offers to process +user events. + + +For already advanced users: The button has no parent declared in the constructor, therefore it +is a top-level widget alone and runs in a local event loop which doesn't need to wait for the main +event loop. See the QWidget class documentation and The KDE Library Reference Guide + + + + + + +User Interaction + +After reading the last sections, you should already know: + +What the Qt-library provides in terms of GUI applications +How a program using Qt is created and +Where and how to find information about classes that you want to use with the documentation browser + + + +Now we'll turn to give the application "life" by processing user events. Generally, the user has two ways +to interact with a program: the mouse and the keyboard. For both ways, a graphical user interface has to +provide methods that detect actions and methods that do something as a reaction to these actions. + + +The Window system therefore sends all interaction events to the according application. The +QApplication then sends them to the active window as a QEvent +and the widgets themselves have to decide what to do with them. A widget receives the event and processes +QWidget::event(QEvent*), which then decides which event has been executed +and how to react; event() is therefore the main event handler. Then, +the event() method passes the event to so-called event filters +that determine what happened and what to do with the event. If no filter signs responsible for the +event, the specialized event handlers are called. Thereby we can decide between: + + +Keyboard events -- TAB and Shift-TAB keys: + +virtual void focusInEvent(QFocusEvent *) +virtual void focusOutEvent(QFocusEvent *) + + + + +All other keyboard input: + +virtual void keyPressEvent(QKeyEvent *) +virtual void keyReleaseEvent(QKeyEvent *) + + + + +Mouse movements: + +virtual void mouseMoveEvent(QMouseEvent *) +virtual void enterEvent(QEvent *) +virtual void leaveEvent(QEvent *) + + + + +Mouse button actions + +virtual void mousePressEvent(QMouseEvent *) +virtual void mouseReleaseEvent(QMouseEvent *) +virtual void mouseDoubleClickEvent(QMouseEvent *) + + + + +Window events containing the widget + +virtual void moveEvent(QMoveEvent *) +virtual void resizeEvent(QResizeEvent *) +virtual void closeEvent(QCloseEvent *) + + + + + + +Note that all event functions are virtual and protected; therefore you can re-implement the events +that you need in your own widgets and specify how your widget has to react. QWidget +also contains some other virtual methods that can be useful in your programs; anyway, it is sufficient +to know about QWidget very well. + + + +Object Interaction by Signals and Slots + +Now we're coming to the most obvious advantages of the Qt toolkit: the signal/slot mechanism. +This offers a very handy and useful solution to object interaction, which usually is solved by +callback functions for X-Window toolkits. As this communication requires a strict programming and +sometimes makes user interface creation very difficult (as referred by the Qt documentation and explained +in Programming with Qt by K.Dalheimer), Troll Tech invented a new system where objects can emit signals +that can be connected to methods declared as slots. For the C++ part of the programmer, he only has to know +some things about this mechanism: + + +the class declaration of a class using signals/slots has to contain the Q_OBJECT macro at the beginning +(without a semicolon); and have to be derved from the QObject class + + +a signal can be emitted by the keyword emit, e.g. emit signal(parameters); from within any member function +of a class that allows signals/slots + + + +all signals used by the classes that are not inherited have to be added to the class declaration by a +signals section + + +all methods that can be connected with a signal are declared in sections with the additional keyword slot, +e.g. public slots: within the class declaration + + +the meta-object compiler moc has to run over the header file to expand the macros and to produce the +implementation (which is not necessary to know). The output files of moc are compiled also by the C++ compiler. + + + + +Another way to use signals without deriving from QObject is to use the +QSignal class- see the reference documentation for more information and example +usage. In the following, we assume you're deriving from QObject. + + +This way, your class is able to send signals anywhere and to provide slots that signals can connect +to. By using the signals, you don't have to care about who's receiving it- you just have to emit the +signal and whatever slot you want to connect to it can react to the emission. Also the slots can be used +as normal methods during implementation. + + +Now, to connect a signal to a slot, you have to use the connect() methods that +are provided by QObject or, where available, special methods that objects provide +to set the connection for a certain signal. + + + +Sample Usage + +To explain the way how to set up object-interaction, we'll take our first example again and extend it by a +simple connection: + +#include <qapplication.h> +#include <qpushbutton.h> + +int main( int argc, char **argv ) +{ +QApplication a( argc, argv ); + +QPushButton hello( "Hello world!" , 0); +hello.resize( 100, 30 ); + +a.setMainWidget( &hello ); + +QObject::connect(&hello, SIGNAL( clicked() ), &a, SLOT( quit() )); + +hello.show(); +return a.exec(); +} + + + +You see, the only addition to give the button more interaction is to use a connect() + method: connect(&hello, SIGNAL( clicked() ), &a, SLOT( quit() )); +is all you have to add. What is the meaning now? The class declaration of QObject says about the +connect() method: + + +bool connect ( const QObject * sender, const char * signal, const QObject * receiver, const char * member ) + + +This means you have to specify a QObject instance pointer that is the sender +of the signal, meaning that it can emit this signal as first parameter; then you have to specify the signal +that you want to connect to. The last two parameters are the receiver object that provides a slot, followed +by the member function which actually is the slot that will be executed on signal emission. + + +By using signals and slots, your program's objects can interact with each other easily without explicitly +depending on the type of the receiver object. You will learn more about using this mechanism for productive +usage later in this handbook. More information about the Signals/Slot mechanism can also be found in +The KDE Library Reference Guide +and the Qt online reference. + + + + + + +What KDE provides + +The KDE 3.x libraries + +The main KDE libraries you'll be using for creating your own TDE applications are: + + +the tdecore library, containing all classes that are non-visible elements to provide application functionality + + +the tdeui library, containing user interface elements like menubars, toolbars, etc. + + +the tdefile library, containing the file selection dialogs + + + + +Additionally, for specific solutions KDE offers the following libraries: + + +the tdefx library, containing pixmaps, image effects the TDEStyle extension to QStyle + + +the tdehtml library, containing KDE's html component + + +the kjs library, containing KDE's Javascript support + + +the tdeio library, containing low level access to network files + + +the tdeparts library, containing support for re-usable embeddable extendable applications + + + + +Next we'll have a look at what is needed to turn out first Qt Application into a KDE one. + + + +Example KDE Application + +In the following, you will see that writing a KDE application is not much more difficult than a +Qt application. For the use of KDE's features, you just have to use some other classes, and you're almost +done. As an example, we'll discuss the changed version of the Qt example from above: + +#include <tdeapplication.h> +#include <qpushbutton.h> + +int main( int argc, char **argv ) +{ +TDEApplication a( argc, argv ); + +QPushButton hello( "Hello world!", 0 ); +hello.resize( 100, 30 ); + +a.setTopWidget( &hello ); + +QObject::connect(&hello, SIGNAL( clicked() ), &a, SLOT( quit() )); + +hello.show(); +return a.exec(); +} + + + +You see that first we have changed from QApplication to TDEApplication +. Further, we had to change the previously used setMainWidget() method +to setTopWidget, which TDEApplication uses to set the main +widget. That's it! Your first KDE application is ready - you only have to tell the compiler the KDE +include path and the linker to link in the tdecore library with -ltdecore. + + +As you now know what at least the main() function provides generally and how an +application gets visible and allows user and object interaction, we'll go on with the next chapter, +where our first application is made with &tdevelop;. There you can also test everything which was +mentioned before and see the effects. + + +What you should have looked into additionally until now is the reference documentation for Qt, +especially the QApplication, QWidget and QObject + class and the tdecore library documentation for the TDEApplication class. +The KDE Library Reference handbook +also covers a complete description about the invocation of the QApplication and +TDEApplication constructors including command-line argument processing. + + + + + + + +Creating New Applications + + +The Application Wizard + +&tdevelop;'s Application Wizard is intended to let you start working on new project with &tdevelop;. Therefore +all of your projects are first created by the wizard, and then you can start building them and extend what is +already provided by the source skeleton. You can choose from several project types according to your project goals: + + +KDE Application Framework: includes source code for a complete frame structre of a standard KDE application + + +QMake Project: Creates an application framework based around Trolltech's qmake configuration system + + +Simple hello world program: Creates a C++ terminal based program with no GUI support + + +A multitude of other program skeletons + + + + +In this chapter we'll see how the Application Wizard can be invoked and what has to be done to generate +a KDE application project. This will also be the initial step of our coverage, where we will create the +initial version of a sample project. For all other project types the steps are usualyl the same, but you +may not have as many options available. + + + + +Invoking the Application Wizard and Project Generation + +Starting the Application Wizard and the First Page + +To start with your KDE application, open &tdevelop;. From the Project menu, selection New Project. The +Application Wizard starts, and you'll see the selection tree on the first page containing available project +types that can be created. Choose the C++ subtree, then KDE, then Application Framework. + + +For our sample project, we are going to create the application KScribble. Enter this as the application +name, and change any other information at the bottom of this screen that may need it. Then, select Next. + + +Application Wizard + + + + +Version control information + +On this screen you have the ability to decide if your project will use a version control system like +CVS. For our sample project we will not use source control, so make sure the selection box reads None +and select Next. + + + +Header and Source Templates + +The next two pages show example headers that will go at the top of each of the header and source files that +you create using &tdevelop;. For now, just leave these as the default, and select Next, then Finish. If the +Finish button is not activated, you haven't set all of the options correct. Use the Back button to return +to earlier menus and correct any mistakes. + + + +Finishing Up + +Upon completion, the Application Wizard should close and the messages window should popup displaying +information about the tasks that &tdevelop; is currently doing. At the end of all of the tasks, you +should see **** Success *****. This means the application framework was successfully loaded. + + + + + +The First Build + +After our project is generated, we'll first make a trip through the source code to get a general understanding +of how the application framework looks. This won't only help us get started, but we'll know where to change +what in later steps. + + +This chapter makes the assumption that you understand the basic navigation of &tdevelop;. Consult the +TDevelop User Manual for information if you need it. + + +The Automake manager shows the project files as follows: + + +Files in our project + + + +Before diving into the sources, we'll let &tdevelop; build an run our new application. To do this, select +Build Project from the Build menu, or press F8. The output window opens and displays output messages during +the compilation phase. + +1 cd /home/caleb/kscribble && WANT_AUTOCONF_2_5=1 WANT_AUTOMAKE_1_6=1 gmake k +2 gmake all-recursive +3 gmake[1]: Entering directory `/home/caleb/kscribble' +4 Making all in doc +5 gmake[2]: Entering directory `/home/caleb/kscribble/doc' +6 Making all in . +7 gmake[3]: Entering directory `/home/caleb/kscribble/doc' +8 gmake[3]: Nothing to be done for `all-am'. +9 gmake[3]: Leaving directory `/home/caleb/kscribble/doc' +10 Making all in en +11 gmake[3]: Entering directory `/home/caleb/kscribble/doc/en' +12 /usr/local/trinity/bin/meinproc --check --cache index.cache.bz2 /home/caleb/kscribble/doc/en/index.docbook +13 gmake[3]: Leaving directory `/home/caleb/kscribble/doc/en' +14 gmake[2]: Leaving directory `/home/caleb/kscribble/doc' +15 Making all in po +16 gmake[2]: Entering directory `/home/caleb/kscribble/po' +17 gmake[2]: Nothing to be done for `all'. +18 gmake[2]: Leaving directory `/home/caleb/kscribble/po' +19 Making all in src +20 gmake[2]: Entering directory `/home/caleb/kscribble/src' +21 source='main.cpp' object='main.o' libtool=no \ +22 depfile='.deps/main.Po' tmpdepfile='.deps/main.TPo' \ +23 depmode=gcc3 /bin/sh /home/caleb/kscribble/admin/depcomp \ +24 g++ -DHAVE_CONFIG_H -I. -I/home/caleb/kscribble/src -I.. -I/usr/local/trinity/include + -I/usr/lib/qt/include -I/usr/X11R6/include -DQT_THREAD_SUPPORT -D_REENTRANT -Wnon-virtual-dtor + -Wno-long-long -Wundef -Wall -pedantic -W -Wpointer-arith -Wmissing-prototypes -Wwrite-strings + -ansi -D_XOPEN_SOURCE=500 -D_BSD_SOURCE -Wcast-align -Wconversion -O2 -fno-exceptions -fno-check-new + -c -o main.o `test -f 'main.cpp' || echo '/home/caleb/kscribble/src/'`main.cpp +25 /usr/lib/qt/bin/moc /home/caleb/kscribble/src/kscribble.h -o kscribble.moc +26 source='kscribble.cpp' object='kscribble.o' libtool=no \ +27 depfile='.deps/kscribble.Po' tmpdepfile='.deps/kscribble.TPo' \ +28 depmode=gcc3 /bin/sh /home/caleb/kscribble/admin/depcomp \ +29 g++ -DHAVE_CONFIG_H -I. -I/home/caleb/kscribble/src -I.. -I/usr/local/trinity/include + -I/usr/lib/qt/include -I/usr/X11R6/include -DQT_THREAD_SUPPORT -D_REENTRANT -Wnon-virtual-dtor + -Wno-long-long -Wundef -Wall -pedantic -W -Wpointer-arith -Wmissing-prototypes -Wwrite-strings + -ansi -D_XOPEN_SOURCE=500 -D_BSD_SOURCE -Wcast-align -Wconversion -O2 -fno-exceptions -fno-check-new + -c -o kscribble.o `test -f 'kscribble.cpp' || echo '/home/caleb/kscribble/src/'`kscribble.cpp +30 kscribble.cpp: In member function `void KScribble::setupActions()' +31 kscribble.cpp:107: warning: unused variable `TDEAction*custom' +32 /usr/lib/qt/bin/moc /home/caleb/kscribble/src/kscribbleview.h -o kscribbleview.moc +33 source='kscribbleview.cpp' object='kscribbleview.o' libtool=no \ +34 depfile='.deps/kscribbleview.Po' tmpdepfile='.deps/kscribbleview.TPo' \ +35 depmode=gcc3 /bin/sh /home/caleb/kscribble/admin/depcomp \ +36 g++ -DHAVE_CONFIG_H -I. -I/home/caleb/kscribble/src -I.. -I/usr/local/trinity/include + -I/usr/lib/qt/include -I/usr/X11R6/include -DQT_THREAD_SUPPORT -D_REENTRANT -Wnon-virtual-dtor + -Wno-long-long -Wundef -Wall -pedantic -W -Wpointer-arith -Wmissing-prototypes -Wwrite-strings -ansi + -D_XOPEN_SOURCE=500 -D_BSD_SOURCE -Wcast-align -Wconversion -O2 -fno-exceptions -fno-check-new -c + -o kscribbleview.o `test -f 'kscribbleview.cpp' || echo '/home/caleb/kscribble/src/'`kscribbleview.cpp +37 kscribbleview.cpp: In member function `void KScribbleView::print(QPainter*, +38 int, int)': +39 kscribbleview.cpp:79: warning: unused parameter `QPainter*p' +40 kscribbleview.cpp:79: warning: unused parameter `int height' +41 kscribbleview.cpp:79: warning: unused parameter `int width' +42 /usr/lib/qt/bin/moc /home/caleb/kscribble/src/pref.h -o pref.moc +43 source='pref.cpp' object='pref.o' libtool=no \ +44 depfile='.deps/pref.Po' tmpdepfile='.deps/pref.TPo' \ +45 depmode=gcc3 /bin/sh /home/caleb/kscribble/admin/depcomp \ +46 g++ -DHAVE_CONFIG_H -I. -I/home/caleb/kscribble/src -I.. -I/usr/local/trinity/include + -I/usr/lib/qt/include -I/usr/X11R6/include -DQT_THREAD_SUPPORT -D_REENTRANT -Wnon-virtual-dtor + -Wno-long-long -Wundef -Wall -pedantic -W -Wpointer-arith -Wmissing-prototypes -Wwrite-strings + -ansi -D_XOPEN_SOURCE=500 -D_BSD_SOURCE -Wcast-align -Wconversion -O2 -fno-exceptions -fno-check-new + -c -o pref.o `test -f 'pref.cpp' || echo '/home/caleb/kscribble/src/'`pref.cpp +47 /usr/local/trinity/bin/dcopidl /home/caleb/kscribble/src/kscribbleiface.h > kscribbleiface.kidl || + ( rm -f kscribbleiface.kidl ; /bin/false ) +48 /usr/local/trinity/bin/dcopidl2cpp --c++-suffix cpp --no-signals --no-stub kscribbleiface.kidl +49 source='kscribbleiface_skel.cpp' object='kscribbleiface_skel.o' libtool=no \ +50 depfile='.deps/kscribbleiface_skel.Po' tmpdepfile='.deps/kscribbleiface_skel.TPo' \ +51 depmode=gcc3 /bin/sh /home/caleb/kscribble/admin/depcomp \ +52 g++ -DHAVE_CONFIG_H -I. -I/home/caleb/kscribble/src -I.. -I/usr/local/trinity/include + -I/usr/lib/qt/include -I/usr/X11R6/include -DQT_THREAD_SUPPORT -D_REENTRANT -Wnon-virtual-dtor + -Wno-long-long -Wundef -Wall -pedantic -W -Wpointer-arith -Wmissing-prototypes -Wwrite-strings + -ansi -D_XOPEN_SOURCE=500 -D_BSD_SOURCE -Wcast-align -Wconversion -O2 -fno-exceptions -fno-check-new + -c -o kscribbleiface_skel.o `test -f 'kscribbleiface_skel.cpp' || + echo '/home/caleb/kscribble/src/'`kscribbleiface_skel.cpp +53 /bin/sh ../libtool --silent --mode=link --tag=CXX g++ -Wnon-virtual-dtor -Wno-long-long -Wundef -Wall + -pedantic -W -Wpointer-arith -Wmissing-prototypes -Wwrite-strings -ansi -D_XOPEN_SOURCE=500 + -D_BSD_SOURCE -Wcast-align -Wconversion -O2 -fno-exceptions -fno-check-new -o kscribble -R + /usr/local/trinity/lib -R /usr/lib/qt/lib -R /usr/X11R6/lib -L/usr/X11R6/lib -L/usr/lib/qt/lib + -L/usr/local/trinity/lib main.o kscribble.o kscribbleview.o pref.o kscribbleiface_skel.o -ltdeio +54 source='kscribble_client.cpp' object='kscribble_client.o' libtool=no \ +55 depfile='.deps/kscribble_client.Po' tmpdepfile='.deps/kscribble_client.TPo' \ +56 depmode=gcc3 /bin/sh /home/caleb/kscribble/admin/depcomp \ +57 g++ -DHAVE_CONFIG_H -I. -I/home/caleb/kscribble/src -I.. -I/usr/local/trinity/include + -I/usr/lib/qt/include -I/usr/X11R6/include -DQT_THREAD_SUPPORT -D_REENTRANT -Wnon-virtual-dtor + -Wno-long-long -Wundef -Wall -pedantic -W -Wpointer-arith -Wmissing-prototypes -Wwrite-strings + -ansi -D_XOPEN_SOURCE=500 -D_BSD_SOURCE -Wcast-align -Wconversion -O2 -fno-exceptions -fno-check-new + -c -o kscribble_client.o `test -f 'kscribble_client.cpp' || echo + '/home/caleb/kscribble/src/'`kscribble_client.cpp +58 /bin/sh ../libtool --silent --mode=link --tag=CXX g++ -Wnon-virtual-dtor -Wno-long-long -Wundef + -Wall -pedantic -W -Wpointer-arith -Wmissing-prototypes -Wwrite-strings -ansi -D_XOPEN_SOURCE=500 + -D_BSD_SOURCE -Wcast-align -Wconversion -O2 -fno-exceptions -fno-check-new -o kscribble_client -R + /usr/local/trinity/lib -R /usr/lib/qt/lib -R /usr/X11R6/lib -L/usr/X11R6/lib -L/usr/lib/qt/lib + -L/usr/local/trinity/lib kscribble_client.o -ltdecore +59 gmake[2]: Leaving directory `/home/caleb/kscribble/src' +60 gmake[2]: Entering directory `/home/caleb/kscribble' +61 gmake[2]: Nothing to be done for `all-am'. +62 gmake[2]: Leaving directory `/home/caleb/kscribble' +63 gmake[1]: Leaving directory `/home/caleb/kscribble' +64 *** Success *** + + + +As you can see, we've put line numbers in front of each line which won't appear on your output but it makes it +easier to describe what is happening during the build. First of all, gmake works recursively. This means +that it starts from the directory it is invoked and goes into the subdirectories first, one at a time, then +returns to the directory it was started, processes it, then finishes. + + +Our first line of interest is 24. Notice on this line that g++, which is our C++ compiler, gets called by make +to compile the first source code file in our project - in this case main.cpp. Many extra command line options +are also being used with the g++ compiler; some of which are defaults and some of which can be configured +via &tdevelop;. + + +Before the next file (kscribble.cpp, line 29) is compiled, the moc (meta object compiler) is first +invoked on kscribble.h (line 25). This is because KScribble classes use signals/slots, so the +Q_OBJECT macro must be expanded, and the moc does this for us. The resultant file, kscribble.moc, is +used by kscribble.cpp via an #include statement inside of the file. + + + + +The source skeleton + +To conceptualize how a KDE application works, we'll first have a very close look at the source +skeleton already provided by the Application Wizard. As we already saw, we're having a set of source +and header files that build the initial code for the application and make it ready-to-run. Therefore, +the easiest way to explain the code is to follow the implementation line by line as it is processed +during executing the program until it enters the main event loop and is ready to accept user input. +Then, we'll have a look at the functionality that enables user interaction and how certain things work. +This is probably the best way to explain the framework and, as it is similar to almost all KDE +applications, will enable you to read source codes from other projects as well; additionally, you will +know where to change what part of the code to make your applications behave the way they are designed for. + + + +The main() function + +As the application begins its execution with entering the main() function, +this will be the start for our code examination. The main() function of +KScribble is implemented in the file main.cpp and can also be found using the Class Browser +by selecting the "Global Functions" folder. + +1 int main(int argc, char **argv) +2 { +3 TDEAboutData about("kscribble", I18N_NOOP("KScribble"), version, description, +4 TDEAboutData::License_GPL, "(C) 2002 Your Name", 0, 0, "you@you.com"); +5 about.addAuthor( "Your Name", 0, "you@you.com" ); +6 TDECmdLineArgs::init(argc, argv, &about); +7 TDECmdLineArgs::addCmdLineOptions(options); +8 TDEApplication app; +9 +10 // register ourselves as a dcop client +11 app.dcopClient()->registerAs(app.name(), false); +12 +13 // see if we are starting with session management +14 if (app.isRestored()) +15 RESTORE(KScribble) +16 else +17 { +18 // no session.. just start up normally +19 TDECmdLineArgs *args = TDECmdLineArgs::parsedArgs(); +20 if (args->count() == 0) +21 { +22 KScribble *widget = new KScribble; +23 widget->show(); +24 } +25 else +26 { +27 int i = 0; +28 for (; i < args->count(); i++) +29 { +30 KScribble *widget = new KScribble; +31 widget->show(); +32 widget->load(args->url(i)); +33 } +34 } +35 args->clear(); +36 } +37 +38 return app.exec(); +39 } + + + +Now, what happens first is the usual creation of a TDEApplication object, but we've +added some KDE methods that set program and author information for this application. + + + +User Application Start + +... (not written yet) + + + +The Constructor + +Let's have a look at the constructor and see how this instance is called + +1 KScribble::KScribble() +2 : TDEMainWindow( 0, "KScribble" ), +3 m_view(new KScribbleView(this)), +4 m_printer(0) +5 { +6 // accept dnd +7 setAcceptDrops(true); +8 +9 // tell the TDEMainWindow that this is indeed the main widget +10 setCentralWidget(m_view); +11 +12 // then, setup our actions +13 setupActions(); +14 +15 // and a status bar +16 statusBar()->show(); +17 +18 // allow the view to change the statusbar and caption +19 connect(m_view, SIGNAL(signalChangeStatusbar(const QString&)), +20 this, SLOT(changeStatusbar(const QString&))); +21 connect(m_view, SIGNAL(signalChangeCaption(const QString&)), +22 this, SLOT(changeCaption(const QString&))); +23 +24 } + + + +Notice that KScribble inherits the TDEMainWindow class - a +commonly used base class for TDE applications. We initialize a class called KScribbleView +as our central widget, create a KStatusBar via the statusBar() +method (line 16), and connect some signals and slots together. + + + + + + + +Application View Design + +Introduction + +When developing an application with a graphical user interface, the main work takes place in +providing a so-called "view" for the application. A view generally is a widget that displays the data +of a document and provides methods to manipulate the document contents. This can be done by the user via +the events he emits by the keyboard or the mouse; more complex operations are often processed by toolbars +and menubars which interact with the view and the document. The statusbar then provides information about +the document, view or application status. As an example, we look at how an editor is constructed and where +we can find which part. + + +An editor generally is supposed to provide an interface to view and/or change the contents of a text +document for the user. If you start Kate, you see the visual interface as the following: + + +The menubar: providing complex operations as well as opening, saving and closing files and +exiting the application. + + +The toolbar: offers icons which allow quicker access for most needed functions, + + +The statusbar: displays the status of the cursor position by the current row and column, + + +The view in the center of the window, displaying a document and offering a cursor connected to +the keyboard and the mouse to operate on the data. + + + + +Now it's easy to understand that a view is the most unique part of the application and the design +of the view decides about the usability and acceptability of an application. This means that one of +the first steps in development is to determine the purpose of the application and what kind of view +design would match best to allow any user to work with the application with a minimum of work +learning how to handle the user interface. + + +For some purposes like text editing and displaying HTML files, views are provided by the Qt and KDE +libraries; we will discuss certain aspects of these high-level widgets in the next section. +But for most applications new widgets have to be designed and implemented. It is that what makes a +programmer also a designer and where his abilities on creativity are asked. Nevertheless, you should +watch for intuitivity first. Remember, a lot of users won't accept an application that isn't: + + +graphically nice. + + +offering a lot of features + + +easy to handle + + +fast to learn how to use it + + + + +Needless to say that stability is a major design goal. Nobody can prevent bugs, but a minimum can +be reached at least by clever design goals and wide use of object-oriented design. C++ makes programming +a joy if you know how to exploit it's capabilities- inheritance, information hiding and reusablitity of +already existing code. + + +When creating a KDE or Qt project, you always have to have a view that inherits QWidget, either by +direct inheritance or because the library widget you want to use inherits QWidget. Therefore, the +Application Wizard already constructed a view that is an instance of a class yourappView, which +inherits QWidget already. + + +This chapter therefore describes how to use library widgets for creating views of KDE or +Qt applications that are generated with &tdevelop;, then we look at the libraries and what kind of +views are already offered. + + + +Using Library Views + +When your application design has been set up, you first should look for already existing code that +will make your life a lot easier. A part of this search is to look for a widget that can be used as +a view or at least as a part of it; either directly or by inheritance. The KDE and Qt libraries already +contain a set of widgets that can be used for this purpose. To use them, you have two options: + + +Remove the new view class and create an instance of a library widget; then set this as the view, + + +Change the inheritance of the provided view class to the class of the library widget to use. + + + + +In either way, it is important to know that if the application framework is currently not linked +against the library that contains the widget, the linker will fail. After you decided to use a +certain widget, look for the library to link to; then open "Project"->"Options" from the &tdevelop; +menubar. Switch to the "Linker Options" page and look for the checkmarks indicating the libraries +that are currently used. If the library of your view widget is already checked, you can leave the +project options untouched and start doing the necessary changes due to your choice. If not, and the +linker options offer to add the library by a check box, check it and press "OK" to leave the project +options dialog again. In any other case, add the library in the edit line below with the -l option. +For libraries that your application has to search for before preparing the Makefiles by the +configure script on the end-user machine, add the according search macro to the configure.in file +located at the root directory of your project and add the macro to the edit line. Mind that you have +to run "Build"->"Autoconf and automake" and "Build"->"Configure" before the Makefiles contain the +correct expansion for the library macro. + + +Also, if the include files for the library to add are not in the current include path +(which can be seen by the -I options in the output window on "Make"), you have to add the path to the +Project Options dialog -"Compiler Options" page with the -I option or the according automake macro at +the edit line for "Additional Options". + + +Qt Views + +Looking at the first page of the Qt online documentation, you will find a link to +"Widget Screenshots" where you can have a look at how the widgets Qt contains look like. +These are ready to use and can be combined together to form complex widgets to create application +views or dialogs. In the following, we'll discuss some of these which are very usable for creating +application views, but keep in mind that the KDE libraries sometimes contain other widgets for the +same purpose; those will be reviewed in the next section. + + +Here are a set of hints for what purpose you could use which Qt component: + + +If your view area isn't big enough to display all your data, the user must be enabled to scroll +over the document with bars on the left and bottom of the view. For this, Qt provides the class +QScrollView, which offers a scrollable child area. As explained, you could +inherit your own widget from QScrollView or use an instance to manage your +document's view widget. + + +to create a ScrollView yourself, inherit the View widget from QWidget +and add vertical and horizontal QScrollBars . +(This is done by KDE`s TDEHTMLView widget.) + + +For text processing, use QTextEdit. This class provides a complete +text editor widget that is already capable to cut, copy and paste text and is managed by a scrollview. + + +Use QTable to display data that is arranged in a table. +As QTable is managed by scrollbars as well, it offers a good solution for +table calculation applications. + + +To display two different widgets or two widget instances at the same time, use QSplitter +. This allows to tile views by horizontal or vertical dividers. +KMail is a good example what this would look like- the main view is separated by a +splitter vertically, the right window then is divided again horizontally. + + +QListView displays information in a list and tree. +This is useful for creating file trees or any other hierarchical information you want to interact with. + + + + +You see that Qt alone offers a whole set of widgets which are ready to use so you don't have to invent +new solutions if these match your needs. The sideffect when using standard widgets is that users already +know how to handle them and only have to concentrate on the displayed data. + + + +KDE Views + +The KDE libraries were invented to make designing applications for the K Desktop Environment easier +and capable of more functionality than what Qt alone is offering. The tdeui library offers: + + +TDEListView: a more powerful version of QListView + + +TDEIconView: a graphical viewer of icon files + + + + +The tdehtml library, on the other hand, offers a complete HTML-interpreting widget that is ready to use. +It is scrollable already, so you don't even have to take care for that. A possible use could be to +integrate it as a preview widget for an HTML editor; used by applications such as Konqueror to display HTML files. + + + + +Creating your own Views + +Not yet written + + + + + +Configuring Menubars and Toolbars + +Introduction + +Menubars and toolbars are one of the most important parts of an application to provide methods to +work with a document structure. As a general rule, you should make all functions available by the menubar. +Those methods that should not be available at a current stage of the application process should be +disabled. + + +Further, an application can only contain one menubar, but several toolbars. +Toolbars on the other hand should contain only the most frequently used commands by pixmap +icons or provide quick access methods like combos to select values. + + + +How does it work? + +Our application inherits the TDEMainWindow class, which automatically handles creating +a menu bar and tool bars for us. In the KScribble::setupActions() method there is +a call to TDEMainWindow::createGUI(). This method loads a resource file, in this +case kscribbleui.rc, to initialize menus at startup. Note that kscribbleui.rc is listed as one of the +project files in the Automake Manager. Opening that file up reveals this: + +1 <!DOCTYPE kpartgui SYSTEM "kpartgui.dtd"> +2 <kpartgui name="kscribble" version="1"> +3 <MenuBar> +4 <Menu name="custom"><text>C&ustom</text> +5 <Action name="custom_action" /> +6 </Menu> +7 </MenuBar> +8 </kpartgui> + + + +Explanation... + + +Another way to modify the contents of the menu and tool bars is to directly manipulate them through the +methods provided by their class. For example, the menuBar() method returns the +KMenuBar widget that the menubar for our program. Looking at the documentation for +KMenuBar and its inheritor class QMenuBar, you will find +a large number of insertItem() methods which allow you to add items to the +menu bar. + + +TDEMainWindow's methods statusBar() and +toolBar() will also provide you with applicable widgets. + + + +Keyboard Accelerator Configuration + +A very professional thing you should always add to your application are keyboard accelerators. +Those are mainly used by experienced users that want to work fast with their applications and +are willing to learn shortcuts. For this, the KDE libraries provide the class +TDEAction, which provides the keyboard accelerator keys and access to global configured +standard keyboard accelerators. + + +By default, frame applications generated by &tdevelop; only use standard keyboard accelerators +such as F1 for accessing online-help, Ctrl+N for New File etc. + + +If your application contains a lot of accelerators, you should make them configurable +by an Options-menu; either it could be combined with other application configuration in a QWidget +or stand alone. The KDE library already provides a KKeyChooser +for use in tab dialogs, whereas KKeyDialog provides a ready-to use +key-configuration dialog. + + + + + + + +Help Functions + +Introduction + +A very important part of the development process is to provide help functionality to the user +wherever possible. Most developers tend to delay this, but you should remember that a normal user +isn't necessarily a Unix expert. He may come from the the dark side of computer software usage offering +all sweets that a user may need to work himself into using an application even without ever touching the +manuals. Therefore, the KDE and Qt library provide all means usually considered making an application +professional in the eyes of the normal user by help functions that are ready to use. +Within the application, those are: + +Tool-Tips +Statusbar help +What's this...? buttons + + +Additionally, the application should provide means to access a HTML-based online manual directly +using the standard help key F1. This context based help system is provided automatically through the +TDEMainWindow class, though as the author you must provide the content. + + +As &tdevelop; also offers all types of help as well as the KDE framework generated by the +application wizard already contains support for this, this chapter will help you find out where +and how to add your help functionality. + +During the development of your application you should try to be consistent whatever you're doing; +therefore you should do the necessary steps directly while extending the code. This will prevent you +from diving into the code again and figuring out what your application does or what you intended by +certain parts of the code. + + + + +Tool-Tips + +A very easy means of providing help are tool-tips. Those are small help messages popping up while +the user moves the mouse over a widget that provides a tool-tip and disappears when the mouse moves away. +The most popular usage of tool-tips is made in toolbars where your tool-tips should be kept as small +as possible because toolbars can be configured to display their contents in various ways: +either displaying the button, button with text on the right, button with text below, text only. +This possibility should be made configurable by the user, but isn't a must-be. The text is shown +as a tool-tip anyway and a toolbar usually consists of buttons and other widgets like lineedits and +combo boxes. For a complete reference, see the TDEToolBar class reference located +in the tdeui library. + + +As an example, we have a look at the "New File" button in a generic application: + + +There, the part i18n("New File") provides a tool-tip message. It is enclosed by the i18n() +macro provided by kapp.h to translate the tool-tip towards the currently selected language. + + +Tool-tips can also be added to any custom widget by using the QToolTip +provided by Qt. An example of that would be: + + + +Extending the Statusbar + +As the applications that inherit TDEMainWindow contain a statusbar as well, +it also offers a set of statusbar messages already for all menu and toolbar items. A statusbar +help message is a short message that extends the meaning of a tool-tip or can be seen as a replacement +for a tool-tip over menubar items and is (as the name suggests) displayed in the statusbar when the user +enters a menu and highlights the menu entry. + + + +The <guibutton>What's This...?</guibutton> Button + +The What's This...? button provides help windows with the intention +that the user wants to get help about a certain widget within the working view or a toolbar item. +It is placed in the toolbar and gets activated once the user hits the button. The cursor changes +to an arrow cursor with a question mark like the button itself looks like. The the user can press on +a visible widget item and gets a help window. As an exercise, you could try this behavior with the +What's this...? button within &tdevelop;. + + +To add the What's This...? help to one of your widgets, use the static method +QWhatsThis::add(QWidget *widget, const QString &text) + + + + + +Documentation + +Introduction + +Due to the fact that projects often lack a complete set of user documentation, +all &tdevelop; projects contain a pre-build handbook that can be easily adapted; +therefore fulfiling another goal of KDE: providing enough online-help to support users that +are not familiar with an application. This chapter therefore introduces you on how to extend +the provided documentation template and what you have to do to make it available to the user. + + + +User Documentation + +The documentation for your project lies in projectdir/doc/en, or perhaps another directory if English +isn't your native language. Therein lies a file, index.docbook, in which the documentation is stored. +The format for editing this file is explained on +KDE's documentation website. + + + +Programmer Documentation + +Another important part of the documentation is including a descriptive help for your class interfaces. +This will allow you and other programmers to use your classes by reading the HTML class documentation +that can be created with KDoc. &tdevelop; supports the use of KDoc completely by creating the +KDE-library documentation, also your application frameworks are already documented. To work yourself +into the provided code, it would be a good start to read the included documentation online. +The following describes what to do to get the API documentation, where &tdevelop; helps you add it +and what kind of special tags KDoc provides. + + + + + +Internationalization + +Introdction + +i18n is an internationalization system that is used to offer internationalized versions of an +application or project. The difficulty with writing applications is that they only support the +language they originally are composed with; visually this can be seen on labels, menu entries and the +like. The goal of the internationalization is to provide applications and library functions in the +language of the user; therefore enabling users that are not native speakers the original language to make +use of the provided functionality and feel more comfortable. + + + + + + +Credits + + +(... to be written ...) + + + + + + + +Bibliography + + + +<ulink url="info://make/Top">GNU Make Manual</ulink> + +Richard M.Stallman +RolandMcGrath + + + + +<ulink url="info://automake/Top">GNU Automake</ulink> + +DavidMacKenzie +TomTromey + + + + +<ulink url="info://autoconf/Top">GNU Autoconf</ulink> + +DavidMacKenzie +BenElliston + + + + +<ulink url="info://gcc/Top">Using the GNU Compiler Collection</ulink> +Richard M.Stallman + + + +<ulink url="info://libtool/Top">GNU Libtool</ulink> + +GordonMatzigkeit +AlexandreOliva +ThomasTanner +Gary V.Vaughan + + + + +GNU Autoconf, Automake, and Libtool +1st edition +October 2000 + +Gary V.Vaughan +BenElliston +TomTromey +Ian LanceTaylor + +New Riders Publishing +ISBN 1578701902 + + + + +Advanced Programming in the UNIX(R) Environment +1st edition +June 1992 +W. RichardStevens +Addison-Wesley Pub Co +ISBN 0201563177 + + + +Thinking in C++, Volume 1: Introduction to Standard C++ +2nd Edition +April 15, 2000 +BruceEckel +Prentice Hall +ISBN 0139798099 + + + +Open Source Development with CVS +2nd Edition +October 12, 2001 + +KarlFogel +MosheBar + +The Coriolis Group +ISBN 158880173X + + + +Programming PHP +1st edition +March 2002 + +RasmusLerdorf +KevinTatroe + +O'Reilly & Associates +ISBN 1565926102 + + + +Programming Python +2nd Edition +March 2001 +MarkLutz +O'Reilly & Associates +ISBN 0596000855 + + + +Gui Programming With Python : Using the Qt Toolkit +Bk&Cd-r edition +January 2002 +BoudewijnRempt +Opendocs Llc +ISBN 0970033044 + + + +Programming Perl +The Camel book +3rd Edition +July 2000 + +LarryWall +TomChristiansen +JonOrwant + +O'Reilly & Associates +ISBN 0596000278 + + + +Learning Perl +The Lama book +3rd Edition +July 15, 2001 + +Randal L.Schwartz +TomPhoenix + +O'Reilly & Associates +ISBN 0596001320 + + + + +&underFDL; + + + + + diff --git a/doc/tde_app_devel/kscribblefiles.png b/doc/tde_app_devel/kscribblefiles.png new file mode 100644 index 00000000..1591b3cf Binary files /dev/null and b/doc/tde_app_devel/kscribblefiles.png differ diff --git a/doc/tdearch/Makefile.am b/doc/tdearch/Makefile.am new file mode 100644 index 00000000..171f575c --- /dev/null +++ b/doc/tdearch/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = AUTO diff --git a/doc/tdearch/affine-general.png b/doc/tdearch/affine-general.png new file mode 100644 index 00000000..8e59d5e5 Binary files /dev/null and b/doc/tdearch/affine-general.png differ diff --git a/doc/tdearch/affine-rotate.png b/doc/tdearch/affine-rotate.png new file mode 100644 index 00000000..7192ed9c Binary files /dev/null and b/doc/tdearch/affine-rotate.png differ diff --git a/doc/tdearch/affine-scale.png b/doc/tdearch/affine-scale.png new file mode 100644 index 00000000..0b52fd4c Binary files /dev/null and b/doc/tdearch/affine-scale.png differ diff --git a/doc/tdearch/affine-shear.png b/doc/tdearch/affine-shear.png new file mode 100644 index 00000000..1ed5fbd8 Binary files /dev/null and b/doc/tdearch/affine-shear.png differ diff --git a/doc/tdearch/affine-translate.png b/doc/tdearch/affine-translate.png new file mode 100644 index 00000000..87265e30 Binary files /dev/null and b/doc/tdearch/affine-translate.png differ diff --git a/doc/tdearch/brushstyles.png b/doc/tdearch/brushstyles.png new file mode 100644 index 00000000..b6df50ca Binary files /dev/null and b/doc/tdearch/brushstyles.png differ diff --git a/doc/tdearch/canvas.png b/doc/tdearch/canvas.png new file mode 100644 index 00000000..dd83dae9 Binary files /dev/null and b/doc/tdearch/canvas.png differ diff --git a/doc/tdearch/capflat.png b/doc/tdearch/capflat.png new file mode 100644 index 00000000..5e1c92ce Binary files /dev/null and b/doc/tdearch/capflat.png differ diff --git a/doc/tdearch/capround.png b/doc/tdearch/capround.png new file mode 100644 index 00000000..0e66eaac Binary files /dev/null and b/doc/tdearch/capround.png differ diff --git a/doc/tdearch/capsquare.png b/doc/tdearch/capsquare.png new file mode 100644 index 00000000..35724a72 Binary files /dev/null and b/doc/tdearch/capsquare.png differ diff --git a/doc/tdearch/index.docbook b/doc/tdearch/index.docbook new file mode 100644 index 00000000..3bc09158 --- /dev/null +++ b/doc/tdearch/index.docbook @@ -0,0 +1,3337 @@ + + + +]> + + + + +KDE Architecture Overview + + + + + + +Bernd +Gehrmann +
bernd@kdevelop.org
 + + + + +2001 +2002 +Bernd Gehrmann + + +&FDLNotice; + + +This documentation gives an overview of the KDE Development Platform + + + +KDE +architecture +development +programming + + + + + +Library structure + + +Libraries by name + + + + +tdecore + +The tdecore library is the basic application framework for every KDE based +program. It provides access to the configuration system, command line +handling, icon loading and manipulation, some special kinds inter-process +communication, file handling and various other utilities. + + + + +tdeui + +The tdeui library provides many widgets and standard +dialogs which Qt doesn't have or which have more features than their Qt +counterparts. It also includes several widgets which are subclassed +from Qt ones and are better integrated with the KDE desktop by +respecting user preferences. + + + + +tdeio + +The tdeio library contains facilities for asynchronous, +network transparent I/O and access to mimetype handling. It also provides the +KDE file dialog and its helper classes. + + + + +kjs + +The kjs library provides an implementation of JavaScript. + + + + +tdehtml + +The tdehtml library contains the TDEHTML part, a HTML browsing +widget, DOM API and parser, including interfaces to Java and JavaScript. + + + + + + + + + +Grouped classes + + +Core application skeleton - classes needed by almost every application. + + + + + +<ulink url="kdeapi:tdecore/TDEApplication">TDEApplication</ulink> + +Initializes and controls a KDE application. + + + + +<ulink url="kdeapi:tdecore/KUniqueApplication">KUniqueApplication</ulink> + +Makes sure only one instance of an application can run simultaneously. + + + +<ulink url="kdeapi:tdecore/TDEAboutData">TDEAboutData</ulink> + +Holds information for the about box. + + + +<ulink url="kdeapi:tdecore/TDECmdLineArgs">TDECmdLineArgs</ulink> + +Command line argument processing. + + + + + + +Configuration settings - access to KDE's hierarchical configuration +database, global settings and application resources. + + + + +<ulink url="kdeapi:tdecore/TDEConfig">TDEConfig</ulink> + +Provides access to KDE's configuration database. + + + +<ulink url="kdeapi:tdecore/KSimpleConfig">KSimpleConfig</ulink> + +Access to simple, non-hierarchical configuration files. + + + +<ulink url="kdeapi:tdecore/KDesktopFile">KDesktopFile</ulink> + +Access to .desktop files. + + + +<ulink url="kdeapi:tdecore/TDEGlobalSettings">TDEGlobalSettings</ulink> + +Convenient access to not application-specific settings. + + + + + + +File and URL handling - decoding of URLs, temporary files etc. + + + + +<ulink url="kdeapi:tdecore/KURL">KURL</ulink> + +Represents and parses URLs. + + + +<ulink url="kdeapi:tdecore/KTempFile">KTempFile</ulink> + +Creates unique files for temporary data. + + + +<ulink url="kdeapi:tdecore/KSaveFile">KSaveFile</ulink> + +Allows to save files atomically. + + + + + + +Interprocess communication - DCOP helper classes and subprocess invocation. + + + + +<ulink url="kdeapi:tdecore/TDEProcess">TDEProcess</ulink> + +Invokes and controls child processes. + + + +<ulink url="kdeapi:tdecore/KShellProcess">KShellProcess</ulink> + +Invokes child processes via a shell. + + + +<ulink url="kdeapi:tdesu/PtyProcess">PtyProcess</ulink> + +Communication with a child processes through a pseudo terminal. + + + +<ulink url="kdeapi:tdecore/KIPC">KIPC</ulink> + +Simple IPC mechanism using X11 ClientMessages. + + + +<ulink url="kdeapi:dcop/DCOPClient">DCOPClient</ulink> + +DCOP messaging. + + + +<ulink url="kdeapi:tdecore/KDCOPPropertyProxy">KDCOPPropertyProxy</ulink> + +A proxy class publishing Qt properties through DCOP. + + + +<ulink url="kdeapi:tdeui/KDCOPActionProxy">KDCOPActionProxy</ulink> + +A proxy class publishing a DCOP interface for actions. + + + + + + +Utility classes - memory management, regular expressions, string manipulation, +random numbers + + + + +<ulink url="kdeapi:tdecore/KRegExp">KRegExp</ulink> + +POSIX regular expression matching. + + + +<ulink url="kdeapi:tdecore/KStringHandler">KStringHandler</ulink> + +An extravagant interface for string manipulation. + + + +<ulink url="kdeapi:tdecore/TDEZoneAllocator">TDEZoneAllocator</ulink> + +Efficient memory allocator for large groups of small objects. + + + +<ulink url="kdeapi:tdecore/KRandomSequence">KRandomSequence</ulink> + +Pseudo random number generator. + + + + + + +Keyboard accelerators - classes helping to establish consistent key bindings +throughout the desktop. + + + + +<ulink url="kdeapi:tdecore/TDEAccel">TDEAccel</ulink> + +Collection of keyboard shortcuts. + + + +<ulink url="kdeapi:tdecore/TDEStdAccel">TDEStdAccel</ulink> + +Easy access to the common keyboard shortcut keys. + + + +<ulink url="kdeapi:tdecore/TDEGlobalAccel"></ulink> + +Collection of system-wide keyboard shortcuts. + + + + + + +Image processing - icon loading and manipulating. + + + + +<ulink url="kdeapi:tdecore/TDEIconLoader">TDEIconLoader</ulink> + +Loads icons in a theme-conforming way. + + + +<ulink url="kdeapi:tdecore/TDEIconTheme">TDEIconTheme</ulink> + +Helper classes for TDEIconLoader. + + + +<ulink url="kdeapi:tdecore/KPixmap">KPixmap</ulink> + +A pixmap class with extended dithering capabilities. + + + +<ulink url="kdeapi:tdeui/KPixmapEffect">KPixmapEffect</ulink> + +Pixmap effects like gradients and patterns. + + + +<ulink url="kdeapi:tdeui/KPixmapIO">KPixmapIO</ulink> + +Fast QImage to QPixmap conversion. + + + + + + +Drag and Drop - drag objects for colors and URLs. + + + + +<ulink url="kdeapi:tdecore/KURLDrag">KURLDrag</ulink> + +A drag object for URLs. + + + +<ulink url="kdeapi:tdeui/KColorDrag">KColorDrag</ulink> + +A drag object for colors. + + + +<ulink url="kdeapi:tdecore/KMultipleDrag">KMultipleDrag</ulink> + +Allows to construct drag objects from several others. + + + + + + +Auto-Completion + + + + +<ulink url="kdeapi:tdecore/TDECompletion">TDECompletion</ulink> + +Generic auto-completion of strings. + + + +<ulink url="kdeapi:tdeio/KURLCompletion">KURLCompletion</ulink> + +Auto-completion of URLs. + + + +<ulink url="kdeapi:tdeio/KShellCompletion">KShellCompletion</ulink> + +Auto-completion of executables. + + + + + + +Widgets - widget classes for list views, rules, color selection etc. + + + + +<ulink url="kdeapi:tdeui/TDEListView">TDEListView</ulink> + +A variant of QListView that honors KDE's system-wide settings. + + + +<ulink url="kdeapi:tdeui/TDEListView">TDEListBox</ulink> + +A variant of QListBox that honors KDE's system-wide settings. + + + +<ulink url="kdeapi:tdeui/TDEListView">TDEIconView</ulink> + +A variant of QIconView that honors KDE's system-wide settings. + + + +<ulink url="kdeapi:tdeui/TDEListView">KLineEdit</ulink> + +A variant of QLineEdit with completion support. + + + +<ulink url="kdeapi:tdeui/KComboBox">KComboBox</ulink> + +A variant of QComboBox with completion support. + + + +<ulink url="kdeapi:tdeui/TDEFontCombo">TDEFontCombo</ulink> + +A combo box for selecting fonts. + + + +<ulink url="kdeapi:tdeui/KColorCombo">KColorCombo</ulink> + +A combo box for selecting colors. + + + +<ulink url="kdeapi:tdeui/KColorButton">KColorButton</ulink> + +A button for selecting colors. + + + +<ulink url="kdeapi:tdeui/KURLCombo">KURLCombo</ulink> + +A combo box for selecting file names and URLs. + + + +<ulink url="kdeapi:tdefile/KURLRequester">KURLRequester</ulink> + +A line edit for selecting file names and URLs. + + + +<ulink url="kdeapi:tdeui/KRuler">KRuler</ulink> + +A ruler widget. + + + +<ulink +url="kdeapi:tdeui/KAnimWidget">KAnimWidget</ulink> + +animations. + + + +<ulink url="kdeapi:tdeui/KNumInput">KNumInput</ulink> + +A widget for inputting numbers. + + + +<ulink url="kdeapi:tdeui/KPasswordEdit">KPasswordEdit</ulink> + +A widget for inputting passwords. + + + + + + +Dialogs - full-featured dialogs for file, color and font selection. + + + + +<ulink url="kdeapi:tdefile/KFileDialog">KFileDialog</ulink> + +A file selection dialog. + + + +<ulink url="kdeapi:tdeui/KColorDialog">KColorDialog</ulink> + +A color selection dialog. + + + +<ulink url="kdeapi:tdeui/TDEFontDialog">TDEFontDialog</ulink> + +A font selection dialog. + + + +<ulink url="kdeapi:tdefile/TDEIconDialog">TDEIconDialog</ulink> + +An icon selection dialog. + + + +<ulink url="kdeapi:tdeui/KKeyDialog">KKeyDialog</ulink> + +A dialog for editing keyboard bindings. + + + +<ulink url="kdeapi:tdeui/KEditToolBar">KEditToolBar</ulink> + +A dialog for editing toolbars. + + + +<ulink url="kdeapi:tdeui/KTipDialog">KTipDialog</ulink> + +A Tip-of-the-day dialog. + + + +<ulink url="kdeapi:tdeui/TDEAboutDialog">TDEAboutDialog</ulink> + +An about dialog. + + + +<ulink url="kdeapi:tdeui/KLineEditDlg">KLineEditDlg</ulink> + +A simple dialog for entering text. + + + +<ulink url="kdeapi:tdefile/KURLRequesterDlg">KURLRequesterDlg</ulink> + +A simple dialog for entering URLs. + + + +<ulink url="kdeapi:tdeui/KMessageBox">KMessageBox</ulink> + +A dialog for signaling errors and warnings. + + + +<ulink url="kdeapi:tdeui/KPasswordDialog">KPasswordDialog</ulink> + +A dialog for inputting passwords. + + + + + + +Actions and XML GUI + + + + +<ulink url="kdeapi:tdeui/TDEAction">TDEAction</ulink> + +Abstraction for an action that can be plugged into menu bars and tool bars. + + + +<ulink url="kdeapi:tdeui/TDEActionCollection">TDEActionCollection</ulink> + +A set of actions. + + + +<ulink url="kdeapi:tdeui/KXMLGUIClient">KXMLGUIClient</ulink> + +A GUI fragment consisting of an action collection and a DOM tree representing their location in the GUI. + + + +<ulink url="kdeapi:tdeparts/KPartManager">KPartManager</ulink> + +Manages the activation of XMLGUI clients. + + + + + + +Plugins and Components + + + + +<ulink url="kdeapi:tdecore/KLibrary">KLibrary</ulink> + +Represents a dynamically loaded library. + + + +<ulink url="kdeapi:tdecore/KLibrary">KLibLoader</ulink> + +Shared library loading. + + + +<ulink url="kdeapi:tdecore/KLibFactory">KLibFactory</ulink> + +Object factory in plugins. + + + +<ulink url="kdeapi:tdeio/KServiceType">KServiceType</ulink> + +Represents a service type. + + + +<ulink url="kdeapi:tdeio/KService">KService</ulink> + +Represents a service. + + + +<ulink url="kdeapi:tdeio/KMimeType">KMimeType</ulink> + +Represents a MIME type. + + + +<ulink url="kdeapi:tdeio/KServiceTypeProfile">KServiceTypeProfile</ulink> + +User preferences for MIME type mappings. + + + +<ulink url="kdeapi:tdeio/KServiceTypeProfile">TDETrader</ulink> + +Querying for services. + + + + + + + + + + + + +Graphics + + +Low-level graphics with QPainter + + +Rendering with QPainter + + +Qt's low level imaging model is based on the capabilities provided by X11 and +other windowing systems for which Qt ports exist. But it also extends these by +implementing additional features such as arbitrary affine transformations for +text and pixmaps. + + + +The central graphics class for 2D painting with Qt is +QPainter. It can +draw on a +QPaintDevice. +There are three possible paint devices implemented: One is +QWidget +which represents a widget on the screen. The second is +QPrinter which +represents a printer and produces Postscript output. The third it +the class +QPicture which +records paint commands and can save them on disk and play them back +later. A possible storage format for paint commands is the W3C standard +SVG. + + + +So, it is possible to reuse the rendering code you use for displaying a +widget for printing, with the same features supported. Of course, in +practice, the code is used in a slightly different context. Drawing +on a widget is almost exclusively done in the paintEvent() method +of a widget class. + + + +void FooWidget::paintEvent() +{ + QPainter p(this); + // Setup painter + // Use painter +} + + + +When drawing on a printer, you have to make sure to use QPrinter::newPage() +to finish with a page and begin a new one - something that naturally is not +relevant for painting widgets. Also, when printing, you may want to use the +device metrics +in order to compute coordinates. + + + + + + +Transformations + + +By default, when using QPainter, it draws in the natural coordinate +system of the device used. This means, if you draw a line along the horizontal +axis with a length of 10 units, it will be painted as a horizontal line +on the screen with a length of 10 pixels. However, QPainter can apply arbitrary +affine transformations before actually rendering shapes and curves. An +affine transformation maps the x and y coordinates linearly into x' and +y' according to + + + + + + + +The 3x3 matrix in this equation can be set with QPainter::setWorldMatrix() and +is of type QWMatrix. +Normally, this is the identity matrix, i.e. m11 and m22 are one, and the +other parameters are zero. There are basically three different groups of +transformations: + + + + + +Translations + +These move all points of an object by a fixed amount in +some direction. A translation matrix can be obtained by calling +method m.translate(dx, dy) for a QWMatrix. This corresponds to the +matrix + + + + + + + + + + +Scaling + +These stretch or shrink the coordinates of an object, making +it bigger or smaller without distorting it. A scaling transformation +can be applied to a QWMatrix by calling m.scale(sx, sy). This corresponds +to the matrix + + + + + + + + +By setting one of the parameters to a negative value, one can +achieve a mirroring of the coordinate system. + + + + + +Shearing + +A distortion of the coordinate system with two +parameters. A shearing transformation can be applied by calling +m.shear(sh, sv), corresponding to the matrix + + + + + + + + + + +Rotating + +This rotates an object. A rotation transformation can be +applied by calling m.rotate(alpha). Note that the angle has to be given +in degrees, not as mathematical angle! The corresponding matrix is + + + + + + + + +Note that a rotation is equivalent with a combination of +scaling and shearing. + + + + + + + +Here are some pictures that show the effect of the elementary +transformation to our masquot: + + + + + + + + + + + + + + + + + + + + +a) Normal +b) Rotated by 30 degrees +c) Sheared by 0.4 +d) Mirrored + + + + + + +Transformations can be combined by multiplying elementary matrices. Note that +matrix operations are not commutative in general, and therefore the combined +effect of of a concatenation depends on the order in which the matrices are +multiplied. + + + + + + +Setting stroking attributes + + +The rendering of lines, curves and outlines of polygons can be modified by +setting a special pen with QPainter::setPen(). The argument of this function is a +QPen object. The properties +stored in it are a style, a color, a join style and a cap style. + + + +The pen style is member of the enum +Qt::PenStyle. +and can take one of the following values: + + + + + + + +The join style is a member of the enum +Qt::PenJoinStyle. +It specifies how the junction between multiple lines which are attached to each +other is drawn. It takes one of the following values: + + + + + + + + + + + + + + + + + +a) MiterJoin +c) BevelJoin +b) RoundJoin + + + + + + +The cap style is a member of the enum +Qt::PenCapStyleand specifies how the end points of lines are drawn. It takes one of the values +from the following table: + + + + + + + + + + + + + + + + + +a) FlatCap +b) SquareCap +c) RoundCap + + + + + + + + + +Setting fill attributes + + +The fill style of polygons, circles or rectangles can be modified by setting +a special brush with QPainter::setBrush(). This function takes a +QBrush object as argument. +Brushes can be constructed in four different ways: + + + + +QBrush::QBrush() - This creates a brush that does not fill shapes. + + +QBrush::QBrush(BrushStyle) - This creates a black brush with one of the default +patterns shown below. + + +QBrush::QBrush(const QColor &, BrushStyle) - This creates a colored brush +with one of the patterns shown below. + + +QBrush::QBrush(const QColor &, const QPixmap) - This creates a colored +brush with the custom pattern you give as second parameter. + + + + +A default brush style is from the enum +Qt::BrushStyle. +Here is a picture of all predefined patterns: + + + + + + + +A further way to customize the brush behavior is to use the function +QPainter::setBrushOrigin(). + + + + + + +Color + + +Colors play a role both when stroking curves and when filling shapes. In Qt, +colors are represented by the class +QColor. Qt does not support +advanced graphics features like ICC color profiles and color correction. Colors +are usually constructed by specifying their red, green and blue components, as +the RGB model is the way pixels are composed of on a monitor. + + + +It is also possible to use hue, saturation and value. This HSV representation is +what you use in the Gtk color dialog, e.g. in GIMP. There, the hue corresponds +to the angle on the color wheel, while the saturation corresponds to the +distance from the center of the circle. The value can be chosen with a separate +slider. + + + + + + +Other settings + + +Normally, when you paint on a paint device, the pixels you draw replace those +that were there previously. This means, if you paint a certain region with +a red color and paint the same region with a blue color afterwards, only +the blue color will be visible. Qt's imaging model does not support +transparency, i.e. a way to blend the painted foreground with the background. +However, there is a simple way to combine background and foreground with +boolean operators. The method QPainter::setRasterOp() sets the used operator, +which comes from the enum +RasterOp. + + + +The default is CopyROP which ignores the background. Another popular choice is +XorROP. If you paint a black line with this operator on a colored image, then +the covered area will be inverted. This effect is for example used to create +the rubberband selections in image manipulation programs known as +"marching ants". + + + + + + +Drawing graphics primitives + + +In the following we list the elementary graphics elements supported by +QPainter. Most of them exist in several overloaded versions which take a +different number of arguments. For example, methods that deal with rectangles +usually either take a +QRect as argument or a set +of four integers. + + + + +Drawing a single point - drawPoint(). + + +Drawing lines - drawLine(), drawLineSegments() and drawPolyLine(). + + +Drawing and filling rectangles - drawRect(), drawRoundRect(), +fillRect() and eraseRect(). + + +Drawing and filling circles, ellipses and parts or them - +drawEllipse(), drawArc(), drawPie and drawChord(). + + +Drawing and filling general polygons - drawPolygon(). + + +Drawing bezier curves - drawQuadBezier() [drawCubicBezier in Qt 3.0]. + + + + + + + +Drawing pixmaps and images + + +Qt provides two very different classes to represent images. + + + +QPixmap directly corresponds +to the pixmap objects in X11. Pixmaps are server-side objects and may - on a +modern graphics card - even be stored directly in the card's memory. This makes +it very efficient to transfer pixmaps to the screen. Pixmaps also act as +an off-screen equivalent of widgets - the QPixmap class is a subclass of +QPaintDevice, so you can draw on it with a QPainter. Elementary drawing +operations are usually accelerated by modern graphics. Therefore, a common usage +pattern is to use pixmaps for double buffering. This means, instead of painting +directly on a widget, you paint on a temporary pixmap object and use the +bitBlt +function to transfer the pixmap to the widget. For complex repaints, this helps +to avoid flicker. + + + +In contrast, QImage objects +live on the client side. Their emphasis in on providing direct access to the +pixels of the image. This makes them of use for image manipulation, and things +like loading and saving to disk (QPixmap's load() method takes QImage as +intermediate step). On the other hand, painting an image on a widget is a +relatively expensive operation, as it implies a transfer to the X server, +which can take some time, especially for large images and for remote servers. +Depending on the color depth, the conversion from QImage to QPixmap may also +require dithering. + + + + + + +Drawing text + + +Text can be drawn with one of the overloaded variants of the method +QPainter::drawText(). These draw a QString either at a given point or in a given +rectangle, using the font set by QPainter::setFont(). There is also a parameter +which takes an ORed combination of some flags from the enums +Qt::AlignmentFlags +and +Qt::TextFlags + + + +Beginning with version 3.0, Qt takes care of the complete text layout even for +languages written from right to left. + + + +A more advanced way to display marked up text is the +QSimpleRichText +class. Objects of this class can be constructed with a piece of text using +a subset of the HTML tags, which is quite rich and provides even tables. +The text style can be customized by using a +QStyleSheet (the +documentation of the tags can also be found here). Once the rich text object has +been constructed, it can be rendered on a widget or another paint device with +the QSimpleRichText::draw() method. + + + + + + + + +Structured graphics with QCanvas + + +QPainter offers a powerful imaging model for painting on widgets and pixmaps. +However, it can also be cumbersome to use. Each time your widget receives +a paint event, it has to analyze the QPaintEvent::region() or +QPaintEvent::rect() which has to be redrawn. Then it has to setup a +QPainter and paint all objects which overlap with that region. For example, +image a vector graphics program which allows to drag objects like polygons, +circles and groups of them around. Each time those objects move a bit, the +widget's mouse event handler triggers a paint event for the whole area covered +by the objects in their old position and in their new position. Figuring +out the necessary redraws and doing them in an efficient way can be difficult, +and it may also conflict with the object-oriented structure of the program's +source code. + + + +As an alternative, Qt contains the class +QCanvas in which +you put graphical objects like polygons, text, pixmaps. You may also provide +additional items by subclassing +QCanvasItem or +one of its more specialized subclasses. A canvas can be shown on the screen by +one or more widgets of the class +QCanvasView which +you have to subclass in order to handle user interactions. Qt takes care of +all repaints of objects in the view, whether they are caused by the widget +being exposed, new objects being created or modified or other things. By using +double buffering, this can be done in an efficient and flicker-free way. + + + +Canvas items can overlap each other. In this case, the visible one depends on +the z order which can be assigned by QCanvasItem::setZ(). Items can also be +made visible or invisible. You can also provide a background to be drawn +"behind" all items and a foreground. For associating mouse events with objects, +in the canvas, there is the method QCanvas::collisions() which returns a list +of items overlapping with a given point. Here we show a screenshot of a canvas +view in action: + + + + + + + +Here, the mesh is drawn in the background. Furthermore, there is a +QCanvasText item and a violet QCanvasPolygon. The butterfly is a +QCanvasPixmap. It has transparent areas, so you can see the underlying +items through it. + + + +A tutorial on using QCanvas for writing sprite-based games can be +found here. + + + + + + +3D graphics with OpenGL + + +Low-level interface + + +The de facto standard for rendering 3D graphics today is +OpenGL. Implementations of this +specification come with Microsoft Windows, Mac OS X and XFree86 and often +support the hardware acceleration features offered by modern graphics cards. +OpenGL itself only deals with rendering on a specified area of the framebuffer +through a GL context and does not have any interactions +with the toolkit of the environment + + + +Qt offers the widget QGLWidget +which encapsulates a window with an associated GL context. Basically, you use it +by subclassing it and reimplementing some methods. + + + + + +Instead of reimplementing paintEvent() and using QPainter to draw the widget's +contents, you override paintGL() and use GL commands to render a scene. QLWidget +will take care of making its GL context the current one before paintGL() is +called, and it will flush afterwards. + + + +The virtual method initializeGL() is called once before the first time resizeGL() +or paintGL() are called. This can be used to construct display lists for objects, +and make any initializations. + + + +Instead of reimplementing resizeEvent(), you override resizeGL(). This can +be used to set the viewport appropriately. + + + +Instead of calling update() when the state of the scene has changed - for example +when you animate it with a timer -, you should call updateGL(). This will trigger +a repaint. + + + + + +In general, QGLWidget behaves just like any other widget, i.e. for example +you can process mouse events as usual, resize the widget and combine it with +others in a layout. + + + + + + + +Qt contains some examples of QGLWidget usage in its demo +example. A collection of tutorials can be found +here, +and more information and a reference of OpenGL is available on the +OpenGL homepage. + + + + + + +High-level interfaces + + +OpenGL is a relatively low-level interface for drawing 3D graphics. In the same +way QCanvas gives the programmer a higher-level interface which details with +objects and their properties, there are also high-level interfaces for 3D graphics. +One of the most popular is Open Inventor. Originally a technology developed by SGI, +there is today also the open source implementation +Coin, complemented by a toolkit binding to Qt +called SoQt. + + + +The basic concept of Open Inventor is that of a scene. +A scene can be loaded from disk and saved in a special format closely related +to VRML. A scene consists of a +collection of objects called nodes. Inventor already +provides a rich collection of reusable nodes, such as cubes, cylinders and +meshes, furthermore light sources, materials, cameras etc. Nodes are +represented by C++ classes and can be combined and subclassed. + + + +An introduction to Inventor can be found +here +(in general, you can substitute all mentions of SoXt by SoQt in this article). + + + + + + + + + + + +User interface + + +The action pattern + + + + + + + +Defining menus and toolbars in XML + + +Introduction + + +While the action pattern +allows to encapsulate actions triggered by the user in an object which can be +"plugged" somewhere in the menu bars or toolbars, it does not by itself solve +the problem of constructing the menus themselves. In particular, you have to +build all popup menus in C++ code and explicitly insert the actions in a +certain order, under consideration of the style guide for standard actions. +This makes it pretty difficult to allow the user to customize the menus or +change shortcuts to fit his needs, without changing the source code. + + + +This problem is solved by a set of classes called XMLGUI. +Basically, this separates actions (coded in C++) from their appearance in menu +bars and tool bars (coded in XML). Without modifying any source code, menus +can be simply customized by adjusting an XML file. Furthermore, it helps +to make sure that standard actions (such as +FileOpen +or HelpAbout) +appear in the locations suggested by the style guide. XMLGUI is especially +important for modular programs, where the items appearing in the menu bar may +come from many different plugins or parts. + + + +KDE's class for toplevel windows, +TDEMainWindow, +inherits +KXMLGUIClient +and therefore supports XMLGUI out of the box. All actions created within it must +have the client's actionCollection() as parent. A call to +createGUI() will then build the whole set of menu and tool +bars defined the applications XML file (conventionally with the suffix +ui.rc). + + + + + + +An example: Menu in KView + + +In the following, we take KDE's image view KView as +example. It has a ui.rc file named +kviewui.rc which is installed with the +Makefile.am snippet + + + +rcdir = $(kde_datadir)/kview +rc_DATA = kviewui.rc + + + +Here is an excerpt from the kviewui.rc file. For +simplicity, we show only the definition of the View menu. + + + +<!DOCTYPE kpartgui> +<kpartgui name="kview"> + <MenuBar> + <Menu name="view" > + <Action name="zoom50" /> + <Action name="zoom100" /> + <Action name="zoom200" /> + <Action name="zoomMaxpect" /> + <Separator/> + <Action name="fullscreen" /> + </Menu> + </MenuBar> +</kpartgui> + + + +The corresponding part of the setup in C++ is: + + + + KStdAction::zoomIn ( this, SLOT(slotZoomIn()), actionCollection() ); + KStdAction::zoomOut ( this, SLOT(slotZoomOut()), actionCollection() ); + KStdAction::zoom ( this, SLOT(slotZoom()), actionCollection() ); + new TDEAction ( i18n("&Half size"), ALT+Key_0, + this, SLOT(slotHalfSize()), + actionCollection(), "zoom50" ); + new TDEAction ( i18n("&Normal size"), ALT+Key_1, + this, SLOT(slotDoubleSize()), + actionCollection(), "zoom100" ); + new TDEAction ( i18n("&Double size"), ALT+Key_2, + this, SLOT(slotDoubleSize()), + actionCollection(), "zoom200" ); + new TDEAction ( i18n("&Fill Screen"), ALT+Key_3, + this, SLOT(slotFillScreen()), + actionCollection(), "zoomMaxpect" ); + new TDEAction ( i18n("Fullscreen &Mode"), CTRL+SHIFT+Key_F, + this, SLOT(slotFullScreen()), + actionCollection(), "fullscreen" ); + + + +The View menu resulting from this GUI definition looks like +in this screenshot: + + + + + + + +The XML file begins with a document type declaration. The DTD for kpartgui can +be found in the tdelibs sources in tdeui/kpartgui.dtd. The +outermost element of the file contains the instance name of the application as +attribute. It can also contain a version number in the form "version=2". This +is useful when you release new versions of an application with a changed menu +structure, e.g. with more features. If you bump up the version number of the +ui.rc file, KDE makes sure that any customized version of +the file is discarded and the new file is used instead. + + + +The next line, <MenuBar>, contains a declaration of a +menu bar. You can also insert any number of <ToolBar> +declarations in order to create some tool bars. The menu contains a submenu +with the name "view". This name is already predefined, and thus you see a +translated version of the word "View" in the screenshot. If you declare your +own submenus, you have to add the title explicitly. For example, +KView has a submenu with the title "Image" which is +declared as follows: + + + +<Menu name="image" > + <text>&amp;Image</text> + ... +</Menu> + + + +In KDE's automake framework, such titles are automatically extracted and put +into the application's .po +file , so it is considered by translators. Note that you have to write the +accelerator marker "&" in the form XML compliant form "&amp;". + + + +Let us come back to the example. KView's +View menu contains a couple of custom actions: +zoom50, zoom100, +zoom200, zoomMaxpect and +fullscreen, declared with a +<Action> element. The separator in the +screenshots corresponds to the <Separator> element. + + + +You will note that some menu items do not not have a corresponding element in +the XML file. These are standard actions. Standard +actions are created by the class +KStdAction. +When you create such actions in your application (such as in the C++ example +above), they will automatically be inserted in a prescribed position, and +possibly with an icon and a shortcut key. You can look up these locations in +the file tdeui/ui_standards.rc in the tdelibs sources. + + + + + + +An example: Toolbars in Konqueror + + +For the discussion of toolbars, we switch to +Konqueror's GUI definition. This excerpt defines +the location bar, which contains the input field for URLs. + + + +<ToolBar name="locationToolBar" fullWidth="true" newline="true" > + <text>Location Toolbar</text> + <Action name="clear_location" /> + <Action name="location_label" /> + <Action name="toolbar_url_combo" /> + <Action name="go_url" /> +</ToolBar> + + + +The first thing we notice is that there are a lot more attributes than for +menu bars. These include: + + + + + +fullWidth: Tells XMLGUI that the toolbar has the same width as the + toplevel window. Af this is "false", the toolbar only takes as much space as + necessary, and further toolbars are put in the same row. + + + +newline: This is related to the option above. If newline is "true", +the toolbar starts a new row. Otherwise it may be put in the row together +with the previous toolbar. + + + +noEdit: Normally toolbars can be customized by the user, +e.g. in SettingsConfigure +Toolbars in +Konqueror. Setting this option to "true" marks this +toolbar as not editable. This is important for toolbars which are filled with +items at runtime, e.g. Konqueror's bookmark toolbar. + + + +iconText: Tells XMLGUI to show the text of the action next to the +icon. Normally, the text is only shown as a tooltip when the mouse cursor +remains over the icon for a while. Possible values for this attribute are +"icononly" (shows only the icon), "textonly" (shows only the text), +"icontextright" (shows the text on the right side of the icon) and +"icontextbottom" (shows the text beneath the icon). + + + + +hidden: If this is "true", the toolbar is not visible initially +and must be activated by some menu item. + + + + +position: The default for this attribute is "top", meaning that the +toolbar is positioned under the menu bar. For programs with many tools, +such as graphics programs, it may be interesting to replace this with +"left", "right" or "bottom". + + + + + + + + +Dynamical menus + + +Obviously, an XML can only contain a static description of a user interface. +Often, there are menus which change at runtime. For example, +Konqueror's Location menu +contains a set of items Open with Foo with the +applications able to load a file with a given MIME type. Each time the +document shown changes, the list of menu items is updated. XMLGUI is prepared +to handle such cases with the notion of action lists. +An action list is declared as one item in the XML file, but consists of +several actions which are plugged into the menu at runtime. The above example +is implemented with the following declaration in +Konqueror's XML file: + + + +<Menu name="file"> + <text>&amp;Location</text> + ... + <ActionList name="openwith"> + ... +</Menu> + + + +The function KXMLGUIClient::plugActionList() is then used +to add actions to be displayed, whereas the function +KXMLGuiClient::unplugActionList() removes all +plugged actions. The routine responsible for updating looks as follows: + + + +void MainWindow::updateOpenWithActions() +{ + unplugActionList("openwith"); + openWithActions.clear(); + for ( /* iterate over the relevant services */ ) { + TDEAction *action = new TDEAction( ...); + openWithActions.append(action); + } + plugActionList("openwith", openWithActions); +} + + + +Note that in contrast to the static actions, the ones created here are +not constructed with the action collection as parent, and +you are responsible for deleting them for yourself. The simplest way to achievethis +is by using openWithActions.setAutoDelete(true) in the above +example. + + + + + + +Context menus + + +The examples above only contained cases where a main window's menubar and +toolbars were created. In the cases, the processes of constructing these +containers is completely hidden from you behind the +createGUI() call (except if you have custom containers). +However, there are cases, where you want to construct other containers and +populate them with GUI definitions from the XML file. One such example are +context menus. In order to get a pointer to a context menu, you have to +ask the client's factory for it: + + + +void MainWindow::popupRequested() +{ + QWidget *w = factory()->container("context_popup", this); + QPopupMenu *popup = static_cast<QPopupMenu *>(w); + popup->exec(QCursor::pos()); +} + + + +The method KXMLGUIFactory::container() used above looks +whether it finds a container in the XML file with the given name. Thus, a +possible definition could look as follows: + + + +... +<Menu name="context_popup"> + <Action name="file_add"/> + <Action name="file_remove"/> +</Menu> +... + + + + + + + + +Providing online help + + +Making a program easy and intuitive to use involves a wide range of +facilities which are usually called online help. Online help has several, +partially conflicting goals: on the one, it should give the user answers +to the question "How can I do a certain task?", on the other hand it +should help the user exploring the application and finding features he +doesn't yet know about. It is important to recognize that this can only +be achieved by offering several levels of help: + + + + + +Tooltips are tiny labels that pop up over user interface elements when +the mouse remains there longer. They are especially important for tool- +bars, where icons are not always sufficient to explain the purpose of +a button. + + + +"What's this?" help is usually a longer and richer explanation of a widget +or a menu item. It is also more clunky to use: In dialogs, it can be invoked +in two ways: either by pressing +ShiftF1 or by clicking +on the question mark in the title bar (where the support of the latter depends +on the window manager). The mouse pointer then turns into an arrow with a +question mark, and the help window appears when a user interfact element has +been clicked. "What's this?" help for menu items is usually activated by a +button in the toolbar which contains an arrow and a question mark. + + + +The problem with this approach is that the user can't see whether a widget +provides help or not. When the user activates the question mark button and +doesn't get any help window when clicking on a user interface element, he +will get frustrated very quickly. + + + +The advantage of "What's this?" help windows as provided by Qt and KDE is that +they can contain rich text, +i.e. the may contain different fonts, bold and italic text and even images and tables. + + + +An example of "What's this?" help: + + + + + + + + + +Finally, every program should have a manual. A manual is normally viewed in +KHelpCenter by activating the +Help menu. That means, a complete additional application +pops up and diverts the user from his work. Consequently, consulting the +manual should only be necessary if other facilities like tooltips and what's +this help are not sufficient. Of course, a manual has the advantage that it +does not explain single, isolated aspects of the user interface. Instead, it +can explain aspects of the application in a greater context. Manuals for KDE +are written using the DocBook markup +language. + + + + + +From the programmer's point of view, Qt provides an easy to use API for online +help. To assign a tooltip to widget, use the +QToolTip class. + + + +QToolTip::add(w, i18n("This widget does something.")) + + + +If the menu bars and tool bars are created using the +action pattern, the string used as tooltip is derived from the first argument +of the TDEAction constructor: + + + +action = new TDEAction(i18n("&Delete"), "editdelete", + SHIFT+Key_Delete, actionCollection(), "del") + + + +Here it is also possible to assign a text which is shown in the status bar when the +respective menu item is highlighted: + + + +action->setStatusText(i18n("Deletes the marked file")) + + + +The API for "What's this?' help is very similar. In dialogs, use the following +code: + + + +QWhatsThis::add(w, i18n("<qt>This demonstrates <b>Qt</b>'s" + " rich text engine.<ul>" + "<li>Foo</li>" + "<li>Bar</li>" + "</ul></qt>")) + + + +For menu items, use + + + +action->setWhatsThis(i18n("Deletes the marked file")) + + + +The invocation of KHelpCenter is encapsulated in the +TDEApplication +class. In order to show the manual of your application, just use + + + +kapp->invokeHelp() + + + +This displays the first page with the table of contents. When you want to +display only a certain section of the manual, you can give an additional +argument to invokeHelp() determining the anchor which +the browser jumps to. + + + + + + + + + +Components and services + + +KDE services + + +What are KDE services? + + +The notion of a service is a central concept in KDE's +modular architecture. There is no strict technical implementation connected +with this term - services can be plugins in the form of shared libraries, +or they can be programs controlled via DCOP. +By claiming to be of a certain service type, a service +promises to implement certain APIs or features. In C++ terms, one can think +of a service type as an abstract class, and a service as an implementation +of that interface. + + + +The advantage of this separation is clear: An application utilizing a service +type does not have to know about possible implementations of it. It just uses +the APIs associated with the service type. In this way, the used service can be +changed without affecting the application. Also, the user can configure which +services he prefers for certain features. + + + +Some examples: + + + + + +The HTML rendering engine used in Konqueror is an +embedable component that implements the service types +KParts/ReadOnlyPart and Browser/View. + + +In TDevelop HEAD, most functionality is packaged in +plugins with the service type TDevelop/Part. At startup, +all services with this type are loaded, such that you can extend the IDE in a +very flexible way. + + +In the icon view, Konqueror displays - if enabled - +thumbnail pictures of images, HTML pages, PDF and text files. This ability can +be extended. If you want it to display preview pictures of your own data files +with some MIME type, you can implement a service with service type +ThumbCreator. + + + + + +Obviously, a service is not only characterized by the service types it +implements, but also by some properties. For example, a +ThumbCreator does not only claim to implement the C++ class with the type +ThumbCreator, it also has a list of MIME types it is +responsible for. Similarly, TDevelop parts have the programming language they +support as a property. When an application requests a service type, it can +also list constraints on the properties of the service. In the above example, +when TDevelop loads the plugins for a Java project, it asks only for the +plugins which have Java as the programming language property. For this +purpose, KDE contains a full-blown CORBA-like trader with +a complex query language. + + + + + + +Defining service types + + +New service types are added by installing a description of them into the +directory TDEDIR/share/servicetypes. In an automake +framework, this can be done with this Makefile.am +snippet: + + + +kde_servicetypesdir_DATA = tdeveloppart.desktop +EXTRA_DIST = $(kde_servicetypesdir_DATA) + + + +The definition tdeveloppart.desktop of a +TDevelop part looks as follows: + + + +[Desktop Entry] +Type=ServiceType +X-TDE-ServiceType=TDevelop/Part +Name=TDevelop Part + +[PropertyDef::X-TDevelop-Scope] +Type=QString + +[PropertyDef::X-TDevelop-ProgrammingLanguages] +Type=QStringList + +[PropertyDef::X-TDevelop-Args] +Type=QString + + + +In addition to the usual entries, this example demonstrates how you declare +that a service has some properties. Each property definition corresponds +to a group [PropertyDef::name] in the configuration file. In +this group, the Type entry declares the type of the property. +Possible types are everything that can be stored in a +QVariant. + + + + + + +Defining shared library services + + +Service definitions are stored in the directory +TDEDIR/share/services: + + + +kde_servicesdir_DATA = kdevdoxygen.desktop +EXTRA_DIST = $(kde_servicesdir_DATA) + + + +The content of the following example file +tdevdoxygen.desktop defines the +KDevDoxygen plugin with the service type +TDevelop/Part: + + + +[Desktop Entry] +Type=Service +Comment=Doxygen +Name=KDevDoxygen +ServiceTypes=TDevelop/Part +X-TDE-Library=libtdevdoxygen +X-TDevelop-ProgrammingLanguages=C,C++,Java +X-TDevelop-Scope=Project + + + +In addition to the usual declarations, an important entry is +X-TDE-Library. This contains the name of the libtool +library (without the .la extension). It also fixes +(with the prefix init_ prepended) the name of the exported +symbol in the library which returns an object factory. For the above example, +the library must contain the following function: + + + +extern "C" { + void *init_libtdevdoxygen() + { + return new DoxygenFactory; + } +}; + + + +The type of the factory class DoxygenFactory depends on +the specific service type the service implements. In our example of a TDevelop +plugin, the factory must be a KDevFactory (which +inherits KLibFactory). More common examples are +KParts::Factory +which is supposed to produce +KParts::ReadOnlyPart +objects or in most cases the generic +KLibFactory. + + + + + + +Using shared library services + + +In order to use a shared library service in an application, you need to obtain a +KService object +representing it. This is discussed in the +section about MIME types (and in a section about the +trader to be written :-) + + + +With the KService object at hand, you can very simply +load the library and get a pointer to its factory object: + + + +KService *service = ... +QString libName = QFile::encodeName(service->library()); +KLibFactory *factory = KLibLoader::self()->factory(libName); +if (!factory) { + QString name = service->name(); + QString errorMessage = KLibLoader::self()->lastErrorMessage(); + KMessageBox::error(0, i18n("There was an error loading service %1.\n" + "The diagnostics from libtool is:\n%2") + .arg(name).arg(errorMessage); +} + + + +From this point, the further proceeding depends again on the service type. For +generic plugins, you create objects with the method +KLibFactory::create(). +For KParts, you must cast the factory pointer to the more specific KParts::Factory and use +its create() method: + + + +if (factory->inherits("KParts::Factory")) { + KParts::Factory *partFactory = static_cast<KParts::Factory*>(factory); + QObject *obj = partFactory->createPart(parentWidget, widgetName, + parent, name, "KParts::ReadOnlyPart"); + ... +} else { + cout << "Service does not implement the right factory" << endl; +} + + + + + + +Defining DCOP services + + +A DCOP service is usually implemented as a program that is started up when it is +needed. It then goes into a loop and listens for DCOP connections. The program +may be an interactive one, but it may also run completely or for a part of its +lifetime as a daemon in the background without the user noticing it. An example +for such a daemon is tdeio_uiserver, which implements user interaction +such as progress dialog for the TDEIO library. The advantage of such a centralized +daemon in this context is that e.g. the download progress for several different +files can be shown in one window, even if those downloads were initiated from +different applications. + + + +A DCOP service is defined differently from a shared library service. Of course, +it doesn't specify a library, but instead an executable. Also, DCOP services +do not specify a ServiceType line, because usually they are started by their +name. As additional properties, it contains two lines: + + + +X-DCOP-ServiceType specifies the way the service is +started. The value Unique says that the service must not be +started more than once. This means, if you try to start this service (e.g. via + +TDEApplication::startServiceByName(), KDE looks whether it is already +registered with DCOP and uses the running service. If it is not registered yet, +KDE will start it up and wait until is registered. Thus, you can immediately +send DCOP calls to the service. In such a case, the service should be implemented +as a +KUniqueApplication. + + + +The value Multi for X-DCOP-ServiceType says that multiple +instances of the service can coexist, so every attempt to start the service +will create another process. As a last possibility the value None +can be used. In this case, a start of the service will not wait until it +is registered with DCOP. + + + +X-TDE-StartupNotify should normally be set to false. Otherwise, when +the program is started, the task bar will show a startup notification, or, depending +on the user's settings, the cursor will be changed. + + + +Here is the definition of tdeio_uiserver: + + + +[Desktop Entry] +Type=Service +Name=tdeio_uiserver +Exec=tdeio_uiserver +X-DCOP-ServiceType=Unique +X-TDE-StartupNotify=false + + + + + + +Using DCOP services + + +A DCOP service is started with one of several methods in the TDEApplication +class: + + + +DCOPClient *client = kapp->dcopClient(); +client->attach(); +if (!client->isApplicationRegistered("tdeio_uiserver")) { + QString error; + if (TDEApplication::startServiceByName("tdeio_uiserver", QStringList(), &error)) + cout << "Starting kioserver failed with message " << error << endl; +} +... +QByteArray data, replyData; +QCString replyType; +QDataStream arg(data, IO_WriteOnly); +arg << true; +if (!client->call("tdeio_uiserver", "UIServer", "setListMode(bool)", + data, replyType, replyData)) + cout << "Call to tdeio_uiserver failed" << endl; +... + + + +Note that the example of a DCOP call given here uses explicit marshalling +of arguments. Often you will want to use a stub generated by dcopidl2cpp +instead, because it is much simpler and less error prone. + + + +In the example given here, the service was started "by name", i.e. the +first argument to TDEApplication::startServiceByName() is +the name is appearing in the Name line of the desktop +file. An alternative is to use +TDEApplication::startServiceByDesktopName(), which takes +the file name of its desktop file as argument, i.e. in this case +"tdeio_uiserver.desktop". + + + +All these calls take a list of URLs as a second argument, which is given +to the service on the command line. The third argument is a pointer to a +QString. If starting the service fails, this argument +is set to a translated error message. + + + + + + + + +MIME types + + +What are MIME types? + + +MIME types are used to describe the content type of files or data +chunks. Originally they were introduced in order to allow sending around image +or sound files etc. by e-mail (MIME stands for "Multipurpose Internet Mail +Extensions"). Later this system was also used by web browsers to determine how +to present data sent by a web server to the user. For example, an HTML page +has a MIME type "text/html", a postscript file "application/postscript". In +KDE, this concept is used at a variety of places: + + + + + +In Konqueror's icon view, files are represented by +icons. Each MIME type has a certain associated icon shown here. + + + +When you click onto a file icon or a file name in +Konqueror, either the file is shown in an embedded +view, or an application associated with the file type is opened. + + + +When you drag and drop some data from one application to another (or +within the same application), the drop target may choose to accept only +certain data types. Furthermore, it will handle image data different +from textual data. + + + +Clipboard data has a MIME type. Traditionally, X programs only handle +pixmaps or texts, but with Qt, there are no restrictions on the data type. + + + + + +From the above examples, it is clear that MIME handling is a complex issue. +First, it is necessary to establish a mapping from file names to MIME types. +KDE goes one step further in allowing even file contents to be mapped to +MIME types, for cases in which the file name is not available. Second, it +is necessary to map MIME types to applications or libraries which can view +or edit a file with a certain type, or create a thumbnail picture for it. + + + +There is a variety of APIs to figure out the MIME type of data or files. In +general, there is a certain speed/reliability trade-off you have to make. You +can find out the type of a file by examining only its file name (i.e. in most +cases the file name extension). For example, a file +foo.jpg is normally "image/jpeg". In cases where the +extension is stripped off this is not safe, and you actually have to look at +the contents of the file. This is of course slower, in particular for files +that have to be downloaded via HTTP first. The content-based method is based +on the file TDEDIR/share/mimelnk/magic and therefore +difficult to extend. But in general, MIME type information can easily be made +available to the system by installing a .desktop file, and +it is efficiently and conveniently available through the KDE libraries. + + + + + + +Defining MIME types + + +Let us define a type "application/x-foo" for our new +foobar program. To this end, you have to write a +file foo.desktop and install it into +TDEDIR/share/mimelnk/application. (This is the usual +location, which may differ between distributions). This can be done by adding +this to the Makefile.am: + + + +mimedir = $(kde_mimedir)/application +mime_DATA = foo.desktop +EXTRA_DIST = $(mime_DATA) + + + +The file foo.desktop should look as follows: + + + +[Desktop Entry] +Type=MimeType +MimeType=application/x-foo +Icon=fooicon +Patterns=*.foo; +DefaultApp=foobar +Comment=Foo Data File +Comment[de]=Foo Datei + + + +The "Comment" entry is supposed to be translated. Since the +.desktop file specifies an icon, you should also install +an icon fooicon.png, which represents the file e.g. in +Konqueror. + + + +In the KDE libraries, such a type definition is mapped to an instance of the +class KMimeType. +Use this like in the following example: + + + +KMimeType::Ptr type = KMimeType::mimeType("application/x-foo"); +cout << "Type: " << type->name() < endl; +cout << "Icon: " << type->icon() < endl; +cout << "Comment: " << type->icon() < endl; +QStringList patterns = type->patterns(); +QStringList::ConstIterator it; +for (it = patterns.begin(); it != patterns.end(); ++it) + cout << "Pattern: " << (*it) << endl; + + + + + + +Determining the MIME type of data + + +The fast method for determining the type of a file is +KMimeType::findByURL(). This looks for the URL string and +in most cases determines the type from the extension. For certain protocols +(e.g. http, man, info), this mechanism is not used. For example, CGI scripts +on web servers written in Perl often have the extension +.pl, which would indicate a +"text/x-perl" type. However, we file delivered by the +server is the output of this script, which is normally HTML. For such a case, +KMimeType::findByURL() returns the MIME type +"application/octet-stream" (available through +KMimeType::defaultMimeType()), which indicates a failure +to find out the type. + + + +KMimeType::Ptr type = KMimeType::findByURL("/home/bernd/foobar.jpg"); +if (type->name() == KMimeType::defaultMimeType()) + cout << "Could not find out type" << endl; +else + cout << "Type: " << type->name() << endl; + + + +(this method has some more arguments, but these are undocumented, so simply +forget about them.) + + + +You may want to find out a MIME from the contents of file instead of +the file name. This is more reliable, but also slower, as it requires +reading a part of the file. This is done with the +KMimeMagic +class, which has different error handling: + + + +KMimeMagicResult *result = KMimeMagic::self()->findFileType("/home/bernd/foobar.jpg"); +if (!result || !result->isValid()) + cout << "Could not find out type" << endl; +else + cout << "Type: " << result->mimeType() << endl; + + + +As a variant of this function, you can also determine the type of a memory +chunk. This is e.g. used in Kate in order to find +out the highlighting mode: + + + +QByteArray array; +... +KMimeMagicResult *result = KMimeMagic::self()->findBufferType(array); +if (!result || !result->isValid()) + cout << "Could not find out type" << endl; +else + cout << "Type: " << result->mimeType() << endl; + + + +Of course, even KMimeMagic is only able to determine a file type from the +contents of a local file. For remote files, there is a further possibility: + + + +KURL url("http://developer.kde.org/favicon.ico"); +QString type = TDEIO::NetAccess::mimetype(url); +if (type == KMimeType::defaultMimeType()) + cout << "Could not find out type" << endl; +else + cout << "Type: " << type << endl; + + + +This starts a TDEIO job to download a part of the file and check this. +Note that this function is perhaps quite slow and blocks the program. Normally +you will only want to use this if KMimeType::findByURL() +has returned "application/octet-stream". + + + +On the other hand, if you do not want to block your application, you can also +explicitly start the TDEIO job and connect to some of its signals: + + + +void FooClass::findType() +{ + KURL url("http://developer.kde.org/favicon.ico"); + TDEIO::MimetypeJob *job = TDEIO::mimetype(url); + connect( job, SIGNAL(result(TDEIO::Job*)), + this, SLOT(mimeResult(TDEIO::Job*)) ); +} + +void FooClass::mimeResult(TDEIO::Job *job) +{ + if (job->error()) + job->showErrorDialog(); + else + cout << "MIME type: " << ((TDEIO::MimetypeJob *)job)->mimetype() << endl; +} + + + + + + +Mapping a MIME type to an application or service + + +When an application is installed, it installs a .desktop +file which contains a list of MIME types this application can load. Similarly, +components like KParts make this information available by their service +.desktop files. So in general, there are several programs +and components which can process a given MIME type. You can obtain such a list +from the class KServiceTypeProfile: + + + +KService::OfferList offers = KServiceTypeProfile::offers("text/html", "Application"); +KService::OfferList::ConstIterator it; +for (it = offers.begin(); it != offers.end(); ++it) { + KService::Ptr service = (*it); + cout << "Name: " << service->name() << endl; +} + + + +The return value of this function is a list of service offers. A +KServiceOffer object packages a KService::Ptr together +with a preference number. The list returned by +KServiceTypeProfile::offers() is ordered by the user's +preference. The user can change this by calling "keditfiletype +text/html" or choosing Edit File Type on +Konqueror's context menu on a HTML file. + + + +In the above example, an offer list of the applications supporting +text/html was requested. This will - among others - contain +HTML editors like Quanta Plus. You can also replace +the second argument "Application" by +"KParts::ReadOnlyPart". In that case, you get a list of +embedable components for presenting HTML content, for example TDEHTML. + + + +In most cases, you are not interested in the list of all service offers +for a combination of MIME type and service type. There is a convenience +function which gives you only the service offer with the highest preference: + + + +KService::Ptr offer = KServiceTypeProfile::preferredService("text/html", "Application"); +if (offer) + cout << "Name: " << service->name() << endl; +else + cout << "No appropriate service found" << endl; + + + +For even more complex queries, there is a full-blown CORBA-like +trader. + + + +In order to run an application service with some URLs, use +KRun: + + + +KURL::List urlList; +urlList << "http://www.ietf.org/rfc/rfc1341.txt?number=1341"; +urlList << "http://www.ietf.org/rfc/rfc2046.txt?number=2046"; +KRun::run(offer.service(), urlList); + + + + + + +Miscellaneous + + +In this section, we want to list some APIs which are loosely related +to the previous discussion. + + + +Getting an icon for a URL. This looks for the type of the URL +and returns the associated icon. + + + +KURL url("ftp://ftp.kde.org/pub/incoming/wibble.c"); +QString icon = KMimeType::iconForURL(url); + + + +Running a URL. This looks for the type of the URL and starts the +user's preferred program associated with this type. + + + +KURL url("http://dot.kde.org"); +new KRun(url); + + + + + + + + +Network transparency + + +Introduction + + +In the age of the world wide web, it is of essential importance that desktop +applications can access resources over the internet: they should be able to +download files from a web server, write files to an ftp server or read mails +from a web server. Often, the ability to access files regardless of their +location is called network transparency. + + + +In the past, different approaches to this goals were implemented. The old NFS +file system is an attempt to implement network transparency on the level of +the POSIX API. While this approach works quite well in local, closely coupled +networks, it does not scale for resources to which access is unreliable and +possibly slow. Here, asynchronicity is important. While +you are waiting for your web browser to download a page, the user interface +should not block. Also, the page rendering should not begin when the page is +completely available, but should updated regularly as data comes in. + + + +In the KDE libraries, network transparency is implemented in the TDEIO API. The +central concept of this architecture is an IO job. A job +may copy, or delete files or similar things. Once a job is started, it works +in the background and does not block the application. Any communication from +the job back to the application - like delivering data or progress information +- is done integrated with the Qt event loop. + + + +Background operation is achieved by starting ioslaves to +perform certain tasks. ioslaves are started as separate processes and are +communicated with through UNIX domain sockets. In this way, no multi-threading +is necessary and unstable slaves can not crash the application that uses them. + + + +File locations are expressed by the widely used URLs. But in KDE, URLs do not +only expand the range of addressable files beyond the local file system. It +also goes in the opposite direction - e.g. you can browse into tar archives. +This is achieved by nesting URLs. For example, a file in a tar archive on +a http server could have the URL + + + +http://www-com.physik.hu-berlin.de/~bernd/article.tgz#tar:/paper.tex + + + + + + +Using TDEIO + + +In most cases, jobs are created by calling functions in the TDEIO namespace. +These functions take one or two URLs as arguments, and possible other +necessary parameters. When the job is finished, it emits the signal +result(TDEIO::Job*). After this signal has been emitted, the job +deletes itself. Thus, a typical use case will look like this: + + + +void FooClass::makeDirectory() +{ + SimpleJob *job = TDEIO::mkdir(KURL("file:/home/bernd/tdeiodir")); + connect( job, SIGNAL(result(TDEIO::Job*)), + this, SLOT(mkdirResult(TDEIO::Job*)) ); +} + +void FooClass::mkdirResult(TDEIO::Job *job) +{ + if (job->error()) + job->showErrorDialog(); + else + cout << "mkdir went fine" << endl; +} + + + +Depending on the type of the job, you may connect also to other +signals. + + + +Here is an overview over the possible functions: + + + + +TDEIO::mkdir(const KURL &url, int permission) + +Creates a directory, optionally with certain permissions. + + + +TDEIO::rmdir(const KURL &url) + +Removes a directory. + + + +TDEIO::chmod(const KURL &url, int permissions) + +Changes the permissions of a file. + + + +TDEIO::rename(const KURL &src, const KURL &dest, + bool overwrite) + +Renames a file. + + + +TDEIO::symlink(const QString &target, const KURL &dest, + bool overwrite, bool showProgressInfo) + +Creates a symbolic link. + + + +TDEIO::stat(const KURL &url, bool showProgressInfo) + +Finds out certain information about the file, such as size, modification +time and permissions. The information can be obtained from +TDEIO::StatJob::statResult() after the job has finished. + + + +TDEIO::get(const KURL &url, bool reload, bool showProgressInfo) + +Transfers data from a URL. + + + +TDEIO::put(const KURL &url, int permissions, bool overwrite, + bool resume, bool showProgressInfo) + +Transfers data to a URL. + + + +TDEIO::http_post(const KURL &url, const QByteArray &data, + bool showProgressInfo) +Posts data. Special for HTTP. + + + +TDEIO::mimetype(const KURL &url, bool showProgressInfo) + +Tries to find the MIME type of the URL. The type can be obtained from +TDEIO::MimetypeJob::mimetype() after the job has finished. + + + +TDEIO::file_copy(const KURL &src, const KURL &dest, int permissions, + bool overwrite, bool resume, bool showProgressInfo) + +Copies a single file. + + + +TDEIO::file_move(const KURL &src, const KURL &dest, int permissions, + bool overwrite, bool resume, bool showProgressInfo) + +Renames or moves a single file. + + + +TDEIO::file_delete(const KURL &url, bool showProgressInfo) + +Deletes a single file. + + + +TDEIO::listDir(const KURL &url, bool showProgressInfo) + +Lists the contents of a directory. Each time some new entries are known, the +signal TDEIO::ListJob::entries() is emitted. + + + +TDEIO::listRecursive(const KURL &url, bool showProgressInfo) + +Similar to the listDir() function, but this one is recursive. + + + +TDEIO::copy(const KURL &src, const KURL &dest, bool showProgressInfo) + +Copies a file or directory. Directories are copied recursively. + + + +TDEIO::move(const KURL &src, const KURL &dest, bool showProgressInfo) + +Moves or renames a file or directory. + + + +TDEIO::del(const KURL &src, bool shred, bool showProgressInfo) + +Deletes a file or directory. + + + + + + + + + +Directory entries + + +Both the TDEIO::stat() and TDEIO::listDir() jobs return their results as a type +UDSEntry, UDSEntryList resp. The latter is defined as QValueList<UDSEntry>. +The acronym UDS stands for "Universal directory service". The principle behind +it is that the a directory entry only carries the information which an ioslave +can provide, not more. For example, the http slave does not provide any +information about access permissions or file owners. +Instead, a UDSEntry is a list of UDSAtoms. Each atom provides a specific piece +of information. It consists of a type stored in m_uds and either an integer +value in m_long or a string value in m_str, depending on the type. + + + +The following types are currently defined: + + + + + +UDS_SIZE (integer) - Size of the file. + + + +UDS_USER (string) - User owning the file. + + + +UDS_GROUP (string) - Group owning the file. + + + +UDS_NAME (string) - File name. + + + +UDS_ACCESS (integer) - Permission rights of the file, as e.g. stored +by the libc function stat() in the st_mode field. + + + +UDS_FILE_TYPE (integer) - The file type, as e.g. stored by stat() in the +st_mode field. Therefore you can use the usual libc macros like S_ISDIR to +test this value. Note that the data provided by ioslaves corresponds to +stat(), not lstat(), i.e. in case of symbolic links, the file type here is +the type of the file pointed to by the link, not the link itself. + + + +UDS_LINK_DEST (string) - In case of a symbolic link, the name of the file +pointed to. + + + +UDS_MODIFICATION_TIME (integer) - The time (as in the type time_t) when the +file was last modified, as e.g. stored by stat() in the st_mtime field. + + + +UDS_ACCESS_TIME (integer) - The time when the file was last accessed, as +e.g. stored by stat() in the st_atime field. + + + +UDS_CREATION_TIME (integer) - The time when the file was created, as e.g. +stored by stat() in the st_ctime field. + + + +UDS_URL (string) - Provides a URL of a file, if it is not simply the +the concatenation of directory URL and file name. + + + +UDS_MIME_TYPE (string) - MIME type of the file + + + +UDS_GUESSED_MIME_TYPE (string) - MIME type of the file as guessed by the +slave. The difference to the previous type is that the one provided here +should not be taken as reliable (because determining it in a reliable way +would be too expensive). For example, the KRun class explicitly checks the +MIME type if it does not have reliable information. + + + + + +Although the way of storing information about files in a +UDSEntry is flexible and practical from the ioslave +point of view, it is a mess to use for the application programmer. For +example, in order to find out the MIME type of the file, you have to iterate +over all atoms and test whether m_uds is +UDS_MIME_TYPE. Fortunately, there is an API which is a lot +easier to use: the class KFileItem. + + + + + + +Synchronous usage + + +Often, the asynchronous API of TDEIO is too complex to use and therefore +implementing full asynchronicity is not a priority. For example, in a program +that can only handle one document file at a time, there is little that can be +done while the program is downloading a file anyway. For these simple cases, +there is a mucher simpler API in the form of a set of static functions in +TDEIO::NetAccess. For example, in order to copy a file, use + + + +KURL source, target; +source = ...; +target = ... +TDEIO::NetAccess::copy(source, target); + + + +The function will return after the complete copying process has finished. Still, +this method provides a progress dialog, and it makes sure that the application +processes repaint events. + + + +A particularly interesting combination of functions is +download() in combination with +removeTempFile(). The former downloads a file from given +URL and stores it in a temporary file with a unique name. The name is stored +in the second argument. If the URL is local, the file is +not downloaded, and instead the second argument is set to the local file +name. The function removeTempFile() deletes the file +given by its argument if the file is the result of a former download. If that +is not the case, it does nothing. Thus, a very easy to use way of loading +files regardless of their location is the following code snippet: + + + +KURL url; +url = ...; +QString tempFile; +if (TDEIO::NetAccess::download(url, tempFile) { + // load the file with the name tempFile + TDEIO::NetAccess::removeTempFile(tempFile); +} + + + + + + +Meta data + + +As can be seen above, the interface to IO jobs is quite abstract and does not +consider any exchange of information between application and IO slave that +is protocol specific. This is not always appropriate. For example, you may give +certain parameters to the HTTP slave to control its caching behavior or +send a bunch of cookies with the request. For this need, the concept of meta +data has been introduced. When a job is created, you can configure it by adding +meta data to it. Each item of meta data consists of a key/value pair. For +example, in order to prevent the HTTP slave from loading a web page from its +cache, you can use: + + + +void FooClass::reloadPage() +{ + KURL url("http://www.kdevelop.org/index.html"); + TDEIO::TransferJob *job = TDEIO::get(url, true, false); + job->addMetaData("cache", "reload"); + ... +} + + + +The same technique is used in the other direction, i.e. for communication from +the slave to the application. The method +Job::queryMetaData() asks for the value of the certain +key delivered by the slave. For the HTTP slave, one such example is the key +"modified", which contains a (stringified representation of) +the date when the web page was last modified. An example how you can use this +is the following: + + + +void FooClass::printModifiedDate() +{ + KURL url("http://developer.kde.org/documentation/kde2arch/index.html"); + TDEIO::TransferJob *job = TDEIO::get(url, true, false); + connect( job, SIGNAL(result(TDEIO::Job*)), + this, SLOT(transferResult(TDEIO::Job*)) ); +} + +void FooClass::transferResult(TDEIO::Job *job) +{ + QString mimetype; + if (job->error()) + job->showErrorDialog(); + else { + TDEIO::TransferJob *transferJob = (TDEIO::TransferJob*) job; + QString modified = transferJob->queryMetaData("modified"); + cout << "Last modified: " << modified << endl; +} + + + + + + +Scheduling + + +When using the TDEIO API, you usually do not have to cope with the details of +starting IO slaves and communicating with them. The normal use case is to +start a job and with some parameters and handle the signals the jobs emits. + + + +Behind the curtains, the scenario is a lot more complicated. When you create a +job, it is put in a queue. When the application goes back to the event loop, +TDEIO allocates slave processes for the jobs in the queue. For the first jobs +started, this is trivial: an IO slave for the appropriate protocol is started. +However, after the job (like a download from an http server) has finished, it +is not immediately killed. Instead, it is put in a pool of idle slaves and +killed after a certain time of inactivity (current 3 minutes). If a new request +for the same protocol and host arrives, the slave is reused. The obvious +advantage is that for a series of jobs for the same host, the cost for creating +new processes and possibly going through an authentication handshake is saved. + + + +Of course, reusing is only possible when the existing slave has already finished +its previous job. when a new request arrives while an existing slave process is +still running, a new process must be started and used. In the API usage in the +examples above, there are no limitation for creating new slave processes: if you +start a consecutive series of downloads for 20 different files, then TDEIO will +start 20 slave processes. This scheme of assigning slaves to jobs is called +direct. It not always the most appropriate scheme, as it +may need much memory and put a high load on both the client and server machines. + + + +So there is a different way. You can schedule jobs. If +you do this, only a limited number (currently 3) of slave processes for a +protocol will be created. If you create more jobs than that, they are put in a +queue and are processed when a slave process becomes idle. This is done as +follows: + + + +KURL url("http://developer.kde.org/documentation/kde2arch/index.html"); +TDEIO::TransferJob *job = TDEIO::get(url, true, false); +TDEIO::Scheduler::scheduleJob(job); + + + +A third possibility is connection oriented. For example, +for the IMAP slave, it does not make any sense to start multiple processes for +the same server. Only one IMAP connection at a time should be enforced. In +this case, the application must explicitly deal with the notion of a slave. It +has to deallocate a slave for a certain connection and then assign all jobs +which should go through the same connection to the same slave. This can again +be easily achieved by using the TDEIO::Scheduler: + + + +KURL baseUrl("imap://bernd@albert.physik.hu-berlin.de"); +TDEIO::Slave *slave = TDEIO::Scheduler::getConnectedSlave(baseUrl); + +TDEIO::TransferJob *job1 = TDEIO::get(KURL(baseUrl, "/INBOX;UID=79374")); +TDEIO::Scheduler::assignJobToSlave(slave, job1); + +TDEIO::TransferJob *job2 = TDEIO::get(KURL(baseUrl, "/INBOX;UID=86793")); +TDEIO::Scheduler::assignJobToSlave(slave, job2); + +... + +TDEIO::Scheduler::disconnectSlave(slave); + + + +You may only disconnect the slave after all jobs assigned to it are guaranteed +to be finished. + + + + + + +Defining an ioslave + + +In the following we discuss how you can add a new ioslave to the system. +In analogy to services, new ioslaves are advertised to the system by +installing a little configuration file. The following Makefile.am +snippet installs the ftp protocol: + + + +protocoldir = $(kde_servicesdir) +protocol_DATA = ftp.protocol +EXTRA_DIST = $(mime_DATA) + + + +The contents of the file ftp.protocol is as follows: + + + +[Protocol] +exec=tdeio_ftp +protocol=ftp +input=none +output=filesystem +listing=Name,Type,Size,Date,Access,Owner,Group,Link, +reading=true +writing=true +makedir=true +deleting=true +Icon=ftp + + + +The "protocol" entry defines for which protocol this slave +is responsible. "exec" is (in contrast what you would +expect naively) the name of the library that implements the slave. When the +slave is supposed to start, the "tdeinit" executable is +started which in turn loads this library into its address space. So in +practice, you can think of the running slave as a separate process although it +is implemented as library. The advantage of this mechanism is that it saves a +lot of memory and reduces the time needed by the runtime linker. + + + +The "input" and "output" lines are not used currently. + + + +The remaining lines in the .protocol file define which +abilities the slave has. In general, the features a slave must implement are +much simpler than the features the TDEIO API provides for the application. The +reason for this is that complex jobs are scheduled to a couple of subjobs. For +example, in order to list a directory recursively, one job will be started for +the toplevel directory. Then for each subdirectory reported back, new subjobs +are started. A scheduler in TDEIO makes sure that not too many jobs are active +at the same time. Similarly, in order to copy a file within a protocol that +does not support copying directly (like the ftp: protocol), +TDEIO can read the source file and then write the data to the destination +file. For this to work, the .protocol must advertise the +actions its slave supports. + + + +Since slaves are loaded as shared libraries, but constitute standalone programs, +their code framework looks a bit different from normal shared library plugins. +The function which is called to start the slave is called +kdemain(). This function does some initializations and +then goes into an event loop and waits for requests by the application using +it. This looks as follows: + + + +extern "C" { int kdemain(int argc, char **argv); } + +int kdemain(int argc, char **argv) +{ + TDELocale::setMainCatalogue("tdelibs"); + TDEInstance instance("tdeio_ftp"); + (void) TDEGlobal::locale(); + + if (argc != 4) { + fprintf(stderr, "Usage: tdeio_ftp protocol " + "domain-socket1 domain-socket2\n"); + exit(-1); + } + + FtpSlave slave(argv[2], argv[3]); + slave.dispatchLoop(); + return 0; +} + + + + + + +Implementing an ioslave + + +Slaves are implemented as subclasses of TDEIO::SlaveBase +(FtpSlave in the above example). Thus, the actions listed in the +.protocol correspond to certain virtual functions in +TDEIO::SlaveBase the slave implementation must +reimplement. Here is a list of possible actions and the corresponding virtual +functions: + + + + +reading - Reads data from a URL +void get(const KURL &url) + +writing - Writes data to a URL and create the file if it does not exist yet. +void put(const KURL &url, int permissions, bool overwrite, bool resume) + +moving - Renames a file. +void rename(const KURL &src, const KURL &dest, bool overwrite) + +deleting - Deletes a file or directory. +void del(const KURL &url, bool isFile) + +listing - Lists the contents of a directory. +void listDir(const KURL &url) + +makedir - Creates a directory. +void mkdir(const KURL &url, int permissions) + + + + +Additionally, there are reimplementable functions not listed in the .protocol +file. For these operations, TDEIO automatically determines whether they are supported +or not (i.e. the default implementation returns an error). + + + + +Delivers information about a file, similar to the C function stat(). +void stat(const KURL &url) + +Changes the access permissions of a file. +void chmod(const KURL &url, int permissions) + +Determines the MIME type of a file. +void mimetype(const KURL &url) + +Copies a file. +copy(const KURL &url, const KURL &dest, int permissions, bool overwrite) + +Creates a symbolic link. +void symlink(const QString &target, const KURL &dest, bool overwrite) + + + + +All these implementation should end with one of two calls: If the operation +was successful, they should call finished(). If an error has occurred, +error() should be called with an error code as first argument and a +string in the second. Possible error codes are listed as enum +TDEIO::Error. The second argument is usually the URL in +question. It is used e.g. in TDEIO::Job::showErrorDialog() +in order to parameterize the human-readable error message. + + + +For slaves that correspond to network protocols, it might be interesting to +reimplement the method SlaveBase::setHost(). This is +called to tell the slave process about the host and port, and the user name +and password to log in. In general, meta data set by the application can be +queried by SlaveBase::metaData(). You can check for the +existence of meta data of a certain key with +SlaveBase::hasMetaData(). + + + + + + +Communicating back to the application + + +Various actions implemented in a slave need some way to communicate data back +to the application using the slave process: + + + + + +get() sends blocks of data. This is done with +data(), which takes a QByteArray +as argument. Of course, you do not need to send all data at once. If you send +a large file, call data() with smaller data blocks, so +the application can process them. Call finished() when +the transfer is finished. + + + +listDir() reports information about the entries of a +directory. For this purpose, call listEntries() with a +TDEIO::UDSEntryList as argument. Analogously to +data(), you can call this several times. When you are +finished, call listEntry() with the second argument set +to true. You may also call totalSize() to report the +total number of directory entries, if known. + + + +stat() reports information about a file like size, MIME +type, etc. Such information is packaged in a +TDEIO::UDSEntry, which will be discussed below. Use +statEntry() to send such an item to the application. + + + +mimetype() calls mimeType() with a +string argument. + + + +get() and copy() may want to provide +progress information. This is done with the methods +totalSize(), processedSize(), +speed(). The total size and processed size are reported +as bytes, the speed as bytes per second. + + + +You can send arbitrary key/value pairs of meta data with +setMetaData(). + + + + + + + + +Interacting with the user + + +Sometimes a slave has to interact with the user. Examples include informational +messages, authentication dialogs and confirmation dialogs when a file is about +to be overwritten. + + + + + +infoMessage() - This is for informational feedback, such +as the message "Retrieving data from <host>" from the http slave, which +is often displayed in the status bar of the program. On the application side, +this method corresponds to the signal +TDEIO::Job::infoMessage(). + + + +warning() - Displays a warning in a message box with +KMessageBox::information(). If a message box is still +open from a former call of warning() from the same slave process, nothing +happens. + + + +messageBox() - This is richer than the previous +method. It allows to open a message box with text and caption and some +buttons. See the enum SlaveBase::MessageBoxType for reference. + + + +openPassDlg() - Opens a dialog for the input of user name +and password. + + + + + + + + + + + + + +Licensing + +&underFDL; +&underGPL; + + + + diff --git a/doc/tdearch/joinbevel.png b/doc/tdearch/joinbevel.png new file mode 100644 index 00000000..584b6bd4 Binary files /dev/null and b/doc/tdearch/joinbevel.png differ diff --git a/doc/tdearch/joinmiter.png b/doc/tdearch/joinmiter.png new file mode 100644 index 00000000..e5d94b13 Binary files /dev/null and b/doc/tdearch/joinmiter.png differ diff --git a/doc/tdearch/joinround.png b/doc/tdearch/joinround.png new file mode 100644 index 00000000..9a8bbe93 Binary files /dev/null and b/doc/tdearch/joinround.png differ diff --git a/doc/tdearch/konqi-mirrored.png b/doc/tdearch/konqi-mirrored.png new file mode 100644 index 00000000..5145c0ee Binary files /dev/null and b/doc/tdearch/konqi-mirrored.png differ diff --git a/doc/tdearch/konqi-normal.png b/doc/tdearch/konqi-normal.png new file mode 100644 index 00000000..c16e1475 Binary files /dev/null and b/doc/tdearch/konqi-normal.png differ diff --git a/doc/tdearch/konqi-rotated.png b/doc/tdearch/konqi-rotated.png new file mode 100644 index 00000000..157e82dd Binary files /dev/null and b/doc/tdearch/konqi-rotated.png differ diff --git a/doc/tdearch/konqi-sheared.png b/doc/tdearch/konqi-sheared.png new file mode 100644 index 00000000..ee645f87 Binary files /dev/null and b/doc/tdearch/konqi-sheared.png differ diff --git a/doc/tdearch/kview-menu.png b/doc/tdearch/kview-menu.png new file mode 100644 index 00000000..0e57e721 Binary files /dev/null and b/doc/tdearch/kview-menu.png differ diff --git a/doc/tdearch/opengl.png b/doc/tdearch/opengl.png new file mode 100644 index 00000000..2489777d Binary files /dev/null and b/doc/tdearch/opengl.png differ diff --git a/doc/tdearch/penstyles.png b/doc/tdearch/penstyles.png new file mode 100644 index 00000000..7e976bcd Binary files /dev/null and b/doc/tdearch/penstyles.png differ diff --git a/doc/tdearch/whatsthis.png b/doc/tdearch/whatsthis.png new file mode 100644 index 00000000..4bdba093 Binary files /dev/null and b/doc/tdearch/whatsthis.png differ diff --git a/doc/tdevassistant/CMakeLists.txt b/doc/tdevassistant/CMakeLists.txt new file mode 100644 index 00000000..caa4d7b8 --- /dev/null +++ b/doc/tdevassistant/CMakeLists.txt @@ -0,0 +1,9 @@ +################################################# +# +# Improvements and feedback are welcome +# +# This file is released under GPL >= 2 +# +################################################# + +tde_create_handbook( DESTINATION tdevassistant ) diff --git a/doc/tdevassistant/Makefile.am b/doc/tdevassistant/Makefile.am new file mode 100644 index 00000000..41691557 --- /dev/null +++ b/doc/tdevassistant/Makefile.am @@ -0,0 +1,3 @@ +KDE_LANG = en +KDE_DOCS = AUTO + diff --git a/doc/tdevassistant/index.docbook b/doc/tdevassistant/index.docbook new file mode 100644 index 00000000..065276f9 --- /dev/null +++ b/doc/tdevassistant/index.docbook @@ -0,0 +1,65 @@ + +TDevAssistant"> + + + +]> + + + + + +
+The &tdevassistant; Handbook + + +The &tdevassistant; Handbook + + +&tde-authors; + + + +&tde-release-version; +Reviewed: &tde-release-date; + + +&tde-copyright-date; +&tde-team; + + + + + + +&tdevassistant; is a development documentation viewer for &tde;. + + + + +TDE + + + + + +We Apologize +No documentation has yet been written for &tdevassistant;. + +If you need help, please check The &tde; +web site, submit questions to the +&tde; mail lists, or file a bug report at the +&tde; bug tracker. + +If you are interested in helping, please consider writing the help file. +Submitting a basic text file is acceptable as the &tde-team; will convert the text. + +Thank you for helping and thank you for your patience. + +&underFDL; + + + +&documentation.index; +
diff --git a/doc/tdevdesigner/CMakeLists.txt b/doc/tdevdesigner/CMakeLists.txt new file mode 100644 index 00000000..d8d93cbb --- /dev/null +++ b/doc/tdevdesigner/CMakeLists.txt @@ -0,0 +1,9 @@ +################################################# +# +# Improvements and feedback are welcome +# +# This file is released under GPL >= 2 +# +################################################# + +tde_create_handbook( DESTINATION tdevdesigner ) diff --git a/doc/tdevdesigner/Makefile.am b/doc/tdevdesigner/Makefile.am new file mode 100644 index 00000000..41691557 --- /dev/null +++ b/doc/tdevdesigner/Makefile.am @@ -0,0 +1,3 @@ +KDE_LANG = en +KDE_DOCS = AUTO + diff --git a/doc/tdevdesigner/index.docbook b/doc/tdevdesigner/index.docbook new file mode 100644 index 00000000..3bfdf384 --- /dev/null +++ b/doc/tdevdesigner/index.docbook @@ -0,0 +1,65 @@ + +TDevDesigner"> + + + +]> + + + + + +
+The &tdevdesigner; Handbook + + +The &tdevdesigner; Handbook + + +&tde-authors; + + + +&tde-release-version; +Reviewed: &tde-release-date; + + +&tde-copyright-date; +&tde-team; + + + + + + +&tdevdesigner; is a GUI designer environment for &tde;. + + + + +TDE + + + + + +We Apologize +No documentation has yet been written for &tdevdesigner;. + +If you need help, please check The &tde; +web site, submit questions to the +&tde; mail lists, or file a bug report at the +&tde; bug tracker. + +If you are interested in helping, please consider writing the help file. +Submitting a basic text file is acceptable as the &tde-team; will convert the text. + +Thank you for helping and thank you for your patience. + +&underFDL; + + + +&documentation.index; +
diff --git a/doc/tdevelop/app-files.docbook b/doc/tdevelop/app-files.docbook index 547010ec..736baf16 100644 --- a/doc/tdevelop/app-files.docbook +++ b/doc/tdevelop/app-files.docbook @@ -56,7 +56,7 @@ Most &tdevelop; features are provided by KParts. These are basically application -There are quite a lot of default configuration subdirectories in $TDEDIR/share/apps/ whose names all start with a kdev sequence. Most of them are for &tdevelop; internal use only. They might be deliberately grouped for readability as: +There are quite a lot of default configuration subdirectories in $TDEDIR/share/apps/ whose names all start with a tdev sequence. Most of them are for &tdevelop; internal use only. They might be deliberately grouped for readability as: Stand-alone Applications Task Specific Parts @@ -76,25 +76,25 @@ There are quite a lot of default configuration subdirectories in profiles/ — contains default plugin profile settings. (Currently there is only a tiny profile provided which defines a minimum set of active &tdevelop; plugins.) eventsrc — holds a lot of Process successful localization strings. tdevelopui.rc — provides the basic menu and tool bar entries &tdevelop; uses. - kdevhtml_partui.rc — provides a Print... entry in the File menu, a Copy entry in the Edit menu, and Back and Forward arrows in the Browser Toolbar in case a &HTML; file is browsed from the Documentation plugin. + tdevhtml_partui.rc — provides a Print... entry in the File menu, a Copy entry in the Edit menu, and Back and Forward arrows in the Browser Toolbar in case a &HTML; file is browsed from the Documentation plugin. - kdevassistant/ — provides the menu and tool bars of the stand-alone &tdevelop; Assistant documentation browser. - kdevdesigner/ and kdevdesignerpart/ — provide menu bar and tool bars of the stand-alone &tdevelop; user interface designer. + tdevassistant/ — provides the menu and tool bars of the stand-alone &tdevelop; Assistant documentation browser. + tdevdesigner/ and tdevdesignerpart/ — provide menu bar and tool bars of the stand-alone &tdevelop; user interface designer. Task Specific Parts - kdevabbrev/ — contains files used by the Abbreviation Expansion plugin: + tdevabbrev/ — contains files used by the Abbreviation Expansion plugin: sources/ — contains keyword definition files used by the Expand Text command. templates/ — contains template definition files used by the Expand Abbreviation command. - kdevabbrev.rc — provides the Expand Text and Expand Abbreviation entries in the Edit menu. + tdevabbrev.rc — provides the Expand Text and Expand Abbreviation entries in the Edit menu. - kdevappwizard/ — contains files used by the &appwizard; part: + tdevappwizard/ — contains files used by the &appwizard; part: importfiles/ — contains .tdevelop project files which control the initialization of a new project. imports/ — contains templates to set up project specific .desktop files. @@ -104,89 +104,89 @@ There are quite a lot of default configuration subdirectories in *.tar.gz — tarballs containing the source files to be included in a new generated project directory. - kdevastyle/ — provides the Reformat Source entry in the Edit menu. - kdevautoproject/ — provides most of the entries in the Build menu and the Build Toolbar (&tdevelop;) toolbar. + tdevastyle/ — provides the Reformat Source entry in the Edit menu. + tdevautoproject/ — provides most of the entries in the Build menu and the Build Toolbar (&tdevelop;) toolbar. - kdevclassview/ — contains files used by the Class View project plugin: + tdevclassview/ — contains files used by the Class View project plugin: pics/ — contains the icons used in the Classes classview tree. - kdevclassview.tc — provides the Class Inheritance Diagram entry in the Projects menu as well as the classes navigation combo box in the Browser Toolbar. + tdevclassview.tc — provides the Class Inheritance Diagram entry in the Projects menu as well as the classes navigation combo box in the Browser Toolbar. - kdevcloser/ — provides the Windows menu close entries. - kdevctags/ — provides the CTags entry in the Tools menu for the CTags Frontend project plugin. - kdevcvsservice/ — provides the icon used by the CvsService tab and a short shell script used to add a new entry to the &cvs; repository, both used by the CVS Integration project plugin. - kdevdebugger/ — provides the Debug menu entries for the Debugger Frontend project plugin. - kdevdiff/ — provides the Difference Viewer entry in the Tools menu. - kdevdistpart/ — provides the Distribution & Publishing entry in the Project menu for the Final Packaging Support project plugin. + tdevcloser/ — provides the Windows menu close entries. + tdevctags/ — provides the CTags entry in the Tools menu for the CTags Frontend project plugin. + tdevcvsservice/ — provides the icon used by the CvsService tab and a short shell script used to add a new entry to the &cvs; repository, both used by the CVS Integration project plugin. + tdevdebugger/ — provides the Debug menu entries for the Debugger Frontend project plugin. + tdevdiff/ — provides the Difference Viewer entry in the Tools menu. + tdevdistpart/ — provides the Distribution & Publishing entry in the Project menu for the Final Packaging Support project plugin. - kdevdocumentation/ — contains files used by the Documentation plugin: + tdevdocumentation/ — contains files used by the Documentation plugin: en/ and pics/ — contain files used by the htdig search tool. tocs/ — contain the default &tdevelop; documentation content description files (see the description in Basic Structure of &tdevelop; TOC Files). - kdevpart_documentation.rc — provides the search related entries in the Help menu. + tdevpart_documentation.rc — provides the search related entries in the Help menu. - kdevdoxygen/ — provides the menu entries for the Doxygen Support project plugin. + tdevdoxygen/ — provides the menu entries for the Doxygen Support project plugin. - kdevfilecreate/ — contains files used by the New File Wizard: + tdevfilecreate/ — contains files used by the New File Wizard: file-templates/ — provides the initial text contents to be put into the new source file of a given type. - kdevpart_filecreate.rc — provides the New entry in the File menu. + tdevpart_filecreate.rc — provides the New entry in the File menu. template-info.xml — contains descriptions of the available file types to be displayed in the New File tool view. - kdevfilter/ — provides the Execute Command... and Filter Selection Through Command... entries in the Tools menu used by the Shell Filtering and Insertion plugin. - kdevfullscreen/ — provides the Full Screen Mode entry in the View menu and the according tool bar icon. - kdevgrepview/ — provides the Find in Files...entry in the Edit menu used by the Grep Frontend plugin. - kdevhistory/ — provides the Back and Forward entries in the View menu. - kdevjavadebugger/ — provides a Java Debug menu in order to debug a &Java; application. - kdevoutputviews/ — provides the Next Error and Previous Error entries in the View menu. - kdevpartexplorer/ — provides the Part Explorer entry in the Tools menu used by the Part Explorer Tool plugin. - kdevquickopen/ — provides the Quick Open File.. entry in the File menu and the Quick Open Class... and Quick Open Method entries in the Tools menu used by the Quick Open project plugin. - kdevregexptest/ — provides the Debug Regular Expression... entry in the Tools menu used by the Regular Expression Tester plugin. - kdevreplace/ — provides the Find-Select-Replace... entry in the Edit menu used by the Replace Part plugin. - kdevtipofday/ — provides the Tip of the Day entry in the Help menu as well as a HTML-File containing the available tips. - kdevtools/ — controls various menu entries ceated by Tools Menu and External Tools Menu settings provided by the Tools Menu Addition plugin. - kdevvalgrind/ — provides the Valgrind Memory Leak Check and Profile with KCachegrind entries in the Debug menu used by the Valgrind Frontend plugin. + tdevfilter/ — provides the Execute Command... and Filter Selection Through Command... entries in the Tools menu used by the Shell Filtering and Insertion plugin. + tdevfullscreen/ — provides the Full Screen Mode entry in the View menu and the according tool bar icon. + tdevgrepview/ — provides the Find in Files...entry in the Edit menu used by the Grep Frontend plugin. + tdevhistory/ — provides the Back and Forward entries in the View menu. + tdevjavadebugger/ — provides a Java Debug menu in order to debug a &Java; application. + tdevoutputviews/ — provides the Next Error and Previous Error entries in the View menu. + tdevpartexplorer/ — provides the Part Explorer entry in the Tools menu used by the Part Explorer Tool plugin. + tdevquickopen/ — provides the Quick Open File.. entry in the File menu and the Quick Open Class... and Quick Open Method entries in the Tools menu used by the Quick Open project plugin. + tdevregexptest/ — provides the Debug Regular Expression... entry in the Tools menu used by the Regular Expression Tester plugin. + tdevreplace/ — provides the Find-Select-Replace... entry in the Edit menu used by the Replace Part plugin. + tdevtipofday/ — provides the Tip of the Day entry in the Help menu as well as a HTML-File containing the available tips. + tdevtools/ — controls various menu entries ceated by Tools Menu and External Tools Menu settings provided by the Tools Menu Addition plugin. + tdevvalgrind/ — provides the Valgrind Memory Leak Check and Profile with KCachegrind entries in the Debug menu used by the Valgrind Frontend plugin. Project Generation Parts - kdevadaproject/ — provides entries for the Build menu and according tool bar icons to build an Ada application. - kdevantproject/ — provides entries for the Build menu when the Ant project generator is used. - kdevautoproject/ — provides entries for the Build menu and according tool bar icons when working with the &GNU; Tools based &automake; project generator. Additionally provides the Add Translation and Build Configuration entries to the Project menu. - kdevcustomproject/ — provides entries for the Build menu and according tool bar icons when the project is based on custom Makefils. - kdevgenericproject/ — contains menu definitions for an experimental generic project generator. Currently (version 3.1.0) unused. - kdevhaskellproject/ — provides entries for the Build menu and according tool bar icons to build a Haskell application. - kdevpascalproject/ — provides entries for the Build menu and according tool bar icons to build a Pascal application. - kdevtrollproject/ — provides entries for the Build menu and according tool bar icons to build an application using the &Qt; QMake project manager. + tdevadaproject/ — provides entries for the Build menu and according tool bar icons to build an Ada application. + tdevantproject/ — provides entries for the Build menu when the Ant project generator is used. + tdevautoproject/ — provides entries for the Build menu and according tool bar icons when working with the &GNU; Tools based &automake; project generator. Additionally provides the Add Translation and Build Configuration entries to the Project menu. + tdevcustomproject/ — provides entries for the Build menu and according tool bar icons when the project is based on custom Makefils. + tdevgenericproject/ — contains menu definitions for an experimental generic project generator. Currently (version 3.1.0) unused. + tdevhaskellproject/ — provides entries for the Build menu and according tool bar icons to build a Haskell application. + tdevpascalproject/ — provides entries for the Build menu and according tool bar icons to build a Pascal application. + tdevtrollproject/ — provides entries for the Build menu and according tool bar icons to build an application using the &Qt; QMake project manager. Language Specific Parts - kdevadasupport/ — provides entries in the Tools menu and according tool bar icons needed to develop Ada applications. - kdevbashsupport/ — provides entries in the Build menu and according tool bar icons needed to develop Bash scripts. + tdevadasupport/ — provides entries in the Tools menu and according tool bar icons needed to develop Ada applications. + tdevbashsupport/ — provides entries in the Build menu and according tool bar icons needed to develop Bash scripts. - kdevcppsupport/ — contains files used by the &appwizard; to build C++ applications: + tdevcppsupport/ — contains files used by the &appwizard; to build C++ applications: newclass/ — contains header and source templates from which the &appwizard; builds the according source files. subclassing/ — contains templates which the &appwizard; uses to set up initial class declarations/definitions in the source files. templates — contains templates from which the &appwizard; sets up the default header and source template files to be used by the &nfwizard;. configuration — dummy template to add macros. - kdevcppsupport.rc — provides the Complete Text and Make Member entries fo the Edit menu, the Switch Header/Implementation entry for the View menu, and the New Class entry for the Project menu as well as a New Class icon for the Browser Toolbar. + tdevcppsupport.rc — provides the Complete Text and Make Member entries fo the Edit menu, the Switch Header/Implementation entry for the View menu, and the New Class entry for the Project menu as well as a New Class icon for the Browser Toolbar. - kdevfortransupport/ — provides entries in the Build menu needed to develop Fortran applications. - kdevhaskellsupport/ — provides entries in the Build menu and according tool bar icons needed to develop Haskell applications. - kdevjavasupport/ — contains the UI definition needed to develop &Java; applications. - kdevpascalsupport/ — contains the UI definition needed to develop Pascal applications. - kdevperlsupport/ — provides Project and Help menu entries needed to develop Perl scripts. - kdevphpsupport/ — contains UI and PHP function definition files needed to develop PHP scripts. - kdevpythonsupport/ — provides Build and Help menu entries and according tool bar icons needed to develop Python scripts. - kdevrubysupport/ — provides Build menu entries and according tool bar icons needed to develop Ruby scripts. - kdevscriptproject/ — provides th UI definitions needed to develop custom projects. Currently (version 3.1.0) unused. - kdevsqlsupport/ — provides th UI definitions needed to develop SQL projects. Currently (version 3.1.0) unused. + tdevfortransupport/ — provides entries in the Build menu needed to develop Fortran applications. + tdevhaskellsupport/ — provides entries in the Build menu and according tool bar icons needed to develop Haskell applications. + tdevjavasupport/ — contains the UI definition needed to develop &Java; applications. + tdevpascalsupport/ — contains the UI definition needed to develop Pascal applications. + tdevperlsupport/ — provides Project and Help menu entries needed to develop Perl scripts. + tdevphpsupport/ — contains UI and PHP function definition files needed to develop PHP scripts. + tdevpythonsupport/ — provides Build and Help menu entries and according tool bar icons needed to develop Python scripts. + tdevrubysupport/ — provides Build menu entries and according tool bar icons needed to develop Ruby scripts. + tdevscriptproject/ — provides th UI definitions needed to develop custom projects. Currently (version 3.1.0) unused. + tdevsqlsupport/ — provides th UI definitions needed to develop SQL projects. Currently (version 3.1.0) unused. @@ -212,7 +212,7 @@ All information about user defined settings is kept in two subdirectories of Application Specific Configuration -Any user changes to the &tdevelop; Default Configuration settings as well as user specific settings which are not kept in any of the Resource Configuration Files are found in kdev... subdirectories of the $TDEHOME/share/apps/ directory. +Any user changes to the &tdevelop; Default Configuration settings as well as user specific settings which are not kept in any of the Resource Configuration Files are found in tdev... subdirectories of the $TDEHOME/share/apps/ directory. Most of these configuration files are however used by various &tdevelop; plugins in order to provide some specific menu and/or toolbar entries. Thus they are of interest only in case something went really wrong with the user interface. @@ -223,30 +223,30 @@ In case the contents of these directories mirror those of the Default Configurat - kdevabbrev/ — contains files used by the Abbreviation Expansion plugin: + tdevabbrev/ — contains files used by the Abbreviation Expansion plugin: sources/ — currently empty; &tdevelop; uses the default keyword definition files for Expand Text commands. templates/ — contains the user modified template definition files used by the Expand Abbreviation command. - kdevabbrev.rc — provides the Expand Text and Expand Abbreviation entries in the Edit menu. + tdevabbrev.rc — provides the Expand Text and Expand Abbreviation entries in the Edit menu. - kdevappwizard/ — only provides the New Project... and Import Existing Project... entries in the Projects menu. The &appwizard; will use the default configuration settings for its actual works. + tdevappwizard/ — only provides the New Project... and Import Existing Project... entries in the Projects menu. The &appwizard; will use the default configuration settings for its actual works. - kdevastyle/ — provides the actual Reformat Source entry in the Edit menu. + tdevastyle/ — provides the actual Reformat Source entry in the Edit menu. - kdevautoproject/ — provides the actual entries in the Build menu and the Build Toolbar (KDevelop) toolbar. + tdevautoproject/ — provides the actual entries in the Build menu and the Build Toolbar (TDevelop) toolbar. - kdevclassview/ — provides the Class Inheritance Diagram entry in the Project menu and the class browser combo box in the Browser Toolbar by the Class View project plugin. + tdevclassview/ — provides the Class Inheritance Diagram entry in the Project menu and the class browser combo box in the Browser Toolbar by the Class View project plugin. - kdevcloser/ — provides the Close Selected Windows... entry in the Windows menu. + tdevcloser/ — provides the Close Selected Windows... entry in the Windows menu. - kdevcppsupport/ — holds the acual configuration used by the &appwizard; to build C++ applications. The &appwizard; however uses its main bulk of configuration information directly from the default configuration directory. See there for more detail. + tdevcppsupport/ — holds the acual configuration used by the &appwizard; to build C++ applications. The &appwizard; however uses its main bulk of configuration information directly from the default configuration directory. See there for more detail. newclass/ — contains the actual header and source templates from which the &appwizard; builds the according source files. @@ -255,22 +255,22 @@ In case the contents of these directories mirror those of the Default Configurat pcs/ — contains database files &tdevelop; uses build the actual Persistent Code Store (.pcs) file of a &kde; C++ project. - kdevcppsupport.rc — provides the Complete Text and Make Member entries fo the Edit menu, the Switch Header/Implementation entry for the View menu, and the New Class entry for the Project menu as well as a New Class icon for the Browser Toolbar. + tdevcppsupport.rc — provides the Complete Text and Make Member entries fo the Edit menu, the Switch Header/Implementation entry for the View menu, and the New Class entry for the Project menu as well as a New Class icon for the Browser Toolbar. - kdevctags/ — provides the CTags entry in the Tools menu for the CTags Frontend project plugin. + tdevctags/ — provides the CTags entry in the Tools menu for the CTags Frontend project plugin. - kdevdebugger/ — provides the Debug menu entries for the Debugger Frontend project plugin. + tdevdebugger/ — provides the Debug menu entries for the Debugger Frontend project plugin. - kdevdiff/ — provides the Difference Viewer entry in the Tools menu. + tdevdiff/ — provides the Difference Viewer entry in the Tools menu. - kdevdocumentation/ — contains the actual files used by the Documentation plugin in addition to the default configuration files. See there for more detail. - The directories in kdevdocumentation/ mainly hold actual bookkeeping information. The actually set up documentation files are kept in doc...pluginrc files in the $TDEHOME/share/config/ directory. + tdevdocumentation/ — contains the actual files used by the Documentation plugin in addition to the default configuration files. See there for more detail. + The directories in tdevdocumentation/ mainly hold actual bookkeeping information. The actually set up documentation files are kept in doc...pluginrc files in the $TDEHOME/share/config/ directory. bookmarks/ — maintains the entries in the Bookmarks tab of the &tdevelop; Documentation plugin. @@ -282,12 +282,12 @@ In case the contents of these directories mirror those of the Default Configurat search/ — contains files used by the htdig search tool which serves search calls from the Search tab of the Documentation plugin. - kdevpart_documentation.rc — provides the search related entries in the Help menu. + tdevpart_documentation.rc — provides the search related entries in the Help menu. - kdevdoxygen/ — provides the menu entries for the Doxygen Support project plugin. + tdevdoxygen/ — provides the menu entries for the Doxygen Support project plugin. tdevelop/ — contains some actual settings &tdevelop; uses for its basic setup: @@ -297,45 +297,45 @@ In case the contents of these directories mirror those of the Default Configurat - kdevfilecreate/ — contains files used by the New File Wizard: + tdevfilecreate/ — contains files used by the New File Wizard: file-templates/ — provides the actually used text contents to be put into the new source file of a given type. More file templates are found in the default configuration files directory. - kdevpart_filecreate.rc — provides the New entry in the File menu. + tdevpart_filecreate.rc — provides the New entry in the File menu. template-info.xml — contains descriptions of the available file types to be displayed in the New File tool view. - kdevfilter/ — provides the Execute Command... and Filter Selection Through Command... entries in the Tools menu used by the Shell Filtering and Insertion plugin. + tdevfilter/ — provides the Execute Command... and Filter Selection Through Command... entries in the Tools menu used by the Shell Filtering and Insertion plugin. - kdevfullscreen/ — provides the Full Screen Mode entry in the View menu and the according tool bar icon. + tdevfullscreen/ — provides the Full Screen Mode entry in the View menu and the according tool bar icon. - kdevgrepview/ — provides the Find in Files...entry in the Edit menu used by the Grep Frontend plugin. + tdevgrepview/ — provides the Find in Files...entry in the Edit menu used by the Grep Frontend plugin. - kdevoutputviews/ — provides the Next Error and Previous Error entries in the View menu. + tdevoutputviews/ — provides the Next Error and Previous Error entries in the View menu. - kdevpartexplorer/ — provides the Part Explorer entry in the Tools menu used by the Part Explorer Tool plugin. + tdevpartexplorer/ — provides the Part Explorer entry in the Tools menu used by the Part Explorer Tool plugin. - kdevquickopen/ — provides the Quick Open File.. entry in the File menu and the Quick Open Class... and Quick Open Method entries in the Tools menu used by the Quick Open project plugin. + tdevquickopen/ — provides the Quick Open File.. entry in the File menu and the Quick Open Class... and Quick Open Method entries in the Tools menu used by the Quick Open project plugin. - kdevregexptest/ — provides the Debug Regular Expression... entry in the Tools menu used by the Regular Expression Tester plugin. + tdevregexptest/ — provides the Debug Regular Expression... entry in the Tools menu used by the Regular Expression Tester plugin. - kdevreplace/ — provides the Find-Select-Replace... entry in the Edit menu used by the Replace Part plugin. + tdevreplace/ — provides the Find-Select-Replace... entry in the Edit menu used by the Replace Part plugin. - kdevtipofday/ —provides the Tip of the Day entry in the Help menu. The HTML-File containing the available tips is provided as a default configuration file only. + tdevtipofday/ —provides the Tip of the Day entry in the Help menu. The HTML-File containing the available tips is provided as a default configuration file only. - kdevtools/ — controls various menu entries ceated by Tools Menu and External Tools Menu settings provided by the Tools Menu Addition plugin. + tdevtools/ — controls various menu entries ceated by Tools Menu and External Tools Menu settings provided by the Tools Menu Addition plugin. - kdevvalgrind/ — provides the Valgrind Memory Leak Check and Profile with KCachegrind entries in the Debug menu used by the Valgrind Frontend plugin. + tdevvalgrind/ — provides the Valgrind Memory Leak Check and Profile with KCachegrind entries in the Debug menu used by the Valgrind Frontend plugin. @@ -348,35 +348,35 @@ In case the contents of these directories mirror those of the Default Configurat There are two groups of &tdevelop; configuration files in the $TDEHOME/share/config/ directory, distiguished by their surrounding character sequences: doc...pluginrc denotes files used by the documentation plugin. - kdev...rc denotes configuration files used by &tdevelop; itself and its available plugins. + tdev...rc denotes configuration files used by &tdevelop; itself and its available plugins. Configuration Files Used by &tdevelop; - kdevabbrevrc — holds the current state of the Abbreviations configuration provided by the Abbreviation Expansion plugin. + tdevabbrevrc — holds the current state of the Abbreviations configuration provided by the Abbreviation Expansion plugin. This only records whether the abbreviations will be used or not. The actual definitions of new abbreviations will go into the $TDEHOME/share/apps/kdevabbrev/templates/templates file. - kdevassistantrc — holds some configuration states specific of the stand-alone &tdevelop; Assistant documentation browser. + tdevassistantrc — holds some configuration states specific of the stand-alone &tdevelop; Assistant documentation browser. Most common configuration settings are shared with the &tdevelop; IDE tdeveloprc file. - kdevassistantuimode4rc — holds the current MDI configuration states (dock positions &etc;) of the stand-alone &tdevelop; Assistant documentation browser. + tdevassistantuimode4rc — holds the current MDI configuration states (dock positions &etc;) of the stand-alone &tdevelop; Assistant documentation browser. - kdevclassviewrc — holds the View Mode setting of the Classes class browser tab provided by the Class View project plugin. + tdevclassviewrc — holds the View Mode setting of the Classes class browser tab provided by the Class View project plugin. This is a global setting, although the Class View plugin may be disabled on a per project basis. Any change in this setting will be globally updated whenever the current project is closed and thus affect all subsequently loaded projects. - kdevcppsupportrc — holds some settings used to set up CPP source files. In particular you will find the settings made on the C++ Class Generator configuration dialog in here. - kdevdocumentationrc — holds actual settings the Documentation plugin uses. + tdevcppsupportrc — holds some settings used to set up CPP source files. In particular you will find the settings made on the C++ Class Generator configuration dialog in here. + tdevdocumentationrc — holds actual settings the Documentation plugin uses. tdeveloprc — holds the global settings the &tdevelop; IDE and the &tdevelop; Assistant stand-alone documentation browser will use. tdevelopuimode4rc — holds the current MDI configuration states (dock positions &etc;) of the &tdevelop; IDE. - kdevfileselectorrc — holds actual settings the File Selector plugin uses. - kdevfileviewrc — holds the actual filename color settings the CVS Integration (Cervisia) project plugin uses for display. - kdevfilterrc — holds actual settings the Shell Filtering and Insertion plugin uses. - kdevgrepviewrc — holds actual settings the Grep Frontend plugin uses. - kdevsnippetrc — holds actual settings the Code Snippets plugin uses. - kdevtoolsrc — holds actual settings the Tools Menu Addition plugin uses. + tdevfileselectorrc — holds actual settings the File Selector plugin uses. + tdevfileviewrc — holds the actual filename color settings the CVS Integration (Cervisia) project plugin uses for display. + tdevfilterrc — holds actual settings the Shell Filtering and Insertion plugin uses. + tdevgrepviewrc — holds actual settings the Grep Frontend plugin uses. + tdevsnippetrc — holds actual settings the Code Snippets plugin uses. + tdevtoolsrc — holds actual settings the Tools Menu Addition plugin uses. @@ -385,7 +385,7 @@ There are two groups of &tdevelop; configuration files in the the Filter plugin. +the Filter plugin. @@ -1840,10 +1840,10 @@ Configure Editor... Settings -Configure KDevelop... +Configure TDevelop... -Configure KDevelop... +Configure TDevelop... @@ -1866,7 +1866,7 @@ Configure KDevelop... Help -KDevelop Handbook +TDevelop Handbook View this document. @@ -1960,10 +1960,10 @@ Info Page... Help -About KDevelop... +About TDevelop... Display some brief information about -KDevelop's version number, authors and license agreement. +TDevelop's version number, authors and license agreement. diff --git a/doc/tdevelop/getting-started.docbook b/doc/tdevelop/getting-started.docbook index a805f393..39d7c4de 100644 --- a/doc/tdevelop/getting-started.docbook +++ b/doc/tdevelop/getting-started.docbook @@ -77,7 +77,7 @@ already did switch to another user interface mode some items may not be there as described or will behave slightly different. If in doubt which user interface mode your &tdevelop; currently uses, check with the Settings Configure -KDevelop... User Interface +TDevelop... User Interface dialog. @@ -416,7 +416,7 @@ and plugged-in tools to extend the basic &IDE; capabilities. The The upper set of Tools menu entries will be provided by the editor plugin which is in use. You may select your favorite editor via Settings Configure -KDevelop... Editor. Once an +TDevelop... Editor. Once an editable document file is selected, the upper part of the Tools menu will provide advanced editing commands specific to the editor part in use. @@ -452,10 +452,10 @@ Also, you can configure shortcuts, toolbars, notifications, the editor and Help -Here you can open this KDevelop manual, look up terms in various +Here you can open this TDevelop manual, look up terms in various documentation files, open man pages (the traditional UNIX manual format) and info pages (the GNU manual format). Furthermore you can report bugs here or get -some info about your current KDevelop version and its authors. +some info about your current TDevelop version and its authors. @@ -497,7 +497,7 @@ different main purpose. actual work. More tools to work on that project will be available then. The actual number of tool views depends on the Plugin Tools being currently available to &tdevelop;. You will find more on this -topic in the Configuring KDevelop chapter. +topic in the Configuring TDevelop chapter. Currently, with no project open and the default number of plugin tools loaded, you will find the following tool views. Clicking on a tab will open @@ -627,7 +627,7 @@ adjusted. If you want to know more about &tdevelop; configuration, have a look at -the Configuring KDevelop chapter. +the Configuring TDevelop chapter. @@ -635,8 +635,8 @@ the Configuring KDevelop chapter. To configure &tdevelop;, click the Settings menu and select -Configure KDevelop.... The -Configure KDevelop dialog will pop up, showing the +Configure TDevelop.... The +Configure TDevelop dialog will pop up, showing the following General settings page to the right. @@ -770,7 +770,7 @@ mandatory that the KDELibs Apidocs were present when perform the identifier lookup examples later in this chapter, make sure that this documentation exists and is accessible to &tdevelop;. See Installing -KDevelop fore more detail. +TDevelop fore more detail. @@ -1127,7 +1127,7 @@ and hello.kdevses. Of particular importance in each project is the xxx.tdevelop (where xxx denotes the project -name) file. It is the main KDevelop 3 Project File and +name) file. It is the main TDevelop 3 Project File and needed if you later want load this project into the &IDE;. @@ -1789,7 +1789,7 @@ this behavior. Select Settings Configure -KDevelop... +TDevelop... In the left hand icon bar on the dialog popup click the User diff --git a/doc/tdevelop/index.docbook b/doc/tdevelop/index.docbook index d412dc35..9e83802d 100644 --- a/doc/tdevelop/index.docbook +++ b/doc/tdevelop/index.docbook @@ -76,7 +76,7 @@ Entries which require special treatment are marked with comments starting with ' - &tdevelop; User Manual + &tdevelop; Handbook 2006-06-19 &kdevrelease; diff --git a/doc/tdevelop/kdevdesigner.png b/doc/tdevelop/kdevdesigner.png deleted file mode 100644 index 4fa74c68..00000000 Binary files a/doc/tdevelop/kdevdesigner.png and /dev/null differ diff --git a/doc/tdevelop/nutshell.docbook b/doc/tdevelop/nutshell.docbook index ca0a4276..93db1506 100644 --- a/doc/tdevelop/nutshell.docbook +++ b/doc/tdevelop/nutshell.docbook @@ -37,7 +37,7 @@ smaller tool view tabs in IDEAl Mode By default &tdevelop; starts with large text-based tool tip tabs around the work area. You may change this look to ⪚ save space in the &tdevelop; configuration dialog (Settings -Configure KDevelop... User +Configure TDevelop... User Interface). If you use an older &tdevelop; 3 version, this configuration dialog may not be available. To change the toolview tabs display manually, place a diff --git a/doc/tdevelop/plugin-tools.docbook b/doc/tdevelop/plugin-tools.docbook index ad10fb16..174767e2 100644 --- a/doc/tdevelop/plugin-tools.docbook +++ b/doc/tdevelop/plugin-tools.docbook @@ -14,11 +14,11 @@ For example, in the file menu there is a Quick Open feature, but only if it's enabled in the Project - Project Options dialog. -Technically, plugins are based on the KDevPlugin class defined in +Technically, plugins are based on the TDevPlugin class defined in lib/interfaces/kdevplugin.h. The following is taken from a comment from there. -KDevPlugin is the base class for all TDevelop plugins. +TDevPlugin is the base class for all TDevelop plugins. A plugin is a component which is loaded into TDevelop shell at startup or by request. A plugin has a scope that can be either: @@ -32,7 +32,7 @@ A plugin has a scope that can be either: are not selectable by user in plugin configuration pages. Global plugins are plugins which require only shell to be loaded and do not operate on -KDevProject interface and/or do not use project wide information. +TDevProject interface and/or do not use project wide information. For example, the uimode plugin allows a developer to select which user interface they wish to use. @@ -43,13 +43,13 @@ The Automake Manager, for example, only needs to be active when an Automake base As stated above, core plugins cannot be disabled. Global plugins can be enabled/disabled in Settings -Configure KDevelop... +Configure TDevelop... under Plugins. Project plugins can be enabled/disabled in Project Project Options... under Plugins. -Active plugins can have many effects on KDevelop. +Active plugins can have many effects on TDevelop. Depending on their function, they may add extra menus, extra menu items, extra tool buttons, etc. @@ -67,13 +67,13 @@ it is because the plugin authors made them this way. Scope: Core - + Application Wizard Application Wizard - + Difference Viewer Difference Viewer - + FileCreate FileCreate @@ -85,7 +85,7 @@ it is because the plugin authors made them this way. User-Interface Selection Provides a dialog for UI-mode selection. - + VCSManager Version Control System Manager @@ -95,13 +95,13 @@ it is because the plugin authors made them this way. Abbreviation Expansion Provides support for customizable abbreviations - short words which expand into commonly needed code structures. - + Documentation The Documentation plugin offers browsing and searching in local and online documentation with support for multiple documentation systems. FileList Provides a list of all currently open files. (Handy when the tab bar is not quite wide enough.) - + File Selector Powerful network transparent file browser utility. @@ -109,14 +109,14 @@ it is because the plugin authors made them this way. Provides a way of manipulating editor text using commandline tools. Appears in the Tools menu. Grep Frontend -Integrates "find|grep" in KDevelop - allows fast searching of multiple files using patterns or regular expressions. +Integrates "find|grep" in TDevelop - allows fast searching of multiple files using patterns or regular expressions. Embedded Konsole -This plugin gives KDevelop an embedded konsole for quick and easy command line access. +This plugin gives TDevelop an embedded konsole for quick and easy command line access. "Open with" Menu Addon -This plugin provides additional "open" alternatives for various context menus in KDevelop. - +This plugin provides additional "open" alternatives for various context menus in TDevelop. + Part Explorer Tool A Graphical tool for performing TDETrader-like queries about registered services @@ -127,7 +127,7 @@ it is because the plugin authors made them this way. This plugin is an interactive projectwide "Search and Replace" tool. Search using string or regexp matching, and select the replacements to be made from a preview before the action is finalized. When loaded it appears in the Edit menu. Scripting -The Scripting plugin offers KScript based scripting of the KDevelop application +The Scripting plugin offers KScript based scripting of the TDevelop application Code Snippets This plugin allows you to store code snippets and add them to your code @@ -242,13 +242,13 @@ templates than for &Java;. The set of code templates is configurable. If the plugin is enabled, you can see which ones are available in the Settings -Configure KDevelop... +Configure TDevelop... dialog under Abbreviations. - + The <command>filter</command> Plugin filter diff --git a/doc/tdevelop/project-advanced.docbook b/doc/tdevelop/project-advanced.docbook index a87b1658..81c0e4a6 100644 --- a/doc/tdevelop/project-advanced.docbook +++ b/doc/tdevelop/project-advanced.docbook @@ -42,10 +42,10 @@ -Converting Old KDevelop Project Files +Converting Old TDevelop Project Files -&tdevelop; allows you to open old KDevelop 2.x project files and convert them to &tdevelop; files. To do so go to Open Project... and select KDevelop 2 project files in the Filter:. Then select project file you want to open. The project gets converted to &tdevelop; and saved as a &tdevelop; project file. +&tdevelop; allows you to open old TDevelop 2.x project files and convert them to &tdevelop; files. To do so go to Open Project... and select TDevelop 2 project files in the Filter:. Then select project file you want to open. The project gets converted to &tdevelop; and saved as a &tdevelop; project file. diff --git a/doc/tdevelop/setup.docbook b/doc/tdevelop/setup.docbook index 0c078a3b..2c448945 100644 --- a/doc/tdevelop/setup.docbook +++ b/doc/tdevelop/setup.docbook @@ -271,14 +271,14 @@ This let you choose the way you want .ui files to be displa This uses &tdevelop; own designer embedded within &tdevelop; Run &tdevelop;'s designer as a separate application - The KDevDesigner application will be run separately in its own window. + The TDevDesigner application will be run separately in its own window. - + - KDevDesigner in its own window + TDevDesigner in its own window @@ -294,7 +294,7 @@ Run Qt Designer Terminal Emulation -You choose here which terminal you want to be integrated within KDevelop. +You choose here which terminal you want to be integrated within TDevelop. @@ -349,7 +349,7 @@ A typical example of this user interface mode is Borland Delphi 6.0. -To switch the user interface mode select Settings Configure &tdevelop;... from the menus. The Customize KDevelop dialog will pop up, where you have to select User Interface in the left hand tree. This will display the following settings dialog to the right. +To switch the user interface mode select Settings Configure &tdevelop;... from the menus. The Customize TDevelop dialog will pop up, where you have to select User Interface in the left hand tree. This will display the following settings dialog to the right. @@ -524,7 +524,7 @@ The active toolview window must be shown fixed (non-overlap mode), sharing the w Selecting an Editor -&tdevelop; allows you to select your favorite text editor tool. Mark the Editor entry in the left hand side selections tree of the Configure KDevelop window. The following dialog will be displayed to the right. +&tdevelop; allows you to select your favorite text editor tool. Mark the Editor entry in the left hand side selections tree of the Configure TDevelop window. The following dialog will be displayed to the right. @@ -568,7 +568,7 @@ Changing the editor will not effect already open files. There are two possibilit -KDevelop lets you use editor interfaces which have registered with &kde; and that provide a KatePart interface. If you miss one one of the selections shown above check your &kde; installation if the corresponding KPart was correctly installed. +TDevelop lets you use editor interfaces which have registered with &kde; and that provide a KatePart interface. If you miss one one of the selections shown above check your &kde; installation if the corresponding KPart was correctly installed. What to do if the file has been changed externally: @@ -663,7 +663,7 @@ The reformat source feature is currently available for C, C++, and &Java; only. -To set up a specific format style, select Settings Configure &tdevelop;.. from the menubar. The Customize KDevelop dialog will pop up, where you have to select Source Formatter in the left hand tree. This will display a series of three settings dialog tabs to the right, namely a General Formatting Setup, a Indentation Style Setup, and a Other Formatting Setup. +To set up a specific format style, select Settings Configure &tdevelop;.. from the menubar. The Customize TDevelop dialog will pop up, where you have to select Source Formatter in the left hand tree. This will display a series of three settings dialog tabs to the right, namely a General Formatting Setup, a Indentation Style Setup, and a Other Formatting Setup. @@ -997,7 +997,7 @@ split a long line apart. For C/C++ code this can be controlled here. Setting Up the Code Snippets Tool -When editing in &tdevelop; you can store often used parts of code as Code Snippets. To configure the capabilities of the code snippets part select Settings Configure &tdevelop;.. from the menubar. The Customize KDevelop dialog will pop up, where you have to select Code Snippets in the left hand tree. This will show the following dialog in the right hand side. +When editing in &tdevelop; you can store often used parts of code as Code Snippets. To configure the capabilities of the code snippets part select Settings Configure &tdevelop;.. from the menubar. The Customize TDevelop dialog will pop up, where you have to select Code Snippets in the left hand tree. This will show the following dialog in the right hand side. @@ -1089,7 +1089,7 @@ system. The behaviour of the File Selector can be highly configured. Select Settings Configure &tdevelop;.. from the -menubar. The Customize KDevelop dialog will pop up, +menubar. The Customize TDevelop dialog will pop up, where you have to select File Selector in the left hand tree. This will show the following dialog in the right hand side. @@ -1330,7 +1330,7 @@ If &tdevelop; was automatically restarted by the &kde; session manager the chang -You may set up contents and behaviour of the various parts of this documentation window if you select Settings Configure &tdevelop;.. from the menubar. The Customize KDevelop dialog will pop up, where you have to select Documentation in the left hand window. +You may set up contents and behaviour of the various parts of this documentation window if you select Settings Configure &tdevelop;.. from the menubar. The Customize TDevelop dialog will pop up, where you have to select Documentation in the left hand window. @@ -1662,10 +1662,10 @@ You must put the &API; of your current project into this Doxygen Docum -Handling Structured Documentation (KDevelopTOC Files) +Handling Structured Documentation (TDevelopTOC Files) -The main bulk of the &tdevelop; documentation facility provides immediate access to structured documentation, local as well as remote ones. You can configure this on the KDevelopTOC Documentation Collection page. +The main bulk of the &tdevelop; documentation facility provides immediate access to structured documentation, local as well as remote ones. You can configure this on the TDevelopTOC Documentation Collection page. @@ -1674,17 +1674,17 @@ The main bulk of the &tdevelop; documentation facility provides immediate access - Providing KDevelopTOC structured documentation access + Providing TDevelopTOC structured documentation access -&tdevelop; comes with a bunch of predefined KDevelopTOC files which are automatically entered in the table at installation time. To keep the display manageable only the most often used will initially be marked for display. If you want to see another documentation, mark the TOC check box in the setup table. +&tdevelop; comes with a bunch of predefined TDevelopTOC files which are automatically entered in the table at installation time. To keep the display manageable only the most often used will initially be marked for display. If you want to see another documentation, mark the TOC check box in the setup table. -KDevelopTOC files cannot be indexed to perform a full text search because they usually point to a remote location. On the other hand, such a .toc file can have an index manually defined, using the <index> tag. Thus the Index check box will be enabled ony when &tdevelop; finds an <index> tag in the .toc file. (For more detail see the description below in the &tdevelop; TOC Files section.) +TDevelopTOC files cannot be indexed to perform a full text search because they usually point to a remote location. On the other hand, such a .toc file can have an index manually defined, using the <index> tag. Thus the Index check box will be enabled ony when &tdevelop; finds an <index> tag in the .toc file. (For more detail see the description below in the &tdevelop; TOC Files section.) The Search check box in the setup table will alway be disabled. @@ -1720,7 +1720,7 @@ Such structured access is made possible through the use of special table Standard Directory of &tdevelop; TOC Files -When &tdevelop; was installed usually a series of predefined .toc files has been put into the $TDEDIR/share/apps/kdevdocumentation/tocs directory. These are fairly simple, structured text files. You may look at them using a text editor or other text display facility. +When &tdevelop; was installed usually a series of predefined .toc files has been put into the $TDEDIR/share/apps/tdevdocumentation/tocs directory. These are fairly simple, structured text files. You may look at them using a text editor or other text display facility. diff --git a/doc/tdevelop/survey-manual.docbook b/doc/tdevelop/survey-manual.docbook index 0bd59c8d..93c1fd63 100644 --- a/doc/tdevelop/survey-manual.docbook +++ b/doc/tdevelop/survey-manual.docbook @@ -198,7 +198,7 @@ necessary and why you need an &IDE;. --> -KDevelop User Interface Mode Examples +TDevelop User Interface Mode Examples Shows user interface modes. diff --git a/doc/tdevelop/tdevdesigner.png b/doc/tdevelop/tdevdesigner.png new file mode 100644 index 00000000..4fa74c68 Binary files /dev/null and b/doc/tdevelop/tdevdesigner.png differ diff --git a/doc/tdevelop/tdevelop-install.docbook b/doc/tdevelop/tdevelop-install.docbook index 14f7236b..663d9d08 100644 --- a/doc/tdevelop/tdevelop-install.docbook +++ b/doc/tdevelop/tdevelop-install.docbook @@ -699,7 +699,7 @@ The tdebuildsycoca command does not run from within the root. API is the short form of Application Program Interface. Actually such an API cotains a series of descriptions (&ie; calling conventions) by which an application program can access the operating system and other services. In our context, however, a broader definition was adopted. The API of a &kde; or &Qt; application is an abstract of the classes and methods interfaces, a synopsis to be used like a dictionary to navigate the sources. -There is a version of the most current API available at the KDevelop-Home website. It will be automatically updated every 24 hours so you can keep up. +There is a version of the most current API available at the TDevelop-Home website. It will be automatically updated every 24 hours so you can keep up. Alas, this version is best used read-only over the internet. If you do not always have internet access you may as well build your own API documentation from the &tdevelop; sources. To do so, you must tell the automake system where to find the KDELIBS API in your system. This is accomplished by the special option in the configure command when you prepare to compile the &tdevelop; sources: diff --git a/doc/tdevelop/tdevelop-scripting.docbook b/doc/tdevelop/tdevelop-scripting.docbook index 1b722f2d..1cb8a294 100644 --- a/doc/tdevelop/tdevelop-scripting.docbook +++ b/doc/tdevelop/tdevelop-scripting.docbook @@ -7,12 +7,12 @@ -Using Scripts in KDevelop +Using Scripts in TDevelop Running Scripts - To access a script that is available to &tdevelop; use the ToolsScripts menu. If there there is no such menu item then there are no installed scripts available to KDevelop. + To access a script that is available to &tdevelop; use the ToolsScripts menu. If there there is no such menu item then there are no installed scripts available to TDevelop. diff --git a/doc/tdevelop/tdevelop-survey.docbook b/doc/tdevelop/tdevelop-survey.docbook index 0f117958..7aca28a9 100644 --- a/doc/tdevelop/tdevelop-survey.docbook +++ b/doc/tdevelop/tdevelop-survey.docbook @@ -145,7 +145,7 @@ switch UI modes -To switch the user interface mode select Settings Configure KDevelop... from the menus. The Customize KDevelop dialog will pop up, where you have to select User Interface in the left hand tree. This will display the settings page shown below. +To switch the user interface mode select Settings Configure TDevelop... from the menus. The Customize TDevelop dialog will pop up, where you have to select User Interface in the left hand tree. This will display the settings page shown below. -- cgit v1.2.1