KDE TechBase - User contributions [en]

Development/Tutorials/Localization/i18n Semantics

2012-03-22T12:23:18Z

Zander:

== Abstract ==

Typical way of formatting user visible strings in application interfaces, for a long time has been that of plain text or at most visual markup like HTML tags. In most textual content environments, shift to ''semantic'' markup has been recognized as superior to visual (for example, the Docbook XML for documentation). Why not go down the same road for UI strings?

{{Note|A [http://people.ubuntu.com/~apachelogger/misc/i18nccheatsheet.png handy cheat sheet] for the KUIT semantic markup language has been prepared by apachelogger.}}

== Semantic Markup by Examples ==

In the semantic model, user interface strings are marked for their ''context'', and text elements within for their ''meaning'' rather than visual appearance. Consider few i18n examples of usual, non-semantic format:
<syntaxhighlight lang="cpp-qt">
i18n("Move");

i18n("Descending");

i18n("<qt>%1 does not exist</qt>", fname);

i18n("<h1>History Sidebar</h1> You can configure the history sidebar here.");
</syntaxhighlight>

Using KDE UI Text (KUIT for short) semantic markup, these strings would be formated like this:
<syntaxhighlight lang="cpp-qt">
i18nc("@action:button", "Move");

i18nc("@item:inmenu", "Descending");

i18nc("@info", "<filename>%1</filename> does not exist", fname);

i18nc("@info:whatsthis",
"<title>History Sidebar</title>"
"<para>You can configure the history sidebar here.</para>");
</syntaxhighlight>

Two distinct differences between ordinary and KUIT markup can be observed.

The first is the use of context i18n calls, the <tt>i18nc()</tt>, to convey the usage context of the string by means of the ''context marker''. The first message above, "Move", has been assigned the <tt>@action:button</tt> marker, where <tt>@action</tt> is the ''semantic role'' which describes the text as an action to be taken (e.g. operation on data or opening of a new dialog), and <tt>:button</tt> is the ''interface subcue'' saying that this text is displayed on a pushbutton widget. The second message, "Descending", has been marked as semantically a list item (<tt>@item</tt>), displayed in a menu (<tt>:inmenu</tt>). The interface subcue can be left out if none is appropriate, as has been done in the third message.

The other difference is the use of the semantic tags, which convey the meaning of a word or phrase within the text. The <tt><filename>%1</filename></tt> part of the third message tells that the substituted text is the name of a file. The <tt><title></tt> and <tt><para></tt> tags in the last message clearly lay out structure of a longer informational text.

{{note|The context marker can be added when within some of the standard XML sources too. In Qt Designer forms (<tt>.ui</tt> files), each text label to a widget has <tt>comment</tt> attribute (presented as "disambiguation" property within Designer, or "comment" prior to Qt 4.5), which can be used in the same manner as context argument of <tt>i18nc()</tt> call. Similarly, in the KXmlGui (<tt>.rc</tt>) and KConfigXT (<tt>.kcfg</tt>) files, tags <tt><text></tt>, <tt>label</tt>, and <tt>whatsthis</tt> can have a <tt>context</tt> attribute. For example:
<syntaxhighlight lang="xml">
<label context="@label">Hide trivial details</label>
<whatsthis context="@info:whatsthis">Option to hide drivel</whatsthis>
<text context="@item:inmenu">&New...</text>
</syntaxhighlight>}}

Even when a context marker is present, sometimes the programmer may want to provide an additional "free-form" description to translators, in order to shed more light on particularly ambiguous strings. The free-form description is just separated by a whitespace from the context marker proper, like this:
<syntaxhighlight lang="cpp-qt">
i18nc("@item:inmenu Sorting order", "Descending");
</syntaxhighlight>

One particularly useful and yet general piece of free-form description, is the title under which the message is grouped -- the menu title for actions in menu, the group title of set of radio-buttons, the listbox label for items in list, etc. For example:
<syntaxhighlight lang="cpp-qt">
iconSizeBox = new QGroupBox(i18nc("@title:group", "Icon Size"), this);
//...
iconSize1 = new QRadioButton(i18nc("@option:radio Icon Size", "Small"), this);
iconSize2 = new QRadioButton(i18nc("@option:radio Icon Size", "Medium"), this);
iconSize3 = new QRadioButton(i18nc("@option:radio Icon Size", "Large"), this);
//...
</syntaxhighlight>

== Advantages of Semantic Markup ==

KUIT markup has advantages both to users and to translators of applications that make use of it.

For the users, the use of semantic tags means consistent formatting of same kinds of text. A notorious example of inconsistent visual formatting are filenames and paths, which are sometimes put in as is, sometimes in quotes (and ordinary quotes at that, rather than proper English fancy quotes), and sometimes in bold tags. Furthermore, the text within the tag may be modified when semantically marked; for example, the standard "/" path delimiters in a <tt><filename></tt> text will be substituted for platform specific ones.

Translators will benefit from both context markers and tags. For the <tt>@action</tt> role of the "Move" string in the example above, the translator may use command form of the verb, while gerund form (like "Moving") may be more appropriate for the <tt>@title</tt> role, which would be used if the string was title of the menu, window, etc. The interface subcue, like <tt>:button</tt> above, if present, additionally enables the translator to mentally picture the actual runtime GUI. Tags within the text will also benefit translators, as they may clarify the structure of the sentence, especially in presence of placeholder substitutions.

Context markers also serve a technical purpose: they decide whether what form of visual formatting is used. For example, any <tt>@title</tt> role will use plain text, whereas <tt>@info</tt> will frequently produce rich text, depending on the subcue.

None the least, semantic markup removes the burden from programmers of thinking about the visual formatting to apply, like "''Should I put the path in quotes or ?''", or "''Should the title be <h2> or <h3>?''", and so on.

== Context Markers ==

Context marker consist of the semantic role and the interface subcue, in the form of <tt>@role:subcue</tt>. Each message should be given a role, but the subcue may be left out. The subcue should be given only when the string clearly maps to the user interface element that it describes.

Every role/subcue combination determines the default visual formatting of resulting string, whether it comes out as plain or rich text. See the section on [[#Limitations to Semantic Markup|limitations]] for a way to override the default formatting when necessary.

{{warning|Roles and subcues in the context marker cannot be specified at will, but must be drawn from the sets defined below. This is important for several reasons, one being that translators have deliberated about and agreed upon the meanings of presented sets, rather than having to second-guess arbitrary combinations.}}

KUIT defines the following roles and subcues (with notes on default visual formatting):

; <tt>@action</tt>
: Text to all clickable widgets that cause some action to be performed, like an operation on the data, view restructuring, or opening a dialog. The button texts and menu entries (except submenu titles) all fall into this category.
:
:: <tt>:button</tt> - pushbuttons in windows and dialogs
:: <tt>:inmenu</tt> - menu entries that perform an action
:: <tt>:intoolbar</tt> - toolbar buttons
:
: All <tt>@action</tt> markers are formatted as '''plain text''' by default.

; <tt>@title</tt>
: Text that is semantically a title in the interface. These would include window titles, menu titles, tab names, option group names in configuration dialogs, and column and row names in list views.
:
:: <tt>:window</tt> - window title (also dock name)
:: <tt>:menu</tt> - menu name
:: <tt>:tab</tt> - tab name
:: <tt>:group</tt> - option group
:: <tt>:column</tt> - column name
:: <tt>:row</tt> - row name
:
: All <tt>@title</tt> markers are formatted as '''plain text''' by default.

; <tt>@option</tt>
: Text to options which user can turn on and off, or choose between. These are the labels to checkboxes (either in dialogs or in menus) and radio buttons.
:
:: <tt>:check</tt> - checkbox label
:: <tt>:radio</tt> - radio-button label
:
: All <tt>@option</tt> markers are formatted as '''plain text''' by default.

; <tt>@label</tt>
: Text labels to various widgets in the interface, which are none of <tt>@action</tt>, <tt>@title</tt>, <tt>@option</tt>. These include labels to sliders, spinboxes, combo, list and text boxes, font and color choosers.
:
:: <tt>:slider</tt> - slider labels (but end-ranges are @item:inrange!)
:: <tt>:spinbox</tt> - spinbox labels
:: <tt>:listbox</tt> - list and combo boxes
:: <tt>:textbox</tt> - text and edit boxes
:: <tt>:chooser</tt> - chooser widgets (fonts, colors, etc.)
:
: All <tt>@label</tt> markers are formatted as '''plain text''' by default.

; <tt>@item</tt>
: Strings that can be considered one from a range of possibilities or properties. Entries in listings, dropdown and combo boxes are obvious, but also some menu items (e.g. encoding selection, sort orderings), end-labels to ranges (e.g. high/low, more/less), inserts into longer texts, and properites (e.g. file types, permissions) frequently displayed in tabular form (e.g. column views, property dialogs).
:
:: <tt>:inmenu</tt> - items presented as menu entries
:: <tt>:inlistbox</tt> - items in list and combo boxes
:: <tt>:intable</tt> - items presented in table-like forms
:: <tt>:inrange</tt> - range labels to sliders, etc.
:: <tt>:intext</tt> - words and phrases inserted into other messages
:
: All <tt>@item</tt> markers are formatted as '''plain text''' by default.

; <tt>@info</tt>
: General texts for user's information, that do not fall under any of the previous roles. These are for example tooltip and "What's This?" texts, text in message boxes, fields in status bar, and strings in progress dialogs.
:
:: <tt>:tooltip</tt> - hovering tooltips
:: <tt>:whatsthis</tt> - "What's This?" explanations of widgets
:: <tt>:status</tt> - texts in status displays (e.g. in status bar)
:: <tt>:progress</tt> - the current state of ongoing process
:: <tt>:tipoftheday</tt> - introductory tips on application startup
:: <tt>:credit</tt> - contributor names and their contributions
:: <tt>:shell</tt> - info output to the terminal, rather than to GUI
:
: Standalone <tt>@info</tt>, without a subcue, is formatted as '''rich text''' by default; the same holds for <tt>:tooltip</tt>, <tt>:whatsthis</tt>, and <tt>:tipoftheday</tt> subcues. With <tt>:status</tt>, <tt>:progress</tt>, and <tt>:credit</tt>, '''plain text''' is produced. <tt>:shell</tt> produces '''terminal text''' (like plain, but with possible shell escape sequences).

== Semantic Tags ==

KUIT semantic tags come in several logical groups:
* ''phrase tags'' - those that ascribe meaning to certain phrases and inserts
* ''sentence tags'' - which describe the purpose of a complete sentence in text
* ''structure tags'' - used to order longer text into paragraphs, titles, etc.

=== Phrase tags ===

Phrase tags will by default not admit any subtags; where some subtags can be used, it is so indicated. KUIT defines the folowing phrase tags:

; <tt><application></tt>
: Name of an application.
<syntaxhighlight lang="cpp-qt">
i18nc("@action:inmenu",
"Open with <application>%1</application>", appName);
</syntaxhighlight>

; <tt><bcode></tt>
: Line-breaking body of code, for short listings.
<syntaxhighlight lang="cpp-qt">
i18nc("@info:whatsthis",
"You can try the following snippet:<bcode>"
"\\begin{equation}"
" C_{x_i} = \\frac{C_z^2}{e \\pi \\lambda}"
"\\end{equation}"
"</bcode>");
</syntaxhighlight>

; <tt><command></tt>
: Name of shell command or system call. Its man section can be provided via <tt>section</tt> attribute.
<syntaxhighlight lang="cpp-qt">
i18nc("@info",
"This will call <command>%1</command> internally.", cmdName);

i18nc("@info",
"Consult man entry for <command section='1'>%1</command>", cmdName);
</syntaxhighlight>

; <tt><email></tt>
: Email address. Without attributes, the tag text is the address. Address can also be given with <tt>address</tt> attribute, in which case the tag text is the name or description attached to the address.
<syntaxhighlight lang="cpp-qt">
i18nc("@info",
"Send bug reports to <email>%1</email>.", emailNull);

i18nc("@info",
"Send praises to <email address='%1'>the author</email>.", emailMy);
</syntaxhighlight>
: The construct will be hyperlinked in rich text format.

; <tt><emphasis></tt>
: Emphasize a word or phrase in the text.
<syntaxhighlight lang="cpp-qt">
i18nc("@info:progress",
"Checking <emphasis>feedback</emphasis> circuits...");
</syntaxhighlight>
: For strong emphasis, attribute <tt>strong</tt> (since KDE 4.3) may be used, with value <tt>1</tt>, <tt>yes</tt>, or <tt>true</tt>.

; <tt><envar></tt>
: Environment variable. The $ sign will be prepended automatically in formatted text.
<syntaxhighlight lang="cpp-qt">
i18nc("@info",
"Assure that your <envar>PATH</envar> is properly set.");
</syntaxhighlight>

; <tt><filename></tt>
: File or folder name or path. The path separators will be transformed into what is native to the platform.
<syntaxhighlight lang="cpp-qt">
i18nc("@info", "Cannot read <filename>%1</filename>.", filename);

i18nc("@info",
"<filename><envar>HOME</envar>/.foorc</filename> does not exist.");
</syntaxhighlight>
: The <tt><envar></tt> can be used as subtag.

; <tt><icode></tt>
: Inline code, like shell command lines.
<syntaxhighlight lang="cpp-qt">
i18nc("@info:tooltip",
"Execute <icode>svn merge</icode> on selected revisions.");
</syntaxhighlight>
: The <tt><placeholder></tt> can be used as subtag.

; <tt><interface></tt>
: Path to GUI interface element. If there is more than one element in the path, use "|" or "->" to delimit elements, which will be converted into canonical delimiter.
<syntaxhighlight lang="cpp-qt">
i18nc("@info:whatsthis",
"If you make a mistake, click "
"<interface>Reset</interface> to start again.");
i18nc("@info:whatsthis",
"The line colors can be changed under "
"<interface>Settings->Visuals</interface>.");
</syntaxhighlight>

; <tt><link></tt>
: Link to a URL-addressable resource. Without attributes, the tag text is the URL; alternatively, the URL can be given by <tt>url</tt> attribute, and then the tag text serves as description.
<syntaxhighlight lang="cpp-qt">
i18nc("@info:tooltip",
"Go to <link>%1</link> website.", urlKDE);

i18nc("@info:tooltip",
"Go to <link url='%1'>the KDE website</link>.", urlKDE);
</syntaxhighlight>
: The variant with URL/description separation is preferred when applicable. The construct will be hyperlinked in rich text format.

; <tt><message></tt>
: An external message to be reported to the user.
<syntaxhighlight lang="cpp-qt">
i18nc("@info",
"The fortune cookie says: <message>%1</message>", trouble);
</syntaxhighlight>

; <tt><nl></tt>
: Line break, counterpart to HTML's <tt> </tt>. In plain text it will format as a newline character, and in rich text as <tt> </tt>.
<syntaxhighlight lang="cpp-qt">
i18nc("@info",
"Do you really want to delete:<nl/>"
"<filename>%1</filename>", fileName);
</syntaxhighlight>

; <tt><numid></tt>
: By default, numbers supplied as arguments to i18n calls are formatted into localized form. If the number is supposed to be a numeric identifier instead, like a port number, use this tag to signal numeric-id environment.
<syntaxhighlight lang="cpp-qt">
i18nc("@info:progress",
"Connecting to <numid>%1</numid>...", portNo);
</syntaxhighlight>

; <tt><placeholder></tt>
: A placeholder text, either something to be replaced by the user, or a generic item in a list.
<syntaxhighlight lang="cpp-qt">
i18nc("@info",
"Replace <placeholder>name</placeholder> with your name.");

i18nc("@item:inlistbox",
"<placeholder>All images</placeholder>");
</syntaxhighlight>

; <tt><resource></tt>
: General named resource. Names of documents, sessions, projects, toolbars, plugins, schemes and themes, accounts, etc.
<syntaxhighlight lang="cpp-qt">
i18nc("@info", "Apply color scheme <resource>%1</resource>?", colScheme);
</syntaxhighlight>

; <tt><shortcut></tt>
: Combination of keys to press. Separate the keys by "+" or "-", and the shortcut will be converted into canonical form.
<syntaxhighlight lang="cpp-qt">
i18nc("@info:whatsthis",
"Cycle through layouts using <shortcut>Alt+Space</shortcut>.");
</syntaxhighlight>

=== Sentence tags ===

Sentence tags mark complete sentences in text, and will admit any phrase tags as subtags. The following are defined:

; <tt><note></tt>
: The sentence is a side note of significance to the topic.
<syntaxhighlight lang="cpp-qt">
i18nc("@info",
"Probably the best known of all duck species is the Mallard. "
"It breeds throughout the temperate areas around the world. "
"<note>Most domestic ducks are derived from Mallard.</note>");
</syntaxhighlight>
: Do not explicitly add "Note:", it will be added automatically. If you really need other label than "Note", use attribute <tt>label</tt>, e.g. <tt>"<note label='Trivia'>...</note>"</tt>.

; <tt><warning></tt>
: The sentence is a warning.
<syntaxhighlight lang="cpp-qt">
i18nc("@info",
"Really delete this key?"
"<warning>This cannot be undone.</warning>");
</syntaxhighlight>
: Do not explicitly add "Warning:", it will be added automatically. If you really need other label than "Warning", use attribute <tt>label</tt>, e.g. <tt>"<warning label='Danger'>...</warning>"</tt>.

=== Structure tags ===

Structure tags are used to split longer texts into titles, paragraphs, and lists. By default they can contain any phrase or sentence tags, unless indicated otherwise.

; <tt><para></tt>
: Text paragraph.

; <tt><title></tt>
: The title of the text. Must be the first tag if present, but can be omitted.

; <tt><subtitle></tt>
: Subtitle in the text. Must be followed by at least one <tt><para></tt>.

; <tt><list></tt>
: List of items. Can contain only <tt><item></tt> as subtags. List is considered an element of the paragraph, so the <tt><list></tt> must be found inside <tt><para></tt>.

; <tt><item></tt>
: List item.

If any of the structure tags is present, then there must be no text outside of structure tags. The following is not valid KUIT markup:
<syntaxhighlight lang="cpp-qt">
// invalid markup
i18nc("@info",
"<title>History Sidebar</title>"
"You can configure the history sidebar here."); // <para> missing
</syntaxhighlight>

== Limitations to Semantic Markup ==

Semantic markup cannot be used in "dumb" strings, which do not pass through KDE's i18n subsystem. These would be, for example, strings in <tt>.desktop</tt> format files. But ''not'' the strings in UI files, as in Qt Designer they can be equipped with both context markers (via comment field to text properties) and semantic tags.

Qt's rich text HTML tags can be used concurrently with KUIT tags, but this is not advised unless necessary. They may be needed, for example, to create tables or insert images, as KUIT does not implement this functionality at the moment.

Sometimes, the visual formatting may not be quite appropriate for the output device; every role/subcue combination has a preset default formatting. For example, if the <tt>@info</tt> role is applied to a string which is used in a widget that does not handle rich text, it will come out with HTML tags displayed verbatim. To handle this, visual formatting can be explicitly signaled by <tt>/''format''</tt> modifier appended to context marker:

<syntaxhighlight lang="cpp-qt">
i18nc("@info/plain",
"<filename>%1</filename> does not exist", fname);
</syntaxhighlight>

Presently, the possible format modifiers are <tt>/plain</tt>, <tt>/rich</tt> and <tt>/term</tt> (for terminal format, possible use of escape sequences).

To specify context in kpartgui rc file use context attribute (<text context="@title:menu">File</text>). A context-aware version of I18N_NOOP is I18N_NOOP2.

== Should I Go For Semantic Markup? ==

Admittedly, KUIT markup is an additional thing to be learned and applied throughout the course of development. By now you may be wondering if it is worthwile to invest time into that, particularly in view of two cases:
* starting work on a new application, and
* porting messages in existing applications.

You are strongly advised to use KUIT for new code. Compared to the total time spent on code, writing UI messages is only a small fraction. Context markers will help translators a lot, and message tags will provide consistent visual text formatting to your application.

When modifying existing code, there are two issues. First, obviously it is a daunting task to go through hundreds (or worse) of messages and equip them with semantic markup. Second, by changing the messages, the translators too will have to review their existing translations; however, it is not expected that the porting will take so "epic" proportions that the translators cannot keep up. Sumarily, feel free to do as you see fit.

Additionally, for porting, keep in mind that it is not all-or-nothing proposal. Any amount of semantic messages are useful to translators, and users can only see the difference for the better. Thus, for example, deciding to make all ''new'' messages semantic and slowly over time fix old messages, is a perfectly fine strategy.

To make your job easier, there is an i18n-checker script that will report the problems in KUIT markup, as well as check some other i18n nuances. It is run daily on KDE code repository-wide as part Krazy-framework, but you can also run it locally on your code. It can be found in {{path|trunk/quality/krazy2/plugins/general/i18ncheckarg}}. Furthermore, as of this moment Krazy checks only C++ sources, while when you run the script locally, some of the XML sources containing translatable strings will be checked as well. <tt>i18ncheckarg</tt> requires Perl libxml bindings, which are probably already packaged for your distribution (Debian package is libxml-libxml-perl).

{{note|By default <tt>i18ncheckarg</tt> takes a single filename to check, but using <tt>--allsources</tt> option you can provide as many file or directory paths as you wish; typically you would give top directory path to your sources. Also, to report all missing context markers use <tt>--ctxmark</tt> option, or otherwise missing markers will be reported only if some threshold of marked-to-total number of messages in a file is reached.}}

Last but not the least, there is also a chic-effect to the KUIT. Its wide use, together with some under-the-hood elements on translators' disposal, will make KDE4's i18n layer without peer in free or proprietary software world. Insofar as you consider localization excellence an important part of the overall KDE excellence, this is something that may also tip your decision :) -- Your Friendly Translator.

User:Zander

2011-01-17T21:10:42Z

Zander:

'''Thomas Zander''' 
KOffice developer

Projects/MovetoGit

2011-01-17T21:09:32Z

Zander:

This is the page for co-ordinating KDE's move to [http://git-scm.com/ Git].

If you're interested in helping, you should join the [https://mail.kde.org/mailman/listinfo/kde-scm-interest kde-scm-interest@kde.org] mailinglist and [irc://chat.freenode.net/kde-git #kde-git] on freenode.

Meetings are wednesdays, 19:30 UTC, in #kde-git.

'''New! [http://community.kde.org/Sysadmin/DeveloperAccessForRuleWriting The best way you can help us migrate]'''

=The Plan=

KDE is, eventually, moving to Git. We will be using gitolite + Redmine + reviewboard on our own servers.

In the summer of 2009, [http://gitorious.org/amarok Amarok] moved to Gitorious to test the waters and find problems that would affect KDE.

After it has been decided in Jun 2010 to use our own servers, Amarok and Konversation moved to git.kde.org/projects.kde.org to test the waters and find problems that would affect KDE.

Once those problems have been solved, all of KDE will be able to switch.

A full schedule for the git infrastructure can be found [http://community.kde.org/Sysadmin/GitInfrastructureLaunch here].

==Why?==

Git offers many advantages over svn, including offline commits and much easier to keep a feature branch up-to-date. Many KDE developers are already using git-svn, but this tool has its limitations. We want to have the full power of Git available, and we have people willing to do the work necessary to migrate.

==How?==

When we move, KDE's svn repository will be migrated into several Git repos, all on git.kde.org. Main modules such as kdelibs and kdebase will each become one repository. Projects in extragear will each have their own repository. The projects.kde.org site will have a list (lists?) of all these repositories using the redmine project wiki. Scripts will be provided for downloading, say, all of extragear, so "moving" a project from kdereview to extragear would simply involve editing a file kept online that defined the location of projects.
Details on the reasoning behind this layout is available [[Projects/MoveToGit/Layout|here]].

A few things will stay in subversion - currently websites, translations and manuals. It's possible they could move to Git later, but they won't be part of the mass migration.

All KDE developers will in principle be able to use their existing "svn" accounts. Developers using HTTPS ideally would request their HTTPS SVN account to be converted to SSH as that makes it easiest for the KDE sysadmins, but alternatively they can also just provide a public key. At some point the KDE sysadmins are going to send everybody with a HTTPS SVN account an email with a link to a web app to collect their key (see http://www.omat.nl/2010/06/13/sysamin-update-your-email-address/).

From the times when gitorious.org was the preferred hosting solution, a procedure to move a project from svn to gitorious.org can be found in [[Projects/MoveToGit/StepsToMove|Steps to follow for Moving]].
Many points probably still apply, but have to be updated.

=Blockers=

Tasks that need to get done before we can migrate

==Setup git.kde.org==
{{Progress bar|100}}
'''Owner:''' Eike, Jeff, Sysadmin team

'''Status:''' ''Progressing''

: It [http://lists.kde.org/?l=kde-scm-interest&m=127612957219466&w=2 has been decided] to use gitolite + Redmine + reviewboard on our own servers rather than gitorious.org. Sysadmin team is preparing git.kde.org for this.

==Write / update importing rules for svn2git==
{{Progress bar|35}}
'''Owner:''' see below - volunteers needed!

'''Status:''' ''sho: ???, tumaix:started to read the docs, cryos: getting started [2010-01-06]''

:The importer is on gitorious.org as svn2git we have a set of rules to tell the importer what svn dirs turn into which git repos and those need constant updating whenever a new branch or tag or project is created. Currently the rules are mostly a rough draft, as seen by the large amount of rule-editing that had to be done for Konversation and Amarok. This has not been done for quite some time and so someone should rsync the svn repo run svn2git and fix the rules and importer whenever the import stops.

:This is a very big task, too big for one person; it's probably best to tackle it one module at a time

:To get started on a module, read [[Projects/MoveToGit/UsingSvn2Git|Using Svn2Git]]

:TZander has done the koffice ruleset as of 2009-01-06

:Jpwhiting has finished (more or less) the kdeaccessibility ruleset 2010-01-24.

:aavci has done the k3b ruleset as of 2010-01-27

progress details:
{| border="1"
!repo
!owner
!%
!comments
|-
|SC/kdeaccessibility
|jpwhiting
|99
|"more or less"?
|-
|SC/kdeadmin
|ruphy
|0
|
|-
|SC/kdeartwork
|ruphy
|0
|
|-
|SC/kdebase
|ruphy
|0
|
|-
|SC/kdebindings
|pumphaus/Arno Rehn
|100
|All written, converted and migrated
|-
|SC/kdeedu
|cryos?
|10
|[[http://community.kde.org/KDE_Edu#Git_Migration]]
|-
|SC/kdeedu/marble
|jmho
|100
|Contains: trunk with moves (playground->kdereview->kdeedu), regular kde branches/tags and the following other branches: marble-0.4, gsoc-2009 and geodata-nt. Checking done: gitk --all, verify-git-from-svn
|-
|SC/kdeexamples
|ruphy
|50
|
|-
|SC/kdegames
|jobermayr
|95
|coolo or mueller do not give me required information for old tags :-(
|-
|SC/kdegraphics
|ruphy
|0
|
|-
|SC/kdelibs
|ruphy
|0
|
|-
|SC/kdemultimedia
|eean
|0
|
|-
|SC/kdenetwork
| grundleborg
|0
|
|-
|SC/kdepim
|tnyblom
|100
|Donen.
|-
|SC/kdepim-runtime
|tnyblom
|100
|Done
|-
|SC/kdepimlibs
|tnyblom
|100
|Awaits 4.6.0 release
|-
|SC/kdeplasma-addons
|asouza
|95
|Verifying
|-
|SC/kdesdk
|
|0
|
|-
|SC/kdetoys
|
|0
|
|-
|SC/kdeutils
|jobermayr
|95
|coolo or mueller do not give me required information for old tags :-(
|-
|SC/kdewebdev
|
|0
|
|-
|extragear/sdk/kdevelop
| apaku
| 95
| trunk and branches complete, need to cleanup tags from cvs days.
|-
|extragear/sdk/kdevplatform
| apaku
| 100
| done, all tags seem fine all branches are there
|-
|extragear/sdk/kdevelop-plugins
| nsams
| 100
| done
|-
|extragear/sdk/quanta
| nsams
| 99
| done
|-
|extragear/utils/krecipes
| santa
| 85
| Branches are done, I'm working on tags.
|-
|extragear/*/*
|
|xx
|expand the *'s later (let's focus on the base modules first)
|-
|kde-common
|mattr
|75
|analyzing import history
|-
|kdesupport
|
|0
|
|-
|kdesupport/soprano
|cgiboudeaux
|100
|Ready to migrate
|-
|kdesupport/attica
|cgiboudeaux
|100
|Ready to migrate
|-
|koffice
|tzander
|100
|Migrated
|-
|promo
|ruphy
|0
|
|-
|quality
|
|0
|
|-
|tests
|
|0
|
|}

== Requirements of KDEPIM and KDAB ==

{{Progress bar|90}}
'''Owner:''' Stephen Kelly

'''Status:''' ''Proposed workflow identified. Partially depends on KDE policies regarding branches and merging. Gathering estimates for porting of tooling from svn to git. People unfamiliar with the tool are starting to learn to use it.''

'''Estimated completion date''': End of May.

'''Summary of issues'''

* Clean slate
** The existing backlog of commits which need to be merged or ported to trunk needs to be empty before the change to git so that nothing gets lost. This is a lot of work and will take time. ''Estimate'' 10 calendar weeks.
* Technical difficulties and limitations.
** Up to KDE 3.5 there was one kdepim module. For the KDE4 cycle, this was split into kdepimlibs and kdepim. For the above mentioned merging to be possible, it makes sense for both to be in the same git module. This poses extra difficulty to the svn2git script.

'''Email threads'''

* Mid-January thread on scm-interest: http://thread.gmane.org/gmane.comp.kde.devel.pim/26726
* Early March thread on kde-core-devel (Till email): http://thread.gmane.org/gmane.comp.kde.devel.core/63915/focus=63970
* Early March thread on kde-core-devel (Till follow-up):
http://thread.gmane.org/gmane.comp.kde.devel.core/63915/focus=64069

'''Resolved Issues'''

* Branch maintenance workflow '''Resolution: http://thread.gmane.org/gmane.comp.kde.scm-interest/1310'''
** KDAB maintains several branches of legacy versions of KDE for enterprise customer deployments. [http://websvn.kde.org:80/branches/kdepim/enterprise/ Enterprise 3.5] [http://websvn.kde.org:80/branches/kdepim/enterprise4/ Enterprise 4 (based on KDE 4.2)]. The current KDEPIM trunk known as Enterprise 5 and is Akonadi based.
** Periodically (weekly or so), tags are created from the enterprise branches with bugfixes. http://websvn.kde.org:80/tags/kdepim/ Customers can download the tagged versions with the latest updates. Fixes are merged from the Enterprise 3.5 branch, and into trunk (which sometimes involves a lot of work, as the fix must be ported to Akonadi). Additionally, fixes get merged in the other direction. From official KDE modules into the Enterprise branches.
** Some fixes from Enterprise 3.5 should not be merged into Enterprise 4 for reasons such as no longer being reproducible. Some fixes do not get merged for a long time because they require so much work that porting the fix or feature is deffered. There needs to be a list of commits which should never be merged (blocked commits), and commits which should be merged, but have not been merged yet. The tool [[Development/Tools/svnmerge.py|svnmerge]] is used to facilitate this. svnmerge uses svn properties to maintain lists of commits that are blocked and that have already been integrated. See for example the svn-blocked and svn-integrated properties here: http://websvn.kde.org:80/trunk/KDE/kdepim/. The lists of commits available to be merged into the various branches are here: http://www.kdab.com/~thomas/avail/
** There needs to be a way in git to keep track of what commits have been merged, what commits need to be merged, and what commits are blocked. There needs to be a way of merging only specific commits from a branch, but not all, and not blocked commits. Proposed solutions:
*** git cherry-pick allows 'merging' of individual commits, but does not record where the commits came from. Instead it creates a new commit without any reference to where it came from. This alone is unsuitable.
*** branch per fix. This would lead to an explosion of branches which is not a problem in git as all commits are branches. It may make gitk un-navigatable. There would need to be a naming convention such as komo-merge-<fixname> for branches which should be merged. The commands <tt>git checkout 4.5 && git merge $(git branch -a | grep -E ^origin/komo-merge)</tt> and <tt>git checkout enterprise4.5 && git merge $(git branch -a | grep -E ^origin/komo-merge)</tt> and <tt>git checkout master && git merge $(git branch -a | grep -E ^origin/komo-merge)</tt>. That could of course be optimized, but gets the point across. If the code has changed so much that the branch is unmergable, but the fix still needs to be in trunk, the system breaks down.
*** Custom git command with flat text files representing the same information as svnmerge, that is lists of blocked and integrated commits. This is most likely to be a workable solution, possibly together with conventional branch naming.
* Internal Tools and external customer tools and workflows
** KDAB is a consumer of KDE software, but also has downstream customers fetching software from where it is developed. That is, KDE SVN. For example packages are created from the tags in tags/kdepim. Some of these downstreams are less close to KDE and depend on current workflows. If KDE SVN is not the place to get those updates anymore, this needs to be communicated to those downstreams, and the tools updated. ''Estimate'' 1 week to port the tools.
*** Internally used tools have been updated and are now being used to access git repos such as dbus.
* Other commitments
** Project deadlines and other commitments prevent the possibility of blocking off time to work on git migration when so many other things need to be done which have milestones separate to KDE cycles. The required work to convert to git can't be prioritized as highly, and so will take more time.
*** Most of the technical work regarding migration of kdepim repos has been completed by community member Torgny Nyblom.
* Tool knowledge
** People who don't currently know how to use git need to get familiar with it so that transitioning will be nearly seamless, and not result in too much development slowdown.
*** Workshops and use of git-svn have been used to bring developers up to speed on how to use git at some level.

=Nice to have before the migration=

==Push log==
{{Progress bar|100}}
'''Owner:''' sysadmin

'''Status:''' finished

It's a push log, similar to a local repository's reflog.

---------------

For every push, log:
- who pushed (not the Unix username, which will be "git")
- which branch heads changed (what from, what to)
- which tags were created
- the state of all other branches and tags

Just use git commit-tree with the empty tree and save everything in the commit
message, one after the other.

-----------

Gitolite includes this functionality inbuilt to itself, although all repositories are logged in the same file - bcooksley

==Script for downloading virtual KDE hierarchies==
{{Progress bar|99}}
'''Owner''':

'''Status:'''

:we already have kdesvn-build, build-tool and mr: three good tools for managing repos.

Most people use kdesrc-build; it will neither eat babies nor kittens. it has options for updating everything or individual modules, can do fetch-only or build-only, etc..
Command-line options for updating the configuration would be a nice addition.

TODO: details on mr and build-tool

note: scripty also has its own list of repos. it's just in a rather weird bash file.

'''Discussion:'''

As far as I can see, kdesvn-build is able to do it, it should be just a matter of providing a configuration. As I'm not using build-tool, I can't say anything about it. --jmho

'''Links'''
*[http://kdesvn-build.kde.org/ kdesvn-build]
*[[Projects/MovetoGit/MassCloneScript]]
*[http://rubyforge.org/projects/build-tool/ build-tool]
*TODO: link to mr

==pre-receive hooks==
{{Progress bar|50}}
'''Owner:''' ''volunteers needed!!''

* Line endings and encodings

'''Discussion:'''
this got accidentally marked as done or something, but it's not.

This has now been ported to Git - bcooksley

Note however that it doesn't look for a .gitattributes file yet - patches welcome ( see sysadmin/repo-management on git.kde.org )

'''Notes:'''
> > As for line-endings, be careful because Git is different from Subversion.
>
> different how?

Just ensure that all files are stored as LF only, except if there's a
.gitattributes file saying "-crlf" (i.e., allow it to have CRLF).

==Snapshot to read-only svn==
{{Progress bar|100}}
'''Owner:'''

:It's work, but maybe some people would like it. NEEDED for documentation, in order to get it back into SVN for the translators/scripty/?

'''Discussion'''

:Could be done with a git-svn gateway presumably? -Mike Arthur 19/10/2009 16:04

:if we leave the docbook stuff in svn, we can avoid this a bit longer. --[[User:Chani|Chani]] 23:21, 12 November 2009 (UTC)

Scripty operates on a git clone of the repo's. No need for this item imho -- toma

==[[Development/Tutorials/Git|Techbase Documentation]]==
'''Owner:''' Chani, greeneg, - ''please help out!''
{{Progress bar|10}}

:At least minimal documentation about how to checkout, how to request a merge needed, other git documentation and links to other git information would be very useful also.

:see the [[Development/Tutorials/Git|Git Tutorial Page]]. help wanted!!

'''Discussion'''

==Setup git mirrors for cloning==
{{Progress bar|100}}
'''Owner:''' sysadmin
:Re-purpose the anonsvn servers. This item might be a blocker.
'''Discussion'''
:sysadmin will add mirrors as needed and is prepared for it. -- toma

==Local pre-commit hooks==
{{Progress bar|0}}
'''Owner:''' argonel

:A set of recommended local hooks that give useful warnings could be nice to have.

'''Discussion'''
...on the other hand, if we get a lot of bikeshedding about what hooks, then it won't be so nice. so I'd put this in the "very optional" pile. --[[User:Chani|Chani]] 19:10, 16 December 2009 (UTC)

=Post-migration Issues=

==Website Branding==
{{Progress bar|50|text=(initial ideas on the table)}}
'''Owner:''' ruphy

:KDE Gitorious should be branded accordingly, and should be reachable from git.kde.org as well as kde.gitorious.org

'''Discussion'''

Is this section still necessary at all? Perhaps some branding has to be done for redmine or cgit, but I don't know. --jmho

Neverendingo is looking at this as needed --toma

=Unscheduled & Open=

==Allow tagging without involving sysadmins==
{{Progress bar|100}}

'''Owner:''' sysadmin

:Gitolite allows sysadmin to permit certain people on certain repos only to manage both branches and tag without needing force push rights.

'''Discussion'''

==Account setup for Gitolite==
{{Progress bar|100}}

'''Owner:''' ''sysadmin''

:Accounts for existing SVN accounts which use SSH for access have been automatically granted access to Gitolite. Those who are still using HTTPS need to file a sysadmin bug to change their SVN account to SSH and will recieve Git access automatically.

==post-update hooks==
{{Progress bar|100}}
'''Owner:''' ''morice'' ''Ian Monroe''

:* License checker

'''Discussion:'''
We have a fairly complete set of post-update hooks now. See [http://gitorious.org/remotehook remotehook]. However, it would be nice to have a system that lives on the Gitorious server and/or requires less manual maintenance. But its certainly workable and no longer a blocker.

Working fine in the new setup, --toma

=Completed Tasks=

==Get rid of svn:externals==
{{Progress bar|100}}
'''Owner:''' David Faure

'''Status:''' ''???''

:not possible with git, broken by design.

::

'''Discussion'''

Exists, but ignorable:
* kdesupport shared-desktop-ontologies (temporary)
* playground/utils strigi-chemical/test/ctfr
* playground/devtools kdevelop4-extra-plugins/php/parser/generated/kdevelop-pg-qt
* playground/devtools kdevelop4-extra-plugins/python/parser/generated/kdevelop-pg-qt
* playground/devtools kdevelop4-extra-plugins/qmake/parser/generated/kdevelop-pg-qt
* playground/devtools kommander-plugins/database3/admin
* playground/devtools kommander-plugins/database/admin
* playground/devtools kommander-plugins/datetimefuncs/admin
* playground/devtools kommander-plugins/htmlpart/admin
* playground/devtools kommander-plugins/httpform/admin
* playground/devtools kommander-plugins/kparts/admin
* playground/devtools kommander-plugins/qtactionproxy/admin
* playground/devtools kommander-plugins/timewidget/admin
* playground/devtools kommander-plugins/webkit3/admin
* playground/devtools kpackagemaker/admin

==EBN==
{{Progress bar|95}}
'''Owner:''' ''drf''

'''Status:''' ''Amarok has EBN checks''

:EBN's krazy checks currently run on kde's svn repo; it needs upgrading to download and check our git repos too.

:This would be easier if there was a repo-list that EBN could parse, as it can no longer just svn up to get everything.

==Talk to people using other distros about git==
{{Progress bar|100}}
'''Owner:''' Sebas, Eike

'''Discussion'''
* Gentoo: They seem to be prepared for moving their live SVN packages to git; their package manager has easily-reusable classes to fetch from an SCM and moving the ebuilds to using the git class rather than the SVN class should be easy. Positive comments to that end from people in #gentoo-kde.
* Fedora: Some unhappyness about git because SVN allows them to remotely produce a diff between two SVN URLs (or two revisions of one and the same URL) without making a checkout first, while git requires making a clone. Kevin Kofler (IRC nick Kevin_Kofler, #fedora-kde) says this will make their packager work harder.
* Debian: Is indifferent about the SCM switch.

==Post Update hooks==
{{Progress bar|100}}
'''Owner:''' ''morice, johan, mattr

:List of scripts needed:
:* BUG/CCMAIL
:* email/CIA

:Gitorious needs to provide a way for hooks to be called; KDE needs to write said hooks.

'''Discussion'''

:There is a branch of gitorious called web-hooks http://gitorious.org/gitorious/mainline/commits/web-hooks --Panagiotis Papadopoulos 1 November 2009
:Same situation as commit emails. I can do it but it doesn't scale well and a Gitorious-supported solution would be nicer. --[[User:Eean|eean]] 16:07, 12 November 2009 (UTC)

==Reviewboard==
{{Progress bar|100}}
'''Owner:''' darktears

This should be easily done with Gitorious web interface and merge requests actually.

'''Discussion'''

:but reviewboard has features gitorious (right now) doesn't, like commenting on specific lines and not having to set up a merge request. --chani
::Also email notifications when someone reviews are needed --thomasz
:We're working on this for someone else right now, so pretty soon --johan-s
:I consider the latest changes to gitorious to finish this. If more reviewboard features are still needed, and git supports reviewboard, I think this is something we can look at doing post-conversion. --Ian Monroe

==Gitorious Needs a feature to disable merge request emails for certain repos==
{{Progress bar|100}}
'''Owner:''' [http://gitorious.org/gitorious Gitorious]

Have a sensible system for merge request emails. This is now in place - you can join groups, chose whether to have emails on a per repo basis, etc.

==SSH blocked in corporations and universities.==
{{Progress bar|100}}
'''Owner:''' ''Unknown''

:Some universities tend to block the SSH port. There should be a workaround to use SSH on some different port. github.com already runs a SSH server on port 443. But that assumes you are using a proxy. It has been found that this hasn't worked with a lot of people, especially those who have a direct connection to the internet ( so some transparent blocking by the ISP ). It would be great if (almost) every KDE developer were to be asked to check if other ports work before KDE made the switch. Otherwise there could be an automated email where the git patches could be sent, and appropriately patched to the right location too.

'''Discussion'''

:http://blog.gitorious.org/2009/10/20/stuck-behind-a-firewall/, and there's always been HTTP cloning (although the current impl. in Git is a bit on the slow side) --johan-s

==Talk to windows guys about git.==
{{Progress bar|100}}
'''Owner:''' aseigo

'''Discussion'''

They aren't huge fans of git, but are using it. They require a single mainline and can't cope with multiple branches. Otherwise, it's workable, even if it will take an adjustment period.

==pre-commit hooks==
{{Progress bar|100}}
'''Owner:''' ''(unknown)''

:acltest, docbook, EOL/UTF-8

:A web hook isn't good enough for these because they have to run and return whether to allow the push, for every single push to every KDE repo.

'''Discussion'''

:gitorious guys said they *might* be willing to allow a few scripts on their server for KDE as a special exception, iirc. --chani

:: Yes, at least for basic things, heavier things like doc building would probably have to be mirrored (goes for pre/post) --johan-s

:It turns out that acl and docbook might not be needed so long as web and docs/ stuff stays in svn.

:: Here's where to find the current scripts - http://websvn.kde.org/trunk/kde-common/svn/hooks/ --[[User:Argonel|Argonel]] 23:06, 11 November 2009 (UTC)

::So: this is actually done because it needs no longer to be done? (boud)

::Apparently, so; moving to complete. (aseigo)

= other notes =

==kde-common/accounts==

Someone said: KDE accounts file is no longer necessary---used for mapping svn ID -> email, but we have that now from Gitorious.
Answer from David Faure: I strongly disagree. We still need a KDE accounts file. This is very useful for finding people's email addresses, and having an overview on the number of active kde contributors; and if we keep it we can even have a kdepim resource again for filling an addressbook from it, for completion in kmail's composer (so you can write to any other kde contributor by just typing his/her name). It's also used for populating automatically the kde-cvs-announce mailing-list, for announcements. kde-common/accounts is our family tree (well, list), let's not get rid of it.

Here's my proposal for a kde-common/accounts replacement for the git era: We write a post-receive hook that looks at every commit and records all known email addresses for a given real name as well as the commit hash and date of when an address was last encountered. We can then present that data in the form of a file like kde-common/accounts, or write a web interface to query it (with nice links to the commits on Gitorious, etc.) --Eike (Sho_ on IRC)

To clear up possible confusion: The author information for a given commit is baked into the commit object itself, and comes from the configuration of the git repository it was created in. It is unrelated to any Gitorious account. Due to the distributed nature of Git, the one who uses his Gitorious account to push a commit need not be the same who created it. If Developer A creates a commit in his local clone and Developer B fetches it into his local clone directly from Developer A's machine and then pushes it into the public repo, the repo will only show a commit from Developer A. The Gitorious website will show that Developer B has pushed up a commit from Developer A, but that data is not contained in the repository. Thus collecting only Gitorious accounts and their mail addresses is insufficient. --Eike

==Random==
http://mail.kde.org/pipermail/dot-stories/2005-May/000509.html might be a good guide on what docs we need.

some of this stuff was from the list from GCDS that was in this email [http://markmail.org/message/u6eqfjece7fibfyo http://markmail.org/message/u6eqfjece7fibfyo]

==IRC Meetings==
* [[Projects/MovetoGit/Meeting1111|Minutes]] of meeting 11 November 2009
* [[Projects/MovetoGit/Meeting1118|Next meeting]] 18:00, 25 November 2009 (UTC)

= jobs =
''TODO merge this with the todolists above''

michael jansen: talking to kdesvn-build/mpyne
:--Done? -> http://kdesvn-build.kde.org/releases/kdesvn-build-1.10.php -- Panagiotis Papadopoulos 1 November 2009
::Yes, but the __kdesvn-build-remote used in the impl isn't pleasant for users already on git so it still needs more work for them. [[User:Mpyne|Mpyne]] 20:32, 11 November 2009 (UTC)

jonas: domain name

chani: techbase docs for scripty

sebas/lydia/leo: communication with teams! tell people! keeping track that
everything is being done.

Projects/MovetoGit

2010-03-08T19:46:59Z

Zander: /* Write / update importing rules for svn2git */

This is the page for co-ordinating KDE's move to [http://git-scm.com/ Git].

If you're interested in helping, you should join the [https://mail.kde.org/mailman/listinfo/kde-scm-interest kde-scm-interest@kde.org] mailinglist and [irc://chat.freenode.net/kde-git #kde-git] on freenode.

Meetings are wednesdays, 19:30 UTC, in #kde-git.

=The Plan=

KDE is, eventually, moving to Git. We will be using [http://gitorious.org/ gitorious.org] servers, with funding from Nokia. We will also have our own mirrors using existing KDE servers.

We are working with the Gitorious people to ensure their server will meet all our needs as well as everyone's privacy requirements. The distributed nature of Git will make it easy for us to migrate off gitorious.org at any time should the need arise (but that's unlikely :).

In the summer of 2009, [http://gitorious.org/amarok Amarok] moved to Gitorious to test the waters and find problems that would affect KDE. Once those problems have been solved, all of KDE will be able to switch.

==Why?==

Git offers many advantages over svn, including offline commits and much easier to keep a feature branch up-to-date. Many KDE developers are already using git-svn, but this tool has its limitations. We want to have the full power of Git available, and we have people willing to do the work necessary to migrate.

==How?==

When we move, KDE's svn repository will be migrated into several Git repos, all on gitorious.org. Main modules such as kdelibs and kdebase will each become one repository. Projects in extragear will each have their own repository. The kde.gitorious.org site will have a list (lists?) of all these repositories using the builtin project wiki. Scripts will be provided for downloading, say, all of extragear, so "moving" a project from kdereview to extragear would simply involve editing a file kept online that defined the location of projects.

A few things will stay in subversion - currently websites, translations and manuals. It's possible they could move to Git later, but they won't be part of the mass migration.

On Gitorious, all KDE developers will be part of the [http://gitorious.org/+kde-developers kde-developers group]. Developers in this group are required to set their "full name" for their Gitorious account to their real name. If you want to be in this group, file a bugreport for sysadmin on bugs.kde.org. :)

The procedure to move a project from svn to gitorious.org can be found in [[Projects/MoveToGit/StepsToMove|Steps to follow for Moving]].

=Blockers=

Tasks that need to get done before we can migrate

==SLA for gitorious.org==
{{Progress bar|30}}
'''Owner:''' aseigo, frank

'''Status:''' ''Progressing well; will take a while''

: The SLA terms need to be documented as well as who will be footing the bill, if any. TZander has talked to Shortcut AS and sent the relevant information (eg cost) to the KDE eV board.

: aseigo and Frank (and someone?) had a meeting with Shortcut people during tokamak. They asked for a rather large sum of money; negotiations are continuing, but we might want to consider hosting our own server...

==Write / update importing rules for svn2git==
{{Progress bar|0}}
'''Owner:''' see below - volunteers needed!

'''Status:''' ''sandsmark: stuck on a svn2git bug. sho: ???, tumaix:started to read the docs, cryos: getting started [2010-01-06]''

:The importer is on gitorious.org as svn2git we have a set of rules to tell the importer what svn dirs turn into which git repos and those need constant updating whenever a new branch or tag or project is created. Currently the rules are mostly a rough draft, as seen by the large amount of rule-editing that had to be done for Konversation and Amarok. This has not been done for quite some time and so someone should rsync the svn repo run svn2git and fix the rules and importer whenever the import stops.

:This is a very big task, too big for one person; it's probably best to tackle it one module at a time

:To get started on a module, read [[Projects/MoveToGit/UsingSvn2Git|Using Svn2Git]]

:TZander has done the koffice ruleset as of 2009-01-06

:Jpwhiting has finished (more or less) the kdeaccessibility ruleset 2010-01-24.

:aavci has done the k3b ruleset as of 2010-01-27

progress details:
{| border="1"
!repo
!owner
!%
!comments
|-
|SC/kdeaccessibility
|jpwhiting
|99
|"more or less"?
|-
|SC/kdeadmin
|
|0
|
|-
|SC/kdeartwork
|
|0
|
|-
|SC/kdebase
|
|0
|
|-
|SC/kdebindings
|
|0
|
|-
|SC/kdeedu
|cryos?
|?
|update me!
|-
|SC/kdeexamples
|
|0
|
|-
|SC/kdegames
|tumaix?
|?
|update me!
|-
|SC/kdegraphics
|
|0
|
|-
|SC/kdelibs
|
|0
|
|-
|SC/kdemultimedia
|eean
|0
|
|-
|SC/kdenetwork
| grundleborg
|0
|
|-
|SC/kdepim
|tnyblom
|0
|Just getting started Help needed.
|-
|SC/kdepimlibs
|tnyblom
|0
|Just getting started Help needed.
|-
|SC/kdeplasma-addons
|
|0
|
|-
|SC/kdesdk
|mattr
|0
|just starting
|-
|SC/kdetoys
|mattr
|0
|just starting
|-
|SC/kdeutils
|
|0
|
|-
|SC/kdewebdev
|
|0
|
|-
|extragear/sdk/kdevelop
| apaku
| 85
| Misses history from KDE3.3 and older (KDevelop3.2), probably something with layout-changes, might need recurse-action but don't know how to do it.
|-
|extragear/sdk/kdevplatform
| apaku
| 100
| done, all tags seem fine all branches are there
|-
|extragear/*/*
|
|xx
|expand the *'s later (let's focus on the base modules first)
|-
|kde-common
|mattr
|0
|just starting
|-
|kdesupport
|
|0
|
|-
|koffice
|tzander
|85
|All but tags are done
|-
|promo
|
|0
|
|-
|quality
|
|0
|
|-
|tests
|
|0
|
|}

== Requirements of KDEPIM and KDAB ==

{{Progress bar|10}}
'''Owner:''' till (To be reassigned)

'''Status:''' ''Requirements of tools and for workflow identified. Someone from KDAB will be nominated to co-ordinate and communicate specific requirements''

'''Summary of issues'''

* Branch maintenance workflow
** KDAB maintains several branches of legacy versions of KDE for enterprise customer deployments. [http://websvn.kde.org:80/branches/kdepim/enterprise/ Enterprise 3.5] [http://websvn.kde.org:80/branches/kdepim/enterprise4/ Enterprise 4 (based on KDE 4.2)]. The current KDEPIM trunk known as Enterprise 5 and is Akonadi based.
** Periodically (weekly or so), tags are created from the enterprise branches with bugfixes. http://websvn.kde.org:80/tags/kdepim/ Customers can download the tagged versions with the latest updates. Fixes are merged from the Enterprise 3.5 branch, and into trunk (which sometimes involves a lot of work, as the fix must be ported to Akonadi). Additionally, fixes get merged in the other direction. From official KDE modules into the Enterprise branches.
** Some fixes from Enterprise 3.5 should not be merged into Enterprise 4 for reasons such as no longer being reproducible. Some fixes do not get merged for a long time because they require so much work that porting the fix or feature is deffered. There needs to be a list of commits which should never be merged (blocked commits), and commits which should be merged, but have not been merged yet. The tool [[Development/Tools/svnmerge.py|svnmerge]] is used to facilitate this. svnmerge uses svn properties to maintain lists of commits that are blocked and that have already been integrated. See for example the svn-blocked and svn-integrated properties here: http://websvn.kde.org:80/trunk/KDE/kdepim/. The lists of commits available to be merged into the various branches are here: http://www.kdab.com/~thomas/avail/
** There needs to be a way in git to keep track of what commits have been merged, what commits need to be merged, and what commits are blocked. There needs to be a way of merging only specific commits from a branch, but not all, and not blocked commits. Proposed solutions:
*** git cherry-pick allows 'merging' of individual commits, but does not record where the commits came from. Instead it creates a new commit without any reference to where it came from. This alone is unsuitable.
*** branch per fix. This would lead to an explosion of branches which is not a problem in git as all commits are branches. It may make gitk un-navigatable. There would need to be a naming convention such as komo-merge-<fixname> for branches which should be merged. The commands <tt>git checkout 4.5 && git merge $(git branch -a | grep -E ^origin/komo-merge)</tt> and <tt>git checkout enterprise4.5 && git merge $(git branch -a | grep -E ^origin/komo-merge)</tt> and <tt>git checkout master && git merge $(git branch -a | grep -E ^origin/komo-merge)</tt>. That could of course be optimized, but gets the point across. If the code has changed so much that the branch is unmergable, but the fix still needs to be in trunk, the system breaks down.
*** Custom git command with flat text files representing the same information as svnmerge, that is lists of blocked and integrated commits. This is most likely to be a workable solution, possibly together with conventional branch naming.
* Clean slate
** The existing backlog of commits which need to be merged or ported to trunk needs to be empty before the change to git so that nothing gets lost. This is a lot of work and will take time.
* Internal Tools and external customer tools and workflows
** KDAB is a consumer of KDE software, but also has downstream customers fetching software from where it is developed. That is, KDE SVN. For example packages are created from the tags in tags/kdepim. Some of these downstreams are less close to KDE and depend on current workflows. If KDE SVN is not the place to get those updates anymore, this needs to be communicated to those downstreams, and the tools updated.
** People who don't currently know how to use git need to get familiar with it so that transitioning will be nearly seamless, and not result in too much development slowdown.
* Other commitments
** Project deadlines and other commitments prevent the possiblity of blocking off time to work on git migration when so many other things need to be done which have milestones separate to KDE cycles. The required work to convert to git can't be prioritized as highly, and so will take more time.
* Technical difficulties and limitations.
** Up to KDE 3.5 there was one kdepim module. For the KDE4 cycle, this was split into kdepimlibs and kdepim. For the above mentioned merging to be possible, it makes sense for both to be in the same git module. This poses extra difficulty to the svn2git script.

'''Email threads'''

* Mid-January thread on scm-interest: http://thread.gmane.org/gmane.comp.kde.devel.pim/26726
* Early March thread on kde-core-devel (Till email): http://thread.gmane.org/gmane.comp.kde.devel.core/63915/focus=63970
* Early March thread on kde-core-devel (Till follow-up):
http://thread.gmane.org/gmane.comp.kde.devel.core/63915/focus=64069

=Nice to have before the migration=

==Push log==
{{Progress bar|0}}
'''Owner:''' nobody!!

'''Status:''' argonel had a hd failure :( [2010-01-06]

:Gitorious records who pushed each commit. This is useful information because commits themselves can say anything, and there are legitimate reasons to push commits with another person's name.

:Internally, Gitorious stores this information in an SQL database, and the information is viewable through the web interface. However we want a way to backup this information for the case that Gitorious suddenly go offline.

:quotes from the mailing list:

> How about every repo has, by convention, a "commits" branch and
> a post commit hook that ensures whatever meta info is required,
> however it can be gleaned, is also checked into that commits branch.
> A bit like how gitosis uses a repo to store auth/acl info to help
> manage the other repos.

That's exactly my idea. And of course it won't be named commits, because we're
not talking about commits.

It's a push log, similar to a local repository's reflog.

---------------

For every push, log:
- who pushed (not the Unix username, which will be "git")
- which branch heads changed (what from, what to)
- which tags were created
- the state of all other branches and tags

Just use git commit-tree with the empty tree and save everything in the commit
message, one after the other.

-----------

This does not require help from gitorious.org until the script is actually written: it's just another pre-receive hook for them to install on their servers.
it *might* also be possible to run it as a post-receive hook (in which case we can do the whole thing ourselves).

if we self-host, then we won't need this.

==Script for downloading virtual KDE hierarchies==
{{Progress bar|0}}
'''Owner''':

'''Status:'''

:Let's start over on this.
what we already have: two build scripts for kde; kdesvn-build and build-tool.
what we want: an easy way for people to get large chunks of kde, without thinking about what urls the repos come from or having to look things up.

do kde-svnbuild and build-tool satisfy this well enough?
or do we want a computer-readable file listing all the repos too?

btw, scripty has its own list of repos already. it's just in a rather weird bash file.

'''Links'''
[http://kdesvn-build.kde.org/]
[[Projects/MovetoGit/MassCloneScript]]
[http://rubyforge.org/projects/build-tool/]

==pre-receive hooks==
{{Progress bar|0}}
'''Owner:''' ''volunteers needed!!''

* Line endings and encodings

'''Discussion:'''
this got accidentally marked as done or something, but it's not.

'''Notes:'''
> > As for line-endings, be careful because Git is different from Subversion.
>
> different how?

Just ensure that all files are stored as LF only, except if there's a
.gitattributes file saying "-crlf" (i.e., allow it to have CRLF).

==Snapshot to read-only svn==
{{Progress bar|0}}
'''Owner:'''

:It's work, but maybe some people would like it. NEEDED for documentation, in order to get it back into SVN for the translators/scripty/?

'''Discussion'''

:Could be done with a git-svn gateway presumably? -Mike Arthur 19/10/2009 16:04

:if we leave the docbook stuff in svn, we can avoid this a bit longer. --[[User:Chani|Chani]] 23:21, 12 November 2009 (UTC)

==[[Development/Tutorials/Git|Techbase Documentation]]==
'''Owner:''' Chani, greeneg, - ''please help out!''
{{Progress bar|10}}

:At least minimal documentation about how to checkout, how to get a Gitorious account, how to request a merge needed, other git documentation and links to other git information would be very useful also.

:see the [[Development/Tutorials/Git|Git Tutorial Page]]. help wanted!!

'''Discussion'''

==Setup git mirrors for cloning==
{{Progress bar|0}}
'''Owner:''' No one (help!)
:Re-purpose the anonsvn servers. This item might be a blocker.
'''Discussion'''

==Local pre-commit hooks==
{{Progress bar|0}}
'''Owner:''' argonel

:A set of recommended local hooks that give useful warnings could be nice to have.

'''Discussion'''
...on the other hand, if we get a lot of bikeshedding about what hooks, then it won't be so nice. so I'd put this in the "very optional" pile. --[[User:Chani|Chani]] 19:10, 16 December 2009 (UTC)

=Post-migration Issues=

==Website Branding==
{{Progress bar|2|text=(initial ideas on the table)}}
'''Owner:''' ruphy

:KDE Gitorious should be branded accordingly, and should be reachable from git.kde.org as well as kde.gitorious.org

'''Discussion'''

=Unscheduled & Open=

==Allow tagging without involving sysadmins==
{{Progress bar|0}}

'''Owner:''' johan

:Pushing a tag currently requires permissions to do a force push, which is a repository-wide checkbox that can only be toggled by a kde-developers admin. Thus the workflow for a dev wanting to do a release tag for his app is to ask an admin to enable force pushing, then to push his tag, and then to tell the admin he can disable force pushing again. This doesn't scale, is insecure, and at odds with KDE's open access policy when it comes to managing the repos (right now in SVN, you need sysadmin to create an app dir in /tags for you, but don't have to ask permission for every individual tag). Johan has promised a solution for this.

:Notable discussion points on kde-scm-interest:
:http://mail.kde.org/pipermail/kde-scm-interest/2009-November/000782.html
:http://mail.kde.org/pipermail/kde-scm-interest/2009-November/000784.html

'''Discussion'''

==Account setup on Gitorious==
{{Progress bar|0}}

'''Owner:''' ''eean, johan, boud, dario''

:Creating an account on Gitorious isn't hard, but asking to be added to the KDE group is inconvenient. For the migration we should set up a system (via email or wiki?) where developers can ask to have an account autocreated for them, or add their existing Gitorious account to a list to be added to the group. Once this is in place an announcement should be sent to all svn accounts explaining the process, and privacy information.

:Basically the currently method of using Bugzilla works fine now and works fine in the longterm. But in the transition month when hundreds of accounts must be created or added, we need a better system. Its important to make it as easy as possible so that we don't lose anyone in the shuffle.

'''Discussion'''

: I think most people have made their own accounts by now. this isn't really needed.

==post-update hooks==
{{Progress bar|90}}
'''Owner:''' ''morice'' ''Ian Monroe''

:* License checker

'''Discussion:'''
We have a fairly complete set of post-update hooks now. See [http://gitorious.org/remotehook remotehook]. However, it would be nice to have a system that lives on the Gitorious server and/or requires less manual maintenance. But its certainly workable and no longer a blocker.

=Completed Tasks=

==Get rid of svn:externals==
{{Progress bar|100}}
'''Owner:''' David Faure

'''Status:''' ''???''

:not possible with git, broken by design.

::

'''Discussion'''

Exists, but ignorable:
* kdesupport shared-desktop-ontologies (temporary)
* playground/utils strigi-chemical/test/ctfr
* playground/devtools kdevelop4-extra-plugins/php/parser/generated/kdevelop-pg-qt
* playground/devtools kdevelop4-extra-plugins/python/parser/generated/kdevelop-pg-qt
* playground/devtools kdevelop4-extra-plugins/qmake/parser/generated/kdevelop-pg-qt
* playground/devtools kommander-plugins/database3/admin
* playground/devtools kommander-plugins/database/admin
* playground/devtools kommander-plugins/datetimefuncs/admin
* playground/devtools kommander-plugins/htmlpart/admin
* playground/devtools kommander-plugins/httpform/admin
* playground/devtools kommander-plugins/kparts/admin
* playground/devtools kommander-plugins/qtactionproxy/admin
* playground/devtools kommander-plugins/timewidget/admin
* playground/devtools kommander-plugins/webkit3/admin
* playground/devtools kpackagemaker/admin

==EBN==
{{Progress bar|95}}
'''Owner:''' ''drf''

'''Status:''' ''Amarok has EBN checks''

:EBN's krazy checks currently run on kde's svn repo; it needs upgrading to download and check our git repos too.

:This would be easier if there was a repo-list that EBN could parse, as it can no longer just svn up to get everything.

==Talk to people using other distros about git==
{{Progress bar|100}}
'''Owner:''' Sebas, Eike

'''Discussion'''
* Gentoo: They seem to be prepared for moving their live SVN packages to git; their package manager has easily-reusable classes to fetch from an SCM and moving the ebuilds to using the git class rather than the SVN class should be easy. Positive comments to that end from people in #gentoo-kde.
* Fedora: Some unhappyness about git because SVN allows them to remotely produce a diff between two SVN URLs (or two revisions of one and the same URL) without making a checkout first, while git requires making a clone. Kevin Kofler (IRC nick Kevin_Kofler, #fedora-kde) says this will make their packager work harder.
* Debian: Is indifferent about the SCM switch.

==Post Update hooks==
{{Progress bar|100}}
'''Owner:''' ''morice, johan, mattr

:List of scripts needed:
:* BUG/CCMAIL
:* email/CIA

:Gitorious needs to provide a way for hooks to be called; KDE needs to write said hooks.

'''Discussion'''

:There is a branch of gitorious called web-hooks http://gitorious.org/gitorious/mainline/commits/web-hooks --Panagiotis Papadopoulos 1 November 2009
:Same situation as commit emails. I can do it but it doesn't scale well and a Gitorious-supported solution would be nicer. --[[User:Eean|eean]] 16:07, 12 November 2009 (UTC)

==Opt-in privacy exception required for kde-developers==
<strike>
{{Progress bar|0}}
'''Owner:''' ''Gitorious'', ''KDE e.V. Board'', ''eean''

:KDE sysadmins need access to some information that Shortcut could not give them due to their privacy policy. Examples include an email list of all the developers and SQL-level access to information about all the repos in KDE (since it stores who pushes what, information not stored in the git repo itself).

:Such requirements will likely be put into the contract with Shortcut.

'''Discussion'''
:So the e.V. Board is an owner since this is a legal/contract/money issue. Added myself only because I'm shepherding the issue. --[[User:Eean|eean]] 16:16, 12 November 2009 (UTC)

</strike>

:'''We will not get sql access to the information. For the alternative solution see the Push Log issue'''

==Reviewboard==
{{Progress bar|100}}
'''Owner:''' darktears

This should be easily done with Gitorious web interface and merge requests actually.

'''Discussion'''

:but reviewboard has features gitorious (right now) doesn't, like commenting on specific lines and not having to set up a merge request. --chani
::Also email notifications when someone reviews are needed --thomasz
:We're working on this for someone else right now, so pretty soon --johan-s
:I consider the latest changes to gitorious to finish this. If more reviewboard features are still needed, and git supports reviewboard, I think this is something we can look at doing post-conversion. --Ian Monroe

==Gitorious Needs a feature to disable merge request emails for certain repos==
{{Progress bar|100}}
'''Owner:''' [http://gitorious.org/gitorious Gitorious]

Have a sensible system for merge request emails. This is now in place - you can join groups, chose whether to have emails on a per repo basis, etc.

==SSH blocked in corporations and universities.==
{{Progress bar|100}}
'''Owner:''' ''Unknown''

:Some universities tend to block the SSH port. There should be a workaround to use SSH on some different port. github.com already runs a SSH server on port 443. But that assumes you are using a proxy. It has been found that this hasn't worked with a lot of people, especially those who have a direct connection to the internet ( so some transparent blocking by the ISP ). It would be great if (almost) every KDE developer were to be asked to check if other ports work before KDE made the switch. Otherwise there could be an automated email where the git patches could be sent, and appropriately patched to the right location too.

'''Discussion'''

:http://blog.gitorious.org/2009/10/20/stuck-behind-a-firewall/, and there's always been HTTP cloning (although the current impl. in Git is a bit on the slow side) --johan-s

==Talk to windows guys about git.==
{{Progress bar|100}}
'''Owner:''' aseigo

'''Discussion'''

They aren't huge fans of git, but are using it. They require a single mainline and can't cope with multiple branches. Otherwise, it's workable, even if it will take an adjustment period.

==pre-commit hooks==
{{Progress bar|100}}
'''Owner:''' ''(unknown)''

:acltest, docbook, EOL/UTF-8

:A web hook isn't good enough for these because they have to run and return whether to allow the push, for every single push to every KDE repo.

'''Discussion'''

:gitorious guys said they *might* be willing to allow a few scripts on their server for KDE as a special exception, iirc. --chani

:: Yes, at least for basic things, heavier things like doc building would probably have to be mirrored (goes for pre/post) --johan-s

:It turns out that acl and docbook might not be needed so long as web and docs/ stuff stays in svn.

:: Here's where to find the current scripts - http://websvn.kde.org/trunk/kde-common/svn/hooks/ --[[User:Argonel|Argonel]] 23:06, 11 November 2009 (UTC)

::So: this is actually done because it needs no longer to be done? (boud)

::Apparently, so; moving to complete. (aseigo)

= other notes =

==kde-common/accounts==

Someone said: KDE accounts file is no longer necessary---used for mapping svn ID -> email, but we have that now from Gitorious.
Answer from David Faure: I strongly disagree. We still need a KDE accounts file. This is very useful for finding people's email addresses, and having an overview on the number of active kde contributors; and if we keep it we can even have a kdepim resource again for filling an addressbook from it, for completion in kmail's composer (so you can write to any other kde contributor by just typing his/her name). It's also used for populating automatically the kde-cvs-announce mailing-list, for announcements. kde-common/accounts is our family tree (well, list), let's not get rid of it.

Here's my proposal for a kde-common/accounts replacement for the git era: We write a post-receive hook that looks at every commit and records all known email addresses for a given real name as well as the commit hash and date of when an address was last encountered. We can then present that data in the form of a file like kde-common/accounts, or write a web interface to query it (with nice links to the commits on Gitorious, etc.) --Eike (Sho_ on IRC)

To clear up possible confusion: The author information for a given commit is baked into the commit object itself, and comes from the configuration of the git repository it was created in. It is unrelated to any Gitorious account. Due to the distributed nature of Git, the one who uses his Gitorious account to push a commit need not be the same who created it. If Developer A creates a commit in his local clone and Developer B fetches it into his local clone directly from Developer A's machine and then pushes it into the public repo, the repo will only show a commit from Developer A. The Gitorious website will show that Developer B has pushed up a commit from Developer A, but that data is not contained in the repository. Thus collecting only Gitorious accounts and their mail addresses is insufficient. --Eike

==Random==
http://mail.kde.org/pipermail/dot-stories/2005-May/000509.html might be a good guide on what docs we need.

some of this stuff was from the list from GCDS that was in this email [http://markmail.org/message/u6eqfjece7fibfyo http://markmail.org/message/u6eqfjece7fibfyo]

==IRC Meetings==
* [[Projects/MovetoGit/Meeting1111|Minutes]] of meeting 11 November 2009
* [[Projects/MovetoGit/Meeting1118|Next meeting]] 18:00, 25 November 2009 (UTC)

= jobs =
''TODO merge this with the todolists above''

michael jansen: talking to kdesvn-build/mpyne
:--Done? -> http://kdesvn-build.kde.org/releases/kdesvn-build-1.10.php -- Panagiotis Papadopoulos 1 November 2009
::Yes, but the __kdesvn-build-remote used in the impl isn't pleasant for users already on git so it still needs more work for them. [[User:Mpyne|Mpyne]] 20:32, 11 November 2009 (UTC)

jonas: domain name

ML: convert to SSH

chani: techbase docs for scripty

sebas/lydia/leo: communication with teams! tell people! keeping track that
everything is being done.

Projects/MovetoGit

2009-12-02T21:57:26Z

Zander: /* Random */

Projects/MovetoGit

2009-12-02T21:56:46Z

Zander: /* jobs */

Projects/MovetoGit

2009-12-02T21:52:27Z

Zander: /* Update bugs.kde.org's account-request page */

Projects/MovetoGit

2009-12-02T21:48:53Z

Zander: /* Account setup on Gitorious */

Projects/MovetoGit

2009-12-02T21:48:33Z

Zander: /* Allow tagging without involving sysadmins */

Projects/MovetoGit

2009-12-02T21:46:48Z

Zander: /* Snapshot to read-only svn */

Projects/MovetoGit

2009-12-02T19:13:56Z

Zander: /* Gitorious Needs a New Contact Framework */

Development/Tutorials/KWord Scripting

2009-04-17T08:59:57Z

Zander: /* Intro */

==Intro==

KWord2.0 uses [[Development/Languages/Kross|Kross]] to provide scripting with [http://www.python.org/ Python], [http://www.ruby-lang.org/ Ruby] and [http://xmelegance.org/kjsembed KDE JavaScript].

With the 2.0 release the scripts Application Programming Interface (API) is unsupported and unfinished and known to change. Use the API at your own risk! When the API is stable you can depend on future versions not breaking your scripts, this support is not present in the 2.0 release of KWord.

===The Scripting Plugin===

The [http://websvn.kde.org/trunk/koffice/kword/plugins/scripting/ KWord Scripting Plugin] implements a plugin to dynamic access the scripting functionality from within KWord.

* The [http://websvn.kde.org/trunk/koffice/kword/plugins/scripting/KWScriptingPart.h?view=markup KWScriptingPart] class implements a KPart component to integrate scripting as plugin into KWord.
* The [http://websvn.kde.org/trunk/koffice/kword/plugins/scripting/Module.h?view=markup Scripting::Module] class enables access to the KWord functionality from within the scripting backends.
* The [http://websvn.kde.org/trunk/koffice/kword/plugins/scripting/FrameSet.h?view=markup FrameSet] and [http://websvn.kde.org/trunk/koffice/kword/plugins/scripting/Frame.h?view=markup Frame] classes are holding the content that is displayed on screen.
* The [http://websvn.kde.org/trunk/koffice/kword/plugins/scripting/TextDocument.h?view=markup TextDocument] class represents a QTextDocument within the Scribe text-engine KWord uses to enable editing of text content. The [http://websvn.kde.org/trunk/koffice/kword/plugins/scripting/TextCursor.h?view=markup TextCursor] implements a control structure for the successive traversal of content within such a TextDocument .

===Scripting Handbook===

The [http://kross.dipe.org/dox/kword.html KWord Scripting Handbook] ([http://kross.dipe.org/dox/kword.pdf PDF]) contains a full reference of the functionality accessible from within the scripting backends.

The Handbook is generated from the sourcecode using doxygen and KWord's [[Development/Tutorials/KWord_Scripting#Import_combined_Doxygen_XML_File|Import Doxygen XML File]] python script.

==Samples==

=== Load and save documents ===

Following Python script demonstrates how to load and save files;
<code python>
import KWord
KWord.document().openURL("/home/myuser/myDoc.odt")
KWord.document().saveAs("/home/myuser/myDocCopy.odt")
KWord.document().saveAs("/home/myuser/myDocAsText.txt")
</code>

All slots and signals within the [http://websvn.kde.org/trunk/koffice/libs/kofficecore/KoDocumentAdaptor.h?view=markup KoDocumentAdaptor] are accessible as KWord.document().

=== Import and export content ===

The [http://websvn.kde.org/trunk/koffice/kword/plugins/scripting/scripts/sample_importfile.py?view=markup sample_importfile.py] Python script implements import of content from a text or html file.

<code python>
import KWord
doc = KWord.mainFrameSet().document()
f = open("/home/myuser/mytextfile.txt", "r")
doc.setText( ' '.join(f.readlines()) )
#doc.setHtml( ' '.join(f.readlines()) )
f.close()
</code>

The [http://websvn.kde.org/trunk/koffice/kword/plugins/scripting/scripts/sample_exportfile.py?view=markup sample_exportfile.py] Python script implements export of content to a text or html file.

<code python>
import KWord
doc = KWord.mainFrameSet().document()
f = open("/home/myuser/mytextfile.txt", "w")
f.write( doc.toText() )
#f.write( doc.toHtml() )
f.close()
</code>

=== Framesets, Frames and Shapes ===

The following python script adds a polygon shape and then prints the name and the ID of each shape.
<code python>
import KWord
KWord.addFrame("mypoly", "KoRegularPolygonShape")
for i in range( KWord.frameCount() ):
f = KWord.frame(i)
print "%s %s" % (f.frameSet().name(),f.shapeId())
</code>

The [http://websvn.kde.org/trunk/koffice/kword/plugins/scripting/scripts/sample_insertshape.py?view=markup sample_insertshape.py] Python script implements inserting of a shape into the document.

<code python>
import KWord
textshape = KWord.addTextFrame("MyTextShape")
textshape.document().setText("Some text")
</code>

The [http://websvn.kde.org/trunk/koffice/kword/plugins/scripting/scripts/sample_allshapes.py?view=markup sample_allshapes.py] Python script just adds all shapes into the document.

<code python>
import KWord
for shapeId in KWord.shapeKeys():
frame = KWord.addFrame("myshape", shapeId)
if frame:
frame.setTextRunAround(frame.RunThrough)
frame.setPosition(200, 50)
frame.resize(160, 80)
</code>

=== Text content ===

The [http://websvn.kde.org/trunk/koffice/kword/plugins/scripting/scripts/sample_text.py?view=markup sample_text.py] Python script demonstrates usage of the text engine.

The following python sample adds some text at the end of the main framesets document.
<code python>
import KWord
doc = KWord.mainFrameSet().document()
cursor = doc.rootFrame().lastCursorPosition()
cursor.insertHtml("Some text")
</code>

This python sample adds some text and sets the page header and the page footer.
<code python>
import KWord
doc = KWord.mainFrameSet().document()
doc.lastCursor().insertHtml("Even more Hello World")
KWord.firstPageHeaderFrameSet().document().setText("Header")
KWord.firstPageFooterFrameSet().document().setText("Footer")
</code>

Python sample that prints the url and some metainformations of the document.
<code python>
import KWord
print KWord.document().url()
print KWord.document().documentInfoTitle()
print KWord.document().documentInfoAuthorName()
</code>

The [http://websvn.kde.org/trunk/koffice/kword/plugins/scripting/scripts/sample_lists_html.py?view=markup sample_lists_html.py] Python script demonstrates how to create lists with HTML.

The [http://websvn.kde.org/trunk/koffice/kword/plugins/scripting/scripts/sample_lists_cursor.py?view=markup sample_lists_cursor.py] Python script demonstrates how to create lists with a cursor.

The [http://websvn.kde.org/trunk/koffice/kword/plugins/scripting/scripts/sample_tables.py?view=markup sample_tables.py] Python script demonstrates how to deal with tables.

=== KoStore and XML ===

The following python sample does demonstrate how to print the element-names of all xml-files that are within the KWord KoStore backend (see [http://websvn.kde.org/trunk/koffice/libs/kokross/KoScriptingOdf.h?view=markup KoScriptingOdf.h]) for our current document.

<code python>
import KWord
store = KWord.store()
reader = store.open("META-INF/manifest.xml")
if not reader:
raise "Failed to read the mainfest"
paths = []
for i in range( reader.count() ):
if reader.type(i) == "text/xml":
paths.append( reader.path(i) )
for p in paths:
reader = store.open(p)
if not reader:
raise "Failed to read %s" % p
def onElement():
print reader.name()
reader.connect("onElement()", onElement)
reader.start()
</code>

=== Variables ===

The [http://websvn.kde.org/trunk/koffice/kword/plugins/scripting/scripts/sample_variables.py?view=markup sample_variables.py] Python script demonstrates how to handle variables.

<code python>
import KWord
doc = KWord.mainFrameSet().document()
for v in doc.variableNames():
print "name=%s value=%s" % (v, doc.variableValue(v))
</code>

The [http://websvn.kde.org/trunk/koffice/kword/plugins/scripting/scripts/variable_readfile.py?view=markup variable_readfile.py] Python script to read a variable from a file.

=== KWord ===

The [http://websvn.kde.org/trunk/koffice/kword/plugins/scripting/scripts/sample_cursor.rb?view=markup sample_cursor.rb] Ruby script demonstrates how to control the cursor.

The [http://websvn.kde.org/trunk/koffice/kword/plugins/scripting/scripts/sample_actions.py?view=markup sample_actions.py] Python script demonstrates usage of actions.

<code python>
import KWord
KWord.shell().slotFileNew()
KWord.mainWindow().setCaption("My Caption")
</code>

The [http://websvn.kde.org/trunk/koffice/kword/plugins/scripting/scripts/sample_toolactions.py?view=markup sample_toolactions.py] Python script demonstrates how to trigger actions the current tool provides.

<code python>
import KWord
tool = KWord.tool()
for n in tool.actionNames():
print "%s: %s" % (n, tool.actionText(n))
tool.triggerAction(n)
</code>

The [http://websvn.kde.org/trunk/koffice/kword/plugins/scripting/scripts/sample_progressbar.py?view=markup sample_progressbar.py] Python script demonstrates how to use the progressbar.

<code python>
import KWord
for i in range(1,101):
KWord.shell().slotProgress(i)
KWord.shell().slotProgress(-1)
</code>

The [http://websvn.kde.org/trunk/koffice/kword/plugins/scripting/scripts/onlinehelp.py?view=markup onlinehelp.py] Python script uses the KHTML Part to display the KWord Scripting online help.

<code python>
import Kross
forms = Kross.module("forms")
dialog = forms.createDialog("KHTML Part")
page = dialog.addPage("", "")
url = "http://wiki.koffice.org"
part = forms.loadPart(page, "libkhtmlpart", url)
dialog.exec_loop()
</code>

== Scripts ==

=== Import from a Text or HTML File ===

The python script [http://websvn.kde.org/trunk/koffice/kword/plugins/scripting/scripts/importfile.py?view=markup importfile.py] allows to import content from text- or html-files.

=== Import combined Doxygen XML File ===

The python script [http://websvn.kde.org/trunk/koffice/kword/plugins/scripting/scripts/importdoxyxml.py?view=markup importdoxyxml.py] implements import of combined doxygen XML files into KWord.

As example this got used to generate the KSpread Scripting API-Reference. This is done by running doxygen with the [http://websvn.kde.org/trunk/koffice/kspread/plugins/scripting/docs/ KSpread doxygen file].

We are able to produce from within the commandline the handbook like demonstrated bellow;
cd kspread/plugins/scripting/docs
doxygen kspreadscripting.doxyfile
cd xml
xsltproc combine.xslt index.xml | importdoxyxml.py kspread.html

You are also able to just generate a combined doxygen XML file with;
cd kspread/plugins/scripting/docs
doxygen kspreadscripting.doxyfile
cd xml
xsltproc combine.xslt index.xml > ~/mydoxygen.xml

Such a combined doxygen XML file can then be imported into our running KWord instance by running "Import Doxygen XML File" python script from the Tools/Scripts-menu.

=== Import File with OpenOffice.org UNO ===

The python script [http://websvn.kde.org/trunk/koffice/kword/plugins/scripting/scripts/ooimport.py?view=markup ooimport.py] uses the PyUNO module to access OpenOffice.org and import content from any by OpenOffice.org supported fileformat.
For this an optional hidden OpenOffice.org instance need to be started. Then the script connects as client to this OpenOffice.org server instance and controls it. If the script got executed and the connecting to the server failed, then it will startup such a hidden OpenOffice.org server instance and shuts it down again once the work is done.

If the script got executed from within KWord (e.g. by using the "Tools=>Script Manager") the following dialog is displayed. The user chooses the file he likes to import and may also able to change settings related to how the connection to OpenOffice.org should be established. Then a progressdialog will be displayed while in the background we try to connect with OpenOffice.org and let it load the file and pass the content back to KWord.

[[Image:kwordscriptingooimport.jpg]]

That way KWord is able to optional use the OpenOffice.org import-filters to import content from file formats like;

OpenDocument Text (*.odt), OpenDocument Text Template (*.ott), OpenOffice.org 1.0 Text Document (*.sxw), OpenOffice.org 1.0 Text Document Template (*.stw), Microsoft Word 95/97/2000/XP (*.doc), Microsoft Word 95/97/2000/XP Template (*.dot), Microsoft Word 2003 XML (*.xml), Rich Text Format (*.rtf), Text (*.txt), HTML Document (*.html *.htm), DocBook (*.xml), StarWriter 1.0 - 5.0 (*.sdw), StarWriter 3.0 - 5.0 Templates (*.vor), WordPerfect Document (*.wpd), Lotus WordPro Document (*.lwp), Ichitaro 8/9/10/11 (*.jtd), Ichitaro 8/9/10/11 Template (*.jtt), Hangul WP 97 (*.hwp), WPS 2000/Office 1.0 (*.wps), etc.

=== Export to a Text or HTML File ===

The python script [http://websvn.kde.org/trunk/koffice/kword/plugins/scripting/scripts/exportfile.py?view=markup exportfile.py] allows to export content to text- or html-files.

=== XML Viewer ===

The python script [http://websvn.kde.org/trunk/koffice/kword/plugins/scripting/scripts/xmlviewer.py?view=markup xmlviewer.py] to view the ISO OpenDocumentText XML representation of the current document displayed in KWord.

The XML Viewer does also allow to open the XML of the current document with an external application like KWrite or KXMLEditor. The "Compare..." button enables to compare the current XML with the XML of another ODT file.

[[Image:kwordxmlviewer.jpg]]

=== Document Structure Viewer ===

The [http://websvn.kde.org/trunk/koffice/kword/plugins/scripting/scripts/doctree.rb?view=markup doctree.rb] QtRuby script implement a document structur viewer.

The viewer displays the framesets, frames, documents and there objects as tree where each node may provide additional functionality like a collection of properties, text or styles.

[[Image:kwordscriptingdoctree.jpg]]

Talk:Projects/Summer of Code/2009/Ideas

2009-03-18T13:34:09Z

Zander: /* Work on GTK+ integration */

=== Google calender support for Akonadi/KOrganizer ===
I don't have sufficient knowledge of the codebase to write up a full blown proposal, but since GSoC is sponsored by google and for KDE, wouldn't this be a perfect project for it? I seen where akondi devs have talked about GCal support, but I haven't seen anything come of it. Full co-operation between kontact and Google apps would be a dream come true -- When I'm forced to use a non-linux box, I could just open up google and everything I need would be there -- from email to calendars to rss feeds. If only GCal supported "Todo"'s.... I suppose the only problem here is if this project would be doable in the constraints of GSoC.

Comment by krake:
This is already being worked on [http://websvn.kde.org/trunk/playground/pim/googledata/ here].

=== KMail HTML support ===

Shouldn't this SoC be based on porting the composer to be based off of WebKit/KHTML with contentEdtiable? It is the only way KMail is ever going to properly support rich email creation. The current composer is about 5 years behind the times in capabilities because it is based off of QRichTextEdit.

== Work on GTK+ application integration into KDE ==

Work on the GTK+ projects that use the Qt theming API and the KDE api for GTK/Gnome applications to improve integration of those gnome apps into the kde desktop.

This is done for: theming, file dialogs ,Open/Save file, OK/Cancel vs the gnome way Cancel/OK buttons.

Yes I know those are not part of official KDE4 but IMHO those are needed and many people use them. It would be very benefical to KDE to improve things in those projects and maybe even support them officially. And without KDE support those have no chance to be part of GSoC2009. If anyone says it should be done on GNOME/GTK+ front I do agree but sadly I don't think they care enough about KDE to do so.

http://www.kde-apps.org/content/show.php?content=36077
http://gtk-qt.ecs.soton.ac.uk/
In general it is about improving how GTK+ apps integrate when running in KDE4 desktop, so be aware that KDE might not have any mentors for this.

Talk:Projects/Summer of Code/2009/Ideas

2009-03-18T13:11:25Z

Zander: /* Work on GTK+ integration */

=== Google calender support for Akonadi/KOrganizer ===
I don't have sufficient knowledge of the codebase to write up a full blown proposal, but since GSoC is sponsored by google and for KDE, wouldn't this be a perfect project for it? I seen where akondi devs have talked about GCal support, but I haven't seen anything come of it. Full co-operation between kontact and Google apps would be a dream come true -- When I'm forced to use a non-linux box, I could just open up google and everything I need would be there -- from email to calendars to rss feeds. If only GCal supported "Todo"'s.... I suppose the only problem here is if this project would be doable in the constraints of GSoC.

Comment by krake:
This is already being worked on [http://websvn.kde.org/trunk/playground/pim/googledata/ here].

=== KMail HTML support ===

Shouldn't this SoC be based on porting the composer to be based off of WebKit/KHTML with contentEdtiable? It is the only way KMail is ever going to properly support rich email creation. The current composer is about 5 years behind the times in capabilities because it is based off of QRichTextEdit.

== Work on GTK+ integration ==

GNOME since Qt4.5 has a nice integration for Qt4 apps with QGTKStyle. This is done for: theming, file dialogs ,Open/Save file, OK/Cancel vs the gnome way Cancel/OK buttons. Similiar projects exist for KDE4: GTKQtEngines, Kgtk.
Yes I know those are not part of official KDE4 but IMHO those are needed and many people use them. It would be very benefical to KDE to improve things in those projects and maybe even support them officially. And without KDE support those have no chance to be part of GSoC2009. If anyone says it should be done on GNOME/GTK+ front I do agree but sadly I don't think they care enough about KDE to do so.

Just for consideration. <Ehm; these projects are part of Qt and quite complete already; whats the SoC project here? (TZndr)>

Development/Tutorials/KOffice Overview

2009-03-18T10:56:15Z

Zander: /* Inline Objects */

KOffice has gotten more and more configurable through plugins over time, which is a really good thing as 3rd party developers can extend KOffice using dedicated code for their purpose.

You will learn what functionality you can place in each plugin type so you can choose wisely. There is a general guide to writing plugins and each type has a tutorial showing how to create a new plugin of that type.

well, not all required info is there yet; but this is the idea :) Anyone want to help?

__TOC__

== Generic Information ==
Plugins are a design technique with a series of steps that will lead you to a loadable plugin. If you want to know more its is interresting to read an overview at [[Development/Tutorials/Generic KOffice Plugin Creation|Generic KOffice Plugin Creation]]

== Shapes ==
In KOffice shapes are document content. This content can be manipulated by the user and can be shown on screen or printed. The fact that they are plugins means that a new content types can be added to documents by just installing the plugin and starting your favorite KOffice application.
To get a feel for what a shape is, here are some examples of existing shapes, sometimes referred to as Flake shapes because shapes are one of the two main parts of the Flake library.

We have a PathShape which is a generic vector shape capable of showing and printing any sort of vector art like SVG or EPS vector graphics.

There is a Text plugin that is capable of showing marked up text with a huge feature set including HTML capabilities and a big part of the more extensive OpenDocument format.

KSpread exports a tableShape, to allow a spread-sheet table to be embedded in other KOffice applications.

API docs start at; [http://www.koffice.org/developer/apidocs/libs-flake/classKoShapeRegistry.html KoShapeRegistry]

The tutorial on how to write your own shape plugins can be found at [[Development/Tutorials/Write a Flake Plugin|Write a Flake Plugin]]

== Tools ==

A tool is a plugin that handles user input and can manipulate either the general application data, or can manipulate a specific shape.
All user input mouse and keyboard events that are send to the document area (canvas), will be passed to the active tool. The active tool can use them to, for example, move shapes around or rotate them. If you combine a tool with a shape plugin you can make the tool manipulate the data of the shape. A good example is the text tool which is bundled with the text shape. The text tool takes all keyboard events and thereby lets the user type text in the text shape.

This gives a clear separation of control and content. The shape holds the content and a tool is required to control that content.

In general there are two types of Tools;
* generic tools that are not associated with a shape plugin. Its rare that you will create such plugins, though we still need a 'measure' tool that falls in that category.
* bundled tools that come with a specific flake shape and is made to manipulate that shapes data.

API docs start at; [http://www.koffice.org/developer/apidocs/libs-flake/classKoToolRegistry.html KoToolRegistry]

The tutorial on how to write your own shape plugins can be found at [[Development/Tutorials/Write a Flake Plugin|Write a Flake Plugin]]

== Dockers ==

Plugins that provide a docker are basically plugins that provide a graphical user interface element for KOffice applications. In KOffice2 the focus on toolbars and dialogs will be less as they have been proven to be confusing to users because they clutter the interface.
Instead the focus is shifted to widgets that can be docked along the sides of a document window but also moved to be a separate window. The real change is that, unlike dialogs, they don't have an 'Ok' button but instead change the content life and immediately.
Examples of dockers are; the toolbox, the shape selector and the tool-options but also the color selector.

API docs start at; [http://www.koffice.org/developer/apidocs/libs/classKoDockRegistry.html KoDockRegistry]

Within KOffice dockers could also be written in a scripting language like Python or Ruby. The [[Development/Tutorials/KSpread_Scripting#Scripting_Docker_Widgets|KSpread Scripting Docker]] tutorial shows how it was done within KSpread.

=== Considerations ===
Dockers should never be passed a document or a view in the constructor. The reasons for that is simple; the lifetime of the docker is longer then the lifetime of the document and also of the view.

The proper way to do this is to let the application tell you there is a new document or a new image, etc. And listen on that.
This involves a couple of steps;
* The application should use the KoCanvasResourceProvider to put content on. Like the current layer, the current document etc.
* The docker should (also) inherit from KoCanvasObserver which means it will get notified when its canvas changes.
* Using the KoCanvasBase received from the KoCanvasObserver it can fetch the document from the KoCanvasResourceProvider. It can also connect to the provider to be informed about any changes.

An extra tip is to use the KoCanvasResource::DocumentIsLoading boolean, dockers should listen to it to avoid doing work while the document is loading.

== Colorspaces ==

== File Filters ==

== Text Plugins ==

The text component used in all KOffice applications has a set of plugins itself. These plugins allow the possibility to enhance the content as well as allow to enhance the editing experience. Use Inline object plugins to write content such as inline variables and bookmarks. Use Text Editing plugins to be able to replace the text a user types while he types it. For example for autocorrection.

=== Inline Objects ===

The plugins of this type effectively become a character in the text document. What this means is that a user can insert an inline object and the plugin can decide the size and content of the character inserted.
A good example of inline objects are variables. A variable can have a name and a value and altering the value of a variable will then change the value in the text all over the document. This is done by an inline object that shows the full text of the variable, but in the document it behaves as it is one big character that can't be split over lines or otherwise edited.

An inline object does not have to have content, it can just be a placeholder as well. Which makes it ideal for things like in-text comments/annotations and Bookmarks.

API docs start at; [http://www.koffice.org/developer/apidocs/libs-kotext/classKoInlineObjectRegistry.html KoInlineObjectRegistry]

=== Text Editing ===

The text editing plugins are all about handling user input while (s)he is editing the text. A plugin can do near everything with the typed text, including altering it and adding markup.
The plugin gives events when a word and when a paragraph has been finished. Which is ideal for autocorrection and autoreplacement of text.

Examples of usages of this plugin type are; a word count in a docker updated continuesly, auto correction of text, replacing formatted text with calculated values or custom shape plugins.

API docs start at; [http://www.koffice.org/developer/apidocs/libs-kotext/classKoTextEditingRegistry.html KoTextEditingRegistry]

== Krita's plugins ==
* filters (effects)
* paintop (plugin that are in charge of painting when the user uses a drawing tool)
* viewplugin (aka misc)
See [http://docs.kde.org/development/en/koffice/krita/developers-plugins.html Krita's handbook]

Development/Tutorials/KOffice Overview

2009-03-18T10:14:42Z

Zander: /* Inline Objects */

KOffice has gotten more and more configurable through plugins over time, which is a really good thing as 3rd party developers can extend KOffice using dedicated code for their purpose.

You will learn what functionality you can place in each plugin type so you can choose wisely. There is a general guide to writing plugins and each type has a tutorial showing how to create a new plugin of that type.

well, not all required info is there yet; but this is the idea :) Anyone want to help?

__TOC__

== Generic Information ==
Plugins are a design technique with a series of steps that will lead you to a loadable plugin. If you want to know more its is interresting to read an overview at [[Development/Tutorials/Generic KOffice Plugin Creation|Generic KOffice Plugin Creation]]

== Shapes ==
In KOffice shapes are document content. This content can be manipulated by the user and can be shown on screen or printed. The fact that they are plugins means that a new content types can be added to documents by just installing the plugin and starting your favorite KOffice application.
To get a feel for what a shape is, here are some examples of existing shapes, sometimes referred to as Flake shapes because shapes are one of the two main parts of the Flake library.

We have a PathShape which is a generic vector shape capable of showing and printing any sort of vector art like SVG or EPS vector graphics.

There is a Text plugin that is capable of showing marked up text with a huge feature set including HTML capabilities and a big part of the more extensive OpenDocument format.

KSpread exports a tableShape, to allow a spread-sheet table to be embedded in other KOffice applications.

API docs start at; [http://www.koffice.org/developer/apidocs/libs-flake/classKoShapeRegistry.html KoShapeRegistry]

The tutorial on how to write your own shape plugins can be found at [[Development/Tutorials/Write a Flake Plugin|Write a Flake Plugin]]

== Tools ==

A tool is a plugin that handles user input and can manipulate either the general application data, or can manipulate a specific shape.
All user input mouse and keyboard events that are send to the document area (canvas), will be passed to the active tool. The active tool can use them to, for example, move shapes around or rotate them. If you combine a tool with a shape plugin you can make the tool manipulate the data of the shape. A good example is the text tool which is bundled with the text shape. The text tool takes all keyboard events and thereby lets the user type text in the text shape.

This gives a clear separation of control and content. The shape holds the content and a tool is required to control that content.

In general there are two types of Tools;
* generic tools that are not associated with a shape plugin. Its rare that you will create such plugins, though we still need a 'measure' tool that falls in that category.
* bundled tools that come with a specific flake shape and is made to manipulate that shapes data.

API docs start at; [http://www.koffice.org/developer/apidocs/libs-flake/classKoToolRegistry.html KoToolRegistry]

The tutorial on how to write your own shape plugins can be found at [[Development/Tutorials/Write a Flake Plugin|Write a Flake Plugin]]

== Dockers ==

Plugins that provide a docker are basically plugins that provide a graphical user interface element for KOffice applications. In KOffice2 the focus on toolbars and dialogs will be less as they have been proven to be confusing to users because they clutter the interface.
Instead the focus is shifted to widgets that can be docked along the sides of a document window but also moved to be a separate window. The real change is that, unlike dialogs, they don't have an 'Ok' button but instead change the content life and immediately.
Examples of dockers are; the toolbox, the shape selector and the tool-options but also the color selector.

API docs start at; [http://www.koffice.org/developer/apidocs/libs/classKoDockRegistry.html KoDockRegistry]

Within KOffice dockers could also be written in a scripting language like Python or Ruby. The [[Development/Tutorials/KSpread_Scripting#Scripting_Docker_Widgets|KSpread Scripting Docker]] tutorial shows how it was done within KSpread.

=== Considerations ===
Dockers should never be passed a document or a view in the constructor. The reasons for that is simple; the lifetime of the docker is longer then the lifetime of the document and also of the view.

The proper way to do this is to let the application tell you there is a new document or a new image, etc. And listen on that.
This involves a couple of steps;
* The application should use the KoCanvasResourceProvider to put content on. Like the current layer, the current document etc.
* The docker should (also) inherit from KoCanvasObserver which means it will get notified when its canvas changes.
* Using the KoCanvasBase received from the KoCanvasObserver it can fetch the document from the KoCanvasResourceProvider. It can also connect to the provider to be informed about any changes.

An extra tip is to use the KoCanvasResource::DocumentIsLoading boolean, dockers should listen to it to avoid doing work while the document is loading.

== Colorspaces ==

== File Filters ==

== Text Plugins ==

The text component used in all KOffice applications has a set of plugins itself. These plugins allow the possibility to enhance the content as well as allow to enhance the editing experience. Use Inline object plugins to write content such as inline variables and bookmarks. Use Text Editing plugins to be able to replace the text a user types while he types it. For example for autocorrection.

=== Inline Objects ===

The plugins of this type effectively become a character in the text document. What this means is that a user can insert an inline object and the plugin can decide the size and content of the character inserted.
A good example of inline objects are variables. A variable can have a name and a value and altering the value of a variable will then change the value in the text all over the document. This is done by an inline object that shows the full text of the variable, but in the document it behaves as it is one big character that can't be split over lines or otherwise edited.

An inline object does not have to have content, it can just be a placeholder as well. Which makes it ideal for things like in-text comments/annotations and Bookmarks.

API docs start at; [http://www.koffice.org/developer/apidocs/libs-kotext/classKoVariableRegistry.html KoInlineObjectRegistry]

=== Text Editing ===

The text editing plugins are all about handling user input while (s)he is editing the text. A plugin can do near everything with the typed text, including altering it and adding markup.
The plugin gives events when a word and when a paragraph has been finished. Which is ideal for autocorrection and autoreplacement of text.

Examples of usages of this plugin type are; a word count in a docker updated continuesly, auto correction of text, replacing formatted text with calculated values or custom shape plugins.

API docs start at; [http://www.koffice.org/developer/apidocs/libs-kotext/classKoTextEditingRegistry.html KoTextEditingRegistry]

== Krita's plugins ==
* filters (effects)
* paintop (plugin that are in charge of painting when the user uses a drawing tool)
* viewplugin (aka misc)
See [http://docs.kde.org/development/en/koffice/krita/developers-plugins.html Krita's handbook]

Development/Tutorials/KOffice Overview

2009-03-18T10:13:22Z

Zander: /* Text Editing */

KOffice has gotten more and more configurable through plugins over time, which is a really good thing as 3rd party developers can extend KOffice using dedicated code for their purpose.

You will learn what functionality you can place in each plugin type so you can choose wisely. There is a general guide to writing plugins and each type has a tutorial showing how to create a new plugin of that type.

well, not all required info is there yet; but this is the idea :) Anyone want to help?

__TOC__

== Generic Information ==
Plugins are a design technique with a series of steps that will lead you to a loadable plugin. If you want to know more its is interresting to read an overview at [[Development/Tutorials/Generic KOffice Plugin Creation|Generic KOffice Plugin Creation]]

== Shapes ==
In KOffice shapes are document content. This content can be manipulated by the user and can be shown on screen or printed. The fact that they are plugins means that a new content types can be added to documents by just installing the plugin and starting your favorite KOffice application.
To get a feel for what a shape is, here are some examples of existing shapes, sometimes referred to as Flake shapes because shapes are one of the two main parts of the Flake library.

We have a PathShape which is a generic vector shape capable of showing and printing any sort of vector art like SVG or EPS vector graphics.

There is a Text plugin that is capable of showing marked up text with a huge feature set including HTML capabilities and a big part of the more extensive OpenDocument format.

KSpread exports a tableShape, to allow a spread-sheet table to be embedded in other KOffice applications.

API docs start at; [http://www.koffice.org/developer/apidocs/libs-flake/classKoShapeRegistry.html KoShapeRegistry]

The tutorial on how to write your own shape plugins can be found at [[Development/Tutorials/Write a Flake Plugin|Write a Flake Plugin]]

== Tools ==

A tool is a plugin that handles user input and can manipulate either the general application data, or can manipulate a specific shape.
All user input mouse and keyboard events that are send to the document area (canvas), will be passed to the active tool. The active tool can use them to, for example, move shapes around or rotate them. If you combine a tool with a shape plugin you can make the tool manipulate the data of the shape. A good example is the text tool which is bundled with the text shape. The text tool takes all keyboard events and thereby lets the user type text in the text shape.

This gives a clear separation of control and content. The shape holds the content and a tool is required to control that content.

In general there are two types of Tools;
* generic tools that are not associated with a shape plugin. Its rare that you will create such plugins, though we still need a 'measure' tool that falls in that category.
* bundled tools that come with a specific flake shape and is made to manipulate that shapes data.

API docs start at; [http://www.koffice.org/developer/apidocs/libs-flake/classKoToolRegistry.html KoToolRegistry]

The tutorial on how to write your own shape plugins can be found at [[Development/Tutorials/Write a Flake Plugin|Write a Flake Plugin]]

== Dockers ==

Plugins that provide a docker are basically plugins that provide a graphical user interface element for KOffice applications. In KOffice2 the focus on toolbars and dialogs will be less as they have been proven to be confusing to users because they clutter the interface.
Instead the focus is shifted to widgets that can be docked along the sides of a document window but also moved to be a separate window. The real change is that, unlike dialogs, they don't have an 'Ok' button but instead change the content life and immediately.
Examples of dockers are; the toolbox, the shape selector and the tool-options but also the color selector.

API docs start at; [http://www.koffice.org/developer/apidocs/libs/classKoDockRegistry.html KoDockRegistry]

Within KOffice dockers could also be written in a scripting language like Python or Ruby. The [[Development/Tutorials/KSpread_Scripting#Scripting_Docker_Widgets|KSpread Scripting Docker]] tutorial shows how it was done within KSpread.

=== Considerations ===
Dockers should never be passed a document or a view in the constructor. The reasons for that is simple; the lifetime of the docker is longer then the lifetime of the document and also of the view.

The proper way to do this is to let the application tell you there is a new document or a new image, etc. And listen on that.
This involves a couple of steps;
* The application should use the KoCanvasResourceProvider to put content on. Like the current layer, the current document etc.
* The docker should (also) inherit from KoCanvasObserver which means it will get notified when its canvas changes.
* Using the KoCanvasBase received from the KoCanvasObserver it can fetch the document from the KoCanvasResourceProvider. It can also connect to the provider to be informed about any changes.

An extra tip is to use the KoCanvasResource::DocumentIsLoading boolean, dockers should listen to it to avoid doing work while the document is loading.

== Colorspaces ==

== File Filters ==

== Text Plugins ==

The text component used in all KOffice applications has a set of plugins itself. These plugins allow the possibility to enhance the content as well as allow to enhance the editing experience. Use Inline object plugins to write content such as inline variables and bookmarks. Use Text Editing plugins to be able to replace the text a user types while he types it. For example for autocorrection.

=== Inline Objects ===

The plugins of this type effectively become a character in the text document. What this means is that a user can insert an inline object and the plugin can decide the size and content of the character inserted.
A good example of inline objects are variables. A variable can have a name and a value and altering the value of a variable will then change the value in the text all over the document. This is done by an inline object that shows the full text of the variable, but in the document it behaves as it is one big character that can't be split over lines or otherwise edited.

An inline object does not have to have content, it can just be a placeholder as well. Which makes it ideal for things like in-text comments/annotations and Bookmarks.

API docs start at; [http://www.koffice.org/developer/apidocs/libs/classKoInlineObjectRegistry.html KoInlineObjectRegistry]

=== Text Editing ===

The text editing plugins are all about handling user input while (s)he is editing the text. A plugin can do near everything with the typed text, including altering it and adding markup.
The plugin gives events when a word and when a paragraph has been finished. Which is ideal for autocorrection and autoreplacement of text.

Examples of usages of this plugin type are; a word count in a docker updated continuesly, auto correction of text, replacing formatted text with calculated values or custom shape plugins.

API docs start at; [http://www.koffice.org/developer/apidocs/libs-kotext/classKoTextEditingRegistry.html KoTextEditingRegistry]

== Krita's plugins ==
* filters (effects)
* paintop (plugin that are in charge of painting when the user uses a drawing tool)
* viewplugin (aka misc)
See [http://docs.kde.org/development/en/koffice/krita/developers-plugins.html Krita's handbook]

Projects/Summer of Code/2009/Ideas

2009-02-25T22:09:28Z

Zander: /* Project: Improvments in KMail's HTML support */

== Guidelines ==
===Information for Students===

These ideas were contributed by our developers and users. They are sometimes vague or incomplete. If you wish to submit a proposal based on these ideas, you may wish to contact the developers and find out more about the particular suggestion you're looking at.

Being accepted as a Google Summer of Code student is quite competitive. Accepted students typically have thoroughly researched the technologies of their proposed project and have been in frequent contact with potential mentors. Simply copying and pasting an idea here will not work. On the other hand, creating a completely new idea without first consulting potential mentors is unlikely to work out.

When writing your proposal or asking for help from the general KDE community don't assume people are familiar with the ideas here. KDE is really big!

If there is no specific contact given you can ask questions on the general KDE development list kde-devel@kde.org. See [http://www.kde.org/mailinglists/ the KDE mailing lists page] for information on available mailing lists and how to subscribe.

===Adding a Proposal===
When adding an idea to this section, please try to include the following data:
:* if the application is not widely known, a description of what it does and where its code lives
:* a brief explanation
:* the expected results
:* pre-requisites for working on your project
:* if applicable, links to more information or discussions
:* mailing list or IRC channel for your application/library/module
:* your name and email address for contact (if you're willing to be a mentor)

If you are not a developer but have a good idea for a proposal, get in contact with relevant developers first.
==Ideas==
===Plasma===
[http://plasma.kde.org Website] - [https://mail.kde.org/mailman/listinfo/panel-dev Mailing list] - IRC channel: #plasma on Freenode.

====Project: Network Enabling Plasma::Service====
'''Brief explanation:'''
The Service should be able to parse WSDL files and let Plasmoids connect to the described Webservices as well as optionally announce itself to the local network over uPnp and/or zeroconf. Finally, a Service that announces itself and can send a widget over the wire to another Plasma instance would complete this project.

====Project: Simple Media Center components====
'''Brief explanation:'''
Plasma could offer a Media center mode, where features a really simple ui to browse media files and plasmoids that shows the actual media. All should be operable with mouse, keyboard or a simple remote control. the work could consist in building the whole thing or just writing a plasmoid able to browse media files, that is the most important missing part.
Mockups for it by Nuno Pinheiro can be seen [http://img213.imageshack.us/img213/3200/image3231picturefz5.png here] and [http://img26.imageshack.us/img26/3407/image323musicoloectionck2.png here]

'''Expected results:'''
An applet to browse and thumbnail media files, like the first mockup and control the actual media viewing applets, like the media player applet or the picture frame applet. At this stage the functionality will be really minimum

'''Knowledge prerequisite:'''
Knowledge of C++ and some familiarity with Qt especially QGraphicsView related classes.

'''Mentor:'''
Marco Martin (notmart a gmail dot org), or other Plasma developers. Contact at plasma-devel@kde.org or #plasma on freenode.

====Project: Plasmate====
'''Brief explanation:'''
PlasMate is an application that gives people a way to start creating scripted plasmoids without worrying about anything except making their bits. It hides the whole metadata.desktop thing, the package layout details, making a Plasmoid package (aka "zipping up the directory"), uploading content and version control system.

'''Expected results:'''
Working application that one can do the tasks described above, making it easy to create and distribute a scripted plasmoid.

'''Knowledge prerequisite:'''
Knowledge of C++ and familiarity with Qt (QWidgets and QGraphicsView related classes).

'''Mentor:'''
Artur Duque de Souza (morpheuz a gmail dot org), or other Plasma developers. Contact at plasma-devel@kde.org or #plasma on freenode.

====Project: Qt Kinetic + Plasma====
'''Brief explanation:'''
A layer over Qt Kinetic to provide a standardized set of "out of the box"
animations and bring them into libplasma. The work will be done with the Plasma developers to make this API as efficient as possible. The work will be based on Kinetic, the next framework for animations in Qt.

'''Expected results:'''
We can kill Plasma::Animator class. The goal is to bring fancy effects/animations in Plasma to have one of the best desktop ever.

'''Knowledge prerequisite:'''
Knowledge of C++, familiarity with QGraphicsView related classes and some familiarity with animations bits.

'''Mentor:'''
Alexis Ménard (alexis.menard at nokia dot com) or Artur Duque de Souza (morpheuz a gmail dot org). Contact at plasma-devel@kde.org or #plasma on freenode.

====Project: Eduactional layout====
'''Brief explanation:'''
A set of Containments and Plasmoids specifically designed for primary school
students.

'''Expected results:'''
A simplified panel containment that contains basic launchers and user feedback
for the student, a widget that allows teachers to provide context-specific
sets of applications and documents to the student (context being a combination
of the student logged in and the current class subject), a widget that
provides some basic teacher->student communication and status (e.g. what the
current assignment is, how long the student has been logged in, etc) and
optionally some widgets that work with KDE edu apps.

'''Knowledge prerequisite:'''
Knowledge of C++.

'''Mentor:'''
Plasma team. Contact at plasma-devel@kde.org or #plasma on freenode.

====Project: Desktop dock====
'''Brief explanation:'''
A MacOS style dock containment.

'''Expected results:'''
A containment that provides a similar user experience to the MacOS dock:
application launchers that are also task bar entries when the application is
active and a separate area for widgets such as the trash, battery, etc.

'''Knowledge prerequisite:'''
Knowledge of C++.

'''Mentor:'''
Plasma team. Contact at plasma-devel@kde.org or #plasma on freenode.

====Project: Kdm frontend using plasma====
'''Brief explanation:'''
A log-in screen layout manager for KDM that uses libplasma.

'''Expected results:'''
A KDM screen that is rendered completely using Plasma. This means both using
libplasma in KDM for the log in screen as well as writing Plasmoids for
entering the user name and password, listing users, session switching, etc.
Some of these widgets already exist for the desktop shell, so in some cases
this will be simply integrating existing Plasmoids, but in other cases will
mean writing new ones from the ground up.

'''Knowledge prerequisite:'''
Knowledge of C++.

'''Mentor:'''
Plasma team. Contact at plasma-devel@kde.org or #plasma on freenode.

====Project: Raptor====
'''Brief explanation:'''
Raptor aims to deliver a new kind of launch menu system for KDE. It is designed with usability and beauty in mind.
Raptor-Menu does not try to be the final answer to the menu question, instead aspires to be the best answer we can give, merging many ideas form modern desktop launch menus.

'''Expected results:'''
http://www.raptor-menu.org/

'''Knowledge prerequisite:'''
Knowledge of C++.

'''Mentor:'''
Plasma team. Contact at plasma-devel@kde.org or #plasma on freenode.

====Project: New Widget Explorer====
'''Brief explanation:'''
A new widget explorer that supports both our own widgets as well as others
more seamlessly.

'''Expected results:'''
A usable and pretty browser for widgets that allows a user to see an icon or
snapshot of the widget, select a widget to be placed in a containment, search
for a widget based on name/description, sort the widgets into categories, rate
widgets and provide ways to launch the online browsers and installers for both
native Plasmoids as well as third party tools such as Google Gadgets (which is
already supported in the Package class). All the required support
functionality already exists, this project is really about creating a
beautiful and dynamic user interface for looking through a widget catalog that
looks "Plasma".

'''Knowledge prerequisite:'''
Knowledge of C++.

'''Mentor:'''
Plasma team. Contact at plasma-devel@kde.org or #plasma on freenode.

====Project: D-Bus Interface====
'''Brief explanation:'''
A comprehensive set of D-Bus interfaces for the plasma-desktop Plasma shell.

'''Expected results:'''
The D-Bus interface must provide access to the Corona (DestkopCorona class),
which in turn will list all existing Containments and allow Containments to be
added, removed, saved, etc.

A D-Bus interface for each existing Containment will be made available as
well, which will provide a standard set of tools including listing, adding and
removing widgets as well as positioning and sizing for PanelContaiments. Ways
to control the wallpaper, if any, will also be provided in the per-Containment
D-Bus interface.

In turn, a D-Bus interface for each widget representing its available
contextual actions will be provided dynamically upon request.

Finally, the application D-Bus interface for things such as locking/unlocking
widgets will be designed and implemented.

The result will be a Plasma that is fully accessible via D-Bus.

'''Knowledge prerequisite:'''
Knowledge of C++.

'''Mentor:'''
Plasma team. Contact at plasma-devel@kde.org or #plasma on freenode.

====Project: Security====
'''Brief explanation:'''
A set of methods to define the existing security state of the Plasma
application, the security requirements of individual widgets, mechanisms to
respect those two sets of information and cryptographic signing of Plasmoid
packages.

'''Expected results:'''
A set of functionality descriptions will be enumerated (e.g. "Network access",
"Local file system access", etc.). Individual widgets will advertise which of
these functionality sets they require.

The plasma-overlay shell (used on the screensaver) will have code added to it
to respect these settings and not run widgets that advertise they need things
that aren't safe to provide on a screensaver (due to it being locked to
prevent others from accessing the system).

The plasma-desktop shell will gain the ability to be put into various lock down
states which will map to different sets of functionality. Part of this project
will be enumerate the various states, but that list must include "only load
trusted widgets", "no external access", "no local file system access".

The JavaScript engine will provide methods for each of the functionality sets
(e.g. a set of functions to access local files) which will be exported or not
based on the current Security state. This implies providing a security state
to the Corona which can then be passed on down to Applets and AppletScripts.

Finally, GPG signing of Plasmoid packages will be implemented along with a way
of checking the validity of these at runtime.

'''Knowledge prerequisite:'''
Knowledge of C++ and some experience with security.

'''Mentor:'''
Plasma team. Contact at plasma-devel@kde.org or #plasma on freenode.

====Project: Telepathy Integration====

See [[#Project:_Telepathy_Plasma_Integration| here]] for more project details.

===Amarok===
A KDE music manager and player.

[http://amarok.kde.org Website] - [https://mail.kde.org/mailman/listinfo/amarok Mailing list] - IRC channel: #amarok on Freenode.

====Project: DLNA/UPnP Support====
'''Brief explanation:'''
Using the UPnP protocol users can, for example, share music from their Vista computer to a PS3. Amarok lacks any sort of UPnP support. Being able to act as a client or possibly a UPnP media server would be useful. In addition to that controlling a UPnP Media Renderer from within Amarok is possible with framework support.

The [http://coherence.beebits.net/ Coherence server] would likely be used since it is also intended to be used by a KIO slave.

'''Expected results:'''
*Using the Amarok Collection framework, create a plugin which allows Amarok to browse, search and play music off of a UPnP share. Playing music may use the UPnP KIO-slave, but more advanced functionality requires Amarok to handle this directly.
*Allow Amarok to share it's collection with other devices or control other devices via UPnP. This is secondary priority but it may be pretty easy with Coherence.
*Control UPnP Media Renderers (DMR: Digital Media Renderer device class in DLNA) from within Amarok.

'''Material Prerequisite:''' Some UPnP devices or computers to test with. Good excuse to buy a PS3. If you live in Europe a Philips Streamium DMR can be borrowed.

'''Knowledge Prerequisite:''' C++ and Qt. Coherence uses Python and D-Bus but doesn't need to be hacked on in the scope of this project.

And of course, understanding of UPnP networking and devices wouldn't hurt!

'''Mentor:''' Stecchino (bart.cerneels at kde dot org)
----

====Project: New meta-applets for the Context View====
'''Brief Explanation:'''
The Context View (CV) is currently used to display multiple applets that expose various information. However, due to the fact that each applet displays a certain type of information from one data source, there is significant amount of wasted space, and it is hard to show much more than 3 different pieces of data at once.

Meta-Applets are large applets that integrate date from multiple data sources in order to display more semantically related information coherently and efficiently. This could mean, for example, an applet that brings together lyrics, artist info, upcoming concerts, and related songs/artists.

More info is available here [http://amarok.kde.org/wiki/Proposals/More_Contexual_Information on the amarok wiki]

'''Expected Results:'''
Two or three (to be discussed with mentor in application writing process) applets that elegantly execute the ideas discussed above.

'''Knowledge prerequisite:'''
Knowledge of C++ is required, and some familiarity with Qt is helpful (especially QGraphicsView) but not necessary.

'''Mentor:'''
Leo Franchi (lfranchi AAAT kde DT org), or other Amarok developers. Contact at amarok@kde.org or #amarok on freenode.

----
====Project: Code regression test suite, implemented with QtScript ====
'''Brief explanation:'''
Amarok currently has no automatic code regression testing ("unit testing") in place at all. We very much need such a system in place (for as many components as possible), as we sometimes accidentally break certain components of the program by extending the code.

'''Expected results:'''
Code regression test suite for Amarok 2, implemented as one "Amarok-Script" (JavaScript), and internally split into multiple separate files and components, so that it would be possible to run arbitray tests (or the full suite) with very little effort, and no compiling, at any time. A requirement would also be testing of the collection scanning code (with test case collections), and testing of GUI correctness with the QTest library.

Also see:
http://amarok.kde.org/wiki/Development/Scripting_HowTo_2.0

A plus would be the generation of suitable statistics (possibly with document export), and possibly a visual representation of the data.

'''Knowledge Prerequisite:'''
C++, Qt, KDE-Libs, QtScript (JavaScript), SVN, git, code testing.

'''Mentor:'''
Contact the amarok mailing list or ask in our IRC channel #amarok
----

====Project: Multilevel playlist sorting and sorting GUI ====
'''Brief explanation:'''
In Amarok 2.1, the layout of the playlist will be very configurable, being able to show as much or as little information about each track as each user might wish. Currently however, it is lacking an advanced system for sorting in the playlist, something that many users comming from Amarok 1 are missing. While simple sorting is relatively easy to do (and has already been partly implemented) we would like to aim a bit higher with Amarok 2.

'''Expected results:'''
A proxy model allowing the tracks in the playlist to be sorted using an arbitrary number of "layered" sort criteria. for instance, a sort setup could be "artist-album-tracknumber" This would sort all tracks by artist, then sort the tracks from each artist by album, and finally the tracks from each album based on track number. Once this model is working, a GUI is needed for making this functionality easilly avaialble to the user. Ideally this gui should tie in well with the playlist layout and search/filter stuff. Also, all track navigators (the classes that determines the order of playback, such as normal, random, random album and so on) need to be updated to use and work correctly with the new proxy model.

'''Knowledge Prerequisite:'''
C++, Qt, KDE-Libs, SVN/git.

'''Mentor:'''
Nikolaj Hald Nielsen <nhnFreespirit@gmail.com> or contact the amarok mailing list or ask in our IRC channel #amarok
----

====Project: Playlist and Collection synchronization====
'''Brief explanation:'''
Mediadevices and services can add tracks and playlists to Amarok. Synchronization would automatically copy over tracks between the main Amarok Collection and devices or services or even between each other, either for a single playlist or the complete collection.
An algorithm needs to be implemented that does this automatically in a fast and efficient way with minimal intervention needed by the user.

'''Expected results:'''
Playlists set up on both the local collection and a portable mediaplayer will get synchronized the moment the player is connected.

'''Knowledge Prerequisite:'''
C++, Qt, KDE-Libs, SVN/git.

'''Mentor:'''
Bart Cerneels <bart.cerneels at kde dot org> or contact the amarok mailing list or ask in our IRC channel #amarok

====Project: CD Ripping====
'''Brief explanation:'''
Many users (eg, my girlfriend) expect their music player to rip CDs. Amarok has never had this feture. With [http://solid.kde.org Solid] it should be fairly easy to create a non-intrusive UI.

'''Expected results:'''
An easy to use but unintrusive interface in Amarok to rip audio CDs into a variety of audio formats. Perhaps work with the media device developers to design a UI that will react to events such as "user inserts audio CD" or "user connects their iPod."

'''Material Prerequisite:'''
Some audio CDs. You remember those shiny things you used to get at record stores?

'''Knowledge Prerequisite:'''
C++, Qt, kdelibs. Knowledge of how CD ripping and audio encoding works in Linux would be useful.

'''Mentor:'''
Potentially one of several. Contact the Amarok mailing list or ask in our IRC channel #amarok

===Phonon===
Abstraction library for sound and video support. Used by KDE notifications, Amarok, Dragon Player and Qt Software.

[http://phonon.kde.org Website] - [https://mail.kde.org/mailman/listinfo/phonon-backends Mailing list] - IRC channel: #phonon on Freenode.

====Project: Analyzer Support====
'''Brief explanation:'''
Applications such as Amarok and Dragon Player cannot have an analyzer or visualizations since they use Phonon which does not yet have the functionality to do it. The analyzer is the little bar graph thing which bounces around while music is playing. Users like it as its pretty and gives them a visual indication of their music playing.

'''Expected results:'''
As this project is working on extending a library, it has three parts: the Phonon library itself, a Phonon backend, and an application. The Phonon library would need the new API calls. At least phonon-xine and preferably 1 or 2 other Phonon backends must then implement the new API. An application like Amarok or Dragon Player should be used to demonstrate the use of the new API.

'''Knowledge Prerequisite:''' C++ and Qt. Experience with Xine or GStreamer is probably useful.

'''Mentor:''' Ian Monroe (contact on the [https://mail.kde.org/mailman/listinfo/amarok Amarok mailing list]) or possibly another Amarok or Phonon developer.
----
===Marble===
A desktop globe and map application. Also provides a map Qt Widget.

[http://edu.kde.org/marble/ Website] - [https://mail.kde.org/mailman/listinfo/marble-devel Mailing list]

====Project: Satellite navigation====
'''Brief explanation:'''
Satellite navigation devices have become widely used and the quality of openstreetmap data is becoming high, with some cities completely mapped already. Providing satellite navigation would be a useful desktop app for many as well as adding appeal for the use of KDE in embedded devices.

It also opens the possibility to bringing many of the free software ideals to interaction with the real world such as collaborative/social POIs.

'''Expected results:'''
The project would aim at getting a basic satellite navigation application running. The most basic features required would be getting the current location from a GPS device and providing route calculation to a destination.

The AndNav project (http://andnav.org) has already achieved something similar for Android so it could be a point of reference for how to use OpenStreetMap data to achieve this. A possible approach would be to use [http://developers.cloudmade.com/projects/show/vector-tiles vector tiles from Cloudmade].

'''Knowledge Prerequisite:''' C++ and Qt. Experience with GPS devices under linux would be beneficial. Knowing java may also be of benefit in order to study the AndNav implementation.

'''Mentor:''' I (Alan Jones, skyphyr using gmail) am willing to mentor, but not having any GPS or Marble experience there is most likely somebody far more suited to undertake this role.

Comment from a Marble Project guy: Alan, please get in touch with the Marble Project. Our mailing list is marble-devel@kde.org. We'd like to support this project if a student is willing to do it.

----

====Project: Add Time support to Marble====
'''Brief explanation:'''
Wouldn't it be great to be able to see the world at different times in Marble? Like having a slider which would give you the ability to browse through the time? Marble's internal datastructure is modelled after KML. But support for time-related tags is missing.

'''Expected results:'''
* Having a GUI on the map and as a QWidget based dialog which allows people to "slide" through time.
* Implementation of the KML [http://code.google.com/apis/kml/documentation/kmlreference.html#timeprimitive <TimePrimitive>] and [http://code.google.com/apis/kml/documentation/kmlreference.html#timespan <TimeSpan>] tag: Creating the KML-handler and needed data classes for the GeoData parser.
* Having a central "internal" clock which the current view would be based on.
* Porting existing features (like the starry sky and the sun shading) over to the new class design.

'''Knowledge Prerequisite:''' C++ and Qt. Knowledge about KML is not necessary but would be appreciated.

'''Mentor:''' Torsten Rahn / Patrick Spendrin.

----

===KDevelop===
KDE-based Integrated Development Environment, specializing in c++ support, but including a powerful generic framework (definition use chain) which makes it possible to relatively easily support multiple different languages.

[http://www.kdevelop.org Website] - [http://www.kdevelop.org/index.html?filename=mailinglist.html Mailing list] - IRC channel: #kdevelop on Freenode.

====Project: C++ Refactoring Support====
'''Brief explanation:'''
C++ support in KDevelop is already highly advanced, often equalling or surpassing what the user and compiler understand about the code. A few refactoring tools have been developed already, but they have been constructed in a crude fashion, generating code via string concatenation.

This project would aim to create a new system to implement refactoring tools, and to create, test and deploy several advanced refactoring tools for c++.

'''Expected results:'''
A library would be created to enable refactoring based on the c++ AST (abstract syntax tree). A reverse parser (AST to code) already exists, but classes would be created to allow programatic manipulation of an AST. Optionally this library would also cover a generic framework based on the duchain which would be re-usable by other languages and make refactoring plugins easier to develop and partially shareable between languages.

See the [http://api.kde.org/4.x-api/kdevplatform-apidocs/language/codegen/html/index.html Code Generation Design] documents for the initial plan for this project.

'''Knowledge Prerequisite:''' C++ and Qt. Experience with parsers would be a bonus.

'''Mentor:''' Hamish Rodda (Definition-Use chain code creator) rodda at kde/dot/org, possibly also David Nolden (DUChain guru)(to be confirmed)
----
=== KStars ===
KStars is a Desktop Planetarium for KDE. It displays a map of the sky and provides a lot of tools to learn astronomy, or to calculate and predict astronomical phenomena. See [[http://edu.kde.org/kstars|The KStars Homepage]] for more information.

==== Project: Community Integration for KStars ====
'''Project Information:''' KStars is a desktop planetarium program for KDE.

'''Brief explanation:''' Amateur Astronomy (which is one of the important use-cases of KStars) is typically done in communities. KStars permits users to save their own observing logs. It would be nicer if the user could share his observing logs with other users and see other observers' logs within KStars. It would also be nice if KStars had a map (using MarbleWidget) to display various Astronomy-related establishments (like amateur associations, observatories, research institutes). Another possible idea could be an observing report generator that would generate a report based on observing logs, and at the user's will, share it / post it on the internet.

'''Expected results:''' Implement some features that will make it easier for users to collaborate, as suggested above.

'''Knowledge Pre-Requisite:''' Required: C++. Prior knowledge of KIO_HTTP will help.

'''Mentor:''' Akarsh Simha <akarsh DOT simha AT kdemail DOT net>

==== Project: FITS Image Overlay on the sky map. ====

'''Project Information:''' KStars is a desktop planetarium program for KDE.

'''Brief explanation:''' It would be great if a FITS image could be overlayed on the sky map so that the field drawn by KStars could be compared with the field in the FITS image. This would be of great benefit to observational astronomers, astrophotographers and comet / asteroid observers. An extension would be to download a DSS image using KStars' already existing tool and map it onto the sky map. The support of shapes like ds9 region, annotations on the sky, etc. could also be added.

'''Expected results:''' Functionality to overlay a FITS image or a DSS image obtained through KStars on to the sky map.

'''Knowledge Pre-Requisite:''' Required: C++. Prior knowledge of the FITS format and cfitsio library will help.

'''Mentor:''' Akarsh Simha <akarsh DOT simha AT kdemail DOT net>

==== Project: Tools for Eclipses ====

'''Project Information:''' KStars is a desktop planetarium program for KDE. Currently, it can predict Solar Eclipses (using the Conjunctions tool), but cannot plot trajectory of shadows, or predict Lunar Eclipses.

'''Brief explanation:''' The project's primary goals are to include simulation and prediction (maybe using the existing Conjunction backend) of Lunar eclipses, and to create a tool to mark the trajectories of Solar and Lunar eclipse shadows on a map of the earth, including marking of totality, partial eclipse and annular eclipse. Something similar to this: [http://eclipse.gsfc.nasa.gov/SEmono/TSE2009/TSE2009iau/TSE2009-fig01.GIF]

'''Expected results:''' A complete set of tools to deal with eclipses.

'''Knowledge Pre-Requisite:''' C++

'''Mentor:''' Akarsh Simha <akarsh DOT simha AT kdemail DOT net>

==== Project: KStars: Prettyfication ====
'''Project Information:''' KStars is a desktop planetarium program for KDE. The display is interactive, but it could be made more beautiful.

'''Brief explanation:''' We often get good suggestions for making KStars look better. Choose any of the following ideas: realistic rendering of asteroids and comets (including tails!); texture-mapping of the sky (this would mostly allow a photorealistic Milky Way); texture-mapping of planets; realistic sky-lighting effects (i.e., sky is blue in the daytime, gets gradually darker and colorful at sunset). One could also think of using Qt-GL rendering optionally.

'''Expected results:''' Successful implementation of any of these ideas to make KStars more beautiful.

'''Knowledge Pre-Requisite:''' Required: C++.

'''Mentor:''' Akarsh Simha <akarsh DOT simha AT kdemail DOT net>

==== Project: Printable star charts ====
'''Project Information:''' KStars is a desktop planetarium program for KDE. It already has a print feature, but the printed chart could be much better.

'''Brief explanation:''' A printed star chart should at least include a legend explaining the symbols, and provide some information on the location of the user, the time and date, etc. The user would ideally be able to annotate the chart in various ways.

'''Expected results:''' Significant improvements to the printed star charts in KStars.

'''Knowledge Pre-Requisite:''' Basic programming skills, ability to quickly learn QPainter API.

'''Mentor:''' Akarsh Simha <akarsh DOT simha AT kdemail DOT net>

==== Project: Many Moons ====
'''Project Information:''' KStars is a desktop planetarium program for KDE. It currently includes Earth's moon and 4 of Jupiter's moons.

'''Brief explanation:''' Generalize the JupiterMoons class to encapsulate any planet's Moons. The project will require some research to identify a public source of orbital data for planetary moons, most likely from a NASA webpage.

'''Expected results:''' Implement moons for at least Mars, Jupiter, Saturn, and Pluto with the new system.

'''Knowledge Pre-Requisite:''' Required: C++. The project doesn't require much contact with Qt/KDE APIs, and the existing JupiterMoons class can be used as a template.

'''Mentor:''' Akarsh Simha <akarsh DOT simha AT kdemail DOT net>

==== Project: Support many catalogs ====
'''Project Information:''' KStars is a Desktop Planetarium for KDE. Currently KStars loads some star catalogs that are made available in a KStars native format.

'''Brief Explanation:''' KStars currently loads Tycho-2 and parts of USNO NOMAD catalog of stars. These catalogs are required to be in KStars' native format which uses the Hirearcheal Triangular Mesh to index regions in the sky. Popular star catalogs like USNO A organize stars and divide the sky into regions differently. Most users of astronomy software typically have one of these popular catalogs downloaded, and it would be great if KStars could support them somehow. While ability to read the non-native catalogs straight off is desirable, tools to convert these catalogs into KStars' native format would also help.

'''Expected Results:''' Implement support for at least the most popular catalogs like USNO-A2.0, Stellarium's Extra catalog, Cartes du Ciel's Tycho and Tycho-2 catalogs.

'''Knowledge Pre-Requisite:''' Required: C++. Ability to read documentation and quickly understand the existing code and ability to deal with binary files will help.

=== Kalzium ===

==== Project: Strigi integration ====

'''Project Information:'''
The goal of this project is to integrate Strigi as backend behind the periodic table and the glossary (and possible other elements).

'''Brief explanation:'''
The idea here is to have a GUI element that shows Strigi search results based on the element selected from the periodic table, or the item from the glossary, found on the users desktop. For element, this would include the elements name, and possible even the element symbol, if integration with last years Strigi-Chemistry GSoC project is achieved. For glossary items, a simple text search would suffice.

Another idea is to make it possible to querry like this: "Give me all molecules with a molecularweigth of 123u and at least one Carbon atom". For this we can use the [http://chem-file.sourceforge.net/ Chemical File Database] (or of course every other database, even those for [http://www.rcsb.org/pdb/home/home.do proteins].

'''Expected results:'''
* provide GUI for Strigi search results for an element selected in the periodic table
* provide GUI for Strigi search results for an glossary item

'''Knowledge Pre-Requisite:''' Required: C++, DBUS. Could be useful: Qt.

'''Mentor:''' Undecided.

----

==== Project: Kalzium beautification ====

'''Project Information:'''
Many parts of [http://edu.kde.org/kalzium Kalzium] could need a fresh up of the interface. For example, the main table should be written using Qt Model/View technique and for example use SVGs as a background. A first (uncomplete but working) code is already existing.

At the same time, many dialogs are not as beautiful as they could be. This project could also include the creation of a "simplified Kalzium" mode in which some parts of the feature set are hidden; this would be good for schools.

A third idea is to make more use of Plasma, for example improve the already written Plasmoids and/or extent Kalzium so that a Plasmoid could open a information dialog using Kalzium.

'''Expected results:'''
Depending on the chosen project for example a cleaned up codebase with an improved interface.

'''Knowledge Pre-Requisite:''' Required: C++, Qt, possible Plasma, Debug.

'''Mentor:''' Carsten Niehaus

==== Project: Molecular calculator ====

'''Project Information:'''
Kalzium already has a basic mass calculator for molecules (in the sidebar). The goal of this project would be to add full-blown widget that allows users to calculate masses of molecules, do calculations with them, calculate concentrations (mol/l, g/l..) of solutions...
ChemicalDataObject already has the needed data to achieve this, there's a parser for molecule formulas, so the project's goal is to make a nice GUI and of course write code that uses that data in the good way.

'''Expected results:'''
An easy-to-use (multi-tabbed?) window, where users can enter what they know (molecule name and number of grams...), pick what they want to know (number of mols).

'''Knowledge Pre-Requisite:''' Required: C++, Qt, basic knowledge of chemistry.

'''Mentor:''' Undecided.

=== KOffice ===
-----

'''Project:''' support for versioned OpenDocument files.

'''Explanation:''' The OpenDocument specification doesn't include support for multiple versions of the same document in a single file. But that feature is supported by OpenOffice.org. The objective for this Summer of Code is to add support for that versioning system in KOffice. Since KOffice shares the OpenDocument loading/saving code, it should be possible to add this support in every KOffice application in one Summer of Code.

'''Expected results:''' Being able to load a specific version of a file, and create/manage versions

'''Knowledge Pre-Requisite:''' C++, excellent english reading skills.
-----

'''Project:''' Add support for e-book formats to KOffice.

'''Brief explanation:''' Add a new export for one or more formats that are specifically tuned for e-book devices.

With the increased popularity of ebook readers there is going to be a need for tools to create ebook content. While most e-book devices can display PDF there are in fact a lot more formats in use. One such format is .epub, which allows reflowable content (unlike PDF). The format itself is based on XML and uses style sheets (CSS) to format content. There are few free software tools that can generate and manipulate this format and those that exist are restricted to command line.

Since most people creating content will most likely want to use an office suite or word processor to make documents it makes sense to add an export option for this format to KOffice.

'''Knowledge requisites:'''
* C++
* XML
* CSS

==== Flake ====
-----

'''Project:''' support missing ODF drawing shape feature

'''Explanation:''' KOffice can already load and save most of the shapes that ODF defines. Still a few features are missing especially text on shapes, but also caption, title, description and the measure shape.

'''Expected results:''' The project should implement the mentioned features and it should be possible to load, save and easily edit them

'''Knowledge Pre-Requisite:''' C++

==== KWord ====
-----

==== KPresenter ====
-----

'''Project:''' Powerpoint import.

'''Explanation:''' From some years ago another gSoc project implemented the basis for powerpoint import, but it was never finished. So there is a good basis to start from. From a quick look it seems like styles support is the thing missing most to complete the work, however a thorough analysis of what is there and what is not needs to be done. And then the actual work needs to be done too, obviously

==== Krita ====

-----

'''Project:''' New tile engine for Krita

'''Project information:''' Krita's current tile engine suffers from some limitations, like extensive locking. A new tile engine should offer some compelling features, like mipmapping, tile aging, in-memory compression, lock-free access of tiles, as efficient as possible undo information, pluggable backends (like png or tiff). See for a short summary http://wiki.koffice.org/index.php?title=Krita/Akademy_2007_Meeting#tile_backend.
'''Expected Results:''' an production-ready implementation having these features.

'''Knowledge Prerequisite:''' This is a difficult, ambitious project. Applicants should have a good knowledge of C++, data structures and be aware of existing literature on this subject and have a knowledge of graphics applications.

'''Project:''' Sketch-pad interface for Krita

'''Project Information:''' Krita is a large and complex application built around a sophisticated painting engine. The goal of this project is to create a new interface around the Krita engine, specialized for quick sketching.

'''Expected results:''' This project should implement a new interface around Krita, presenting the user a single-layer plus tracing paper interface with a single freehand sketching tool. Easy to use and graphic color and paint operation (brush, pencil, eraser etc.) interface elements must be designed and implemented.

'''Knowledge Pre-Requisite:''' C++

-----

'''Project:''' Shader filters and generators for Krita

'''Project Information:''' Some initial work has already been done to make it possible to write filters in the OpenGL shading language. This project should take that initial code as a basis and implement a fully functioning plugin for Krita that allows filters and shaders to be executed on images in any colorspace.

'''Expected results:''' The plugin should have a finished user interface and make it possible to experiment with shader filters in an interactive way. Example filters must be implemented.

'''Knowledge Pre-Requisite:''' C++, OpenGL.

-----

'''Project:''' Animation support

'''Project Information:''' There is no support at all in Krita for animated images such as GIF or MNG or for working with images in an animation context, such as textures or backgrounds in applications like Blender. The applicant should first investigate user needs and use cases and then implement support in the user interface and in the import/export filters.

'''Expected results:''' A user-friendly way of working with animated images (i.e., not by making each frame a layer), but e.g. a docker that shows the the animation running in thumbnail format. Import/export filters for relevant file formats.

'''Knowledge Pre-Requisite:''' C++

-----

'''Project:''' PSD and Gimp plugins

'''Project Information:''' Krita is powerful enough to handle nearly all that the Gimp and Photoshop are capable of saving. This project is about creating dedicated file import/export filters that can handle as much of these file formats as possible, possibly through the use of existing libraries.

'''Expected results:''' 4 plugins: psd import/export and xcf import/export. These plugins should be able to handle complex files in all supported colorspaces. Ideally the project would also deliver a library to convert PSD/XF to/from Open Raster files.

'''Knowledge Pre-Requisite:''' C++

-----

'''Project:''' Workspaces

'''Project Information:''' A workspace is a loadable package of settings that finetune Krita for a particular purpose. A workspace could contain additional plugins (like an image browser plugin for batch operations) and a subset of resources. Example workspaces could be batch-editing of images, editing of animation sequences or painting or sketching.

'''Expected results:''' the user interface and framework to make packages of plugins and resources that users can switch between. Also extra plugins to extend krita in areas like batch processing that do not exist yet.

'''Knowledge Pre-Requisite:''' C++, artistic workflow

-----

'''Project:''' Kipi and digikam plugins compatibility

'''Project Information:''' Kipi and digikam provide lots of interesting plugins for working with 8 and 16 bit RGBA images. It would be great to be able to re-use those plugins from within Krita.

'''Expected results:''' Two plugins that load kipi and digikam filters into two new menus in the filter menu. Code to convert Krita layers to the digikam image representation and back, taking care of icc profiles and other niceties.

'''Knowledge Pre-Requisite:''' C++, artistic workflow

==== Kivio ====
-----

'''Project:''' support for basic flowchart editing

'''Project Information:''' In KOffice 1.6 Kivio provided tools and stencils for editing flowcharts. Flake already provides the the building blocks: shapes, glue points and a connector shape. Goal of the project is to recreate old functionality based on flake.

'''Expected results:''' Import of the Kivio stencil format. A docker that allows to handle collections of stencils. Implementation of a connector tool, that can easily connect different shapes.

'''Knowledge Pre-Requisite:''' C++

===KDE PIM===
KDE PIM is the interest group working on applications related to personal information management, e.g. contacts, calendar, mails, etc.

One of the current challenges is utilizing the new cross-desktop PIM infrastructure called [http://www.akonadi-project.org/ Akonadi].

There are interesting projects on all levels of the software stack: libraries, application porting, new applications, access to online resources, etc.

[http://pim.kde.org/ Website] - [http://techbase.kde.org/Projects/PIM Project Wiki] - [https://mail.kde.org/mailman/listinfo/kde-pim Mailing list] - IRC channel: #kontact and #akonadi on Freenode.

====Project: Akonadi Janitor Agent====
'''Brief explanation:'''
An [[Development/Architecture/KDE4/Akonadi#Akonadi_Agents|Akonadi Agent]] is a service process for performing tasks on data provided through the Akonadi server.

The task of a Janitor agent would be to keep the user's PIM data neatly organized, for example deleting news feed items which are above a certain age and not flagged, moving last week's mail to an archive, etc.

'''Expected results:'''
* An Akonadi Agent capable of managing actions on Akonadi collections triggered by various criteria
* At least fully working implementation of actions based on "Expire" criterias for mail, e.g. delete mail above certain age, move/copy to different collection, etc
* GUI for configuring actions and their trigger criteria.

'''Knowledge Prerequisite:''' C++ and Qt. Ideally would already have gone through the [[Development/Tutorials/Akonadi/Resources|Akonadi Resource Tutorial]] since Resources are a specialized form of agents and thus share some of the API and characteristics.

'''Mentor:''' Kevin Krammer (kevin dot krammer at gmx dot at)
----
====Project: Alternative Akonadi Client Library====
'''Brief explanation:'''
Akonadi has a server/client like architecture where clients such as applications (but also resource) connect to a service and communicate with it through a suitable protocol.

Currently this is implemented for KDE in library called libakonadi-kde, however it is desirable to have additional implementations to be suitable for other library stacks, e.g. GLib/GObject based ones.

'''Expected results:'''
* A non-KDE based, preferably GLib/GObject based, Akonadi client library which
** can connect to a running Akonadi server
** fetch Akonadi collections
** fetch Akonadi items
** receive Akonadi change notifications (D-Bus based)

* A set of demo programs using the library which can
** recursively list (id and content MIME types) collections
** list (id and MIME type)oif items in a collection
** get the raw payload of an item

'''Knowledge Prerequisite:''' Depends on the chosen language and toolstack, e.g. C/Vala and GLib/GObject knowledge for a GLib/GObject based implementation.

'''Mentor:'''
----
====Project: Akonadi Consistency Checker====
'''Brief explanation:'''
Akonadi provides a structure of collections and items, similar to folders and files of a filesystem. Similarly the internal structures have to follow certain constraints which must not be violated. Nevertheless, this can happen as result of bugs, hardware failures, power loss and a million other reasons.

Filesystem checks exist to detect and possibly fix such situations. Such functionality would also be desirable for Akonadi.

'''Expected results:'''
* A consistency checker (built into the Akonadi server or stand-alone) that performs an extensible set of checks on the internal data structures of the Akonadi server, such as:
** items belong to existing collections
** collections are child collections of existing collections
** the collection tree is non-cyclic
** every collections is owned by an existing resource
** collection sub-trees are owned by the same resource
** every item payload part belongs to an existing item
** content type constraints of collections are not violated
** ...
* each check should be accompanied with recovery code, such as moving orphaned items into a lost+found folder
* integration into Akonadiconsole
* integration into unit-tests

'''Knowledge Prerequisite:''' C++ and Qt mandatory, SQL/database knowledge would be useful.

'''Mentor:''' Volker Krause <vkrause@kde.org>
----
====Project: Akonadi Resource for KMail local folders====
'''Brief explanation:'''
KMail stores its mail in a folder hierachy where each folder can contain mails '''and''' further sub folders.

While mails are stored either as mbox or maildir, additional index files are used to speed up message listing and to store message status and flags.

The already existing Akonadi MailDir resource can handle the maildir aspects but cannot handle either mbox based folders nor the additional information stored in the index files.

'''Expected results:'''
* a set of classes, probably as a library, capable of
** recursively listing the KMail folder tree given a base directory
** reading mails from the mbox and maildir folders in the KMail folder tree
** reading KMail index files
* an Akonadi resource using these classes to provide read-only access to all mails currently handled by KMail. The resource should also be able to transfer the flags stored in KMail's index file to Akonadi.
* Writing a migrator, similar to the current KResource->Akonadi migrator, that automatically reads the KMail config file and creates a Akonadi resource out of it. Optionally, depending on the overall progress, the migrator would also convert some of KMail's folder settings, like the folder icon or the expiry settings, to Akonadi collection attributes.

'''Knowledge Prerequisite:''' C++ and Qt mandatory, code analysis skills would be helpful regarding the handling of index files, refactoring skills if KMail's classes are to be extracted from KMail's code base (not required).

'''Mentor:''' Thomas McGuire <mcguire at kde dot org>
----

====Project: Improvments in KMail's HTML support====
'''Brief explanation:''' Improve the HTML support in KMail, especially making it possible to preserve the HTML format when replying or inline forwarding.

While KMail's HTML support has been constantly improving, it still has some important bits missing and some minor bugs. The goal of this project would be to implement the missing features and do general bugfixing in the HTML support.

One of the biggest missing features, with over 1500 votes on [https://bugs.kde.org/show_bug.cgi?id=86423 bugzilla], is the ability to preserve the HTML format when replying or forwarding, which is often an essential requirement in some enterprises.

[http://websvn.kde.org/?view=rev&revision=911149 Recently], support for inline HTML images was added to KMail. This support needs a few improvements, like being able to put images in the signature or resizing the images.

Currently, KMail relies on [http://doc.trolltech.com/4.4/qtextedit.html#html-prop QTextEdit::toHtml()] to generate the HTML source. This however is very weak, as QTextEdit has some bugs and generally produces HTML that is only equaled by MS Word in its ugliness. Stephen Kelly has started some work to make this output nicer, and to produce other forms of markup, like text/enriched. This is achived by creating so-called [http://websvn.kde.org:80/trunk/KDE/kdepimlibs/kpimidentities/richtextbuilders/ rich-text builders]. One goal would be to finish this work and integrate it into KMail.

Comment by Thomas; QTextEdit html generation is not optimal due to html simply not supporting all QTextEdit features. Qt45 choose to export to ODF instead. Maybe KMail should try to leverage this instead?

Other nice points would be to support the text/enriched format for reading or composing mails, and to support the text/flowed format when composing. Although this is not strictly HTML related, it would improve the experience for many people.

Of course, your own ideas are very welcome as well

'''Expected results:'''
* Option to preserve the HTML format when replying or forwarding
* Support inline images also in signatures
* Improve inline image support by allowing to scale the images
* Nicer HTML generation by completing and integrating the HTML builder from Stephen Kelly
* Various bugfixes in the HTML support
* Optionally, also support text/enriched as alternative to HTML (both reading and composing). See [http://www.faqs.org/rfcs/rfc1896.html RFC 1896]. Composing support can also be based on Stephen's builders.
* Optionally, support text/flowed format for non-HTML mail ([http://www.faqs.org/rfcs/rfc3676.html RFC 3676])

'''Knowledge Prerequisite:''' Moderate C++ and basic Qt knowledge mandatory

'''Mentor:''' Thomas McGuire <mcguire at kde dot org>
----

====Project: import/export for filtering rules in Sieve format in KMail====
'''Brief explanation''' Add functionality to import/export of mail filtering rules in Sieve format in KMail.

Sieve is a language for declaring mail filter rules on a mail server. It was developed as part of the Cyrus IMAP server, but was quickly spin off and turned into a standard (http://tools.ietf.org/html/rfc5228). There are quite a few servers that have support for Sieve, in various degrees of completeness. It is quickly gaining support. Clients that support it are KMail and Thunderbird.

KMail already has support for talking to Sieve enabled servers and also has support for client side filters. These two rule sets seem to be separate. It would be nice if you could dump the rules you have in one client and able to either install them on a server, or load them into another client, if you want to access your mail from different machines, but don't want to reconfigure your mail clients over and over again, or to quickly reconfigure clients if you don't have a Sieve enabled server.

'''Expected results:'''
Successful import and export of a (subset) of mail filtering rules between various KMail instances.

'''Knowledge requisites'''
* C++
* knowledge of how mail works

===KDE on Windows===
====Solid API backend====
'''Brief explanation:'''
The porting efforts to make KDE available across platforms do need some backends for system dependent tasks. One of the KDE libraries that bundles this is Solid.

'''Expected results:'''
You implement a backend for the [http://solid.kde.org Solid API] using WINAPI.
It has to work with both MinGW and MSVC compilers. Not every function is required, but the basic functionality (network access, removable drives/harddisks and power) should be implemented.

'''Knowledge Prerequisite:''' Windows API and C++/Qt. You should be able to set up the [http://techbase.kde.org/Getting_Started/Build/KDE4/Windows development environment] yourself and be familiar with it.

'''Mentor:''' Carlo Segato (brandon dot ml at gmail dot com) or Patrick Spendrin (ps_ml at gmx dot de)
----

===KDE Games===
====Project: Kolf 2 landscape object====
'''Brief explanation:'''
Kolf 2 is the second incarnation of KDE's minigolf game. We are currently rewriting it from scratch to take advantage of the powerful technologies provided by Qt 4 and KDE 4.

'''Expected results:'''
The task in this project is to create an object (or multiple objects) that provide(s) landscape textures, slopes, puddles and sand bunkers.

If you finish this task before the end of the summer, you can fill the remaining time by porting as much game objects from Kolf 1 to Kolf 2 as possible (e.g. windmills, floating blocks, signs or bumpers).

'''Knowledge Prerequisite:''' C++/Qt. Experiences in graphics programming with Qt will definitely help, as you are expected to implement 2D rendering for the landscape object.

'''Mentor:''' Stefan Majewsky (majewsky at gmx dot net) – Please contact me to let me help you to improve your proposal.

====Project: Kolf 2 editor interface====
'''Brief explanation:'''
The minigolf game Kolf provided an editor interface from the beginning, to allow the users to create custom courses. For Kolf 2, we are rewriting the game engine and can therefore not use the old editor code.

'''Expected results:'''
Your task would be to create an editor interface (may be embedded in the game, or a standalone application). A few basic parts are available, and the Kolf 2 engine supports generic methods to provide data to editor interfaces, and display editor overlays on the game view.

If you finish the editor interface before the end of the summer, you can fill the remaining time by porting as much game objects from Kolf 1 to Kolf 2 as possible (e.g. windmills, floating blocks, signs or bumpers), or using your editor to put together some cool courses.

'''Knowledge Prerequisite:''' C++/Qt. Experiences in model/view programming with Qt will be of good use.

'''Mentor:''' Stefan Majewsky (majewsky at gmx dot net) – Please contact me to let me help you to improve your proposal.

----

===kdelibs===
==== Project: DOM3 XPath Level 1 and/or DOM selectors API support in KHTML ====
'''Brief explanation:'''
Because JavaScript frameworks have popularized access to parts of documents using various query languages, direct browser support for such queries
has become fairly common. This project is about adding support for one (or two) of such languages to KHTML. Basic implementation of each is expected to be simple, but there may be some interesting optimization opportunities to explore.

'''Expected results:'''
Implementations of XPath 1 or DOM selectors API at DOM level with appropriate JavaScript bindings that are standard-compliant, written in simple & maintainable fashion, and perform reasonably well.

'''Knowledge Prerequisite:''' C++, and some comfort with working with large codebases.

'''Mentor:''' Maks Orlovich (maksim at kde dot org)

===Solid===
====Project: UPnP support through Jolie====
'''Brief explanation:'''
Adding UPnP support to Solid would mean offering transparent UPnP support to every KDE application using the Solid API, keeping them clean from every UPnP implementation aspect.
At the present, the [http://www.jolie-lang.org/ Jolie language] is being integrated with Plasma by means of the [http://websvn.kde.org/branches/work/~ervin/sodep/ QtSodep] library, soon to offer higher levels of abstraction.

The aim of this project would be to implement a UPnP protocol for Jolie, so that Solid could re-use the integration being made with QtSodep and gain UPnP support without having to worry about implementation details. Having a UPnP protocol implementation in Jolie would have other considerable consequences, like the possibility to act easily as a UPnP server or to compose and export existing UPnP services.

'''Expected results:'''
*The creation of a "upnp" protocol in Jolie, supporting at least the Internet Gateway Device (IGD) and MediaServer profiles.
*The creation of a UPnP Jolie service for UPnP service discovery and monitoring.
*Extending libsolid to expose UPnP devices found on the network.

'''Material Prerequisite:''' Having UPnP devices or software applications to test with. Most home routers support IGD, and there exists free software supporting the MediaServer profile ([http://mediatomb.cc/ mediatomb]).

'''Knowledge Prerequisite:''' Understanding of the UPnP specifications, Java (for the development of the Jolie UPnP protocol) and basic knowledge of the Jolie language.

'''Mentors:''' ervin (ervin at kde dot org) fmontesi (famontesi at gmail dot com)
----

===KWin===

KDE's window manager

[http://techbase.kde.org/Projects/KWin Techbase page] - [https://mail.kde.org/mailman/listinfo/kwin Mailinglist] - IRC channel: #kwin on Freenode.

====Project: Window tabbing====

'''Brief explanation:'''
Window tabbing is a feature that allows you to group multiple application windows together to cover the same space. It is identical to what is already available in any modern web browser except it applies the the window as a whole. Window managers that have this feature available include Fluxbox and Ion. This feature was [http://bugs.kde.org/show_bug.cgi?id=42023 originally requested] in 2002.

'''Knowledge Prerequisite:''' C++ and Qt. Understanding of the X window system and Xlib is a benefit but not required.

'''Mentors:''' Lucas Murray (lmurray undefinedfire com)

====Project: Window tiling====

'''Brief explanation:'''
Window tiling is a technique of displaying application windows side-by-side without overlap. The position, size and layout of the windows can either be specified by the user or determined automatically to best fit the screen. Examples of existing tiling window managers include Awesome, XMonad, Ion and Ratpoison. One of the main advantages of tiling is that is makes application windows easy to navigate solely by the keyboard. This feature was [http://bugs.kde.org/show_bug.cgi?id=59338 originally requested] in 2003.

'''Expected results:'''
* Users should be able tile existing floating windows on-the-fly with simple keyboard shortcuts or mouse gestures.
* It should also be possible to run the entire desktop environment entirely in tiled mode (Enabled by configuration settings). In this mode new window would be added to the tiling grid by default yet can be removed by the user if required.
* The final tiling system should not interfere in any way with the existing floating window management.

'''Knowledge Prerequisite:''' C++ and Qt. Understanding of the X window system and Xlib is a benefit but not required.

'''Mentors:''' Lucas Murray (lmurray undefinedfire com)

====Project: Window snapping====
'''Brief explanation:'''
Easy drag and drop for whole Windows:
http://lifehacker.com/5085657/aerosnap-brings-the-windows-7-snap-feature-to-xp-vista

----

=== digiKam ===

Photo Management program

[http://www.digikam.org digiKam project web site] - [https://mail.kde.org/mailman/listinfo/digikam-devel Mailinglist] - IRC channel: #digikam on Freenode.

====Project: High Dynamic Range (HDR) plugin====

'''Project Information:''' digiKam is an advanced digital photo management application for KDE, which makes importing and organizing digital photos a "snap". The photos are organized in albums which can be sorted chronologically, by folder layout or by custom collections. digiKam has an Image Editor which has its own plugin subsystem with some common tools e.g. red eye correction or Gamma correction. Additional plugins are provided with the main application to process advanced corrections on image like color management, noise reduction, or special effects. digiKam image editor support 16 bits color depth image internally. The goal of this project is to create a new plugin dedicated to create [http://en.wikipedia.org/wiki/High_dynamic_range_imaging HDR image].

'''Expected results:''' This project should implement an HDR tool will mix two or more (nearly) identical images having different exposure into a new image representing a wider dynamic range, which is closer to human perception of a photographic scene. [http://en.wikipedia.org/wiki/Tone_mapping Tone-mapping method] must be used to create HDR images. An open-source implementation is already available at [http://zynaddsubfx.sourceforge.net/other/tonemapping this url] and can be re-used as well. There is an old [https://bugs.kde.org/show_bug.cgi?id=144593 feature request].

'''Knowledge Pre-Requisite:''' C++/Qt.

'''Mentors:''' Gilles Caulier (caulier dot gilles at gmail dot com)

----

===KDE Telepathy Integration===
The [http://telepathy.freedesktop.org Telepathy Framework] is a desktop independent framework for real-time communication, such as VoIP and Instant Messaging. The projects below are some ideas for integrating telepathy into KDE.

If you want to know any more about Telepathy and KDE, drop by the irc channel #decibel and talk to '''grundleborg''', or use the mailing list decibel AT kde DOT org.

====Project: Message Logging====

'''Project Information:''' The Telepathy Framework allows for components which can watch channels whilst a user is interacting with them through another application. A program could be created to log the content of text instant messages into an Akonadi collection.

'''Expected results:''' This project should result in a telepathy watcher which is capable of logging the contents of text chats into an Akonadi collection. It should be possible to go off-the-record in a particular conversation from telepathy user interfaces and the logger should not save any messages in this situation. This project might also include modifying the Kopete logging plugin to use the same akonadi collection for logs, and making a migration tool from Kopete's old logging format to the new Akonadi collection.

'''Knowledge Pre-Requisite:''' C++/Qt, some basic knowledge of the Telepathy Framework is an advantage, but not necessary if you have an interest in real-time communcation and are prepared to learn fast.

'''Mentors:''' George Goldberg (grundleborg at gmail dot com) IRC: grundleborg

====Project: Telepathy Integration to any KDE application====

'''Project Information:''' Provide some collaborative feature or instant messaging integration for your favourite KDE application.

'''Expected results:''' This project should result in a collaborative feature or instant messaging integration being added to the chosen KDE application. It should be complete enough to provide at least basic functionality to end users, with the possibility of further improvement after the summer of code period ends.

'''Knowledge Pre-Requisite:''' C++/Qt, some basic knowledge of the Telepathy Framework is an advantage, but not necessary if you have an interest in real-time communcation and are prepared to learn fast.

'''Mentors:''' George Goldberg (grundleborg at gmail dot com) IRC: grundleborg. You should also discuss your idea with the development team of the application in which you would like to provide a Telepathy feature.

====Project: Telepathy Plasma Integration====

'''Project Information:''' Provide integration of presence and buddy information into plasma.

'''Expected results:''' You should provide multiple points of integration between presence and contact information and plasma. Plasmoids allowing the display and manipulation of your own presence information should be made available, building on the plasma applets and datengines already in existance for presence information. Plasma activities could also be made aware of presence, and the contacts plasmoid could be made aware of your buddies from Telepathy instant messaging accounts.

'''Knowledge Pre-Requisite:''' C++/Qt

'''Mentors:''' George Goldberg (grundleborg at gmail dot com) IRC: grundleborg. You should also discuss your ideas with the plasma development team before making a proposal.

----

===Nepomuk===
[http://nepomuk.kde.org Website] - [http://lists.semanticdesktop.org/mailman/listinfo/nepomuk-kde Mailing list] - IRC channel: #nepomuk-kde on Freenode.

====Project: A Context Sidebar====
'''Brief Explanation''':
The ideas is to have a sidebar on the desktop (see Plasma project above for example) which shows information about the resource in the current context. Examples include files or important emails from a specific person that sent the email I am currently reading. Or related information on a webpage I am currently browsing. Or the author information on a pdf I am reading. And so on.
The sidebar should pick up DBus signals that can be sent out by any application to change the current resource (this is just an idea).

'''Expected Results''':
Creation of the sidebar and integration into at least two applications (like KMail or Okular) which will then update the resource in focus. It might also be good if the sidebar could monitor if the application that set the resource looses focus or is closed.

'''Knowledge Pre-Requisite:''' C++/Qt/KDE/Plasma

'''Mentor''': Sebastian Trueg (trueg at kde dot org)

====Project: Saving and Loading of Documents via Meta-data====
'''Brief Explanation''':
Today we still save and load our documents using a file browser. We navigate through folder structures that we created and try to find the best spot for the document. Another way would be to store a document by specifying meta-data about it. We could for example set the type (not the mimetype but the actual type like it is a letter or an invoice or a holiday picture and so on) or set properties on the document like related projects, related persons, tags, and so on. The system would then store the document someplace (we don't care about that). Loading the document would work the same way: filter documents according to type, date, persons or any other property we might have chosen to describe it.
In KDE applications today can predefine the file extension. How about letting the application predefine a set of meta-data properties.

'''Expected Results''':
A prototype for saving and loading documents via meta-data and at least one use case which is demoable.

'''Knowledge Pre-Requisite:''' C++/Qt/KDE, knowledge on ontologies and RDF are very helpful

'''Hints''':
One might think of a plugin system here that allows to suggest annotations to the user. Compare the annotation system already in [http://websvn.kde.org/trunk/playground/base/nepomuk-kde/annotationplugins/ playground] based on [http://websvn.kde.org/trunk/playground/base/nepomuk-kde/annotationplugins/annotation.h?revision=915514&view=markup Nepomuk::Annotation].

'''Mentor''': Sebastian Trueg (trueg at kde dot org)

Projects/Summer of Code/2009/Ideas

2009-02-20T16:52:17Z

Zander: Remove silly suggestions that will not be accepted into mainline anyway.

Contribute/Bugsquad/BugDays/KOfficeDay2/KWord

2009-01-23T16:04:12Z

Zander: /* Application specific tips */

===KWord===

====Application specific tips====

At Beta5 the state of KWord is that the application has been stabilized to a large extend and all present features should work with small exceptions.
The loading and saving of documents has not received a lot of attention and therefor it is well known that there will be loads of problems in loading ODFs. So testing KWord by loading may give you some silly results beware of that. And I'd rather have interaction and new document creation be the focus of testing due to that. (ThomasZ)

====Testers====
Please put your IRC nickname and KOffice svn revision number (or beta5) in the table if you are testing this app.
{|
|-
!IRC Nickname !! KOffice svn revision number tested !! Testing details
|}

====Bugs====
Please list all bugs found in the application below here. Remember to sign every comment you write on this wiki page with <nowiki>~~~</nowiki>.

* After starting kword, with the colorful document, the default tool is Text Editing, without doing anything else, when I choose Paragraph tool, the options bars suffer a little colapse. Look at: [[Image:Kword_toolbar1.png]] [[User:Jtamate|Jtamate]]
NOTE: It happens also with a lot of tools. 
NOTE: This only happens with the colorful document, with a blank document it does not happen.

* The tool toolbar can not be horizontally srinked to only one or two tools (specially usefull on small screens). [[User:Jtamate|Jtamate]] 
NOTE: This only happens with one user account (that has used previous betas), with a fresh new account it does not happen.

* The zoom options toolbar is not painted totally. Look at: 
[[Image:Zoom_options.png]] [[User:Jtamate|Jtamate]]

* The zoom options toolbar does not select the default tool (zoom in or zoom out). [[User:Jtamate|Jtamate]]

* Find does nothing. Hope the find interface will change to something similar to what kate has. [[User:Jtamate|Jtamate]]

* The hand drawing plots are not saved (or loaded). What I wrote: 
[[Image:Screen_with_free_hand_drawings.png]] 
But only the text is restored. If there are some things that can not be saved or restored, it should be shown when saving the file.[[User:Jtamate|Jtamate]]

Development/Tutorials/Write a Flake Plugin

2008-12-15T10:35:55Z

Zander: Remove question; answer is that it hasn't changed.

This tutorial will guide you step by step through the creation of a [http://wiki.koffice.org/index.php?title=Flake Flake] shape. At the end you will be able to write a shape that is loadable by any KOffice application.

For an introduction of KOffice plugins, see [[Development/Tutorials/KOffice Overview]] and for a technical introduction to plugins in KOffice see [[Development/Tutorials/Generic KOffice Plugin Creation|Generic KOffice Plugin Creation]]

=Do the groundwork - create a shape=

First of all you need a class derived from the [http://koffice.org/developer/apidocs/libs-flake/classKoShape.html KoShape] class. This will be the actual shape class so you have to ensure that all the data you need for painting is accessable for this KoShape derived class.
The only method you '''have''' to reimplement is the [http://koffice.org/developer/apidocs/libs-flake/classKoShape.html#027c57ec3dc4360294c5bb7330c768d7 paint()] method which is responsible for painting your shape.

What you might be interested in is the [http://koffice.org/developer/apidocs/libs-flake/classKoShape.html#09a45358ef20c372675790531989d5b6 resize()] and [http://koffice.org/developer/apidocs/libs-flake/classKoShape.html#5bc408a6f4d7f0bd0ea832002b96ac83 size()] method which set the available size to the shape. Some shapes define the size they need on their own so they reimplement size() to return the size they have.

An example for this is the KoFormulaShape. A formula has a fixed size due to its contents and so KoFormulaShape reimplements the size() method.
If your shape has a special outline, reimplement [http://koffice.org/developer/apidocs/libs-flake/classKoShape.html#71ac11dbac93b5bff2f91fb768fa17e5 outline()] to return your shape's outline correctly.

The rotation, scaling and skewing is done through a matrix and so you don't need to care about it.

So here is an example how your code might look like:
<code cppqt>
#include <KoShape.h>

class KoFooShape : public KoShape {
public:
KoFooShape();
~KoFooShape();

// absolutly necessary:
void paint( QPainter &painter,
const KoViewConverter &converter );

private:
SomeDataClass* m_dataClass;
};
</code>

=Make your shape loadable - create a factory and a plugin=

Now when you have created your shape class and implemented all the necessary things to make it at least compile you can think about the loading of your shape.

The KOffice apps use [http://koffice.org/developer/apidocs/libs-flake/classKoShapeFactory.html KoShapeFactory] to get instances of shapes in a generic way. This way of obtaining shape instances is designed after [http://en.wikipedia.org/wiki/Abstract_factory_pattern the factory pattern]. So you should also implement a KoShapeFactory derived class that makes creating new instances of your shape possible. The factory class has to implement two methods:

* KoShape* createDefaultShape() const;
* KoShape* createShape( const KoProperties* params ) const;

An example factory class definition:
<code cppqt>
class FooShapeFactory : public KoShapeFactory {
public:
FooShapeFactory( QObject *parent );

KoShape* createDefaultShape() const;
KoShape* createShape(const KoProperties* params) const;
};
</code>
The according implementation:
<code cppqt>
FooShapeFactory::FooShapeFactory(QObject* parent)
: KoShapeFactory( parent, "FooShape",
i18n("Foo Shape") )
{
setToolTip( i18n("A foo shape") );
}

KoShape* FooShapeFactory::createDefaultShape() const
{
KoFooShape* fooShape = new KoFooShape();
// set defaults
return fooShape;
}

KoShape* FooShapeFactory::createShape(
const KoProperties* params ) const
{
KoFooShape* fooShape = new KoFooShape();
// use the params
return fooShape;
}
</code>

With the factory there is now a generic way to obtain an instance of your shape. But somehow you have to publish your shape as a plugin to let the KOffice application know that there is a plugin to load. Therefore the flake library provides the [http://koffice.org/developer/apidocs/libs-flake/classKoShapeRegistry.html KoShapeRegistry] class. Each application has access to the registry and to let the application know about your shape you have to register it within the registry.

To register we would have to make a call like this:
<code cppqt>
KoShapeRegistry::instance()->add( new FooShapeFactory( parent ) );
</code>
In order to make that call, we will create a plugin class which is special in that it will be automatically loaded and created by KOffice when an application starts. This means that the constructor of our plugin class will be the perfect place to actually register our shape using the above line.

The registration is done within the constructor of the FooShapePlugin class. This is a very simple class that represents the plugin and does registration.

Example plugin class definition:
<code cppqt>
#include <QObject>

class FooShapePlugin : public QObject {
Q_OBJECT
public:
FooShapePlugin(QObject *parent, const QStringList&);
};
</code>

Example plugin class implementation:
<code cppqt>
#include "FooShapePlugin.h"
#include <kgenericfactory.h>

K_EXPORT_COMPONENT_FACTORY(fooshapelibrary,
KGenericFactory<FooShapePlugin>( "FooPlugin" ) )

FooShapePlugin::FooShapePlugin(QObject *parent, const QStringList&)
: QObject(parent)
{
// register the shape's factory
KoShapeRegistry::instance()->add(
new KoFooShapeFactory( parent ) );
// we could register more things here in this same plugin.
}
#include "FooShapePlugin.moc"
</code>
This demonstrates how for the plugin related tasks KDE provides services which are dynamic loaded libraries. The secret ingredient that makes this class the plugin of that library is the call to the K_EXPORT_COMPONENT_FACTORY macro defined in {{path|kgenericfactory.h}}

We now have a way to create instances of your shape (FooShapeFactory), a way to register them for the apps (KoShapeRegistry) and a plugin that can dynamically be loaded (FooShapePlugin). The last step is to create a {{path|.desktop}} file that describes your plugin and makes it findable by KOffice. For "X-KDE-Library" you have to set the library name you have already specified within K_EXPORT_COMPONENT_FACTORY().

Example {{path|fooshape.desktop}} file:
<code ini>
[Desktop Entry]
Encoding=UTF-8
Name=Foo Shape
ServiceTypes=KOffice/Flake
Type=Service
X-KDE-Library=fooshapelibrary
X-Flake-Version=1
</code>

After installing that file in the KDE services directory and installing your plugin where the application can open it, your plugin is system wide known and can be loaded by KOffice.

TODO; add example CMake file.

=Make your shape editable - create a tool=

To edit your shape in the GUI the user wants to select a tool and alter your shape. Therefore you have to provide a KoTool derived class. This class implements all edit actions that can be done on your shape but it is also possible to have more than one tool per shape.

Talk:Archive:Development/Tutorials/Git

2008-04-21T07:51:58Z

Zander: tips

Lots of good ideas can be found here; [http://wiki.winehq.org/GitWine Git tutorial at WineHq].
I am in the process of writing a front-end that is more userfriendly; it may be useful to link to it [http://vng.googlecode.com home] [http://repo.or.cz/w/vng.git repo].
[[User:Zander|Zander]] 09:51, 21 April 2008 (CEST)

Development/Architecture/KDE3/Network Transparency

2008-02-10T21:06:12Z

Zander: /* Using KIO */

'''KDE Architecture - KDE's IO architecture'''

== 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 KIO 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 achived 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 KIO ==

In most cases, jobs are created by calling functions in the KIO namespace.
These functions take one or two URLs as arguments, and possible other
necessary parameters. When the job is finished, it emits the signal
<tt>result(KIO::Job*)</tt>. After this signal has been emitted, the job
deletes itself. Thus, a typical use case will look like this:

<code cppqt3>
void FooClass::makeDirectory()
{
SimpleJob *job = KIO::mkdir(KURL("file:/home/bernd/kiodir"));
connect( job, SIGNAL(result(KIO::Job*)),
this, SLOT(mkdirResult(KIO::Job*)) );
}

void FooClass::mkdirResult(KIO::Job *job)
{
if (job->error())
job->showErrorDialog();
else
cout << "mkdir went fine" << endl;
}
</code>

Depending on the type of the job, you may connect also to other
signals.

Here is an overview over the possible functions:

KIO::mkdir(const KURL &url, int permission)
:Creates a directory, optionally with certain permissions.
KIO::rmdir(const KURL &url)
:Removes a directory.
KIO::chmod(const KURL &url, int permissions)
:Changes the permissions of a file.
KIO::rename(const KURL &src, const KURL &dest, bool overwrite)
:Renames a file.
KIO::symlink(const QString &target, const KURL &dest, bool overwrite, bool showProgressInfo)
:Creates a symbolic link.
KIO::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 KIO::StatJob::statResult() after the job has finished.
KIO::get(const KURL &url, bool reload, bool showProgressInfo)
:Transfers data from a URL.
KIO::put(const KURL &url, int permissions, bool overwrite, bool resume, bool showProgressInfo)
:Transfers data to a URL.
KIO::http_post(const KURL &url, const QByteArray &data, bool showProgressInfo)
:Posts data. Special for HTTP.
KIO::mimetype(const KURL &url, bool showProgressInfo)
:Tries to find the MIME type of the URL. The type can be obtained from KIO::MimetypeJob::mimetype() after the job has finished.
KIO::file_copy(const KURL &src, const KURL &dest, int permissions, bool overwrite, bool resume, bool showProgressInfo)
:Copies a single file.
KIO::file_move(const KURL &src, const KURL &dest, int permissions, bool overwrite, bool resume, bool showProgressInfo)
:Renames or moves a single file.
KIO::file_delete(const KURL &url, bool showProgressInfo)
:Deletes a single file.
KIO::listDir(const KURL &url, bool showProgressInfo)
:Lists the contents of a directory. Each time some new entries are known, the signal KIO::ListJob::entries() is emitted.
KIO::listRecursive(const KURL &url, bool showProgressInfo)
:Similar to the listDir() function, but this one is recursive.
KIO::copy(const KURL &src, const KURL &dest, bool showProgressInfo)
:Copies a file or directory. Directories are copied recursively.
KIO::move(const KURL &src, const KURL &dest, bool showProgressInfo)
:Moves or renames a file or directory.
KIO::del(const KURL &src, bool shred, bool showProgressInfo)
:Deletes a file or directory.

== Directory entries ==

Both the KIO::stat() and KIO::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 KIO 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
KIO::NetAccess. For example, in order to copy a file, use

<code cppqt3>
KURL source, target;
source = ...;
target = ...
KIO::NetAccess::copy(source, target);
</code>

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:

<code cppqt3>
KURL url;
url = ...;
QString tempFile;
if (KIO::NetAccess::download(url, tempFile) {
// load the file with the name tempFile
KIO::NetAccess::removeTempFile(tempFile);
}
</code>

== 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:

<code cppqt3>
void FooClass::reloadPage()
{
KURL url("http://www.kdevelop.org/index.html");
KIO::TransferJob *job = KIO::get(url, true, false);
job->addMetaData("cache", "reload");
...
}
</code>

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:

<code cppqt3>
void FooClass::printModifiedDate()
{
KURL url("http://www.kde.org");
KIO::TransferJob *job = KIO::get(url, true, false);
connect( job, SIGNAL(result(KIO::Job*)),
this, SLOT(transferResult(KIO::Job*)) );
}

void FooClass::transferResult(KIO::Job *job)
{
QString mimetype;
if (job->error())
job->showErrorDialog();
else {
KIO::TransferJob *transferJob = (KIO::TransferJob*) job;
QString modified = transferJob->queryMetaData("modified");
cout << "Last modified: " << modified << endl;
}
</code>

== Scheduling ==

When using the KIO 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,
KIO 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 KIO 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:

<code cppqt3>
KURL url("http://www.kde.org");
KIO::TransferJob *job = KIO::get(url, true, false);
KIO::Scheduler::scheduleJob(job);
</code>

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
allocate 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 KIO::Scheduler:

<code cppqt3>
KURL baseUrl("imap://bernd@albert.physik.hu-berlin.de");
KIO::Slave *slave = KIO::Scheduler::getConnectedSlave(baseUrl);

KIO::TransferJob *job1 = KIO::get(KURL(baseUrl, "/INBOX;UID=79374"));
KIO::Scheduler::assignJobToSlave(slave, job1);

KIO::TransferJob *job2 = KIO::get(KURL(baseUrl, "/INBOX;UID=86793"));
KIO::Scheduler::assignJobToSlave(slave, job2);

...

KIO::Scheduler::disconnectSlave(slave);
</code>

You may only disconnect the slave after all jobs assigned to it are guaranted
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=kio_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 "kdeinit"
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 <tt>.protocol</tt> file define which abilities the
slave has. In general, the features a slave must implement are much simpler than
the features the KIO 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 KIO 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), KIO can read the source file and then
write the data to the destination file. For this to work, the <tt>.protocol</tt>
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:

<code cppqt3>
extern "C" { int kdemain(int argc, char **argv); }

int kdemain(int argc, char **argv)
{
KLocale::setMainCatalogue("kdelibs");
KInstance instance("kio_ftp");
(void) KGlobal::locale();

if (argc != 4) {
fprintf(stderr, "Usage: kio_ftp protocol "
"domain-socket1 domain-socket2\n");
exit(-1);
}

FtpSlave slave(argv[2], argv[3]);
slave.dispatchLoop();
return 0;
}
</code>

== Implementing an ioslave ==

Slaves are implemented as subclasses of KIO::SlaveBase (FtpSlave in the above
example). Thus, the actions listed in the {{path|.protocol}} correspond to
certain virtual functions in KIO::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 <tt>.protocol</tt>
file. For these operations, KIO 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 <tt>finished()</tt>. If an error has occured,
<tt>error()</tt> should be called with an error code as first argument and a
string in the second. Possible error codes are listed as enum KIO::Error. The
second argument is usually the URL in question. It is used e.g. in
KIO::Job::showErrorDialog() in order to parametrize 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 KIO::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 KIO::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 KIO::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.

''Initial Author:'' [mailto:bernd@kdevelop.org Bernd Gehrmann]

[[Category:KDE3]]
[[Category:Architecture]]

User:Chani/GettingStarted

2008-02-02T12:49:21Z

Zander: Add more links

A quick intro for potential plasma contributors (kdebase and maybe extragear, not playground or other locations)

*Plasma uses kdelibs coding style. there's a file somewhere in svn that makes vim follow this automatically. I know there was a page explaining it, so why can't I find it? (I think its this one; [http://websvn.kde.org/trunk/KDE/kdesdk/scripts/kde-devel-vim.vim?view=log kde-devel.vim] [[User:Zander|Zander]] 13:46, 2 February 2008 (CET))
*if a patch is nontrivial, please get it reviewed before committing. best place to do that is http://matt.rogers.name/dashboard/
*mailing list is panel-devel [http://mail.kde.org/mailman/listinfo/panel-devel subcribe] [http://lists.kde.org/?l=kde-panel-devel&r=1&w=2 archives]

User:Chani/GettingStarted

2008-02-02T12:46:12Z

Zander: add link

A quick intro for potential plasma contributors (kdebase and maybe extragear, not playground or other locations)

*Plasma uses kdelibs coding style. there's a file somewhere in svn that makes vim follow this automatically. I know there was a page explaining it, so why can't I find it? (I think its this one; [http://websvn.kde.org/trunk/KDE/kdesdk/scripts/kde-devel-vim.vim?view=log kde-devel.vim] [[User:Zander|Zander]] 13:46, 2 February 2008 (CET))
*if a patch is nontrivial, please get it reviewed before committing. best place to do that is http://matt.rogers.name/dashboard/
*mailing list is panel-devel (iirc it's harder to find than other kde lists... what's the url?)

Projects/Oxygen/StyleWinDec

2007-12-01T21:17:54Z

Zander: Incoming; this one was lost somehow. :( Maybe we should move this to bugzilla

The current Oxygen style and window decoration for KDE4 can be found in SVN under http://websvn.kde.org/trunk/KDE/kdebase/runtime/kstyles/oxygen and http://websvn.kde.org/trunk/KDE/kdebase/workspace/kwin/clients/oxygen

== Visitors ==
Add new bugs to [[#Incoming_New_Bugs|Incoming New Bugs]], and we (the developers) will move it down and prioritize.

Note: we may move invalid bugs may be moved to the discussion page, along with a reason why they won't be fixed [by us].

DO NOT EDIT OTHER SECTIONS WITHOUT PERMISSION. This page has now been protected due to unauthorized edits. If you need to leave a comment anonymously, do it on the discussion page and/or talk to us on #oxygen.

== Incoming New Bugs ==
* When the tabbar has many tabs, so that not all of them can be shown at once, arrow buttons are drawn to navigate to the other tabs. These arrows are painted incorrectly, see [http://bugs.kde.org/show_bug.cgi?id=152327 this bug report].
* An icon set on a [Q]PushButton is not drawn respecting QAbstractButton::abstractSize() - look at the user pic selector in kcmshell4 kdm->Users.
* On a menu, it is not possible to see which menu is actually active.
::See [http://bugs.kde.org/show_bug.cgi?id=152123 this bug report]
* In Beta4, it seems that the WinDeco doesn't yet get the color scheme from the kcm color module. i.e., changing the active/inactive window colors doesn't seem to actually work.
* In (double) spinboxes the font is positioned one pixel too high. Lowering it one makes it baseline-aligned with labels in front. Unfortunately not possible 
: what about altering the size hints so the whole widget moves down? Trouble is we want them to be the same size as editable comboboxes and lineedits and buttons so those line up. The 1px wrong placement of text is a qt weirdness that gives visual bugs when we try to work around it - believe me - I've spent several hours on this.
* The ok and cancel buttons on dialogs (so called 'control buttons') don't have the same width. Not a style problem 
* Centered group titles pose several problems. Left align group titles instead. See Discussion for more details.
* Window decoration scales the menu icons down resulting in the icons blurring. Interestingly in the kwindecoration kcmshell the preview shows the 16x16/mimetypes/unknown.png icon at its correct 16x16 size, but as soon as the use the deco for real, it starts blurring them. (This is also true for KDE4's Plastik deco). [[User:Djmdave|Djmdave]] 22:26, 28 October 2007 (CET)
* Dockers; the title is positioned too far to the left and it runs into the rounded-border

== Known Bugs ==
* tabs
** east and west aren't done at all priority
** small glitches in filling inactive tabs priority
** tab bar edge should extend full length of widget releasable
* Dockers
** frame when floating should have rounded corners releasable
* KHTML integration
** khtml makes illegal assumptions about buttons. Awaits patch review by Maxim showstopper
* "flat" buttons drawn same as regular buttons releasable
* KLineEdit
** stylesheets ruin the look. Aseigo says to wait for qt fix showstopper
* Holes in general
** need bigger margins so shadow/glow are not lost?
** fix non-rounded corners when filling (at least) lineedits priority
** with autoFillBackground, corners are overpainted (how to fix this??) priority
* QToolBox not drawn showstopper
* need to audit color role use (see QA #3) showstopper
* Reverse layout is broken
** listview,tablevies paint the frame in LTR place Qt issue 137304 releasable
* progress bars still not like the artist wants priority
* menus not done releasable
** KMenu::addTitle() adds a widget action to display a title in a popup menu. This is not specific to Oxygen, but the widget it creates could use some polishing. (to see this, right click any icon in the system tray)
* windeco
** corners should really be alpha transparent releasable
* should repaint on globalChange signal (how?) releasable
** this seems to only be a problem for the colors kcm, may not even be a style bug
*headers in tables
**not really done - but the plain color look is acceptable for now releasable
* checkboxes in Q3ListView (Kontact-ToDo) are broken releasable
* Groupboxes
** does not report a minimum size that allows it to show the text on the box. I.e. a groupbox with no contents, the groupbox-title is clipped. releasable
* Buttons on KNewStuff download dialog do not appear

== QA ==
* reverse layout
* high-contrast color schemes (i.e. all fg/bg black or white)
* reverse-light/dark color schemes (e.g. light-on-dark buttons with dark-on-light views, etc.)
* tabs, in all directions
* no gray space between scrollbar and the text area it controls.
* sliders, scrollbars, progress - in all orientations and good cross section of values
* content padding works for all controls, does not break sizeToContents functionality
* controls align nicely and controls that should be the same size, are
* no obvious glitches in uidemo

[[Category:Artwork]][[Category:Oxygen]]

Projects/Oxygen/StyleWinDec

2007-12-01T21:12:27Z

Zander: icon != indicator

The current Oxygen style and window decoration for KDE4 can be found in SVN under http://websvn.kde.org/trunk/KDE/kdebase/runtime/kstyles/oxygen and http://websvn.kde.org/trunk/KDE/kdebase/workspace/kwin/clients/oxygen

== Visitors ==
Add new bugs to [[#Incoming_New_Bugs|Incoming New Bugs]], and we (the developers) will move it down and prioritize.

Note: we may move invalid bugs may be moved to the discussion page, along with a reason why they won't be fixed [by us].

DO NOT EDIT OTHER SECTIONS WITHOUT PERMISSION. This page has now been protected due to unauthorized edits. If you need to leave a comment anonymously, do it on the discussion page and/or talk to us on #oxygen.

== Incoming New Bugs ==
* When the tabbar has many tabs, so that not all of them can be shown at once, arrow buttons are drawn to navigate to the other tabs. These arrows are painted incorrectly, see [http://bugs.kde.org/show_bug.cgi?id=152327 this bug report].
* An icon set on a [Q]PushButton is not drawn respecting QAbstractButton::abstractSize() - look at the user pic selector in kcmshell4 kdm->Users.
* On a menu, it is not possible to see which menu is actually active.
::See [http://bugs.kde.org/show_bug.cgi?id=152123 this bug report]
* In Beta4, it seems that the WinDeco doesn't yet get the color scheme from the kcm color module. i.e., changing the active/inactive window colors doesn't seem to actually work.
* In (double) spinboxes the font is positioned one pixel too high. Lowering it one makes it baseline-aligned with labels in front. Unfortunately not possible 
: what about altering the size hints so the whole widget moves down? Trouble is we want them to be the same size as editable comboboxes and lineedits and buttons so those line up. The 1px wrong placement of text is a qt weirdness that gives visual bugs when we try to work around it - believe me - I've spent several hours on this.
* The ok and cancel buttons on dialogs (so called 'control buttons') don't have the same width. Not a style problem 

* Centered group titles pose several problems. Left align group titles instead. See Discussion for more details.

* Window decoration scales the menu icons down resulting in the icons blurring. Interestingly in the kwindecoration kcmshell the preview shows the 16x16/mimetypes/unknown.png icon at its correct 16x16 size, but as soon as the use the deco for real, it starts blurring them. (This is also true for KDE4's Plastik deco). [[User:Djmdave|Djmdave]] 22:26, 28 October 2007 (CET)

== Known Bugs ==
* tabs
** east and west aren't done at all priority
** small glitches in filling inactive tabs priority
** tab bar edge should extend full length of widget releasable
* Dockers
** frame when floating should have rounded corners releasable
* KHTML integration
** khtml makes illegal assumptions about buttons. Awaits patch review by Maxim showstopper
* "flat" buttons drawn same as regular buttons releasable
* KLineEdit
** stylesheets ruin the look. Aseigo says to wait for qt fix showstopper
* Holes in general
** need bigger margins so shadow/glow are not lost?
** fix non-rounded corners when filling (at least) lineedits priority
** with autoFillBackground, corners are overpainted (how to fix this??) priority
* QToolBox not drawn showstopper
* need to audit color role use (see QA #3) showstopper
* Reverse layout is broken
** listview,tablevies paint the frame in LTR place Qt issue 137304 releasable
* progress bars still not like the artist wants priority
* menus not done releasable
** KMenu::addTitle() adds a widget action to display a title in a popup menu. This is not specific to Oxygen, but the widget it creates could use some polishing. (to see this, right click any icon in the system tray)
* windeco
** corners should really be alpha transparent releasable
* should repaint on globalChange signal (how?) releasable
** this seems to only be a problem for the colors kcm, may not even be a style bug
*headers in tables
**not really done - but the plain color look is acceptable for now releasable
* checkboxes in Q3ListView (Kontact-ToDo) are broken releasable
* Groupboxes
** does not report a minimum size that allows it to show the text on the box. I.e. a groupbox with no contents, the groupbox-title is clipped. releasable
* Buttons on KNewStuff download dialog do not appear

== QA ==
* reverse layout
* high-contrast color schemes (i.e. all fg/bg black or white)
* reverse-light/dark color schemes (e.g. light-on-dark buttons with dark-on-light views, etc.)
* tabs, in all directions
* no gray space between scrollbar and the text area it controls.
* sliders, scrollbars, progress - in all orientations and good cross section of values
* content padding works for all controls, does not break sizeToContents functionality
* controls align nicely and controls that should be the same size, are
* no obvious glitches in uidemo

[[Category:Artwork]][[Category:Oxygen]]

Schedules/KDE4/4.0 Upstream Issues

2007-12-01T17:40:38Z

Zander: /* Qt4 */

{{Box|Upstream Issues HotList|Listed below are various upstream issues that are considered release critical problems. This is not a bug tracker or meant to supplant one, but to keep a running tally of open upstream issues we need to address for KDE4 releases.}}

== Qt4 ==
* '''Problem''': CSS currently resets fonts in widgets when used, making it very difficult to use with widgets where fonts are set programmatically as done throughout KDE.
** Affects: All widgets using CSS, such as the Konqueror location bar when using CSS to set an offset for the clear button.
** Solution: Pending; perhaps a CSS value (font: QWidget?) that prevents the style sheet from resetting fonts outside of what the widget is doing. Can be done currently on a case-by-case basis by overriding changeEvent, intercepting font changes and updating CSS strings containing the font desired; this is error prone (easy to trigger infinite loops) and seems sub-optimal.
** Status: upstream is investigating solutions.

* '''Problem''': Designer converts WhatsThis text to richtext blocks
** Affects: translators who get opaque blocks of html code
** Solution: None yet
** Status: Fixed for Qt4.4, patch being reviewed for qt-copy
** [http://trolltech.com/developer/task-tracker/index_html?id=187205&method=entry Upstream tracker link]

== Xine ==
* '''Problem''': short Oggs are not played properly
** Affects: Phonon playing short sounds, therefore all audio notification in KDE
** Solution: Patch being worked on by Matthias Kretz, needs to be upstreamed to libxine
** Status: Pending patch completion and approval

== gcc 4.3 ==
* '''Problem''': gcc 4.3 is expected to be released around the same time as KDE 4.0. Current gcc 4.3 SVN snapshots miscompile KDE 4.0 snapshots, causing core applications like plasma and konqueror to crash on startup.
** Status: small, self-contained test case is needed

Projects/Oxygen/StyleWinDec

2007-11-27T11:39:40Z

Zander: /* Incoming New Bugs */

The current Oxygen style and window decoration for KDE4 can be found in SVN under http://websvn.kde.org/trunk/KDE/kdebase/runtime/kstyles/oxygen and http://websvn.kde.org/trunk/KDE/kdebase/workspace/kwin/clients/oxygen

== Visitors ==
Add new bugs to [[#Incoming_New_Bugs|Incoming New Bugs]], and we (the developers) will move it down and prioritize.

Note: we may move invalid bugs may be moved to the discussion page, along with a reason why they won't be fixed [by us].

DO NOT EDIT OTHER SECTIONS WITHOUT PERMISSION. This page has now been protected due to unauthorized edits. If you need to leave a comment anonymously, do it on the discussion page and/or talk to us on #oxygen.

== Incoming New Bugs ==
* When the tabbar has many tabs, so that not all of them can be shown at once, arrow buttons are drawn to navigate to the other tabs. These arrows are painted incorrectly, see [http://bugs.kde.org/show_bug.cgi?id=152327 this bug report].
* A QRadioButton in the oxygen style does not report the size of the icon through iconSize() correctly; when using the iconSize() the painted button will be cut off.
* An icon set on a [Q]PushButton is not drawn respecting QAbstractButton::abstractSize() - look at the user pic selector in kcmshell4 kdm->Users.
* On a menu, it is not possible to see which menu is actually active.
::See [http://bugs.kde.org/show_bug.cgi?id=152123 this bug report]
* In Beta4, it seems that the WinDeco doesn't yet get the color scheme from the kcm color module. i.e., changing the active/inactive window colors doesn't seem to actually work.
* In (double) spinboxes the font is positioned one pixel too high. Lowering it one makes it baseline-aligned with labels in front. Unfortunately not possible 
: what about altering the size hints so the whole widget moves down? Trouble is we want them to be the same size as editable comboboxes and lineedits and buttons so those line up. The 1px wrong placement of text is a qt weirdness that gives visual bugs when we try to work around it - believe me - I've spent several hours on this.
* The ok and cancel buttons on dialogs (so called 'control buttons') don't have the same width. Not a style problem 

* Centered group titles pose several problems. Left align group titles instead. See Discussion for more details.

* Window decoration scales the menu icons down resulting in the icons blurring. Interestingly in the kwindecoration kcmshell the preview shows the 16x16/mimetypes/unknown.png icon at its correct 16x16 size, but as soon as the use the deco for real, it starts blurring them. (This is also true for KDE4's Plastik deco). [[User:Djmdave|Djmdave]] 22:26, 28 October 2007 (CET)

== Known Bugs ==
* tabs
** east and west aren't done at all priority
** small glitches in filling inactive tabs priority
** tab bar edge should extend full length of widget releasable
* Dockers
** frame when floating should have rounded corners releasable
* KHTML integration
** khtml makes illegal assumptions about buttons. Awaits patch review by Maxim showstopper
* "flat" buttons drawn same as regular buttons releasable
* KLineEdit
** stylesheets ruin the look. Aseigo says to wait for qt fix showstopper
* Holes in general
** need bigger margins so shadow/glow are not lost?
** fix non-rounded corners when filling (at least) lineedits priority
** with autoFillBackground, corners are overpainted (how to fix this??) priority
* QToolBox not drawn showstopper
* need to audit color role use (see QA #3) showstopper
* Reverse layout is broken
** listview,tablevies paint the frame in LTR place Qt issue 137304 releasable
* progress bars still not like the artist wants priority
* menus not done releasable
** KMenu::addTitle() adds a widget action to display a title in a popup menu. This is not specific to Oxygen, but the widget it creates could use some polishing. (to see this, right click any icon in the system tray)
* windeco
** corners should really be alpha transparent releasable
* should repaint on globalChange signal (how?) releasable
** this seems to only be a problem for the colors kcm, may not even be a style bug
*headers in tables
**not really done - but the plain color look is acceptable for now releasable
* checkboxes in Q3ListView (Kontact-ToDo) are broken releasable
* Groupboxes
** does not report a minimum size that allows it to show the text on the box. I.e. a groupbox with no contents, the groupbox-title is clipped. releasable
* Buttons on KNewStuff download dialog do not appear

== QA ==
* reverse layout
* high-contrast color schemes (i.e. all fg/bg black or white)
* reverse-light/dark color schemes (e.g. light-on-dark buttons with dark-on-light views, etc.)
* tabs, in all directions
* no gray space between scrollbar and the text area it controls.
* sliders, scrollbars, progress - in all orientations and good cross section of values
* content padding works for all controls, does not break sizeToContents functionality
* controls align nicely and controls that should be the same size, are
* no obvious glitches in uidemo

[[Category:Artwork]][[Category:Oxygen]]

Schedules/KDE4/4.0 Upstream Issues

2007-11-27T11:17:51Z

Zander: /* Qt4 */

{{Box|Upstream Issues HotList|Listed below are various upstream issues that are considered release critical problems. This is not a bug tracker or meant to supplant one, but to keep a running tally of open upstream issues we need to address for KDE4 releases.}}

== Qt4 ==
* '''Problem''': CSS currently resets fonts in widgets when used, making it very difficult to use with widgets where fonts are set programmatically as done throughout KDE.
** Affects: All widgets using CSS, such as the Konqueror location bar when using CSS to set an offset for the clear button.
** Solution: Pending; perhaps a CSS value (font: QWidget?) that prevents the style sheet from resetting fonts outside of what the widget is doing. Can be done currently on a case-by-case basis by overriding changeEvent, intercepting font changes and updating CSS strings containing the font desired; this is error prone (easy to trigger infinite loops) and seems sub-optimal.
** Status: upstream is investigating solutions.

* '''Problem''': Designer converts WhatsThis text to richtext blocks
** Affects: translators who get opaque blocks of html code
** Solution: None yet
** Status: Pending
** [http://trolltech.com/developer/task-tracker/index_html?id=187205&method=entry Upstream tracker link]

== Xine ==
* '''Problem''': short Oggs are not played properly
** Affects: Phonon playing short sounds, therefore all audio notification in KDE
** Solution: Patch being worked on by Matthias Kretz, needs to be upstreamed to libxine
** Status: Pending patch completion and approval

== gcc 4.3 ==
* '''Problem''': gcc 4.3 is expected to be released around the same time as KDE 4.0. Current gcc 4.3 SVN snapshots miscompile KDE 4.0 snapshots, causing core applications like plasma and konqueror to crash on startup.
** Status: small, self-contained test case is needed

Contribute/Bugsquad/KrushDays

2007-11-09T11:59:41Z

Zander: Move issue to proper place, there is no KDEPrint.

{{Box|KDE4 Krush Days|Join us Saturdays on irc in the #kde4-krush channel to work out release critical issues for KDE 4.0. Testers, artists, documenters and programmers are all welcome and encouraged to join in on the fun. Issues that are identified and being worked on will be added to this community scratchpad page.}}{{Box|Note|
* Please attach you nickname in irc when you add a bug to this page.
*In order to mark a bug as fixed please use <nowiki><s></s></nowiki>-tags and mention the revision number(s) of this fix.}}

{{Box|Crash Backtraces|
Do not use <nowiki>http://rafb.net/paste/</nowiki> for your crash backtraces, because those paste URLs there will expire after 24 hours.

Please use [http://pastebin.ca/ http://pastebin.ca/] for crash backtraces and add a link to your paste when you add the crash to the list below.

A backtrace is generally very helpful for developers to identify the reason for the crash. To get good backtraces, read [[Development/Tutorials/Debugging/How_to_create_useful_crash_reports|this article]].
}}

==== Screen Locker (krunner_lock) ====
* unlocking the session is impossible as I get "wrong password" (logixoul) (confirmed by goliath23)
** prolly installed as user - kcheckpass requires setuid root
* enabling and disabling capslock in the "unlock session" dialog doesn't hide the red "Warning: capslock enabled" label (logixoul) (works fine for TunaTom [rev 731731])

==== Packaging ====
* share/icons/oxygen/22x22/actions/kscd-dock.png is installed by both kdebase and kdemultimedia (jstubbs)

==== Konsole ====

* Selecting text in the default color scheme gives black-on-black selections (jstubbs)(confirmed by annma)(not reproducible by TunaTom)
* None of the Alt+<letter> menu shortcuts work when the terminal has focus (apaku) (confirmed by TunaTom)
* Wish: Could the links be not clickable as an option? it really goes on the way as it makes copy/paste too difficult when a link is present in the copied text (annma)
* crashes when clicking on a link, but konqueror opens successfully ([C]167
* Changes made with "Edit Current Profile::Appearance" are not
saved. (JRT)
*"Edit Font" isn't restricted to only monospace fonts. (JRT)

==== Dolphin ====
* <s>Restoring a deleted item from the trash crashes dolphin/konqueror (mbiebl)</s>
** Fixed by Sergej Melderis and David Faure (Peter Penz)
* The "Desktop" and "Root" icons in dolphin have a completely different style than the usual folder icon. (mbiebl)
* <s>Dolphin has no proper icon in taskbar/window decoration. (mbiebl)</s>
** fixed. (logixoul)
* Select icon in folder/file properties doesn't show the icons of the selected categories at first. Only after changing the combobox the icons are loaded. (bbroeksema)(I can confirmed that [TunaTom r732119])
* <s>Edit Locations (F6) doesn't work as expected. Currently it only switches to edit mode and focuses the location bar if it's in navigation mode, otherwise it doesn't do anything. (Mogger)</s>
** For me, it switches from navigation to edit mode and focuses as well [TunaTom r732119]
*** Yeah same for me, sorry for being unclear. Edited now. (Mogger)
**** Thanks for the report, this issue is fixed now :-) (Peter Penz)
* no option for 'select on hover' (emilsedgh)
* <s>cannot show thumbnails (it was showing the thumbnails when konqueror was unable to show them, so seems a different bug with konqueror's "cannot show preview" bug, also file properties->preview hasnt the preview anyymore) (emilsedgh)</s>
** fixed by mlaurent (logixoul)
* "Empty Trash" does not show up in the file menu when viewing the trash (yuriy)
** Application menus should never be changed dynamically. So an option would be showing "Empty Trash" always. From my point of view using the context menu is enough (at least I'm not aware about any file manager that has "Empty Trash" as part of the file-menu). For further discussions please mail me directly (peter.penz@gmx.at) or just use the kfm-devel mailing list. Thanks! (Peter Penz)
* Several of the F1-F11 do not show up in the "Configure Shortcuts" dialog (e.g. F4) (gissi)
* Inconsistency (IMHO): F4 in dolphin behaves different than in Konqueror (terminal panel vs. terminal in new window) (gissi)
* It can only configure mimetype associations individually via properties on a file, and later clicking on a small settings button. To configure mimetypes globally, and not file related, it has to be done with Konqueror settings, as there is no such entry in SystemSettings. IMHO Dolphin or SystemSettings should also get the Konqueror's File association settings panel. (q3xr2).
* <s>When moving a hidden file to trash this file is not shown in trash. However, it is in ~/.local/share/Trash, so it's not lost. The problem is probably that kiotrash ignores hidden files. (gissi, confirmed by JustinNoel, luca_b and logixoul)</s>
** Fixed by Sergejs Melderis and David Faure (Peter Penz)
* When you delete Trash from sidebar, you can't get it back. (amp)

==== Phonon ====
* Can't get any sound to work. Chosen backend is xine. Tried to play an mp3 in juk. juk says its playing, but I get no sound. (mbiebl)

==== Juk ====
* Too much colums in default setting. Not a bug but a bad looking thing. (frank95com)

==== Oxygen ====
* Missing icons for "Appearance" and "Desktop" in systemsettings. (mbiebl)
* Visual glitches in Oxygen: tabs in konqui, progressbar in dolphin. (mbiebl)
* konsole, Oxygen: the arrows of the right scrollbar are not visible (black on black). (mbiebl)
* Chanel icons in KMix could use some Oxygenification (JLP)
* Too little contrast in the window-list from alt-tab shortcut, people with only slight visual problems won't be able to see the difference between selected/not selected (apaku)
* Buttons inside konqueror are not drawn properly, text labels are off and often are missing completely. This doesn't happen with plain Qt style, but also with Plastik (apaku)

==== Plasma ====

* The taskbar doesn't remember the position of the clock plasmoid. (mbiebl)
* The network plasmoid does not automatically selet the active network connection (It uses eth0 by default, but I use wlan0 mostly) (mbiebl)
* systemtray: starting one juk instance shows two identical icons in the systray.
* with the plasma toolbox, clicking "add widgets" but releasing the mouse button elsewhere still activates it. (jstubbs)
* hovering the plasma toolbox for the first time after cleaning config makes buttons slide in from TOP-LEFT rather than TOP-RIGHT. Every subsequent hovering works correctly. (logixoul)
* can't move panel plasmoids. (logixoul)
* can't put pager or systray on panel. (logixoul)
* systray on desktop has no border. (logixoul)
* MinimizeAnimation doesn't animates correctly to the taskbar, with Kicker it works fine (Plasma should tell KWin where the taskbar-entry is) (boom1992)
* The dictionary plasmoid doesn't show the results. (Mogger)
** Looks like fixed in r732655, shows the result, but first changes the box with animation, then changes the result text, also its a bit slow (emilsedgh)
* krunner hangs on each and every letter typed in after some time working in a kde4 desktop. May be related to manual killing the strigidaemon which goes nuts on CPU usage. Output from console: http://www.apaku.de/vardata/krunner_output_hang (apaku)
* notes applet should be resized when the text is bigger that current size (emilsedgh)
* Colorpicker and Kickoff plasmoid don't have context menu, so they can't be removed. (TunaTom)
** context menus are going to be replaced by hover-action-icons (ivan)
** Lancelot now has context menu and is (re)movable (emilsedgh)
* Running plasma with QT_FLUSH_PAINT I can see lots of extra repainting. For example the panel is very bad. (rich)
* Plasma is shown in the Alt+Tab windowlist, this should not happen (especially since switching to this app then does nothing visually except lose focus from the toplevel window) (BCoppens)
* Analog Clock: add text & seconds indicator. Change size to 400. Is so SLOW that it easily skips 3 seconds per redraw! (Core2 Duo 2.20GHz, Quadro FX 570M, nvidia binary drivers, Thinkpad T61p) (BCoppens)
* Digital clock is useless by its inconfigurability: I'm not interested in a disorganized list of timezones, no, I want a) the date underneath, b) a less fancy digital font instead of the current one with the distracting 'line' in the middle. (BCoppens)
**The date format is not affected by the settings in KControl.<JRT>
** Time Zone list should be redundant in configuration since the TZ should be set in KControl. All that is needed is an option to display it. Note, I think that this is the standard timezone list. If what is wanted is an option to display a TZ other than the user's TZ, this should be a separate context menu item. <JRT>
* The Lock/Logout Widget has rectangular buttons -- should have square? IAC, icons should be centered on buttons. <JRT>
*System Tray Widget doesn't work correctly: The Widget doesn't size itself to hold the contents. The contents seem to have the wrong X display priority (they are always on top). It (the contents, not the widget) interacts with windows (snap). The contents are only displayed on Desktop #1. When something triggers a refresh of something, then the SystemTray widget resizes and looks correct but the icons are still not working correctly. They are only on DeskTop #1 and always on top. <JRT>
*The Application Launcher Widget seems to be stuck in the middle of the screen; I can't drag it. In this position with 1024x768 the menu window does not open correctly. It extends beyond the top of the screen and is cut off. <JRT>
*The Clock on the Panel slides over and winds up on top of the TaskBar on the Panel.<JRT>

==== Plasma - Kickoff 'Start Menu' ====

* Unable to resize the kickoff menu. (mbiebl)
* Kickoff opens konqueror when clicking on an entry under "My Computer". (mbiebl)
* In kickoff, clicking the utilities menu and then clicking back again shows the top menu scrolled to the top rather than where it was before clicking utilities. (jstubbs)
** Confirmed. Additional strange bahaviour: When opened by clicking on a link in "Storage" for example, Konqueror shows the contents of "/" in an unnamed tab. Right of that tab is another one showing the correct location. If you click that tab, konqeuror crashes. (goliath23)
* Kickoff: Clicking the applications tab, when the tab is open should return it to top-level.Current catalog-memory is a good feature however, so keep that aswell. (eirik_)
* Kickoff does not start firefox. It loads the .desktop file in kwrite (amp)

==== System Settings ====
* systemsettings has no menu entry. Typing it into kickoffs search entry doesn't find/list it either. (mbiebl)
* When clicking on "Appearance", it seems to delete a file. http://rafb.net/p/zzS2fM55.html (Mogger)
**When I select "Appearance" in "System Settings", three "Progress Dialog" boxes pop up.<JRT>
* Missing "get root rights" button on pages like Date/Time, thus its impossible to change such settings (apaku)
* Searching something doesn't seem to limit the displayed modules or highlight any of the search results.
* no settings to be changed for keyboard shortcuts - everything is empty (nixternal)
**This is probably a function of your system configuration. IIUC,It reads an X11 file. <JRT>
* When clicking e.g. "Appearance", the System Settings window doesn't get resized. This causes very ugly (horizontal and vertical) scrollbars (gissi)
* Default size for the text beneath the icons is too small. I see stuff like 'ppearanc' instead of 'Appearance' and 'ccesibilit'. Some other texts are wide enough, like 'Splash Screen'. (BCoppens)
* Changing the style to Oxygen changes all windows, EXCEPT the System Settings (BCoppens)
*Regional & Language::Time & Dates (should that be "Time & Date"?) doesn't have USA style date formats in "Short date format": MM.DD.YYYY & mM.dD.YYYY and should also have formats with only 2 digits for year: YY.

==== KMix ====
* <s>m_qcb->blockSignals( true ); where m_qcb is null from MDWSlider::updateInternal during kmix startup http://pastebin.ca/759601 (jstubbs)</s> Fixed by SVN commit [http://websvn.kde.org/?view=rev&revision=732246 732246]
* <s>Right click on KMix icon in system tray, select master channel, dialog comes up empty, when you close it KMix icon disappears from the tray (JLP)</s> Fixed by SVN commit [http://websvn.kde.org/?view=rev&revision=732367 732367]

==== KWin ====
* Windows are not fully redrawn when minimizing and then restoring with OpenGL compositing in use (jstubbs)
* the compositing KCM should provide an easy way to enable the COMPOSITE extension (logixoul)
* <s>Menu shadows are being left on the desktop (but not on windows, it seems) (Mogger)</s> Fixed by SVN commit [http://websvn.kde.org/?view=rev&revision=732268 732268]
* Sometimes (tested with Konsole, X.org 7.3, latest nvidia drivers and a Geforce 5900XT), the clicked menus are not displayed and KWin crashes. Backtrace : [http://rafb.net/p/zmYj1980.html] (idem)
* After a while the alt-tab window list is completely missing though I can still switch between windows with alt+tab (apaku)
* alt+tab only allows to switch between windows on the same screen in a multihead setup, its impossible to activate a window on another screen (though its on the same virtual X11 desktop) (apaku)
* alt+tab (without compositing) shows a list of windows but no indication which window in this list is selected when cycling through them. (goliath23)
* KWin does not detect compositing ability on my pc with a GeForce 7600 GS (driver version 100.14.19) (goliath23)
* The Composite Effect 'Demo Liquid' crashes KWin (BCoppens)
* 'Scale In' effect also scales in Menus and Dropdown boxes from the 'middle' of their target area, this is ugly. Either don't do that for such windows, or let them scale in from their topleft corner (BCoppens)
* Alt+Shift+Tab for backwards scrolling through Alt+Tab shortcut is not assigned, but I can't remember if this was the case in KDE3 as well or not... (BCoppens)
*Moving windows with "Display Content" turned off does not display an empty frame. (using an OpenSource driver)<JRT>

==== KNS ====
* KNS uses 100% CPU when 550 is enabled in kdebugdialog (jstubbs)
* Sometimes KNS dialog is under Settings dialog (Kanagram and KStars) modal/non-modal issue when KNS is invoked from a Config dialog (jstubbs)

==== KHangMan ====
* <s>"Already Guessed" tooltip timer does not work.</s> FIXED annma r732068
* <s>When changing the "Already Guessed" tim in Config, the current word should stay (KHangMan jumps to a new word).</s> FIXED annma r732068
* After typing an already typed letter, the focus is left on the guess "button", which means I have to press tab to get back to the letter entry field. If we enable the focus back before tooltip is hidden, it means the tooltip has to be hidden when a new letter is entered. (jstubbs)
** annma: intented behaviour is that the input is impossible why popup is shown. To leave the kid the time to understand what he is doing. Messing with the tooltip now seems bad to me. It's a WON'T FIX until we have it tested with kids ;) sorry jstubbs!
* <s>See if the font progressbar can disappear after first run (jstubbs)</s>
** annma: Removing your ~/.fonts/d dustismo_roman.ttf will make the bug go away. The font will reinstall and then it'll be found. Not sure why it happened...
* Test what happens for the fonts when no internet connection (jstubbs)
* Wish: when using the Special chars toolbar, letters should go immediatly in the word or in Missed. Annma is not sure this would work with kids, they maybe won't understand what happens. (jstubbs)
** annma: maybe a config option for KDE 4.1 as we are in feature freeze now.
* Language combo in toolbar does not resize correctly when changing language. (jstubbs)
* <s>Right-clicking "Type accented letters" does not offer the context sensitive help when the option is disabled. (jstubbs)</s>
** annma: this is from Qt, it's default behaviour for QWhatsThis help.

==== Kiten ====
* Searching for "one" takes a long time to process, during which the application blocks without any feedback. (jstubbs)
* From the Search menu, selecting Search {with Beginning of Word, Anywhere}, Grade or Strokes does not seem to have any affect (jstubbs)
* Selecting Verb or Noun from the grammatical element dropdown does not seem to have any affect (jstubbs)

==== KBruch ====
* In fraction tasks, the denominators used sometimes exceed the max denominator that is set. (jstubbs) r732343 attempted to fixe it but not totally

==== KPercentage ====
* <s>When starting a new set of tests, and on various other actions, the window unnecessarily moves to the centre of the screen (jstubbs)</s> Fixed r732700

==== KGeography ====
* <s>Intermittent crash after a placing state on a map (jstubbs)</s> Fixed r732331 (tsdgeos)
* <s>Selecting zoom when placing state on a map leaves the cursor as the state to be placed - perhaps the cursor should change back to a pointer while in zoom mode? (jstubbs)</s> Fixed r732314 (tsdgeos)
* With KWin's dimming of inactive windows, it is difficult to relate the colors signfying right/wrong answers back to the map (jstubbs)

==== KmPlot ====
* Editing function does not work as if Enter is not doing anything (rivo, gissi and idem-kde4) Annma cannot reproduce.
**Note by gissi: For me, only editing a cartesian plot doesn't work, the others work as expected. Don't know wether that's the same for rivo and idem.

==== KMail ====
* Creating a new Imap Account and press "Check what the Server Supports" in Security crashes KMail. Stacktrace / ConsoleLog at http://pastebin.ca/759562 (voltaire)
:: This is probably a KSSL problem, which will be fixed when the new KSSL arrives in kdelibs --[[User:TMG|TMG]] 00:03, 4 November 2007 (CET)
* <s>If I open a link from an email it opens it but then it crashes - Backtrace http://pastebin.ca/759997 (frank95com)</s>
:: <s>This is a kdelibs (krun) bug, it happens in other apps, like Konsole, as well</s> --[[User:TMG|TMG]] 00:03, 4 November 2007 (CET)
:: Fixed in kdelibs --[[User:TMG|TMG]] 21:27, 6 November 2007 (CET)
*When an IMAP server stops responding KMail popups up the "IMAP Disconnected" dialog with an "Ok" button. Clicking "Ok" crashes KMail. Stack Trace: http://www.pastebin.ca/759969 (JustinNoel)
* KMail initial account wizard. A process related to the KMail initial setup wizard crashes when "Check for supported security capabilites on..." appears. Console spew suggests something crashed. KMail starts with an IMAP account with an incorrect security configuration. Description/Reproduction Steps/Console Spew: http://www.pastebin.ca/760052 Needs verification as I only have one IMAP server to try. (Justin Noel)
:: Seems like the same bug above, the one reported by voltaire. --[[User:TMG|TMG]] 00:03, 4 November 2007 (CET)
* KMail with disconnected IMAP: after customizing options and restart, it crashes on startup http://pastebin.ca/764484 ([[User:Lure|Lure]] 09:07, 7 November 2007 (CET))

==== Build issue ====
* <s>in kdebase when OpenGL is not found, cmake stops with "CMake Error: This project requires some variables to be set, and cmake can not find them. Please set the following variables: OPENGL_gl_LIBRARY (ADVANCED)" so there is a bad check somewhere in kdebase (annma, issue of frank95com, http://pastebin.ca/759575). Possible patch: http://pastebin.ca/759603 (annma). Other possible patch by ThomasZ: http://pastebin.ca/759605</s> fixed svn r733932
* In kdebase on OS X 10.5 the build WITH_XKB = OFF variable is not respected resulting in failure of the build. (build process info found at http://techbase.kde.org/Getting_Started/Build/KDE4/Mac_OS_X_10.5_issues) Sorry it's so wordy, but I initially wrote it up for personal use.

==== Kolf ====
* The direction and velocity marker flickers and often cannot be seen. Using opengl compositing. (jstubbs)

==== KDElibs ====
* <s>The tab order of the configure shortcuts dialog is incorrect. (Mogger)</s> Fixed by SVN commit [http://websvn.kde.org/?view=rev&revision=732404 732404]''
* Drag and drop doesn't work in the configure toolbars dialog. (Mogger)
* Applications crash when downloading something. Traceback from Konsole when clicking on a link: http://rafb.net/p/1aiHyn63.html (Mogger)
** The link appears to be dead
* cannot write Right-To-Left...in kde3 when you start a line with a character of an rtl language, the line goes rtl automatically (emilsedgh)
* Configure shortcuts dialog is too small at start: I cannot see the action name at all (it says stuff like 'C...' instead of 'Close'). Furthermore, and much worse: I cannot change the width of the columns at all to try to make the action names readable! (BCoppens)

==== Konqueror ====
* Website http://kriptopolis.org it is really bad rendered, however it is fine with Konqueror 3.5.7. (q3xr2)
* often doesn't load pages properly, for example clicking the login link on a techbase page almost always gets me an empty page (apaku) (frank95com too, gruf too)
* <s>Cannot show thumbnails (emilsedgh)</s>
** fixed by mlaurent (logixoul)
* Up Button loads a different view, while back button doesn't, when walking through the filesystem. The up button loads a similar view to what you get in dolhpin, while the default view when typing in a local path is a plain iconview (apaku)
* When entering already visited directories, the animated logo doesn't stop. (Plain iconview instead of dolphin part?) (Mogger)
* Nothing in View -> Sort By, Additional Information, Panels, Navigation Bar submenus (yuriy)
* Nothing except "home folder" in home folder sidebar (yuriy)
* Some favicons do not appear in Konqueror's nav bar to titlebar. google.com and kubuntu.org works. kde.org, cnn.com and slashdot.org do not work. (JustinNoel)
* pressing ctrl+a when focus is on addressbar selects whole webpage instead of the text that is written in the addressbar (only on webpages: khtmlpart?) (emilsedgh)
* have to keep refreshing pages in order for them to display (nixternal)
* have quite a few problems trying to edit this page alone (nixternal)
* In file management mode it can't show hidden files, it doesn't have this option in the View menu, neither there is a shorcut available. (q3xr2)
* In HTML forms (such as the textbox to edit this wikipage with, or the username box), the initial fontsize is small. Once I click on the form, the font suddenly enlargens. Especially annoying with this editbox, since the place where you think you clicked changes after fontsize change (BCoppens)
* Asks nicely if it has to store my form data (such as password and username in the Wallet, but does not actually do so (BCoppens)
* Clicking on a link to an in-page 'tag' (the a href=#tag thing, like there are lots of in the index of this wiki page), results in konqueror showing the 'Drag link' mouse cursor (BCoppens)
* Not only do I get blank pages, but I get the following on trying to edit this wiki with Konqueror of KDE4: after sending in the changes, it shows a blank page. I press F5, and Konq asks me to resubmit form data. Wiki then shows an almost-empty edit page, with 'Sorry! We could not process your edit due to a loss of session data' (BCoppens)
* Start Konq. Press 'Next: An Introduction to Konqueror'. The page goes blank, and 'Previous page' also shows up blank. (BCoppens)
* With Konqui becoming webbrowser as primary task, it would make sense to redesign the start page altogether and remove stuff like Storage media, Trash etc. Show something like "Search the web" which points to a search engine, like Google, yahoo,...
* Start Konq. Enter '~'. Make a new tab (CtrlShift+N). Type something. Note how the cursor goes OVER the map icon, instead of starting next to it (BCoppens)
* (Different from the one above) Start Konq. Enter '~'. Make a new tab (CtrlShift+N). Enter '/'. Switch back to the first tab. It's caption suddenly changes from '/home/kde4/' to 'kde4'! Switching to the second tab, removes the '/' and makes that tab nameless) (BCoppens)
* Printing a html file from konqueror. The "HTML Settings" tab has an odd layout. It seems to miss a proper border. (mbiebl)

==== IO-slaves ====
* Browsing with IO-slaves that require autenthication is broken: SMB, FTP, SSH do not display anything after authentication is entered (luca_b, nixternal, yuriy).
* When adding RSA keys using fish:/, the buttons to accept/refuse are blank. (luca_b, yuriy)
* smb:/ ioslave causes crash (nixternal)
* smb:/ ioslave does not work with shares that need authentication. Console output: http://pastebin.ca/760196 (luca_b)
* kio_file: After a while I have 100% of CPU usage when running KDE4. top says, the process is kio_file, which is sometimes up to 4 times running (amp)
* The settings:/ ioslave (accessible through Settings on the welcome screen of Konq) does not work at all. For example, try Appearanc&Themes -> Fonts: it tries to open this with KWrite! (BCoppens)

==== Color KCM ====
* Changing the checkbox "Apply colors to non-KDE4 apps" doesn't trigger the changed signal and thus the apply button in systemsettings stays grayed out (apaku)
* the same as above applies to the whole Effects tab (apaku)

==== Kate ====
* Crash when going down page-wise with PageDn beyond the end of the file. Backtrace: http://www.apaku.de/vardata/kate_crash_pagedn (apaku)

==== Marble ====
* Navigate to Minneapolis (search is quick) and then zoom in until "saint paul" appears. Rotating up and down will now cause the text "saint paul" to jump around. (jstubbs)
* In full screen mode, clicking in the right half of the globe doesn't work. It seems that plasma is getting the events? (jstubbs)

==== Kinfocenter ====
* Most of the Items are empty (emilsedgh)

==== Kopete ====
* Adding an account a second time (same protocol, same user id as an existing) makes kopete crash (moi1392, idem-kde4). http://pastebin.ca/759660. More verbose fix in the works (Earthwings). http://lists.kde.org/?l=kopete-devel&m=119411618226111&w=2
* I can't get my Google Talk account to finish it's authentication process, however I can login without any troubles with my jabber.org account. I don't know if the trouble it's related to the SSL login or qca-tls which I have installed (q3xr2).
** Google Talk did not work before for me, but it works now (with today's SVN version), maybe you should retest with current SVN version.
*** It works now for me also! (q3xr2).
* Configure->Plugins results in consistent crash here http://pastebin.ca/764575 ([[User:Lure|Lure]] 12:34, 7 November 2007 (CET))

==== kfind ====
* kfind crashes when the find is stopped (by pressing "stop" button) during the find process (shaga)
* the stop button has to be pressed twice, the first click is lost (shaga)

==== Gwenview ====
* Random crashes when navigating to directories, or when editing the path manually. Backtrace http://pastebin.ca/760077 (luca_b)

==== Login Manager KCM ====
* There are numbers on the tabs (yuriy)
** yes - the kcm is too big to have non-clashing letter shortcuts.

==== kscd ====
* crashes when inserting a CD. Problem is an assert thats hit (apaku):
kscd(31228)/kdecore (KConfigSkeleton) KConfigSkeleton::readConfig: KConfigSkeleton::readConfig()
kscd(31228)/libkcddb KCDDB::Cache::lookup: Looking up "ae0cdb0e" in CDDB cache
kscd(31228)/libkcddb KCDDB::CDInfo::load: Loaded CDInfo for "ae0cdb0e"
kscd(31228)/libkcddb KCDDB::Client::lookup: Found 1 hit(s)
ASSERT: "info.numberOfTracks() == cddbInfo.numberOfTracks()" in file /home/andreas/KDE-work/4.0/kdemultimedia/kscd/kscd.cpp, line 753
* crashes when starting up (but not if the user does not have permissions to acces the cdrom) backtrace: http://pastebin.ca/760172 (yuriy)
==== KFontChooser ====
*It doesn't work correctly for the bit mapped fonts Fixed[Misc] & Fixed[Sony] which come with X11 are the best example of this since they might be used in Konsole. This is mainly a Konsole issue. <JRT>
**There should be only 2 sizes of Fixed[Sony] which works correctly in KDE3 it displays only two sizes. I'm not 100% clear on how this works if you have a screen resolution other than 75 or 100, but xfontsel lists two point sizes for 100 dpi: 12 & 17 and this agrees with the KFontSel dialog. But in KDE4 it lists the usual list of sizes from 4 to 64.
**There are several sizes of Fixed[Misc], according to xfonsel they are: 5, 6, 7, 8, 10, 11, 12, & 14. KDE has this fairly close to correct -- close enough that it works OK. It also lists 4 which may be a 75 dpi font and it lists 9 but not 12. Could these be rounding errors? IAC, KDE4 is the same as with Fixed[Sony], it has the standard list of 4 to 64.
*We need to first ask if this is a Qt bug/error as are other font issues.
**The Fixed{Misc} fonts are not a uniform set of fonts and I don't think that there is any way that Qt can deal with this issue.

==== Akregator ====
*Crashes while trying to delete a feed.
** Nickname and backtrace in pastebin.ca please

*Marking feeds or messages as Read does not work. The context menu in the feeds list reappear two times after the first select. Even when reading a message, it is not marked as read. ([[User:Kleag|Kleag]] 23:46, 7 November 2007 (CET))

==== Kontact ====
*Crashes starting the application.
::We need a backtrace, otherwise we can't do anything. It doesn't crash for us. --[[User:TMG|TMG]] 21:24, 6 November 2007 (CET)

Contribute/Bugsquad/KrushDays

2007-11-09T11:49:21Z

Zander: Don't link to the url we want people to avoid.

{{Box|KDE4 Krush Days|Join us Saturdays on irc in the #kde4-krush channel to work out release critical issues for KDE 4.0. Testers, artists, documenters and programmers are all welcome and encouraged to join in on the fun. Issues that are identified and being worked on will be added to this community scratchpad page.}}{{Box|Note|
* Please attach you nickname in irc when you add a bug to this page.
*In order to mark a bug as fixed please use <nowiki><s></s></nowiki>-tags and mention the revision number(s) of this fix.}}

{{Box|Crash Backtraces|
Do not use <nowiki>http://rafb.net/paste/</nowiki> for your crash backtraces, because those paste URLs there will expire after 24 hours.

Please use [http://pastebin.ca/ http://pastebin.ca/] for crash backtraces and add a link to your paste when you add the crash to the list below.

A backtrace is generally very helpful for developers to identify the reason for the crash. To get good backtraces, read [[Development/Tutorials/Debugging/How_to_create_useful_crash_reports|this article]].
}}

==== Screen Locker (krunner_lock) ====
* unlocking the session is impossible as I get "wrong password" (logixoul) (confirmed by goliath23)
** prolly installed as user - kcheckpass requires setuid root
* enabling and disabling capslock in the "unlock session" dialog doesn't hide the red "Warning: capslock enabled" label (logixoul) (works fine for TunaTom [rev 731731])

==== Packaging ====
* share/icons/oxygen/22x22/actions/kscd-dock.png is installed by both kdebase and kdemultimedia (jstubbs)

==== Konsole ====

* Selecting text in the default color scheme gives black-on-black selections (jstubbs)(confirmed by annma)(not reproducible by TunaTom)
* None of the Alt+<letter> menu shortcuts work when the terminal has focus (apaku) (confirmed by TunaTom)
* Wish: Could the links be not clickable as an option? it really goes on the way as it makes copy/paste too difficult when a link is present in the copied text (annma)
* crashes when clicking on a link, but konqueror opens successfully ([C]167
* Changes made with "Edit Current Profile::Appearance" are not
saved. (JRT)
*"Edit Font" isn't restricted to only monospace fonts. (JRT)

==== Dolphin ====
* <s>Restoring a deleted item from the trash crashes dolphin/konqueror (mbiebl)</s>
** Fixed by Sergej Melderis and David Faure (Peter Penz)
* The "Desktop" and "Root" icons in dolphin have a completely different style than the usual folder icon. (mbiebl)
* <s>Dolphin has no proper icon in taskbar/window decoration. (mbiebl)</s>
** fixed. (logixoul)
* Select icon in folder/file properties doesn't show the icons of the selected categories at first. Only after changing the combobox the icons are loaded. (bbroeksema)(I can confirmed that [TunaTom r732119])
* <s>Edit Locations (F6) doesn't work as expected. Currently it only switches to edit mode and focuses the location bar if it's in navigation mode, otherwise it doesn't do anything. (Mogger)</s>
** For me, it switches from navigation to edit mode and focuses as well [TunaTom r732119]
*** Yeah same for me, sorry for being unclear. Edited now. (Mogger)
**** Thanks for the report, this issue is fixed now :-) (Peter Penz)
* no option for 'select on hover' (emilsedgh)
* <s>cannot show thumbnails (it was showing the thumbnails when konqueror was unable to show them, so seems a different bug with konqueror's "cannot show preview" bug, also file properties->preview hasnt the preview anyymore) (emilsedgh)</s>
** fixed by mlaurent (logixoul)
* "Empty Trash" does not show up in the file menu when viewing the trash (yuriy)
** Application menus should never be changed dynamically. So an option would be showing "Empty Trash" always. From my point of view using the context menu is enough (at least I'm not aware about any file manager that has "Empty Trash" as part of the file-menu). For further discussions please mail me directly (peter.penz@gmx.at) or just use the kfm-devel mailing list. Thanks! (Peter Penz)
* Several of the F1-F11 do not show up in the "Configure Shortcuts" dialog (e.g. F4) (gissi)
* Inconsistency (IMHO): F4 in dolphin behaves different than in Konqueror (terminal panel vs. terminal in new window) (gissi)
* It can only configure mimetype associations individually via properties on a file, and later clicking on a small settings button. To configure mimetypes globally, and not file related, it has to be done with Konqueror settings, as there is no such entry in SystemSettings. IMHO Dolphin or SystemSettings should also get the Konqueror's File association settings panel. (q3xr2).
* <s>When moving a hidden file to trash this file is not shown in trash. However, it is in ~/.local/share/Trash, so it's not lost. The problem is probably that kiotrash ignores hidden files. (gissi, confirmed by JustinNoel, luca_b and logixoul)</s>
** Fixed by Sergejs Melderis and David Faure (Peter Penz)
* When you delete Trash from sidebar, you can't get it back. (amp)

==== Phonon ====
* Can't get any sound to work. Chosen backend is xine. Tried to play an mp3 in juk. juk says its playing, but I get no sound. (mbiebl)

==== Juk ====
* Too much colums in default setting. Not a bug but a bad looking thing. (frank95com)

==== Oxygen ====
* Missing icons for "Appearance" and "Desktop" in systemsettings. (mbiebl)
* Visual glitches in Oxygen: tabs in konqui, progressbar in dolphin. (mbiebl)
* konsole, Oxygen: the arrows of the right scrollbar are not visible (black on black). (mbiebl)
* Chanel icons in KMix could use some Oxygenification (JLP)
* Too little contrast in the window-list from alt-tab shortcut, people with only slight visual problems won't be able to see the difference between selected/not selected (apaku)
* Buttons inside konqueror are not drawn properly, text labels are off and often are missing completely. This doesn't happen with plain Qt style, but also with Plastik (apaku)

==== Plasma ====

* The taskbar doesn't remember the position of the clock plasmoid. (mbiebl)
* The network plasmoid does not automatically selet the active network connection (It uses eth0 by default, but I use wlan0 mostly) (mbiebl)
* systemtray: starting one juk instance shows two identical icons in the systray.
* with the plasma toolbox, clicking "add widgets" but releasing the mouse button elsewhere still activates it. (jstubbs)
* hovering the plasma toolbox for the first time after cleaning config makes buttons slide in from TOP-LEFT rather than TOP-RIGHT. Every subsequent hovering works correctly. (logixoul)
* can't move panel plasmoids. (logixoul)
* can't put pager or systray on panel. (logixoul)
* systray on desktop has no border. (logixoul)
* MinimizeAnimation doesn't animates correctly to the taskbar, with Kicker it works fine (Plasma should tell KWin where the taskbar-entry is) (boom1992)
* The dictionary plasmoid doesn't show the results. (Mogger)
** Looks like fixed in r732655, shows the result, but first changes the box with animation, then changes the result text, also its a bit slow (emilsedgh)
* krunner hangs on each and every letter typed in after some time working in a kde4 desktop. May be related to manual killing the strigidaemon which goes nuts on CPU usage. Output from console: http://www.apaku.de/vardata/krunner_output_hang (apaku)
* notes applet should be resized when the text is bigger that current size (emilsedgh)
* Colorpicker and Kickoff plasmoid don't have context menu, so they can't be removed. (TunaTom)
** context menus are going to be replaced by hover-action-icons (ivan)
** Lancelot now has context menu and is (re)movable (emilsedgh)
* Running plasma with QT_FLUSH_PAINT I can see lots of extra repainting. For example the panel is very bad. (rich)
* Plasma is shown in the Alt+Tab windowlist, this should not happen (especially since switching to this app then does nothing visually except lose focus from the toplevel window) (BCoppens)
* Analog Clock: add text & seconds indicator. Change size to 400. Is so SLOW that it easily skips 3 seconds per redraw! (Core2 Duo 2.20GHz, Quadro FX 570M, nvidia binary drivers, Thinkpad T61p) (BCoppens)
* Digital clock is useless by its inconfigurability: I'm not interested in a disorganized list of timezones, no, I want a) the date underneath, b) a less fancy digital font instead of the current one with the distracting 'line' in the middle. (BCoppens)
**The date format is not affected by the settings in KControl.<JRT>
** Time Zone list should be redundant in configuration since the TZ should be set in KControl. All that is needed is an option to display it. Note, I think that this is the standard timezone list. If what is wanted is an option to display a TZ other than the user's TZ, this should be a separate context menu item. <JRT>
* The Lock/Logout Widget has rectangular buttons -- should have square? IAC, icons should be centered on buttons. <JRT>
*System Tray Widget doesn't work correctly: The Widget doesn't size itself to hold the contents. The contents seem to have the wrong X display priority (they are always on top). It (the contents, not the widget) interacts with windows (snap). The contents are only displayed on Desktop #1. When something triggers a refresh of something, then the SystemTray widget resizes and looks correct but the icons are still not working correctly. They are only on DeskTop #1 and always on top. <JRT>
*The Application Launcher Widget seems to be stuck in the middle of the screen; I can't drag it. In this position with 1024x768 the menu window does not open correctly. It extends beyond the top of the screen and is cut off. <JRT>
*The Clock on the Panel slides over and winds up on top of the TaskBar on the Panel.<JRT>

==== Plasma - Kickoff 'Start Menu' ====

* Unable to resize the kickoff menu. (mbiebl)
* Kickoff opens konqueror when clicking on an entry under "My Computer". (mbiebl)
* In kickoff, clicking the utilities menu and then clicking back again shows the top menu scrolled to the top rather than where it was before clicking utilities. (jstubbs)
** Confirmed. Additional strange bahaviour: When opened by clicking on a link in "Storage" for example, Konqueror shows the contents of "/" in an unnamed tab. Right of that tab is another one showing the correct location. If you click that tab, konqeuror crashes. (goliath23)
* Kickoff: Clicking the applications tab, when the tab is open should return it to top-level.Current catalog-memory is a good feature however, so keep that aswell. (eirik_)
* Kickoff does not start firefox. It loads the .desktop file in kwrite (amp)

==== System Settings ====
* systemsettings has no menu entry. Typing it into kickoffs search entry doesn't find/list it either. (mbiebl)
* When clicking on "Appearance", it seems to delete a file. http://rafb.net/p/zzS2fM55.html (Mogger)
**When I select "Appearance" in "System Settings", three "Progress Dialog" boxes pop up.<JRT>
* Missing "get root rights" button on pages like Date/Time, thus its impossible to change such settings (apaku)
* Searching something doesn't seem to limit the displayed modules or highlight any of the search results.
* no settings to be changed for keyboard shortcuts - everything is empty (nixternal)
**This is probably a function of your system configuration. IIUC,It reads an X11 file. <JRT>
* When clicking e.g. "Appearance", the System Settings window doesn't get resized. This causes very ugly (horizontal and vertical) scrollbars (gissi)
* Default size for the text beneath the icons is too small. I see stuff like 'ppearanc' instead of 'Appearance' and 'ccesibilit'. Some other texts are wide enough, like 'Splash Screen'. (BCoppens)
* Changing the style to Oxygen changes all windows, EXCEPT the System Settings (BCoppens)
*Regional & Language::Time & Dates (should that be "Time & Date"?) doesn't have USA style date formats in "Short date format": MM.DD.YYYY & mM.dD.YYYY and should also have formats with only 2 digits for year: YY.

==== KMix ====
* <s>m_qcb->blockSignals( true ); where m_qcb is null from MDWSlider::updateInternal during kmix startup http://pastebin.ca/759601 (jstubbs)</s> Fixed by SVN commit [http://websvn.kde.org/?view=rev&revision=732246 732246]
* <s>Right click on KMix icon in system tray, select master channel, dialog comes up empty, when you close it KMix icon disappears from the tray (JLP)</s> Fixed by SVN commit [http://websvn.kde.org/?view=rev&revision=732367 732367]

==== KWin ====
* Windows are not fully redrawn when minimizing and then restoring with OpenGL compositing in use (jstubbs)
* the compositing KCM should provide an easy way to enable the COMPOSITE extension (logixoul)
* <s>Menu shadows are being left on the desktop (but not on windows, it seems) (Mogger)</s> Fixed by SVN commit [http://websvn.kde.org/?view=rev&revision=732268 732268]
* Sometimes (tested with Konsole, X.org 7.3, latest nvidia drivers and a Geforce 5900XT), the clicked menus are not displayed and KWin crashes. Backtrace : [http://rafb.net/p/zmYj1980.html] (idem)
* After a while the alt-tab window list is completely missing though I can still switch between windows with alt+tab (apaku)
* alt+tab only allows to switch between windows on the same screen in a multihead setup, its impossible to activate a window on another screen (though its on the same virtual X11 desktop) (apaku)
* alt+tab (without compositing) shows a list of windows but no indication which window in this list is selected when cycling through them. (goliath23)
* KWin does not detect compositing ability on my pc with a GeForce 7600 GS (driver version 100.14.19) (goliath23)
* The Composite Effect 'Demo Liquid' crashes KWin (BCoppens)
* 'Scale In' effect also scales in Menus and Dropdown boxes from the 'middle' of their target area, this is ugly. Either don't do that for such windows, or let them scale in from their topleft corner (BCoppens)
* Alt+Shift+Tab for backwards scrolling through Alt+Tab shortcut is not assigned, but I can't remember if this was the case in KDE3 as well or not... (BCoppens)
*Moving windows with "Display Content" turned off does not display an empty frame. (using an OpenSource driver)<JRT>

==== KNS ====
* KNS uses 100% CPU when 550 is enabled in kdebugdialog (jstubbs)
* Sometimes KNS dialog is under Settings dialog (Kanagram and KStars) modal/non-modal issue when KNS is invoked from a Config dialog (jstubbs)

==== KHangMan ====
* <s>"Already Guessed" tooltip timer does not work.</s> FIXED annma r732068
* <s>When changing the "Already Guessed" tim in Config, the current word should stay (KHangMan jumps to a new word).</s> FIXED annma r732068
* After typing an already typed letter, the focus is left on the guess "button", which means I have to press tab to get back to the letter entry field. If we enable the focus back before tooltip is hidden, it means the tooltip has to be hidden when a new letter is entered. (jstubbs)
** annma: intented behaviour is that the input is impossible why popup is shown. To leave the kid the time to understand what he is doing. Messing with the tooltip now seems bad to me. It's a WON'T FIX until we have it tested with kids ;) sorry jstubbs!
* <s>See if the font progressbar can disappear after first run (jstubbs)</s>
** annma: Removing your ~/.fonts/d dustismo_roman.ttf will make the bug go away. The font will reinstall and then it'll be found. Not sure why it happened...
* Test what happens for the fonts when no internet connection (jstubbs)
* Wish: when using the Special chars toolbar, letters should go immediatly in the word or in Missed. Annma is not sure this would work with kids, they maybe won't understand what happens. (jstubbs)
** annma: maybe a config option for KDE 4.1 as we are in feature freeze now.
* Language combo in toolbar does not resize correctly when changing language. (jstubbs)
* <s>Right-clicking "Type accented letters" does not offer the context sensitive help when the option is disabled. (jstubbs)</s>
** annma: this is from Qt, it's default behaviour for QWhatsThis help.

==== Kiten ====
* Searching for "one" takes a long time to process, during which the application blocks without any feedback. (jstubbs)
* From the Search menu, selecting Search {with Beginning of Word, Anywhere}, Grade or Strokes does not seem to have any affect (jstubbs)
* Selecting Verb or Noun from the grammatical element dropdown does not seem to have any affect (jstubbs)

==== KBruch ====
* In fraction tasks, the denominators used sometimes exceed the max denominator that is set. (jstubbs) r732343 attempted to fixe it but not totally

==== KPercentage ====
* <s>When starting a new set of tests, and on various other actions, the window unnecessarily moves to the centre of the screen (jstubbs)</s> Fixed r732700

==== KGeography ====
* <s>Intermittent crash after a placing state on a map (jstubbs)</s> Fixed r732331 (tsdgeos)
* <s>Selecting zoom when placing state on a map leaves the cursor as the state to be placed - perhaps the cursor should change back to a pointer while in zoom mode? (jstubbs)</s> Fixed r732314 (tsdgeos)
* With KWin's dimming of inactive windows, it is difficult to relate the colors signfying right/wrong answers back to the map (jstubbs)

==== KmPlot ====
* Editing function does not work as if Enter is not doing anything (rivo, gissi and idem-kde4) Annma cannot reproduce.
**Note by gissi: For me, only editing a cartesian plot doesn't work, the others work as expected. Don't know wether that's the same for rivo and idem.

==== KMail ====
* Creating a new Imap Account and press "Check what the Server Supports" in Security crashes KMail. Stacktrace / ConsoleLog at http://pastebin.ca/759562 (voltaire)
:: This is probably a KSSL problem, which will be fixed when the new KSSL arrives in kdelibs --[[User:TMG|TMG]] 00:03, 4 November 2007 (CET)
* <s>If I open a link from an email it opens it but then it crashes - Backtrace http://pastebin.ca/759997 (frank95com)</s>
:: <s>This is a kdelibs (krun) bug, it happens in other apps, like Konsole, as well</s> --[[User:TMG|TMG]] 00:03, 4 November 2007 (CET)
:: Fixed in kdelibs --[[User:TMG|TMG]] 21:27, 6 November 2007 (CET)
*When an IMAP server stops responding KMail popups up the "IMAP Disconnected" dialog with an "Ok" button. Clicking "Ok" crashes KMail. Stack Trace: http://www.pastebin.ca/759969 (JustinNoel)
* KMail initial account wizard. A process related to the KMail initial setup wizard crashes when "Check for supported security capabilites on..." appears. Console spew suggests something crashed. KMail starts with an IMAP account with an incorrect security configuration. Description/Reproduction Steps/Console Spew: http://www.pastebin.ca/760052 Needs verification as I only have one IMAP server to try. (Justin Noel)
:: Seems like the same bug above, the one reported by voltaire. --[[User:TMG|TMG]] 00:03, 4 November 2007 (CET)
* KMail with disconnected IMAP: after customizing options and restart, it crashes on startup http://pastebin.ca/764484 ([[User:Lure|Lure]] 09:07, 7 November 2007 (CET))

==== Build issue ====
* <s>in kdebase when OpenGL is not found, cmake stops with "CMake Error: This project requires some variables to be set, and cmake can not find them. Please set the following variables: OPENGL_gl_LIBRARY (ADVANCED)" so there is a bad check somewhere in kdebase (annma, issue of frank95com, http://pastebin.ca/759575). Possible patch: http://pastebin.ca/759603 (annma). Other possible patch by ThomasZ: http://pastebin.ca/759605</s> fixed svn r733932
* In kdebase on OS X 10.5 the build WITH_XKB = OFF variable is not respected resulting in failure of the build. (build process info found at http://techbase.kde.org/Getting_Started/Build/KDE4/Mac_OS_X_10.5_issues) Sorry it's so wordy, but I initially wrote it up for personal use.

==== Kolf ====
* The direction and velocity marker flickers and often cannot be seen. Using opengl compositing. (jstubbs)

==== KDElibs ====
* <s>The tab order of the configure shortcuts dialog is incorrect. (Mogger)</s> Fixed by SVN commit [http://websvn.kde.org/?view=rev&revision=732404 732404]''
* Drag and drop doesn't work in the configure toolbars dialog. (Mogger)
* Applications crash when downloading something. Traceback from Konsole when clicking on a link: http://rafb.net/p/1aiHyn63.html (Mogger)
** The link appears to be dead
* cannot write Right-To-Left...in kde3 when you start a line with a character of an rtl language, the line goes rtl automatically (emilsedgh)
* Configure shortcuts dialog is too small at start: I cannot see the action name at all (it says stuff like 'C...' instead of 'Close'). Furthermore, and much worse: I cannot change the width of the columns at all to try to make the action names readable! (BCoppens)

==== Konqueror ====
* Website http://kriptopolis.org it is really bad rendered, however it is fine with Konqueror 3.5.7. (q3xr2)
* often doesn't load pages properly, for example clicking the login link on a techbase page almost always gets me an empty page (apaku) (frank95com too, gruf too)
* <s>Cannot show thumbnails (emilsedgh)</s>
** fixed by mlaurent (logixoul)
* Up Button loads a different view, while back button doesn't, when walking through the filesystem. The up button loads a similar view to what you get in dolhpin, while the default view when typing in a local path is a plain iconview (apaku)
* When entering already visited directories, the animated logo doesn't stop. (Plain iconview instead of dolphin part?) (Mogger)
* Nothing in View -> Sort By, Additional Information, Panels, Navigation Bar submenus (yuriy)
* Nothing except "home folder" in home folder sidebar (yuriy)
* Some favicons do not appear in Konqueror's nav bar to titlebar. google.com and kubuntu.org works. kde.org, cnn.com and slashdot.org do not work. (JustinNoel)
* pressing ctrl+a when focus is on addressbar selects whole webpage instead of the text that is written in the addressbar (only on webpages: khtmlpart?) (emilsedgh)
* have to keep refreshing pages in order for them to display (nixternal)
* have quite a few problems trying to edit this page alone (nixternal)
* In file management mode it can't show hidden files, it doesn't have this option in the View menu, neither there is a shorcut available. (q3xr2)
* In HTML forms (such as the textbox to edit this wikipage with, or the username box), the initial fontsize is small. Once I click on the form, the font suddenly enlargens. Especially annoying with this editbox, since the place where you think you clicked changes after fontsize change (BCoppens)
* Asks nicely if it has to store my form data (such as password and username in the Wallet, but does not actually do so (BCoppens)
* Clicking on a link to an in-page 'tag' (the a href=#tag thing, like there are lots of in the index of this wiki page), results in konqueror showing the 'Drag link' mouse cursor (BCoppens)
* Not only do I get blank pages, but I get the following on trying to edit this wiki with Konqueror of KDE4: after sending in the changes, it shows a blank page. I press F5, and Konq asks me to resubmit form data. Wiki then shows an almost-empty edit page, with 'Sorry! We could not process your edit due to a loss of session data' (BCoppens)
* Start Konq. Press 'Next: An Introduction to Konqueror'. The page goes blank, and 'Previous page' also shows up blank. (BCoppens)
* With Konqui becoming webbrowser as primary task, it would make sense to redesign the start page altogether and remove stuff like Storage media, Trash etc. Show something like "Search the web" which points to a search engine, like Google, yahoo,...
* Start Konq. Enter '~'. Make a new tab (CtrlShift+N). Type something. Note how the cursor goes OVER the map icon, instead of starting next to it (BCoppens)
* (Different from the one above) Start Konq. Enter '~'. Make a new tab (CtrlShift+N). Enter '/'. Switch back to the first tab. It's caption suddenly changes from '/home/kde4/' to 'kde4'! Switching to the second tab, removes the '/' and makes that tab nameless) (BCoppens)

==== IO-slaves ====
* Browsing with IO-slaves that require autenthication is broken: SMB, FTP, SSH do not display anything after authentication is entered (luca_b, nixternal, yuriy).
* When adding RSA keys using fish:/, the buttons to accept/refuse are blank. (luca_b, yuriy)
* smb:/ ioslave causes crash (nixternal)
* smb:/ ioslave does not work with shares that need authentication. Console output: http://pastebin.ca/760196 (luca_b)
* kio_file: After a while I have 100% of CPU usage when running KDE4. top says, the process is kio_file, which is sometimes up to 4 times running (amp)
* The settings:/ ioslave (accessible through Settings on the welcome screen of Konq) does not work at all. For example, try Appearanc&Themes -> Fonts: it tries to open this with KWrite! (BCoppens)

==== Color KCM ====
* Changing the checkbox "Apply colors to non-KDE4 apps" doesn't trigger the changed signal and thus the apply button in systemsettings stays grayed out (apaku)
* the same as above applies to the whole Effects tab (apaku)

==== Kate ====
* Crash when going down page-wise with PageDn beyond the end of the file. Backtrace: http://www.apaku.de/vardata/kate_crash_pagedn (apaku)

==== Marble ====
* Navigate to Minneapolis (search is quick) and then zoom in until "saint paul" appears. Rotating up and down will now cause the text "saint paul" to jump around. (jstubbs)
* In full screen mode, clicking in the right half of the globe doesn't work. It seems that plasma is getting the events? (jstubbs)

==== Kinfocenter ====
* Most of the Items are empty (emilsedgh)

==== Kopete ====
* Adding an account a second time (same protocol, same user id as an existing) makes kopete crash (moi1392, idem-kde4). http://pastebin.ca/759660. More verbose fix in the works (Earthwings). http://lists.kde.org/?l=kopete-devel&m=119411618226111&w=2
* I can't get my Google Talk account to finish it's authentication process, however I can login without any troubles with my jabber.org account. I don't know if the trouble it's related to the SSL login or qca-tls which I have installed (q3xr2).
** Google Talk did not work before for me, but it works now (with today's SVN version), maybe you should retest with current SVN version.
*** It works now for me also! (q3xr2).
* Configure->Plugins results in consistent crash here http://pastebin.ca/764575 ([[User:Lure|Lure]] 12:34, 7 November 2007 (CET))

==== kfind ====
* kfind crashes when the find is stopped (by pressing "stop" button) during the find process (shaga)
* the stop button has to be pressed twice, the first click is lost (shaga)

==== Gwenview ====
* Random crashes when navigating to directories, or when editing the path manually. Backtrace http://pastebin.ca/760077 (luca_b)

==== Login Manager KCM ====
* There are numbers on the tabs (yuriy)
** yes - the kcm is too big to have non-clashing letter shortcuts.

==== kscd ====
* crashes when inserting a CD. Problem is an assert thats hit (apaku):
kscd(31228)/kdecore (KConfigSkeleton) KConfigSkeleton::readConfig: KConfigSkeleton::readConfig()
kscd(31228)/libkcddb KCDDB::Cache::lookup: Looking up "ae0cdb0e" in CDDB cache
kscd(31228)/libkcddb KCDDB::CDInfo::load: Loaded CDInfo for "ae0cdb0e"
kscd(31228)/libkcddb KCDDB::Client::lookup: Found 1 hit(s)
ASSERT: "info.numberOfTracks() == cddbInfo.numberOfTracks()" in file /home/andreas/KDE-work/4.0/kdemultimedia/kscd/kscd.cpp, line 753
* crashes when starting up (but not if the user does not have permissions to acces the cdrom) backtrace: http://pastebin.ca/760172 (yuriy)
==== KFontChooser ====
*It doesn't work correctly for the bit mapped fonts Fixed[Misc] & Fixed[Sony] which come with X11 are the best example of this since they might be used in Konsole. This is mainly a Konsole issue. <JRT>
**There should be only 2 sizes of Fixed[Sony] which works correctly in KDE3 it displays only two sizes. I'm not 100% clear on how this works if you have a screen resolution other than 75 or 100, but xfontsel lists two point sizes for 100 dpi: 12 & 17 and this agrees with the KFontSel dialog. But in KDE4 it lists the usual list of sizes from 4 to 64.
**There are several sizes of Fixed[Misc], according to xfonsel they are: 5, 6, 7, 8, 10, 11, 12, & 14. KDE has this fairly close to correct -- close enough that it works OK. It also lists 4 which may be a 75 dpi font and it lists 9 but not 12. Could these be rounding errors? IAC, KDE4 is the same as with Fixed[Sony], it has the standard list of 4 to 64.
*We need to first ask if this is a Qt bug/error as are other font issues.
**The Fixed{Misc} fonts are not a uniform set of fonts and I don't think that there is any way that Qt can deal with this issue.

==== Akregator ====
*Crashes while trying to delete a feed.
** Nickname and backtrace in pastebin.ca please

*Marking feeds or messages as Read does not work. The context menu in the feeds list reappear two times after the first select. Even when reading a message, it is not marked as read. ([[User:Kleag|Kleag]] 23:46, 7 November 2007 (CET))

==== Kontact ====
*Crashes starting the application.
::We need a backtrace, otherwise we can't do anything. It doesn't crash for us. --[[User:TMG|TMG]] 21:24, 6 November 2007 (CET)

==== KDEPrint ====
*Printing a html file from konqueror. The "HTML Settings" tab has an odd layout. It seems to miss a proper border. (mbiebl)

Development/Tutorials/KOffice Overview

2007-11-05T17:29:03Z

Zander: /* Considerations */ Wikify

KOffice has gotten more and more configurable through plugins over time, which is a really good thing as 3rd party developers can extend KOffice using dedicated code for their purpose.

You will learn what functionality you can place in each plugin type so you can choose wisely. There is a general guide to writing plugins and each type has a tutorial showing how to create a new plugin of that type.

well, not all required info is there yet; but this is the idea :) Anyone want to help?

__TOC__

== Generic Information ==
Plugins are a design technique with a series of steps that will lead you to a loadable plugin. If you want to know more its is interresting to read an overview at [[Development/Tutorials/Generic KOffice Plugin Creation|Generic KOffice Plugin Creation]]

== Shapes ==
In KOffice shapes are document content. This content can be manipulated by the user and can be shown on screen or printed. The fact that they are plugins means that a new content types can be added to documents by just installing the plugin and starting your favorite KOffice application.
To get a feel for what a shape is, here are some examples of existing shapes, sometimes referred to as Flake shapes because shapes are one of the two main parts of the Flake library.

We have a PathShape which is a generic vector shape capable of showing and printing any sort of vector art like SVG or EPS vector graphics.

There is a Text plugin that is capable of showing marked up text with a huge feature set including HTML capabilities and a big part of the more extensive OpenDocument format.

KSpread exports a tableShape, to allow a spread-sheet table to be embedded in other KOffice applications.

API docs start at; [http://www.koffice.org/developer/apidocs/libs-flake/classKoShapeRegistry.html KoShapeRegistry]

The tutorial on how to write your own shape plugins can be found at [[Development/Tutorials/Write a Flake Plugin|Write a Flake Plugin]]

== Tools ==

A tool is a plugin that handles user input and can manipulate either the general application data, or can manipulate a specific shape.
All user input mouse and keyboard events that are send to the document area (canvas), will be passed to the active tool. The active tool can use them to, for example, move shapes around or rotate them. If you combine a tool with a shape plugin you can make the tool manipulate the data of the shape. A good example is the text tool which is bundled with the text shape. The text tool takes all keyboard events and thereby lets the user type text in the text shape.

This gives a clear separation of control and content. The shape holds the content and a tool is required to control that content.

In general there are two types of Tools;
* generic tools that are not associated with a shape plugin. Its rare that you will create such plugins, though we still need a 'measure' tool that falls in that category.
* bundled tools that come with a specific flake shape and is made to manipulate that shapes data.

API docs start at; [http://www.koffice.org/developer/apidocs/libs-flake/classKoToolRegistry.html KoToolRegistry]

The tutorial on how to write your own shape plugins can be found at [[Development/Tutorials/Write a Flake Plugin|Write a Flake Plugin]]

== Dockers ==

Plugins that provide a docker are basically plugins that provide a graphical user interface element for KOffice applications. In KOffice2 the focus on toolbars and dialogs will be less as they have been proven to be confusing to users because they clutter the interface.
Instead the focus is shifted to widgets that can be docked along the sides of a document window but also moved to be a separate window. The real change is that, unlike dialogs, they don't have an 'Ok' button but instead change the content life and immediately.
Examples of dockers are; the toolbox, the shape selector and the tool-options but also the color selector.

API docs start at; [http://www.koffice.org/developer/apidocs/libs/classKoDockRegistry.html KoDockRegistry]

Within KOffice dockers could also be written in a scripting language like Python or Ruby. The [[Development/Tutorials/KSpread_Scripting#Scripting_Docker_Widgets|KSpread Scripting Docker]] tutorial shows how it was done within KSpread.

=== Considerations ===
Dockers should never be passed a document or a view in the constructor. The reasons for that is simple; the lifetime of the docker is longer then the lifetime of the document and also of the view.

The proper way to do this is to let the application tell you there is a new document or a new image, etc. And listen on that.
This involves a couple of steps;
* The application should use the KoCanvasResourceProvider to put content on. Like the current layer, the current document etc.
* The docker should (also) inherit from KoCanvasObserver which means it will get notified when its canvas changes.
* Using the KoCanvasBase received from the KoCanvasObserver it can fetch the document from the KoCanvasResourceProvider. It can also connect to the provider to be informed about any changes.

An extra tip is to use the KoCanvasResource::DocumentIsLoading boolean, dockers should listen to it to avoid doing work while the document is loading.

== Colorspaces ==

== File Filters ==

== Text Plugins ==

The text component used in all KOffice applications has a set of plugins itself. These plugins allow the possibility to enhance the content as well as allow to enhance the editing experience. Use Inline object plugins to write content such as inline variables and bookmarks. Use Text Editing plugins to be able to replace the text a user types while he types it. For example for autocorrection.

=== Inline Objects ===

The plugins of this type effectively become a character in the text document. What this means is that a user can insert an inline object and the plugin can decide the size and content of the character inserted.
A good example of inline objects are variables. A variable can have a name and a value and altering the value of a variable will then change the value in the text all over the document. This is done by an inline object that shows the full text of the variable, but in the document it behaves as it is one big character that can't be split over lines or otherwise edited.

An inline object does not have to have content, it can just be a placeholder as well. Which makes it ideal for things like in-text comments/annotations and Bookmarks.

API docs start at; [http://www.koffice.org/developer/apidocs/libs/classKoInlineObjectRegistry.html KoInlineObjectRegistry]

=== Text Editing ===

The text editing plugins are all about handling user input while (s)he is editing the text. A plugin can do near everything with the typed text, including altering it and adding markup.
The plugin gives events when a word and when a paragraph has been finished. Which is ideal for autocorrection and autoreplacement of text.

Examples of usages of this plugin type are; a word count in a docker updated continuesly, auto correction of text, replacing formatted text with calculated values or custom shape plugins.

API docs start at; [http://www.koffice.org/developer/apidocs/libs/classKoTextEditingRegistry.html KoTextEditingRegistry]

== Krita's plugins ==
* filters (effects)
* paintop (plugin that are in charge of painting when the user uses a drawing tool)
* viewplugin (aka misc)
See [http://docs.kde.org/development/en/koffice/krita/developers-plugins.html Krita's handbook]

Projects/Plasma/Tasks

2007-11-02T22:12:50Z

Zander: /* Major Bugs */

{{warning|If you clear a task, please write "'''Completed'''" near it. If you are still working on it, please put your name. Percentage of the work done is accepted.}}

== Tasks ==

If you want to claim a task, please put your name (or nickname, both is better) in brackets near the task you wish to claim. Please add it when you start working on it, and if you stop, please remove it, so we can know "who is working on what" and what tasks still needs to be started.

And, of course, this will avoid duplication of work. Thanks a lot! =)

{{note|This is a roughly sorted list of tasks that popped out during the meeting. We probably need to categorize it better, like seeing which task is blocker for which other, setting priority, split between "research" and "coding" and things like that. Still sounds like a premature thing though.}}

=== KRunner ===
==== Major Bugs ====
In the alt-f2 dialog type a command (like 'kword') and press the button to have more options. Then press the same button again to get less options. => crash

==== Runners ====
* pull in options from kdesktop/minicli.cpp and merge into shell and app runners
* Search Runner: use strigi (blocked by Xesam)
* listen to async match updates (Interface:updateMatches())
* runners, runners and more runners!

==== Interface ====
* options slide drawer animation

==== Misc ====
* install [[Development/Tutorials/D-Bus/Autostart_Services|D-Bus autoactivation service]]
* QtScript bindings to AbstractRunner

=== Plasma ===
''This is what we are focusing on implementing right now:''
* '''general libplasma'''
** unit tests.
** api documentation reviews
** XML Config: add support for unsupported data types (these are documented in the API docu)
** Applet needs a way to access resources for customization (think: clock faces)
** Need to implement the math in Phase to update the intervals according to the CurveShape, ala QTimeLine (ask aseigo for more details if you find that cryptic ;)

* '''Applets'''
** application launcher interface
** <div style="color: green">taskbar (Robert Knight; others welcome to help)</div>
** <div style="color: green">systray (Alexander Rodin; others welcome to help)</div>
** <div style="color: green">on mouse over, show a set of small buttons that allow for the following actions: close, configure, lock, information and move. aseigo has graphics for the buttons already. (manyoso)</div>
** add global settings config page, if it exists in the Package (which means adding a pair of entries in packages.cpp for globalconfigui and globalconfigxml), alongside the per-applet ones

* '''plasmagik'''
** unit tests
** <div style="color: green">resuscitate trunk/playground/base/plasma/plasmagik (adjam, ruphy)</div>

* '''bindings'''
** <div style="color: green">QtScript bindings are being worked on (rdale)</div>

* '''RootWidget''' (the "desktop")
** <div style="color: green">Controls box: an expand-on-mouse-over widget that sits on top of the graphicsview and provides discoverable access to zooming, jumping, configuration, adding of elements, locking ...? Currently needs to pretty-fied and the more "techie" options removed (aseigo)</div>

* '''Corona''' (QGraphicsScene subclass)
** Zooming: 3-level zooming needs to be supported. 100% == 1 item group at full zoom; 50% == all item groups visible with panning with each item replaced by a simple icon; 10% == all item groups visible without panning, each group replaced by a simple icon and items not painted at all
** Respond to resolution changes
** Ability to define default panel/desktop/applet layouts without modifying loadDefaultSetup code, e.g. with config files on disk.

* '''Views'''
** Implement configurable background painting. This can in part be ported from kdesktop for DesktopView.
** Implement composite based translucency for panels
** Create a dashboard view (full screen, always on top)

* '''Widgets''' [[../Widgets|Here is a page describing the nature of these widgets]]. Widgets still needed that aren't implemented yet are:
** Icon needs the icon hover feature to be finished
** [[/HTMLViewer|An html widget]]
** panner widget that shows N QGraphicsViewItems at a time in a fancy manner (asiraj)

* '''DataEngine'''
** Configuration parameters for sources

''We also have:''
* Implement Zack's physical equations for animations

''Nice to have:''
* Implement python bindings of Plasma
* Associate units with a data source's data?

Projects/Oxygen/StyleWinDec

2007-10-19T22:18:07Z

Zander: add idea

Projects/Oxygen/StyleWinDec

2007-10-18T13:18:32Z

Zander:

Projects/Oxygen/StyleWinDec

2007-10-18T13:18:06Z

Zander: /* Incoming New Bugs */

Development/Tutorials/Generic KOffice Plugin Creation

2007-08-29T11:19:31Z

Zander: /* The concept of a plugin. */

Writing a plugin for KOffice technically means the following things are created;
* An interface that is shipped in the base-libraries will be inherited from, and functionality implemented unique to the plugin. Examples of these interfaces are KoShape, KoTool and KoColorSpace.
* A factory class is created. The factory design pattern allows the plugin to create as many instances of the plugin code as required in a flexible manner. Each plugin type has its own Factory object that should be inherited from.
* A plugin object is created. This is really a plugin-loader object and it will be created and immediately deleted by the KOffice libraries.
* A library file is installed that contains all classes that make up the plugin.
* A desktop file is installed with the information about the plugin, including the name of the library.

== The concept of a plugin. ==

The concept is really based on what Object Orientated design is saying, it means that you can create a programmer-interface and encapsulate that in a class without being very clear as to what that implementation is suppost to do. You can then supply several classes that actually contains the implementation of the programmer-interface, each in their own way.
The actual way that the class responds to the same environment is thus the implementation and not the programmer-interface.
Plugins are a way to provide a different implementation for a known interface.

KOffice has defined several classes as base classes and has made the programmer interface of those base classes generic enough so a wide range of functionality can be accomplished by providing a plugin with a new implementation for such a base class.

An example; one plugin type that KOffice supports is a docker widget. A docker widget is really a widget that can be shown on screen like a button or a text field are widgets as well.
The plugin can ship a new implementation of the QDockWidget class by inheriting from that QDockWidget and providing text/buttons and functionality using the full API of the Qt and KDE/KOffice libraries to do their work.
This means I can provide a plugin that ships a docker. And the docker shows the time of day, for example. By installing the plugin according to the instructions for that type of KOffice-plugin the KOffice application are able to find it and the docker will be created and shown on screen.

One unique property of a plugin is that it is self contained. Which means that the end result of the plugin is one library which exports just the 'plugin object'. This means that whatever code and classes is changed in one plugin can not possibly affect code in another plugin or even in the KOffice applications.
This has the benefit that development becomes more separated and changes in one place will not give problems in another.
It is therefor suggested to use any number of classes that fit your design and programming style, and you are free to avoid using namespaces or class name prefixes, as you wish. In other words; your plugin is walled off, nobody will be bothered by what you do, or how do you it.

== Components ==

The '''first component''' is the class that inherits from the interface this plugin represents.
Each plugin type will go into details on this as each interface has different features and requirements.

The '''factory component''' is also unique per plugin, but quite generic in setup and idea. The reason for the existance of a factory is that it makes it possible to create any number of the plugin objects at the time that the host applications want to do this, probably at the request of the user.
The workflow in general is this;
* A plugin is loaded and a factory is created. (see the plugin-object component)
* This factory is registered in a Registry.
* Applications query the registry to ask about all plugins and use, for example, the name and an icon from the factory to show buttons on screen.
* The user clicks on a button, or in another way selects the plugin factory.
* The plugin factory is then asked to create a new instance of the thing it is meant to create.
* That new shape or widget or other thing is used in the document or gui. All depending on the plugin type.

This means that our main advertisement to the outside world is the factory. As the factory is used to show the user what kind of things this plugin can do. Each plugin type has its own factory, with at minimum a create() like method which then returns a new instance.
The factories typically have a large set of user interface components you can register on them. Like a name, or an icon etc. It is wise to fill as many of them with relevant information as possible.

The next component is the '''Plugin component'''. This is a QObject inheriting class that has a specific constructor signature and, interrestingly, will be deleted immediately after it is created.
The trick therefor is to do all the work of creating and registring the factories in the constructor.
The code for this class is pretty simple, and you copy paste it with just a few modifications;

in the header file:

<code cppqt>
#include <QObject>
class MyPlugin : public QObject {
Q_OBJECT
public:
MyPlugin(QObject * parent, const QStringList &list);
};
</code>

in the cpp file;

<code cppqt>
#include "MyPlugin.h"
#include <kgenericfactory.h>
#include <KoShapeRegistry.h>
#include <KoToolRegistry.h>

K_EXPORT_COMPONENT_FACTORY(libraryname, KGenericFactory<MyPlugin>("MyPlugin"))

MyPlugin::MyPlugin(QObject * parent, const QStringList &)
: QObject(parent)
{
KoToolRegistry::instance()->add(new MyToolFactory(parent));
KoShapeRegistry::instance()->add(new MyShapeFactory(parent));
}
#include <MyPlugin.moc>
</code>

This example registeres 2 factories, but you can register any number you want to ship in 1 plugin. Note how only the factory is created, and nothing else is done. This makes loading of the plugin as fast as possible.
If you copy paste this code make sure you update the 'libraryname' to be the (all lowercase) name of your plugin-library. Which is also repeated in the desktop file. Note that the name is without any extentions. In the <code>K_EXPORT_COMPONENT_FACTORY</code> macro the 'MyPlugin' is repeated twice. Its easiest to just replace that with the class name you choose for your project.

The '''library''' is what will contain all the compiled classes of your plugin.

A plugin is technically implemented as a library, at least on Linux and other unixes. It is loaded as a library by KOffice near the start of the application start. As the plugin is a library all development software can create them using a linker.
It is worth noting that it is possible for your plugin to depend on external shared libraries, apart from the koffice ones. But you should install that shared library as well as your plugin.
In cmake the creation of a library goes like this;

########### Flake Plugin library ###############
project( myPlugin)
include_directories( ${KOFFICEUI_INCLUDES} ) 
SET ( myplugin_SRCS
MyPlugin.cpp
# other cpp files
) 
kde4_add_plugin(textshape ${myplugin_SRCS})
target_link_libraries(myplugin kofficeui)
install(TARGETS myplugin DESTINATION ${PLUGIN_INSTALL_DIR})
install( FILES myplugin.desktop DESTINATION ${SERVICES_INSTALL_DIR})

And last is the '''desktop-file component''' after which the plugin will be found and used by KOffice.
A desktop file is basically a database record for the KDE database of what is installed. In this case the component is a 'Service'.
For our running example here is myplugin.desktop

<code ini>
[Desktop Entry]
Encoding=UTF-8
Name=My Shape
ServiceTypes=KOffice/Flake
Type=Service
X-KDE-Library=myplugin
X-Flake-Version=1
</code>

A couple of things are important;
* The encoding has to match the encoding used. So make sure you use an editor that understands and writes utf-8 when editing this file.
* The name is used for the plugin-manager.
* The ServiceTypes is used to specify which registry should try to load us. One plugin can contain any number of factories, and some would say, it can contain any number of plugins. It typically is useful to combine a shape and a tool into one plugin, for example. Now, when an application looks for all shape plugins, our plugin should be found, naturally. So we can choose to use the ServiceTypes 'KOffice/Shape'. But when the application looks for tools we should also find the plugin. So we might need to have 'KOffice/Tool' instead. This gets confusing and we don't want one plugin to be loaded twice, so instead we take the more generic 'KOffice/flake' which will be searched for when either a shape or a tool is requested. Each plugin type will show the best matching ServiceType, but if you are doubtful you can always use 'KOffice/Flake'.
* The X-KDE-Library field has to contain the actual (lowercase) name of the library we created in the previous step. Without any extention.

Projects/kdelibs

2007-07-28T11:31:22Z

Zander: Add one

= The Master Todo List for KDE 4 =

This project page contains several lists (presented as tables) of things we still need to do in the kdelibs module.

== Bugs ==

Fix these bugs as soon as possible.

{| border="1"
! Issue !! Reported by !! Being fixed by !! Status
|-
| The KFileDialog file extension stuff has disappeared. There seems to be insufficient spacing around that checkbox too. || Clarence Dang || Clarence Dang || Fix of first bit is to revert the top hunk of this [http://lists.kde.org/?l=kde-commits&m=111835187828266&w=2 patch], don't think this causes a getOpenUrl() regression, will ask jowenn
|-
| KDoubleNumInput doesn't handle keyboard input properly esp. with '.'. I did see a FIXME in that file regarding the KIntNumInput validator or similar. || Clarence Dang || ||
|-
| Pressing the '?' button (from kwin) on a child widget of a widget containing WhatsThis complains about a lack of WhatsThis, even though it could just fetch it from its parent. || Clarence Dang || ||
|-
| Saving an image with RGB KImageIO crashes in SGIImage::writeImage() || Clarence Dang || ||
|-
| The settings->configure shortcuts dialog needs some serious usability love :) Oh, and it fails to show up the majority of my actions in kword. || Thomas Zander || Andreas Hartmetz ||
|-
| One cannot call KGlobalSettings::desktopGeometry(this) in a const method of a QWidget. || Loïc Corbasson || Loïc Corbasson || [http://pastebin.com/m628a3f67 Patch available], discussed with thiago, will commit next Monday
|-
| KPrinter doesn't work well after a myKPrinter.setOutputFormat(QPrinter::PdfFormat);
| Thomas Zander
|
|
|-
|}

== Do Now ==

Things we need to do right away.

{| border="1"
! Issue !! Person !! Status
|-
| Remove deprecated methods. || ||
|-
| Remove classes that aren't used by more than 1 app. || ||
|-
| KSSL needs love || thiago ||
|-
| Phonon's extended API || Matthias Kretz ||
|-
| Oxygen style (currently in playground || Casper Boemann ||
|-
| Buncha KIO issues || Jeff Mitchell, ervin, dfaure ||
|-
| URLArgs split up into OpenUrlArguments and BrowserArguments || dfaure ||
|-
| KDebug reimplementation from QDebug || thiago, dirk ||
|-
| On-the-fly add pages to KConfigDialog || Joris Guisson ||
|-
| Port K3Icon to KIcon. || ||
|-
| KDirNotify::emitFilesChanged complains that it's only half implemented || ||
|-
| KPrinter sucks, improve it.|| ||
|-
| kdefx. remove? || mwoehlke ||
|-
| kstyle fixes || Maxsim ||
|-
| API improvements that make it easier to port from KDE3 (in the sense of less work or things to change). It is time to make our desktop functional, and while this might mean to change the API here and there, our focus should be to get the application code we have from KDE3 running at least as good as it did with KDE3, without actually having to rewrite all of our existing code.|| ||
|-
| Import KExpandableWidget (KCollapsibleGroupBox?? -- 'Expandable' may be confused with To/CC/BCC lineedits in kmail) to kdeui || danimo ||
|-
| Rename KXMLGUIBuilder, KXMLGUIClient, KXMLGUIFactory to KXmlGuiBuilder, KXmlGuiClient, KXmlGuiFactory, respectively || Robin Stocker ||
|}

== Medium to Large-Scale Items ==

Medium to large-scale API changes that we would like to make for the next binary incompatible release.

{| border="1"
! Issue !! Person !! KDE Version !! Status
|-
| Check for forked classes in kde pim and other modules || Danimo || ||
|-
| Remove all KSocks references throughout KDE in favor of KNetwork's socket implementations. || Thiago || ||
|-
| Remove all methods marked 'deprecated' in KDE 3.x. || Martijn || ||
|-
| Make it possible to create a KSystemTray without a KMainWindow and instead lazily create the main window on demand. || Martijn || ||
|-
| Make KSystemTray add its own reference to KApp, so tray apps that adhere to the style guide can safely close their main window without having to worry about the app quitting instead. || Martijn || ||
|-
| Sort out reference counting of applications and KMainWindows: Add a setRefCountEnabled() function to KApplication; deref()ing the last reference should only quit the application if reference counts are enabled, and the reference count should be disabled by default so apps that don't use a KMainWindow mostly continue to work. Make the KMainWindow constructor call setRefCountEnabled(true), and make each KMainWindow hold its own reference to the application. The KMainWindow should drop its app reference on hide, and regain it on show.Make KSysTray also hold a reference to the app. Then apps that use more than one main window and the tray (like KSIrc and Kopete) will quit at the right time without nasty hacks. || Richard Smith || ||
|-
| Make some long-lasting operations threaded. There are some operations in KDE that take too long on at least ~500MHz hardware to be done using event loops. Examples are the use of KLibLoader to dlopen plugins and KRun to fire up other processes.Konqueror and KMail tend to stall occasionally too, but that's harder to refactor because the bulk of the work there is X11-related.|| Martijn || ||
|-
| Make it possible to use SSL-ed sockets outside KIO. KSSL isn't very suitable for reuse, and the certificate dialogs are not even available in public API at all, leading e.g. to Kopete IRC duplicating a lot of stuff and all KDE Jabber clients based on libpsi (PSI, Light Hawk and Kopete) using homebrewn solutions. [How does this have to do with changing KIO? It's just a request to have that code in a different form....] ||Martijn|| ||
|-
| Solve need for casting when using bitfield enums (e.g. K3Process::Communication) by the use of Q_DECLARE_FLAGS/Q_DECLARE_OPERATORS_FOR_FLAGS || Simon|| ||
|-
| Merge kdelibs/kdecore/kuser.h and kdeadmin/kuser/kuser.h. || Frans || ||
|-
| KParts: remove plugin loading from setInstance, add an explicit loadPlugins() call in all parts that should load plugins (at the end of the derived-part ctor). || David|| ||
|-
| KParts: come up with better names for ReadOnlyPart and ReadWritePart, ReadOnly is a minimum requirement, but this does not become clear until you dig deeper into the class. With QTextEdit and QTextBrowser for instance, the inheritance is the other way around. E.g.: ReaderPart? ViewerPart? || David || ||
|-
| Other ideas in this thread: http://lists.kde.org/?l=kde-core-devel&m=107608067302571&w=2 (Contributors to that thread, please add specific items here.) || Waldo || ||
|-
| Change classes that store bool data using strings ("true"/"false") to use bool calls (readBoolEntry()). Although not technicaly a binary incompatablity...just something to bring up for possible change (for the better)Use KConfigXT instead! || Frans || ||
|-
| Is it really necessary to bother people using the KCM APIs with withFallback? I have never heard of it failing and when would you not like to have that fallback? I think a default of 'true' would be fine(and remove the argument in the APIs). || Frans|| ||
|-
| Do we need to have factory arguments in the KCM API? (who would use it anyway?) || Frans || ||
|-
| The config options in kdeglobals needs to be cleaned up a little. Perhaps I'm being picky..<ul><li>They should be named properly, for example "enableIcons" instead of "EnableIcons". Or at least settle on one thing.<li>AFAICT it would be the right thing if KWin had its own rc file instead of having its "WM" section in kdeglobals.<li>Shouldn't Sonnet have its own rc file instead of kdeglobals?<li>Should we allow spaces in option names?<li>Some option names are too short for being understandable. fixed->fixedFont; font->systemWideFont<li>Perhaps an own font section?</ul>|| Frans || ||
|-
| KKeyDialog needs to be improved. It should simplify using KKeyChooser by not having to instantiate KDialogBase without restricting the possibilities of KKeyChooser (for instance, being able to configure global and application accels in one dialog). If there is only little time, simply expose the KKeyChooser object instead of making it private and inaccessible. || Michael Brade || ||
|-
| Fix the APIs taking Matthias Ettrich's hints into account, most importantly fix the massive amount of bool-usage in the CTORs. || Michael Brade || ||
|-
| Implement a "default" ctor for the widgets i.e. explicit Foo(QWidget* parent =0). || André Wöbbeking || ||
|-
| Get rid of libkdesu dependency in libkio, get rid of KIO::SessionData::AuthData* || Waldo || ||
|-
| Make functions in KHelpMenu virtual so they can be overridden (ex: to provide an alternative help->contents action) || George Staikos || ||
|-
| Make sure all GUI classes adopt well to palette changes. || Danimo || ||
|-
| K3ListView lacked a setDnDMode to choose between "dnd to move items" (e.g. keditbookmarks) and "dnd onto items" (e.g. kmail). Check how to do this with QListView/QTreeView... || David || ||
|-
| Add the concept of a session to KIO, in particular for KHTML so that it can have all of its jobs associated in some way (a unique key of sorts). Will make SSL much easier to implement and allow removal of many hacks, mostly involving metadata. || George Staikos || ||
|-
| Make KLibLoader default to RTLD_GLOBAL and make necessary changes to make KDE namespace clean. || Coolo || ||
|-
| Maybe just make sure we don't emit multiple copies of per-class data (vtable,RTTI), then RTLD_LOCAL should do as well, and it should(?) be simpler this way. || Lubos || ||
|-
| Many instances of creating containers on the heap instead of stack, can be replaced? [where?] || Caleb Tennis || ||
|-
| Remove all of the (const char *name) arguments to QObject derived classes. [mostly done, what's missing?] || Caleb Tennis || ||
|-
| Add KAssistant, a new KDE standards-compliant wizard, (TODO/KAssistant) Qt4 has no QWizard (only Q3Wizard left). Add a new KDE standards-compliant wizard with a bit more powerful API and features like "Steps list" pane on the left hand ofthe wizard (user can click any step if developer allowed such action). Example from OO.org: http://www.openoffice.org/dev_docs/features/2.0/images/mail_merge.jpg We could add more consistency (using themes, guidelines) in this area, as in KDE3 some apps implement wizard's features like left-hand funky pictures or help text again and again (see http://www.kolab.org/doc/kde-client-manual-0.9cvs20030801-html/c43.html). Other ideas:<ul><li>use nonintrusive "watermark" effect on the 1st or all pages http://images.apple.com/macosx/features/setup/images/index_setup20050412.jpg<li>allow to disable steps on the left-side list as an answer to calling setAppropriate().<li>QWizard's API is mostly ok for the new class, just avoid requiring to pass a pointer to page widget (as in setAppropriate()) but allow to pass QString names or IDs instead.</ul> || Jaroslaw Staniek || ||
|-
| K3IconView/K3ListView equivalents based on Qt4 interview. As discussed on kde-core-devel,this probably means a custom QItemDelegate instead, to handle single-click/double-click, execute-mode/select-mode (cf K3IconView), number of lines used for wrapping, "held" signal.In short, rewriting k3iconview features to be based on interview. For K3ListView we need to check if QTreeView supports both modes of drag-n-drop (dropping onto items, and dropping between items like in the bookmark editor). || David, Till etc. || ||
|-
|CMake:<ul><li>install man pages (e.g. doc/kdelibs/man-kbuildsycoca.8.docbook)<li>install /share/apps/ksgmltools2/customization/entities/kde-standard-accels.entities<li>win32: fix path delimiter problem generated *.bat wrapper (using ' ' instead of ';')</ul> || || ||
|-
| It looks like most of the functions KStringHandler can be removed. At least, insword, setword,remrange, and remword could be removed [DONE] . Those four don't seem to be used anywhere inside of KDE. Other functions like capitalize and reverse seem to be sparsely used. || Caleb Tennis || ||
|-
| Prevent re-entering event loop in kded to avoid reentrancy problems like with kwallet in KDE3. || Lubos || ||
|-
| Customizable KToolTip/KWhatsThis widgets, now KWhatsThis is a part of KDE GSoC "Implement OpenUsability's Context Sensitive Help Redesign" project, by Joshua Keel, mentored by Ellen Reitmayr<ul><li>initial notes: http://wiki.kde.org/tiki-index.php?page=kdelibs4+TODO%2FKToolTip<li>design page: http://wiki.kde.org/tiki-index.php?page=KWhatsThis</ul> || Jaroslaw Staniek || ||
|-
| Additional (automatic) shortcuts for KMessageBox. See http://lists.kde.org/?l=kde-usability&m=109688936328920&w=2 || Jaroslaw Staniek || ||
|-
| Port krosskjs away from KjsEmbed to Kjs || Sebastian Sauer || 4.1 ||
|-
|}

Policies/Licensing Policy

2007-07-18T10:56:24Z

Zander: /* Artistic License */ Remove the indent.

All source code in KDE SVN must meet the following requirements:
# All source files must contain a copyright header which identifies the copyright holder(s) together with a e-mail address that can be used to reach the copyright holder.
# Each source file must contain a license or a reference to a license which states under which terms the software may be used, modified and redistributed.
# Source files that are part of a library in kdelibs must be licensed under the terms of any of the following licenses:
#* '''LGPL''' as listed in {{path|kdelibs/COPYING.LIB}}
#* '''BSD license''' as listed in {{path|kdelibs/COPYING.BSD}} and below. Note that the BSD license '''does not contain the so called 'advertisement clause'.'''
#* '''X11 license''' as listed below.
# Any other source files must be licensed under the terms of one of the licenses listed under 3) or any of the following licenses:
#* '''GPL''' as listed in {{path|kdelibs/COPYING}}
#* '''QPL''' as listed below.
#* '''MIT license''' as listed below.
#* '''Artistic license''' as listed below.

== BSD License ==
<pre>
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:

1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
</pre>

== X11 License ==
<pre>
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Except as contained in this notice, the name of the X Consortium shall not be
used in advertising or otherwise to promote the sale, use or other dealings
in this Software without prior written authorization from the X Consortium.
</pre>

== QPL ==
<pre>
THE Q PUBLIC LICENSE
version 1.0

Copyright (C) 1999-2000 Trolltech AS, Norway.
Everyone is permitted to copy and
distribute this license document.

The intent of this license is to establish freedom to share and change the
software regulated by this license under the open source model.

This license applies to any software containing a notice placed by the
copyright holder saying that it may be distributed under the terms of
the Q Public License version 1.0. Such software is herein referred to as
the Software. This license covers modification and distribution of the
Software, use of third-party application programs based on the Software,
and development of free software which uses the Software.

Granted Rights

1. You are granted the non-exclusive rights set forth in this license
provided you agree to and comply with any and all conditions in this
license. Whole or partial distribution of the Software, or software
items that link with the Software, in any form signifies acceptance of
this license.

2. You may copy and distribute the Software in unmodified form provided
that the entire package, including - but not restricted to - copyright,
trademark notices and disclaimers, as released by the initial developer
of the Software, is distributed.

3. You may make modifications to the Software and distribute your
modifications, in a form that is separate from the Software, such as
patches. The following restrictions apply to modifications:

a. Modifications must not alter or remove any copyright notices in
the Software.

b. When modifications to the Software are released under this
license, a non-exclusive royalty-free right is granted to the
initial developer of the Software to distribute your modification
in future versions of the Software provided such versions remain
available under these terms in addition to any other license(s) of
the initial developer.

4. You may distribute machine-executable forms of the Software or
machine-executable forms of modified versions of the Software, provided
that you meet these restrictions:

a. You must include this license document in the distribution.

b. You must ensure that all recipients of the machine-executable forms
are also able to receive the complete machine-readable source code
to the distributed Software, including all modifications, without
any charge beyond the costs of data transfer, and place prominent
notices in the distribution explaining this.

c. You must ensure that all modifications included in the
machine-executable forms are available under the terms of this
license.

5. You may use the original or modified versions of the Software to
compile, link and run application programs legally developed by you
or by others.

6. You may develop application programs, reusable components and other
software items that link with the original or modified versions of the
Software. These items, when distributed, are subject to the following
requirements:

a. You must ensure that all recipients of machine-executable forms of
these items are also able to receive and use the complete
machine-readable source code to the items without any charge
beyond the costs of data transfer.

b. You must explicitly license all recipients of your items to use
and re-distribute original and modified versions of the items in
both machine-executable and source code forms. The recipients must
be able to do so without any charges whatsoever, and they must be
able to re-distribute to anyone they choose.

c. If the items are not available to the general public, and the
initial developer of the Software requests a copy of the items,
then you must supply one.

Limitations of Liability

In no event shall the initial developers or copyright holders be liable
for any damages whatsoever, including - but not restricted to - lost
revenue or profits or other direct, indirect, special, incidental or
consequential damages, even if they have been advised of the possibility
of such damages, except to the extent invariable law, if any, provides
otherwise.

No Warranty

The Software and this license document are provided AS IS with NO WARRANTY
OF ANY KIND, INCLUDING THE WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS
FOR A PARTICULAR PURPOSE.
Choice of Law

This license is governed by the Laws of Norway. Disputes shall be settled
by Oslo City Court.
</pre>

== MIT license ==
<pre>
Permission to use, copy, modify, and distribute this software
and its documentation for any purpose and without fee is hereby
granted, provided that the above copyright notice appear in all
copies and that both that the copyright notice and this
permission notice and warranty disclaimer appear in supporting
documentation, and that the name of the author not be used in
advertising or publicity pertaining to distribution of the
software without specific, written prior permission.

The author disclaim all warranties with regard to this
software, including all implied warranties of merchantability
and fitness. In no event shall the author be liable for any
special, indirect or consequential damages or any damages
whatsoever resulting from loss of use, data or profits, whether
in an action of contract, negligence or other tortious action,
arising out of or in connection with the use or performance of
this software.
</pre>

== Artistic License ==
<pre>
The "Artistic License"

Preamble

The intent of this document is to state the conditions under which a
Package may be copied, such that the Copyright Holder maintains some
semblance of artistic control over the development of the package,
while giving the users of the package the right to use and
distribute the Package in a more-or-less customary fashion, plus the
right to make reasonable modifications.

Definitions:

* "Package" refers to the collection of files distributed by the
Copyright Holder, and derivatives of that collection of files
created through textual modification.

* "Standard Version" refers to such a Package if it has not been
modified, or has been modified in accordance with the wishes of
the Copyright Holder.

* "Copyright Holder" is whoever is named in the copyright or
copyrights for the package.

* "You" is you, if you're thinking about copying or distributing
this Package.

* "Reasonable copying fee" is whatever you can justify on the
basis of media cost, duplication charges, time of people
involved, and so on. (You will not be required to justify it to
the Copyright Holder, but only to the computing community at
large as a market that must bear the fee.)

* "Freely Available" means that no fee is charged for the item
itself, though there may be fees involved in handling the item.
It also means that recipients of the item may redistribute it
under the same conditions they received it.

1. You may make and give away verbatim copies of the source form of
the Standard Version of this Package without restriction, provided
that you duplicate all of the original copyright notices and
associated disclaimers.

2. You may apply bug fixes, portability fixes and other
modifications derived from the Public Domain or from the Copyright
Holder. A Package modified in such a way shall still be considered
the Standard Version.

3. You may otherwise modify your copy of this Package in any way,
provided that you insert a prominent notice in each changed file
stating how and when you changed that file, and provided that you do
at least ONE of the following:

a) place your modifications in the Public Domain or
otherwise make them Freely Available, such as by posting
said modifications to Usenet or an equivalent medium, or
placing the modifications on a major archive site such as
ftp.uu.net, or by allowing the Copyright Holder to include
your modifications in the Standard Version of the Package.

b) use the modified Package only within your corporation
or organization.

c) rename any non-standard executables so the names do not
conflict with standard executables, which must also be
provided, and provide a separate manual page for each
non-standard executable that clearly documents how it
differs from the Standard Version.

d) make other distribution arrangements with the Copyright
Holder.

4. You may distribute the programs of this Package in object code or
executable form, provided that you do at least ONE of the following:

a) distribute a Standard Version of the executables and
library files, together with instructions (in the manual
page or equivalent) on where to get the Standard Version.

b) accompany the distribution with the machine-readable
source of the Package with your modifications.

c) accompany any non-standard executables with their
corresponding Standard Version executables, giving the
non-standard executables non-standard names, and clearly
documenting the differences in manual pages (or
equivalent), together with instructions on where to get
the Standard Version.

d) make other distribution arrangements with the Copyright
Holder.

5. You may charge a reasonable copying fee for any distribution of
this Package. You may charge any fee you choose for support of this
Package. You may not charge a fee for this Package itself. However,
you may distribute this Package in aggregate with other (possibly
commercial) programs as part of a larger (possibly commercial)
software distribution provided that you do not advertise this
Package as a product of your own.

6. The scripts and library files supplied as input to or produced as
output from the programs of this Package do not automatically fall
under the copyright of this Package, but belong to whomever
generated them, and may be sold commercially, and may be aggregated
with this Package.

7. C or perl subroutines supplied by you and linked into this
Package shall not be considered part of this Package.

8. The name of the Copyright Holder may not be used to endorse or
promote products derived from this software without specific prior
written permission.

9. THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.

The End

</pre>

[[Category:Policies]]

Schedules

2007-07-18T08:08:35Z

Zander: mirror rename of page

__NOTOC__

During development, the KDE project sets goals in features and dates for upcoming releases. This way, the team knows when it would be a good time to add a new feature or when it's time to
focus on cleaning up any bugs in preparation for a release. Any plans are tentative schedules and the final dates are generally decided on the kde-core-devel mailing list.

Learn more about [[/Release Schedules Guide|release schedules]].

== KDE4 ==
* [[/KDE4/Goals|KDE 4 Goals]]

*'''KDE 4.0'''
** [[/KDE4/4.0 Release Roadmap|Release milestones]]
** [[/KDE4/4.0 Module_Status|Module status and pending application issues]]
** [[/KDE4/4.0 Release Schedule|Release schedule]]
** [[/KDE4/4.0 Feature Plan|Feature plan]]

== KDE3 ==

*'''KDE 3.5''' [[/KDE 3.5 Release Schedule|release schedule]], [[/KDE 3.5 Feature Plan|feature plan]]

=== Previous releases ===

*'''KDE 3.4''' [[/KDE 3.4 Release Schedule|release schedule]], [[/KDE 3.4 Feature Plan|feature plan]]
*'''KDE 3.3''' [[/KDE 3.3 Release Schedule|release schedule]], [[/KDE 3.3 Feature Plan|feature plan]]
*'''KDE 3.2''' [[/KDE 3.2 Release Schedule|release schedule]], [[/KDE 3.2 Feature Plan|feature plan]]
*'''KDE 3.1''' [[/KDE 3.1 Release Schedule|release schedule]], [[/KDE 3.1 Feature Plan|feature plan]]
*'''KDE 3.0''' [[/KDE 3.0 Release Schedule|release schedule]], [[/KDE 3.0 Feature Plan|feature plan]]

== KOffice ==

=== Current releases ===

*'''KOffice 2.0''' [[/KOffice 2.0 Release Schedule|release schedule]], [http://wiki.koffice.org/index.php?title=KOffice2/Goals feature plan]
*'''KOffice 1.6''' [[/KOffice 1.6 Release Schedule|release schedule]], [[/KOffice 1.6 Feature Plan|feature plan]]

=== Previous releases ===

*'''KOffice 1.5''' [[/KOffice 1.5 Release Schedule|release schedule]], [[/KOffice 1.5 Feature Plan|feature plan]]
*'''KOffice 1.4''' [[/KOffice 1.4 Release Schedule|release schedule]]
*'''KOffice 1.3''' [[/KOffice 1.3 Release Schedule|release schedule]]

Development/Tutorials/Using KActions

2007-06-22T14:36:00Z

Zander: /* XmlGui */

{{TutorialBrowser|

series=Beginner Tutorial|

name=How To Use KActions and XmlGui|

pre=[[Development/Tutorials/Programming_Tutorial_KDE_4/Using_KXmlGuiWindow|Tutorial 2 - KXmlGuiWindow]], Basic XML knowledge|

next=[[Development/Tutorials/Programming_Tutorial_KDE_4/Using_KConfig|Tutorial 4 - KConfig]]|

reading=None
}}

==Abstract==
We're going to introduce the concept of actions. Actions are a unified way of supplying the user with ways to interact with your program.

Say, for example, we want to let the user clear the text box by clicking a button in the toolbar, from an option in the File menu or through a keyboard shortcut; we can provide all of those through one {{class|KAction}}.

[[image:introtokdetutorial3.png|frame|center]]

==KAction==
A {{class|KAction}} is an object which contains all the information about the icon and shortcuts you want associated to a certain action. You then connect the action to a [http://doc.trolltech.com/latest/signalsandslots.html slot] which carries out the work of your action.

===Creating Your Own===

To create an action, you need to <tt>#include <KAction></tt> in your <tt>.cpp</tt> file.
=====Creating the object=====
We're going to create an action which will clear the text area (see Tutorial 2). The KAction is built up in a number of steps. The first is creating the KAction
<code cppqt>KAction* clearAction = new KAction(actionCollection(), "clear");</code>
This creates a KAction called <tt>clearAction</tt>. The first constructor argument is telling the action that it is part of the <tt>{{class|KActionCollection}} actionCollection()</tt> and the second is simply setting a name for internal use (it doesn't necessarily have to be textually similar to the function of the action).
=====Text=====
Now we have our KAction object, we can start setting its properties. First, we'll set the text that will be displayed in the menu and under its icon in the toolbar.
<code cppqt>clearAction->setText(i18n("Clear"));</code>
As you can see, the text must be passed through the i18n() function if you want your UI to be translatable.

=====Icon=====
If you're going to display the action in a toolbar, you're going to want to have an icon depicting the action. To set an icon we simply use the <tt>setIcon()</tt> function thus:
<code cppqt>clearAction->setIcon(KIcon("filenew"));</code>
Here we're setting the icon to the standard KDE <tt>filenew</tt> icon.
=====Shortcut=====
We can also set a shortcut that will perform our action. It's as simple as a
<code cppqt>clearAction->setShortcut(Qt::CTRL+Qt::Key_W);</code>
to set Ctrl+W to be associated to this action.
=====Connecting the action=====
Now our action is fully set up, we need to connect it to something useful. We're going to connect our action to the <tt>clear()</tt> action belonging to a KTextArea.
<code cppqt>
connect( clearAction, SIGNAL( triggered(bool) ),
textArea, SLOT( clear() ) );
</code>
This is the same as it would be done in Qt with a {{qt|QAction}}.

===KStandardAction===

For actions which would likely appear in almost every KDE application such as 'quit', 'save', and 'load' there are pre-created convenience KActions, accessed through {{class|KStandardAction}}.

They are very simple to use. Once you've done <tt>#include <KStandardAction></tt>, you simply need to supply it with what you want the function to do and which KActionCollection to add it to. For example,
<code cppqt>KStandardAction::quit(kapp, SLOT(quit()), actionCollection());</code>
Will Create a KAction with the correct icon, text and shortcut and will even add it to the File menu.

==The Code==
===mainwindow.h===
<code cppqt n>
#ifndef MAINWINDOW_H
#define MAINWINDOW_H

#include <KXmlGuiWindow>
#include <KTextEdit>

class MainWindow : public KXmlGuiWindow
{
public:
MainWindow(QWidget *parent=0);

private:
KTextEdit* textArea;
void setupActions();
};

#endif
</code>

===mainwindow.cpp===
<code cppqt n>
#include "mainwindow.h"

#include <KApplication>
#include <KAction>
#include <KLocale>
#include <KActionCollection>
#include <KStandardAction>

MainWindow::MainWindow(QWidget *parent)
: KXmlGuiWindow(parent)
{
textArea = new KTextEdit;
setCentralWidget(textArea);

setupActions();
}

void MainWindow::setupActions()
{
QAction* clearAction =
actionCollection()->addAction( "clear" );
clearAction->setText(i18n("Clear"));
clearAction->setIcon(KIcon("filenew"));
clearAction->setShortcut(Qt::CTRL+Qt::Key_W);
connect(clearAction, SIGNAL(triggered(bool)),
textArea, SLOT(clear()));

KStandardAction::quit(kapp, SLOT(quit()),
actionCollection());

setupGUI();
}
</code>

===main.cpp===
<code cppqt n>
#include <KApplication>
#include <KAboutData>
#include <KCmdLineArgs>

#include "mainwindow.h"

int main (int argc, char *argv[])
{
KAboutData aboutData( "tutorial3", "Tutorial 3",
"1.0", "A simple text area using KAction etc.",
KAboutData::License_GPL, "(c) 2006" );
KCmdLineArgs::init( argc, argv, &aboutData );
KApplication app;

MainWindow* window = new MainWindow();
window->show();
return app.exec();
}
</code>

==Putting the actions in the menus and toolbars==
Now, at the moment, we've only created our new "Clear" action. It won't yet show up in the menus or in the toolbars. To tell the program where to put our actions (and to allow the end-user to move them around) we use a KDE technology called XmlGui.
===XmlGui===
{{improve|Mention that it may in future be replaced by liveui, which is in the design stage now}}

When you call <tt>setupGUI()</tt> in your {{class|KXmlGuiWindow}} class, it calls the XmlGui system which reads an XML file description of your interface (which we will create in a minute) and creates the buttons and menus appropriately.

Now obviously XmlGui needs to know which file is your description file, i.e. it needs to know its name and location. The rule for the naming is the file should be called <tt>appnameui.rc</tt> (where <tt>appname</tt> is the name you set in {{class|KAboutData}}), so in our example, the file will be called <tt>tutorial3ui.rc</tt>. Where the file will be located is handled by CMake.

===Writing your ''appname''ui.rc File===

Since the description of our UI is being defined with XML, the layout of the description must follow strict rules. We won't go through all the rules in this tutorial but for more information, see the _detailed_XmlGui_page_ (once we have a full explanation of XmlGui (or possibly liveui if that's done soon :)) on the wiki, I'll link it up).

{{improve|Walk through what the code below means}}

===tutorial3ui.rc===
<code xml n>
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE kpartgui SYSTEM "kpartgui.dtd">
<gui name="tutorial3" version="1">

<ToolBar name="mainToolBar" >
<text>Main Toolbar</text>
<Action name="clear" />
</ToolBar>
<MenuBar>
<Menu name="file" >
<text>&File</text>
<Action name="clear" />
</Menu>
</MenuBar>
</gui>
</code>

==CMake==
Now that we're using XmlGui, we need to put the <tt>tutorial3ui.rc</tt> somewhere where KDE can find it. '''This means we need to install our project somewhere.'''
===CMakeLists.txt===
<code ini n>
PROJECT(tutorial3)

FIND_PACKAGE(KDE4 REQUIRED)
INCLUDE_DIRECTORIES( ${KDE4_INCLUDES} )

SET(tutorial3_SRCS
main.cpp
mainwindow.cpp
)

KDE4_ADD_EXECUTABLE(tutorial3 ${tutorial3_SRCS})

TARGET_LINK_LIBRARIES( tutorial3 ${KDE4_KDEUI_LIBS})

install(TARGETS tutorial3 DESTINATION ${BIN_INSTALL_DIR})
install( FILES tutorial3ui.rc
DESTINATION ${DATA_INSTALL_DIR}/tutorial3 )
</code>

===Make, Install And Run===
If you don't have write access to where your KDE4 installation directory, you can install it to a folder in your home directory.

To tell CMake where to install the program, set the <tt>DCMAKE_INSTALL_PREFIX</tt> switch. So to install the program to the KDE directory, do
cmake . -DCMAKE_INSTALL_PREFIX=$KDEDIR
make install
tutorial3
Though, if you just want to install it somewhere local for testing (it's probably a bit silly to go to the effort of installing these tutorials to your KDE directory) you can do something like
cmake . -DCMAKE_INSTALL_PREFIX=/home/user/kdetmp
which will create a KDE-like directory structure under ~/kdetmp

==Moving On==
Now that we can make the GUI look like and do whatever we want, we can move on to storing application settings with [[Development/Tutorials/Programming_Tutorial_KDE_4/Using_KConfig|KConfig XT]].

[[Category:C++]]

Development/Tutorials/KOffice Overview

2007-06-04T08:43:28Z

Zander: /* Dockers */

KOffice has gotten more and more configurable through plugins over time, which is a really good thing as 3rd party developers can extend KOffice using dedicated code for their purpose.

You will learn what functionality you can place in each plugin type so you can choose wisely. There is a general guide to writing plugins and each type has a tutorial showing how to create a new plugin of that type.

well, not all required info is there yet; but this is the idea :) Anyone want to help?

__TOC__

== Generic Information ==
Plugins are a design technique with a series of steps that will lead you to a loadable plugin. If you want to know more its is interresting to read an overview at [[Development/Tutorials/Generic KOffice Plugin Creation|Generic KOffice Plugin Creation]]

== Shapes ==
In KOffice shapes are document content. This content can be manipulated by the user and can be shown on screen or printed. The fact that they are plugins means that a new content types can be added to documents by just installing the plugin and starting your favorite KOffice application.
To get a feel for what a shape is, here are some examples of existing shapes, sometimes referred to as Flake shapes because shapes are one of the two main parts of the Flake library.

We have a PathShape which is a generic vector shape capable of showing and printing any sort of vector art like SVG or EPS vector graphics.

There is a Text plugin that is capable of showing marked up text with a huge feature set including HTML capabilities and a big part of the more extensive OpenDocument format.

KSpread exports a tableShape, to allow a spread-sheet table to be embedded in other KOffice applications.

API docs start at; [http://www.koffice.org/developer/apidocs/libs-flake/classKoShapeRegistry.html KoShapeRegistry]

The tutorial on how to write your own shape plugins can be found at [[Development/Tutorials/Write a Flake Plugin|Write a Flake Plugin]]

== Tools ==

A tool is a plugin that handles user input and can manipulate either the general application data, or can manipulate a specific shape.
All user input mouse and keyboard events that are send to the document area (canvas), will be passed to the active tool. The active tool can use them to, for example, move shapes around or rotate them. If you combine a tool with a shape plugin you can make the tool manipulate the data of the shape. A good example is the text tool which is bundled with the text shape. The text tool takes all keyboard events and thereby lets the user type text in the text shape.

This gives a clear separation of control and content. The shape holds the content and a tool is required to control that content.

In general there are two types of Tools;
* generic tools that are not associated with a shape plugin. Its rare that you will create such plugins, though we still need a 'measure' tool that falls in that category.
* bundled tools that come with a specific flake shape and is made to manipulate that shapes data.

API docs start at; [http://www.koffice.org/developer/apidocs/libs-flake/classKoToolRegistry.html KoToolRegistry]

The tutorial on how to write your own shape plugins can be found at [[Development/Tutorials/Write a Flake Plugin|Write a Flake Plugin]]

== Dockers ==

Plugins that provide a docker are basically plugins that provide a graphical user interface element for KOffice applications. In KOffice2 the focus on toolbars and dialogs will be less as they have been proven to be confusing to users because they clutter the interface.
Instead the focus is shifted to widgets that can be docked along the sides of a document window but also moved to be a separate window. The real change is that, unlike dialogs, they don't have an 'Ok' button but instead change the content life and immediately.
Examples of dockers are; the toolbox, the shape selector and the tool-options but also the color selector.

API docs start at; [http://www.koffice.org/developer/apidocs/libs/classKoDockRegistry.html KoDockRegistry]

== Colorspaces ==

== File Filters ==

== Text Plugins ==

The text component used in all KOffice applications has a set of plugins itself. These plugins allow the possibility to enhance the content as well as allow to enhance the editing experience. Use Inline object plugins to write content such as inline variables and bookmarks. Use Text Editing plugins to be able to replace the text a user types while he types it. For example for autocorrection.

=== Inline Objects ===

The plugins of this type effectively become a character in the text document. What this means is that a user can insert an inline object and the plugin can decide the size and content of the character inserted.
A good example of inline objects are variables. A variable can have a name and a value and altering the value of a variable will then change the value in the text all over the document. This is done by an inline object that shows the full text of the variable, but in the document it behaves as it is one big character that can't be split over lines or otherwise edited.

An inline object does not have to have content, it can just be a placeholder as well. Which makes it ideal for things like in-text comments/annotations and Bookmarks.

API docs start at; [http://www.koffice.org/developer/apidocs/libs/classKoInlineObjectRegistry.html KoInlineObjectRegistry]

=== Text Editing ===

The text editing plugins are all about handling user input while (s)he is editing the text. A plugin can do near everything with the typed text, including altering it and adding markup.
The plugin gives events when a word and when a paragraph has been finished. Which is ideal for autocorrection and autoreplacement of text.

Examples of usages of this plugin type are; a word count in a docker updated continuesly, auto correction of text, replacing formatted text with calculated values or custom shape plugins.

API docs start at; [http://www.koffice.org/developer/apidocs/libs/classKoTextEditingRegistry.html KoTextEditingRegistry]

== Krita's plugins ==
* filters (effects)
* paintop (plugin that are in charge of painting when the user uses a drawing tool)
* viewplugin (aka misc)
See [http://docs.kde.org/development/en/koffice/krita/developers-plugins.html Krita's handbook]

Development/Tutorials/Write a Flake Plugin

2007-05-02T15:05:17Z

Zander: /* Make your shape editable - create a tool */

This tutorial will guide you step by step through the creation of a [http://wiki.koffice.org/index.php?title=Flake Flake] shape. At the end you will be able to write a shape that is loadable by any KOffice application.

For an introduction of KOffice plugins, see [[Development/Tutorials/KOffice Overview]] and for a technical introduction to plugins in KOffice see [[Development/Tutorials/Generic KOffice Plugin Creation|Generic KOffice Plugin Creation]]

=Do the groundwork - create a shape=

First of all you need a class derived from the [http://koffice.org/developer/apidocs/libs-flake/classKoShape.html KoShape] class. This will be the actual shape class so you have to ensure that all the data you need for painting is accessable for this KoShape derived class.
The only method you '''have''' to reimplement is the [http://koffice.org/developer/apidocs/libs-flake/classKoShape.html#027c57ec3dc4360294c5bb7330c768d7 paint()] method which is responsible for painting your shape.

What you might be interested in is the [http://koffice.org/developer/apidocs/libs-flake/classKoShape.html#09a45358ef20c372675790531989d5b6 resize()] and [http://koffice.org/developer/apidocs/libs-flake/classKoShape.html#5bc408a6f4d7f0bd0ea832002b96ac83 size()] method which set the available size to the shape. Some shapes define the size they need on their own so they reimplement size() to return the size they have.

An example for this is the KoFormulaShape. A formula has a fixed size due to its contents and so KoFormulaShape reimplements the size() method.
If your shape has a special outline, reimplement [http://koffice.org/developer/apidocs/libs-flake/classKoShape.html#71ac11dbac93b5bff2f91fb768fa17e5 outline()] to return your shape's outline correctly.

The rotation, scaling and skewing is done through a matrix and so you don't need to care about it.

So here is an example how your code might look like:
<pre>
#include <KoShape.h>

class KoFooShape : public KoShape {
public:
KoFooShape();
~KoFooShape();

// absolutly necessary:
void paint( QPainter &painter,
const KoViewConverter &converter );

private:
SomeDataClass* m_dataClass;
};
</pre>

=Make your shape loadable - create a factory and a plugin=

XXX: Hasn't this changed? Look at the video or picture shape -- I think we do without all of this nowadays. (Boudewijn)

Now when you have created your shape class and implemented all the necessary things to make it at least compile you can think about the loading of your shape.

The KOffice apps use [http://koffice.org/developer/apidocs/libs-flake/classKoShapeFactory.html KoShapeFactory] to get instances of shapes in a generic way. This way of obtaining shape instances is designed after [http://en.wikipedia.org/wiki/Abstract_factory_pattern the factory pattern]. So you should also implement a KoShapeFactory derived class that makes creating new instances of your shape possible. The factory class has to implement two methods:

* KoShape* createDefaultShape() const;
* KoShape* createShape( const KoProperties* params ) const;

An example factory class definition:
<pre>
class FooShapeFactory : public KoShapeFactory {
public:
FooShapeFactory( QObject *parent );

KoShape* createDefaultShape() const;
KoShape* createShape(const KoProperties* params) const;
};
</pre>
The according implementation:
<pre>
FooShapeFactory::FooShapeFactory(QObject* parent)
: KoShapeFactory( parent, "FooShape",
i18n("Foo Shape") )
{
setToolTip( i18n("A foo shape") );
}

KoShape* FooShapeFactory::createDefaultShape() const
{
KoFooShape* fooShape = new KoFooShape();
// set defaults
return fooShape;
}

KoShape* FooShapeFactory::createShape(
const KoProperties* params ) const
{
KoFooShape* fooShape = new KoFooShape();
// use the params
return fooShape;
}
</pre>

With the factory there is now a generic way to obtain an instance of your shape. But somehow you have to publish your shape as a plugin to let the KOffice application know that there is a plugin to load. Therefore the flake library provides the [http://koffice.org/developer/apidocs/libs-flake/classKoShapeRegistry.html KoShapeRegistry] class. Each application has access to the registry and to let the application know about your shape you have to register it within the registry.

To register we would have to make a call like this:
KoShapeRegistry::instance()->add( new FooShapeFactory( parent ) );
In order to make that call, we will create a plugin class which is special in that it will be automatically loaded and created by KOffice when an application starts. This means that the constructor of our plugin class will be the perfect place to actually register our shape using the above line.

The registration is done within the constructor of the FooShapePlugin class. This is a very simple class that represents the plugin and does registration.

Example plugin class definition:
<pre>
#include <QObject>

class FooShapePlugin : public QObject {
Q_OBJECT
public:
FooShapePlugin(QObject *parent, const QStringList&);
};
</pre>

Example plugin class implementation:
<pre>
#include "FooShapePlugin.h"
#include <kgenericfactory.h>

K_EXPORT_COMPONENT_FACTORY(fooshapelibrary,
KGenericFactory<FooShapePlugin>( "FooPlugin" ) )

FooShapePlugin::FooShapePlugin(QObject *parent, const QStringList&)
: QObject(parent)
{
// register the shape's factory
KoShapeRegistry::instance()->add(
new KoFooShapeFactory( parent ) );
// we could register more things here in this same plugin.
}
#include "FooShapePlugin.moc"
</pre>
This demonstrates how for the plugin related tasks KDE provides services which are dynamic loaded libraries. The secret ingredient that makes this class the plugin of that library is the call to the K_EXPORT_COMPONENT_FACTORY macro defined in kgenericfactory.h

We now have a way to create instances of your shape (FooShapeFactory), a way to register them for the apps (KoShapeRegistry) and a plugin that can dynamically be loaded (FooShapePlugin). The last step is to create a .desktop file that describes your plugin and makes it findable by KOffice. For "X-KDE-Library" you have to set the library name you have already specified within K_EXPORT_COMPONENT_FACTORY().

Example fooshape.desktop file:
<pre>
[Desktop Entry]
Encoding=UTF-8
Name=Foo Shape
ServiceTypes=KOffice/Flake
Type=Service
X-KDE-Library=fooshapelibrary
X-Flake-Version=1
</pre>

After installing that file in the kde services directory and installing your plugin where the application can open it, your plugin is system wide known and can be loaded by KOffice.

TODO; add example CMake file.

=Make your shape editable - create a tool=

To edit your shape in the GUI the user wants to select a tool and alter your shape. Therefore you have to provide a KoTool derived class. This class implements all edit actions that can be done on your shape but it is also possible to have more than one tool per shape.

Development/Tutorials/Write a Flake Plugin

2007-05-02T15:04:30Z

Zander:

This tutorial will guide you step by step through the creation of a [http://wiki.koffice.org/index.php?title=Flake Flake] shape. At the end you will be able to write a shape that is loadable by any KOffice application.

For an introduction of KOffice plugins, see [[Development/Tutorials/KOffice Overview]] and for a technical introduction to plugins in KOffice see [[Development/Tutorials/Generic KOffice Plugin Creation|Generic KOffice Plugin Creation]]

=Do the groundwork - create a shape=

First of all you need a class derived from the [http://koffice.org/developer/apidocs/libs-flake/classKoShape.html KoShape] class. This will be the actual shape class so you have to ensure that all the data you need for painting is accessable for this KoShape derived class.
The only method you '''have''' to reimplement is the [http://koffice.org/developer/apidocs/libs-flake/classKoShape.html#027c57ec3dc4360294c5bb7330c768d7 paint()] method which is responsible for painting your shape.

What you might be interested in is the [http://koffice.org/developer/apidocs/libs-flake/classKoShape.html#09a45358ef20c372675790531989d5b6 resize()] and [http://koffice.org/developer/apidocs/libs-flake/classKoShape.html#5bc408a6f4d7f0bd0ea832002b96ac83 size()] method which set the available size to the shape. Some shapes define the size they need on their own so they reimplement size() to return the size they have.

An example for this is the KoFormulaShape. A formula has a fixed size due to its contents and so KoFormulaShape reimplements the size() method.
If your shape has a special outline, reimplement [http://koffice.org/developer/apidocs/libs-flake/classKoShape.html#71ac11dbac93b5bff2f91fb768fa17e5 outline()] to return your shape's outline correctly.

The rotation, scaling and skewing is done through a matrix and so you don't need to care about it.

So here is an example how your code might look like:
<pre>
#include <KoShape.h>

class KoFooShape : public KoShape {
public:
KoFooShape();
~KoFooShape();

// absolutly necessary:
void paint( QPainter &painter,
const KoViewConverter &converter );

private:
SomeDataClass* m_dataClass;
};
</pre>

=Make your shape loadable - create a factory and a plugin=

XXX: Hasn't this changed? Look at the video or picture shape -- I think we do without all of this nowadays. (Boudewijn)

Now when you have created your shape class and implemented all the necessary things to make it at least compile you can think about the loading of your shape.

The KOffice apps use [http://koffice.org/developer/apidocs/libs-flake/classKoShapeFactory.html KoShapeFactory] to get instances of shapes in a generic way. This way of obtaining shape instances is designed after [http://en.wikipedia.org/wiki/Abstract_factory_pattern the factory pattern]. So you should also implement a KoShapeFactory derived class that makes creating new instances of your shape possible. The factory class has to implement two methods:

* KoShape* createDefaultShape() const;
* KoShape* createShape( const KoProperties* params ) const;

An example factory class definition:
<pre>
class FooShapeFactory : public KoShapeFactory {
public:
FooShapeFactory( QObject *parent );

KoShape* createDefaultShape() const;
KoShape* createShape(const KoProperties* params) const;
};
</pre>
The according implementation:
<pre>
FooShapeFactory::FooShapeFactory(QObject* parent)
: KoShapeFactory( parent, "FooShape",
i18n("Foo Shape") )
{
setToolTip( i18n("A foo shape") );
}

KoShape* FooShapeFactory::createDefaultShape() const
{
KoFooShape* fooShape = new KoFooShape();
// set defaults
return fooShape;
}

KoShape* FooShapeFactory::createShape(
const KoProperties* params ) const
{
KoFooShape* fooShape = new KoFooShape();
// use the params
return fooShape;
}
</pre>

With the factory there is now a generic way to obtain an instance of your shape. But somehow you have to publish your shape as a plugin to let the KOffice application know that there is a plugin to load. Therefore the flake library provides the [http://koffice.org/developer/apidocs/libs-flake/classKoShapeRegistry.html KoShapeRegistry] class. Each application has access to the registry and to let the application know about your shape you have to register it within the registry.

To register we would have to make a call like this:
KoShapeRegistry::instance()->add( new FooShapeFactory( parent ) );
In order to make that call, we will create a plugin class which is special in that it will be automatically loaded and created by KOffice when an application starts. This means that the constructor of our plugin class will be the perfect place to actually register our shape using the above line.

The registration is done within the constructor of the FooShapePlugin class. This is a very simple class that represents the plugin and does registration.

Example plugin class definition:
<pre>
#include <QObject>

class FooShapePlugin : public QObject {
Q_OBJECT
public:
FooShapePlugin(QObject *parent, const QStringList&);
};
</pre>

Example plugin class implementation:
<pre>
#include "FooShapePlugin.h"
#include <kgenericfactory.h>

K_EXPORT_COMPONENT_FACTORY(fooshapelibrary,
KGenericFactory<FooShapePlugin>( "FooPlugin" ) )

FooShapePlugin::FooShapePlugin(QObject *parent, const QStringList&)
: QObject(parent)
{
// register the shape's factory
KoShapeRegistry::instance()->add(
new KoFooShapeFactory( parent ) );
// we could register more things here in this same plugin.
}
#include "FooShapePlugin.moc"
</pre>
This demonstrates how for the plugin related tasks KDE provides services which are dynamic loaded libraries. The secret ingredient that makes this class the plugin of that library is the call to the K_EXPORT_COMPONENT_FACTORY macro defined in kgenericfactory.h

We now have a way to create instances of your shape (FooShapeFactory), a way to register them for the apps (KoShapeRegistry) and a plugin that can dynamically be loaded (FooShapePlugin). The last step is to create a .desktop file that describes your plugin and makes it findable by KOffice. For "X-KDE-Library" you have to set the library name you have already specified within K_EXPORT_COMPONENT_FACTORY().

Example fooshape.desktop file:
<pre>
[Desktop Entry]
Encoding=UTF-8
Name=Foo Shape
ServiceTypes=KOffice/Flake
Type=Service
X-KDE-Library=fooshapelibrary
X-Flake-Version=1
</pre>

After installing that file in the kde services directory and installing your plugin where the application can open it, your plugin is system wide known and can be loaded by KOffice.

TODO; add example CMake file.

=Make your shape editable - create a tool=

To edit your shape in the GUI the user wants to select a tool and alter your shape. Therefore you have to provide a KoTool derived class. This class implements all edit actions that can be done on your shape but it is also possible to have more than one tool per shape.

Note from TZ: I suggest creating a koffice/shapes/example dir in svn
which you can refer to from this tutorial.

Development/Tutorials/Generic KOffice Plugin Creation

2007-05-02T15:02:26Z

Zander: New page

Writing a plugin for KOffice technically means the following things are created;
* An interface that is shipped in the base-libraries will be inherited from, and functionality implemented unique to the plugin. Examples of these interfaces are KoShape, KoTool and KoColorSpace.
* A factory class is created. The factory design pattern allows the plugin to create as many instances of the plugin code as required in a flexible manner. Each plugin type has its own Factory object that should be inherited from.
* A plugin object is created. This is really a plugin-loader object and it will be created and immediately deleted by the KOffice libraries.
* A library file is installed that contains all classes that make up the plugin.
* A desktop file is installed with the information about the plugin, including the name of the library.

== The concept of a plugin. ==

The concept is really based on what Object Orientated design is saying, it means that you can create programmer-interface and encapsulate that in a class without being very clear as to what that implementation is suppost to do. You can then supply serveral classes that actually contains the implementation of the programmer-interface, each in their own way.
The actual way that the class responds to the same environment is thus the implementation and not the programmer-interface.
Plugins are a way to provide a different implementation for a known interface.

KOffice has defined several classes as base classes and has made the programmer interface of those base classes generic enough so a wide range of functionality can be accomplished by providing a plugin with a new implemntation for such a base class.

An example; one plugin type that KOffice supports is a docker widget. A docker widget is really a widget that can be shown on screen like a button or a text field are widgets as well.
The plugin can ship a new implementation of the QDockWidget class by inheriting from that QDockWidget and providing text/buttons and functionality using the full API of the Qt and KDE/KOffice libraries to do their work.
This means I can provide a plugin that ships a docker. And the docker shows the time of day, for example. By installing the plugin according to the instructions for that type of KOffice-plugin the KOffice application are able to find it and the docker will be created and shown on screen.

One unique property of a plugin is that it is self contained. Which means that the end result of the plugin is one library which exports just the 'plugin object'. This means that whatever code and classes is changed in one plugin can not possibly affect code in another plugin or even in the KOffice applications.
This has the benefit that development becomes more separated and changes in one place will not give problems in another.
It is therefor suggested to use any number of classes that fit your design and programming style, and you are free to avoid using namespaces or class name prefixes, as you wish. In other words; your plugin is walled off, nobody will be bothered by what you do, or how do you it.

== Components ==

The '''first component''' is the class that inherits from the interface this plugin represents.
Each plugin type will go into details on this as each interface has different features and requirements.

The '''factory component''' is also unique per plugin, but quite generic in setup and idea. The reason for the existance of a factory is that it makes it possible to create any number of the plugin objects at the time that the host applications want to do this, probably at the request of the user.
The workflow in general is this;
* A plugin is loaded and a factory is created. (see the plugin-object component)
* This factory is registered in a Registry.
* Applications query the registry to ask about all plugins and use, for example, the name and an icon from the factory to show buttons on screen.
* The user clicks on a button, or in another way selects the plugin factory.
* The plugin factory is then asked to create a new instance of the thing it is meant to create.
* That new shape or widget or other thing is used in the document or gui. All depending on the plugin type.

This means that our main advertisement to the outside world is the factory. As the factory is used to show the user what kind of things this plugin can do. Each plugin type has its own factory, with at minimum a create() like method which then returns a new instance.
The factories typically have a large set of user interface components you can register on them. Like a name, or an icon etc. It is wise to fill as many of them with relevant information as possible.

The next component is the '''Plugin component'''. This is a QObject inheriting class that has a specific constructor signature and, interrestingly, will be deleted immediately after it is created.
The trick therefor is to do all the work of creating and registring the factories in the constructor.
The code for this class is pretty simple, and you copy paste it with just a few modifications;

in the header file:

#include <QObject>
class MyPlugin : public QObject {
Q_OBJECT
public:
MyPlugin(QObject * parent, const QStringList &list);
};

in the cpp file;

#include "MyPlugin.h"
#include <kgenericfactory.h>
#include <KoShapeRegistry.h>
#include <KoToolRegistry.h> 
K_EXPORT_COMPONENT_FACTORY(libraryname, KGenericFactory<MyPlugin>( "MyPlugin" ) ) 
MyPlugin::MyPlugin(QObject * parent, const QStringList &)
: QObject(parent)
{
KoToolRegistry::instance()->add(new MyToolFactory(parent));
KoShapeRegistry::instance()->add(new MyShapeFactory(parent));
}
#include <MyPlugin.moc>

This example registeres 2 factories, but you can register any number you want to ship in 1 plugin. Note how only the factory is created, and nothing else is done. This makes loading of the plugin as fast as possible.
If you copy paste this code make sure you update the 'libraryname' to be the (all lowercase) name of your plugin-library. Which is also repeated in the desktop file. Note that the name is without any extentions. In the <code>K_EXPORT_COMPONENT_FACTORY</code> macro the 'MyPlugin' is repeated twice. Its easiest to just replace that with the class name you choose for your project.

The '''library''' is what will contain all the compiled classes of your plugin.

A plugin is technically implemented as a library, at least on Linux and other unixes. It is loaded as a library by KOffice near the start of the application start. As the plugin is a library all development software can create them using a linker.
It is worth noting that it is possible for your plugin to depend on external shared libraries, apart from the koffice ones. But you should install that shared library as well as your plugin.
In cmake the creation of a library goes like this;

########### Flake Plugin library ###############
project( myPlugin)
include_directories( ${KOFFICEUI_INCLUDES} ) 
SET ( myplugin_SRCS
MyPlugin.cpp
# other cpp files
) 
kde4_automoc(${myplugin_SRCS})
kde4_add_plugin(textshape ${myplugin_SRCS})
target_link_libraries(myplugin kofficeui)
install(TARGETS myplugin DESTINATION ${PLUGIN_INSTALL_DIR})
install( FILES myplugin.desktop DESTINATION ${SERVICES_INSTALL_DIR})

And last is the '''desktop-file component''' after which the plugin will be found and used by KOffice.
A desktop file is basically a database record for the KDE database of what is installed. In this case the component is a 'Service'.
For our running example here is myplugin.desktop

[Desktop Entry]
Encoding=UTF-8
Name=My Shape
ServiceTypes=KOffice/Flake
Type=Service
X-KDE-Library=myplugin
X-Flake-Version=1

A couple of things are important;
* The encoding has to match the encoding used. So make sure you use an editor that understands and writes utf-8 when editing this file.
* The name is used for the plugin-manager.
* The ServiceTypes is used to specify which registry should try to load us. One plugin can contain any number of factories, and some would say, it can contain any number of plugins. It typically is useful to combine a shape and a tool into one plugin, for example. Now, when an application looks for all shape plugins, our plugin should be found, naturally. So we can choose to use the ServiceTypes 'KOffice/Shape'. But when the application looks for tools we should also find the plugin. So we might need to have 'KOffice/Tool' instead. This gets confusing and we don't want one plugin to be loaded twice, so instead we take the more generic 'KOffice/flake' which will be searched for when either a shape or a tool is requested. Each plugin type will show the best matching ServiceType, but if you are doubtful you can always use 'KOffice/Flake'.
* The X-KDE-Library field has to contain the actual (lowercase) name of the library we created in the previous step. Without any extention.

Development/Tutorials/KOffice Overview

2007-05-02T15:00:26Z

Zander: Add link

KOffice has gotten more and more configurable through plugins over time, which is a really good thing as 3rd party developers can extend KOffice using dedicated code for their purpose.

You will learn what functionality you can place in each plugin type so you can choose wisely. There is a general guide to writing plugins and each type has a tutorial showing how to create a new plugin of that type.

well, not all required info is there yet; but this is the idea :) Anyone want to help?

__TOC__

== Generic Information ==
Plugins are a design technique with a series of steps that will lead you to a loadable plugin. If you want to know more its is interresting to read an overview at [[Development/Tutorials/Generic KOffice Plugin Creation|Generic KOffice Plugin Creation]]

== Shapes ==
In KOffice shapes are document content. This content can be manipulated by the user and can be shown on screen or printed. The fact that they are plugins means that a new content types can be added to documents by just installing the plugin and starting your favorite KOffice application.
To get a feel for what a shape is, here are some examples of existing shapes, sometimes referred to as Flake shapes because shapes are one of the two main parts of the Flake library.

We have a PathShape which is a generic vector shape capable of showing and printing any sort of vector art like SVG or EPS vector graphics.

There is a Text plugin that is capable of showing marked up text with a huge feature set including HTML capabilities and a big part of the more extensive OpenDocument format.

KSpread exports a tableShape, to allow a spread-sheet table to be embedded in other KOffice applications.

API docs start at; [http://www.koffice.org/developer/apidocs/libs-flake/classKoShapeRegistry.html KoShapeRegistry]

The tutorial on how to write your own shape plugins can be found at [[Development/Tutorials/Write a Flake Plugin|Write a Flake Plugin]]

== Tools ==

A tool is a plugin that handles user input and can manipulate either the general application data, or can manipulate a specific shape.
All user input mouse and keyboard events that are send to the document area (canvas), will be passed to the active tool. The active tool can use them to, for example, move shapes around or rotate them. If you combine a tool with a shape plugin you can make the tool manipulate the data of the shape. A good example is the text tool which is bundled with the text shape. The text tool takes all keyboard events and thereby lets the user type text in the text shape.

This gives a clear separation of control and content. The shape holds the content and a tool is required to control that content.

In general there are two types of Tools;
* generic tools that are not associated with a shape plugin. Its rare that you will create such plugins, though we still need a 'measure' tool that falls in that category.
* bundled tools that come with a specific flake shape and is made to manipulate that shapes data.

API docs start at; [http://www.koffice.org/developer/apidocs/libs-flake/classKoToolRegistry.html KoToolRegistry]

The tutorial on how to write your own shape plugins can be found at [[Development/Tutorials/Write a Flake Plugin|Write a Flake Plugin]]

== Dockers ==

Plugins that provide a docker are basically plugins that provide a graphical user interface element for KOffice applications. In KOffice2 the focus on toolbars and dialogs will be less as they have been proven to be confusing to users because they clutter the interface.
Instead the focus is shifted to widgets that can be docked along the sides of a document window but also moved to be a separate window. The real change is that, unlike dialogs, they don't have an 'Ok' button but instead change the content life and immediately.
Examples of dockers are; the toolbox, the shape selector and the tool-options but also the color selector.

== Colorspaces ==

== File Filters ==

== Text Plugins ==

The text component used in all KOffice applications has a set of plugins itself. These plugins allow the possibility to enhance the content as well as allow to enhance the editing experience. Use Inline object plugins to write content such as inline variables and bookmarks. Use Text Editing plugins to be able to replace the text a user types while he types it. For example for autocorrection.

=== Inline Objects ===

The plugins of this type effectively become a character in the text document. What this means is that a user can insert an inline object and the plugin can decide the size and content of the character inserted.
A good example of inline objects are variables. A variable can have a name and a value and altering the value of a variable will then change the value in the text all over the document. This is done by an inline object that shows the full text of the variable, but in the document it behaves as it is one big character that can't be split over lines or otherwise edited.

An inline object does not have to have content, it can just be a placeholder as well. Which makes it ideal for things like in-text comments/annotations and Bookmarks.

API docs start at; [http://www.koffice.org/developer/apidocs/libs/classKoInlineObjectRegistry.html KoInlineObjectRegistry]

=== Text Editing ===

The text editing plugins are all about handling user input while (s)he is editing the text. A plugin can do near everything with the typed text, including altering it and adding markup.
The plugin gives events when a word and when a paragraph has been finished. Which is ideal for autocorrection and autoreplacement of text.

Examples of usages of this plugin type are; a word count in a docker updated continuesly, auto correction of text, replacing formatted text with calculated values or custom shape plugins.

API docs start at; [http://www.koffice.org/developer/apidocs/libs/classKoTextEditingRegistry.html KoTextEditingRegistry]

== Krita's plugins ==
* filters (effects)
* paintop (plugin that are in charge of painting when the user uses a drawing tool)
* viewplugin (aka misc)
See [http://docs.kde.org/development/en/koffice/krita/developers-plugins.html Krita's handbook]

Development/Tutorials/KOffice Overview

2007-05-02T14:55:27Z

Zander: Initial document.

KOffice has gotten more and more configurable through plugins over time, which is a really good thing as 3rd party developers can extend KOffice using dedicated code for their purpose.

You will learn what functionality you can place in each plugin type so you can choose wisely. There is a general guide to writing plugins and each type has a tutorial showing how to create a new plugin of that type.

well, not all required info is there yet; but this is the idea :) Anyone want to help?

__TOC__

== Shapes ==
In KOffice shapes are document content. This content can be manipulated by the user and can be shown on screen or printed. The fact that they are plugins means that a new content types can be added to documents by just installing the plugin and starting your favorite KOffice application.
To get a feel for what a shape is, here are some examples of existing shapes, sometimes referred to as Flake shapes because shapes are one of the two main parts of the Flake library.

We have a PathShape which is a generic vector shape capable of showing and printing any sort of vector art like SVG or EPS vector graphics.

There is a Text plugin that is capable of showing marked up text with a huge feature set including HTML capabilities and a big part of the more extensive OpenDocument format.

KSpread exports a tableShape, to allow a spread-sheet table to be embedded in other KOffice applications.

API docs start at; [http://www.koffice.org/developer/apidocs/libs-flake/classKoShapeRegistry.html KoShapeRegistry]

The tutorial on how to write your own shape plugins can be found at [[Development/Tutorials/Write a Flake Plugin|Write a Flake Plugin]]

== Tools ==

A tool is a plugin that handles user input and can manipulate either the general application data, or can manipulate a specific shape.
All user input mouse and keyboard events that are send to the document area (canvas), will be passed to the active tool. The active tool can use them to, for example, move shapes around or rotate them. If you combine a tool with a shape plugin you can make the tool manipulate the data of the shape. A good example is the text tool which is bundled with the text shape. The text tool takes all keyboard events and thereby lets the user type text in the text shape.

This gives a clear separation of control and content. The shape holds the content and a tool is required to control that content.

In general there are two types of Tools;
* generic tools that are not associated with a shape plugin. Its rare that you will create such plugins, though we still need a 'measure' tool that falls in that category.
* bundled tools that come with a specific flake shape and is made to manipulate that shapes data.

API docs start at; [http://www.koffice.org/developer/apidocs/libs-flake/classKoToolRegistry.html KoToolRegistry]

The tutorial on how to write your own shape plugins can be found at [[Development/Tutorials/Write a Flake Plugin|Write a Flake Plugin]]

== Dockers ==

Plugins that provide a docker are basically plugins that provide a graphical user interface element for KOffice applications. In KOffice2 the focus on toolbars and dialogs will be less as they have been proven to be confusing to users because they clutter the interface.
Instead the focus is shifted to widgets that can be docked along the sides of a document window but also moved to be a separate window. The real change is that, unlike dialogs, they don't have an 'Ok' button but instead change the content life and immediately.
Examples of dockers are; the toolbox, the shape selector and the tool-options but also the color selector.

== Colorspaces ==

== File Filters ==

== Text Plugins ==

The text component used in all KOffice applications has a set of plugins itself. These plugins allow the possibility to enhance the content as well as allow to enhance the editing experience. Use Inline object plugins to write content such as inline variables and bookmarks. Use Text Editing plugins to be able to replace the text a user types while he types it. For example for autocorrection.

=== Inline Objects ===

The plugins of this type effectively become a character in the text document. What this means is that a user can insert an inline object and the plugin can decide the size and content of the character inserted.
A good example of inline objects are variables. A variable can have a name and a value and altering the value of a variable will then change the value in the text all over the document. This is done by an inline object that shows the full text of the variable, but in the document it behaves as it is one big character that can't be split over lines or otherwise edited.

An inline object does not have to have content, it can just be a placeholder as well. Which makes it ideal for things like in-text comments/annotations and Bookmarks.

API docs start at; [http://www.koffice.org/developer/apidocs/libs/classKoInlineObjectRegistry.html KoInlineObjectRegistry]

=== Text Editing ===

The text editing plugins are all about handling user input while (s)he is editing the text. A plugin can do near everything with the typed text, including altering it and adding markup.
The plugin gives events when a word and when a paragraph has been finished. Which is ideal for autocorrection and autoreplacement of text.

Examples of usages of this plugin type are; a word count in a docker updated continuesly, auto correction of text, replacing formatted text with calculated values or custom shape plugins.

API docs start at; [http://www.koffice.org/developer/apidocs/libs/classKoTextEditingRegistry.html KoTextEditingRegistry]

== Krita's plugins ==
* filters (effects)
* paintop (plugin that are in charge of painting when the user uses a drawing tool)
* viewplugin (aka misc)
See [http://docs.kde.org/development/en/koffice/krita/developers-plugins.html Krita's handbook]

Development/Tutorials

2007-05-02T14:50:33Z

Zander: /* KOffice */

Tutorials are the fastest way of finding out what KDE will do for you, and how to do it. Here is a list of currently available tutorials '''for KDE4'''. Material for KDE3 and KDE2 is available on the bottom of this page.

== Getting started ==
;[[/Programming Tutorial KDE 4|Introduction To KDE 4 Programming]]
:''Are you interested in writing applications with KDE 4? This tutorial series is aimed at those completely new to KDE programming.''

;[[/KDE4 Porting Guide|Porting Your Application]]
:''Help Porting Applications from Qt3/KDE3 to Qt4/KDE4''

;[[/CMake|Introduction to CMake]] ([[/CMake_(zh_CN)|Simplified Chinese version]])
:''How to use the CMake build system used by KDE4.''

;[[/Common Programming Mistakes|Common Programming Mistakes]]
:''Various common mistakes made while developing Qt and KDE applications and how to avoid them.''

;[[/Using Qt Designer|Using Qt Designer to build user interfaces]]
:''How to create UI files with designer, and how to integrate them into a KDE program.''

;[[/Command-Line Options|Using Command-line Options]]
:''Processing and accessing command-line arguments the easy way with KDE's command line arguments classes.''

== Testing And Debugging ==

;[[/Debugging|Debugging your application]]
:''Tips, tools and techniques to apply when debugging your KDE application''

;[[Development/Tutorials/Unittests|Writing Unittests for Qt4 and KDE4 with QTestLib]] ([http://developer.kde.org/documentation/tutorials/writingunittests/writingunittests.html Original link])
:''Tutorial by [mailto:bradh@frogmouth.net Brad Hards] that describes how to write unit tests using the QTestLib framework. It is presented as an example based tutorial, and is still under development.''

;[[/Code_Checking|Semi-automatic ways to detect code errors]]
:''Techniques you can use to detect errors in KDE code''

== Managing Configuration Data With KConfig ==
;[[/KConfig|Introduction To KConfig]]
:''An overview of the KConfig classes and how to use them in your application code''

;[[/Using KConfig XT|Using KConfig XT]]
:''Tutorial on how to efficiently use the KConfig XT framework.''

== Localization ==
;[[/Localization/Unicode|Introduction To Unicode]]
:''An introduction to what Unicode is as well as how to handle Unicode data in KDE applications.''

; [[/Localization/i18n|Writing Applications With Localization In Mind]]
:''This tutorial covers what localization is, why it's important and how to ensure your application is ready to be localized. A must read for all application developers.''

; [[/Localization/i18n Mistakes|Avoiding Common Localization Pitfalls]]
:''There are several common mistakes that prevent applications from being properly localized. Find out what they are and how to easily avoid them in this tutorial.''

; [[/Localization/Building KDE's l10n Module|Building KDE's Localization Module]]
:''Building and installing language support from KDE's localization (l10n) module is a good idea for those working on applications in the main KDE repository. Doing so will allow you to test your application in another language and spot problem areas. Learn how to do just that in this tutorial.''

; [[/Localization/i18n Build Systems|Incorporating i18n Into the Build System]]
:''Once your application is ready to be localized, the next step is to ensure that translation files are built automatically and kept up to date. This tutorial covers the necessary CMakeFiles.txt additions as well the process of distributing the resulting message catalogs with your application.''

; [[/Localization/i18n Challenges|Common i18n Challenges and Solutions]]
:''This tutorial covers challenges that you may eventually run into such as translating handbooks and other data that exists outside of the source code, merging and handling obsolete .po files, dealing with freezes, coding in languages other than English and creating independent releases of or moving applications between KDE modules.''

== Documentation ==

;[[Development/Tutorials/API_Documentation|API Documentation]]
:''This tutorial explains how to document your APIs properly.''

== Application Automation and Scripting ==

=== D-Bus ===
; [[/D-Bus/Introduction|Introduction to D-Bus]]
:''A straight-forward introduction to the core concepts in D-Bus from an application developer's perspective, this tutorial covers what D-Bus is and how it can be used by applications.''
; [[/D-Bus/Accessing Interfaces|Accessing D-Bus Interfaces]]
:''A step-by-step guide to calling D-Bus methods and connecting to D-Bus signals using QtDBus.''
; [[/D-Bus/Intermediate_D-Bus|Intermediate D-Bus]]
:''Tips to make use of QtDBus when faced with problematic real-world interfaces.''
; [[/D-Bus/Creating Interfaces|Creating D-Bus Interfaces]]
:''Learn how to expose functionality in your application by creating and using custom D-Bus interfaces. Covers generating the XML descriptions, instantiating interfaces at run time and setting up the build system with CMake.''
; [[/D-Bus/Autostart Services|D-Bus Autostart Services]]
:''Turn your application into a D-Bus autostart service with this tutorial. This D-Bus feature, also known as "D-Bus service activation", will ensure that even when your application isn't running that D-Bus calls made to it will work by relying on the D-Bus daemon itself to start your app if and when needed.''
; [[/Porting_to_D-Bus|Porting from DCOP to D-Bus]]
: ''Port your applications from DCOP to D-Bus with this handy guide.''

=== Konqueror ===
; [[/Creating Konqueror Service Menus|Creating Konqueror Service Menus]]
:''This tutorial shows you how to create mimetype-specific actions in Konqueror's context menu (aka "servicemenus").''

=== Kross ===
; [[Development/Tutorials/Kross-Tutorial|Kross Tutorial]]
:''This tutorial explains how to integrate the Kross scripting framework into an application.''

=== KOffice ===
; [[Development/Tutorials/KOffice Overview]]
:''This document shows an overview of the different KOffice plugin types and tells you what each of their purpose and strengths are.'' If you are new with KOffice plugins, this is the place to start.

; [[Development/Tutorials/Write a Flake Plugin|Creating KOffice Flake Plugins]]
:''This tutorial shows you how you can build a plugin for KOffice applications to allow you embed content in ODF documents using Flake.''

; [[Development/Tutorials/KWord Scripting|KWord Scripting]]
:''This tutorial shows how to script KWord with Python, Ruby or JavaScript using Kross.''

; [[Development/Tutorials/KSpread Scripting|KSpread Scripting]]
:''This tutorial shows how to script KSpread with Python, Ruby or JavaScript using Kross.''

; [[Development/Tutorials/Krita Scripting|Krita Scripting]]
:''This tutorial shows how to script Krita with Python, Ruby or JavaScript using Kross.''

=== SuperKaramba ===
; [[Development/Tutorials/SuperKaramba|SuperKaramba Tutorial]]
:''This tutorial provides an overview of scripting within SuperKaramba.''

== Search and Metadata ==

=== Strigi ===

; [[/Writing file analyzers|Writing file analyzers]]
:''File analyzers extract data from files to display in the file dialogs and file managers. The data gathered this way is also used to search for files. KDE4 allows the use of multiple analyzers per file type. This tutorial describes how you can write new analyzers.''

=== Nepomuk-KDE ===

; [[/Metadata/KMetaData first steps|KMetaData first steps]]
:''KMetaData is the KDE library which provides easy access to metadata in the [http://nepomuk-kde.semanticdesktop.org Nepomuk-KDE] system. Learn how to make your application create and read metadata using the KMetaData system.''

== Hardware Awareness (Solid) ==

;[[/Solid_Tutorials|Introduction to Solid]]
:''An introduction to using the Solid hardware discovery and interaction system in KDE applications.''

;[[/Solid_Network_Tutorial|Accessing Network Information]]
:''How to use the Solid system to get information about the network''

== Multimedia (Phonon) ==

;[[/Phonon/Introduction|Phonon]]
:''How to start with the multimedia API''

==Printing==

;[[/Printing Hello World|Hello World]]
:''Introduction to the KDE printing system''

;TODO Print Dialog
:''Using the KDE print dialog''

== Get Hot New Stuff ==
; [[Development/Tutorials/Introduction to Get Hot New Stuff|Introduction to Get Hot New Stuff]]
:''An introduction to the developer-friendly network update system that allows KDE applications to fetch new application data at runtime in a user friendly manner.''

;[[Development/Tutorials/KNewStuffSecure|KNewStuff Secure]] ([http://developer.kde.org/documentation/tutorials/knewstuffsecure/index.html Original Link])
:''Tutorial showing how to share resources in a secured way (KDE 3.4 and later).'' By András Mantia <amantia@kde.org>.

== Rapid Application Development ==

=== Python ===

;[[Development/Tutorials/Python introduction to signals and slots|101 Introduction to signals and slots]]
:''A simple introduction to Qt's signal and slot architecture.''

=== Ruby ===

;[http://developer.kde.org/language-bindings/ruby/kde3tutorial/index.html KDE Ruby Korundum tutorial]
:''A ruby version of Antonio Larrosa Jiménez's KDE tutorial by Richard Dale. See the [http://developer.kde.org/language-bindings/ruby/index.html Ruby Developers Corner] for Qt tutorials and other info.''

;[[Development/Tutorials/Qt4_Ruby_Tutorial|Qt4 Ruby Tutorial]]
:''Trolltech's fabulous introductory tutorial to Qt, translated to Ruby.''

=== Shell ===

;[[Development/Tutorials/Shell_Scripting_with_KDE_Dialogs|Shell Scripting with KDE dialogs]] ([http://developer.kde.org/documentation/tutorials/kdialog/t1.html Original Link]) [[Development/Tutorials/Shell_Scripting_with_KDE_Dialogs_(de)| (German version)]]
:''Tutorial by [mailto:bradh@frogmouth.net Brad Hards] that describes how to use KDE dialogs in shell scripts with kdialog. It is presented as an example based tutorial.''

== Other tutorials ==

=== 2D Plotting (KPlotWidget) ===
;[[/KPlotWidget|Using the KDE data-plotting widget]]
:''This tutorial introduces KPlotWidget, which is used for 2-D data plotting. It includes information on simple usage of the widget (including adding and modifying data sets, and customizing the plot axes and labels), and advanced customization (including extending the widget through sub-classing).''

=== Spelling and Grammar Checking (Sonnet) ===
;[[/Sonnet/SonnetTutorial|Adding spell-checking or grammar-checking to KDE applications]]
:''This tutorial introduces Sonnet and how one may use it to add language correction to your KDE application. Sonnet's auxiliary features shall be described in a separate tutorial.''

== KDE2 and KDE3 Materials ==

;[[Development/Tutorials/KDE3|KDE3 Tutorials]]
:''These tutorials cover topics related to KDE3.''

;[[Development/Tutorials/KDE2|KDE2 Tutorials]]
:''These tutorials cover topics related to KDE2.''

[[Category:KDE4]]

Projects/Widgets and Classes

2007-04-27T19:22:40Z

Zander: /* KTreeViewHeaderContextMenu */

If you have a KDE class or widget that you feel would be useful to other applications but which isn't in kdelibs, please add it to this page in alphabetical order. Please include the name of the class, a description (and a screenshot if you wish), where the source code can be found, the version of KDE required (if any), your name and the date of the entry.

== KCurve ==
{|
|-
| valign=top | '''Description''' || A widget that allows editing of spline based y=f(x) curves. Handy for cases where you want the user to control such things as tablet pressure response, color transformations, acceleration by time, aeroplane lift by angle of attack. Already used in krita, and originally (less generic code) in digiKam
|-
| '''Location''' || trunk/koffice/krita/ui/kcurve.*
|-
| '''Author''' || Casper Boemann (boemann) and Gilles (of digiKam fame)
|-
| '''Date''' || April, 05, 2007
|-
| '''Screenshots''' || [http://www.kdedevelopers.org/system/files?file=images//pressuresensitive2.preview.png Link]
|}

== KListView ==
{|
|-
| valign=top | '''Description''' || An extension to QListView that lets you categorize the items, if the applied model is sorting capable (QSortFilterProxyModel). If no categorizer is set, KListView will behave exactly as a QListView.
|-
| '''Location''' || trunk/KDE/kdebase/apps/dolphin/src/klistview[.cpp, .h, _p.h]
|-
| '''Author''' || Rafael Fernández López (ereslibre)
|-
| '''Date''' || April, 04, 2007
|-
| '''Screenshots''' || [http://www.ereslibre.es/wp-content/uploads/2007/04/categorization5.png Link]
|}

== KItemCategorizer ==
{|
|-
| valign=top | '''Description''' || The interface that lets you categorize items on the KListView class.
|-
| '''Location''' || trunk/KDE/kdebase/apps/dolphin/src/kitemcategorizer.h
|-
| '''Author''' || Rafael Fernández López (ereslibre)
|-
| '''Date''' || April, 04, 2007
|}

== KonqUndoManager ==
{|
|-
| valign=top | '''Description''' || Undo/redo support for KIO jobs. One problem might be that we're about to add "undo closing a tab" support to it...
|-
| '''Location''' || trunk/KDE/kdebase/libkonq/konq_undo.*
|-
| '''Author''' || David Faure
|-
| '''Date''' || April, 05, 2007
|}

== KoSliderCombo ==
{|
|-
| valign=top | '''Description''' || A Combobox-like widget that combines numerical input with a popup slider. It uses QStyle to draw itself so it's themed right out of the box.
|-
| '''Location''' || trunk/koffice/libs/kofficeui/KoSliderCombo.*
|-
| '''Author''' || Casper Boemann (boemann)
|-
| '''Date''' || April, 06, 2007
|-
| '''Screenshots''' || [http://www.kdedevelopers.org/system/files?file=images//comboslider_0.png Link]
|}

== KTreeViewHeaderContextMenu ==
{|
|-
| valign=top | '''Description''' || A class that takes a QListView and adds a contextmenu to its header. With this contextmenu you can show and hide the columns.

Options:
* specify which columns can be shown/hidden

Style of the contextmenu:
* Show checkboxes before column names
* Show checkboxes before column names only if the checkbox is checked
* Do not show checkboxes. Display the text "Hide"/"Show" before the column names
|-
| '''Location''' || trunk/KDE/kdepim/ktimetracker/treeviewheadercontextmenu.*
|-
| '''Author''' || Mathias Soeken (msoeken)
|-
| '''Date''' || April, 18, 2007
|}

Schedules/KOffice 2.0 Release Schedule

2007-04-24T14:09:06Z

Zander:

All dates given here are subject to revision, but we will try our best to stick to them if possible. 
[mailto:boud@valdyas.org Boudewijn Rempt] is acting as release coordinator for the KOffice 2.0 release. 
KOffice 2.0 will be released independently from KDE, but we will aim to make the alphas coincide with the KDE wide ones.

==KOffice 2.0 Alpha 1==
===June 25, 2006===
The first alpha of KOffice 2.0 is released to the public.

User:Zander

2007-04-16T16:10:37Z

Zander:

'''Thomas Zander''' 
KOffice developer 
HCI WorkingGroup member.

Jabber: zander (AT) jabber.xs4all DOT nl

User:Zander

2007-04-16T16:10:01Z

Zander: foo

Thomas Zander
KOffice developer
HCI WorkingGroup member.

Jabber: zander (AT) jabber.xs4all DOT nl

User:Danimo

2007-04-09T18:39:16Z

Zander: Bug report.

== TODO ==

* Beautify Subpage titles

== Bugs ==
sorry for reporting a bug here; but this seems like as good a place as any :)
When using <nowiki><code cpp></nowiki> tags I noted a bug. Specifically when you use the colon (or other means) to indent it. [[User:Zander|Zander]] 20:39, 9 April 2007 (CEST)
Example code:

:<code cpp>
#include <iostream>
#include <QtCore/QDate>
#include <zlib.h>
</code>

User:Mkretz

2007-04-09T17:41:29Z

Zander: /* as a library developer */

== getting #includes right ==

There are two types of #include statements: <tt>#include <foo.h></tt> and <tt>#include "foo.h"</tt>.

Say we have the file <tt>header1.h</tt> in <tt>/usr/include/mylib/</tt> that contains the following:
<code cpp n>
#include <header2.h>
#include "header3.h"
</code>

The preprocessor will search for the file <tt>header2.h</tt> in all the paths given as <tt>-I</tt> arguments and then replace the line with the contents of that file.

For line 2 the preprocessor tries to use the file /usr/include/mylib/header3.h first and if it does not exist search for the file like for <tt>header2.h</tt>. The important part to note here is that the preprocessor does not look in the directory of the source file that includes <tt>header1.h</tt> but in the directory where <tt>header1.h</tt> resides.

Now, which include statement is the one to use? After all you can specify every directory you want using <tt>-I</tt> and thus could use <tt>#include <...></tt> everywhere.

=== as an application developer ===
* Include headers from external libraries using angle brackets.
<code cpp>
#include <iostream>
#include <QtCore/QDate>
#include <zlib.h>
</code>
* Include headers from your own project using double quotes.
<code cpp>
#include "myclass.h"
</code>Using angle brackets works correctly if the first <tt>-I</tt> switch to the compiler is your own source directory. Ideally you would not need to specify <tt>-I./</tt> though, as that might break with library headers that have the same filename as a header of your project (i.e.: If a library has the header file <tt>foo.h</tt> and your project has a different file with the same filename the compiler will always pick the header from your project instead of the one from the library because the source directory of the project is specified first.)

=== as a library developer ===
* Include headers from '''external''' libraries using '''angle brackets'''.
<code cpp>
#include <iostream>
#include <QtCore/QDate>
#include <zlib.h>
</code>
* Include headers of your '''own library''' and libraries that belong to it using '''double quotes'''.
<code cpp>
#include "xyz.h" // same library and same directory
</code>

If you use subdirectories for the installed header files you need to have the exact same directory structure for the headers in the source directory. Example:

<tt>/usr/include/libfoo/</tt> contains the directory <tt>bar</tt>. In <tt>libfoo</tt> resides the header <tt>header1.h</tt>, in <tt>libfoo/bar</tt> the file <tt>header2.h</tt>. The latter depends on the former so it includes it using
<code cpp>
#include "../header1.h" // BAD IDEA
</code>
If the source directory structure of the library is not the same (in this case: <tt>header2.h</tt> in a subdirectory of the directory where <tt>header1.h</tt> resides) this obviously will break.

It is also possible to use angle brackets in library headers, but that requires the application to supply the exactly correct <tt>-I</tt> paths (e.g. libfoo above can be used either with <tt>-I/usr/include</tt> and <tt>#include <libfoo/header1.h></tt> or <tt>-I/usr/include/libfoo</tt> and <tt>#include <header1.h></tt>, if libfoo were to use angle brackets to include its own headers one of the include switches has to be present for the lib to find its own headers). Also angle brackets require the application to not put any include directory before the <tt>-I</tt> switch for the lib that contains header files of the same filename as for the library. An example how angle brackets can break the build:

<tt>/usr/include/libxyz/xyz.h</tt> includes <tt>foo.h</tt> using angle brackets and expects to have it replaced with the contents of the file <tt>/usr/include/libzyx/foo.h</tt>. Assuming there's another library that also ships a <tt>foo.h</tt> file in the directory <tt>/usr/include/anotherlib</tt>. If the application that uses both libraries compiles with
<tt>g++ -I/usr/include/libxyz -I/usr/include/anotherlib ...</tt> libxyz will work as expected (but anotherlib might break). If the application compiles with <tt>g++ -I/usr/include/anotherlib -I/usr/include/libxyz ...</tt> the header <tt>xyz.h</tt> will include the file <tt>/usr/include/anotherlib/foo.h</tt> instead of the file that is shipped with libxyz. The same problem can appear if an application has a header file of the same name as a library and specifies <tt>-I./</tt> as the first include directory.

----
I suggest replacing 'application' with 'buildsystem' in various places to avoid confusion. Further what is missing here is a small guideline section. Things that people can read and use without having to grok the whole thing. Thanks! [[User:Zander|Zander]] 19:41, 9 April 2007 (CEST)

Talk:Development/Tutorials/Unittests

2007-03-21T21:08:32Z

Zander: Did someone try the tutorial?

==Source ==

This tutorial has been taken from
http://developer.kde.org/documentation/tutorials/writingunittests/

This tutorial was originally licensed under the GFDL. It can also
be used under the terms of the Creative Commons Share-alike license.

==Placement==
Does this tutorial really belong under "Getting started" on the Tutorial page? It doesn't really seem like a beginner tutorial. At least not something that beginners to KDE4 programming would need to know. Maybe place it under Debugging (though maybe that's a bit stretched :S ) --[[User:Milliams|milliams]] 14:49, 5 January 2007 (CET)

Did someone try the tutorial? I noted that there is an include of tutorial1.moc but we use qmake in that example. I was under the impression that foo.moc was a cmake standard; qmake doesn't generate that file (its something like moc_foo.h) . You typically don't need to include anything in qmake. [[User:Zander|Zander]] 22:08, 21 March 2007 (CET)

Development/Tutorials/Unittests

2007-03-21T21:03:08Z

Zander: Clearer language.

'''Author:''' Brad Hards, Sigma Bravo Pty Limited

== Abstract ==

This article provides guidance on writing unittests for Qt4 and KDE4, based on the QtTestLib framework provided starting with Qt4.1. It provides an introduction to the ideas behind unit testing, tutorial material on the QtTestLib framework, and suggestions for getting the most value for your effort.
This document is matched to Qt 4.1 and KDE 4.

== About Unit Testing ==

A unit test is a test that checks the functionality, behaviour and correctness of a single software component. In Qt4 code (including KDE4 code) unit tests are almost always used to test a single C++ class (although testing a macro or C function is also possible).

Unit tests are a key part of Test Driven Development, however they are useful for all software development processes. It is not essential that all of the code is covered by unit tests (although that is obviously very desirable!). Even a single test is a useful step to improving code quality.

Note that unit tests are dynamic tests (i.e. they run, using the compiled code) rather than static analysis tests (which operate on the source or some intermediate representation).

Even if they don't call them "unit tests", most programmers have written some "throwaway" code that they use to check an implementation. If that code was cleaned up a little, and built into the development system, then it could be used over and over to check that the implementation is still OK. To make that work a little easier, we can use test frameworks.

Note that it is sometimes tempting to treat the unit test as a pure verification tool. While it is true that unit tests do help to ensure correct functionality and behaviour, they also assist with other aspects of code quality. Writing a unit test requires a slightly different approach to coding up a class, and thinking about what inputs need to be tested can help to identify logic flaws in the code (even before the tests get run). In addition, the need to make the code testable is a very useful driver to ensure that classes do not suffer from close coupling.

Anyway, enough of the conceptual stuff - lets talk about a specific tool that can reduce some of the effort and let us get on with the job.

==About QtTestLib==

QtTestlib is a lightweight testing library developed by Trolltech and released under the GPL (a commercial version is also available, for those who need alternative licensing). It is written in C++, and is cross-platform. It is provided as part of the tools included in Qt 4.1, and earlier versions were provided separately. Note that earlier versions had a different API, and the examples will not work with that earlier version.

In addition to normal unit testing capabilities, QtTestLib also offers basic GUI testing, based on sending QEvents. This allows you to test GUI widgets, but is not generally suitable for testing full applications.

Each testcase is a standalone test application. Unlike CppUnit or JUnit, there is no Runner type class. Instead, each testcase is an executable which is simply run.

== Tutorial 1: A simple test of a date class ==

In this tutorial, we will build a simple test for a class that represents a date, using QtTestLib as the test framework. To avoid too much detail on how the date class works, we'll just use the QDate. class that comes with Qt. In a normal unittest, you would more likely be testing code that you've written yourself.

The code below is the entire testcase.

'''Example 1. QDate test code'''
<code cppqt n>
#include <QtTest>
#include <QtCore>

class testDate: public QObject
{
Q_OBJECT
private slots:
void testValidity();
void testMonth();
};

void testDate::testValidity()
{
// 11 March 1967
QDate date( 1967, 3, 11 );
QVERIFY( date.isValid() );
}

void testDate::testMonth()
{
// 11 March 1967
QDate date;
date.setYMD( 1967, 3, 11 );
QCOMPARE( date.month(), 3 );
QCOMPARE( QDate::longMonthName(date.month()),
QString("March") );
}

QTEST_MAIN(testDate)
#include "tutorial1.moc"
</code>

Stepping through the code, the first line imports the header files for the QtTest namespace. The second line imports the headers for the QtCore namespace (not strictly necessary, since QtTest also imports it, but it is robust and safe). Lines 4 to 10 give us the test class, testData. Note that testDate inherits from QObject and has the Q_OBJECT macro - QtTestLib requires specific Qt functionality that is present in QObject.

Lines 12 to 17 provide our first test, which checks that a date is valid. Note the use of the QVERIFY macro, which checks that the condition is true. So if date.isValid() returns true, then the test will pass, otherwise the test will fail. QVERIFY is similar to ASSERT in other test suites.

Similarly, lines 19 to 27 provide another test, which checks a setter, and a couple of accessor routines. In this case, we are using QCOMPARE, which checks that the conditions are equal. So if date.month() returns 3, then that part of that test will pass, otherwise the test will fail.

{{Warning|As soon as a QVERIFY evaluates to false or a QCOMPARE does not have two equal values, the whole test is marked as failed and the next test will be stated. So in the example above, if the check at line 24 fails, then the check at lines 25 and 26 will not be run.}}

In a later tutorial we will see how to work around problems that this behaviour can cause.

Line 30 uses the QTEST_MAIN which creates an entry point routine for us, with appropriate calls to invoke the testDate unit test class.

Line 31 includes the Meta-Object compiler output, so we can make use of our QObject functionality.

The qmake project file that corresponds to that code is shown below. You would then use qmake to turn this into a Makefile and then compile it with make.

'''Example 2. QDate unit test project'''
<code>
CONFIG += qtestlib
TEMPLATE = app
TARGET +=
DEPENDPATH += .
INCLUDEPATH += .

# Input
SOURCES += tutorial1.cpp
</code>

This is a fairly normal project file, except for the addition of the <code>CONFIG += qtestlib</code>. This adds the right header and library setup to the Makefile.

This will produce an application that can then be run on the command line. The output looks like the following:

'''Example 3. QDate unit test output'''
<code>
$ ./tutorial1
********* Start testing of testDate *********
Config: Using QTest library 4.1.0, Qt 4.1.0-snapshot-20051003
PASS : testDate::initTestCase()
PASS : testDate::testValidity()
PASS : testDate::testMonth()
PASS : testDate::cleanupTestCase()
Totals: 4 passed, 0 failed, 0 skipped
********* Finished testing of testDate *********
</code>

Looking at the output above, you can see that the output includes the version of the test library and Qt itself, and then the status of each test that is run. In addition to the testValidity and testMonth tests that we defined, there is also a setup routine (initTestCase) and a teardown routine (cleanupTestCase) that can be used to do additional configuration if required.

===Failing tests===

If we had made an error in either the production code or the unit test code, then the results would show an error. An example is shown below:

'''Example 4. QDate unit test output showing failure'''
<code>
$ ./tutorial1
********* Start testing of testDate *********
Config: Using QTest library 4.1.0, Qt 4.1.0-snapshot-20051003
PASS : testDate::initTestCase()
PASS : testDate::testValidity()
FAIL! : testDate::testMonth() Compared values are not the same
Actual (date.month()): 4
Expected (3): 3
Loc: [tutorial1.cpp(25)]
PASS : testDate::cleanupTestCase()
Totals: 3 passed, 1 failed, 0 skipped
********* Finished testing of testDate *********
</code>

===Running selected tests===

When the number of test functions increases, and some of the functions take a long time to run, it can be useful to only run a selected function. For example, if you only want to run the testMonth function, then you just specify that on the command line, as shown below:

'''Example 5. QDate unit test output - selected function'''

<code>
$ ./tutorial1 testValidity
********* Start testing of testDate *********
Config: Using QTest library 4.1.0, Qt 4.1.0-snapshot-20051003
PASS : testDate::initTestCase()
PASS : testDate::testValidity()
PASS : testDate::cleanupTestCase()
Totals: 3 passed, 0 failed, 0 skipped
********* Finished testing of testDate *********
</code>

Note that the initTestCase and cleanupTestCase routines are always run, so that any necessary setup and cleanup will still be done.

You can get a list of the available functions by passing the -functions option, as shown below:

'''Example 6. QDate unit test output - listing functions'''
<code>
$ ./tutorial1 -functions
testValidity()
testMonth()
</code>

===Verbose output options===

You can get more verbose output by using the -v1, -v2 and -vs options. -v1 produces a message on entering each test function. I found this is useful when it looks like a test is hanging. This is shown below:

'''Example 7. QDate unit test output - verbose output'''

<code>
$ ./tutorial1 -v1
********* Start testing of testDate *********
Config: Using QTest library 4.1.0, Qt 4.1.0-snapshot-20051003
INFO : testDate::initTestCase() entering
PASS : testDate::initTestCase()
INFO : testDate::testValidity() entering
PASS : testDate::testValidity()
INFO : testDate::testMonth() entering
PASS : testDate::testMonth()
INFO : testDate::cleanupTestCase() entering
PASS : testDate::cleanupTestCase()
Totals: 4 passed, 0 failed, 0 skipped
********* Finished testing of testDate *********
</code>

The -v2 option shows each QVERIFY, QCOMPARE and QTEST, as well as the message on entering each test function. I found this useful for verifying that a particular step is being run. This is shown below:

''''Example 8. QDate unit test output - more verbose output'''

<code>
$ ./tutorial1 -v2
********* Start testing of testDate *********
Config: Using QTest library 4.1.0, Qt 4.1.0-snapshot-20051003
INFO : testDate::initTestCase() entering
PASS : testDate::initTestCase()
INFO : testDate::testValidity() entering
INFO : testDate::testValidity() QVERIFY(date.isValid())
Loc: [tutorial1.cpp(17)]
PASS : testDate::testValidity()
INFO : testDate::testMonth() entering
INFO : testDate::testMonth() COMPARE()
Loc: [tutorial1.cpp(25)]
INFO : testDate::testMonth() COMPARE()
Loc: [tutorial1.cpp(27)]
PASS : testDate::testMonth()
INFO : testDate::cleanupTestCase() entering
PASS : testDate::cleanupTestCase()
Totals: 4 passed, 0 failed, 0 skipped
********* Finished testing of testDate *********
</code>

The -vs option shows each signal that is emitted. In our example, there are no signals, so -vs has no effect. Getting a list of signals is useful for debugging failing tests, especially GUI tests which we will see in the third tutorial.

===Output to a file===

If you want to output the results of your testing to a file, you can use the -o filename, where you replace filename with the name of the file you want to save output to.

==Tutorial 2: Data driven testing of a date class==

In the previous example, we looked at how we can test a date class. If we decided that we really needed to test a lot more dates, then we'd be cutting and pasting a lot of code. If we subsequently changed the name of a function, then it has to be changed in a lot of places. As an alternative to introducing these types of maintenance problems into our tests, QtTestLib offers support for data driven testing.

The easiest way to understand data driven testing is by an example, as shown below:

'''Example 9. QDate test code, data driven version'''
<code cppqt n>
#include <QtTest>
#include <QtCore>

class testDate: public QObject
{
Q_OBJECT
private slots:
void testValidity();
void testMonth_data();
void testMonth();
};

void testDate::testValidity()
{
// 12 March 1967
QDate date( 1967, 3, 12 );
QVERIFY( date.isValid() );
}

void testDate::testMonth_data()
{
QTest::addColumn<int>("year"); // the year we are testing
QTest::addColumn<int>("month"); // the month we are testing
QTest::addColumn<int>("day"); // the day we are testing
QTest::addColumn<QString>("monthName"); // the name of the month

QTest::newRow("1967/3/11") << 1967 << 3 << 11 << QString("March");
QTest::newRow("1966/1/10") << 1966 << 1 << 10 << QString("January");
QTest::newRow("1999/9/19") << 1999 << 9 << 19 << QString("September");
// more rows of dates can go in here...
}

void testDate::testMonth()
{
QFETCH(int, year);
QFETCH(int, month);
QFETCH(int, day);
QFETCH(QString, monthName);

QDate date;
date.setYMD( year, month, day);
QCOMPARE( date.month(), month );
QCOMPARE( QDate::longMonthName(date.month()), monthName );
}

QTEST_MAIN(testDate)
#include "tutorial2.moc"
</code>

As you can see, we've introduced a new method - testMonth_data, and moved the specific test date out of testMonth. We've had to add some more code (which will be explained soon), but the result is a separation of the data we are testing, and the code we are using to test it.
The names of the functions are important - you must use the _data suffix for the data setup routine, and the first part of the data setup routine must match the name of the driver routine.

It is useful to visualise the data as being a table, where the columns are the various data values required for a single run through the driver, and the rows are different runs. In our example, there are four columns (three integers, one for each part of the date; and one QString ), added in lines 19 through 22. The addColumn template obviously requires the type of variable to be added, and also requires a variable name argument. We then add as many rows as required using the newRow function, as shown in lines 23 through 26. The string argument to newRow is a label, which is handy for determining what is going on with failing tests, but doesn't have any effect on the test itself.

To use the data, we simply use QFETCH to obtain the appropriate data from each row. The arguments to QFETCH are the type of the variable to fetch, and the name of the column (which is also the local name of the variable it gets fetched into). You can then use this data in a QCOMPARE or QVERIFY check. The code is run for each row, which you can see below:

'''Example 10. Results of data driven testing, showing QFETCH'''

<code>
$ ./tutorial2 -v2
********* Start testing of testDate *********
Config: Using QTest library 4.1.0, Qt 4.1.0-snapshot-20051020
INFO : testDate::initTestCase() entering
PASS : testDate::initTestCase()
INFO : testDate::testValidity() entering
INFO : testDate::testValidity() QVERIFY(date.isValid())
Loc: [tutorial2.cpp(19)]
PASS : testDate::testValidity()
INFO : testDate::testMonth() entering
INFO : testDate::testMonth(1967/3/11) COMPARE()
Loc: [tutorial2.cpp(44)]
INFO : testDate::testMonth(1967/3/11) COMPARE()
Loc: [tutorial2.cpp(45)]
INFO : testDate::testMonth(1966/1/10) COMPARE()
Loc: [tutorial2.cpp(44)]
INFO : testDate::testMonth(1966/1/10) COMPARE()
Loc: [tutorial2.cpp(45)]
INFO : testDate::testMonth(1999/9/19) COMPARE()
Loc: [tutorial2.cpp(44)]
INFO : testDate::testMonth(1999/9/19) COMPARE()
Loc: [tutorial2.cpp(45)]
PASS : testDate::testMonth()
INFO : testDate::cleanupTestCase() entering
PASS : testDate::cleanupTestCase()
Totals: 4 passed, 0 failed, 0 skipped
********* Finished testing of testDate *********
</code>

=== The QTEST macro ===

As an alternative to using QFETCH and QCOMPARE, you may be able to use the QTEST macro instead. QTEST takes two arguments, and if one is a string, it looks up that string as an argument in the current row. You can see how this can be used below, which is equivalent to the testMonth() code in the previous example.

'''Example 11. QDate test code, data driven version using QTEST'''

<code cppqt n>
void testDate::testMonth()
{
QFETCH(int, year);
QFETCH(int, month);
QFETCH(int, day);

QDate date;
date.setYMD( year, month, day);
QCOMPARE( date.month(), month );
QTEST( QDate::longMonthName(date.month()), "monthName" );
}
</code>

In the example above, note that monthname is enclosed in quotes, and we no longer have a QFETCH call for monthname.

The other QCOMPARE could also have been converted to use QTEST, however this would be less efficient, because we already needed to use QFETCH to get month for the setYMD in the line above.

===Running selected tests with selected data===

In the previous tutorial, we saw how to run a specific test by specifying the name of the test as a command line argument. In data driven testing, you can select which data you want the test run with, by adding a colon and the label for the data row. For example, if we just want to run the testMonth test for the first row, we would use <pre>./tutorial2 -v2 testMonth:1967/3/11</pre>. The result of this is shown below.

'''Example 12. QDate unit test output - selected function and data'''
<code>
$ ./tutorial2 -v2 testMonth:1967/3/11
********* Start testing of testDate *********
Config: Using QTest library 4.1.0, Qt 4.1.0-snapshot-20051020
INFO : testDate::initTestCase() entering
PASS : testDate::initTestCase()
INFO : testDate::testMonth() entering
INFO : testDate::testMonth(1967/3/11) COMPARE()
Loc: [tutorial2.cpp(44)]
INFO : testDate::testMonth(1967/3/11) COMPARE()
Loc: [tutorial2.cpp(45)]
PASS : testDate::testMonth()
INFO : testDate::cleanupTestCase() entering
PASS : testDate::cleanupTestCase()
Totals: 3 passed, 0 failed, 0 skipped
********* Finished testing of testDate *********
</code>

==Tutorial 3: Testing Graphical User Interfaces==

In the previous two tutorials, we've tested a date management class. This is an pretty typical use of unit testing. However Qt and KDE applications will make use graphical classes that take user input (typically from a keyboard and mouse). QtTestLib offers support for testing these classes, which we'll see in this tutorial.

Again, we'll use an existing class as our test environment, and again it will be date related - the standard Qt {{qt|QDateEdit}} class. For those not familiar with this class, it is a simple date entry widget (although with some powerful back end capabilities). A picture of the widget is shown below.

[[Image:Qdateedit_dlg.png|thumb|'''Figure 1. QDateEdit widget screenshot''']]

The way QtTestLib provides GUI testing is by injecting {{qt|QInputEvent}} events. To the application, these input events appear the same as normal key press/release and mouse clicks/drags. However the mouse and keyboard are unaffected, so that you can continue to use the machine normally while tests are being run.

An example of how you can use the GUI functionality of QtTestLib is shown below.

'''Example 13. QDateEdit test code'''

<code cppqt n>
#include <QtTest>
#include <QtCore>
#include <QtGui>
Q_DECLARE_METATYPE(QDate)

class testDateEdit: public QObject
{
Q_OBJECT
private slots:
void testChanges();
void testValidator_data();
void testValidator();
};

void testDateEdit::testChanges()
{
// 11 March 1967
QDate date( 1967, 3, 11 );
QDateEdit dateEdit( date );

// up-arrow should increase day by one
QTest::keyClick( &dateEdit, Qt::Key_Up );
QCOMPARE( dateEdit.date(), date.addDays(1) );

// we click twice on the "reduce" arrow at the bottom RH corner
// first we need the widget size to know where to click
QSize editWidgetSize = dateEdit.size();
QPoint clickPoint(editWidgetSize.rwidth()-2, editWidgetSize.rheight()-2);
// issue two clicks
QTest::mouseClick( &dateEdit, Qt::LeftButton, 0, clickPoint);
QTest::mouseClick( &dateEdit, Qt::LeftButton, 0, clickPoint);
// and we should have decreased day by two (one less than original)
QCOMPARE( dateEdit.date(), date.addDays(-1) );

QTest::keyClicks( &dateEdit, "25122005" );
QCOMPARE( dateEdit.date(), QDate( 2005, 12, 25 ) );

QTest::keyClick( &dateEdit, Qt::Key_Tab, Qt::ShiftModifier );
QTest::keyClicks( &dateEdit, "08" );
QCOMPARE( dateEdit.date(), QDate( 2005, 8, 25 ) );
}

void testDateEdit::testValidator_data()
{
qRegisterMetaType<QDate>("QDate");

QTest::addColumn<QDate>( "initialDate" );
QTest::addColumn<QString>( "keyclicks" );
QTest::addColumn<QDate>( "finalDate" );

QTest::newRow( "1968/4/12" ) << QDate( 1967, 3, 11 )
<< QString( "12041968" )
<< QDate( 1968, 4, 12 );

QTest::newRow( "1967/3/14" ) << QDate( 1967, 3, 11 )
<< QString( "140abcdef[" )
<< QDate( 1967, 3, 14 );
// more rows can go in here
}

void testDateEdit::testValidator()
{
QFETCH( QDate, initialDate );
QFETCH( QString, keyclicks );
QFETCH( QDate, finalDate );

QDateEdit dateEdit( initialDate );
// this next line is just to start editing
QTest::keyClick( &dateEdit, Qt::Key_Enter );
QTest::keyClicks( &dateEdit, keyclicks );
QCOMPARE( dateEdit.date(), finalDate );
}

QTEST_MAIN(testDateEdit)
#include "tutorial3.moc"
</code>

Much of this code is common with previous examples, so I'll focus on the new elements and the more important changes as we work through the code line-by-line.

Lines 1 to 3 import the various Qt declarations, as before.

Line 4 is a macro that is required for the data-driven part of this test, which I'll come to soon.

Lines 5 to 12 declare the test class - while the names have changed, it is pretty similar to the previous example. Note the testValidator and testValidator_data functions - we will be using data driven testing again in this example.

Our first real test starts in line 13. Line 16 creates a QDate, and line 17 uses that date as the initial value for a QDateEdit widget.

Lines 19 and 20 show how we can test what happens when we press the up-arrow key. The QTest::keyClick function takes a pointer to a widget, and a symbolic key name (a char or a Qt::Key). At line 20, we check that the effect of that event was to increment the date by a day. The QTest:keyClick function also takes an optional keyboard modifier (such as Qt::ShiftModifier for the shift key) and an optional delay value (in milliseconds). As an alternative to using QTest::keyClick, you can use QTest::keyPress and QTest::keyRelease to construct more complex keyboard sequences.

Lines 23 to 29 show a similar test to the previous one, but in this case we are simulating a mouse click. We need to click in the lower right hand part of the widget (to hit the decrement arrow - see Figure 1), and that requires knowing how large the widget is. So lines 23 and 24 calculate the correct point based off the size of the widget. Line 26 (and the identical line 27) simulates clicking with the left-hand mouse button at the calculated point. The arguments to Qt::mouseClick are:

*a pointer to the widget that the click event should be sent to.
*the mouse button that is being clicked.
*an optional keyboard modifier (such a Qt::ShiftModifier), or 0 for no modifiers.
*an optional click point - this defaults to the middle of the widget if not specified.
*an optional mouse delay.

In addition to QTest::mouseClick, there is also QTest::mousePress, QTest::mouseRelease, QTest::mouseDClick (providing double-click) and QTest::mouseMove. The first three are used in the same way as QTest::mouseClick. The last takes a point to move the mouse to. You can use these functions in combination to simulate dragging with the mouse.

Lines 30 and 31 show another approach to keyboard entry, using the QTest::keyClicks. Where QTest::keyClick sends a single key press, QTest::keyClicks takes a QString (or something equivalent, in line 30 a character array) that represents a sequence of key clicks to send. The other arguments are the same.

Lines 32 to 34 show how you may need to use a combination of functions. After we've entered a new date in line 30, the cursor is at the end of the widget. At line 32, we use a Shift-Tab combination to move the cursor back to the month value. Then at line 33 we enter a new month value. Of course we could have used individual calls to QTest::keyClick, however that wouldn't have been as clear, and would also have required more code.

=== Data-driven GUI testing ===

Lines 50 to 60 show a data-driven test - in this case we are checking that the validator on QDateEdit is performing as expected. This is a case where data-driven testing can really help to ensure that things are working the way they should.

At lines 52 to 54, we fetch in an initial value, a series of key-clicks, and an expected result. These are the columns that are set up in lines 39 to 41. However note that we are now pulling in a QDate, where in previous examples we used three integers and then build the QDate from those. However QDate isn't a registered type for {{qt|QMetaType}, and so we need to register it before we can use it in our data-driven testing. This is done using the Q_DECLARE_METATYPE macro in line 4 and the qRegisterMetaType function in line 38.

Lines 42 to 47 add in a couple of sample rows. Lines 42 to 44 represent a case where the input is valid, and lines 45 to 47 are a case where the input is only partly valid (the day part). A real test will obviously contain far more combinations than this.

Those test rows are actually tested in lines 55 to 59. We construct the QDateEdit widget in line 55, using the initial value. We then send an Enter key click in line 57, which is required to get the widget into edit mode. At line 58 we simulate the data entry, and at line 59 we check whether the results are what was expected.

Lines 61 and 62 are the same as we've seen in previous examples.

=== Re-using test elements ===

If you are re-using a set of events a number of times, then it may be an advantage to build a list of events, and then just replay them. This can improve maintainability and clarity of a set of tests, especially for mouse movements.

The key class for building a list of test events is imaginatively known as QTestEventList. It is a QList of QTestEvents. The normal approach is to create the list, and then use various member functions to add key and mouse events. The normal functions that you'll need are addKeyClick and addMouseClick, which are very similar to the QTest::keyClick and QTest::mouseClick functions we used earlier in this tutorial. For finer grained operations, you can also use addKeyPress, addKeyRelease, addKeyEvent, addMousePress, addMouseRelease, addMouseDClick and addMouseMove to build up more complex event lists. You can also use addDelay to add a specified delay between events. When the list has been built up, you just call simulate on each widget.

You can see how this works in the example below, which is the QDateEdit example (from above) converted to use QTestEventList.

'''Example 14. QDateEdit test code, using QTestEventList'''
<code cppqt n>
#include <QtTest>
#include <QtCore>
#include <QtGui>
Q_DECLARE_METATYPE(QDate)

class testDateEdit: public QObject
{
Q_OBJECT
private slots:
void testChanges();
void testValidator_data();
void testValidator();
};

void testDateEdit::testChanges()
{
// 11 March 1967
QDate date( 1967, 3, 11 );
QDateEdit dateEdit( date );

// up-arrow should increase day by one
QTest::keyClick( &dateEdit, Qt::Key_Up );
QCOMPARE( dateEdit.date(), date.addDays(1) );

// we click twice on the "reduce" arrow at the bottom RH corner
// first we need the widget size to know where to click
QSize editWidgetSize = dateEdit.size();
QPoint clickPoint(editWidgetSize.rwidth()-2, editWidgetSize.rheight()-2);
// build a list that contains two clicks
QTestEventList list1;
list1.addMouseClick( Qt::LeftButton, 0, clickPoint);
list1.addMouseClick( Qt::LeftButton, 0, clickPoint);
// call that list on the widget
list1.simulate( &dateEdit );
// and we should have decreased day by two (one less than original)
QCOMPARE( dateEdit.date(), date.addDays(-1) );

QTest::keyClicks( &dateEdit, "25122005" );
QCOMPARE( dateEdit.date(), QDate( 2005, 12, 25 ) );

QTestEventList list2;
list2.addKeyClick( Qt::Key_Tab, Qt::ShiftModifier );
list2.addKeyClicks( "08" );
list2.simulate( &dateEdit );
QCOMPARE( dateEdit.date(), QDate( 2005, 8, 25 ) );
}

void testDateEdit::testValidator_data()
{
qRegisterMetaType<QDate>("QDate");

QTest::addColumn<QDate>( "initialDate" );
QTest::addColumn<QTestEventList>( "events" );
QTest::addColumn<QDate>( "finalDate" );

QTestEventList eventsList1;
// this next line is just to start editing
eventsList1.addKeyClick( Qt::Key_Enter );
eventsList1.addKeyClicks( "12041968" );

QTest::newRow( "1968/4/12" ) << QDate( 1967, 3, 11 )
<< eventsList1
<< QDate( 1968, 4, 12 );

QTestEventList eventsList2;
eventsList2.addKeyClick( Qt::Key_Enter );
eventsList2.addKeyClicks( "140abcdef[" );

QTest::newRow( "1967/3/14" ) << QDate( 1967, 3, 11 )
<< eventsList2
<< QDate( 1967, 3, 14 );
// more rows can go in here
}

void testDateEdit::testValidator()
{
QFETCH( QDate, initialDate );
QFETCH( QTestEventList, events );
QFETCH( QDate, finalDate );

QDateEdit dateEdit( initialDate );

events.simulate( &dateEdit);

QCOMPARE( dateEdit.date(), finalDate );
}

QTEST_MAIN(testDateEdit)
#include "tutorial3a.moc"
</code>

This example is pretty much the same as the previous version, up to line 25. In line 26, we create a QTestEventList. We add events to the list in lines 27 and 28 - note that we don't specify the widget we are calling them on at this stage. In line 30, we simulate each event on the widget. If we had multiple widgets, we could call simulate using the same set of events.

Lines 31 to 34 are as per the previous example.

We create another list in lines 35 to 37, although this time we are using addKeyClick and addKeyClicks instead of adding mouse events. Note that an event list can contain combinations of mouse and keyboard events - it just didn't make sense in this test to have such a combination. We use the second list at line 38, and check the results in line 39.

You can also build lists of events in data driven testing as well, as shown in lines 41 to 70. The key difference is that instead of fetching a QString in each row, we are fetching a QTestEventList. This requires that we add a column of QTestEventList, rather than QString (see line 45). At lines 47 to 50, we create a list of events. At line 52 we add those events to the applicable row. We create a second list at lines 54 to 56, and add that second list to the applicable row in line 58.

We fetch the events in line 65, and use them in line 68. If we had multiple widgets, then we could use the same event list several times.

==Tutorial 4 - Testing for failure and avoiding tests==

Under some conditions, it is impossible to avoid tests failing. In this section, we'll see how to deal with these cases.

===Skipping tests===

Where a test doesn't make sense to run (for example, if the required test files aren't available, or the feature is architecture or operating system dependent), the cleanest solution is to skip the test.

Tests are skipped using the QSKIP macro. QSKIP takes two arguments - a label string that should be used to describe why the test is being skipped, and a enumerated constant that controls how much of the test is skipped. If you pass SkipSingle, and the test is data driven, then only the current row is skipped. If you pass SkipAll and the test is data driven, then all following rows are skipped. If the test is not data driven, then it doesn't matter which one is used.

You can see how QSKIP works in the example below:

'''Example 15. Unit test showing skipped tests'''
<code>
void testDate::testSkip_data()
{
QTest::addColumn<int>("val1");
QTest::addColumn<int>("val2");

QTest::newRow("1") << 1 << 1;
QTest::newRow("2") << 1 << 2;
QTest::newRow("3") << 3 << 3;
QTest::newRow("5") << 5 << 5;
QTest::newRow("4") << 4 << 5;
}

void testDate::testSkip()
{
QFETCH(int, val1);
QFETCH(int, val2);

if ( val2 == 2 )
QSKIP("Two isn't good, not doing it", SkipSingle);
if ( val1 == 5 )
QSKIP("Five! I've had enough, bailing here", SkipAll);
QCOMPARE( val1, val2 );
}
</code>

'''Example 16. Output of unit test showing skipped tests'''
<code>
$ ./tutorial4 testSkip -v2
********* Start testing of testDate *********
Config: Using QTest library 4.1.0, Qt 4.1.0-snapshot-20051107
INFO : testDate::initTestCase() entering
PASS : testDate::initTestCase()
INFO : testDate::testSkip() entering
INFO : testDate::testSkip(1) COMPARE()
Loc: [tutorial4.cpp(82)]
SKIP : testDate::testSkip(2) Two isn't good, not doing it
Loc: [tutorial4.cpp(79)]
INFO : testDate::testSkip(3) COMPARE()
Loc: [tutorial4.cpp(82)]
SKIP : testDate::testSkip(5) Five! I've had enough, bailing here
Loc: [tutorial4.cpp(81)]
PASS : testDate::testSkip()
INFO : testDate::cleanupTestCase() entering
PASS : testDate::cleanupTestCase()
Totals: 3 passed, 0 failed, 2 skipped
********* Finished testing of testDate *********
</code>

from the verbose output, you can see that the test was run on the first and third rows. The second row wasn't run because of the QSKIP call with a SkipSingle argument. Similarly, the fourth and fifth rows weren't run because the fourth row triggered a QSKIP call with a SkipAll argument.

Also note that the test didn't fail, even though there were two calls to QSKIP. Conceptually, a skipped test is a test that didn't make sense to run for test validity reasons, rather than a test that is valid but will fail because of bugs or lack of features in the code being tested.

===Handling expected failures===

If you have valid tests, but the code that you are testing doesn't pass them, then ideally you fix the code you are testing. However sometimes that isn't possible in the time that you have available, or because of a need to avoid binary incompatible changes. In this case, it is undesirable to delete or modify the unit tests - it is better to flag the test as "expected to fail", using the QEXPECT_FAIL macro. An example of this is shown below:

'''Example 17. Unit test showing expected failures'''

<code cppqt n>
void testDate::testExpectedFail()
{
QEXPECT_FAIL("", "1 is not 2, even for very large 1", Continue);
QCOMPARE( 1, 2 );
QCOMPARE( 2, 2 );

QEXPECT_FAIL("", "1 is not 2, even for very small 2", Abort);
QCOMPARE( 1, 2 );
// The next line will not be run, because we Abort on previous failure
QCOMPARE( 3, 3 );
}
</code>

'''Example 18. Output of unit test showing expected failures'''

<code>
$ ./tutorial4/tutorial4 testExpectedFail -v2
********* Start testing of testDate *********
Config: Using QTest library 4.1.0, Qt 4.1.0-snapshot-20051107
INFO : testDate::initTestCase() entering
PASS : testDate::initTestCase()
INFO : testDate::testExpectedFail() entering
INFO : testDate::testExpectedFail() Compared values are not the same
Actual (1): 1
Expected (2): 2
Loc: [tutorial4.cpp(41)]
XFAIL : testDate::testExpectedFail() 1 is not 2, even for very large 1
Loc: [tutorial4.cpp(41)]
INFO : testDate::testExpectedFail() COMPARE()
Loc: [tutorial4.cpp(42)]
INFO : testDate::testExpectedFail() Compared values are not the same
Actual (1): 1
Expected (2): 2
Loc: [tutorial4.cpp(45)]
XFAIL : testDate::testExpectedFail() 1 is not 2, even for very small 2
Loc: [tutorial4.cpp(45)]
PASS : testDate::testExpectedFail()
INFO : testDate::cleanupTestCase() entering
PASS : testDate::cleanupTestCase()
Totals: 3 passed, 0 failed, 0 skipped
********* Finished testing of testDate *********
</code>

As you can see from the verbose output, we expect a failure from each time we do a QCOMPARE( 1, 2);. In the first call to QEXPECT_FAIL, we use the Continue argument, so the rest of the tests will still be run. However in the second call to QEXPECT_FAILwe use the Abort and the test bails at this point. Generally it is better to use Continue unless you have a lot of closely related tests that would each need a QEXPECT_FAIL entry.

Also note that tests that are marked as expected failures are not considered to be failures, so the test function above is considered to be a pass.

If a test that is marked to be an expected failure, and it unexpectedly passes, then that is flagged as an error, as shown below:

'''Example 19. Unit test showing unexpected pass'''
<code cppqt n>
void testDate::testUnexpectedPass()
{
QEXPECT_FAIL("", "1 is not 2, even for very large 1", Continue);
QCOMPARE( 1, 1 );
QCOMPARE( 2, 2 );

QEXPECT_FAIL("", "1 is not 2, even for very small 2", Abort);
QCOMPARE( 1, 1 );
QCOMPARE( 3, 3 );
}
</code>

'''Example 20. Output of unit test showing unexpected pass'''

<code>
$ ./tutorial4/tutorial4 testUnexpectedPass -v2
********* Start testing of testDate *********
Config: Using QTest library 4.1.0, Qt 4.1.0-snapshot-20051107
INFO : testDate::initTestCase() entering
PASS : testDate::initTestCase()
INFO : testDate::testUnexpectedPass() entering
INFO : testDate::testUnexpectedPass() COMPARE()
Loc: [tutorial4.cpp(53)]
XPASS : testDate::testUnexpectedPass() COMPARE()
Loc: [tutorial4.cpp(53)]
INFO : testDate::testUnexpectedPass() COMPARE()
Loc: [tutorial4.cpp(54)]
INFO : testDate::testUnexpectedPass() COMPARE()
Loc: [tutorial4.cpp(57)]
XPASS : testDate::testUnexpectedPass() COMPARE()
Loc: [tutorial4.cpp(57)]
INFO : testDate::cleanupTestCase() entering
PASS : testDate::cleanupTestCase()
Totals: 2 passed, 2 failed, 0 skipped
********* Finished testing of testDate *********
</code>

As you can see from the verbose output, we expect a failure from each time we do a QCOMPARE( 1, 2);. In the first call to QEXPECT_FAIL, we use the Continue argument, so the rest of the tests will still be run. However in the second call to QEXPECT_FAILwe use the Abort and the test bails at this point. Generally it is better to use Continue unless you have a lot of closely related tests that would each need a QEXPECT_FAIL entry.

Also note that tests that are marked as expected failures are not considered
to be failures, so the test function above is considered to be a pass.

If a test that is marked to be an expected failure, and it unexpectedly passes, then that is flagged as an error, as shown below:

'''Example 19. Unit test showing unexpected pass'''

<code cppqt n>
void testDate::testUnexpectedPass()
{
QEXPECT_FAIL("", "1 is not 2, even for very large 1", Continue);
QCOMPARE( 1, 1 );
QCOMPARE( 2, 2 );

QEXPECT_FAIL("", "1 is not 2, even for very small 2", Abort);
QCOMPARE( 1, 1 );
QCOMPARE( 3, 3 );
}
</code>

'''Example 20. Output of unit test showing unexpected pass'''

<code>
$ ./tutorial4/tutorial4 testUnexpectedPass -v2
********* Start testing of testDate *********
Config: Using QTest library 4.1.0, Qt 4.1.0-snapshot-20051107
INFO : testDate::initTestCase() entering
PASS : testDate::initTestCase()
INFO : testDate::testUnexpectedPass() entering
INFO : testDate::testUnexpectedPass() COMPARE()
Loc: [tutorial4.cpp(53)]
XPASS : testDate::testUnexpectedPass() COMPARE()
Loc: [tutorial4.cpp(53)]
INFO : testDate::testUnexpectedPass() COMPARE()
Loc: [tutorial4.cpp(54)]
INFO : testDate::testUnexpectedPass() COMPARE()
Loc: [tutorial4.cpp(57)]
XPASS : testDate::testUnexpectedPass() COMPARE()
Loc: [tutorial4.cpp(57)]
INFO : testDate::cleanupTestCase() entering
PASS : testDate::cleanupTestCase()
Totals: 2 passed, 2 failed, 0 skipped
********* Finished testing of testDate *********
</code>

The effect of unexpected passes on the running of the test is controlled by the second argument to QEXPECT_FAIL. If the argument is Continue and the test unexpectedly passes, then the rest of the test function will be run. If the argument is Abort, then the test will stop.

===Checking debug messages and warnings===

If you are testing border cases, you will likely run across the case where some kind of message will be produced using the qDebug or qWarning functions. Where a test produces a debug or warning message, that message will be logged in the test output (although it will still be considered a pass unless some other check fails), as shown in the example below:

Example 21. Unit test producing warning and debug messages
<code cppqt n>
void testDate::testQdebug()
{
qWarning("warning");
qDebug("debug");
qCritical("critical");
}
</code>

'''Example 22. Output of unit test producing warning and debug messages'''
<code>
$ ./tutorial4 testQdebug
********* Start testing of testDate *********
Config: Using QTest library 4.1.0, Qt 4.1.0-snapshot-20051107
PASS : testDate::initTestCase()
QWARN : testDate::testQdebug() warning
QDEBUG : testDate::testQdebug() debug
QSYSTEM: testDate::testQdebug() critical
PASS : testDate::testQdebug()
PASS : testDate::cleanupTestCase()
Totals: 3 passed, 0 failed, 0 skipped
********* Finished testing of testDate *********
</code>

Note that while this example produces the debug and warning messages within the test function (testQdebug), those messages would normally be propagated up from the code being tested. However the source of the messages does not make any difference to how they are handled.

If your test needs include either a clean output, or verification that appropriate messages are generated, then you will probably need the QtTest::ignoreMessage function.

{{Tip|'''Note:''' The ignoreMessage function can be used to ignore a message, however it might be clearer to think of this function as checking for the presence of an expected message. In particular, it is a test failure if you call ignoreMessage and the message is not generated.}}

An example of how ignoreMessage works is shown below.

'''Example 23. Example of using ignoreMessage'''
<code cppqt n>
void testDate::testValidity()
{
QTest::ignoreMessage(QtWarningMsg, "validity warning");
qWarning("validity warning");
}

void testDate::testValiditi()
{
QTest::ignoreMessage(QtWarningMsg, "validity warning");
qWarning("validiti warning");
}
</code>

'''Example 24. Output of ignoreMessage example'''
<code>
$ ./tutorial4 testValidity testValiditi
********* Start testing of testDate *********
Config: Using QTest library 4.1.0, Qt 4.1.0-snapshot-20051107
PASS : testDate::initTestCase()
PASS : testDate::testValidity()
QWARN : testDate::testValiditi() validiti warning
INFO : testDate::testValiditi() Did not receive message: "validity warning"
FAIL! : testDate::testValiditi() Not all expected messages were received
PASS : testDate::cleanupTestCase()
Totals: 3 passed, 1 failed, 0 skipped
********* Finished testing of testDate *********
</code>

Note that the warning message in testDate::testValidity has been "swallowed" by the the call to ignoreMessage.

By contrast, the warning message in testDate::testValiditi still causes a warning to be logged, because the ignoreMessage call does not match the text in the warning message. In addition, because a we expected a particular warning message and it wasn't received, the testDate::testValiditi test function fails.

==Tutorial 5: Testing Qt slots and signals==

An important part of Qt programming is the use of signals and slots. This section covers the support for testing of these features.

{{Tip|'''Note:''' If you are not familiar with Qt signals and slots, you probably should review the introduction to this feature provided in your Qt documentation. It is also available at http://doc.trolltech.com/latest/signalsandslots.html. You also might like to review Tutorial 5 in your Qt documentation. This tutorial is also available at http://doc.trolltech.com/latest/tutorial-t5.html.}}

===Testing slots===

Testing slots is very easy, because a slot is just a specially annotated method. You can call slots just like any other method you'd like to test, as shown below:

'''Example 25. QLabel test code, showing testing of a couple of slots'''
<code cppqt n>
#include <QtTest>
#include <QtCore>
#include <QtGui>

class testLabel: public QObject
{
Q_OBJECT
private slots:
void testChanges();
};

void testLabel::testChanges()
{
QLabel label;

// setNum() is a QLabel slot, but we can just call it like any
// other method.
label.setNum( 3 );
QCOMPARE( label.text(), QString("3") );

// clear() is also a slot.
label.clear();
QVERIFY( label.text().isEmpty() );
}

QTEST_MAIN(testLabel)
#include "tutorial5.moc"
</code>

===Testing signals===
Testing of signals is a little more difficult than testing of slots, however Qt offers a very useful class called QSignalSpy that helps a lot.

{{qt|QSignalSpy}} is a class provided with Qt that allows you to record the signals that have been emitted from a particular QObject subclass object. You can then check that the right number of signals have been emitted, and that the right kind of signals were emitted. You can find more information on the QSignalSpy class in your Qt documentation.

An example of how you can use QSignalSpy to test a class that has signals is shown below.

'''Example 26. QCheckBox test code, showing testing of signals'''

<code cppqt n>
#include <QtTest>
#include <QtCore>
#include <QtGui>

class testCheckBox: public QObject
{
Q_OBJECT
private slots:
void testSignals();
};

void testCheckBox::testSignals()
{
// You don't need to use an object created with "new" for
// QSignalSpy, I just needed in in this case to test the emission
// of a destroyed() signal.
QCheckBox *xbox = new QCheckBox;

// We are going to have two signal monitoring classes in use for
// this test.
// The first monitors the stateChanged() signal.
// Also note that QSignalSpy takes a pointer to the object.
QSignalSpy stateSpy( xbox, SIGNAL( stateChanged(int) ) );

// Not strictly necessary, but I like to check that I have set up
// my QSignalSpy correctly.
QVERIFY( stateSpy.isValid() );

// Now we check to make sure we don't have any signals already
QCOMPARE( stateSpy.count(), 0 );

// Here is a second monitoring class - this one for the
// destroyed() signal.
QSignalSpy destroyedSpy( xbox, SIGNAL( destroyed() ) );
QVERIFY( destroyedSpy.isValid() );

// A sanity check to verify the initial state
// This also shows that you can mix normal method checks with
// signal checks.
QCOMPARE( xbox->checkState(), Qt::Unchecked );

// Shouldn't already have any signals
QCOMPARE( destroyedSpy.count(), 0 );

// If we change the state, we should get a signal.
xbox->setCheckState( Qt::Checked );
QCOMPARE( stateSpy.count(), 1 );

xbox->setCheckState( Qt::Unchecked );
QCOMPARE( stateSpy.count(), 2 );

xbox->setCheckState( Qt::PartiallyChecked );
QCOMPARE( stateSpy.count(), 3 );

// If we destroy the object, the signal should be emitted.
delete xbox;

// So the count of objects should increase.
QCOMPARE( destroyedSpy.count(), 1 );

// We can also review the signals that we collected
// QSignalSpy is really a QList of QLists, so we take the first
// list, which corresponds to the arguments for the first signal
// we caught.
QList<QVariant> firstSignalArgs = stateSpy.takeFirst();
// stateChanged() only has one argument - an enumerated type (int)
// So we take that argument from the list, and turn it into an integer.
int firstSignalState = firstSignalArgs.at(0).toInt();
// We can then check we got the right kind of signal.
QCOMPARE( firstSignalState, static_cast<int>(Qt::Checked) );

// check the next signal - note that takeFirst() removes from the list
QList<QVariant> nextSignalArgs = stateSpy.takeFirst();
// this shows another way of fudging the argument types
Qt::CheckState nextSignalState = (Qt::CheckState)nextSignalArgs.at(0).toInt();
QCOMPARE( nextSignalState, Qt::Unchecked );

// and again for the third signal
nextSignalArgs = stateSpy.takeFirst();
nextSignalState = (Qt::CheckState)nextSignalArgs.at(0).toInt();
QCOMPARE( nextSignalState, Qt::PartiallyChecked );
}

QTEST_MAIN(testCheckBox)
#include "tutorial5a.moc"
</code>

The first 11 lines are essentially unchanged from previous examples that we've seen. Line 15 creates the object that will be tested - as noted in the comments in lines 12-14, the only reason that I'm creating it with new is because I need to delete it in line 45 to cause the destroyed() signal to be emitted.

Line 20 sets up the first of our two QSignalSpy instances. The one in line 20 monitors the stateChanged(int) signal, and the one in line 29 monitors the destroyed() signal. If you get the name or signature of the signal wrong (for example, if you use stateChanged() instead of stateChanged(int)), then this will not be caught at compile time, but will result in a runtime failure. You can test if things were set up correctly using the isValid(), as shown in lines 24 and 30.

As shown in line 34, there is no reason why you cannot test normal methods, signals and slots in the same test.

Line 38 changes the state of the object under test, which is supposed to result in a stateChanged(int) signal being emitted. Line 39 checks that the number of signals increases from zero to one. Lines 40 and 41 repeat the process, and again in lines 42 and 43.

Line 45 deletes the object under test, and line 47 tests that the destroyed() signal has been emitted.

For signals that have arguments (such as our stateChanged(int) signal), you may also wish to check that the arguments were correct. You can do this by looking at the list of signal arguments. Exactly how you do this is fairly flexible, however for simple tests like the one in the example, you can manually work through the list using takeFirst() and check that each argument is correct. This is shown in line 52, 55 and 57 for the first signal. The same approach is shown in lines 59, 61 and 62 for the second signal, and the in lines 64 to 66 for the third signal. For a more complex set of tests, you may wish to apply some data driven techniques.

{{Tip|'''Note:''' You should be aware that, for some class implementations, you may need to return control to the event loop to have signals emitted. If you need this, try using the {{qt|QTest}}::qWait() function.}}

==Tutorial 6: Integrating with CMake==

The KDE4 build tool is [http://www.cmake.org CMake], and I assume that you are familiar with the use of CMake. If not, you should review the [[Development/Tutorials/CMake|CMake Tutorial]] first.

CMake offers quite good support for unit testing, and QTestLib tests can be easily integrated into any CMake build system.

=== Configuring for Testing ===

Tests are not built by default - you have to enable the test system, and build the tests.

You enable tests by adding an '''ENABLE_TESTING()''' line to the top of your CMakeLists.txt file.

In some configurations, there may be a build system option to turn on (or off) the compilation of tests. At this stage, you have to enable the '''BUILD_TESTING''' option in KDE4 modules, however this may go away in the near future, as later version of CMake can build the test applications on demand.

=== Adding Tests ===

You add a single test to the list of all tests that can be run by using
'''ADD_TEST''', which takes a number of arguments:
* The first argument is a display name for the test. This is required.
* The second argument is the name of the executable to be run (including the path to that executable, if required). This is required.
* Any following arguments are passed to the executable. These are optional, and are usually omitted for QTestLib tests.

Note that '''ADD_TEST''' does nothing if '''ENABLE_TESTING()''' has not been run.

When choosing a display name, you should adopt a similar convention to the existing tests (e.g. in kdelibs/kdecore, all the display names start with kdecore-, which makes it easy to find the failing test if you run all the tests in kdelibs). If there are no existing tests, using a submodule prefix is probably a good idea.

The executable doesn't need to be something you build, but it will be for QTestLib, and many other tests. Remember that you need to specify the path, so this normally looks something like "${EXECUTABLE_OUTPUT_PATH}/testapp".

=== KDE4 CMake Recipe for QTestLib ===

If you are working in a KDE4 environment, then it is pretty easy to get CMake set up to build and run a test on demand.

<code>
set(kwhatevertest_SRCS kwhateverest.cpp )

kde4_automoc(${kwhatevertest_SRCS})

kde4_add_executable(kwhatevertest NOGUI RUN_UNINSTALLED ${kwhatevertest_SRCS})

target_link_libraries(kwhatevertest ${KDE4_KDECORE_LIBS} ${QT_QTTEST_LIBRARY})

add_test(ksubmodule-kwhatevertest ${EXECUTABLE_OUTPUT_PATH}/kwhatevertest)
</code>

You are meant to replace "kwhatevertest" with the name of your test application. The target_link_libraries() line will need to contain whatever libraries are needed for the feature you are testing, so if it is a GUI feature, you'll likely need to use "${KDE4_KDEUI_LIBS}.

=== Running the Tests ===
To run all tests, you can just "make test". This will work through each of the tests that have been added (at any lower level) using '''ADD_TEST'''.

This is equivalent to running the "ctest" executable with no arguments. If you want finer grained control over which tests are run or the output format, you can use additional arguments. These are explained in the ctest man page ("man ctest" on a *nix system, or run "ctest --help-full").

=== Further Reading ===

Chapter 8 of the [http://www.kitware.com/products/cmakebook.html CMake Book] provides a detailed description of how to do testing with CMake. Also see Appendix B for more on CTest and the special commands you can use.

Various sections of the CMake Wiki, especially [http://www.cmake.org/Wiki/CMake_Testing_With_CTest CTest testing]

==Tutorial 7: Integrating with qmake==

TODO

==Tutorial 8: XML output==
TODO

== Alternative tools for testing ==

There are a range of alternative testing approaches that can
be used either with unit tests, or as an addition to the unit tests.

===Static tests===
As noted in the introduction, unit tests are dynamic tests - they exercise the compiled code. Static tests are slightly different - they look for problems in source code, rather than making sure that the object code runs correctly.

Static test tools tend to identify completely different types of problems to unit tests, and you should seek to use them both.

For more information on using static tests, see [[../Code Checking|the Code Checking tutorial]].

===Coverage tools and valgrind===
TODO

=== GUI application testing - Squish and KDExecutor ===
TODO

==Conclusions==
TODO

[[Category:KDE4]]

Development/Tutorials

2007-03-16T19:13:32Z

Zander: Add link

Tutorials are the fastest way of finding out what KDE will do for you, and how to do it. Here is a list of currently available tutorials '''for KDE4'''. Material for KDE3 and KDE2 is available on the bottom of this page.

== Getting started ==
;[[/Programming Tutorial KDE 4|Introduction To KDE 4 Programming]]
:''You are interested in writing applications with KDE 4? This tutorial series is aimed at those completely new to KDE programming.''

;[[/KDE4 Porting Guide|Porting Your Application]]
:''Help Porting Applications from Qt3/KDE3 to Qt4/KDE4''

;[[/CMake|Introduction to CMake]]
:''How to use the CMake build system used by KDE4.''

;[[/Using Qt Designer|Using Qt Designer to build user interfaces]]
:''How to create UI files with designer, and how to integrate them into a KDE program.''

;[[/Command-Line Options|Using Command-line Options]]
:''Processing and accessing command-line arguments the easy way with KDE's powerful command line arguments classes.''

== Testing And Debugging ==

;[[/Debugging|Debugging your application]]
:''Tips, tools and techniques to apply when debugging your KDE application''

;[[Development/Tutorials/Unittests|Writing Unittests for Qt4 and KDE4 with QTestLib]] ([http://developer.kde.org/documentation/tutorials/writingunittests/writingunittests.html Original link])
:''Tutorial by [mailto:bradh@frogmouth.net Brad Hards] that describes how to write unit tests using the QTestLib framework. It is presented as an example based tutorial, and is still under development.''

;[[/Code_Checking|Semi-automatic ways to detect code errors]]
:''Techniques you can use to detect errors in KDE code''

== Managing Configuration Data With KConfig ==
;[[/KConfig|Introduction To KConfig]]
:''An overview of the KConfig classes and how to use them in your application code''

;[[/Using KConfig XT|Using KConfig XT]]
:''Tutorial on how to efficiently use the KConfig XT framework.''

== Localization ==
;[[/Localization/Unicode|Introduction To Unicode]]
:''An introduction to what Unicode is as well as how to handle Unicode data in KDE applications.''

; [[/Localization/i18n|Writing Applications With Localization In Mind]]
:''This tutorial covers what localization is, why it's important and how to ensure your application is ready to be localized. A must read for all application developers.''

; [[/Localization/i18n Mistakes|Avoiding Common Localization Pitfalls]]
:''There are several common mistakes that prevent applications from being properly localized. Find out what they are and how to easily avoid them in this tutorial.''

; [[/Localization/Building KDE's l10n Module|Building KDE's Localization Module]]
:''Building and installing language support from KDE's localization (l10n) module is a good idea for those working on applications in the main KDE repository. Doing so will allow you to test your application in another language and spot problem areas. Learn how to do just that in this tutorial.''

; [[/Localization/i18n Build Systems|Incorporating i18n Into the Build System]]
:''Once your application is ready to be localized, the next step is to ensure that translation files are built automatically and kept up to date. This tutorial covers the necessary CMakeFiles.txt additions as well the process of distributing the resulting message catalogs with your application.''

; [[/Localization/i18n Challenges|Common i18n Challenges and Solutions]]
:''This tutorial covers challenges that you may eventually run into such as translating handbooks and other data that exists outside of the source code, merging and handling obsolete .po files, deeling with freezes, coding in languages other than English and creating independent releases of or moving applications between KDE modules.''

== Documentation ==

;[[Development/Tutorials/API_Documentation|API Documentation]]
:''This tutorial explains how to document your APIs properly.''

== Application Automation and Scripting ==

=== D-Bus ===
; [[/D-Bus/Introduction|Introduction to D-Bus]]
:''A straight-forward introduction to the core concepts in D-Bus from an application developer's perspective, this tutorial covers what D-Bus is and how it can be used by applications.''
; [[/D-Bus/Accessing Interfaces|Accessing D-Bus Interfaces]]
:''A step-by-step guide to calling D-Bus methods and connecting to D-Bus signals using QtDBus.''
; [[/D-Bus/Intermediate_D-Bus|Intermediate D-Bus]]
:''Tips to make use of QtDBus when faced with problematic real-world interfaces.''
; [[/D-Bus/Creating Interfaces|Creating D-Bus Interfaces]]
:''Learn how to expose functionality in your application by creating and using custom D-Bus interfaces. Covers generating the XML descriptions, instantiating interfaces at run time and setting up the build system with CMake.''
; [[/D-Bus/Autostart Services|D-Bus Autostart Services]]
:''Turn your application into a D-Bus autostart service with this tutorial. This D-Bus feature, also known as "D-Bus service activation", will ensure that even when your application isn't running that D-Bus calls made to it will work by relying on the D-Bus daemon itself to start your app if and when needed.''
; [[/Porting_to_D-Bus|Porting from DCOP to D-Bus]]
: ''Port your applications from DCOP to D-Bus with this handy guide.''

=== Konqueror ===
; [[/Creating Konqueror Service Menus|Creating Konqueror Service Menus]]
:''This tutorial shows you how to create mimetype-specific actions in Konqueror's context menu (aka "servicemenus").''

===Kross===
; [[Development/Tutorials/Kross-Tutorial|Kross Tutorial]] ([http://wiki.koffice.org/index.php?title=Kross/Tutorial Original Link])
:''This tutorial explains how to integrate the Kross scripting framework into an application.''

=== KOffice ===
; [[Development/Tutorials/Write a Flake Plugin|Creating KOffice Flake Plugins]]
:''This tutorial shows you how you can build a plugin for KOffice applications to allow you embed content in ODF documents using Flake''

== Search and Metadata ==

; [[/Writing file analyzers|Writing file analyzers]]
:''File analyzers extract data from files to display in the file dialogs and file managers. The data gathered this way is also used to search for files. KDE4 allows the use of multiple analyzers per file type. This tutorial describes how you can write new analyzers.''

== Hardware Awareness ==

;[[/Solid_Tutorials|Introduction to Solid]]
:''An introduction to using the Solid hardware discovery and interaction system in KDE applications.''

;[[/Solid_Network_Tutorial|Accessing Network Information]]
:''How to use the Solid system to get information about the network''

==Phonon==

;[[/Phonon/Introduction|Phonon]]
:''How to start with the multimedia API''

==Printing==

;[[/Printing Hello World|Hello World]]
:''Introduction to the KDE printing system''

;TODO Print Dialog
:''Using the KDE print dialog''

== Get Hot New Stuff ==
; [[Development/Tutorials/Introduction to Get Hot New Stuff|Introduction to Get Hot New Stuff]]
:''An introduction to the developer-friendly network update system that allows KDE applications to fetch new application data at runtime in a user friendly manner.''

;[[Development/Tutorials/KNewStuffSecure|KNewStuff Secure]] ([http://developer.kde.org/documentation/tutorials/knewstuffsecure/index.html Original Link])
:''Tutorial showing how to share resources in a secured way (KDE 3.4 and later).'' By András Mantia <amantia@kde.org>.

== Rapid Application Development ==

=== Python ===

;[[Development/Tutorials/Python introduction to signals and slots|101 Introduction to signals and slots]]
:''A simple introduction to Qt's signal and slot architecture.''

=== Ruby ===

;[http://developer.kde.org/language-bindings/ruby/kde3tutorial/index.html KDE Ruby Korundum tutorial]
:''A ruby version of Antonio Larrosa Jiménez's KDE tutorial by Richard Dale. See the [http://developer.kde.org/language-bindings/ruby/index.html Ruby Developers Corner] for Qt tutorials and other info.''

;[[Development/Tutorials/Qt4_Ruby_Tutorial|Qt4 Ruby Tutorial]]
:''Trolltech's fabulous introductory tutorial to Qt, translated to Ruby.''

=== Shell ===

;[[Development/Tutorials/Shell_Scripting_with_KDE_Dialogs|Shell Scripting with KDE dialogs]] ([http://developer.kde.org/documentation/tutorials/kdialog/t1.html Original Link]) ([http://developer.kde.org/documentation/tutorials/kdialog-german/t1.html German Version])
:''Tutorial by [mailto:bradh@frogmouth.net Brad Hards] that describes how to use KDE dialogs in shell scripts with kdialog. It is presented as an example based tutorial.''

== Other tutorials ==

=== KPlotWidget ===
;[http://developer.kde.org/documentation/tutorials/kdeeduplot/kdeeduplot_tutorial.tar.bz2 Using and extending the KDE EDU Plot widget (docbook archive)]
:''This tutorial introduces Jason Harris' KPlotWidget that is part of the KDE-Edu package. Contains information about defining your own widget in Qt / KDevelop designer and about subclassing widgets and overriding member functions to extend functionality.''

=== Sonnet ===
;[[/Sonnet/SonnetTutorial|Adding spell-checking or grammar-checking to KDE applications]]
:''This tutorial introduces Sonnet and how one may use it to add language correction to your KDE application. Sonnet's auxiliary features shall be described in a separate tutorial.''

== KDE2 and KDE3 Materials ==

;[[Development/Tutorials/KDE3|KDE3 Tutorials]]
:''These tutorials cover topics related to KDE3.''

;[[Development/Tutorials/KDE2|KDE2 Tutorials]]
:''These tutorials cover topics related to KDE2.''

[[Category:KDE4]]

Projects/Summer of Code/2007/Ideas

2007-03-15T23:01:46Z

Zander: Reverted edits by 212.202.210.141 (Talk); changed back to last version by Zander

This page is an open list for ideas for the 2007 edition of [http://code.google.com/soc Google Summer of Code]. It will remain editable while the submission process is open.

This list is not exhaustive. It is just a collection of some ideas. To get further ideas, you can also look at our [http://wiki.kde.org/tiki-index.php?page=KDE%20Google%20SoC%202006%20ideas list of ideas for the year 2006]

Before proceeding, please read the [[Projects/Summer of Code/2007/Participation|participation instructions]]. They are useful for students and developers alike. Before editing this page, please take a look at the [[#Notes on editing this page|Notes on editing this page]] section at the end.

== Past ideas ==

You may want to take a look at the [http://wiki.kde.org/tiki-index.php?page=KDE%20Google%20SoC%202006%20ideas ideas page for 2006]. Some of the ideas there are still valid today.

== Project ideas ==

These ideas were contributed by our developers and users. They are sometimes vague or incomplete. If you wish to submit a proposal based on these ideas, you may wish to contact the developers and find out more about the particular suggestion you're looking at.

If there is no specific contact given you can ask questions on the general KDE development list kde-devel@kde.org. See [http://www.kde.org/mailinglists/ the KDE mailing lists page] for information on available mailing lists and how to subscribe.

When adding an idea to this section, please try to include the following data:
:* if the application is not widely known, a description of what it does and where its code lives
:* a brief explanation
:* the expected results
:* pre-requisites for working on your project
:* if applicable, links to more information or discussions
:* mailing list or IRC channel for your application/library/module
:* your name and email address for contact (if you're willing to be a mentor)

=== KDE Libs ===

==== KPassivePopup ====
''' Project Information:''' [http://api.kde.org/cvs-api/kdelibs-apidocs/kdeui/html/classKPassivePopup.html KPassivePopup] is the class that displays information next to taskbar icons, system tray icons or windows without interrupting the user. It is used both directly and by KNotify and is part of libkdeui.

'''Brief explanation:''' Convert KPassivePopup to use QSvg for the frame etc. this would allow it to be much more flexible in its visual appearance and could allow us to eliminate the various custom implementations that are floating around. This would include examining these forks and ensuring the same functionality could be cleanly incorporated.

'''Expected results:''' The intended result would be a single implementation of KPassivePopup that could be reused without copying code by applications such as Kopete that currently maintain their own versions.

'''Knowledge Pre-Requisite:''' A prequisite would be knowledge of Qt/KDE and the ability to setup a KDE build environment. Knowledge of SVG would obviously be a big help.

'''Mentor:''' Richard Moore <rich@kde.org>, Aaron Seigo <aseigo@kde.org>.

==== Solid ====

Solid is the KDE hardware abstraction layer, that enables KDE programs to get consistent results when running on different platforms.

* Plasma integration with Solid: Plasma uses the term 'data engine' to describe inputs to Plasma applets ('plasmoids'). Multiple applets may make use of a data engine. One task would be to write data engines for Solid interfaces for hardware status monitoring and control via Plasma.

* Media player support in Solid: Currently there is no high level support for portable media player devices in Solid. Applications such as Amarok have had to develop their own media player abstraction layers. Having this functionality in Solid would create exciting possibilities, for example, adding podcasts directly to your media device from a browser, or storing files received via IM directly on the media device.

* Scanner support in Solid: On Linux, scanner support uses the SANE library. To make scanners accessible from KDE applications on other platforms, a Solid wrapper to the most frequently used scanner functions and a SANE backend would make a good Summer of Code project for a student interested in imaging on Linux.

==== Phonon ====

==== KHTML ====

==== KJS - Scripting Modules ====

''' Project Information:''' KJS is KDE's JavaScript engine that was originally developed for the Konqueror Web browser. It as a light-weight, standalone library that can easily be embedded into other applications to make them scriptable.

Besides being restricted to running in the sandbox of an application usage for text and file processing or other administrative or server side tasks in a command line interpreter are thinkable. Consider what made e.g. Perl successfull. What's lacking are modules providing the necessary functions.

'''Brief explanation:''' The project would start out with gathering an overview of typical functions found in other scripting languages like Perl, Python and Tcl. The most important ones would then be selected and implemented in (at first) C++ modules that are dynamically loaded by the KJS command line interpreter.

'''Expected results:''' A set of low-level modules like File, CGI, JSON or similar with a documented set of constructors, functions and properties. They should form the base for pure JavaScript modules to be build on top.

'''Knowledge Pre-Requisite:''' Some C++ programming knowledge is required. Knowledge about other scripting languages like Python and Perl would be advantageous.

'''Mentor:''' Harri Porten <porten@kde.org>.

==== Sonnet ====

'''Project Information:''' Sonnet will be the future grammar, spell-checking and language detection framework in kde.

'''Brief explanation:''' Make kateparts compatible and integrated with Sonnet framework.

'''Expected results:'''
* Be allowed to use inline spell-checking in kile (latex front-end based on kateparts) or in the comments of a source file.
* Would be wonderful if the grammar and language detection also work with latex files.

'''Knowledge Pre-Requisite:''' I don't konw but probably C++, parsers, kate parts and language studies.

'''Mentor:'''

==== Kross ====

'''Project Information:''' [http://kross.dipe.org Kross] is a modular scripting framework that provides a complete framework to embed scripting interpreters like Python, Ruby and KDE JavaScript transparently into native applications to bridge the static and dynamic worlds together.

'''Brief explanation:''' While Kross does already provide access to Python, Ruby and KDE JavaScript, Java is missing. With a Java backend we could provide access to JDBC databases, Hibernate, Sandboxes and all the other goodies.

'''Expected results:'''
* Target is to implement a Java backend and offer Java as another supported scripting backend in Kross.
* Propably just bridge or at least provide access to QtJambi.
* Unittests and clean code :)

'''Knowledge Pre-Requisite:''' knowledge of C/C++, be able to get into the dark details of embedding Java.

'''Mentor:''' Sebastian Sauer <mail@dipe.org>

==== KDEPrint -- UI redesign ====

'''Project Information:''' [http://printing.kde.org KDEPrint] is the well known and very advanced printing platform common to all KDE applications.

'''Brief explanation:''' Redesign user interfaces related to printing. Improve usability.

''' Expected results:''' Produce an improved set of graphic interfaces to KDE's printing technology, based on usability reports already available and using new (original) usability ideas.

'''Prerequisites:''' C++, KDE/Qt programming, experience with design and creation of usable UI.

'''Mentor:''' Cristian Tibirna <tibirna@kde.org>

==== KDEPrint -- porting to CUPS > 1.2 ====

'''Project Information:''' [http://printing.kde.org KDEPrint] is the well known and very advanced printing platform common to all KDE applications.

'''Brief explanation:''' Port the current KDEPrint code to supporting CUPS later than 1.2, both in KDE-3.5 and KDE-4 branches.

''' Expected results:''' Based on the already very well thought out interface to CUPS-1.1, work is necessary for supporting new features and following bug fixes in the latest incarnation of CUPS, the most important backend of KDEPrint.

'''Prerequisites:''' C, C++, KDE/Qt programming, writing code following specifications.

'''Mentor:''' Cristian Tibirna <tibirna@kde.org>

==== KDEPrint -- porting to Qt-4.3/KDE-4 ====

'''Project Information:''' [http://printing.kde.org KDEPrint] is the well known and very advanced printing platform common to all KDE applications.

'''Brief explanation:''' Port the KDEPrint code of KDE-4 branch to latest Qt-4/KDE-4 libraries technologies.

''' Expected results:''' This task requires a thorough analysis of technologies used by KDEPrint in the previous (KDE-3.5) incarnation and replacement as needed with new or improved equivalents from Qt-4/KDE-4. Use of the new intercommunication technologies (D-Bus) and new notification technologies is required.

'''Prerequisites:''' C, C++, KDE/Qt programming, willingness to learn D-Bus as well as KDE-4 APIs.

'''Mentor:''' Cristian Tibirna <tibirna@kde.org>

==== KDEPrint -- add support for LinuxPrinting's on-line drivers query ====

'''Project Information:''' [http://printing.kde.org KDEPrint] is the well known and very advanced printing platform common to all KDE applications.

'''Brief explanation:''' Add support to KDEPrint for the new [http://www.linux-foundation.org/en/OpenPrinting/Database/Query OpenPrinting Database] which allows on-line search for new (locally unavailable) drivers for printers during printer installation.

''' Expected results:''' This task requires a good learning of the OpenPrinting Database Querying interface. Getting accustomed with KDEPrint's printer installation algorithms is also required. Target platform is KDE-4 but time permitting, a port to KDE-3.5 would be welcome.

'''Prerequisites:''' C, C++, KDE/Qt programming

'''Mentor:''' Cristian Tibirna <tibirna@kde.org>

==== KIConLoader: SVG Render Cache ====
''' Project Information:''' {{class|KIconLoader}} is the class the fetches icons from disk on demand and returns pixmap data for use on screen. This project would add an on-disk binary cache to be used for SVG icons.

'''Brief explanation:''' [http://aseigo.blogspot.com/2007/03/efficient-scallable-icons.html See my blog entry here for a description of the problem].

'''Expected results:''' A transparent cache that would increase the efficiency of SVG icon usage at runtime, with the possibility of adding runtime composition capabilities to {{class|KIconLoader}}.

'''Knowledge Pre-Requisite:''' A prequisite would be the ability to setup a KDE build environment. Qt/KDE programming knowledge is not a high requirement for this task, though the student will obviously be picking some of that up as they go. Experience with similar projects involving caching would be good.

'''Mentor:''' Aaron Seigo <aseigo@kde.org>.

('''Note:''' KIconLoader would benefit from a generic cache, not limited only to SVG but usable also for PNG icons. See the second paragraph of the benefits section in the blog entry for reasons [less disk seeking]. I think it would make sense to change this to a generic cache for KIconLoader. Lubos Lunak <l.lunak@kde.org> )

=== KDE Base applications ===

==== Konqueror - userscripts ====
''' Project Information:''' The goal of this project would be to implement and integrate into KDE4 a [http://www.konqueror.org/ Konqueror] equivalent of FireFox's [http://en.wikipedia.org/wiki/Greasemonkey Greasemonkey] plugin to allow installing and running user scripts. The project could start of from this [http://www.kde-apps.org/content/show.php?content=51482 existing GPL-ed code].

It seems that someone is already well on their way to completing this already: http://namshub-kde.blogspot.com/2007/01/more-work-on-konquerors-user-scripts.html

'''Expected results:''' A Greasemonkey equivalent for Konqueror that allows (de)installing and running Greasemonkey compatible user scripts.

'''Knowledge Pre-Requisite:''' C++ programming skills

==== Konqueror & Dolphin - file manager ====

* Ability to extract files from RPM packages

==== Plasma: icon placement ====
'''Brief explanation:''' Ordering the icons on the desktop has always been a pain for the users. They invent a certain arrangement (images top left, devices lower right, ...) and try to stick with it. Whenever they drop something to the Desktop folder in their filemanager, or when they plug in a new device the icon appears at an arbitrary location. Using clustering techniques and meta information about the existing icons, it would be possible to determine the most useful location for a new icon on the desktop.

'''Expected results:''' Improve the icon placing strategy of kdesktop (plasma) using clustering techniques.
* Try various clustering algorithms ([http://en.wikipedia.org/wiki/Data_clustering Wikipedia Data Clustering] might help) and choose the one most suitable for the task
* Implement an icon placement strategy in plasma, using the chosen clustering algorithm.

'''Knowledge Pre-Requisite:''' Familiarity with clustering algorithms or motivation to study them, C++/Qt coding skills

==== KWin -- Tiling Support ====
''' Project Information:''' [http://websvn.kde.org/trunk/KDE/kdebase/workspace/kwin/ KWin] is the KDE window manager, an application responsible for managing all windows.

''' Brief explananation:''' Some window managers (e.g. Ion or wmii) have the ability to divide the screen to smaller sections which make it simpler to work with several windows at the same time (window maximize only to its tile, etc.).

'''Expected results:''' Implemented tiling support in KWin.

'''Knowledge Pre-Requisite:'''
:# C++, Qt/KDE (KWin doesn't use much functionality from Qt and KDE libraries besides basic classes though)
:# X11/Xlib knowledge beneficial. X11 parts are mostly abstracted in KWin, but it's possible at least little knowledge might be required (it should be possible to learn necessary things while working on the project though).
:# Multiple-monitor (Xinerama) setup beneficial. KWin already has Xinerama support, parts of which possibly could be used as a base for tiling support. With tiling support implemented, Xinerama support should be implemented as tiles representing Xinerama screens.

'''References:'''
:# Wikipedia window manager [http://en.wikipedia.org/wiki/Window_manager entry]
:# KDE bug [http://bugs.kde.org/show_bug.cgi?id=59338 #59338]
:# KDE bug [http://bugs.kde.org/show_bug.cgi?id=107554 #107554]
:# [http://modeemi.cs.tut.fi/~tuomov/ion/ Ion]
:# [http://www.suckless.org/wiki/wmii wmii]

'''Mentor:''' Lubos Lunak <l.lunak@kde.org>.

==== KWin -- Improved Xinerama Support ====
''' Project Information:''' [http://websvn.kde.org/trunk/KDE/kdebase/workspace/kwin/ KWin] is the KDE window manager, an application responsible for managing all windows.

''' Brief explanation:''' Xinerama (and various implementations known also as e.g. MergedFB or TwinView) is an X server extension that merges two or more physical monitors into one large display. KDE already provides a decent support for Xinerama, but there is still room for improvement, in particular, different monitors are linked together even in cases when it might be more beneficial to have them independent, for example with virtual desktops.

'''Expected results:''' Improved Xinerama support in KDE/KWin. Specifically, making virtual desktops on different Xinerama displays independent, per [http://bugs.kde.org/show_bug.cgi?id=107302 KDE bugreport #107302], and related fixes/changes.

'''Knowledge Pre-Requisite:'''
:# C++, Qt/KDE (KWin doesn't use much functionality from Qt and KDE libraries besides basic classes though)
:# X11/Xlib knowledge beneficial. X11 parts are mostly abstracted in KWin, but at least little knowledge will be required (it should be possible to learn necessary things while working on the project though).
:# Multiple-monitor (Xinerama) setup. Although it is possible to use [http://ktown.kde.org/~seli/fakexinerama/ Fake Xinerama] for making a single monitor act like a Xinerama setup, real Xinerama setup is strongly recommended.

'''References:'''
:# Wikipedia window manager [http://en.wikipedia.org/wiki/Window_manager entry]
:# Wikipedia Xinerama [http://en.wikipedia.org/wiki/Xinerama entry]
:# KDE bug [http://bugs.kde.org/show_bug.cgi?id=107302 #107302]

'''Mentor:''' Lubos Lunak <l.lunak@kde.org>.

==== Strigi: chemistry and biology support ====

''' Project Information:''' [http://www.vandenoever.info/software/strigi/ Strigi] is a promosing alternative to other desktop
search tools, like Beagle/Kerry. It has a plugin architecture that allows writing indexing plugins for a specific area, or specific enhanced purposes. Available are both inline plugins (written in C++), as well as plugins that call programs written in other languages via the command line. Strigi is showing progress towards integration to semantic desktop ideas, as in the [http://nepomuk-kde.semanticdesktop.org/xwiki/bin/view/Main/ Nepomuk] project. This allows chemical information to be semantically marked up, and easily retrieved.

'''Brief explanation:''' The idea of this project is to integrate chemistry and biology knowledge into the KDE desktop, by writing chemistry and biology aware plugins for Strigi. Exact molecule searching on the hard disk will be supported via the [http://www.iupac.org/InChI InChI]. For the rest, normal free text searching will do fine for now. Generation of InChI's will be done via [http://openbabel.sf.net/ OpenBabel], for files supported by the [http://chemical-mime.sourceforge.net/ Chemical MIME]'s (which has existing KDE support) and [http://freshmeat.net/projects/kfile_chemical/?branch_id=60776&release_id=231404 kfile-chemical] (which is available for KDE3 and KDE4). Optionally, the student can incorporate the chemical text mining tool [http://wwmm.ch.cam.ac.uk/wikis/wwmm/index.php/Oscar3 OSCAR3] developed in Cambridge, UK, to extract InChI's from text documents, like PDF, HTML, etc. Here Strigi's jstream technology come in handy, as it will provide a plain text version for all those formats. Extraction of biochemical information is much easier, as these files commonly plain text already.

'''Expected results:''' Strigi plugins that:
:# extract meta data for (bio)chemical files defined by the Chemical MIMEs, via the kfile-chemical kfile plugins,
:# process files with a (subset of) (bio)chemical MIME with OpenBabel to generate an InChI for indexing,
:# (optionally) use OSCAR3 to process plain text and create InChIs for molecules found in that text. Additionally, the student is invited to propose a useful ontology for marking up the extracted chemical and biological information.

'''Knowledge Pre-Requisite:''' knowledge of C++ is a requirement, as is high school education in chemistry and biology.

'''Mentor(s):''' Carsten Niehaus <cniehaus@kde.org>,
Jerome Pansanel <j.pansanel@pansanel.net>, Egon Willighagen <egonw@user.sf.net>, Jos van den Oever" <jvdoever@gmail.com>

'''Mailing list:''' [http://sourceforge.net/mail/?group_id=171000 strigi-devel@lists.sourceforge.net]

=== KDE Edu ===

==== A 3D Molecular Editor ====
''' Project Information:''' There are several 3D molecular editors, but only few open source programs, such as [http://www.uku.fi/~thassine/projects/ghemical/ Ghemical]. The GPL-ed [http://openbabel.sf.net OpenBabel project] open chemistry library has expanded its usefulness improving chemistry software. This resulted in, among other things, an application and library called [http://avogadro.sourceforge.net/ Avogadro]. [http://edu.kde.org/kalzium/index.php Kalzium] and Avogadro will soon merge a lot of code so that both apps share an underlying rendering library for molecules (using OpenGL). Avogadro already has basic "molecule construction" capabilities. The goal of this project is to extend these such to yield a 3D editor suitable for basic molecular drawing and visualization for high school and university students.

'''Expected results:''' The improved application would be based on the new OpenGL based rendering code, and able to construct common organic molecules (such as [http://chem-file.sourceforge.net/data/carboxylic_acids/2R-2-1S-1_2-dihydroxyethyl-4_5-dihydroxy-furan-3-one_en.html this one]). The 3D-display code inside Kalzium will be reused and expanded to handle, for example, protein "ribbon" views, surfaces, and surface-mapped functions like electronic charge. Additional features such as configurable labels (for atoms, protein residues, etc.) and flexibility to change rendering for individual atoms or bonds would be welcome.

'''Knowledge Pre-Requisite:''' Basic Qt-knowledge and basic chemistry knowledge. OpenGL experience welcome.

'''Mentor:''' Carsten Niehaus (cniehaus at kde dot org)

'''Mailing list:''' kalzium at kde dot org

==== MARBLE - Adding a 2D View ====

''' Project Information:''' Marble is a Qt 4-based generic virtual globe widget which is meant to integrate well with the KDE desktop to provide basic input and visualisation facilities for geographical data. Marble currently lives in http://websvn.kde.org/trunk/playground/base/marble/ and the author would like to see Marble be included with KDE-Edu soon. More information: [http://www.kdedevelopers.org/node/2429 the Marble description].

'''Brief explanation:''' To be properly integrated with other applications a 2D View for Marble will be needed in addition to the preferred 3D View (e.g. for merging functionality of KGeography and Marble). Three steps are suggested:
:# reuse the current rendering engine in 2D mode
:# write an optimized approach for the 2D case and thereby refactor parts of Marble (especially the texture mapping)
:# include adding proper access methods for applications and the user interface

Depending on the knowledge of the applicant the refactoring part can be extended.

'''Expected results:''' adding the 2D View Mode to Marble. Optionally, if enough time is available, integrate that view mode in another application like KGeography.

'''Knowledge Pre-Requisite:''' basic knowledge of C++ is a pre-requirement. Basic highschool trigonometry knowledge would be helpful. Other useful skills, but not mandatory are:
* Qt experience

'''Mentor:''' Torsten Rahn <rahn@kde.org>.

'''Mailing list:''' The kde-edu mailing list: http://lists.kde.org/?l=kde-edu&r=1&b=200702&w=2 .

==== MARBLE - OpenStreetMap, GPS, Almanac, improved KML support ====

''' Project Information:''' Marble is a Qt 4-based generic virtual globe widget which is meant to integrate well with the KDE desktop to provide basic input and visualisation facilities for geographical data. Marble currently lives in http://websvn.kde.org/trunk/playground/base/marble/ and the author would like to see Marble be included with KDE-Edu soon. More information: [http://www.kdedevelopers.org/node/2429 the Marble description].

'''Brief explanation:''' There are a lot of other interesting projects that would make a nice Google Summer of Code 2007 project each on their own. Keep in mind that all those should be introduced in an unobtrusive manner as Marble is aimed at casual users without much technical knowledge. So a larger part should be dedicated on the usability (Of course it needs to work, too ;-):
:# Basic support for GPS devices: Introduce an interface to support GPS tracks and / or provide support for the GPX format. Co-Mentor: Inge Wallin.
:# Basic support for OpenStreetMap ( http://www.openstreetmap.org ). The applicant should find a way to incrementally download data collected by the Open Street Map project. This should happen in the background.
:# Marble Almanac: The applicant should extend the current placemark info dialog into a module of its own that compiles together various geographical information from different sources (like the CIA fact book).
:# Improve KML capabilities. Currently Marble has very basic KML support already. Although Marble won't be able to support the whole range of KML tags that e.g. Google Earth supports, it would be nice if support could be made more standards compliant. The student should be able to refactor the current code and introduce an improved design.

'''Knowledge Pre-Requisite:''' All these projects require that the student is a self-starter and will be able to do some research concerning the topics on their own. Beyond that you should have basic C++ knowledge. Prior Qt experience is a plus.

'''Mentor:''' Torsten Rahn <rahn@kde.org>, Co-Mentor for GPS support: Inge Wallin <inge@lysator.liu.se>

'''Mailing list:''' The kde-edu mailing list: http://lists.kde.org/?l=kde-edu&r=1&b=200702&w=2 .

==== Step interactive physical simulator ====

'''Project Information:''' Step is interactive physical simulator for education. It is very young program recently ported to KDE4. You can find more about it here:
http://edu.kde.org/step/ .

'''Note:''' This entry is added by author of the Step who want to apply to SoC as a student himself and seeking for mentor (as suggested on kdeedu mailing list).

'''Brief explanation:''' In order to be useful and to be included in kdeedu Step needs a lot more features than it currently has (it is only two month old). I propose adding the following features to Step (the list will be filtered to fit in SoC timeframe):
:# Simulation (StepCore library):
:## collision detection with friction (I hope this will be ready before summer)
:## movement restrictions (joints) (it can be ready too)
:## global error estimation
:## molecular dynamics (2d gas, 2d fluid)
:## Brownian motion
:## soft bodies and massive springs
:## API polishing
:# GUI (Step itself):
:## threading (do calculations in separate thread)
:## user-editable notes in experiment
:## units for all quantities, unit conversions
:## sidebar with nice descriptions for all bodies and its parameters (main properties, physical laws about it, real-world examples, ...)
:## custom graphics for various quantities (for example v(t) or v(x) - user can select what exactly to plot).
:## custom controllers to interactively control body parameters during simulation (for example user can add slider to control mass of the body and even assign hotkeys to it).
:## knewstuff for sharing experiments
:## tutorials (series of experiments with explanations)
:## GUI polishing

'''Mentor:'''

=== KDE PIM libraries and applications ===

==== KPilot - Enhance Record based syncing ====

''' Project Information:''' KPilot is the KDE application which synchronizes Palm OS PDAs with various KDE applications, including KMail, KAddressbook and Calendar. KPilot makes use of the pilot-link library to handle the interaction between the device and the conduits. These conduits are plugins which handle the actual synchronization of the items. For more information see [http://www.kpilot.org]

'''Brief explanation:''' The vast majority of KPilot's conduits are record-based in nature. This means that the logical program flow for each of the conduits is very much the same in that they will each:

:# Open a Palm database
:# Retrieve either all records or just the changed records
:# Open a PC data store
:# Retrieve either all or changed records
:# Handle tri-directional syncing, conflict handling, and merging changed data
:# Then write the resolved data sets back to the PC and Palm data stores

But the current conduit framework does not abstract this common functionality into a set of base classes as it should. This has resulted in a lot of duplicated code throughout KPilot's conduit base, and each conduit has its own way of handling this common functionality. Understandably, this has led to bugs in the syncing algorithms and has made maintainability of the conduits (and KPilot) a much more difficult thing than it should be. For every conduit, the maintainer has to learn how the actual syncing is done. To make matters worse, there are a couple of conduits which don't sync correctly because of a incomplete implementation of handling records.

'''Expected results:''' The student will create an improved framework for KPilot's record-based conduits and (re)implement a (new) conduit as a proof of concept.

:# Documentation about the syncing process of a record based conduit.
:## Sequence diagrams detailing sync logic for each of the major scenarios: HotSync, FullSync, Copy PC to Handheld, Copy Handheld to PC
:## Class diagram detailing:
:##* Inheritance hierarchy
:##* Class relationships
:# Implementation of the abstract record based conduit in the KPilot library.
:# (Re)implementation of a (new) Conduit as proof of concept.

'''Knowledge Pre-Requisite:''' basic knowledge of C++ is a pre-requirement. Other useful skills, but not mandatory are:
* Qt experience
* Pilot-link experience

'''Mentor:''' Adriaan de Groot <groot@kde.org>, Jason 'vanRijn' Kasper <vR@movingparts.net>.

'''Mailing list:''' The kde-pim mailing list: http://lists.kde.org/?l=kde-pim&r=1&w=2.

==== KitchenSync ====

KitchenSync is the frontend to the generic synchronization system [http://www.openysync.org OpenSync]. It is supposed to become the standard syncing solution for KDE. Right now it already supports synchronization of KDE PIM data with a wider variety of mobile devices like phones and PDAs as well was synchronization with other applications like Evolution or Google calendar.

KitchenSync works pretty well as OpenSync, but doesn't yet cover all functionality OpenSync provides. The goal of this project would be to improve that. For example the configuration GUIs for the various OpenSync plugins would need some work.

This project requires some knowledge in KDE programming. It will also involve collaboartion with the OpenSync team, so some experience with C is helpful.

'''Mentor:''' Cornelius Schumacher <schumacher@kde.org>

==== KOrganizer Theming ====

KOrganizer Theming: In the real world calendars are made from paper and carry lots of pretty pictures, witty sayings, historical data or similar things. Compared to that calendar programs are extremely plain. One of the intents of the CalendarDecoration plugin interface for KOrganizer was to make it possible to add theming to the calendar views, so that you can add all the fun things which make paper calendars more than just a bunch of papers with dates on it. Combined with the KNewStuff technology this could bring much more color to our desktops and make KOrganizer interesting to people which currently wouldn't think of using a calendar program.

'''Mentor:''' Cornelius Schumacher <schumacher@kde.org>

=== KDE Games ===

==== Kombinaton - AI Engine ====

''' Project Information:''' Kombination is a KDE4 scrabble clone. The project would be adding an artificial intelligence interface and at least one engine. Kombination currently lives in trunk/playground/games/kombination/ and the author would like to see Kombination be included with KDE Games soon. More information: [http://home.gna.org/kombination/ the Kombination web page].

'''Knowledge Pre-Requisite:''' basic knowledge of C++ is a pre-requirement. Basic knowledge of Scrabble rules is a must too. KDE and Qt skills will be useful but not mandatory.

'''Mentor:''' Albert Astals Cid <aacid@kde.org>.

'''Mailing list:''' The kombination mailing list: http://home.gna.org/kombination/ .

=== KDE SDK Applications ===

==== Kate ====
''' Project Information:''' Kate is a multi document editor, based on a rewritten version of the kwrite editing widget of KDE, offering all the features of that plus a bunch of its own.

'''Brief explanation:'''
Make Kate a much more capable yet still lightweight development tool for KDE4. Add features to Kate including CVS and SVN integration (either via recognition of the kdesvn or kcvs utilities, or with a custom implementation), Eclipse-like workspace and project management, and build environment integration for various languages/tools via an extensible interface. Scale Kate as much as needed to accomodate these changes, and not beyond that (at least for the scope of this project).

'''Expected results:''' The intended result would be a stable and extended implementation of Kate, providing CVS and SVN integration, Eclipse-like workspace and project management, and build environment integration.

'''Knowledge Pre-Requisite:''' A prequisite would be knowledge of Qt/KDE and the ability to setup a KDE build environment. Additionally, knowledge of interfacing with source code repositories via C++, and general C++ knowledge would be required.

'''Mentor:''' Christoph Cullmann <cullmann@kde.org>.

'''Mailing list:''' [https://mail.kde.org/mailman/listinfo/kwrite-devel The Kate mailing list]

=== KDevelop & Quanta ===

==== Extend KDevelop's snippet support ====

''' Project Information:''' Extend KDevelop's snippet support, see [http://bugs.kde.org/show_bug.cgi?id=106165 RFE 106165] for a detailed description (this proposal has been confirmed by popular vote).

'''Knowledge Pre-Requisite:''' basic knowledge of C++ is a pre-requirement. KDE and Qt skills will required. Likewise, familiarity with XML is probably required, too in order to provide a flexible, multi-platform file format for data storage and -exchange.

'''Suggested Approach:''' given that the envisioned functionality would probably be interesting to a rather large user base/audience, one should consider using a library-oriented approach, where key-functionality is provided in a fashion that facilitates standalone library-deployment, so that other OSS projects (i.e. other IDE projects) may eventually employ the corresponding library to add "snippet"-support, too.

'''Mentor:''' none yet

'''Mailing list:''' [mailto:kdevelop-devel@kdevelop.org KDevelop mailing list]

==== Implement foundations for KDevelop4 Ruby language support ====

''' Project Information:''' Ruby language and Rails web development tool is rapidly gaining popularity. The goal of this project is to implement the foundations for the best possible Ruby/Rails support in KDevelop.

'''Knowledge Pre-Requisite:''' advanced knowledge of C++ is a pre-requirement. KDE and Qt skills are desired but not required. At least basic knowledge of parsing theory (lexers, LL parsers, AST's) is necessary as well. This is a challenging project.

'''Brief Explanation:''' There're beginnings of Ruby support for KDevelop4 already. So the Ruby parser would be finished first and then definition-use chain for would be implemented. Those would allow to build extended code highlighting, navigation and problem reporting. The design for Ruby code completion would also be in the scope of this project.

'''Expected Results:'''
# Ruby parser with tests covering most of the language features
# DUChain builder for class/method definitions and their usages
# Advanced Ruby code highlighter and problem reporter
# Working and well-tested Ruby language support plugin
# Design for Ruby code completion

'''Mentor:''' [mailto:adymo@kdevelop.org Alexander Dymo]

'''Mailing list:''' [mailto:kdevelop-devel@kdevelop.org KDevelop mailing list]

=== Kopete ===

=== Amarok ===

''' Project Information:''' [http://amarok.kde.org/ Amarok website]

==== Tightening of Web Service Integration ====

'''Brief explanation:''' Amarok's motto is ''Rediscover your music''. Since listening to music can be a somewhat uninteresting experience, we try to enhance this aspect in a number of ways:

:* Wikipedia information retrieval
:* Lyric downloads
:* Cover Art
:* Music suggestions

etc, etc. I'm sure you are more than familiar with the 'omg-im-going-to-wet-myself-this-is-so-cool' experience that you have at least once experienced.

We would like to see some sort of enhancement to meta-information which can be displayed to the user. Some ideas that come to mind may include:
:* Upcoming concerts
:* Random artist trivia

'''Expected results:''' The student will come up with a set of web-service enhancements and will implement them so that they integrate tightly with the final Amarok 2.0 interface and design goals.

'''Knowledge Pre-Requisite:''' basic knowledge of C++ is a pre-requirement. Other useful skills, but not mandatory are:
:* Qt experience
:* Web service skills, such as SOAP, XML/DOM structures etc
:* A keen eye for usability and the difference between features and benefits

'''Mentor:''' Seb Ruiz <me@sebruiz.net>

'''Mailing list:''' [https://mail.kde.org/mailman/listinfo/amarok The Amarok mailing list]

==== Integrate Additional Music Store or Streaming Music Service ====

'''Brief explanation:''' Since the introduction of the integrated Magnatune.com music store in Amarok, there has been many proposals for other stores or services that could be integrated in a simmilar way. In the process of working towards Amarok 2.0, a new framework for adding such services without cluttering the interface has been proposed and the Magnatune store has been ported to this framework. Adding a new store or service is a nice way of getting into coding on Amarok at is fairly easy to approach witout knowing all the intricate details of Amaroks inner workings.

There are several types of services that could be of interest:

:* DRM free music stores ( preferably with good, full length, previews )
:* Streaming audio content services ( Again, no DRM is a must )
:* Live recording archives
:* Most likely a 100 other kinds of sites that I have not thought of...

The service chosen will have to be legal, and the service must agree to the integration taking place.

There are currently no concrete agreements in place with other services, so this is very much a "bring your own idea" project, which both makes it a bit harder to get started, but also more rewarding.

'''Expected results:''' The student reaches an agreement with a music store/service/whatnot and integrates its service into Amarok. Some effort would most likely also be spent on helping to mature the service framework.

'''Knowledge Pre-Requisite:''' basic knowledge of C++ is a pre-requirement. Other useful skills, but not mandatory are:
:* Qt experience
:* Web service skills, such as SOAP, XML/DOM structures etc
:* A keen eye for usability and the difference between features and benefits

'''Mentor:''' Nikolaj Hald Nielsen <nhnFreespirit@gmail.com>

'''Mailing list:''' [https://mail.kde.org/mailman/listinfo/amarok The Amarok mailing list]

=== okular ===

''' Project Information:''' okular is a KDE 4 document viewer. http://www.okular.org

'''Mailing list:''' [https://mail.kde.org/mailman/listinfo/okular-devel The okular mailing list]

==== Improve the rendering of PDF patterns ====

'''Explanation:''' okular uses the [http://poppler.freedesktop.org Poppler library] to render the PDF files. Some files with complex patterns may take even minutes to render, while with Acrobat Reader just a couple of seconds.

'''Expected results:''' One needs to improve the Poppler library code that handles rendering of PDF files with patterns, making the pattern rendering faster with no drawbacks.

'''Knowledge Pre-Requisite:''' basic knowledge of C++ is a requirement. Qt4 is strongly suggested too. Graphics and PDF konwledge are strongly suggested as well, but not mandatory.

'''Mentor:''' Albert Astals Cid <aacid@kde.org>

==== Improve the presentation mode ====

'''Explanation and Expected results:''' okular has a presentation mode for displaying documents on the screen in a way similar to a presentation application (think about KPresenter, OpenOffice.org Impress). Currently, the mode can just display only a single page, at the maximum size allowed by the screen. The idea is to extend the presentation mode by adding:
* zooming support and pan mode
* facing mode
* missing PDF transitions, like Fly, Push, Cover, Uncover, Fade

'''Knowledge Pre-Requisite:''' knowledge of C++ and Qt4 is a requirement. KDE 4, graphics and PDF konwledge are strongly suggested as well, but not mandatory.

'''Mentor:''' Albert Astals Cid <aacid@kde.org>

==== Improve the annotation support ====

'''Explanation and Expected results:''' one of the okular's goals is to support the annotations, mainly coming from PDF documents (but also from DjVu and ODT documents). As the support is not yet complete, some ideas could be:
* adding the visual editing features (e.g. mouse click to visually select, drag to move around or resize, etc)
* adding support for more kind of annotations (e.g. Caret, Watermark, etc)
* improve the annotation toolbar
* better support for text and line annotation drawing

'''Knowledge Pre-Requisite:''' basic knowledge of C++ is a requirement. Qt4 is strongly suggested too. Graphics and PDF konwledge are strongly suggested as well, but not mandatory.

'''Mentor:''' Albert Astals Cid <aacid@kde.org>

==== 3D artwork support ====

'''Explanation and Expected results:''' the PDF formats allow the embedding of 3D artwork in documents. The idea is to start supporting this kind of artwork, and start displaying them on the document. What is required to do is:
* basic reading support
* basic displaying of the artwork on the document (thus creating a 3D view)
* basic interaction with the 3D artwork (mouse or document actions)

'''Knowledge Pre-Requisite:''' knowledge of C++ is a requirement. Qt4 is strongly suggested too. Graphics and PDF konwledge are strongly suggested as well, but not mandatory.

'''Mentor:''' Albert Astals Cid <aacid@kde.org>

=== Other Applications ===

==== KBugBuster ====

KBugBuster is a native KDE client for the bug tracking system Bugzilla. It allows to browse, search and view bug reports and make modifications to them. It provides features which the web interface can't provide like an offline mode.

One potential task would be to make KBugBuster work with the XML-RPC interface of Bugzilla. This would make access to Bugzilla more robust and make it possible to better support the editing of bug reports.

'''Mentor:''' Cornelius Schumacher <schumacher@kde.org>

==== Knoware ====

Knoware is previous SOC project. It creates a system that collates bug reports as well as anonymous system specs offered by users. It provides a statistical way of matching up bugs to likely culprits in a system or configuration so that developers can get a better handle on what the problem likely as as well as informing users of KDE what the potential pitfalls of their current system could be.

One potential task would be to document the current system for further development. Another could be porting the curent code to Qt4.

'''Mentor:'''
==== Application User Interface Test System ====

There are a couple of tools available for Qt / KDE that allow testing of applications - squish and kdexecutor. Both are binary only, and are specific to the systems that they are built on.

It would be useful to have an open source tool that allowed us to test applications in a scripted way. Similar open source tools include Dogtail and LDTP, which use the accessibility interfaces in Gnome.

There are arguments for and against using accessibility - it might be a lot more useful to implement a separate system, using some of the Qt4 specific features including QMetaObject. Qt4 has a nice set of hooks, and QTestLib shows how they can be implemented. However instead of requiring specific code in the application (as done by QTestLib), it would be more flexible to use LD_PRELOAD and a small interface library.

'''More discussion:''' Brad Hards <bradh@kde.org>

=== Oxygen ===

=== Decibel ===

You can find a list of Decibel related ideas in the [https://services.brucherseifer.net/dbwiki/index.php/Project_Ideas Decibel Wiki]

=== Usability ===
==== A new design for contextual help (Whatsthis) ====

Implement Ellen Reitmair's, Olaf Schmidt's, Philip Rodrigues' plan for a new infrastructure for contextual help.
[http://www.userbrain.de/whatsthis/ideas_whatsthis_january06_v1.3.pdf ideas_whatsthis_january06_v1.3.pdf]

=== Infrastructure ===

* A way to make bugzilla help in finding duplicated bugs. could be some kind of 'suggested related bugs'

=== KOffice ===
All KOffice projects have common contact information and background info;
You can read documents on [http://www.koffice.org www.koffice.org] and [http://wiki.koffice.org wiki.koffice.org], various proposals will reference pages on the wiki as thats the main design 'scratch pad' for the developers of KOffice.
Contact information; '''IRC''': irc.kde.org channel #koffice '''Mail''': sent mail to the koffice mailinglist. Info [http://www.koffice.org/contact/ here]

==== Collaborative editing in KOffice apps ====
See [http://wiki.koffice.org/index.php?title=Collaboration Collaboration]. We don't expect a fully working implementation, as it is most probably too big a project. So please guestimate what you want to work on and finish.

'''Mentor:''' KOffice or KDE developers

==== Rulers and Grid in KOffice apps ====
All applications in KOffice need a grid. A grid is a raster that will be drawn on top of all content on the canvas. This will tightly be integrated with rulers and guides. [http://wiki.koffice.org/index.php?title=Rulers_And_Grid Grids Framework].

'''Mentor:''' KOffice or KDE developers

==== Improve OpenDocument compatibility in KOffice apps ====
Specifically mentioned here are KSpread, KPresenter, KChart or KFormula

'''Mentor:''' KOffice or KDE developers

==== A 3D diagram flake-shape using lib-Eigen ====
Lib [http://websvn.kde.org/trunk/kdesupport/eigen Eigen] has code to do all the hard lifting for 3D calculations. But little visualisation code. Build on top of that and be able to show data in a 3D manner into a [http://wiki.koffice.org/index.php?title=Flake Flake] shape.

'''Mentor:''' KOffice or KDE developers

==== KWord master document ====
This maybe in combination with book-files, which combine a set of individual documents to one book with continues numbering/etc. See [http://wiki.koffice.org/index.php?title=KWord/Master_Documents Usecase]

'''Mentor:''' KOffice or KDE developers

==== Text-tool plugins for KOffice apps ====
KOffice has a generic text-tool. Which will allow KWord to show all the complexity of text needed for word processing and DTP while other KOffice apps can reuse the component as well. The text tool (based on [http://wiki.koffice.org/index.php?title=Flake Flake]) has a plugin structure allowing external development to create extra functionality. A tutorial on how to build one will be written by the KOffice developers soon.
# bookmarks plugin.
# Uppercase Text. Alter the text to be all lowercase, Title Cased, or Capitalised.
# Replace word. Use a Thesaurus to replace the text with a new one. As a non-standard example what about replace-word with a texting-Language. There are many engines on the web that can replace normal text with some sort of funny version.
# Colorization plugin. For those that publish pieces with sourcecode, being able to colorize text is a really useful tool.
# An optional plugin that shows a word count in a docker updated continuesly.

'''Mentor:''' KOffice or KDE developers

==== A Flake-plugin that works on vector shapes ====
It should be a tool, like the gradient tool or the color-picking tool. (see [http://wiki.koffice.org/index.php?title=Flake Flake])
The tool would give you a set of brushes and each brush is defined as an outline only. So you'd have a 10pt wide circle as one brush, and a heart shaped brush as another. The tool will allow the user to 'stamp' or paint using these brushes and can use the Qt4.3 binary path operations to modify the vector shape.
# Use case: I get a vector image of snow man and I want to paint a nose and two eyes on it like it were a pixel-based image.
# Use case: I want to draw my signature as a vector shape.

'''Mentor:''' KOffice or KDE developers

==== Extend the ShapeSelector which is used by KOffice apps ====
Extend the [http://wiki.koffice.org/index.php?title=ShapeSelector ShapeSelector] to do several more things;
* make it listen to the clipboard and show a visual representation of the current state.
* make it possible to drag something (a shape or just some text) off of the canvas onto the shapeSelector where it then gets stored. Also between sessions.
* make it possible to save a selection of items in the shapeSelector and save them on disk as one 'bundle' so I can send that to someone else.
* make it possible to load such a bundle from disk.
* make it possible to connect to a remove storage (a webpage or a samba share etc) using kio on startup and download changed bundles to show in the shape-selector.

'''Mentor:''' KOffice or KDE developers

==== Add accessibility support to Flake ====
Using the Qt framework for accessibility, make it possible for the text tool and perhaps other tools to be accessible. Which means that a blind user can use KWord.

'''Mentor:''' KOffice or KDE developers

==== Add support for better tables in KWord ====
In KOffice2.0 tables as we know it in 1.x has been removed. The tables for KOffice2 have to be based on the text engine (qt-scribe) which already knows about html-style-tables. The SoC proposal is to extend this and add tables support to KWord again using the ODF specification for the feature list that is required of tables.

'''Mentor:''' KOffice or KDE developers

==== KWord Scripting ====

'''Brief explanation:''' KWord comes with a [http://wiki.koffice.org/index.php?title=KWord/Scripting Scripting Plugin] based on [http://kross.dipe.org Kross]. The plugin provides a clean interface to offer access to the KWord functionality from within scripting backends.

'''Expected results:''' Improve the current scripting plugin.
* Evaluate what is needed or what a script could need and implement it to earn a powerful scripting backend for KWord 2.0.
* The current design may need to be refactored cause the scripting API should be as simple as possible.
* Provide sample scripts to demonstrate what's possible and Unittests for regression testing.

'''Knowledge Pre-Requisite:''' knowledge of C++/Qt, experience with word-processing

'''Mentor:''' Sebastian Sauer <mail@dipe.org>

==== Improve Kexi Data Import/Export ====

'''Brief explanation:''' Currently Kexi allows importing CSV files into an existing database, and converting MySQL/PostgreSQL/MS Access databases into Kexi databases.

The aim of this project is to provide plugin(s) that import from more database backends/formats.

You can select a backend you like to implement migration for:

* HSQLDB - the OpenOffice.org DB backend (quite important to have)
* ODBC
* Paradox
* DBase (e.g. using http://www.anubisnet.de/products/dbf )
* MS SQL Server (e.g. using http://www.freetds.org/ )
* Firebird - pending licence checks

For the ODBC driver, a migration plugin and a backend plugin should be provided. For Paradox, only a migration plugin is required, although this will require modifying the migration framework to allow more than one file to be selected as the source database (i.e. the database to be imported).

Both a migration plugin and a backend plugin could be provided for HSQLDB, which should be implemented using JNI to invoke JDBC methods in the HSQLDB library.

In any case, migration plugins are simpler to implement than direct access plugins (drivers), so these can be developed first.

'''Knowledge Pre-Requisite:''' knowledge of C++, (knowledge of Qt and experience with a given database format/backend is recommended)

'''More info:'''
*[http://kexi-project.org/wiki/wikiview/index.php?GoogleSummerOfCode2006_DBaseMigrationPlugin "DBase Migration Plugin for Kexi" proposed by Jonathon Manning last year]
*[http://kexi-project.org/wiki/wikiview/index.php?GoogleSummerOfCode2006_ParadoxAndHSQLAccess "Paradox & HSQL access for Kexi" proposed by Joseph Wenninger last year]

'''Mentor:''' Jaroslaw Staniek <js@iidea.pl>, Sebastian Sauer <mail@dipe.org>

'''Mailing list:''' [https://mail.kde.org/mailman/listinfo/kexi-devel kexi-devel]

==== Kexi Web Forms ====

'''Brief explanation:''' Web Forms allow to read-only or read-write access to database projects created with Kexi. It is optional feature for uses where client has no Kexi installed for any reason. The fact that the Web Forms will use Web standards, adds another advantage over competitors like MS Access (which uses proprietary Windows-only ActiveX bindings).

Proposed solution is to develop a small standalone web server. It is probably already written in C++ or C by FOSS community. Good examples are lighttpd - http://www.lighttpd.net/
and (being already in KDEnetwork module) KPF - http://rikkus.info/kpf.html.

The web serwer would be dynamically linked to kexidb and thus can access Kexi databases via universal KexiDB API, and create HTML content on demand as an answer to HTTP requests.

For alternative solution see "Alternative solution for Kexi forms using PHP" below.

'''Knowledge Pre-Requisite:''' knowledge of C++ and HTTP/web standards, (knowledge of Qt and experience with a given database format/backend is recommended)

'''More info:''' [http://jacek.migdal.pl/gsoc/ Solution proposed by Jacek Migdal last year]

'''Mentor:''' Jaroslaw Staniek <js@iidea.pl>

'''Mailing list:''' [https://mail.kde.org/mailman/listinfo/kexi-devel kexi-devel]

==== Alternative Solution for Kexi Forms Using PHP ====

'''Brief explanation:''' Create a Kexi plugin generating PHP code saving it directy to the filesystem. This will require Apache (or other PHP-compatible web server) to be present and configured, and also will require the plugin to be packaged with a script that will install appropriate tools that allow r/w accessing the Apache/php subdirs.

'''Knowledge Pre-Requisite:''' knowledge of PHP, web standards and C++, (knowledge of Qt is recommended)

'''Mentor:''' Jaroslaw Staniek <js@iidea.pl>

'''Mailing list:''' [https://mail.kde.org/mailman/listinfo/kexi-devel kexi-devel]

== Notes on editing this page ==

Before making any modifications, please '''log in''' to Techbase. This will help us track who is contributing to the ideas.

When making modifications to existing ideas, please consider whether you're changing it more fundamentally or just superficially. If your changes are substantial, you probably have an entirely new idea. Similarly, if your idea is modified and you feel it no longer reflects your original thought, please split the idea in two, restoring yours.

Please use the [[Talk:Projects/Summer of Code/2007/Ideas|talk page]] if you want to discuss an idea.

Finally, do '''not''' delete ideas without a reason for doing so (like, for instance, being contrary to KDE ideals, being completely unrelated to KDE, being unfeasible, etc.) -- you may want to state in the [[Talk:Projects/Summer of Code/2007/Ideas|talk page]] why you removed the idea.

Do '''not''' re-add ideas that were removed without discussing first with the developers of the target application.

Projects/Summer of Code/2007/Ideas

2007-03-15T21:43:39Z

Zander: /* KWord master document */