From 114a878c64ce6f8223cfd22d76a20eb16d177e5e Mon Sep 17 00:00:00 2001 From: toma Date: Wed, 25 Nov 2009 17:56:58 +0000 Subject: Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features. BUG:215923 git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdevelop@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da --- doc/api/Architecture.dox | 315 +++++++++++++++++++++++++++++ doc/api/Architecture.png | Bin 0 -> 71707 bytes doc/api/Architecture.sxd | Bin 0 -> 7581 bytes doc/api/Development.png | Bin 0 -> 71400 bytes doc/api/Development.sxd | Bin 0 -> 8396 bytes doc/api/EditorsSupportStatus.dox | 189 ++++++++++++++++++ doc/api/FutureTasks.dox | 136 +++++++++++++ doc/api/HighPriTasks.dox | 36 ++++ doc/api/HowToAddApplicationTemplates.dox | 285 ++++++++++++++++++++++++++ doc/api/HowToAddFileTemplates.dox | 30 +++ doc/api/HowToAddGenericBuildTools.dox | 21 ++ doc/api/HowToAddPlugins.dox | 204 +++++++++++++++++++ doc/api/HowToAddProgrammingLanguages.dox | 252 +++++++++++++++++++++++ doc/api/HowToDocument.dox | 39 ++++ doc/api/LangSupportStatus.dox | 330 +++++++++++++++++++++++++++++++ doc/api/Mainpage.dox | 91 +++++++++ doc/api/PropEditor.dox | 108 ++++++++++ doc/api/propeditor1.png | Bin 0 -> 3937 bytes doc/api/propeditor2.png | Bin 0 -> 3697 bytes 19 files changed, 2036 insertions(+) create mode 100644 doc/api/Architecture.dox create mode 100644 doc/api/Architecture.png create mode 100644 doc/api/Architecture.sxd create mode 100644 doc/api/Development.png create mode 100644 doc/api/Development.sxd create mode 100644 doc/api/EditorsSupportStatus.dox create mode 100644 doc/api/FutureTasks.dox create mode 100644 doc/api/HighPriTasks.dox create mode 100644 doc/api/HowToAddApplicationTemplates.dox create mode 100644 doc/api/HowToAddFileTemplates.dox create mode 100644 doc/api/HowToAddGenericBuildTools.dox create mode 100644 doc/api/HowToAddPlugins.dox create mode 100644 doc/api/HowToAddProgrammingLanguages.dox create mode 100644 doc/api/HowToDocument.dox create mode 100644 doc/api/LangSupportStatus.dox create mode 100644 doc/api/Mainpage.dox create mode 100644 doc/api/PropEditor.dox create mode 100644 doc/api/propeditor1.png create mode 100644 doc/api/propeditor2.png (limited to 'doc/api') diff --git a/doc/api/Architecture.dox b/doc/api/Architecture.dox new file mode 100644 index 00000000..ae4ef73d --- /dev/null +++ b/doc/api/Architecture.dox @@ -0,0 +1,315 @@ +/** \file Architecture.dox + * \brief KDevelop architecture + */ + +/** \page architecture KDevelop 3 Architecture + +KDevelop uses a plugin based architecture. This will be explained in more +detail in the next sections. To add a new plugin check the \ref howToAddPlugins page. + +\section devteammodel Development Team cooperation model + +KDevelop is the result of the work of many people. To help syncronize the effords and to automate +some tasks, the team uses many tools: + + - CVS servers + - KDE Bugzilla + - Web servers + - Mailing Lists + - IRC + - Doxygen + - docbook + - LXR + - E-mail :) + - Cron Jobs + - and of course KDevelop :) + . + +They get interconnected like this: + +\image html Development.png + + +\section overview Source Overview + +\subsection source-division Main Source Divisions + +The KDevelop 3 source is divided into several parts which correspond to +subdirectories in the KDevelop project directory. There are several main +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 ) + - languages = \ref language-parts + - buildtools = \ref buildtool-parts + - vcs = \ref vcs-parts + - editors = \ref editor-parts + . + +\image html Architecture.png + +This image is not complete there are parts that are not displayed. See below for a more detailed description. + +\subsection core-part The Core Part of KDevelop + +\subsubsection mainwindows Main Window Objects + +There are two types of possible main window objects: + + - MainWindow implements standard MDI user interfaces: + - Top level mode (see MainWindow::switchToToplevelMode() ) + - Childframe mode (see MainWindow::switchToChildframeMode() ) + - Tab page mode (see MainWindow::switchToTabPageMode() ) + - IDEAl mode (see MainWindow::switchToIDEAlMode() ) + . + - MainWindowIDEAl implements an enhanced MDI main window providing a set of + pre-arranged access tabs around user areas. + . + +Both main window classes inherit from the KDevMainWindow 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 +be accessed through the static function TopLevel::getInstance() (see the +TopLevel class). + +\subsection parts-overview KDevelop Parts Overview + +All parts reside in dedicated subdirectories acording to their function. They can +be viewed according to their functionalities as follows. + +\subsubsection language-parts Programming Language Support Parts + +These parts implement a KDevLanguageSupport 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. + + - languages/ada = Support for Ada + - (see AdaSupportPart) + . + - languages/bash = Support for bash + - (see BashSupportPart) + . + - languages/cpp = Support for C/C++ + - (see CppSupportPart) + - languages/cpp/debugger = GNU Debugger frontend + - (see GDBDebugger::DebuggerPart) + . + . + . + - languages/fortran = Support for Fortran + - (see FortranSupportPart) + . + - languages/haskell = Support for Haskell + - (see HaskellSupportPart) + . + - languages/java = Support for Java + - (see JavaSupportPart) + - languages/java/degugger = Java debugger frontend + - (JAVADebugger::JavaDebuggerPart) + . + . + . + - languages/pascal = Support for Pascal + - (see PascalSupportPart) + . + - languages/perl = Support for Perl + - (see PerlSupportPart) + . + - languages/php = Support for PHP + - (see PHPSupportPart) + . + - languages/python = Support for Python + - (see PythonSupportPart) + . + - languages/ruby = Support for Ruby + - (see RubySupportPart) + . + - languages/sql = Support for SQL + - (see SQLSupportPart) + . + . + +\subsubsection buildtool-parts Build tools Parts + +These parts implement a KDevProject Class interface. + + - buildtools/ada = Ada build tool + - (see AdaProjectPart) + . + - buildtools/ant = ANT build tool + - (see AntProjectPart) + . + - buildtools/autotools = Autotools build tool + - (see AutoProjectPart) + . + - buildtools/custommakefiles = Custom makefiles build tool + - (see CustomProjectPart) + . + - buildtools/generic = Generic build tool + - (see GenericProjectPart) + . + - buildtools/pascal = Pascal build tool + - (see PascalProjectPart) + . + - buildtools/script = Script build tool + - (see ScriptProjectPart) + . + - buildtools/qmake = QMake based build tool + - (see TrollProjectPart) + . + . + + +\subsubsection vcs-parts VCS (Version Control System) Parts + +These parts implement a KDevVersionControl Class interface. + + - vcs/cervisia = Cervisia Support + - (see CervisiaPlugin) + . + - vcs/clearcase = IBM Rational ClearCase Support + - (see ClearcasePart) + . + - vcs/cvs = CVS Support + - (see CvsPart) + . + - vcs/cvsservice = cvsservice Support (Cervisia interface) + - (see CvsServicePart) + . + - vcs/perforce = Version managment system perforce integration + - (see PerforcePart) + . + - vcs/subversion = Subversion integration + - (see subversionPart) + . + . + + +\subsubsection editor-parts editor support Specific Parts + +These parts implement a KTextEditor Class interface. +Take a look at \ref EditorsSupportStatus (doc/api/EditorsSupportStatus.dox file) to see the current status/features of the editors currently supported by KDevelop. + + - editors/editor-chooser = Chooses an internal text editor + - (see EditorChooserPart) + . + - editors/nedit = KTextEditor interface for nedit + - (see KNEditFactory, Document, View) + . + - editors/qeditor = QEditor integration + - (see QEditorPart) + . + . + + +\subsubsection global-parts Global Parts + +Some of the parts are considered global - that is, they effect the entire +operation of KDevelop. + +These parts implement a KDevPlugin Class interface. + + - parts/appwizard = New Project Wizard + - see AppWizardPart + - see \ref howToAddApplicationTemplates (doc/api/HowToAddApplicationTemplates.dox file) + . + - parts/history = Project history + - (see HistoryPart) + . + - parts/konsole = Embedded Konsole + - (see KonsoleViewPart) + . + - parts/doctreeview = Documentation Viewer + - (see DocTreeViewPart) + . + - parts/openwith = "Open with" menu addon + - (see OpenWithPart) + . + - parts/fileselector = A file selection widget + - (see FileSelectorPart) + . + - parts/uimode = Customize the UI mode + - (see UIChooserPart) + . + - parts/texttools = Additional text tools + - (see TextToolsPart) + . + - parts/tipofday = A tip of the day + - (see TipOfDayPart) + . + - parts/grepview = A graphical grep utility + - (see GrepViewPart) + . + - parts/tools = Toolbar management + - (see ToolsPart) + . + - parts/regexptest = A regular expression tester + - (see RegexpTestPart) + . + - parts/abbrev = Abbreviation Expansion + - (see AbbrevPart) + . + - parts/filter = Shell Filtering and Insertion + - (see FilterPart) + . + - parts/valgrind = A graphical valgrind frontend + - (see ValgrindPart) + . + . + + +\subsubsection project-specific-parts Project Specific Parts + +These parts implement a KDevPlugin Class interface. + + - parts/astyle = Source code formatter + - (see AStylePart) + . + - parts/buglist = Bug tracking application + - (see BugList) + . + - parts/classview = Classview Manager + - (see ClassViewPart) + . + - parts/ctags = CTags frontend + - (see CTagsPart) + . + - parts/diff = Difference viewer + - (see DiffPart) + . + - parts/distpart = Aids in building and publishing the final project + - (see DistpartPart) + . + - parts/doxygen = Doxygen integration + - (see DoxygenPart) + . + - parts/filecreate = New file creation + - see FileCreatePart + - see \ref howToAddFileTemplates (doc/api/HowToAddFileTemplates.dox file) + . + - parts/fileview = File groups + - (see FileViewPart, FileGroupsPart) + . + - parts/manager = Document manager + - (see DocManager, ViewManager) + . + - parts/outputviews = Application output views + - (see AppOutputViewPart, MakeViewPart) + . + - parts/scripting = Python scripting interface + - (see ScriptingPart) + . + - parts/sourcenav = Source code navigation + - (see SourceNavPart) + . + - parts/visualboyadvance = VisualBoy Advance integration + - (see VisualBoyAdvance::VisualBoyAdvancePart) + . + . + +*/ + diff --git a/doc/api/Architecture.png b/doc/api/Architecture.png new file mode 100644 index 00000000..306881fa Binary files /dev/null and b/doc/api/Architecture.png differ diff --git a/doc/api/Architecture.sxd b/doc/api/Architecture.sxd new file mode 100644 index 00000000..b48f9a36 Binary files /dev/null and b/doc/api/Architecture.sxd differ diff --git a/doc/api/Development.png b/doc/api/Development.png new file mode 100644 index 00000000..063e63db Binary files /dev/null and b/doc/api/Development.png differ diff --git a/doc/api/Development.sxd b/doc/api/Development.sxd new file mode 100644 index 00000000..ff5b06cc Binary files /dev/null and b/doc/api/Development.sxd differ diff --git a/doc/api/EditorsSupportStatus.dox b/doc/api/EditorsSupportStatus.dox new file mode 100644 index 00000000..e826471c --- /dev/null +++ b/doc/api/EditorsSupportStatus.dox @@ -0,0 +1,189 @@ +/** \file EditorsSupportStatus.dox + * \brief Editors Support Status + */ + +/** \page EditorsSupportStatus Editors Support Status + +Kate and Kvim are part of KDE and KDevelop just uses them. + +qeditor and Nedit are interfaced via KDevelop's code. You can look at their code at editors/qeditor and editors/nedit. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
features/editorkatekvim (KDE 3.2)qeditorNedit (Disabled)
Advanced text editor
Open, close and save big text filesYNYY
Undo and redoYNY
Jump in text: next/previous character, word.YNYY
Jump to start or the end of the line/textYNYY
Go to lineYNY
Select text when jumping (character, word, line), YNY
Select all the textYNY
Copy, paste and delete selections of textYNY
PrintYNY
Advanced text view:
Horizontal and vertical scrollingYNY
Display selectionsYNY
Mouse Wheel supportYNY
Dynamic word wrapYN
Line numbersYN
Show tabsYN
Find in fileYNY
Replace in fileYNY
Coding specific properties:



Syntax highlightingYNY
Code foldingYN
SpellYN
Auto indendtNNY
+ +*/ diff --git a/doc/api/FutureTasks.dox b/doc/api/FutureTasks.dox new file mode 100644 index 00000000..fbed119a --- /dev/null +++ b/doc/api/FutureTasks.dox @@ -0,0 +1,136 @@ +/** \file FutureTasks.dox + * \brief Future tasks and ideas for the next release of KDevelop + */ +/** \page FutureTasks Future tasks and ideas for the next release of KDevelop + +\section codereftodo Code Refactoring / Improvements: + + - Core + - Make sure all lib interfaces are available via DCOP + - Find a nicer way to remove dynamic menu entries from context menus + - Resolve the path handling mess + - Project name should be able to contain spaces + - Import existing directory: Should be named "Import existing project" + and more intuitive (wizard-like) + - Question from the wizard: "I have found C++ files in your + project directory. Should C++ be the primary language of your + project?" User: [Yes/No] => Next Step... + - Something intuitive for the binary/-ies (for debugger and + execution of program), libtool ([Yes/No] for the debugger), build + tool (qmake, automake,...?), etc.., too. + - use mimetype to determine code files, not extension + (see bug # + - Make the help buttons (that we already have) open the KDevelop Handbook on + the correct page (or the index if the subject is not covered yet). + - New and improved VCS framework (Needs better description) + - Another look at the plugin system (Nees better description) + - Another look at the project files (shared, non-shared, session) + - fix(redesign?) project language switching + - editor handling could be made a bit saner if editor plugin switching was an after-restart-only feature + + - Programming Language Support Parts + - Create base classes for language support parts: + - AntlrLanguageSupport + - AntlrBackgroundParser + - AntlrProblemReporter + - Same for: + - YaccLanguageSupport + - YaccBackgroundParser + - YaccProblemReporter + - There is a possibility to create even something like + - LanguageSupportBase + + Look at java, pascal and ada support parts to get more inspiration. + There should be base classes for ada, java and pascal language supports - too much code duplication. + + - CppSupportPart + - Extended "make member" functionality - run on a .h to implement stubs for all unimplemented non-abstract methods + - Code Refactoring + - text hint type info tooltips (edit mode) + - text hint value info tooltips (debug mode) + - Make the language plugin know stuff like what file patterns to look for (for instance, "find in files" needs this) + + - Build tools Parts + - Show .po files in project management + - Custom actions for groups, targets and files for project managers: + - any menu item should be a KAction plugged into KPopupMenu, also we need to define shortcuts for any such action, + also we should make sure those actions are properly executed from a shortcut. + - AutoProjectPart + - Should be able to DND files from other targets / file list / konq to add to targets + - Should loose the experimental crashy and nonstandard "add files" dialog + - Update configure.in when sub projects are added and the project doesn't use am_edit + - Keep the correctly cased project name and save it to the project file + + - Debugger Parts + - Create a debugger support base classes. Make the current GDB support a plugin. + - Implement parts for other debuggers i.e. DBX, WDB, Ladebug, JDB, XDB, bashdb, the Perl debugger, or the Python debugger. + We can use DDD as inspiration. + - General debugger + - variable widget + - set variable by editing the value in the tree + - cast value by editing the type in the tree + - disassembly + - add breakpoint display + - set breakpoint by selecting a line as in the edit window + - allow scrolling of disassembled code about and below current limits + - add source to disassembled code as comments + - basically just re-work the whole disassemble window :) + - Bugs + - Fix "core file" handling + - Fix "attach to" handling + - Breakpoints can disappear at odd times + - When the target program crashes, the debugger can't be started again. (intermittant?) + - Break on method() - could have multiple methods which require a choice. How to handle this? + + + - Plugins + - DocTreeViewPart + - Implement plugin system for doctreeview. + - improve documentation browsing + - Check if a man page exists before offering the context menu item 'Goto manpage' + - right click -> set as bookmark in docviewer + - ClassViewPart + - Implement language-dependant plugin system for classview: + - namespaces/classes/functions are not always applicable to a language, we need a way to correctly + fill a class view and combo boxes - only a language support can do that properly. + - Distinguish vanilla c++ support from c++ + Qt extensions and show signals/slots in the class view only with Qt. (is this still valid?) + - KonsoleViewPart + - Perhaps use konsole part for the application frontend + - cd's when selecting a file, but doesn't when selecting a dir, + desired: a menu option to "cd" to that directory + - QEditor + - Replace editors/qeditor/koReplace.* and editors/qeditor/koFind.* with kdelibs/kutils/kreplace.* and kdelibs/kutils/kfind.* + + +\section extensiontodo Extensions / New Functionality: + + - Core + - implement multiple-views per document (why?) + - Document manager (not obviously useful) + - Implement Add Plugin + - Show intro page on startup + - Programming Language Support Parts + - Build tools Parts + - Plugins + - better sourcenav part (all navigation tools should be supported with at least a "back" action - forward much less important) + - Integrate kontact's TODO-List and knotes plugin. (We need something like a + server/client system that all the knotes/toto-clients are always synced.) + - a generic macro-tool (if possible, probably best implemented as a KTE plugin) + - Free grouping of files in file group plugin + + +\section misctodo Miscellaneous (and possibly invalid) items: + + - UI bugs + - Editor options dialog missing when all views are closed (virtually impossible to fix) + - If you click an error in the output view, "Next Error"/"Previous + Error" should then start from that point (already implemented?) + - Messages in status bar would look nicer if they appeared with + 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 + least the selection parts (Automake Manager, Class Browser, File + Groups, etc...) + +*/ diff --git a/doc/api/HighPriTasks.dox b/doc/api/HighPriTasks.dox new file mode 100644 index 00000000..21116342 --- /dev/null +++ b/doc/api/HighPriTasks.dox @@ -0,0 +1,36 @@ +/** \file HighPriTasks.dox + * \brief High priority tasks + */ +/** \page HighPriTasks High priority tasks! + +\section fixMajBugs Fixing major/annoying bugs + + - Fix the mess of .kdevelop and .kdevses file. + - All project wide setings should go into .kdevelop and + - all session (and personal) options should go into .kdevses file + . + This way the .kdevelop file can be shared in teams of developers. + + +\section KDevelop2compat KDevelop 2 compatibility +(These are things that must be accomplished before we can say that KDevelop 3 +>= kdevelop 2.x UI-wise and functionality-wise!) + + - general UI issues: + - toplevel UI mode broken concerning to the accels + - [Modified] missing in mainframe caption + - captions missing for toolbar buttons + . + - build/configuration: + - cross-compiling feature missing + - make "MIN_VERSION" configurable on new project creation + . + - doctreeview: + - implement "Make User Manual" + - use kdoc to update Qt/KDE docs + . + - Solve the regression bugs. These are the ones +marked with priority "HI" in the bug database + + +*/ diff --git a/doc/api/HowToAddApplicationTemplates.dox b/doc/api/HowToAddApplicationTemplates.dox new file mode 100644 index 00000000..7eec80c7 --- /dev/null +++ b/doc/api/HowToAddApplicationTemplates.dox @@ -0,0 +1,285 @@ +/** \file HowToAddApplicationTemplates.dox + * \brief How to add application templates to the application wizard part + */ +/** \page howToAddApplicationTemplates How to add application templates to the application wizard part + +Project templates provide the developer with a basic application framework. +This is necessary for rapid application development (RAD) and makes it even possible +for an inexperienced 3rd party developer to create standard conforming +applications like kedit as well as plugins for example for kdevelop or noatun.\n\n +\ref templates_1\n + - \ref templates_1_1 + - \ref templates_1_2 + - \ref templates_1_2a + - \ref templates_1_2b + - \ref templates_1_2c + - \ref templates_1_2d + - \ref templates_1_2e + . + . +\ref templates_2\n +\ref templates_3\n +\ref templates_4\n + +
+ +\section templates_1 I. Example: How To Create a Simple KDE Application Template "KHello" + +You can find this template in $KDEDIR/share/apps/kdevappwizard/template-khello. + +\subsection templates_1_1 I.1. Step 1: Basic Skeleton + +Create a directory template-khello with the files +
+    - template-khello/app.cpp
+    - template-khello/app.h
+    - template-khello/app.desktop
+    - template-khello/app.kdevelop
+    - template-khello/appui.rc
+    - template-khello/khello
+    - template-khello/main.cpp
+    - template-khello/preview.png
+    - template-khello/script
+    - template-khello/src-Makefile.am
+    - template-khello/subdirs
+    .
+
 +\note The directory name must begin with "template-". + +\subsection templates_1_2 I.2. Step 2: The Files in Detail + +Have a look into the files! There are some variables which the application +wizard will replace: +
+    - \%{AUTHOR} ...... by the author
+    - \%{EMAIL} ....... by the e-mail address 
+    - \%{VERSION} ..... by the version
+    - \%{APPNAME} ..... by the project name (KHello)
+    - \%{APPNAMELC} ... by the project name in lowercase (khello)
+    - \%{APPNAMEUC} ... by the project name in uppercase (KHELLO)
+    - \%{LICENSE} ..... by the license (GPL, BSD, QPL, LGPL, ...)
+    - \%{LICENSEFILE} . by the licensefile
+    - \%{YEAR} ........ by the year
+    .
+
 +All this can be found in $KDEDIR/share/apps/kdevappwizard/template-common/kdevelop.pm. +\subsubsection templates_1_2a I.2.1. The Source Files + +The files template-khello/app.cpp, template-khello/app.h and +template-khello/main.cpp contain the source code that should not +be too special so that the user can implement his own ideas.\n +(There may be variables included - see \ref templates_1_2 "Step 2: The Files in Detail"). + +\subsubsection templates_1_2b I.2.2. The File template-khello/khello + +It may look like this: +\verbinclude khello/khello + +The application wizard looks into this file to get + - the information where to integrate the plugin into the the listview (Category=) + - the name (Name=) and the comment (Comment=) + - the preview image (Icon=) + - and the file templates the project uses (FileTemplates=). + . +Further information could be (not required): + - Comment= a small comment for the template. Longer comments should go into a README.devel and shown on startup + - ShowFilesAfterGeneration= a comma-separated list (without whitespaces) of files that should be opened immediately after the generation, for instance a README.devel or a source file the user has to modify, the path is relative to the project directory (example: ShowFilesAfterGeneration=src/main.cpp,src/plugin.cpp). And + - APPNAMEUC will be replaced with the projectname in uppercase, + - APPNAMELC will be replaced with the projectname in lowercase, + - APPNAME will be replaced with the projectname. + . + - DefaultDestinatonDir changes the default destination dir for the project (~) to your value, whereas HOMEDIR is a keyword + . + +\attention The file template-khello/khello must have the same name as +the right half of the directory! If the directory is template-foobar +the file must be template-foobar/foobar. + +\see AppWizardPart for more information. + +\subsubsection templates_1_2c I.2.3. Some Additional Files + +The file + - template-khello/appui.rc contains information about the toolbar and the menu. + - template-khello/preview.png will be shown in the aplication wizard. + - template-khello/app.desktop describes the application. + - template-khello/subdirs contains a list of the subdirectories (usually doc, po, src) and can be found in the project root directory. It is necessary for the autotools. + . + +\subsubsection templates_1_2d I.2.4. The File template-khello/src-Makefile.am + +This file will be copied to the $PROJECTDIR/src/. +\verbinclude khello/src-Makefile.am + +\subsubsection templates_1_2e I.2.5. The File template-khello/script + +The following script is used to install the template and replaces all +variables by the corresponding value. The result is a hopefully working +kdevelop project! +\verbinclude khello/script +
+\note There are several application templates which use some identical +files - that's why some files are taken from the "template-common"-directory. + +\section templates_2 II. Registration/Installation Of The Application Template + +The easiest way to install your template is to provide an "install.sh" shell script.\n +Example: +\code +#!/bin/sh + +kde_prefix=`kde-config --prefix` +if [ `id -u` = 0 ]; then + # we are root so install the template into the global kde directory + kde_dir=`kde-config --prefix` +else + # we are a user so install it into $HOME/.kde/share/apps/kdevappwizard directory + kde_dir=`kde-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]:" +read newdir + +if [ "$newdir"a = a ]; then newdir="${kde_dir}/share/apps/kdevappwizard/"; 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; + +# install now +cp -R --target-directory "$newdir" template-khello +# the file template-khello/khello must go to the "templates" directory that +# kdevelop knows that it exists +mv "$newdir/template-khello/khello" "$newdir/templates/" +echo "done" +\endcode +\n +\attention Please test your template whether it installs and behaves correctly! Test, test and test again! ;) + +\section templates_3 III. How To Add The Template To KDevelop CVS HEAD + +This section is for kdevelop developers only. Most probably you don't have to read this!.\n +Move the directory "template-khello" to kdevelop/languages/cpp/app_templates/ +and then add the following files in kdevelop/languages/cpp/app_templates/template-khello/ +(in this example the language is c++ if you use other language replace cpp with the language name): + - ".kdev_ignore" is an empty file. It prevents KDevelop's + C++-parser from parsing the C++ template files. This is necessary because the template files are just code templates and not real code (yet). + - ".cvsignore" looks like this: +\code +Makefile +Makefile.in +script.local +\endcode + - "Makefile.am" looks like this: + \verbinclude khello/Makefile.am + . +Finally add "template-khello" to "SUBDIRS = " in kdevelop/languages/cpp/app_templates/Makefile.am.\n +\attention Please test your template whether it installs and behaves correctly! +Test, test and test again! It works? Well - now talk to the kdevelop guys so +that they know what's going on and probably you may commit. ;) + +\section templates_4 IV. Changes to the template system (VERY IMPORTANT) + +The entire app template system described above has been changed. +To port a template to the new system the +information from the script file will need to be moved into the ini file. +The example is as follows: +\code +install( +"${src}/template-chello/app.kdevelop","${dest}/${APPNAMELC}.kdevelop" ); +\endcode +becomes +\code +[PROJECT] +Type=install +Source=%{src}/template-chello/app.kdevelop +Dest=%{dest}/%{APPNAMELC}.kdevelop +\endcode + +Things like installIncAdmin(); and installGNU(); now involve unpacking +the tar archives. This is done by creating a target in the ini file as +follows: +\code +[GNU] +Type=install archive +Source=%{src}/template-common/gnu.tar.gz +Dest=%{dest} +\endcode + +The popular script functions convert as follows: +\code +installIncAdmin(); %{src}/template-common/incadmin.tar.gz +installGNU(); %{src}/template-common/gnu.tar.gz +installAdmin(); %{src}/template-common/admin.tar.gz +installGnome(); %{src}/template-common/gnome.tar.gz +installWX(); %{src}/template-common/wxwidgets.tar.gz +\endcode + + +To create directories is now: +\code +[SRC] +Type= mkdir +Dir=%{dest}/src +\endcode + +New additions are as follows: +\code +[MGS] +Type=message +Comment=A simple C project was created in %{dest}. +\endcode + +Will allow you to display a custom message when the template has +finished installing. This is very handy for projects that require +custom variables to be set. + +The concept of custom variables was also introduced. To create a +variable that can be edited from the project wizard you need to add an +entry as follows: +\code +[LIBS] +Type = value +ValueType= +Value= +Comment= +Default= +\endcode + +One special value can be used to turn targets on and off. This is done +by adding a value as follows: +\code +[DOCSOPT] +Type = value +ValueType=bool +Value=INSTALL_DOCS +Comment= Install Docbook documentation templates. +Default=true +\endcode + +Then in the targets you wish to make optional you add the Option +property with the value's name as the data. This will look as follows: +\code +[DOCSDIREN] +Type=mkdir +Dir=%{dest}/doc/en +Option=INSTALL_DOCS +\endcode + +The Option target is available to the mkdir, install, and install +archive targets. + +The last new addition is the optional post processing of the files as +they are copied. For install and install archive you can add a +Process=true or Process=false to turn the processing on or off. + +A note on the UI. its not final, it will get better. Suggestions or +bugs should be noted asap. + +*/ diff --git a/doc/api/HowToAddFileTemplates.dox b/doc/api/HowToAddFileTemplates.dox new file mode 100644 index 00000000..fa6e630b --- /dev/null +++ b/doc/api/HowToAddFileTemplates.dox @@ -0,0 +1,30 @@ +/** \file HowToAddFileTemplates.dox + * \brief How to add file templates to the file create part + */ +/** \page howToAddFileTemplates How to add file templates to the file create part + +File templates provide the developer with a basic file. They are prototypes for both source files of +the project's language, and for other files that may be useful in the project. For example, a C++ +project may have templates for both .cpp and .h files, plus QT Designer .ui files, and supporting +files such as XML. + +These prototypes are placed in parts/filecreate/file-templates dir or +languages/YOURLANGUAGE/file_templates and have names equal to the extensions of language +source files. + +Sometimes, different 'flavours' of template are required for a particular file type. In these +instances, 'subtypes' can be defined to allow several different templates for a file type. An example +of this are QT designer '.ui' files. KDevelop supplies several different templates for .ui +files. Subtypes are named by the file type extension followed by a hyphen followed by an identifier +for the subtype. E.g. ui-widget, ui-dialog + +The description of the prototypes is placed in parts/filecreate/template-info.xml. This +file is fairly self-explanatory if you take a look at it. + +Note that templates and templates information can be edited within KDevelop itself. The global +templates that can be made available to any project can be changed in Settings / Configure KDevelop... / New File +Wizard; and project related settings can be changed in Project / Project Options / New File Wizard. + +That's all! :) + +*/ diff --git a/doc/api/HowToAddGenericBuildTools.dox b/doc/api/HowToAddGenericBuildTools.dox new file mode 100644 index 00000000..b073cf0f --- /dev/null +++ b/doc/api/HowToAddGenericBuildTools.dox @@ -0,0 +1,21 @@ +/** \file HowToAddGenericBuildTools.dox + * \brief How to add a generic build tool plugins to the generic build tool part + */ + +/** \page howToAddGenericBuildTools How to add a generic build tool plugins to the generic build tool part + +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 plugins are located in buildtools/generic/buildsystem. + +\section sectionStep1 Step 1: Make your plugin loadable + +For a plugin foo, create a file foo.desktop which contains KDevelop/Part in its list of ServiceTypes. + +The rest of this document is to be written. + +Document your plugin in the way described at \ref howToDocument (doc/api/HowToDocument.dox file). + +*/ + diff --git a/doc/api/HowToAddPlugins.dox b/doc/api/HowToAddPlugins.dox new file mode 100644 index 00000000..ce8f259a --- /dev/null +++ b/doc/api/HowToAddPlugins.dox @@ -0,0 +1,204 @@ +/** \file HowToAddPlugins.dox + * \brief How to extend KDevelop via plugins + */ + +/** \page howToAddPlugins How to extend KDevelop via plugins + +\section createDesktop Step 1: Make your plugin loadable + +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. + . + +If you install this file into \$(kde_servicesdir), your plugin will automatically be loaded. + +\subsection changeLoading How to change the default loading + +You can change the default loading by changing some settings in your foo.desktop file: + + - Set X-KDevelop-Scope= to Global or + Project + - Note: This property is not optional + . + - You can add a list of programming languages which are supported by your + plugin + - If your plugin works with all languages leave the + X-KDevelop-ProgrammingLanguages= field empty + (optional) + . + - You can add a list of keywords. + - The plugin will only be loaded if all keywords match with the + Keywords= field in the projectfile (optional). + . + . + +An example from the Java Debugger Plugin: + +
+    #######################
+    X-KDevelop-Scope=Project
+    X-KDevelop-ProgrammingLanguages=Java
+    Keywords=
+    ##########################
+
 + + +\section createFactory Step 2: Make the plugin accessible by the factory + +Create a factory class FooFactory which inherits +KDevFactory. Put a section + +
+    extern "C" {
+        void *init_libfoo()
+        {
+            return new FooFactory;
+        }
+    }
+
 + +into the source file, so that the factory can be accessed by KDE's library +loader. Keep in mind that the name of the method init_libfoo() is +required for a library with the name libfoo.so. + +This may be simplified by the use of the +K_EXPORT_COMPONENT_FACTORY macro which is defined in +klibloader.h: + + +K_EXPORT_COMPONENT_FACTORY( libfoo, FooFactory ); + + + - Note: Your factory must reimplement the + createPartObject() method of KDevFactory and + produce the part there. + . + +See parts/doctreeview/doctreeviewfactory.cpp for an example. + + +\section implementPart Step 3: Implement your part. + +Your part must be derived from KDevPlugin. + + - KDevPlugin takes two arguments: + - 1) A parent argument. This also comes from + createPartObject(). + - 2) A name, which in turn is given to the QObject + constructor. + . + . + +\subsection accessIDE How to access other IDE components + +A part can access other components of the IDE via some accessors +of KDevPlugin: + + - The application core via core(), + - the build tools via project(), + - the programming language specific stuff via + languageSupport(), + - the make frontend via makeFrontend(), + - the part which displays appication output via + appFrontend(), + and finally + - the symbol database via classStore(). + . + +In order to see what these components provide, see lib/interfaces/kdev*.h. + +\subsection userPrefs How to store user preferences + +Parts can also store user preferences on a per-project basis. To this +end, they can access a QDomDocument representing the project file +(which is stored as xml) via document(). + +Take attention to the issue that the project file usually is shared in a team of +developers (e.g. via version control application CVS). So some user preferences might be +very individual, and some may be valid for all of the team - project-wide so to speak. + +That's why the KDevelop architecture makes a difference here and supports two files +which will be stored in the project root directory. They are the project file (*.kdevelop) +and the session (*.kdevses) file. The later is for individual settings, not to be thought +to be shared. + +\subsection domProject Project file (*.kdevelop) + +For your convenience, you don't have to use the quite complex DOM API. Strings +can very easily be read from and written to this document using the +DomUtil class. Here, entries are identified by a 'path' in the +document. You can think of the DOM document as representing a file system +rooted in the dom document node. + +For example, the autoproject part uses the statement + +
+    QString cflags = DomUtil::readEntry( *part->document(),
+                                         "/kdevautoproject/cflags" );
+
 + +to read the CFLAGS variable set by the user, and uses the statement similar to + +
+    DomUtil::writeEntry( *part->document(),
+                         "kdevautoproject/cflags",
+                         "--no-exceptions" );
+
 + +to write it back. + + - Note: In order to avoid conflicts between different plugins, you + should use your part name as top-level 'directory' in the configuration + tree. + . + +\subsection sessionAccess Project session file (*.kdevses) + +The base class of all KDevelop plugins is KDevPlugin. It provides two virtual methods +restorePartialProjectSession(..) and savePartialProjectSession(..) +that you should reimplement in your special plugin to attach to session loading and saving. + +When KDevelop loads or closes a project, the program's project session manager +(class ProjectSession) calls them for each plugin. That manager gives a QDOM node to the +plugin where it can read out or build up its partial DOM subtree with the session settings. +That subtree will be stored in the .kdevses file by that session manager. + +For example each programmer has set breakpoints in different files than the other ones of +the team. So the debugger plugin saves them to project session file: + +
+void DebuggerPart::savePartialProjectSession(QDomElement* el)
+{
+    gdbBreakpointWidget->savePartialProjectSession(el);
+}
+void GDBBreakpointWidget::savePartialProjectSession(QDomElement* el)
+{
+    QDomDocument domDoc = el->ownerDocument();
+    if (domDoc.isNull()) return;
+    QDomElement breakpointListEl = domDoc.createElement("breakpointList");
+    for ( int row = 0; row < m_table->numRows(); row++ )
+    {
+        BreakpointTableRow* btr = (BreakpointTableRow *) m_table->item(row, Control);
+        Breakpoint* bp = btr->breakpoint();
+        QDomElement breakpointEl = domDoc.createElement("breakpoint"+QString::number(row));
+        breakpointEl.setAttribute("type", bp->type());
+        breakpointEl.setAttribute("location", bp->location(false));
+        breakpointEl.setAttribute("enabled", bp->isEnabled());
+        breakpointEl.setAttribute("condition", bp->conditional());
+        breakpointListEl.appendChild(breakpointEl);
+    }
+    if (!breakpointListEl.isNull()) el->appendChild(breakpointListEl);
+}
+
+}
+
 + +Note that the .kdevses is related to a project. User settings equal for all projects don't +belong to here. You save them to ~/.kde/share/config/kdeveloprc via class KConfig of the +kdecore library. + +Document your part in the way described at \ref howToDocument (doc/api/HowToDocument.dox file). + +*/ + diff --git a/doc/api/HowToAddProgrammingLanguages.dox b/doc/api/HowToAddProgrammingLanguages.dox new file mode 100644 index 00000000..5cfa3643 --- /dev/null +++ b/doc/api/HowToAddProgrammingLanguages.dox @@ -0,0 +1,252 @@ +/** \file HowToAddProgrammingLanguages.dox + * \brief How to add support for a programming language + */ + +/** \page howToAddProgrammingLanguages How to add support for a programming language + +\section LSupport List of things to have "complete" support of a given language in KDevelop + + - Implement interface KDevLanguageSupport + - \ref sectionClassWizard + - \ref sectionAttributeMethodWizard + - \ref sectionQtUiSubclassing - (if the language has Qt bindings) + - \ref sectionLanguageParser + - \ref sectionClassStore + - \ref sectionMemoryClassStore + - \ref sectionPersistantClassStore + . + - \ref sectionCodeCompletion + - \ref sectionProblemReporter - (parses source on the fly and reports syntax errors) + - \ref sectionTemplates + - \ref sectionApplicationTemplates + - \ref sectionApplicationImportTemplates + - \ref sectionSourceFileTemplates + - \ref sectionAbbreviationTemplates - (ife expands to an if else statement, etc) + . + - \ref sectionSourceCodeFormater (prettyprint functionality) + - \ref sectionDocumentationTopics + - \ref sectionDebugger + - (gdb/jdb/??? integration) + - \ref sectionCompilerPlugins + . + +List of optional things to support a given language in KDevelop: + - \ref sectionEditor - Syntax highlighter - (add to QEditor if not available elsewhere) + - \ref sectionBuildTool (make/ant/etc) + . + +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. + + + + +\section sectionLanguageSupport Language Support + +Any language support should be written as a kdevelop part and implement +KDevLanguageSupport interface (lib/interfaces/kdevlanguagesupport.h). + +Implementing methods: + - virtual Features features(); + - virtual KMimeType::List mimeTypes(); + . + +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. + + +You should look at languages/ruby for a simple language support +implementation. For a compilable language support, consult languages/ada or languages/pascal (they are not so complex as languages/cpp). + +Pascal would be a good starting place, as it is the smaller of the two by far. + +Language support can offer additional features: + +\subsection sectionClassWizard Class wizard + - new class wizard: (See ada, php, cpp or java) + - virtual void addClass(); + . + +\subsection sectionAttributeMethodWizard Attribute/Method wizard + - add method dialog: (See cpp or java) + - virtual void addMethod(const QString &className); + . + - add attribute dialog: (See cpp or java) + - virtual void addAttribute(const QString &className); + . + . + +\subsection sectionQtUiSubclassing Qt UI subclassing + +If there is a Qt bindings for your language and there is a possibility +to use QtDesigner ui files, you could implement ui subclassing feature: + - virtual QStringList subclassWidget(const QString& formName); + - virtual QStringList updateWidget(const QString& formName, const QString& + fileName); + . + +See cpp and java for examples. + +\subsection sectionLanguageParser Language parser + +In general, class stores can be filled with information without specialized +and complex language parsers (take a look at languages/python that have a very simple python parser) but your language support will surely benefit +from having such. There is a hand-written c/c++ parser (lib/cppparser) in KDevelop that might be used for ObjC or related C-based languages. + +Other (not so complex as c++) languages can be parsed by ANTLR based parsers (library is in lib/antlr). +Consult www.antlr.org for a ANTLR documentation and look at languages/java, languages/ada and languages/pascal for an example of using such parsers. +The latest version of ANTLR (2.7.2) has support for Java, C, Pascal, Ada, C++, CIM, HTML, IDL, Verilog, VRML, OCL, ASN.1, and SQL. You can write an ANTLR parser for your own language, of course. + +\subsection sectionClassStore Class store + +If you write (or have) a language parser, your language support can have +"class store" (a database containing the information about scopes, classes +and methods - their names, names of source files, location in source files, +etc.). Class store libraries can be found at lib/catalog (Catalog) and lib/interfaces (CodeModel). + +KDevelop provides class browsers that extract information from a class store and display it in a tree view and toolbar selectors of scopes, classes and methods. + +\subsubsection sectionMemoryClassStore Memory class store +CodeModel is the memory class store. It is very efficient and thus it is recommended for using as a project class store. CodeModel libraries are located in lib/interfaces/codemodel.h. The class browser for a CodeModel based stores is parts/classview. + +\subsubsection sectionPersistantClassStore Persistant class store +Catalog is the persistant class store for KDevelop. Persistant class store can be used as an information storage for code completion but it also can be used as a class store for the project. Take a look at +languages/cpp for an example of using catalog. Catalog is stored on disk in the database file (Berkeley db) If you use catalog with the project, your class browser will be parts/classbrowser. + +\subsection sectionCodeCompletion Code completion +Class store enables you to write a code completion for the language. At the +moment (2003-06-25), code completion is available only to cpp so take a +look at it for an example. + +\subsection sectionProblemReporter Problem reporter + +If you have a language parser, you can implement problem reporter +functionality for your language. The problem reporter catches errors +reported by a parser and displays it in a problem reporter view. +languages/java, languages/ada, languages/pascal and languages/cpp have problem reporters. + +\subsection sectionTemplates Templates + +\subsubsection sectionApplicationTemplates Application templates + +Application wizard templates should be also written. Appwizard templates are simple to create - consult \ref howToAddApplicationTemplates (HowToAddApplicationTemplates.dox file) +and look at languages/ruby/app_templates/rubyhello, languages/pascal/app_templates/pascalhello, or languages/ada/app_templates/adahello. + +\subsubsection sectionApplicationImportTemplates Application import templates + +KDevelop has the ability to create a new project from existing projects or source code. +It scans for project files ('*.kdevelop, *.kdevprj, *.studio, *.pro) and if + - it finds a project it extracts the necessary information + - it does not find project files it scans for source files (*.cpp, *.java, *.pl, *.py, ...) + . +and creates a new KDevelop project in the direcotry the user has chosen. + +\subsubsection sectionSourceFileTemplates Source file templates + +Another thing to do is to create file create templates. They are prototypes for a source files of your language. These prototypes are placed in +parts/filecreate/file-templates dir or languages/YOURLANGUAGE/file_templates and have names equal to the extensions of language source files. +The description of the prototypes is placed in parts/filecreate/template-info.xml. + +Consult FileCreatePart (parts/filecreate/README.dox file) and \ref howToAddFileTemplates for further information. + +\subsubsection sectionAbbreviationTemplates Code abbreviation templates + +KDevelop has a support for code abbreviations so you can add some predefined abbreviations to your language support. Take languages/cpp/cpptemplates as an example. + + +\subsection sectionSourceCodeFormater Source code formater + +Implement a KDevSourceFormater class interface. +To obtain source formater functionality (that is already available to +c-based languages) you can extend astyle library (lib/astyle) that is used by KDevelop to format sources. +Take a look at AStylePart for an example how to do it. + +\subsection sectionDocumentationTopics Documentation topics + +Add them to languages/YOURLANGUAGE/doc. For an example see languages/python/doc/python.toc and languages/python/doc/python.index +In the end you need to edit the languages/YOURLANGUAGE/doc/Makefile.am file to include the .toc and/or .index file. + +\subsection sectionDebugger Debugger + +The last thing to have a complete language support in KDevelop is to +write a Debugger . KDevelop already provides GDB support +(languages/cpp/debugger) and JDB (java debugger) support (languages/java/debugger). Take a look at them to get inspiration. + +\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. + + +\section MiscInf Other Info + +In the end you should add the language you implemented to the doc/api/LangSupportStatus.dox file and +document your language support part in the way described at \ref howToDocument (doc/api/HowToDocument.dox file). +See also \ref howToAddPlugins (doc/api/HowToAddPlugins.dox file) for an information on how to create a generic KDevelop plugin and how to manage project and global configuration information. + + + + + +\section sectionEditor Language Editor + +To edit source files KDevelop uses any editor that supports the KTextEditor +interface. The current supported editors and their features are listed +in the \ref EditorsSupportStatus (doc/api/EditorsSupportStatus.dox file) page. + +In case none of the editors does support advanced editing of sources +written in your language (like code folding, syntax highlighting, line +indentation) you can improve QEditor included in KDevelop (editors/qeditor). +By creating QEditorIndenter and QSourceColorizer descendants you can provide the support for an automatic indentation and syntax highlighting that will be available for sure in KDevelop. + + + + + + +\section sectionBuildTool Build Tool + +The language support is important, but it is unusable without a build tool +that can manage projects written on this language. KDevelop +currently provides several build tools. They are: + + - ANT build tool + - see AntProjectPart at buildtools/ant + . + - Autotools build tool + - see AutoProjectPart at buildtools/autotools + . + - Custom build tool + - see CustomProjectPart at buildtools/custommakefiles + - (works with custom makefiles, also has ant support) + . + - Generic build tool + - 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. + . + - QMake build tool + - see TrollProjectPart at buildtools/qmake + . + . + +Also available: + - Script build tool + - buildtools/script + - (the generic build tool for all scripting languages). + . + - buildtools/pascal and + - buildtools/ada + - buildtools/haskell + . + +(They are deprecated build tools that will be replaced with the generic build tool). + +Choose your build tool and if the existing build tools doesn't fit +in, extend generic build tool via build system plugin. \ref howToAddGenericBuildTools page (doc/api/HowToAddGenericBuildTools.dox file) helps you to do it. + + +*/ diff --git a/doc/api/HowToDocument.dox b/doc/api/HowToDocument.dox new file mode 100644 index 00000000..d606a8bf --- /dev/null +++ b/doc/api/HowToDocument.dox @@ -0,0 +1,39 @@ +/** \file HowToDocument.dox + * \brief How to document KDevelop parts + */ +/** \page howToDocument How to document KDevelop parts + +You should add a README and a README.dox file to your part (KDevPlugin). + +On the README file put this text: +\verbatim +Please read the on-line, automaticaly updated KDevelop API documentation at: +http://www.kdevelop.org +or read the README.dox file. +\endverbatim + +On the README.dox file put the mandatory information: +\verbatim +/** \class yourPartClassName +Put a brief description here, the brief description ends at the first dot. +Put a more detailed description of your part in these lines. It can span +over several lines. You can even use some html commands in these lines like: +This is code, html links link text, +and images. + +... + +/* +\endverbatim + +IMPORTANT: You should replace yourPartClassName with the name of the class that +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 + +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/api/LangSupportStatus.dox b/doc/api/LangSupportStatus.dox new file mode 100644 index 00000000..fa08cc67 --- /dev/null +++ b/doc/api/LangSupportStatus.dox @@ -0,0 +1,330 @@ +/** \file LangSupportStatus.dox + * \brief Programming Languages Support Status + */ + +/** \page LangSupportStatus Programming Languages Support Status + +\ref howToAddProgrammingLanguages (doc/api/HowToAddProgrammingLanguages.dox file) for step by step info on how to implement these features. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Feature/LanguageAdaBashC/C++FortranHaskellJavaPascalPerlPHPPythonRubySQL
\ref sectionClassWizardYN/AYN/AN/AYNNYNNN/A
\ref sectionAttributeMethodWizardNN/AYN/AN/AYNNNNNN/A
\ref sectionQtUiSubclassingN/AN/AYN/AN/AYN/AN/AN/ANN/AN/A
\ref sectionLanguageParserANTLRInternalcppparserInternalNANTLRANTLRInternalInternalInternalNN
\ref sectionMemoryClassStoreCodeModelCodeModelCodeModelCodeModelNCodeModelCodeModelCodeModelCodeModelCodeModelNY
\ref sectionPersistantClassStoreNNCatalogNNNNNNNNN/A
\ref sectionCodeCompletionNYYNNNNNYNNN
\ref sectionProblemReporterYNYNNYYNYNNN
\ref sectionApplicationTemplatesYYYYYYYYYYYY
\ref sectionApplicationImportTemplatesYNYYNYYYYYYN
\ref sectionSourceFileTemplatesYNYYYYYYYYYN
\ref sectionAbbreviationTemplatesNNYNN/ANYNYNNN
\ref sectionSourceCodeFormaterNNYNNYNNNNNN
\ref sectionDocumentationTopicsYYYNYYNYYYYN
\ref sectionDebuggerNNYNN/AYNNNNNN
\ref sectionCompilerPluginsNN/AgccPGHPF, PGF77GlasgowNDelphi, Free PascalNNNNN
+
+Legend: +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Feature has not been implemented
Feature is in alpha state, the development has only been started or the feature is turned off at the moment
Feature is in beta state or it is unfinished
Feature is considered to be complete or complete enough for the release
N/AFeature is not applicable for given language
SourceinfoDeprecated class store that should be replaced by a CodeModel +
Features implemented with Sourceinfo should not be marked as complete
CodeModelNew memory class store
CatalogNew persistant class store using Berkeley DB storage backend
ANTLRLanguage parser is generated by ANTLR parser generator, http://www.antlr.org
cppparserNew c/c++ parser written by Roberto Raggi for KDevelop
InternalLanguage parser is included in language support part
+ +*/ + diff --git a/doc/api/Mainpage.dox b/doc/api/Mainpage.dox new file mode 100644 index 00000000..9d4b6d4c --- /dev/null +++ b/doc/api/Mainpage.dox @@ -0,0 +1,91 @@ +/** \file Mainpage.dox + \brief The main page of the doxygen generated %API Documentation +*/ + +/** +\mainpage The KDevelop %API %Documentation + +KDevelop is an easy to use IDE (Integrated Development Environment) for developing applications under X11. + +\section intro Introduction + +This document is targeted at all those that want to add or improve KDevelop's source code. +If you are instead looking for a user manual, just go to the help menu of your KDevelop and select KDevelop handbook. +This documentation contains the KDevelop online class reference for the current +development version of KDevelop. Additionally, you +can subscribe or read the mailing list for any additions and/or +modifications to the %API. + +An on-line, updated every 24H, html version of this documentation can be found at: http://www.kdevelop.org/HEAD/doc/api/html/index.html + +More information about the KDevelop architecture in form of tutorials, HOWTOs, +and FAQs can be found at +the KDevelop website. + + +\section status Current Status + +Here you can see the current \ref requirements and the \ref features. +There is also a \ref LangSupportStatus (doc/api/LangSupportStatus.dox file) page and a \ref EditorsSupportStatus (doc/api/EditorsSupportStatus.dox file) page. + + +\section expand How to expand KDevelop + +First of all read the \ref architecture (doc/api/Architecture.dox file) then you can find more information on how to expand KDevelop: + - \ref howToAddPlugins (doc/api/HowToAddPlugins.dox file) + - \ref howToAddProgrammingLanguages (doc/api/HowToAddProgrammingLanguages.dox file) + - \ref howToAddApplicationTemplates (doc/api/HowToAddApplicationTemplates.dox file) + - \ref howToAddFileTemplates (doc/api/HowToAddFileTemplates.dox file) + - \ref howToAddGenericBuildTools (doc/api/HowToAddGenericBuildTools.dox file) + +Additionally you may also want to find out \ref howToDocument (doc/api/HowToDocument.dox file). + +\section PlannedTasks Planned tasks + +Here is a priority ordered list: + -# \ref HighPriTasks (doc/api/HighPriTasks.dox file) + -# fix the dispersed \ref fixme + -# reported bugs in bugzilla database + -# fix the bugs in the \ref bug + -# fix the dispersed \ref todo all over the code. + . +There are some \ref unmaintained parts in KDevelop. You migth want to "adopt" one. :)\n +There is also \ref FutureTasks (doc/api/FutureTasks.dox file). Put all ideas for the future KDevelop releases there. It is also a good place to comment on those ideas. + +\section misc Misc + + - \ref authors + - \ref maintainers + - \ref FAQ + - \ref deprecated + +\section misc_libs Miscellaneous libraries included in KDevelop + - \ref PropEditor + +\section howTobuildAPIlocalcopy How to build a local copy of this documentation + +This documentation is very large and changes with every cvs commit, therefore is not available for download. +To build your local copy of this documentation you have two choices, depending on your system configuration. + - If you have doxygen >= 1.3.4 , PHP >= 4.10 and a local running webserver then + - make apidox + - make install-apidox (as root) + . + - If you have an older system then + - setenv KDEDIR=/location_of_your_kde_instalation + - setenv QTDIR=/location_of_your_qt_instalation + - doxygen Doxyfile + - make install-apidox (as root) + . + . + +The advantage of the first method is that you'll get a search engine in your documentation if you read your +documentation using your local webserver. + +\section License + +Permission is granted to copy, distribute and/or modify this document under +the terms of the GNU Free %Documentation License, Version 1.2 or any later +version published by the Free Software Foundation; For details see +http://www.gnu.org/copyleft/fdl.html . + +*/ diff --git a/doc/api/PropEditor.dox b/doc/api/PropEditor.dox new file mode 100644 index 00000000..b4f4eccc --- /dev/null +++ b/doc/api/PropEditor.dox @@ -0,0 +1,108 @@ +/** \file PropEditor.dox + \brief The KDevelop Property Editor library description page +*/ + +/** \page PropEditor KDevelop Property Editor library description + +\section whatis What is Property Editor? + +%Property editor is a collection of facilities to store and edit the +properties of an object. For example, look at %Qt Designer. Each widget +has a list of properties that can be edited in a nice table form. +Same ideology is used to edit properties in Kugar Report Designer +(from KOffice distribution). In KDevelop project manager can also display +the properties of currently selected build item in property editor. + +\section over Library Overview + +This PropertyEditor library is a redesign of Kugar property editing library +with the goal to be more generic and extensible. + +Library provides a @ref PropertyLib::Property class which stores property name, value and some +more important information like description or the list of possible values. +Using @ref PropertyLib::Property class adds more overhead over Q_PROPERTY but provides more +flexibility. You can subclass @ref PropertyLib::Property and create your custom properties. +Custom properties can have either predefined type (see @ref PropertyLib::PropertyType) or +custom type. Custom type should be used if a custom property editor widget is +necessary. + +Properties are organized into lists. @ref PropertyLib::PropertyList is designed +to store such lists in most efficient manner. It also allows to group +properties (for example think about "geometrical" properties like "x", "y", etc.). + +Property lists can be displayed in @ref PropertyLib::PropertyEditor widget which will +display them in a table form. Note that @ref PropertyLib::PropertyEditor takes not +a @ref PropertyLib::PropertyList object, but @ref PropertyLib::PropertyAccessor instead. + +@ref PropertyLib::PropertyAccessor is designed to provide a method to access an intersection +of property lists. For example, let's consider object A with property list a_list +abd object B with list b_list. Now let's imagine we want to display common properties +from a_list and b_list in one @ref PropertyLib::PropertyEditor widget. Obviously, we need to +"intersect" a_list with b_list and display the result of intersection. +This is why @ref PropertyLib::PropertyAccessor is used for editing. If we change +the value of a property in the editor, @ref PropertyLib::PropertyAccessor will update +both properties from underlying a_list and b_list. + +@ref PropertyLib::PropertyEditor at the same time shows only one editor for selected +property in the list. Each @ref PropertyLib::PropertyType has corresponding @ref PropertyLib::PropertyWidget +which displays property editor or draws a property in the list if it is not edited. +More exactly, if @ref PropertyLib::PropertyEditor needs to display editor widget, it displays +@ref PropertyLib::PropertyWidget, else it calls @ref PropertyLib::PropertyWidget::drawViewer function. +Custom property widgets should be subclasses of @ref PropertyLib::PropertyWidget. + +To create property widgets at runtime, a factory is used. Factory class is +called @ref PropertyLib::PropertyMachineFactory. Static function @ref PropertyLib::PropertyMachineFactory::getInstance +can be used to obtain the reference to the factory instance. Factory creates and returns +so-called @ref Machine for each registered property type (either predefined or user defined). + +@ref Machine contains @ref PropertyLib::PropertyWidget and a list of "detailed" machines. +Usually only property widget is necessary for a property but there are +complex properties like "Font" for example. We would like to see separate editors +for font family, size, etc. and a button to choose all of these in the dialog. +For that "Font" property, a PropertyWidget with a "choose font" button +and also number of detailed widgets like "font family" combo, etc. can be created. + +\section Examples +A simple example on how to create a property editor and use it with one property list: +\code + PropertyEditor *m_editor = new PropertyEditor(this); + + PropertyList *list = new PropertyList; + list->addProperty("My Group", new Property(Integer, "First Property", + "This is my first property", -5)); + list->addProperty("My Group", new Property(String, "Second Property", + "This is my second property", "Hello")); + list->addProperty(new Property(Color, "Third Property", + "This is my third property", QColor("green"))); + + m_editor->populateProperties(*list); +\endcode + +More advanced example with property accessors and list intersection: +\code + PropertyEditor *m_editor = new PropertyEditor(this); + + PropertyList *list = new PropertyList; + list->addProperty("My Group", new Property(Integer, "First Property", + "This is my first property", -5)); + list->addProperty("My Group", new Property(String, "Second Property", + "This is my second property", "Hello")); + list->addProperty(new Property(Color, "Third Property", + "This is my third property", QColor("green"))); + + PropertyList *list2 = new PropertyList; + list2->addProperty("My Group", new Property(Integer, "First Property", + "This is my first property", -7)); + list2->addProperty("My Group", new Property(String, "Second Property", + "This is my second property", "Hello")); + list2->addProperty(new Property(String, "Third Property", + "This is my third property", "green")); + + PropertyAccessor *ac = list->intersect(*list2); + + m_editor->populateProperties(ac); +\endcode +In this example only properties named "First Property" and "Second Property" will be shown in editor. +"Third Property" has different types in list and list2 and will not be included in intersection. + +*/ diff --git a/doc/api/propeditor1.png b/doc/api/propeditor1.png new file mode 100644 index 00000000..854b91f6 Binary files /dev/null and b/doc/api/propeditor1.png differ diff --git a/doc/api/propeditor2.png b/doc/api/propeditor2.png new file mode 100644 index 00000000..66f8a75b Binary files /dev/null and b/doc/api/propeditor2.png differ -- cgit v1.2.3