KDE TechBase - User contributions [en]

Thread:User talk:Icwiener/thanks/reply

2012-06-10T15:55:45Z

Icwiener: Reply to thanks

No problem. :)

Projects/Games

2012-05-01T16:03:53Z

Icwiener: Add porting page

{{Template:I18n/Language Navigation Bar|Projects/Games}}

=== Development ===
[[/Porting_to_libkdegames_v5|Porting to libkdegames v5]]

[[Category:KDEGames]]

Projects

2012-05-01T16:01:20Z

Icwiener: Reverted edits by Icwiener (talk) to last revision by Santa

{{Template:I18n/Language Navigation Bar|Projects}}
{{note|KDE TechBase Translators: The Projects part is rather a scratchpad for arbitrary projects. It contains texts like IRC logs and rough ideas. ''It probably does not make sense to translate this''. If, however, you wish some part to be translated please either email kde-www@kde.org or comment on #kde-www.}}

{{note|These pages are intended for providing technical documentation for external users of various KDE Projects. For internal project documentation, such as feature plans and meeting minutes please use http://community.kde.org/.}}

= Infrastructure =

{| style="margin: 1em 2.5% 0 2.5%; padding: 0 5px;" cellpadding="5"
|-
|[[Image:Klogo-official-crystal.svg|noframe|left|40px]] ||
;[[/MovetoGit|KDE migration to git]]
:KDE is moving from svn to git, find progress, todo list, etc. here.
|-
|}

= Organisational =

{| style="margin: 1em 2.5% 0 2.5%; padding: 0 5px;" cellpadding="5"
|-
|[[Image:Klogo-official-crystal.svg|noframe|left|40px]] ||
;[http://www.kde.org/community/getinvolved Get Involved with KDE]
:General information for getting involved with KDE projects. Includes a mentor directory for many projects.
|-
|[[Image:Klogo-official-crystal.svg|noframe|left|40px]] ||
;[[/Release_Team|KDE Release Team]]
:The KDE Release Team.
|-
|[[Image:Klogo-official-crystal.svg|noframe|left|40px]] ||
;[[/Documentation|KDE Documentation Project]]
:Creating and maintaining KDE documentation.
|-
|[[Image:Klogo-official-crystal.svg|noframe|left|40px]] ||
;[[/kde.org|kde.org]]
:Information around the *.kde.org websites.
|-
|[[Image:Klogo-official-crystal.svg|noframe|left|40px]] ||
;[[/Promo|KDE Promotion]]
:Promoting KDE and conference organization.
|-
|[[Image:Action_world.svg|noframe|left|40px]] ||
;[[/Partners|Partner Program]]
:KDE partner program targetting ISVs.
|-
| ||
;[[/Usability | KDE Usability project]]
: The KDE Usability Project is an initiative to apply usability principles and practices to the K Desktop Environment.
|-
| [[Image:Bugweeks ladybug.png|noframe|left|40px]]||
;[[Contribute/Bugsquad|KDE BugSquad]]
:The KDE BugSquad keeps track of incoming bugs in KDE software, and goes through old bugs.
|-
| ||
;[[/Summer_of_Code|Summer of Code Projects]]
:Information on Summer of Code projects and prospects related to KDE
|-
| ||
;[[/English Breakfast Network|KDE Code Quality (EBN)]]
: The English Breakfast Network and associated tools dedicated to KDE Quality, including: KDE API Documentation Validation, User Documentation Validation, Source Code Checking, ...
|-
| ||
;[[/KDE Research|KDE Research]]
: Project and community for everyone who is interested in contributing to (funded) research projects with(in) the KDE community.
|-
|}

= Frameworks =

{| style="margin: 1em 2.5% 0 2.5%; padding: 0 5px;" cellpadding="5"
|-
|[[Image:logo_oxygen.png|noframe|left|40px]] ||
;[[/Oxygen|The Oxygen Project]]
:Artwork for KDE4.
|-
|[[Image:Klogo-official-crystal.svg|noframe|left|40px]] ||
;[[/kdelibs|KDE Core Libraries]]
:For the core developers working on the kdelibs module.
|-
|[[Image:Decibel.png|noframe|left|40px]] ||
;[[/Decibel|Decibel]]
:Decibel - Realtime communications framework
|-
| ||
;[[/KGLEngine2D | KGLEngine2D]]
: KGLEngine2D is a framework designed to greatly simplify the development of reach multimedia applications on KDE enabled platforms.
|-
| ||
;[[/KioFuse|KioFuse]]
: Insert KIO resources (remote, archived or compressed files) into the root filesystem hierarchy.
|-
|[[Image:Nepomuk_logo.png|noframe|left|40px]] ||
;[[/Nepomuk|Nepomuk]]
:Nepomuk Semantic Desktop project - Annotation/Indexing/Search/Linking
|-
|[[Image:Action_filequickprint.svg|noframe|left|40px]] ||
;[[/KDEPrint|KDEPrint]]
:Printing related information for KDE.
|-
|[[Image:knetworkmanager.png|noframe|left|40px]] ||
;[[/Network_Management|Network Management]]
: Development on Solid Networking, KNetworkManager applet and configuration tool.
|-
| ||
;[[/D-Bus-WS|D-Bus Web Service Proxy]]
: Fusion of D-Bus services and web services.
|-
| ||
;[[/Silk | Silk]]
: Project Silk - Deep integration of the web
|-
| ||
;[[/Solid | Solid]]
: Solid - The KDE Hardware Library
|-
| ||
;[[/Kbluetooth | Kbluetooth]]
: Kbluetooth - The KDE Bluetooth Library (deprecated)
|-
| ||
;[[/kdesu|kdesu]]
: Considerations and coordination to make kdesu work well with several backends.
|-
| ||
;[[/Telepathy|Telepathy]]
:Telepathy Realtime Communication Framework - Instant Messaging, VoIP and Collaboration.
|-
| ||
;[[/WebKit|WebKit (webkitkde)]]
: Project which aims to integrate WebKit (QtWebKit) into KDE.
|-
| ||
;[[/Widgets and Classes|Widgets & Classes]]
:Widgets and classes that are not in kdelibs but which you may find useful.
|-
| ||
;[[/KSecretsService|KSecretsService - managing KDE application's secrets]]
:Secrets management infrastructure for KDE applications and a collection of related tools, superseding KWallet.
|-
| ||
;[[/Related|Related Projects]]
: Projects which are related to KDE in any way, as dependencies or build tools.
|-
|}

= Programs =

{| style="margin: 1em 2.5% 0 2.5%; padding: 0 5px;" cellpadding="5"
|-
| [[Image:Aki128.png|noframe|left|40px]]||
;[[/Aki | Aki]]
: Aki - Extensive IRC Client
|-
|||
;[[/Digikam|Digikam]]
:Digikam - Photo Management Software.
|-
| [[Image:Hisc-apps-kget.svg|noframe|left|40px]]||
;[[/KGet|KGet]]
: KGet, a KDE Downloader
|-
| ||
;[[/Gwenview|Gwenview]]
:Gwenview, the image viewer.
|-
|[[Image:K3b.png|noframe|left|40px]] ||
;[[/K3b|K3b]]
:K3B, optical disc writer
|-
| ||
;[[/KDevelop4|KDevelop4]]
:KDevelop4, the KDE IDE.
|-
|[[Image:Knights.png|noframe|left|40px]] ||
;[[/Knights|Knights]]
:A chess program for the KDE Platform.
|-
|[[Image:Kopete.svg|noframe|left|40px]] ||
;[[/Kopete|Kopete]]
:Kopete, the KDE Instant Messaging program.
|-
|[[Image:Marble.png|noframe|left|40px]] ||
;[[/Marble|Marble]]
:Marble Desktop Globe - Can You Feel The Earth Spinning?
|-
| ||
;[[/Okular|Okular]]
:Okular, the unified document viewer.
|-
| ||
;[[/rekonq | rekonq]]
: rekonq - A lightweight Web Browser for KDE based on WebKit
|-
|[[Image:Ktimetracker.png|noframe|left|40px]] ||
;[[KTimeTracker]]
:Time management within the KDE PIM.
|-
| ||
;[[/SystemSettings|System Settings]]
: Development on the System Settings configuration tool.
|-
|[[Image:superkaramba.png|noframe|left|40px]] ||
;[[/SuperKaramba|SuperKaramba]]
:SuperKaramba is a tool that allows you to easily create interactive eye-candy on your KDE desktop.
|-
| ||
;[[/KWin|KWin]]
: The KDE Window Manager.
|-
|}

= Suites =

{| style="margin: 1em 2.5% 0 2.5%; padding: 0 5px;" cellpadding="5"
|-
|[[Image:Action_book2.svg|noframe|left|40px]] ||
;[[/Edu|KDE Education Project]]
:Developing educational software for KDE.
|-
| ||
;[[/extragearReleases|Extragear Releases]]
: A current list of what extragear apps are to be released in sync with the core KDE release schedule.
|-
| ||
;[[/KdeFinance | KDE Finance]]
: KDE Finance is a group of KDE-related financial applications
|-
|[[Image:Kdegameslogo_40.png|noframe|left|40px]] ||
;[[/Games|KDE Games Project]]
:Developing desktop's games for KDE.
|-
|[[Image:Action_pencil.svg|noframe|left|40px]] ||
;[[/KOffice|KOffice]] and [http://wiki.koffice.org KOffice.org]
:Developing an Office suite based on KDE.
|-
|[[Image:Action_pencil.svg|noframe|left|40px]] ||
;[[/Calligra/]] and [http://calligra.org Calligra.org]
:Developing an Office suite for KDE.
|-
|[[Image:Action_mail_generic.svg|noframe|left|40px]] ||
;[[/PIM|KDE PIM Project]]
:KDE Personal Information Management.
|-
|[[Image:Plasma_logo.jpg|noframe|left|40px]] ||
;[[/Plasma|Plasma]]
:Quick and easy creation of widgets. Interactive application launchers, window and task managers, weather checkers; they are all made with plasma.
|-
| ||
;[[/Kdetoys | Kdetoys]]
: The Kdetoys project
|-
|[[Image:kdeutils-logo.svg|noframe|left|40px]] ||
;[[/Utils|KDE Utilities Team]]
:For the developers working on the kdeutils module.
|-
| ||
;[[/Necessitas | Necessitas]]
: Necessitas project
|-
|}

= Platforms =

{| style="margin: 1em 2.5% 0 2.5%; padding: 0 5px;" cellpadding="5"
|-
|[[Image:KDE-Mac.png|noframe|left|40px]] ||
;[[/KDE on Mac OS X|KDE on Mac OS X]]
: KDE libraries and applications on Mac OS X.
|-
|[[Image:Konqi-win.png|38px]] ||
;[[/KDE on Windows|KDE on Windows]]
: KDE libraries and applications on MS Windows.
|-
| ||
;[[/KDE on Solaris|KDE on Solaris]]
: KDE libraries and applications on Sun Microsystems Solaris and OpenSolaris.
|-
| ||
;[[/KDE on FreeBSD|KDE on FreeBSD]]
: KDE libraries and applications on FreeBSD and other BSDs.
|-
| ||
;[[Projects/Mobile|Mobile]]
: Project for porting KDE to the Mobile.
|-
|}

__NOTOC__

Projects

2012-04-27T18:14:00Z

Icwiener: /* Suites */ The KDEGames project page has been moved to http://community.kde.org/KDE_Games

{{Template:I18n/Language Navigation Bar|Projects}}
{{note|KDE TechBase Translators: The Projects part is rather a scratchpad for arbitrary projects. It contains texts like IRC logs and rough ideas. ''It probably does not make sense to translate this''. If, however, you wish some part to be translated please either email kde-www@kde.org or comment on #kde-www.}}

{{note|These pages are intended for providing technical documentation for external users of various KDE Projects. For internal project documentation, such as feature plans and meeting minutes please use http://community.kde.org/.}}

= Infrastructure =

{| style="margin: 1em 2.5% 0 2.5%; padding: 0 5px;" cellpadding="5"
|-
|[[Image:Klogo-official-crystal.svg|noframe|left|40px]] ||
;[[/MovetoGit|KDE migration to git]]
:KDE is moving from svn to git, find progress, todo list, etc. here.
|-
|}

= Organisational =

{| style="margin: 1em 2.5% 0 2.5%; padding: 0 5px;" cellpadding="5"
|-
|[[Image:Klogo-official-crystal.svg|noframe|left|40px]] ||
;[http://www.kde.org/community/getinvolved Get Involved with KDE]
:General information for getting involved with KDE projects. Includes a mentor directory for many projects.
|-
|[[Image:Klogo-official-crystal.svg|noframe|left|40px]] ||
;[[/Release_Team|KDE Release Team]]
:The KDE Release Team.
|-
|[[Image:Klogo-official-crystal.svg|noframe|left|40px]] ||
;[[/Documentation|KDE Documentation Project]]
:Creating and maintaining KDE documentation.
|-
|[[Image:Klogo-official-crystal.svg|noframe|left|40px]] ||
;[[/kde.org|kde.org]]
:Information around the *.kde.org websites.
|-
|[[Image:Klogo-official-crystal.svg|noframe|left|40px]] ||
;[[/Promo|KDE Promotion]]
:Promoting KDE and conference organization.
|-
|[[Image:Action_world.svg|noframe|left|40px]] ||
;[[/Partners|Partner Program]]
:KDE partner program targetting ISVs.
|-
| ||
;[[/Usability | KDE Usability project]]
: The KDE Usability Project is an initiative to apply usability principles and practices to the K Desktop Environment.
|-
| [[Image:Bugweeks ladybug.png|noframe|left|40px]]||
;[[Contribute/Bugsquad|KDE BugSquad]]
:The KDE BugSquad keeps track of incoming bugs in KDE software, and goes through old bugs.
|-
| ||
;[[/Summer_of_Code|Summer of Code Projects]]
:Information on Summer of Code projects and prospects related to KDE
|-
| ||
;[[/English Breakfast Network|KDE Code Quality (EBN)]]
: The English Breakfast Network and associated tools dedicated to KDE Quality, including: KDE API Documentation Validation, User Documentation Validation, Source Code Checking, ...
|-
| ||
;[[/KDE Research|KDE Research]]
: Project and community for everyone who is interested in contributing to (funded) research projects with(in) the KDE community.
|-
|}

= Frameworks =

{| style="margin: 1em 2.5% 0 2.5%; padding: 0 5px;" cellpadding="5"
|-
|[[Image:logo_oxygen.png|noframe|left|40px]] ||
;[[/Oxygen|The Oxygen Project]]
:Artwork for KDE4.
|-
|[[Image:Klogo-official-crystal.svg|noframe|left|40px]] ||
;[[/kdelibs|KDE Core Libraries]]
:For the core developers working on the kdelibs module.
|-
|[[Image:Decibel.png|noframe|left|40px]] ||
;[[/Decibel|Decibel]]
:Decibel - Realtime communications framework
|-
| ||
;[[/KGLEngine2D | KGLEngine2D]]
: KGLEngine2D is a framework designed to greatly simplify the development of reach multimedia applications on KDE enabled platforms.
|-
| ||
;[[/KioFuse|KioFuse]]
: Insert KIO resources (remote, archived or compressed files) into the root filesystem hierarchy.
|-
|[[Image:Nepomuk_logo.png|noframe|left|40px]] ||
;[[/Nepomuk|Nepomuk]]
:Nepomuk Semantic Desktop project - Annotation/Indexing/Search/Linking
|-
|[[Image:Action_filequickprint.svg|noframe|left|40px]] ||
;[[/KDEPrint|KDEPrint]]
:Printing related information for KDE.
|-
|[[Image:knetworkmanager.png|noframe|left|40px]] ||
;[[/Network_Management|Network Management]]
: Development on Solid Networking, KNetworkManager applet and configuration tool.
|-
| ||
;[[/D-Bus-WS|D-Bus Web Service Proxy]]
: Fusion of D-Bus services and web services.
|-
| ||
;[[/Silk | Silk]]
: Project Silk - Deep integration of the web
|-
| ||
;[[/Solid | Solid]]
: Solid - The KDE Hardware Library
|-
| ||
;[[/Kbluetooth | Kbluetooth]]
: Kbluetooth - The KDE Bluetooth Library (deprecated)
|-
| ||
;[[/kdesu|kdesu]]
: Considerations and coordination to make kdesu work well with several backends.
|-
| ||
;[[/Telepathy|Telepathy]]
:Telepathy Realtime Communication Framework - Instant Messaging, VoIP and Collaboration.
|-
| ||
;[[/WebKit|WebKit (webkitkde)]]
: Project which aims to integrate WebKit (QtWebKit) into KDE.
|-
| ||
;[[/Widgets and Classes|Widgets & Classes]]
:Widgets and classes that are not in kdelibs but which you may find useful.
|-
| ||
;[[/KSecretsService|KSecretsService - managing KDE application's secrets]]
:Secrets management infrastructure for KDE applications and a collection of related tools, superseding KWallet.
|-
| ||
;[[/Related|Related Projects]]
: Projects which are related to KDE in any way, as dependencies or build tools.
|-
|}

= Programs =

{| style="margin: 1em 2.5% 0 2.5%; padding: 0 5px;" cellpadding="5"
|-
| [[Image:Aki128.png|noframe|left|40px]]||
;[[/Aki | Aki]]
: Aki - Extensive IRC Client
|-
|||
;[[/Digikam|Digikam]]
:Digikam - Photo Management Software.
|-
| [[Image:Hisc-apps-kget.svg|noframe|left|40px]]||
;[[/KGet|KGet]]
: KGet, a KDE Downloader
|-
| ||
;[[/Gwenview|Gwenview]]
:Gwenview, the image viewer.
|-
|[[Image:K3b.png|noframe|left|40px]] ||
;[[/K3b|K3b]]
:K3B, optical disc writer
|-
| ||
;[[/KDevelop4|KDevelop4]]
:KDevelop4, the KDE IDE.
|-
|[[Image:Knights.png|noframe|left|40px]] ||
;[[/Knights|Knights]]
:A chess program for the KDE Platform.
|-
|[[Image:Kopete.svg|noframe|left|40px]] ||
;[[/Kopete|Kopete]]
:Kopete, the KDE Instant Messaging program.
|-
|[[Image:Marble.png|noframe|left|40px]] ||
;[[/Marble|Marble]]
:Marble Desktop Globe - Can You Feel The Earth Spinning?
|-
| ||
;[[/Okular|Okular]]
:Okular, the unified document viewer.
|-
| ||
;[[/rekonq | rekonq]]
: rekonq - A lightweight Web Browser for KDE based on WebKit
|-
|[[Image:Ktimetracker.png|noframe|left|40px]] ||
;[[KTimeTracker]]
:Time management within the KDE PIM.
|-
| ||
;[[/SystemSettings|System Settings]]
: Development on the System Settings configuration tool.
|-
|[[Image:superkaramba.png|noframe|left|40px]] ||
;[[/SuperKaramba|SuperKaramba]]
:SuperKaramba is a tool that allows you to easily create interactive eye-candy on your KDE desktop.
|-
| ||
;[[/KWin|KWin]]
: The KDE Window Manager.
|-
|}

= Suites =

{| style="margin: 1em 2.5% 0 2.5%; padding: 0 5px;" cellpadding="5"
|-
|[[Image:Action_book2.svg|noframe|left|40px]] ||
;[[/Edu|KDE Education Project]]
:Developing educational software for KDE.
|-
| ||
;[[/extragearReleases|Extragear Releases]]
: A current list of what extragear apps are to be released in sync with the core KDE release schedule.
|-
| ||
;[[/KdeFinance | KDE Finance]]
: KDE Finance is a group of KDE-related financial applications
|-
|[[Image:Action_pencil.svg|noframe|left|40px]] ||
;[[/KOffice|KOffice]] and [http://wiki.koffice.org KOffice.org]
:Developing an Office suite based on KDE.
|-
|[[Image:Action_pencil.svg|noframe|left|40px]] ||
;[[/Calligra/]] and [http://calligra.org Calligra.org]
:Developing an Office suite for KDE.
|-
|[[Image:Action_mail_generic.svg|noframe|left|40px]] ||
;[[/PIM|KDE PIM Project]]
:KDE Personal Information Management.
|-
|[[Image:Plasma_logo.jpg|noframe|left|40px]] ||
;[[/Plasma|Plasma]]
:Quick and easy creation of widgets. Interactive application launchers, window and task managers, weather checkers; they are all made with plasma.
|-
| ||
;[[/Kdetoys | Kdetoys]]
: The Kdetoys project
|-
|[[Image:kdeutils-logo.svg|noframe|left|40px]] ||
;[[/Utils|KDE Utilities Team]]
:For the developers working on the kdeutils module.
|-
| ||
;[[/Necessitas | Necessitas]]
: Necessitas project
|-
|}

= Platforms =

{| style="margin: 1em 2.5% 0 2.5%; padding: 0 5px;" cellpadding="5"
|-
|[[Image:KDE-Mac.png|noframe|left|40px]] ||
;[[/KDE on Mac OS X|KDE on Mac OS X]]
: KDE libraries and applications on Mac OS X.
|-
|[[Image:Konqi-win.png|38px]] ||
;[[/KDE on Windows|KDE on Windows]]
: KDE libraries and applications on MS Windows.
|-
| ||
;[[/KDE on Solaris|KDE on Solaris]]
: KDE libraries and applications on Sun Microsystems Solaris and OpenSolaris.
|-
| ||
;[[/KDE on FreeBSD|KDE on FreeBSD]]
: KDE libraries and applications on FreeBSD and other BSDs.
|-
| ||
;[[Projects/Mobile|Mobile]]
: Project for porting KDE to the Mobile.
|-
|}

__NOTOC__

Projects/Games

2012-04-27T18:07:57Z

Icwiener: Remove empty section.

{{Template:I18n/Language Navigation Bar|Projects/Games}}
Intro to do

===IRC===

We are doing meeting on [irc://irc.kde.org/#kdegames IRC] every month to talk about the games development.

[[/Pre DevDays 2009 Sprint|Sprint prior to Qt Developer Days 2009 in Munich]]

[[Category:KDEGames]]

Projects/Games

2012-04-27T17:43:53Z

Icwiener: Remove empty section.

{{Template:I18n/Language Navigation Bar|Projects/Games}}
Intro to do

==Status==
* [[/Status KDE 4.0|Status KDE 4.0]]
** [[/Documentation_progress|Documentation progress]]
** [[/Icons_ToDo|Icons_ToDo]]

* [[/Akademy 2008 Notes|Akademy 2008 Notes]]

==Meeting==

===IRC===

We are doing meeting on [irc://irc.kde.org/#kdegames IRC] every month to talk about the games development.

[[/Pre DevDays 2009 Sprint|Sprint prior to Qt Developer Days 2009 in Munich]]

[[Category:KDEGames]]

Projects/Games

2012-04-27T17:38:58Z

Icwiener: /* Development */ Delete linkt to empty page.

{{Template:I18n/Language Navigation Bar|Projects/Games}}
Intro to do

==Development==

* [[/Ideas| KDEGames Ideas and Proposals]]
* [[/Proposed_Games|Proposed new games]]

==Status==
* [[/Status KDE 4.0|Status KDE 4.0]]
** [[/Documentation_progress|Documentation progress]]
** [[/Icons_ToDo|Icons_ToDo]]

* [[/Akademy 2008 Notes|Akademy 2008 Notes]]

==Meeting==

===IRC===

We are doing meeting on [irc://irc.kde.org/#kdegames IRC] every month to talk about the games development.

[[/Pre DevDays 2009 Sprint|Sprint prior to Qt Developer Days 2009 in Munich]]

[[Category:KDEGames]]

Projects/Games

2012-04-27T17:35:02Z

Icwiener: Remove obsolete links.

{{Template:I18n/Language Navigation Bar|Projects/Games}}
Intro to do

==Development==

* [[/libkdegames Usage|libkdegames Usage]]
* [[/Ideas| KDEGames Ideas and Proposals]]
* [[/Proposed_Games|Proposed new games]]

==Status==
* [[/Status KDE 4.0|Status KDE 4.0]]
** [[/Documentation_progress|Documentation progress]]
** [[/Icons_ToDo|Icons_ToDo]]

* [[/Akademy 2008 Notes|Akademy 2008 Notes]]

==Meeting==

===IRC===

We are doing meeting on [irc://irc.kde.org/#kdegames IRC] every month to talk about the games development.

[[/Pre DevDays 2009 Sprint|Sprint prior to Qt Developer Days 2009 in Munich]]

[[Category:KDEGames]]

Projects/Games

2012-04-27T17:26:16Z

Icwiener: /* The Game Categories */ Remove empty page.

{{Template:I18n/Language Navigation Bar|Projects/Games}}
Intro to do

== The Game Categories ==
*[[/Tactic and Strategy|Tactic and Strategy]]

==Development==

* [[/libkdegames Usage|libkdegames Usage]]
* [[/Ideas| KDEGames Ideas and Proposals]]
* [[/Proposed_Games|Proposed new games]]

==Status==
* [[/Status KDE 4.0|Status KDE 4.0]]
** [[/Documentation_progress|Documentation progress]]
** [[/Icons_ToDo|Icons_ToDo]]

* [[/Akademy 2008 Notes|Akademy 2008 Notes]]

==Meeting==

===IRC===

We are doing meeting on [irc://irc.kde.org/#kdegames IRC] every month to talk about the games development.

[[/Pre DevDays 2009 Sprint|Sprint prior to Qt Developer Days 2009 in Munich]]

[[Category:KDEGames]]

Projects/Games

2012-04-27T17:21:04Z

Icwiener: /* Development */ Page moved to community.kde.org

{{Template:I18n/Language Navigation Bar|Projects/Games}}
Intro to do

== The Game Categories ==
*[[/Arcade Games|Arcade games]]
*[[/Tactic and Strategy|Tactic and Strategy]]

==Development==

* [[/libkdegames Usage|libkdegames Usage]]
* [[/Ideas| KDEGames Ideas and Proposals]]
* [[/Proposed_Games|Proposed new games]]

==Status==
* [[/Status KDE 4.0|Status KDE 4.0]]
** [[/Documentation_progress|Documentation progress]]
** [[/Icons_ToDo|Icons_ToDo]]

* [[/Akademy 2008 Notes|Akademy 2008 Notes]]

==Meeting==

===IRC===

We are doing meeting on [irc://irc.kde.org/#kdegames IRC] every month to talk about the games development.

[[/Pre DevDays 2009 Sprint|Sprint prior to Qt Developer Days 2009 in Munich]]

[[Category:KDEGames]]

Getting Started/Build/Distributions/Linux From Scratch

2012-04-19T02:48:59Z

Icwiener: code -> syntaxhighlight

{{Template:I18n/Language Navigation Bar|Getting_Started/Build/Distributions/LFS}}

{{TutorialBrowser|

series=Getting Started|

name=Building KDE4 From Source (Linux From Scratch requirements)

NOTE: This page is a little out of date. I will be working on it. You might also want to consult the current SVN of Beyond Linux from Scratch for current package versions and build information.|

pre=[[Getting_Started/Build|Build KDE]], [[Getting_Started/Tutorials/D-Bus/Configuration|D-Bus Configuration]]|
next=[[Getting_Started/Build|Build KDE]]|

reading=[[Development/Tutorials/CMake |Introduction to CMake]]|
}}

== CMake ==

KDE-4 and some supporting libraries use CMake.

Install the latest version from cmake.org

== Library Requirements ==

===General dependencies===

KDE-4 requires a lot of the same general purpose libraries as KDE-3.

The output from running CMake should list what you are missing -- which generally applicable libraries that you need which I will not discuss further.

===DBus and HAL===

A system should have these installed:

::DBus
::DBus-Glib
::HAL
::HAL-Info
::PolicyKit-0.9
::EggDBus
::polkit
::ConsoleKit

(and properly configured) although, strictly speaking, they are not all dependencies for KDE-4.x.

See: [http://www.linuxfromscratch.org/blfs/view/svn BLFS] for build and configure instructions.

HAL, PolicyKit & EggDBus are being phased out and may not be needed.

Newer versions of KDE-4.x should install:

::udev
::upower
::udisks

HOWEVER, KDE-4 and KDESupport libraries may need newer versions of the libraries than those in BLFS. So, it is probably best to install the versions stated above or the latest releases of these dependencies rather than the versions in BLFS.

Some of these libraries are dependent on:

::Linux-PAM
::Shadow

which should be installed and configured according to the BLFS instructions.

===DocBook DTD===

KDE-4 still requires version 4.2 of:

::DocBook SGML DTD
::DocBook XML DTD.

See the instructions in this old version of BLFS:

::http://archive.linuxfromscratch.org/blfs-museum/5.0/BLFS-5.0/

===Boost C++ Libraries===

Get the current release (e.g. boost_1_42_0.tar.gz) here:

::http://sourceforge.net/projects/boost/files/boost/

=====Build=====

The current release eliminates the arcane naming issues. Although not the same as using autotools, it is now simple to build and install.

Remove the includes from previous versions:

::/usr/include/boost_<version>

and if you have a link:

::/usr/include/boost

remove that also.

Then:

<syntaxhighlight lang="bash">./bootstrap.sh --prefix=/usr</syntaxhighlight>

<syntaxhighlight lang="bash">./b2 install link=shared</syntaxhighlight>

===CLucene===
Current KDE-4 works with the current release available here:

::http://downloads.sourceforge.net/project/clucene/

Use CMake to build it.

===Qt===

=====TRUNK=====

Use kde-qt from:

::git clone git://gitorious.org/+kde-developers/qt/kde-qt.git

This installs as Qt-<version>, so when it updates to the next version, it won't install in the same place. This means that you will need to change the <version> any place where it is specified. You will also have to install QCA (and its plugins) again when the version changes.

=====KDE >= 4.4=====

You can use the GIT clone [see TRUNK above], or your can use the latest release of QT-4.x.y from Nokia:

::http://qt.nokia.com/downloads/linux-x11-cpp

=====BRANCH up to 4.3 or a release up to 4.3.x=====

Use 4.5.3:

::http://qt.nokia.com/downloads/downloads#lgpl

Or a newer release (see above). A newer release may have issues.

=====Build=====

You will probably need to use some options for configuring Qt. Various options may be appropriate and/or needed depending on your system, what you have installed, and where it is installed. Run:

<syntaxhighlight lang="bash">./configure --help</syntaxhighlight>

to see the options. There are a lot of them, but the defaults work for most of them.

Suggested configuration:

<syntaxhighlight lang="bash">./configure -no-separate-debug-info -plugin-sql-mysql -I/usr/include/mysql -plugin-sql-sqlite -optimized-qmake -nomake demos -nomake examples -fast -dbus</syntaxhighlight>

{change the include directory for mysql as needed}

If installing Phonon from KDESupport (recommended), or other separate Phonon, add the configure option:

<syntaxhighlight lang="bash">-no-phonon</syntaxhighlight>

to avoid having two versions of libraries with the same SO number.

===QCA-2.0.2 (crypto add on for Qt)===

Do not use the one in KDESupport or KDE's SVN.

Download the current release of qca from:

::http://delta.affinix.com/download/qca/2.0/

and the plugins:

::qca-cyrus-sasl
::qca-gnupg
::qca-ossl

from:

::http://delta.affinix.com/download/qca/2.0/plugins/

=====Build=====

NOTE: qca-ossl-2.0.0-beta3 may not build against older releases of OpenSSL without being patched:

::http://home.earthlink.net/~tyrerj/kde/KDE-4/qca-ossl.patch

For current releases, be sure to enable MD2:

<syntaxhighlight lang="bash">enable-md2</syntaxhighlight>

when building OpenSSL.

Check the BLFS SVN for a possible corrections to the build scripts.

Set the: "QTDIR" environment variable correctly and then build QCA with:

<syntaxhighlight lang="bash">./configure --prefix=$QTDIR</syntaxhighlight>

<syntaxhighlight lang="bash">make</syntaxhighlight>

<syntaxhighlight lang="bash">make install</syntaxhighlight>

Then build the plugins with

<syntaxhighlight lang="bash">./configure</syntaxhighlight>

<syntaxhighlight lang="bash">make</syntaxhighlight>

<syntaxhighlight lang="bash">make install</syntaxhighlight>

===LibDBusMenu-Qt===

Required for KDE >= 4.5.0. Appears to be optional for KDE-4.4.

Get current release here:

::https://launchpad.net/libdbusmenu-qt/+download

and the current release of the dependency QJson here:

::http://sourceforge.net/projects/qjson/files/

===GMM===

If you don't have Getfem++ installed, get the current release of GMM from:

::http://home.gna.org/getfem/download.html

===Eigen2===

Get the current 2.0.x release from:

::http://eigen.tuxfamily.org

===Java Development Kit===

You need a Java compiler with JNI to build the Sesame2 storage backend for Soprano and a Java RunTime (JVM) to run it.

::http://java.sun.com/javase/downloads/widget/jdk6.jsp

Remember to add the "bin" directory to your path and the "lib" directory to your "/etc/ld.so.conf" file.

===Raptor, Rasqal, and Redland===

Get the current releases of:

::redland
::rasqal
::raptor2

From:

::http://download.librdf.org/source/

and the current release of the (optional) Redland dependency 3Store here:

::http://downloads.sourceforge.net/project/threestore/files/

Note: If 3store3-3.0.17 will not build against Rasqal, then skip it for now -- it is optional.

When building Redland, you might need to use:

::--with-bdb=

to point to your Berkeley DB directory.

If Redland won't build against SQLite, be sure you have the current >= 3.7.3 installed:

Install in this order:

::Raptor
::Rasqal
::Redland

===Virtuoso Open-Source===

Only needed for KDE >= 4.4 and TRUNK

Get virtuoso-opensource >= 6.1.1 here:

::http://sourceforge.net/projects/virtuoso/

If you have problems, use the direct link:

::http://downloads.sourceforge.net/project/virtuoso/virtuoso/6.1.1/virtuoso-opensource-6.1.1.tar.gz

and the current release of the dependency iODBC here:

::http://www.iodbc.org/dataspace/iodbc/wiki/iODBC/Downloads

If building iODBC only for KDE, use configure parameter:

::--disable-gui

For building Virtuoso, these configure parameters are useful:

<syntaxhighlight lang="bash">--with-jdk4=</syntaxhighlight>

<syntaxhighlight lang="bash">--without-internal-zlib</syntaxhighlight>

<syntaxhighlight lang="bash">--with-pthreads</syntaxhighlight>

<syntaxhighlight lang="bash">--with-readline</syntaxhighlight>

<syntaxhighlight lang="bash">--with-iodbc=</syntaxhighlight>

Check the BLFS SVN for other parameters.

If building Virtuoso only for KDE, (to save disk space) use configure parameters:

<syntaxhighlight lang="bash">--disable-all-vads</syntaxhighlight>

<syntaxhighlight lang="bash">--disable-static</syntaxhighlight>

===KDE Supporting dependencies===

=====TRUNK=====

use KDESupport:

::svn co svn://anonsvn.kde.org/home/kde/trunk/kdesupport

If you don't want to install all the small SVN icons:

::cd kdesupport/oxygen-icons
::svn rm `find -name "small"`

=====KDE 4.6=====

There is no KDESupport-4.6 so, you need to install these packages with:

::CMAKE_INSTALL_PREFIX:PATH=/opt/KDE-4.6 for the BRANCH.

Or:

::CMAKE_INSTALL_PREFIX:PATH=/opt/KDE-4.6.x for a release.

======Automoc4======

Available here:

::ftp://ftp.kde.org/pub/kde/stable/automoc4/<version>

======Attica======

Available here:

::ftp://ftp.kde.org/pub/kde/stable/attica

======Polkit-Qt======

Available here:

::ftp://ftp.kde.org/pub/kde/stable/apps/KDE4.x/admin

======Polkit-Qt-1======

Available here:

::ftp://ftp.kde.org/pub/kde/stable/apps/KDE4.x/admin

======Soprano======

Available from Source Forge:

::http://sourceforge.net/projects/soprano/

======Akonadi======

Available here:

::http://download.akonadi-project.org

======Cagibi======

Available here:

::ftp://ftp.kde.org/pub/kde/stable/cagibi

======Strigi======

Available from SourceForge:

::http://downloads.sourceforge.net/strigi

======QImageBlitz======

Available from Source Forge:

::http://sourceforge.net/projects/qimageblitz/files/qimageblitz

=====KDE 4.4 & 4.5=====

Use KDESupport:

::svn co svn://anonsvn.kde.org/home/kde/tags/kdesupport-for-<version>

This does not include: Ontologies. See below.

=====BRANCH up to 4.3 or a release up to 4.3.x=====

Use the KDESupport SVN tag that matches your KDE version. E.G. for 4.3:

::svn co svn://anonsvn.kde.org/home/kde/tags/kdesupport-for-4.3/kdesupport

=====TagLib=====

Since TagLib is also a dependency for GStreamer (gst-plugins-good), you probably don't want to have a redundant installation for the KDE-4 version that will be your 'production' version. Remove it from KDESupport SVN:

::svn rm taglib

And install the current release from:

::http://developer.kde.org/~wheeler/taglib.html

NOTE: To get GST Plugins Good to build the plugin for TagLib you need to set the environment variable:

::HAVE_CXX="yes"

before you run: "configure".

=====QCA=====

The QCA in KDESupport is not currently used (see QCA-2.0.2 above) so:

::svn rm qca

=====Phonon=====

For KDE Support 4.5 and TRUNK:

Do not use the version in KDE Support. Remove if from KDE Support:

::svn rm phonon

See below

=====Build=====

The current KDESupport may not be compatible with LFS installed FFmpeg. Use this patch:

<nowiki>------8<------8<------8<------8<------8<------8<------8<------8<------8<------8<------8<------</nowiki>
<syntaxhighlight lang="diff">
Index: strigi/src/streamanalyzer/endplugins/CMakeLists.txt
--- strigi/src/streamanalyzer/endplugins/CMakeLists.txt (revision 1096146)
+++ strigi/src/streamanalyzer/endplugins/CMakeLists.txt (working copy)
@@ -34,9 +34,3 @@
target_link_libraries(xine ${XINE_LIBRARY})
endif(XINE_FOUND)

-if(FFMPEG_FOUND)
- include_directories(${FFMPEG_INCLUDE_DIRS})
- ADD_STRIGIEA(ffmpeg ffmpegendanalyzer.cpp)
- #set_target_properties( ffmpeg PROPERTIES COMPILE_FLAGS "${FFMPEG_DEFINITIONS}" )
- target_link_libraries(ffmpeg ${FFMPEG_LIBRARIES})
-endif(FFMPEG_FOUND)
</syntaxhighlight>
<nowiki>------8<------8<------8<------8<------8<------8<------8<------8<------8<------8<------8<------</nowiki>

Or, use the FFmpeg snapshot on the CBLFS page:

::http://cblfs.cross-lfs.org/index.php/FFmpeg

This more recent snapshot requires: "libx264.so.83". The x264 snapshot on CBFLS is too old. This Source RPM worked:

::x264-0.83.2245-1plf2010.1.src.rpm

Google is your friend.

NOTE: You may need to add these parameters to the CMake command line:

::-DENABLE_FAM:BOOL=ON
::-DENABLE_EXPAT:BOOL=ON
::-DENABLE_INOTIFY:BOOL=ON
::-DGAIM_LIBS:STRING=<path>/lib
::-DGAMIN_LIBRARIES:STRING=<path>/lib

You must build with the same CMake parameters as the KDE-4 modules; specifically:

::-DCMAKE_INSTALL_PREFIX:PATH=/opt/KDE-<version>
::-DSYSCONF_INSTALL_DIR=/etc/kde-<version>

===Ontologies===

Required for KDE >= 4.4 and TRUNK.

If you checked out KDESupport from TRUNK, you have the package. Otherwise, get TRUNK here:

::git clone git://oscaf.git.sourceforge.net/gitroot/oscaf/oscaf

Or the release from Source Forge:

::http://sourceforge.net/projects/oscaf/files/shared-desktop-ontologies/

and install with CMake with:

:CMAKE_INSTALL_PREFIX:PATH=/usr

===Phonon===

=====TRUNK=====

Phonon has been moved to

::http://gitorious.org/phonon

Get it with the command:

::git clone git://gitorious.org/phonon/phonon.git

=====KDE >= 4.5=====

The current release of Phonon is available here:

::ftp://ftp.kde.org/pub/kde/stable/phonon/<version>/src

Also install back ends as needed. You must install a back end -- either GStreamer or Xine for Linux. They are available here:

::ftp://ftp.kde.org/pub/kde/stable/phonon/phonon-backend-<name>/4.4.4/<version>/src

Where <name> is one of:

:directshow
:gstreamer
:vlc
:xine

=====KDE-4.4=====

<big>KDEBindings-4.4.x will not build against Phonon from the GIT repository.</big>

Use the version in KDESupport-4.4.

=====Build=====

Install with:

::CMAKE_INSTALL_PREFIX=$QTDIR

and the rest of the CMake parameters the same as KDESupport or Supporting dependencies.

===PolKit-KDE-1===

=====KDE >= 4.4 and TRUNK=====

Use:

::ftp://ftp.kde.org/pub/kde/stable/apps/KDE4.x/admin/polkit-kde-1-0.95.1.tar.bz2

=====Build=====

The 0.95.1 tarball from the KDE FTP site will not install correctly. You need to apply this patch:

<nowiki>------8<------8<------8<------8<------8<------8<------8<------8<------8<------8<------8<------</nowiki>
<syntaxhighlight lang="diff">
diff -Naur polkit-kde-1-0.95.1.old/agent/CMakeLists.txt polkit-kde-1-0.95.1/agent/CMakeLists.txt
--- polkit-kde-1-0.95.1.old/agent/CMakeLists.txt 2009-12-23 04:31:29.000000000 -0700
+++ polkit-kde-1-0.95.1/agent/CMakeLists.txt 2010-03-25 15:54:12.000000000 -0700
@@ -11,7 +11,7 @@

target_link_libraries(polkit-kde-authentication-agent-1
${KDE4_KDEUI_LIBS}
- ${POLKITQT-1_AGENT_LIBRARY}
+ ${POLKITQT-1_LIBRARIES}
)

configure_file(polkit-kde-authentication-agent-1.desktop.in ${CMAKE_BINARY_DIR}/polkit-kde-authentication-agent-1.desktop)
@@ -25,4 +25,4 @@
set (DESKTOP_INSTALL_DIR /etc/xdg/autostart)
endif (DESKTOP_INSTALL_DIR)

-install(FILES ${CMAKE_BINARY_DIR}/polkit-kde-authentication-agent-1.desktop DESTINATION ${DESKTOP_INSTALL_DIR})
+install(FILES ${CMAKE_BINARY_DIR}/polkit-kde-authentication-agent-1.desktop DESTINATION ${KDE4_AUTOSTART_INSTALL_DIR})
</syntaxhighlight>
<nowiki>------8<------8<------8<------8<------8<------8<------8<------8<------8<------8<------8<------</nowiki>

You must build with the same CMake parameters as the KDE-4 modules; specifically:

::-DCMAKE_INSTALL_PREFIX:PATH=/opt/KDE-<version>
::-DSYSCONF_INSTALL_DIR=/etc/kde-<version>
::-DKDE4_AUTH_POLICY_FILES_INSTALL_DIR:STRING=/usr/share/PolicyKit/policy

===shared-mime-info===

You should have this installed with a prefix: "/usr". All you need to do is build KDE-4 with:

::-DUPDATE_MIME_DATABASE_EXECUTABLE:FILEPATH=/usr/bin/update-mime-database

However there appears to be a problem for KDE < 4.5

Get the current release from:

::http://www.freedesktop.org/wiki/Software/shared-mime-info

You need to install this with the same prefix as KDE4 (even if you already have it installed in "/usr") to eliminate missing MIME type errors. Currently, KDELibs won't build unless you do this. And, even if it does, you will get run time errors -- popup windows saying that certain MIME types can not be found.

This appears to be a bug that was fixed with KDE-4.5; for ealier versions this workaround does seem to work.

===KIPI Plugins===

Get the current release from:

::http://sourceforge.net/projects/kipi/

This package is dependent on KDEGraphics. The package has a lot of optional dependencies which you need to satisfy only if you want the corresponding plugins built. You should install it in the same directory where you installed KDE-4.x.y.

Be sure that you updated your: "PKG_CONFIG_PATH" to include $CMAKE_INSTALL_PREFIX/lib/pkgconfig (for example):

::/opt/KDE-4/lib/pkgconfig

===Oxygen Icons===

If you checked out KDESupport from TRUNK or the TAG: "kdesupport-for-<version>", you have them.

If you checked out KDESupport from a tag "kdesupport-<version>" up to 4.3 or didn't use KDESupport, you need to get them. If you are using SVN, that would be:

::svn co svn://anonsvn.kde.org/home/kde/tags/KDE/<version>/oxygen-icons

{where <version> is the latest release for the branch you are using (e.g. 4.3.4 for the 4.3 branch)}

Or, you can simply use TRUNK:

::svn co svn://anonsvn.kde.org/home/kde/trunk/kdesupportsvn/oxygen-icons

===LibSSH===

TRUNK and KDE-4.4 require libssh. Get the current release >= 0.4.0 from:

::http://www.libssh.org/

===Dependencies for specific KDE modules===

====KDEBindings====

=====SIP and PyQt=====

To build the Python bindings for KDE, you need the current releases of SIP and PyQt from here:

::http://www.riverbankcomputing.com/software/sip/download
::http://www.riverbankcomputing.com/software/pyqt/download

Install: "SIP" first and then: "PyQt". These are both Python add-ons so they install with:

::python configure.py
::make
::make install

=====Build Notes for PyQt=====

Unless you want to get into serious complications, you should only build PyQt against one version of Qt and you should only install one version of KDEBindings. If you try to build against multiple versions of Qt or install multiple versions of KDEBindings, with a single instance of Python (or other languages), you will install two versions of the same file in the same place.

PyQt will find Qt based on your environment variables. So, if you want to install for a version of KDE other than the one that you are currently using, be sure that these are set correctly:

::QTDIR
::QT_PLUGIN_PATH

KDEBindings is dependent on KDEGraphics (specifically Okular).

Other language dependencies are optional. If you have other supported languages installed on your system, installing KDEBindings will build bindings for them.

=====QScintilla2=====

QScintilla2 is optional. If you are installing it, get it here:

::http://www.riverbankcomputing.com/software/qscintilla/download

Install it after SIP & PyQt. It has a Qt build system, so install for Qt4 it with:

::cd Qt4
::qmake qscintilla.pro
::make
::make install

====KDEEdu====

KDEEdu might be dependent on KDEBindings.

====KDENetwork====

v4l-utils and Libv4l

Only required for KDE >= 4.4 and TRUNK

Get the current release here:

::http://freecode.com/projects/libv4l

and follow the build instructions in the INSTALL file.

=====Optional Dependencies=====

Telepathy-Qt4 is the Qt bindings for Telepathy. Since this has general usage, you should probably install it along with its semi-optional dependency telepathy-glib.

Get the current releases here:

::http://telepathy.freedesktop.org/releases/telepathy-glib/
::http://telepathy.freedesktop.org/releases/telepathy-qt4/

Install: "telepathy-glib" first and then: 'telepathy-qt4".

The output from CMake lists several other optional dependencies. It appears that these are needed to support specific functions in KDENetwork. So, if you need those functions, you need to install them. You will probably also need to install the corresponding Telepathy addons from here:

::http://telepathy.freedesktop.org/releases/

TO DO: more information needed.

Thread:User talk:StijnRuts/Plasma Tutorial/reply (2)

2012-04-06T18:50:10Z

Icwiener: Reply to Plasma Tutorial

Ok, I moved it there and added a link to the page. Sorry for the hickups of moving it incorrectly at first. And thanks for the contribution. :)

Development/Tutorials/Plasma/WallpaperDoubleBuffer

2012-04-06T18:48:31Z

Icwiener: moved Http://techbase.kde.org/Development/Tutorials/Plasma/WallpaperDoubleBuffer to Development/Tutorials/Plasma/WallpaperDoubleBuffer: Next try to move this page to its correct location.

= Plasma Wallpaper Tutorial 3 - Double Buffer =

==Introduction==

So far we have ignored the exposedRect argument of our paint function. Whenever the paint function was called we redrew the entire wallpaper even when only a small region needed repainting. As you can imagine this is not very efficient so let's improve our wallpaper by using a so-called 'double buffer' technique.

==Adding the Buffer==

The way this double buffer technique works is by rendering our wallpaper to a pixmap in memory, the buffer, instead of rendering it directly to the screen. Whenever a region on the screen needs repainting we can just copy the corresponding region from the buffer to the screen.

First we'll need to add the buffer to our private variables and write a new function for rendering the buffer. Add the following lines to our tutorial.h:

<syntaxhighlight lang="cpp-qt">
#ifndef PLASMA_WALLPAPER_TUTORIAL
#define PLASMA_WALLPAPER_TUTORIAL

#include <Plasma/Wallpaper>
#include "ui_config.h"

class Tutorial : public Plasma::Wallpaper
{
Q_OBJECT
public:
Tutorial(QObject* parent, const QVariantList& args);

virtual void save(KConfigGroup &config);
void paint(QPainter* painter, const QRectF& exposedRect);
virtual QWidget* createConfigurationInterface(QWidget* parent);

Q_SIGNALS:
void settingsChanged(bool modified);

protected:
virtual void init(const KConfigGroup &config);

protected slots:
void settingsModified();

private:
Ui::Config configWidget;
QColor backgroundColor;
QColor textColor;
QFont textFont;
QString textString;
QPixmap buffer; // New
void render(); // New
};

K_EXPORT_PLASMA_WALLPAPER(tutorial, Tutorial)

#endif
</syntaxhighlight>

Now we will implement render() in our tutorial.cpp. This function is largely identical to the old paint function, except it will draw to our newly created buffer.

<syntaxhighlight lang="cpp-qt">
void Tutorial::render()
{
if(buffer.size() != boundingRect().size())
{
buffer = QPixmap(boundingRect().size().toSize());
}

QPainter painter;
painter.begin(&buffer);

painter.setPen(backgroundColor);
painter.setBrush(backgroundColor);
painter.drawRect(boundingRect());

painter.setPen(textColor);
painter.setFont(textFont);
painter.drawText(boundingRect(), Qt::AlignCenter, textString);
}
</syntaxhighlight>

If the buffer has the wrong size or if the buffer doesn't exist yet (size = 0px*0px) we create a new QPixmap with the same size as our wallpaper. We then associate a QPainter object with this buffer and draw with the QPainter as before.

==Using the Buffer==

We will now need to change the paint function to make use of our buffer.

<syntaxhighlight lang="cpp-qt">
void Tutorial::paint(QPainter *painter, const QRectF& exposedRect)
{
if(buffer.size() != boundingRect().size())
{
render();
}

painter->drawPixmap(exposedRect, buffer, exposedRect);
}
</syntaxhighlight>

If the buffer has the wrong size or if the buffer doesn't exist yet (size = 0px*0px) we call our render function to fill the buffer with the correct content. When our buffer is up-to-date we copy the exposedRect region from the buffer to the painter.

We'll also need to update the buffer, by calling our render function, whenever the content of the wallpaper changes. Add the following lines to the init and settingsModified functions in our tutorial.cpp:

<syntaxhighlight lang="cpp-qt">
void Tutorial::init(const KConfigGroup &config)
{
backgroundColor = config.readEntry("backgroundColor", QColor(Qt::white));
textColor = config.readEntry("textColor", QColor(Qt::black));
textFont = config.readEntry("textFont", QFont("Arial", 50));
textString = config.readEntry("textString", QString("Hello World!"));

render(); // New
emit update(boundingRect());
}

void Tutorial::settingsModified()
{
textString = configWidget.textString->text();
textFont = configWidget.textFont->font();
textColor = configWidget.textColor->color();
backgroundColor = configWidget.backgroundColor->color();

render(); // New
emit settingsChanged(true);
emit update(boundingRect());
}
</syntaxhighlight>

== Compiling ==

To compile we follow the same steps as before:

<syntaxhighlight lang="bash">
mkdir -p build
cd build
cmake .. -DCMAKE_INSTALL_PREFIX=`kde4-config --prefix`
make
sudo make install
</syntaxhighlight>

== Testing ==

Again we can test using the Plasma wallpaper viewer:

<syntaxhighlight lang="bash">
plasmawallpaperviewer -p tutorial
</syntaxhighlight>

Or we can test it directly on our desktop. Restart plasma using:

<syntaxhighlight lang="bash">
kquitapp plasma-desktop; sleep 1; plasma-desktop
</syntaxhighlight>

Then right click on your desktop, go to Desktop Settings>Wallpaper>Type and select 'Tutorial'.

== Conclusion ==

By adding a buffer to our wallpaper plugin we can make it redraw only the parts that need to be redrawn.

Development/Tutorials/Plasma/WallpaperDoubleBuffer

2012-04-06T18:47:51Z

Icwiener: moved /Development/Tutorials/Plasma/WallpaperDoubleBuffer to Http://techbase.kde.org/Development/Tutorials/Plasma/WallpaperDoubleBuffer: revert Man, it's easy to blow things up. :/

Development/Tutorials/Plasma/WallpaperDoubleBuffer

2012-04-06T18:46:26Z

Icwiener: moved Http://techbase.kde.org/Development/Tutorials/Plasma/WallpaperDoubleBuffer to /Development/Tutorials/Plasma/WallpaperDoubleBuffer: Oops?

Development/Tutorials/Plasma

2012-04-06T18:45:37Z

Icwiener: /* Wallpapers */ Add new tutorial.

{{Template:I18n/Language Navigation Bar|Development/Tutorials/Plasma}}

== QML ==
Plasmoids that use the QML (aka QtQuick) declarative language to describe their user interface while having the logic of the applet, in JavaScript (QML is essentially a forge between CSS and JavaScript).

This is now the '''recommended''' method of creating plasmoids, where possible. The plasmoid, or applet serves as the visualization for the data which a Plasma::DataEngine contains.

It allows easily the declaring of an interface and to easily create things like ListViews with native Plasma theming. It is what Plasma is leaning the most towards, especially in the Mobile, MediaCenter and KDM shells.

;[[Development/Tutorials/Plasma/QML/GettingStarted|Getting Started]]
:''Creating and running your first plasmoid in QML''

;[[Development/Tutorials/Plasma/QML/Basic_ListView|Basic List Plasmoid]]
:''Make a QML ListView which displays basic text objects as items. Utilizes native Plasma theming and animations.''

;[[Development/Tutorials/Plasma/QML/API|API Reference]]
:''The QML Plasmoid API. Useful for referencing what is available in the runtime, what are the differences with the pure JavaScript ScriptEngine, the differences between pure Qt QML and Plasma, and as a study aid for the tutorials above.''

== C++ ==

=== Plasmoids ===
;[[Development/Tutorials/Plasma/GettingStarted|Getting Started With Plasmoids]]
:''Creating your first plasmoid in C++ with SVG background, icon and text''

;[[Development/Tutorials/Plasma/GettingStarted..Some_More|Getting Started With Plasmoids..Some more]] :''A few more starter's tips.''

;[[Development/Tutorials/Plasma/UsingExtenders|How to use extenders in your Plasmoid]]
:''A simple example that shows how to use extenders in a Plasmoid.''

;[http://www.linux-magazine.com/w3/issue/114/036-040_plasma.pdf Creating Plasmoids]
:''May 2010 article from Linux Magazine''

;[http://www.ibm.com/developerworks/linux/library/l-kde-plasmoids/index.html Create Plasmoids using KDevelop]
:''Article explaining the structure of Plasma and how to create a Plasmoid''

;[http://community.kde.org/User:Mxttie#Adding_configuration Adding configuration to your plasmoid]
:''Article explaining how to add a configuration dialog to your plasmoid.''

=== DataEngines ===

;[[Development/Tutorials/Plasma/DataEngines|Writing a DataEngine]]
:''DataEngines provide a standardized interface to various (read only) data sources for visualizations to use. Learn what a DataEngine is and how to write one of your own.''

;[[Development/Tutorials/Plasma/Services|Writing a Service]]
:''Services provide a standardized interface for visualizations to perform "write operations". This can be for example, uploading pasted test to a pastebin service..''

=== PackageStructures ===

;[[Development/Tutorials/Plasma/PackageStructure|Writing a PackageStructure Plugin]]
:''PackageStructure plugins allow custom Packages to be defined, installed, removed and listed as well as provide access their contents at runtime. Packages may contain any kind of data addons, including scripts.''

=== Runners ===

;[[Development/Tutorials/Plasma/AbstractRunner|Creating Runners]]
:''Runners are plugins that provide action-based search functionality in the Plasma workspace "run command" dialog. These plugins can be used by any application that links again libplasma.''

=== Wallpapers ===

;[[Development/Tutorials/Plasma/WallpaperHelloWorld|Wallpaper Tutorial 1]]
:''This tutorial shows you how to make a simple Hello World plasma wallpaper plugin.''

;[[Development/Tutorials/Plasma/WallpaperConfiguration|Wallpaper Tutorial 2]]
:''This tutorial covers how to add configuration options to the wallpaper.''

;[[Development/Tutorials/Plasma/WallpaperDoubleBuffer|Wallpaper Tutorial 3]]
:''This tutorial improves the wallpaper by using the so-called 'double buffer' technique.''

=== Plasma Shells ===

;[[Development/Tutorials/Plasma/ShellDesign|Creating a Plasma Shell]]
:''This tutorial covers the essentials of writing a new Plasma shell from scratch. A must-read for anyone creating a new or modifying an existing Plasma Shell. Existing Plasma shells include Plasma Desktop, Plasma Netbook, Plasma Mobile, Plasma Media Center, Plasma Screensaver, Plasma KPart and Plasma KDM, and all follow the patterns documented here.''

== JavaScript ==

Plasma has built-in JavaScript (also known as ECMAScript, and often referred to as QtScript in the context of Qt) scripting support without requiring any external dependencies.

=== Plasmoids ===

;[[Development/Tutorials/Plasma/JavaScript/GettingStarted|Getting Started]]
:''Creating and running your first plasmoid in JavaScript''

;[[Development/Tutorials/Plasma/JavaScript/DataEngine|Getting Data]]
:''How to retreive data from a data engine''

;[[Development/Tutorials/Plasma/JavaScript/NowPlaying|Now Playing]]
:''Slightly more advanced data engine usage: displaying what's currently playing''

;[[Development/Tutorials/Plasma/JavaScript/SystemMonitor|System Monitor]]
:''How to access systemmonitor data engine''

;[[Development/Tutorials/Plasma/JavaScript/CheatSheet|Cheat Sheet]]
:''A cheat sheet, rather than a tutorial, of things to remember and watch out for when developing JavaScript plasmoids''

;[[Development/Tutorials/Plasma/JavaScript/API|API Reference]]
:''The Simplified JavaScript Plasmoid API. Useful for referencing what is available in the runtime and as a study aid for the tutorials above.''

=== Other Applications Of Javascript ===
;[[KDE_System_Administration/PlasmaDestkopScripting|Scripting Plasma Shells]]
:The KDE Plasma Desktop and Netbook provide means to manage the desktop shell (desktop, panels, widget) via scripts written in JavaScript. This article describes how to take advantage of this feature set as well as documents the full API. This is primarily a system administration tool, but may also be of interest to power users.

;[[Development/Tutorials/Plasma/JavaScript/Animations|Javascript Animations]]
:''How to write Animations using Javascript for use in Plasma applications''

;[[Development/Tutorials/Plasma/ComicPlugin|Creating Comic Plugins]]
:''This guide shows you how to create a comic plugin for the comic plasmoid.''

== Python ==

=== Plasmoids ===
;[[Development/Tutorials/Plasma/Python/GettingStarted|Getting Started]]
:''Creating and running your first plasmoid in Python''

;[[Development/Tutorials/Plasma/Python/Using widgets|Using widgets]]
:''Introduction to using Plasma widgets''

;[[Development/Tutorials/Plasma/Python/Using DataEngines|Using DataEngines]]
:''How to use DataEngines from a plasmoid''

=== DataEngines ===

;[[Development/Tutorials/Plasma/Python/Writing DataEngines|Writing DataEngines]]
:''How to write your own Plasma DataEngine''

;[[Development/Tutorials/Plasma/PythonPlasmoid|Writing a Plasmoid in Python]]
:''Writing a simple battery graph in python''

=== Runners ===

;[[Development/Tutorials/Plasma/PythonRunner|Writing a KRunner plugin in Python]]
:''Writing a simple krunner plugin in python''

== Ruby ==

=== Plasmoids ===

;[[Development/Tutorials/Plasma/Ruby/GettingStarted|Getting Started]]
:''Creating and running your first plasmoid in Ruby''

;[[Development/Tutorials/Plasma/Ruby/Using widgets|Using widgets]]
:''Introduction to using Plasma widgets''

;[[Development/Tutorials/Plasma/Ruby/SimplePasteApplet|Writing a simple paste applet]]
:''A tutorial explaining how to set up a plasmoid, create a simple paste applet using widgets and add Plasma features seen elsewhere. Complete with tips for those who have never programmed before.''

;[[Development/Tutorials/Plasma/Ruby/Blinker|Use SVG artwork in the simplest way possible]]
:''Follow a fellow student as he asks around about SVG usage and explains why the code examples work. This is a wiki so feel free to add your own insights until this tutorial can be considered complete.''

=== DataEngines ===

;[[Development/Tutorials/Plasma/Ruby/Writing DataEngines|Writing DataEngines]]
:''How to write your own Plasma DataEngine using Ruby''

== Web Technologies (HTML/JS/CSS) ==
;[[Development/Tutorials/Plasma/Web/GettingStarted|Getting Started]]
:''Creating and running your first plasmoid in HTML''

== Plasma integration for applications ==

;[[Development/Tutorials/Solid_Device_Actions|Creating a Device Notifier action]]
:''When your application is interested in removable hardware''

;[[Development/Tutorials/Plasma/ApplicationShell|Integrate Plasma in Applications]]
:''This tutorial shows you how to make an application dashboard based on Plasma technologies.''

== Packages ==

;[[Development/Tutorials/Plasma/PackageOverview|Plasma Packages]]
:''An overview of what makes up a Plasma Package and what they are and can be used for.''

;[[Development/Tutorials/Plasma/PackageStructure|Writing a PackageStructure Pluginin C++]]
:''PackageStructure plugins allow custom Packages to be defined, installed, removed and listed as well as provide access their contents at runtime. Packages may contain any kind of data addons, including scripts.''

== Themes ==

;[[Development/Tutorials/Plasma/Theme|Creating a Plasma Theme Quickstart]]
:''A quick guide to creating your first Plasma theme''

;[[Development/Tutorials/Plasma/ThemeDetails|The Plasma Theme Structure In Detail]]
:''A comprehensive guide to the contents of a Plasma SVG theme, including configuration options, wallpapers, on-disk layout, names of all standard SVG files and every element in them.''

== Activity Templates ==

;[[KDE_System_Administration/PlasmaDesktopScripting#Activity_templates|Creating a Plasma Activity Template Quickstart]]
:''A quick guide to creating your first Plasma Activity Template''

== Resources ==

* [[Projects/Plasma|Projects: Plasma]]
* [http://api.kde.org/4.x-api/kdelibs-apidocs/plasma/html/index.html Plasma api documentation]
* [http://techbase.kde.org/Projects/Plasma/Eclipse_Integration Plasma Eclipse Integration]
* The [https://mail.kde.org/mailman/listinfo/plasma-devel plasma-devel mailing list] and #plasma on IRC (irc.freenode.org).

Development/Tutorials/Plasma/WallpaperDoubleBuffer

2012-04-06T18:43:49Z

Icwiener: moved User:StijnRuts to Http://techbase.kde.org/Development/Tutorials/Plasma/WallpaperDoubleBuffer: User request. Part of a series.

Thread:User talk:StijnRuts/Plasma Tutorial

2012-04-05T22:43:59Z

Icwiener: New thread: Plasma Tutorial

Hi,

where would you want this to go?

Regards

User talk:StijnRuts

2012-04-05T22:43:59Z

Icwiener: Talk page autocreated when first thread was posted

Development/Tutorials/Plasma/WallpaperDoubleBuffer

2012-04-05T22:42:37Z

Icwiener: Typo

Projects/Games

2012-04-01T14:10:15Z

Icwiener: /* Status */ Remove unused links.

Projects/Games

2012-04-01T14:05:43Z

Icwiener: /* Development */ Remove unused link.

{{Template:I18n/Language Navigation Bar|Projects/Games}}
Intro to do

== The Game Categories ==
*[[/Arcade Games|Arcade games]]
*[[/Tactic and Strategy|Tactic and Strategy]]

==Development==

* [[/UI and usability|UI and usability]]
* [[/libkdegames Usage|libkdegames Usage]]
* [[/Ideas| KDEGames Ideas and Proposals]]
* [[/Proposed_Games|Proposed new games]]

==Status==
* [[/Status KDE 4.0|Status KDE 4.0]]
** [[/Documentation_progress|Documentation progress]]
** [[/Icons_ToDo|Icons_ToDo]]
* older pages:
** [[/Status_Should_be_Ready|Should be ready]]
** [[/Status_Playground|kdegames playground (kdegame's candidate or unready) ]]
** [[/Status|old status page]]

* [[/Akademy 2008 Notes|Akademy 2008 Notes]]

==Meeting==

===IRC===

We are doing meeting on [irc://irc.kde.org/#kdegames IRC] every month to talk about the games development.

[[/Pre DevDays 2009 Sprint|Sprint prior to Qt Developer Days 2009 in Munich]]

[[Category:KDEGames]]

Projects/Games

2012-03-27T13:27:50Z

Icwiener: /* IRC */ Remove dead link.

{{Template:I18n/Language Navigation Bar|Projects/Games}}
Intro to do

== The Game Categories ==
*[[/Arcade Games|Arcade games]]
*[[/Tactic and Strategy|Tactic and Strategy]]

==Development==

* [[/UI and usability|UI and usability]]
* [[/libkdegames Usage|libkdegames Usage]]
* [[/Ideas| KDEGames Ideas and Proposals]]
* [[/Proposed_Games|Proposed new games]]
* [[/Porting|Porting to new libkdegames components]]

==Status==
* [[/Status KDE 4.0|Status KDE 4.0]]
** [[/Documentation_progress|Documentation progress]]
** [[/Icons_ToDo|Icons_ToDo]]
* older pages:
** [[/Status_Should_be_Ready|Should be ready]]
** [[/Status_Playground|kdegames playground (kdegame's candidate or unready) ]]
** [[/Status|old status page]]

* [[/Akademy 2008 Notes|Akademy 2008 Notes]]

==Meeting==

===IRC===

We are doing meeting on [irc://irc.kde.org/#kdegames IRC] every month to talk about the games development.

[[/Pre DevDays 2009 Sprint|Sprint prior to Qt Developer Days 2009 in Munich]]

[[Category:KDEGames]]

Projects/Games

2012-03-27T12:08:58Z

Icwiener: /* Development */ Remove dead link.

{{Template:I18n/Language Navigation Bar|Projects/Games}}
Intro to do

== The Game Categories ==
*[[/Arcade Games|Arcade games]]
*[[/Tactic and Strategy|Tactic and Strategy]]

==Development==

* [[/UI and usability|UI and usability]]
* [[/libkdegames Usage|libkdegames Usage]]
* [[/Ideas| KDEGames Ideas and Proposals]]
* [[/Proposed_Games|Proposed new games]]
* [[/Porting|Porting to new libkdegames components]]

==Status==
* [[/Status KDE 4.0|Status KDE 4.0]]
** [[/Documentation_progress|Documentation progress]]
** [[/Icons_ToDo|Icons_ToDo]]
* older pages:
** [[/Status_Should_be_Ready|Should be ready]]
** [[/Status_Playground|kdegames playground (kdegame's candidate or unready) ]]
** [[/Status|old status page]]

* [[/Akademy 2008 Notes|Akademy 2008 Notes]]

==Meeting==

===IRC===

We are doing meeting on [irc://irc.kde.org/#kdegames IRC] every month to talk about the games development.

[[/IRC Meeting|Next Meeting : April 2th/2009 20:00 UTC]]

[[/Pre DevDays 2009 Sprint|Sprint prior to Qt Developer Days 2009 in Munich]]

[[Category:KDEGames]]

Projects/Games

2012-03-27T11:55:04Z

Icwiener: /* Status */ Remove dead links.

{{Template:I18n/Language Navigation Bar|Projects/Games}}
Intro to do

== The Game Categories ==
*[[/Arcade Games|Arcade games]]
*[[/Tactic and Strategy|Tactic and Strategy]]

==Development==

* [[/Maintainers| Game's maintainers]]
* [[/UI and usability|UI and usability]]
* [[/libkdegames Usage|libkdegames Usage]]
* [[/Ideas| KDEGames Ideas and Proposals]]
* [[/Proposed_Games|Proposed new games]]
* [[/Porting|Porting to new libkdegames components]]

==Status==
* [[/Status KDE 4.0|Status KDE 4.0]]
** [[/Documentation_progress|Documentation progress]]
** [[/Icons_ToDo|Icons_ToDo]]
* older pages:
** [[/Status_Should_be_Ready|Should be ready]]
** [[/Status_Playground|kdegames playground (kdegame's candidate or unready) ]]
** [[/Status|old status page]]

* [[/Akademy 2008 Notes|Akademy 2008 Notes]]

==Meeting==

===IRC===

We are doing meeting on [irc://irc.kde.org/#kdegames IRC] every month to talk about the games development.

[[/IRC Meeting|Next Meeting : April 2th/2009 20:00 UTC]]

[[/Pre DevDays 2009 Sprint|Sprint prior to Qt Developer Days 2009 in Munich]]

[[Category:KDEGames]]

Projects/Games

2012-03-27T11:49:16Z

Icwiener: /* The Game Categories */ Remove dead links.

{{Template:I18n/Language Navigation Bar|Projects/Games}}
Intro to do

== The Game Categories ==
*[[/Arcade Games|Arcade games]]
*[[/Tactic and Strategy|Tactic and Strategy]]

==Development==

* [[/Maintainers| Game's maintainers]]
* [[/UI and usability|UI and usability]]
* [[/libkdegames Usage|libkdegames Usage]]
* [[/Ideas| KDEGames Ideas and Proposals]]
* [[/Proposed_Games|Proposed new games]]
* [[/Porting|Porting to new libkdegames components]]

==Status==
* [[/Status KDE 4.2|Status KDE 4.2]]
* [[/Status KDE 4.0|Status KDE 4.0]]
** [[/Documentation_progress|Documentation progress]]
** [[/Icons_ToDo|Icons_ToDo]]
* older pages:
** [[/Status_Ready|Ready]]
** [[/Status_Should_be_Ready|Should be ready]]
** [[/Status_Playground|kdegames playground (kdegame's candidate or unready) ]]
** [[/Status|old status page]]

* [[/Akademy 2008 Notes|Akademy 2008 Notes]]

==Meeting==

===IRC===

We are doing meeting on [irc://irc.kde.org/#kdegames IRC] every month to talk about the games development.

[[/IRC Meeting|Next Meeting : April 2th/2009 20:00 UTC]]

[[/Pre DevDays 2009 Sprint|Sprint prior to Qt Developer Days 2009 in Munich]]

[[Category:KDEGames]]

Contribute/Bugsquad/BugDays

2012-03-10T02:05:04Z

Icwiener: Reverted edits by Stolsoenx3 (talk) to last revision by Anselmolsm

This page contains links to the pages for all past bug triage events.

==Next Bug Day==
{{:Contribute/Bugsquad/NextBugDay}}

We don't just do bugs on BugDays! Don't hesitate to join us at #kde-bugs on irc.freenode.net, we have plenty for you to do. ;) Check the topic to see what we are currently working on. And if you are new, please read the "how to triage bugs" page.

==Previous Bug Days==
A Bug Day is where the Bugsquad goes back through bugs in bugzilla for a particular application and closes all reports that are no longer valid.

* [[/DolphinDay1|Dolphin Bug Day 1: Sunday, August 1st 2010]] (All of Dolphin)

* [[/PhononDay|Phonon Bug Day 1: Sunday, November 8th 2009]] (KDE Multimedia subsystem triage)

* [[/PlasmaDay1|Plasma Bug Day 1: Sunday, April 26th 2009]] (All of Plasma Triage)

* [[/KMailDay3|KMail Bug Day 3: Sunday, March 15th 2009]] (All of KMail)

* [[/KDEPimWeek1|KDE Pim Bug Week 1: Sunday, November 23rd - Saturday, December 6th 2008]] (KMail and KOrganizer)

* [[/KDEPimDay2|KDE Pim Bug Day 2: Sunday, November 9th 2008]] (All of KDE Pim)

* [[/KOfficeDay1/Triage|KOffice Bug Day 1, triage: Sunday, October 26th 2008]] (All of KOffice Triage)

* [[/KonquerorDay6|Konqueror Bug Day 6: Sunday, October 12th 2008]] (Konqueror-General Triage)

* [[/KDEPimDay1|KDE Pim Bug Day 1: Sunday, September 28th 2008]] (KDE Pim and Groupware Triage)

* [[/KMailDay2|KMail Bug Day 2: Sunday, September 14th 2008]] (All of KMail Triage)

* [[/KMailDay1|KMail Bug Day 1: Sunday, August 31st 2008]] (All of KMail Triage)

* [[/KopeteDay2|Kopete Bug Day 2: Sunday, July 20th 2008]] (All of Kopete Triage)

* [[/KopeteDay1|Kopete Bug Day 1: Sunday, July 6th 2008]] (All of Kopete Triage)

* [[/AmarokDay1|Amarok Bug Day 1: Sunday, June 15th 2008]] (All of Amarok Triage)

* [[/KonquerorDay5|Konqueror Bug Day 5: Sunday, June 1st 2008]] (Konqueror-General Triage)

* [[/KonquerorDay4|Konqueror Bug Day 4: Sunday, May 18th 2008]] (Konqueror-General Triage)

* [[/KonquerorDay3|Konqueror Bug Day 3: Sunday, May 4th 2008]] (Konqueror-General Triage)

* [[/KonquerorDay2|Konqueror Bug Day 2: Sunday, April 20th 2008]] (KHTML Triage)

* [[/06APR08|Konqueror Bug Day 1: Sunday, April 6th 2008]] (KHTML Triage)

==Previous Krush Days==
A Krush day is where the Bugsquad tests the target application and reports all the bugs they can find in it.

* [[/KOfficeDay2|KOffice Bug Day 2: Sunday, Januar 25th 2009]] KOffice Krush (IN preparation for 2.0 release)
* [[/KOfficeDay1/Krush|KOffice Bug Day 1, krush: Sunday, October 26th 2008]] KOffice Krush (In preparation for 2.0 release)
* [[/KDEPIMKrush1|KDE PIM Krush Day 2: Sunday, June 8th 2008]] KDE PIM Krush (In preparation for 4.1 release) (Continuation from previous KDE PIM Krush Day 1 on the same page).
* [[/KDEPIMKrush1|KDE PIM Krush Day 1: Sunday, May 25th 2008]] KDE PIM Krush (In preparation for 4.1 release).

==Previous bug triage events==
Prior to the convening of the Bugsquad in its current form, there were a number of Bug Triage and Krush events. Tehcbase pages used for these events can be found below.

* [[Contribute/Bugsquad/KrushDays|KDE4 Krush Days]]

* [[Contribute/Bugsquad/Bug_weekends|Konqueror Bug Weekends]]

==Special triage pages==

* [[/KMailWrapup|KMail Triage Wrapup]] (Bugs that still need to be touched to be done)

* [[/KdelibsOngoing1|kdelibs]] (If you're bored, you can pick some of those :)

* [[/KonquerorOngoing1|Konqueror]] (... or of those)

Contribute/Bugsquad/BugDays/06APR08

2012-03-10T02:04:15Z

Icwiener: Reverted edits by Stolsoenx3 (talk) to last revision by Grundleborg

{{Warning|
This page is now archived for reference by the developers. Please do not add information on newly triaged bugs to it.}}

==Introduction==
This triage day will run from 0:00 UTC - 23:59 UTC on April 6th 2008. Our target for triage is bugs listed in [http://bugs.kde.org bugs.kde.org] under the product Konqueror.

'''The goal of this bug-day is to check for: simple step-by-step instructions, reproducibility, and most of all, come up with test-cases for reproducing the bugs. This will enable the Konqueror developers to deal with bugs more easily, and so have more time left to actually fix them.''' When you have added either a test-case or step-by-step instructions for the reproduction of a bug, please list it in the appropriate section below, so that a second triager can see if they can get your instructions/test-case to work correctly. [http://konqueror.kde.org/investigatebug/ This page] provides an excellent explanation of how to create a test-case. [http://techbase.kde.org/index.php?title=Contribute/Bugsquad This page] also has useful information on how to not mis-mark bugs. In particular, "duplicates are hard". Konqueror doesn't have as many duplicates as some applications, and we don't want to claim things are duplicates when they aren't. So do not look too hard for them, and '''make sure''' to double check them with someone else, preferably one of the developers before marking/closing.'''We especially don't want to create more work for developers!'''

Be sure to join #kde-bugs on irc.freenode.net, as this is where the bug-day will be coordinated. (You can even join now!)

You should either be working with Konqueror from KDE 4 (either 4.0.2 or newer is best or SVN trunk) for testing these bugs. In this case, it probably won't matter which one, because KHTML/KJS are aggressively forward-ported and back-ported, and you might find 4.0.x easier to compile.

You may need another browser to test things in.

===Testcases===
If you come across a bug with a testcase in the text, put it under the testcase section. If it isn't marked "testcase" in the title, make a note of that. Check that the testcase works! (And doesn't work!)

Most importantly, we need to [http://konqueror.kde.org/investigatebug/ create testcases]. These are time-consuming, but extremely useful and really help out developers. These are especially important if it is a site that is either a non-Western language or a site you need some sort of account for.

===Unclear===
If something has no clear instructions on how to reproduce it, or has little useful information, add a comment asking the reporter for more detail. Then list it in the [[#Bugs_awaiting_feedback|bugs awaiting feedback]] section. Be polite, we want to be nice to our bug reporters!

===Is it a big bug?===
Prioritizing is good. If a major website doesn't work, that is important.
Let's keep track of them.

===Version field===
Keep an eye on what the "Version:" fields say in Bugzilla. If it says "unspecified", it won't show up in developer's searches for 4.0 bugs! Change the version field to match what the other one says, i.e. to match version the bug was first reported in, or mark it below if you don't have bugzilla permissions. Do not update or change the version number (ex. from 3.5.2 to 4.0.2) if it is currently set as a number! Just make a note on the bug of what the status is in the version you are testing with (be explicit as to what version of 4 you are using, mentioning whether it is a source build or which distro the packages come from).

===Double Check!===
'''Please list bugs here to get a second opinion before making the change in bugzilla. This also gives a record of what we've done for the developers to check.'''

==Details==

Please select a period of bugs from the [[#Division_of_Labour|Division of Labour]] section below and mark your name next to it and mark it with your irc nickname to show that you are working on it. When you have completed all the bugs in that section, please mark it as complete.

For each bug, try and reproduce it as described in the report. Then list it in the appropriate section below. '''If you wish to close or mark as duplicate a bug, please list it here even if you have the bugzilla permissions to do so, in order to get a second opinion from another triager. This will help to reduce the number of incorrect actions taken on bugs.'''

==Sign-in==
Tell developers what you are testing with. (If you expect to upgrade between now and BugDay, put what version you are using now next to the bugs/comments that you put on this page.)

Please give distro/version or SVN branch/trunk with revision below:

{|
|-
!IRC Nickname !! KDE version used for testing
|-
|[[User:Grundleborg|Grundleborg]]||svn trunk r793457||
|-
|[[User:Blauzahl|Blauzahl]]|| svn branches/KDE/4.0 r793901 ||
|-
|[[User:Finex|FiNeX]]|| svn trunk r793368||
|-
|[[User:lemma|lemma]]|| svn trunk r793971||
|-
|krop|| svn trunk r793966||
|-
|annma|| svn trunk r793777||
|-
|kirun|| 4.0.3 kubuntu||
|-
|[[User:Njg234908|Njg234908]]|| 4.0.3 opensuse||
|-
|matt__|| svn trunk r793709||
|-
|[[User:JLP|JLP]]|| svn trunk r794088||
|-
|[[User:Gtoth|sim0nx]]|| svn trunk r793287||
|}

{{Tip|Please be sure to sign every bug or comment you add to this page with your irc nickname. You can use the wiki markup <nowiki>~~~</nowiki> to insert your wiki username automatically (but only do this if it is the same as your IRC nickname, otherwise write your IRC nickname in by hand).}}

==Division of Labour==
Please choose a month that is not already taken and then query bugs.kde.org for all bugs in that month. Please mark you irc nickname in the table below to show which month's bugs you are working on to avoid duplication of effort.

The bugzilla query to use for this triage day can be [http://bugs.kde.org/query.cgi?short_desc_type=allwordssubstr&short_desc=&long_desc_type=allwordssubstr&long_desc=&product=konqueror&component=khtml&component=khtml+adblock&component=khtml+ecma&component=khtml+event&component=khtml+forms&component=khtml+image+part&component=khtml+parsing&component=khtml+part&component=khtml+printing&component=khtml+renderer&component=khtml+xml&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&bug_severity=critical&bug_severity=grave&bug_severity=major&bug_severity=crash&bug_severity=normal&bug_severity=minor&bugidtype=include&bug_id=&votes=&emailassigned_to1=1&emailtype1=substring&email1=&emailassigned_to2=1&emailreporter2=1&emailcc2=1&emailtype2=substring&email2=&changedin=&chfield=%5BBug+creation%5D&chfieldfrom=2003-01-01&chfieldto=2003-01-31&chfieldvalue=&order=Reuse+same+sort+as+last+time&newqueryname=konq-triage-2003-01&namedcmd=2003-onwards found here]. Be sure to correct the dates to the month which you will triage before running the query.

{|
|-
!Month !! No of bugs !! IRC Nickname !! Status
|-
|pre 2003|| 20 ||[[User:Grundleborg|Grundleborg]]||done||
|-
|2003-01 || 4 ||[[User:Finex|FiNeX]]|| done||
|-
|2003-02 || 6 ||[[User:lemma|lemma]]|| done||
|-
|2003-03 || 6 ||[[User:lemma|lemma]]|| done||
|-
|2003-04 || 3 ||[[User:lemma|lemma]]|| done||
|-
|2003-05 || 3 ||[[User:lemma|lemma]]|| done||
|-
|2003-06 || 5 ||[[User:blauzahl|blauzahl]]|| done ||
|-
|2003-07 || 6 || [[User:Grundleborg|Grundleborg]] || done ||
|-
|2003-08 || 5 ||[[User:lemma|lemma]]|| done ||
|-
|2003-09 || 3 || [[User:Grundleborg|Grundleborg]] || done ||
|-
|2003-10 || 8 || [[User:Grundleborg|Grundleborg]] || done ||
|-
|2003-11 || 12 || annma || done ||
|-
|2003-12 || 13 || [[User:Blauzahl|Blauzahl]] || done ||
|-
|2004-01 || 13 ||[[User:Finex|FiNeX]]|| done ||
|-
|2004-02 || 10 || [[User:Njg234908|Njg234908]] || done||
|-
|2004-03 || 14 || matt__ || done||
|-
|2004-04 || 11 ||[[User:Finex|FiNeX]]|| done||
|-
|2004-05 || 14 || [[User:Grundleborg|Grundleborg]] || done ||
|-
|2004-06 || 8 ||[[User:lemma|lemma]]|| done||
|-
|2004-07 || 8 ||[[User:lemma|lemma]]|| done||
|-
|2004-08 || 11 ||[[User:lemma|lemma]]|| done||
|-
|2004-09 || 16 ||[[User:Finex|FiNeX]]|| done ||
|-
|2004-10 || 8 ||[[User:Finex|FiNeX]]|| done ||
|-
|2004-11 || 12 || kirun || done ||
|-
|2004-12 || 13 || [[User:JLP|JLP]] || done ||
|-
|2005-01 || 11 || [[User:Gtoth|sim0nx]] || done ||
|-
|2005-05 || 23 ||[[User:Finex|FiNeX]]|| done ||
|-
|2005-06 || 22 ||[[User:Finex|FiNeX]]|| done ||
|-
|2005-10 || 20 ||[[User:Finex|FiNeX]]|| done ||
|-
|2005-12 || 21 ||[[User:Finex|FiNeX]]|| done ||
|-
|2006-01 || 13 ||[[User:krop|krop]]|| done ||
|-
|2006-02 || 13 ||[[User:krop|krop]]|| done ||
|}

(Total bugs 355)

==Bugs needing version field changed==
Bugs should be listed here if their version field is invalid and they are still present in KDE 4, so that the version field can be corrected.

==Bugs with test-cases Added==
Bugs that have had a test case (an example of how to reproduce the bug) added should be entered below.
*{{Bug|19921}} - test case was already there but wasn't marked. [[User:Grundleborg|Grundleborg]]
**[testcase] tag added. [[User:Grundleborg|Grundleborg]]
*{{Bug|32563}} - testcase added. [[User:Grundleborg|Grundleborg]]
*{{Bug|79492}} - testcase already present. Bug still reproducible [[User:Finex|Finex]]
**seconded [[User:Grundleborg|Grundleborg]]
*{{Bug|79813}} - testcase already present. Added on the subject. Bug still reproducible: Saving the file of the testcase will start Kget which save an empty file [[User:Finex|Finex]]
*{{Bug|79813}} - testcase already present. Added on the subject. Bug (?) still reproducible. Is it really a bug? It should be checked if a valid email address could contain a "#" char [[User:Finex|Finex]]
*{{Bug|80432}} - testcase already present (even on subject). Bug still reproducible. [[User:Finex|Finex]]
*{{Bug|54844}} - simple (!) testcase added. Bug still reproducible but minor. Needs version change. [[User:lemma|lemma]]
**[testcase] tag added. [[User:Grundleborg|Grundleborg]]
*{{Bug|54696}} - testcase already present (even on subject). Bug still reproducible. Needs version change. [[User:lemma|lemma]]
** version changed [[User:Grundleborg|Grundleborg]]
*{{Bug|56118}} - testcase already present (even on subject). Was actually two different bugs (partly fixed), maybe rename to make the issue clearer. Needs version change. [[User:lemma|lemma]]
**version and title changed [[User:Grundleborg|Grundleborg]]
*{{Bug|55946}} - testcase already present (even on subject). Still present in trunk. Needs version change. [[User:lemma|lemma]]
** confirmed and version changed [[User:Grundleborg|Grundleborg]]
*{{Bug|37007}} - added a testcase and [testcase] tag [[User:Grundleborg|Grundleborg]]
*{{Bug|53885}} - Added an admittedly simple testcase. It might be disputable if this is actually a bug, a wish or deemed as correct behaviour. Needs version change. [[User:lemma|lemma]]
** see also {{Bug|47320}} - similar [[User:Grundleborg|Grundleborg]]
** testcase tag added and version changed. [[User:Grundleborg|Grundleborg]]
*{{Bug|57819}} - Old testcases no longer valid. Added a new testcase. Bug still present in trunk. [[User:lemma|lemma]]
**testcase tag added and version changed [[User:Grundleborg|Grundleborg]]
*{{Bug|57360}} - Some testcases seem to work on trunk, others not. name-anchors seem more likely to work than id-anchors. Needs version change [[User:lemma|lemma]]
**testcase tag added and version changed. [[User:Grundleborg|Grundleborg]]
*{{Bug|49441}} - test case uploaded [[User:Grundleborg|Grundleborg]]
*{{Bug|50688}} - testcase copy uploaded. [[User:Grundleborg|Grundleborg]]
*{{Bug|57485}} - added a simpler testcase (already labeled). still present in trunk. Needs version change. [[User:lemma|lemma]]
**version changed [[User:Grundleborg|Grundleborg]]
*{{Bug|57995}} - readded testcase (already labeled). still present in trunk. Needs version change. [[User:lemma|lemma]]
**version changed [[User:Grundleborg|Grundleborg]]
*{{Bug|51202}} - test case still fails. added testcase tag [[User:Grundleborg|Grundleborg]]
*{{Bug|59492}} - css test suite case; last test fails [[User:Blauzahl|Blauzahl]]
*{{Bug|58111}} - testcase already there (needs label), still reproducible in trunk. Needs version change. [[User:lemma|lemma]]
**testcase tag added, version changed. [[User:Grundleborg|Grundleborg]]
*{{Bug|58432}} - added new testcase, still reproducible in trunk. [[User:lemma|lemma]]
*{{Bug|60867}} - uploaded testcase as attachment. Still present in trunk. [[User:Grundleborg|Grundleborg]]
*{{Bug|62072}} - testcase was already there (needs label), still present in trunk. [[User:lemma|lemma]]
**testcase tag added [[User:Grundleborg|Grundleborg]]
*{{Bug|63048}} - testcase was already there (needs label), still present in trunk. Needs version change. [[User:lemma|lemma]]
**testcase tag added [[User:Grundleborg|Grundleborg]]
*{{Bug|61176}} - testcase tag added. still in trunk. [[User:Grundleborg|Grundleborg]]
*{{Bug|61417}} - testcase tag added. still present in trunk [[User:Grundleborg|Grundleborg]]
*{{Bug|64705}} - testcase tag added, still present in trunk. [[User:Grundleborg|Grundleborg]]
*{{Bug|65722}} - testcase tag added, still present in trunk. [[User:Grundleborg|Grundleborg]]
*{{Bug|66781}} - new testcase added by lemma.
**testcase tag added, version changed [[User:Grundleborg|Grundleborg]]
*{{Bug|67353}} - new testcase added by annma.
**testcase tag added, version changed [[User:Grundleborg|Grundleborg]]
*{{Bug|83916}} - testcase already there (needs label), could probably be made a wish. [[User:lemma|lemma]]
**testcase tag added [[User:Grundleborg|Grundleborg]]
*{{Bug|84217}} - testcase (needs label), confirmed, could probably be made a wish. [[User:lemma|lemma]]
**testcase tag added, version updated. [[User:Grundleborg|Grundleborg]]
*{{Bug|83755}} - testcase (already has label), confirmed. Needs version. [[User:lemma|lemma]]
**version changed. [[User:Grundleborg|Grundleborg]]
*{{Bug|82930}} - testcase (needs label), confirmed. [[User:lemma|lemma]]
** marked as site issue, as there is no actual testcase here. [[User:Grundleborg|Grundleborg]]
*{{Bug|83326}} - testcase (needs label), confirmed, needs recheck if I actually understood the problem. Needs version. [[User:lemma|lemma]]
**looks OK to me. testcase tag added, version changed. [[User:Grundleborg|Grundleborg]]
*{{Bug|83880}} - testcase (already has label), still minor issues. [[User:lemma|lemma]]
**testcase tag added. [[User:Grundleborg|Grundleborg]]
*{{Bug|92885}} - testcase already present (needs label), confirmed.
**testcase tag added. confirmed on trunk. [[User:Grundleborg|Grundleborg]]
*{{Bug|92699}} - testcase added, needs label, confirmed [[User:kirun|kirun]]
**version changed and testcase tag added [[User:Grundleborg|Grundleborg]]
*{{Bug|93747}} - existing testcase (attached), needs label, confirmed [[User:kirun|kirun]]
**testcase tag added. [[User:Grundleborg|Grundleborg]]
*{{Bug|84498}} - testcase already present, confirmed. [[User:lemma|lemma]]
*{{Bug|85774}} - testcase already present (needs label), confirmed. [[User:lemma|lemma]]
** needs a minimal testcase not tied to a separate site. [[User:Grundleborg|Grundleborg]]
*{{Bug|68391}} - testcase already present, confirmed. annma
**added testcase tag, version changed. [[User:Grundleborg|Grundleborg]]
*{{Bug|76489}} - testcase already present, confirmed, suggested patch already attached, matt__
**version set. [[User:Grundleborg|Grundleborg]]
*{{Bug|76676}} - testcase already present, confirmed. matt__
**added confirmed comment, and version set. [[User:Grundleborg|Grundleborg]]
*{{Bug|77833}} - testcase already present. animated gif no longer animates at all, if you save the file and then open it in iceweasel it works fine. matt__
**added comment and testcase tag. [[User:Grundleborg|Grundleborg]]
*{{Bug|74569}} - 2 testcases already present and marked as [testcase]. 1st worked ok for me but 2nd partially reproduced problem. [[User:Njg234908|Njg234908]]
**updated version. [[User:Grundleborg|Grundleborg]]
*{{Bug|68429}} - added testcase, confirmed but low priority. annma
**added testcase tag. [[User:Grundleborg|Grundleborg]]
*{{Bug|87094}} - Bug (with testcase) reproduced on trunk. [[User:Finex|FiNeX]]
**version set. [[User:Grundleborg|Grundleborg]]
*{{Bug|78331}} - test case already given. matt__
**confirmed. [[User:Grundleborg|Grundleborg]]
*{{Bug|78725}} - test case already given. matt__
**needs more investigation. [[User:Grundleborg|Grundleborg]]
*{{Bug|68876}} - test case already given, not fixed in Konqueror 4.0.68. annma
**version set. [[User:Grundleborg|Grundleborg]]
*{{Bug|69091}} - test case already given, not fixed in Konqueror 4.0.68. annma
**version set. [[User:Grundleborg|Grundleborg]]
*{{Bug|120458}} - Testcase already present, confirmed in trunk. [[User:krop|krop]]
**confirmed. [[User:Grundleborg|Grundleborg]]
** No testcase present, however... [[User:Grundleborg|Grundleborg]]
*{{Bug|89251}} - Bug confirmed on trunk (with testcase). [[User:Finex|FiNeX]]
*{{Bug|89607}} - Bug confirmed (with testcase). [[User:Finex|FiNeX]]
** testcase tag added. [[User:Grundleborg|Grundleborg]]
*{{Bug|74607}} - testcase added. needs to be marked [testcase] [[User:Njg234908|Njg234908]]
**testcase tag added [[User:Grundleborg|Grundleborg]]
*{{Bug|75422}} - already has testcase. confirmed. Possible patch also contained in bug report. needs to be marked [testcase] [[User:Njg234908|Njg234908]]
**testcase tag added, version set. [[User:Grundleborg|Grundleborg]]
*{{Bug|87094}} - already has testcase. confirmed. needs version attached. [[User:lemma|lemma]]
**confirmed. [[User:Grundleborg|Grundleborg]]
* {{Bug|120644}} Testcase already present, the bug still exists in trunk. [[User:krop|krop]]
**testcase tag added. [[User:Grundleborg|Grundleborg]]
*{{Bug|76122}} - already has testcase, confirmed in 4.0.3. needs marking [testcase] [[User:Njg234908|Njg234908]]
**testcase tag added, version set. [[User:Grundleborg|Grundleborg]]
*{{Bug|104977}} - Found different JS problems on the webpage, them are different from the problems reported. Confirmed the problem on the testcase. [[User:Finex|FiNeX]]
*{{Bug|105505}} - Bug confirmed on the testcase. [[User:Finex|FiNeX]]
*{{Bug|94867}} - Testcases are there on the linked page - [[User:JLP|JLP]]
*{{Bug|105776}} - Bug partially confirmed. Added the testcase. [[User:Finex|FiNeX]]
*{{Bug|93013}} - testcase is any frames site, added new suggestion, confirmed [[User:kirun|kirun]]
** needs a proper testcase. [[User:Grundleborg|Grundleborg]]
*{{Bug|90602}} - Testcase valid on trunk. [[User:Finex|FiNeX]]
*{{Bug|92142}} - Testcase confirmed. [[User:Finex|FiNeX]]
** testcase tag added. [[User:Grundleborg|Grundleborg]]
*{{Bug|92228}} - Testcase confirmed. [[User:Finex|FiNeX]]
*{{Bug|113776}} - Testcase confirmed. [[User:Finex|FiNeX]]
** testcase tag added. [[User:Grundleborg|Grundleborg]]
*{{Bug|114615}} - Testcase added. [[User:Finex|FiNeX]]
** testcase tag added. [[User:Grundleborg|Grundleborg]]
*{{Bug|114941}} - Testcase confirmed. [[User:Finex|FiNeX]]
*{{Bug|96935}} - Testcase confirmed. [[User:Gtoth|sim0nx]]
** no actual testcase here. [[User:Grundleborg|Grundleborg]]
*{{Bug|115325}} - Testcase confirmed. [[User:Finex|FiNeX]]#
** testcase tag added. [[User:Grundleborg|Grundleborg]]
* {{Bug|120644}} Testcase already present, the bug still exists in trunk. [[User:krop|krop]]
*{{Bug|106663}} - Testcase confirmed. Moreover a new problem is introduced on trunk. [[User:Finex|FiNeX]]
** bug confirmed. [[User:Grundleborg|Grundleborg]]
*{{Bug|106674}} - SVG rendering problem. Testcase confirmed. [[User:Finex|FiNeX]]
** testcase tag added. [[User:Grundleborg|Grundleborg]]
*{{Bug|106749}} - Problem while rendering a textarea on a form. Testcase added. [[User:Finex|FiNeX]]
** testcase tag added. [[User:Grundleborg|Grundleborg]]
*{{Bug|106785}} - Problem iterating CSS rules from JS. Two testcase added. [[User:Finex|FiNeX]]
** testcase tag added. [[User:Grundleborg|Grundleborg]]
*{{Bug|106806}} - Set/get CSS attribute from Javascript. With testcase. [[User:Finex|FiNeX]]
** testcase tag added. [[User:Grundleborg|Grundleborg]]
*{{Bug|96312}} - The bug is about websites being marked as secured (lock icon closed) but the site not or only partially being secure. The bug is still present in 3.5.9, but secured websites aren't displayed at all as being secure or not in konqi, at least not for me. [[User:Gtoth|sim0nx]]
** no testcase here. bug should be moved to appropriate section. [[User:Grundleborg|Grundleborg]]
*{{Bug|107275}} - Javascript issue with testcase. What is the correct behavior? [[User:Finex|FiNeX]]
** testcase tag added. [[User:Grundleborg|Grundleborg]]
*{{Bug|107336}} - Table rendering problem. Testcase confirmed. [[User:Finex|FiNeX]]
*{{Bug|107463}} - Table rendering problem with Javascript. Testcase added. [[User:Finex|FiNeX]]
*<s>{{Bug|107705}} - Iframe rendering problem. Testcase added. [[User:Finex|FiNeX]]</s>
** bug has been closed. [[User:Grundleborg|Grundleborg]]
*{{Bug|107862}} - GET/POST header refresh problem. Testcase added [[User:Finex|FiNeX]]
*{{Bug|117626}} - CSS rendering problem. Testcase confirmed. [[User:Finex|FiNeX]]
*{{Bug|93235}} - On trunk scaling down the font size reduce the line-height. [[User:Finex|FiNeX]]
** needs looking at with trunk as zooming has changed. [[User:Grundleborg|Grundleborg]]
*{{Bug|95307}} - Testcase is there, added to summary. Bug still valid in Konqueror 4. - [[User:JLP|JLP]]
*{{Bug|115293}} - Added testcase. Bug reproducible. [[User:Finex|FiNeX]]
*{{Bug|113907}} - Added testcase. Bug reproducible: selecting text on a fixed textarea don't make the textarea scroll. [[User:Finex|FiNeX]]
*{{Bug|70350}} - existing testcase. CSS stylesheets. still bug [[User:Blauzahl|Blauzahl]]
*{{Bug|85609}} - testcase existing and labeled. Still reproducible. [[User:lemma|lemma]]
*{{Bug|118933}} - JS problem with proxyRender. Testcase reproduced on trunk. [[User:Finex|FiNeX]]
*{{Bug|81739}} - test case already present [[User:Grundleborg|Grundleborg]]
** test case tag already present [[User:Grundleborg|Grundleborg]]
*{{Bug|81875}} - test case added. broken in trunk and 3.5.9. [[User:Grundleborg|Grundleborg]]
*{{Bug|82014}} - test case and tag added. [[User:Grundleborg|Grundleborg]]
**still broken in 3.5.9 and trunk. [[User:Grundleborg|Grundleborg]]
*{{Bug|92183}} - Created a testcase and attached the label. The misbehaviour is not related to JavaScript but to incorrectly nested form/table tags. Might qualify as invalid, however other browsers render this correctly. [[User:lemma|lemma]]
** <s>The webpage is not accessible anymore. What should we do with this bug? [[User:Finex|FiNeX]]</s>
** <s>not sure I understand coolo's comment. Is it enough to explain the bug, or not? can someone else take a look please. [[User:Grundleborg|Grundleborg]]</s>
*{{Bug|118886}} - Sometimes set focus on frames doesn't work. Testcase confirmed (but I cannot reproduce anymore). [[User:Finex|FiNeX]]
** confirmed. [[User:Grundleborg|Grundleborg]]
*{{Bug|89373}} - testcase tag added. still buggy in trunk and 3.5.9. [[User:Grundleborg|Grundleborg]]
*{{Bug|106386}} - still present in 3.5.9 and partially fixed in trunk. [[User:Grundleborg|Grundleborg]]
*{{Bug|89999}} - Need some more infos. [[User:Finex|FiNeX]]
** According to the reporter the testcase needs to be modified a little [[User:lemma|lemma]]
** have requested the test-case maker to update it if possible. [[User:Grundleborg|Grundleborg]]
** oh, nice, they did. this is verified and should get moved to the testcase secion now

==Bugs with step-by-step instructions==
If you have provided step by step instructions on how to reproduce a bug, please list the bug here.

*{{Bug|80067}} - For reproduce the bug go to google.com, type some text on the search field, press "TAB" and "SPACE" quickly. The search will not be started. [[User:Finex|Finex]]
*{{Bug|51649}} - reproduced using instructions. [[User:Grundleborg|Grundleborg]]
*{{Bug|61710}} - instructions to reproduce. Would be good if someone could figure out how to make a testcase out of it. [[User:Grundleborg|Grundleborg]]
*{{Bug|65528}} - instructions tag added, since easy steps to reproduce. [[User:Grundleborg|Grundleborg]]
*{{Bug|105846}} - Bug confirmed on trunk. [[User:Finex|FiNeX]]
*{{Bug|106407}} - Bug confirmed on trunk. [[User:Finex|FiNeX]]
*{{Bug|106469}} - The flash applet is loaded right (using a valid user-agent), but the image above is not refreshed clicking on the "NEXT" button. [[User:Finex|FiNeX]]
*{{Bug|115182}} - The preload seems ok. But the page on the right is not rendered correctly when you click directly on pages. [[User:Finex|FiNeX]]
*{{Bug|97167}} - Added new url to test the bug on...still present in trunk [[User:Gtoth|sim0nx]]
*{{Bug|107209}} - Bug reproduced in trunk. Tabs opened with JS doesn't activate konqueror tab actions. [[User:Finex|FiNeX]]
*{{Bug|108077}} - Bottom frame is not rendered when the website is loaded. [[User:Finex|FiNeX]]
*{{Bug|117569}} - Google analytics is still not well rendered. [[User:Finex|FiNeX]]
*{{Bug|118104}} - konqueror trunk doesn't crash on a alert message in a specific webpage. [[User:Finex|FiNeX]]
*{{Bug|118406}} - Still rendering problems on the webpage (differents from the initial report). Added a screenshot. [[User:Finex|FiNeX]]
*{{Bug|107321}} - Bug reproduced on trunk. [[User:Finex|FiNeX]]
*{{Bug|106748}} - The page now is rendered better. I wasn't able to reproduce the rendering problems reported initially. Anyway the page is not perfect, there are still some rendering problem, probably related to the JS. [[User:Finex|FiNeX]]
*{{Bug|118459}} - Printing problem confirmed on specific page. [[User:Finex|FiNeX]]
*{{Bug|118471}} - The page on the example is completely broken. Anyway the website has been (fortunatly) updated. [[User:Finex|FiNeX]]
*{{Bug|118842}} - Bug confirmed even on trunk (search on lufthansa website doesn't work) [[User:Finex|FiNeX]]
*{{Bug|118890}} - Ford website car builder doesn't work. [[User:Finex|FiNeX]]
*{{Bug|119824}} - Resolved in trunk [[User:krop|krop]]
** Actually I can still reproduce this bug. Just be sure not to move the mouse while entering the page (eg. use caret mode). IMO minor bug [[User:lemma|lemma]]
* {{Bug|122696}} - Resolved in konq4 [[User:krop|krop]]
** Not solved [[User:finex|FiNeX]]
*{{Bug|105723}} - Reproduced on 3.5.9 and trunk. [[User:Finex|FiNeX]]

*{{Bug|77924}} - after discussion on irc we decided this was the right place for this bug. matt__
** reporter says it is not actually fixed yet. [[User:Grundleborg|Grundleborg]]

==Bugs no longer present in 4.x==
If a bug is reported against a version of KDE before 4.0, but the bug can no longer be reproduced in KDE 4.x, then it should be listed here. Please '''do not''' close the bug. The Konqueror developers would like to check each one before they are closed.

*<s>{{Bug|160082}} - works in 4.0.2, reported in 3.5.9 with '''backtrace''' [[User:Blauzahl|Blauzahl]] 03:31, 4 April 2008 (CEST)</s>
*<s>{{Bug|52801}} - Performance improved. Not valid on 4.0.3 [[User:Finex|FiNeX]]</s>
*<s>{{Bug|120315}} - Can't reproduce in trunk. [[User:krop|krop]]</s>
**<s>XHR/Qt crap, duping it with #124910, looks like this one stays, sorry[[User:Blauzahl|Blauzahl]]</s>
** has been closed as a dupe. [[User:Grundleborg|Grundleborg]]
*<s>{{Bug|87178}} - The website now is rendered quite well because there are no layers (the bug was about "layers" on webpages). [[User:Finex|FiNeX]]</s> thanks carewolf!

*<s>{{Bug|78046}} - test case appears to be working in trunk. matt__
** requires java to check. [[User:Grundleborg|Grundleborg]]</s>
*<s>{{Bug|94755}} - messages do show in Konqueror 4 (svn r794088) and probably also in 3.5.9 - [[User:JLP|JLP]]</s>
** closed WORKSFORME. [[User:Grundleborg|Grundleborg]]
*{{Bug|106330}} - Fixed on trunk. Tried the testcase. The event is called on the onload() of animated gif. [[User:Finex|FiNeX]]
*{{Bug|106367}} - The website seems to be ok. The navigation is not slow. [[User:Finex|FiNeX]]
*<s>{{Bug|92186}} - The first website is no more valid. The second one is correct. [[User:Finex|FiNeX]]</s> closed by [[User:finex|FiNeX]]
*<s>{{Bug|114212}} - Cannot reproduce on KDE4. It has been fixed. [[User:Finex|FiNeX]]</s> closed by [[User:finex|FiNeX]]
*<s>{{Bug|114636}} - Cannot reproduce on KDE4. It has been fixed. [[User:Finex|FiNeX]]</s> closed by [[User:finex|FiNeX]]
*<s>{{Bug|115101}} - Cannot reproduce on KDE4. It has been fixed. [[User:Finex|FiNeX]]</s> closed by [[User:finex|FiNeX]]
*<s>{{Bug|115102}} - Cannot reproduce on KDE4. It has been fixed. [[User:Finex|FiNeX]]</s> closed by [[User:finex|FiNeX]]
*<s>{{Bug|115323}} - Fixed on both 3.5.8 and trunk. [[User:Finex|FiNeX]]</s> closed by [[User:finex|FiNeX]]
* <s>{{Bug|121224}} Testcase already present, bug resolved in trunk. [[User:krop|krop]]</s>
** appears fixed. Closed: WORKSFORME. [[User:Grundleborg|Grundleborg]]
* <s>{{Bug|121266}} Testcase already present, wish granted in trunk. [[User:krop|krop]]</s> closed by [[User:finex|FiNeX]]
*<s>{{Bug|97355}} - Fixed on both 3.5.9 and trunk. [[User:Gtoth|sim0nx]]</s> closed by [[User:finex|FiNeX]]
*<s>{{Bug|97621}} - Fixed on both 3.5.9 and trunk. [[User:Gtoth|sim0nx]]</s> closed by [[User:finex|FiNeX]]
*<s>{{Bug|107061}} - The webpage is rendered correctly. It was reported a CSS rendering problem. [[User:Finex|FiNeX]]</s>
** can't reproduce in trunk, so closed. Have a feeling it is still in 3.5.9, but not sure. [[User:Grundleborg|Grundleborg]]
*<s>{{Bug|122052}} - Testcase already present - The bug is resolved in konq4 [[User:krop|krop]]</s> closed by [[User:finex|FiNeX]]
*<s>{{Bug|107904}} - Cannot reproduce on trunk. [[User:Finex|FiNeX]]</s>
** Closed. [[User:Grundleborg|Grundleborg]]
*<s>{{Bug|108116}} - Konqueror load the website without using a lot of CPU. Maybe the website now is better, or maybe even konqueror is better. [[User:Finex|FiNeX]]</s>
** Closed. [[User:Grundleborg|Grundleborg]]
*<s>{{Bug|108156}} - The website is correctly rendered on trunk. [[User:Finex|FiNeX]]</s>
*<s>{{Bug|117776}} - Konqueror in trunk is rendering the table on the webpage correctly. [[User:Finex|FiNeX]]</s>
*<s>{{Bug|118190}} - The webpage pointed seems to be correctly rendered. [[User:Finex|FiNeX]]</s>
*{{Bug|118471}} - Cannot reproduce the rendering problem. The first example is correct, the second test address is unreachable. [[User:Finex|FiNeX]]
*<s>{{Bug|118646}} - Cannot reproduce the rendering problem on trunk. It has been reproduced on 4.0.3 instead. [[User:Finex|FiNeX]]</s>
** Closed. [[User:Grundleborg|Grundleborg]]
** can't reproduce with trunk or 3.5.9. [[User:Grundleborg|Grundleborg]]
*<s>{{Bug|118671}} - Bug fixed in KDE 3.5.8 and KDE 4. [[User:Finex|FiNeX]]</s>
*{{Bug|118860}} - Sites displayed correctly in UTF8 (with jap). [[User:Finex|FiNeX]]
*{{Bug|92274}} - <s>Website changed. Cannot reproduce the bug anymore. [[User:Finex|FiNeX]]</s>
**<s>requested a current example or testcase. [[User:Grundleborg|Grundleborg]]</s>
**gathered an old version using archive.org which seems to render correctly. [[User:lemma|lemma]]
** CLOSED. [[User:Grundleborg|Grundleborg]]

==Bugs no longer present in 4.x, but still present in 3.5.9==
If a bug is reported against a version of KDE before 4.0, the bug is no longer present in 4.x but is still reproducible in 3.5.9 then it goes here. Bugs in this list have already been closed with their version set to 3.5 and the resolution set to LATER. Like that the developers should have no trouble finding bugs that qualify for backporting.
*{{Bug|79207}} - <s>cannot reproduce in svn trunk, the select box is working as expected [[User:Finex|FiNeX]] [[User:lemma|lemma]]</s>
** Still present in 3.5.9 (minor) [[User:lemma|lemma]]
** backport, form, minor [[User:lemma|lemma]]
*{{Bug|54985}} - <s>works in trunk, both testcases mentioned work fine here [[User:lemma|lemma]]</s>
** Still present in 3.5.9 (major) [[User:lemma|lemma]]
** backport, printing [[User:lemma|lemma]]
*{{Bug|55260}} - <s>works in trunk, simple testcase added to confirm. [[User:lemma|lemma]]</s>
** Still present in 3.5.9 [[User:lemma|lemma]]
** backport, table border [[User:lemma|lemma]]
*{{Bug|56354}} - <s>testcase works in trunk. [[User:lemma|lemma]]</s>
** Still present in 3.5.9 (minor) [[User:lemma|lemma]]
** backport, jpeg exif [[User:lemma|lemma]]
*{{Bug|48341}} - <s>seems to be fixed from the test-case included [[User:Grundleborg|Grundleborg]] [[User:lemma|lemma]]</s>
** Still present in 3.5.9 [[User:lemma|lemma]]
** backport, tab-index [[User:lemma|lemma]]
*{{Bug|49523}} - <s>included test case works fine [[User:Grundleborg|Grundleborg]]</s>
**Still an issue in 3.5.9 [[User:Grundleborg|Grundleborg]]
**backport, encoding russian [[User:lemma|lemma]]
*{{Bug|63112}} - <s>seemed to be more of a wishlist item, however fixed in trunk. [[User:lemma|lemma]]</s>
** still in 3.5.9 [[User:lemma|lemma]]
** backport, png minor [[User:lemma|lemma]]
*{{Bug|64635}} - <s>testcase tag added, can't reproduce in trunk. [[User:Grundleborg|Grundleborg]]</s>
** still in 3.5.9 [[User:lemma|lemma]]
** backport, javascript [[User:lemma|lemma]]
*{{Bug|56188}} - <s>testcase works in trunk. [[User:lemma|lemma]]</s>
** still in 3.5.9 [[User:lemma|lemma]]
** backport, form corruption major [[User:lemma|lemma]]
*{{Bug|66583}} - <s>can't reproduce in trunk. [[User:Grundleborg|Grundleborg]]</s>
**Bug still present in 3.5.9 [[User:Grundleborg|Grundleborg]]
**backport, text selection [[User:lemma|lemma]]
*{{Bug|82737}} - <s>testcase works in trunk. [[User:lemma|lemma]]</s>
** Still present in 3.5.9. [[User:lemma|lemma]]
** backport, iframe background [[User:lemma|lemma]]
*{{Bug|84512}} - <s>testcase works in trunk, probably due to Qt4. [[User:lemma|lemma]]</s>
** still in 3.5.9 [[User:lemma|lemma]]
** backport, image rendering [[User:lemma|lemma]]
*{{Bug|87562}} - <s>Cannot reproduce on Konqueror 4 because the "enlarge" and "shrink" actions haven't a button. [[User:Finex|FiNeX]]</s>
** still reproductible in 3.5.9 [[User:lemma|lemma]]
** actually they do have buttons for me but the behaviour has changed (see the HTML toolbar). However it's fixed for trunk as the maximize-button no longer gets disabled. [[User:lemma|lemma]]
** backport, zooming user-interface [[User:lemma|lemma]]
*{{Bug|93078}} - <s>Can't reproduce, new tests added [[User:kirun|kirun]]</s>
** I can still reproduce this partly in 3.5.9.
** backport tooltips [[User:lemma|lemma]]
*{{Bug|119326}} - <s>Resolved in trunk [[User:krop|krop]]</s>
** This bug is still present in 3.5.9. [[User:lemma|lemma]]
** backport, embedded text-editor [[User:lemma|lemma]]
*{{Bug|74709}} - <s>can't reproduce in 4.0.3 [[User:Njg234908|Njg234908]]</s>
** still present in 3.5.9. [[User:lemma|lemma]]
** backport, css menu [[User:lemma|lemma]]
*{{Bug|105327}} - <s>The bug seems solved on 4.0.3. It needs to be verified. [[User:Finex|FiNeX]]</s>
** Still present in 3.5.9. [[User:lemma|lemma]]
** backport, embedded midi looping [[User:lemma|lemma]]
*{{Bug|77966}} - <s>testcase works in trunk. matt__</s>
** still reproducible in 3.5.9 [[User:lemma|lemma]]
** backport, tesco.com, javascript shopping-cart [[User:lemma|lemma]]
*<s>{{Bug|120124}} - Resolved in trunk [[User:krop|krop]]</s>
**still in 3.5.9 but fixed in trunk. Closed. [[User:Grundleborg|Grundleborg]]
** backport, gis javascript [[User:lemma|lemma]]
*<s>{{Bug|117949}} - fixed in trunk but still in 3.5.9. [[User:Edulix|Edulix]]</s>
** backport, tabbing user-interface [[User:lemma|lemma]]
*<s>{{Bug|82420}} - fixed in trunk but still in 3.5.9. [[User:Grundleborg|Grundleborg]]</s>
** closed as later, as could be backported. [[User:Grundleborg|Grundleborg]]
*<s>{{Bug|81187}} - fixed in trunk. [[User:Grundleborg|Grundleborg]]</s>
**Still present in 3.5.9 [[User:Grundleborg|Grundleborg]]
**closed as LATER, as could be backported. [[User:Grundleborg|Grundleborg]]
*<s>{{Bug|114386}} - Cannot reproduce on KDE4. It has been fixed. [[User:Finex|FiNeX]]</s>
** fixed in trunk, still present in 3.5.9. Closed. [[User:Grundleborg|Grundleborg]]

==Bugs no longer present in 3.5.9 and 4.x==
If a bug is reported against a version of KDE before 4.0, but the bug is no longer present in 3.5.9 and 4.x, then it should be listed here. Please '''do not''' close the bug. The Konqueror developers would like to check each one before they are closed.
*<s>{{Bug|31575}} - seems to be fixed in svn trunk [[User:Grundleborg|Grundleborg]] [[User:lemma|lemma]]</s>
*<s>{{Bug|55912}} - testcase works in 3.5.9 and trunk. [[User:lemma|lemma]]</s>
*<s>{{Bug|39703}} - can't reproduce in trunk [[User:Grundleborg|Grundleborg]] works in 3.5.9 as well [[User:lemma|lemma]]</s>
*<s>{{Bug|63139}} - testcase works in trunk but exposes another possible bug which I'm going to file separately. [[User:lemma|lemma]]</s>
** Set to remind in case problems occur with a smaller CPU than mine [[User:lemma|lemma]]
*<s>{{Bug|62481}} - seems to work fine in trunk. new testcase to confirm added (needs label?). [[User:lemma|lemma]] works in 3.5.9 as well [[User:lemma|lemma]]</s>
*<s>{{Bug|64382}} - test case tag added, can't reproduce in trunk. [[User:Grundleborg|Grundleborg]] can't reproduce in 3.5.9 [[User:lemma|lemma]]</s>
*<s>{{Bug|92685}} - bug asks for wrapping, testcase now makes scrollbar which seems OK [[User:kirun|kirun]] wrapping in 3.5.9, so I consider this fixed [[User:lemma|lemma]]</s>
*<s>{{Bug|77454}} - seems to be fixed (e.g. 'annoying' behaviour gone!). matt__</s>
**<s>works in 3.5.9 as well [[User:lemma|lemma]]</s>
*<s>{{Bug|74352}} - unable to reproduce in 4.0.3 [[User:Njg234908|Njg234908]]</s>
*<s>{{Bug|74471}} - unable to reproduce in 4.0.3 [[User:Njg234908|Njg234908]]</s>
**<s>works in 3.5.9 as well [[User:lemma|lemma]]</s>
*<s>{{Bug|86794}} - Bug fixed (on both KDE3.5.8 and trunk) but the report was left open. It should be closed. [[User:Finex|FiNeX]]</s>
*<s>{{Bug|86727}} - Not reproducible on trunk (testcase included). [[User:Finex|FiNeX]]</s>
**<s>works in 3.5.9 as well [[User:lemma|lemma]]</s>
*<s>{{Bug|68574}} - testcase appears to be working in trunk: no difference with Firefox for ex. annma.</s>
**<s>Working on 3.5.9 as well. [[User:lemma|lemma]]</s>
*<s>{{Bug|80754}} - added a testcase. seems to be fixed in trunk though. [[User:Grundleborg|Grundleborg]]</s>
**<s>also working in 3.5.9. [[User:lemma|lemma]]</s>
*<s>{{Bug|119721}} - Resolved in trunk [[User:krop|krop]]</s>
**<s>also working in 3.5.9. [[User:lemma|lemma]]</s>
*<s>{{Bug|88801}} - Cannot reproduce on trunk. [[User:Finex|FiNeX]]</s>
**<s>also working in 3.5.9. [[User:lemma|lemma]]</s>
*<s>{{Bug|88851}} - Cannot reproduce. Bug fixed on both KDE 3.5 and trunk. [[User:Finex|FiNeX]]</s>
*<s>{{Bug|89231}} - Bug not reproducible on trunk. [[User:Finex|FiNeX]]</s>
**<s>also working in 3.5.9. [[User:lemma|lemma]]</s>
*<s>{{Bug|74877}} - can't reproduce in 4.0.3 [[User:Njg234908|Njg234908]]</s>
**<s>also working in 3.5.9. [[User:lemma|lemma]]</s> REMIND
*<s>{{Bug|87150}} - Website address changed. Tested the new (?) address (http://europa.eu/index_fr.htm) which is working. [[User:Finex|FiNeX]]</s>
**<s>Recovered the old page from archive.org and attached that address. Works in 3.5.9 as well as trunk. [[User:lemma|lemma]]</s>
* <s> {{Bug|69646}} - popup menu disabled after http request dispatch closed with worksforme (it worked for last commenter, and if I understand them correctly, works fine now) confirmed by fredrikh</s> [[User:Blauzahl|Blauzahl]]
* <s> {{Bug|160268}} - nspluginviewer crash under 3.5.8 not specific report anyway</s> fredrikh agrees. Great pathological website though: www.canal13.cl [[User:Blauzahl|Blauzahl]]
*<s>{{Bug|160385}} - Fixed in 4.02</s>
**<s>this fix has already been backported. [[User:lemma|lemma]]</s>
*<s>{{Bug|105358}} - The page is correctly rendered. [[User:Finex|FiNeX]]</s>
**<s>Fixed for 3.5.9 as well [[User:lemma|lemma]]</s>
*<s>{{Bug|95274}} - either this is fixed in 3.5.9 and trunk, or my test-case is invalid. Please can someone check the testcase is valid before closing this one. [[User:Grundleborg|Grundleborg]]</s>
** Closed. [[User:Grundleborg|Grundleborg]]
* <s>{{Bug|121665}} - Testcase added - The bug is resolved in konq4 [[User:krop|krop]]</s>
** <s>also fixed in 3.5.9 [[User:Grundleborg|Grundleborg]] </s>
*<s>{{Bug|86938}} - added new testcase (needs label). Seems to be fixed in trunk. [[User:lemma|lemma]]</s>
** fixed in trunk and 3.5.9. Closed. [[User:Grundleborg|Grundleborg]]
*<s>{{Bug|95028}} - No crash here. - [[User:JLP|JLP]]</s>
** can't reproduce in trunk or 3.5.9. Closing. [[User:Grundleborg|Grundleborg]]
*<s>{{Bug|118761}} - The bug seems fixed. But I'm waiting for an answer for confirmation. [[User:Finex|FiNeX]]
** The bug is about login problems on plesk7. Logging in works in the oldest version of plesk around which is 7.5 reloaded. Maybe we should consider closing this bug. [[User:lemma|lemma]]
** You're right. I close it now. [[User:Finex|FiNeX]]</s>
*<s>{{Bug|114828}} - Konqueror now doesn't use lot of CPU. The bug is probably fixed. [[User:Finex|FiNeX]]</s>
** WORKSFORME in trunk and 3.5.9 [[User:Grundleborg|Grundleborg]]

==Bugs to be marked as RESOLVED==
Bugs filed against KDE 4 (ie, only very recent ones) that can no longer be reproduced should be listed here. Bugs filed against earlier versions of KDE that can no longer be reproduced should be listed in the section above.
*<s>{{Bug|159325}} - Seems to be OK with kdelibs: r793701, kdebase: r793720 - [[User:JLP|JLP]]</s> REPORT CLOSED [[User:Grundleborg|Grundleborg]]

==Bugs to be marked as INVALID==
Bugs which are no longer valid go here. A link to the bug and why it qualifies as invalid should be provided.

Some examples of when a bug should be closed as INVALID:
*The reported behavior is not a bug
*The bug is completely unrelated to KDE

This list is not exhaustive. If you feel a bug is invalid for any other reason, be sure to list it here, mentioning why you think it is invalid.

*<s>{{Bug|59815}} - Closed with REMIND per SadEagle's instructions [[User:Blauzahl|Blauzahl]]</s>
*<s>{{Bug|85783}} - testcase renders the same in 3.5.9, trunk, FF2, IE6/7, probably an error in the page. [[User:lemma|lemma]]</s>
**I agree with lemma. This bug is clealy an issue with the web site, not with konqueror. (just look at the source of the test-case to see why!) [[User:Grundleborg|Grundleborg]]
**Closed INVALID as confirmed by several people. [[User:lemma|lemma]]
*<s>{{Bug|87357}} - Bug not reproducible: website changed and no informations about the problem. [[User:Finex|FiNeX]]</s>
**closed as "remind" [[User:Grundleborg|Grundleborg]]
*<s>{{Bug|94675}} - Can't reproduce, it looks like site changed. New one appears to work fine. - [[User:JLP|JLP]]</s>
**closed as "remind". [[User:Grundleborg|Grundleborg]]
*<s>{{Bug|106281}} - Cannot reproduce the problem because the example testsite has been updated. [[User:Finex|FiNeX]]</s>
**closed as "remind" since the example site no longer works. [[User:Grundleborg|Grundleborg]]
*<s>{{Bug|114415}} - This is a WISH. Severity changed. [[User:Finex|FiNeX]]</s>
**I agree with Finex, and he's already changed it :). [[User:Grundleborg|Grundleborg]]
* <s>{{Bug|119944}} The bug cannot be reproduced (website was updated) [[User:krop|krop]]</s>
**reporter says site no longer triggers bug, so can not test it. closed as remind. [[User:Grundleborg|Grundleborg]]
* <s>{{Bug|81185}} The bug cannot be reproduced (website was updated). Closed as REMIND.</s> [[User:lemma|lemma]]
* <s>{{Bug|70365}} I really want to close this with REMIND. game controls under flash? flash stuff has changed so much.... [[User:Blauzahl|Blauzahl]]</s>
** Its closed now. [[User:Grundleborg|Grundleborg]]
* {{Bug|70855}} - <s>I should just close this as INVALID, as the site is long gone, but I like Brazilians, so maybe when I'm awake, I'll go back and use REMIND. I'm not doing this right now, because the 404 has an interesting rendering error which I should probably file a bug on if I knew what to call it. (blue line thick in konq, thin in ice weasel) http://www.in.gov.br/imprensa/index.html [[User:Blauzahl|Blauzahl]] </s>
** FIXED by Maksim. [[User:lemma|lemma]]
Opps! That's the wrong number, but I'll find it. :)
*<s>{{Bug|70447}} - This bug is related to mouse-hiding. As the actual bug-report is about the reporter not wanting his mouse pointer hidden this should be closed WONTFIX. The discussion about mouse hiding behaviour carries on after though. There's two follow-ups to mouse behaviour in 3.5.9 and current trunk which could be used instead:</s>
** <s>{{Bug|100274}} - behaviour on 3.5.9</s>
** <s>{{Bug|161532}} - behaviour on trunk</s>
*** These three have all been closed now. [[User:Grundleborg|Grundleborg]]

==Bugs to be marked as DUPLICATE==
Duplicates found should be placed here with a link to the bug which you think it is a duplicate of.

*<s> {{Bug|160268}} - Flash crash in 3.5.8 that was fixed in 3.5.9</s>[[User:Blauzahl|Blauzahl]]
*<s> {{Bug|74286}} - font face issue - needs a setup with no MS Fonts installed and fontconfig set to replace missing fonts... [[User:Njg234908|Njg234908]]
** Duplicate of {{Bug|57485}}, asked frederikh</s> [[User:lemma|lemma]]

* <s>{{Bug|122123}} - Duplicate of {{Bug|36912}} [[User:krop|krop]]</s>
* <s>{{Bug|117934}} - Maybe this is a dup of {{Bug|48302}}. [[User:Finex|FiNeX]]</s>
** agreed. done. [[User:Grundleborg|Grundleborg]]

==Bugs needing users with particular setups==
Bugs that require particular software or hardware that you don't have available should be listed here with a description of the non-standard requirement.
*{{Bug|55087}} - the reporter was using a PIII 500MHz, I'm on a Q6600. Moving the mouse as reported uses quite some CPU (>32% on 3.5.9, <27% on trunk) but someone with an older CPU should see if this is still an issue. [[User:lemma|lemma]]
*{{Bug|60652}} - needs someone with an ebay account to create a simple test-case so non-ebay account holders can reproduce the bug. [[User:Grundleborg|Grundleborg]]
**have tested on current ebay site using 4.0.3 and added instructions to reproduce. couldn't see an easy way of creating a standalone testcase. [[User:Njg234908|Njg234908]]
*{{Bug|77030}} - needs someone who can read hindi (Devanagari script) to check this one - possibly fixed in trunk. matt__
*{{Bug|77246}} - needs someone with a Yahoo! ID. matt__
** Testcase added, no Yahoo account needed now, needs marking as [testcase] [[User:Njg234908|Njg234908]]
*{{Bug|78210}} - needs someone with a gay.com account. matt__
*{{Bug|105538}} - Bug on BIDI rendering text. [[User:Finex|FiNeX]]
*{{Bug|106244}} - Need to be tested by someone which has an account to the website. [[User:Finex|FiNeX]]
*{{Bug|113811}} - Need testing by someone with an account on dresdner-privat.de. [[User:Finex|FiNeX]]
*{{Bug|114849}} - Need to be tested on particular hours/days. [[User:Finex|FiNeX]]
*{{Bug|106742}} - The problem seems being reproducible even on KDE4. Need to be tested by someone with a blogger.com account. [[User:Finex|FiNeX]]
**Tested and unable to reproduce in 4.0.3 here. [[User:Njg234908|Njg234908]]
*{{Bug|90035}} - Performance problem not present in trunk. [[User:Finex|FiNeX]]
** I guess someone with a slow CPU (orig. reporter had around 1GHz) should recheck this on 3.5.9. [[User:lemma|lemma]]
*{{Bug|96296}} - Website which make konqueror crash is no more reachable. There are no infos and testcases. [[User:Gtoth|sim0nx]]
** This one also needs someone with FreeBSD to test. [[User:lemma|lemma]]
*{{Bug|105959}} - Needs realplayer plugin. [[User:Grundleborg|Grundleborg]]

==Non english locales==
Bugs requiring non-English locales should be listed here, along with the locale they require.
*{{Bug|79356}} - need testing with JP locale. [[User:Finex|FiNeX]]
*{{Bug|52685}} - need testing with JP locale. [[User:Finex|FiNeX]]
*{{Bug|86938}} - Need testing with charset different from ISO-8859-1. [[User:Finex|FiNeX]]
*{{Bug|89484}} - Problem confirmed on Thai charset (testcase included). [[User:Finex|FiNeX]]
*{{Bug|81628}} - needs someone who understands about arabic/RTL text etc... [[User:Grundleborg|Grundleborg]]

{{:Contribute/Bugsquad/BugDays/06APR08/Bugs_needing_attention_from_Konqueror_developers}}

==High Profile==
*{{Bug|93648}} - Affects Hotmail. Related to javascript. Probably WISH as it relates to the implementation of the non-standard window.showModalDialog(). testcase added to the bug. [http://developer.mozilla.org/en/docs/DOM:window.showModalDialog Testcase] [[User:kirun|kirun]]

==Needs more information==

!! DONE !!

*{{Bug|55870}} - <s>The URL (k-state) given by the original reporter is offline. According to archive.org the menu consisted of an image map which works flawless in 3.5.9 and trunk. The second URL (mplayer) looks the same in Firefox. It seems this problem is not reproducible. [[User:lemma|lemma]]</s>
** The pages mentioned have been confirmed to work, so I closed this one. [[User:lemma|lemma]]
*<s>{{Bug|86747}} - Website which make konqueror crash is no more reachable. There are no infos and testcases. [[User:Finex|FiNeX]]</s>
** teve once had a testcase for this. I asked him if it was still available. [[User:lemma|lemma]]
** closed as REMIND. [[User:Grundleborg|Grundleborg]]
*<s>{{Bug|106391}} - Example webpage not reachable. Asked a testcase. [[User:Finex|FiNeX]]</s>
** closed REMIND. [[User:Grundleborg|Grundleborg]]
*<s>{{Bug|97765}} - Website which make konqueror crash is no more reachable. There are no infos and testcases. [[User:Gtoth|sim0nx]]</s>
** closed REMIND [[User:Grundleborg|Grundleborg]]
*<s>{{Bug|97077}} - Testcase described but test website no longer reachable. I've asked the reporter to verify the bug and if possible upload the files which baused the problem. [[User:Gtoth|sim0nx]]</s>
** closed REMIND. [[User:Grundleborg|Grundleborg]]

==Bugs awaiting feedback==

!! DONE !!

'''NB. Feedback should only be requested for bugs if you have tried and failed to reproduce them or if the report contains insufficient information to try and reproduce the bug. Requesting feedback for a bug should be seen as a ''last resort'' only.'''

Bugs for which feedback has been requested, which should be revisited in 30 days to see if there's any response. Please list all bugs here for which feedback has been requested.

*<s>{{Bug|59698}} - I can't reproduce this from the old links given. teve could at one point. (nyt js popup bug) [[User:Blauzahl|Blauzahl]]</s>
**<s>No feedback: REMIND [[User:lemma|lemma]]</s>
*<s>{{Bug|90308}} - Need feedback. [[User:Finex|FiNeX]]</s>
**<s>No feedback: REMIND [[User:lemma|lemma]]</s>
*<s>{{Bug|105123}} - It seems that the bug is no more applicable because the website has changed. [[User:Finex|FiNeX]]</s>
**asked if this can still be reproduced. Will give 30 days, then close. [[User:Grundleborg|Grundleborg]]
** has reportedly been fixed on trunk. depending on if it also works in 3.5.9 we have to change the resolution (already closed). [[User:lemma|lemma]]
*<s>{{Bug|121668}} - Need to be marked as invalid [[User:krop|krop]]</s>
**<s>can't get that site to load either. requested feedback. [[User:Grundleborg|Grundleborg]]</s>
**<s>No feedback: REMIND [[User:lemma|lemma]]</s>
*<s>{{Bug|122671}} - No answer from the reporter / Testcase cannot be verified (site is down). [[User:krop|krop]]</s>
**<s>No feedback: REMIND [[User:lemma|lemma]]</s>
*<s>{{Bug|77592}} - needs someone with Java. matt__</s>
**<s>Original site no longer available. The original reporter is trying to get it back. [[User:lemma|lemma]]</s>
** Update: The administrators of the site in question are not going to put it online again. The bug was marked RESOLVED.
* <s> {{Bug|92937}} - neither of the sites listed give me high CPU [[User:kirun|kirun]]
** The sites have changed. As the the reporter mentioned several sites I posted a comment to ask for other sites he's observing high CPU. Probably could be set to REMIND soon. [[User:lemma|lemma]] </s>
*<s>{{Bug|86671}} - seems fixed in trunk but only part is checkable to no-longer existant external testcase. [[User:lemma|lemma]]</s>
**<s>Posted a comment asking if this is still reproducible. [[User:lemma|lemma]]</s>
**<s>Someone already closed as WORKSFORME [[User:lemma|lemma]]</s>
*<s>{{Bug|161056}} There's really not much information and I can't reproduce it. [[User:Edulix|Edulix]]</s>
** reporter WORKSFORME'd it. [[User:Grundleborg|Grundleborg]]
*<s>{{Bug|160945}} There's really not much information and I can't reproduce it. [[User:Edulix|Edulix]]</s>
**<s>Someone already closed this as WORKSFORME [[User:lemma|lemma]]</s>
*<s>{{Bug|105250}} - This bug needs more info. I've asked on the report a testcase because the old one is not available. [[User:Finex|FiNeX]]</s>
**<s>I added what was reported to a minimal testcase and asked if it was correct. [[User:lemma|lemma]]</s>
**<s>Already closed as WORKSFORME [[User:lemma|lemma]]</s>
*<s>{{Bug|85788}} - testcase (needs to be labeled), one part of the bug has been fixed, the other is not checkable due to the external testcase being unavailable. [[User:lemma|lemma]]</s>
**<s>Asked the reporter if that problem was fixed for him somewhen. We won't be able to recover that page I fear. [[User:lemma|lemma]]</s>
**<s>Already closed as WORKSFORME [[User:lemma|lemma]]</s>

==Bugs not related to today==
*{{Bug|160394}} - KSSL related
**now listed as konqueror-general so shouldn't be included in todays triage anyway. [[User:Grundleborg|Grundleborg]]
* {{Bug|70079}} - khtml image part behavior, minor, is this part dolphin by now? [[User:Blauzahl|Blauzahl]]
** I don't think so, since it affects view->image in a web page. [[User:Grundleborg|Grundleborg]]
*{{Bug|120476}} (still problematic in KDE4 [[User:Grundleborg|Grundleborg]]), {{Bug|121401}} (not sure [[User:Grundleborg|Grundleborg]]) - not sure what to do since there are no "access keys" in Konqueror 4. [[User:Grundleborg|Grundleborg]]
**These were just reimplemented, and I suspect it is different code. (blauzahl)
**will test next time I svn up. [[User:Grundleborg|Grundleborg]]

Projects/MovetoGit/Progress

2012-02-23T08:16:04Z

Icwiener: /* What to take from where for release? */ Remove out-dated comment

=== What to take from where for release? ===

{| cellspacing="0" cellpadding="5" border="1" style="border:1px solid gray; border-collapse:collapse; width:100%;"
|- style="background:#afafaf;"
! Module/Application
! branch name scheme / comment
! 4.7
! 4.8
|- style="background:#dfdfdf;"
| '''kdeaccessibility'''
| -
| -
| -
|-
| style="padding-left:50px;" | jovie
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kaccessible
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kmag
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kmousetool
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kmouth
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
|- style="background:#dfdfdf;"
| '''kdeadmin'''
| not yet
| style="background-color: lightpink;" | SVN
| style="background-color: lightpink;" | SVN
|- style="background:#dfdfdf;"
| '''kdeartwork'''
| not yet
| style="background-color: lightpink;" | SVN
| style="background-color: lightpink;" | SVN
|- style="background:#dfdfdf;"
| '''kdebase'''
| -
| -
| -
|-
| style="padding-left:50px;" | kde-runtime
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kde-workspace
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kde-baseapps
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kate
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | konsole
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|- style="background:#dfdfdf;"
| '''kdebindings'''
| -
| -
| -
|-
| style="padding-left:50px;" | kimono
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | qyoto
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kross-interpreters
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | perlkde
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | perlqt
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | pykde4
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | korundum
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | qtruby
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | smokegen
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | smokekde
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | smokeqt
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
|- style="background:#dfdfdf;"
| '''kdeedu'''
| -
| -
| -
|-
| style="padding-left:50px;" | blinken
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | cantor
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kalgebra
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kalzium
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kanagram
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kbruch
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kgeography
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | khangman
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kig
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kiten
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | klettres
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kmplot
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kstars
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | ktouch
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kturtle
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kwordquiz
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | libkdeedu
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | marble
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | parley
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | rocs
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | step
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|- style="background:#dfdfdf;"
| '''kdegames'''
| not yet
| style="background-color: lightpink;" | SVN
| style="background-color: lightpink;" | SVN
|- style="background:#dfdfdf;"
| '''kdegraphics'''
| -
| -
| -
|-
| style="padding-left:50px;" | libksane
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | libkexiv2
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | libkdcraw
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | libkipi
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | ksaneplugin
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kolourpaint
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | ksnapshot
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | gwenview
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kruler
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | mobipocket
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | svgpart
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kcolorchooser
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kgamma
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kdegraphics-strigi-analyzer
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kdegraphics-thumbnailers
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kamera
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | okular
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|- style="background:#dfdfdf;"
| '''kdelibs'''
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|- style="background:#dfdfdf;"
| '''kdemultimedia'''
| not yet
| style="background-color: lightpink;" | SVN
| style="background-color: lightpink;" | SVN
|- style="background:#dfdfdf;"
| '''kdenetwork'''
| not yet
| style="background-color: lightpink;" | SVN
| style="background-color: lightpink;" | SVN
|- style="background:#dfdfdf;"
| '''kdepim'''
| -
| -
| -
|-
| style="padding-left:50px;" | kdepim
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kdepim-runtime
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kdepimlibs
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|- style="background:#dfdfdf;"
| '''kdeplasma-addons'''
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|- style="background:#dfdfdf;"
| '''kdesdk'''
| not yet
| style="background-color: lightpink;" | SVN
| style="background-color: lightpink;" | SVN
|- style="background:#dfdfdf;"
| '''kdetoys'''
| not yet
| style="background-color: lightpink;" | SVN
| style="background-color: lightpink;" | SVN
|- style="background:#dfdfdf;"
| '''kdeutils'''
| -
| -
| -
|-
| style="padding-left:50px;" | ark
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | filelight
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kcalc
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kcharselect
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kdiskfree
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kfloppy
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kgpg
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | printer applet
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kremotecontrol
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | ktimer
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kwallet
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | superkaramba
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | sweeper
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|- style="background:#dfdfdf;"
| '''kdewebdev'''
| not yet
| style="background-color: lightpink;" | SVN
| style="background-color: lightpink;" | SVN
|- style="background:#dfdfdf;"
| '''kdesupport (somewhat)'''
|
| -
| -
|-
| style="padding-left:50px;" | kde-wallpapers
|
| style="background-color: white;" | ?
| style="background-color: lightpink;" | SVN
|-
| style="padding-left:50px;" | oxygen-icons
|
| style="background-color: lightpink;" | SVN
| style="background-color: lightpink;" | SVN
|-
|}

Projects/MoveToGit/StepsToMove

2012-02-23T08:12:36Z

Icwiener: Fix link.

This page documents the steps to follow for moving a module from KDE's subversion repository to gitorious.org.

* Write a ruleset for the module and make sure the git repository has all necessary history in it. See the [[Projects/MoveToGit/UsingSvn2Git|Using Svn2Git]] page for more information about this step.
* Find a sysadmin who can shut down write access to all places in svn that belong to the module. This is needed so that a final rsync will contain all current history for the module and you don't miss any commit.
* Execute the conversion to create a local git repository
* Create a project (if there's no existing one that fits yet) and a git repository on gitorious.org via its webinterface.
* Create a <module>-reviewers group with the review permission set for the git repository
* Create a <module>-maintainers group (or invite admin users individually)
* Give the kde-developers group commit permissions so that any KDE developer can easily collaborate on the module
* The kde-sysadmins needs to be added too with admin rights, so they can help with tagging and general administration (setting up hooks etc.)
* Add the new remote repository to your local one as new remote, then push all local branches and tags to the remote repository.
* Scripty needs to be pointed to the new place of the module, you can send the kde-i18n-doc mailinglist a note and it should be taken care of.
* Clean up subversion, this means either leaving a single README file instead of the original content of the module, or removing the path completely
* Point EBN to the new place of the module: Contact Allen Winter.
* Point LXR to the new place of the module: Contact [https://bugs.kde.org/enter_sysadmin_request.cgi KDE's sysadmins].
* Adjust the developer information on www.kde.org

Thats it. More information on the permissions and post-hook scripts (for BUG:, CCMAIL: etc) can be found on the [[Development/Git|KDE on Git]] page.

MediaWiki:Filedelete-reason-dropdown

2012-01-30T11:50:55Z

Icwiener: Add Spam as deletion reason

*Common delete reasons
** Copyright violation
** Spam
** Duplicated file

Thread:User talk:Droetker/Sehr schön

2012-01-14T23:41:01Z

Icwiener: New thread: Sehr schön

Sehr schön, dass sich jemand die Übersetzungen ansieht und da einmal aufräumt. :)

User talk:Droetker

2012-01-14T23:41:01Z

Icwiener: Talk page autocreated when first thread was posted

Policies/Kdelibs Coding Style

2012-01-05T12:59:21Z

Icwiener: /* Artistic Style (astyle) automatic code formatting */ Fix my former change.

<languages />
<translate>

This document describes the recommended coding style for kdelibs. Nobody is forced to use this style, but to have consistent formatting of the source code files it is recommended to make use of it.


'''In short: Kdelibs coding style follows the [http://wiki.qt-project.org/Coding_Style Qt 4 coding style].'''

== Indentation == 
* No tabs
* 4 Spaces instead of one tab

== Variable declaration == 
* Each variable declaration on a new line
* Each new word in a variable name starts with a capital letter (so-called camelCase)
* Avoid abbreviations
* Take useful names. No short names, except:
** Single character variable names can denote counters and temporary variables whose purpose is obvious
** Variables and functions start with a lowercase letter


Example:
</translate>
<syntaxhighlight lang="cpp-qt">
<translate>
// wrong</translate>
KProgressBar *prbar;
QString prtxt, errstr;

<translate>
// correct</translate>
KProgressBar *downloadProgressBar;
QString progressText;
QString errorString;
</syntaxhighlight>

<translate>
== Whitespace == 
* Use blank lines to group statements
* Use only one empty line
* Use one space after each keyword
* For pointers or references, use a single space before '*' or '&', but not after
* No space after a cast


Example:
</translate>
<syntaxhighlight lang="cpp-qt">
<translate>
// wrong</translate>
QString* myString;
if(true){
}

<translate>
// correct</translate>
QString *myString;
if (true) {
}
</syntaxhighlight>

<translate>
== Braces == 
As a base rule, the left curly brace goes on the same line as the start of the statement.


Example:
</translate>
<syntaxhighlight lang="cpp-qt">
<translate>
// wrong</translate>
if (true)
{
}

<translate>
// correct</translate>
if (true) {
}
</syntaxhighlight>

<translate>

Exception: Function implementations, class, struct and namespace declarations always have the opening brace on the start of a line.


Example:
</translate>
<syntaxhighlight lang="cpp-qt">
void debug(int i)
{
qDebug("foo: %i", i);
}

class Debug
{
};
</syntaxhighlight>

<translate>

Use curly braces even when the body of a conditional statement contains only one line.


Example:
</translate>
<syntaxhighlight lang="cpp-qt">
<translate>
// wrong</translate>
if (true)
return true;

for (int i = 0; i < 10; ++i)
qDebug("%i", i);

<translate>
// correct</translate>
if (true) {
return true;
}

for (int i = 0; i < 10; ++i) {
qDebug("%i", i);
}
</syntaxhighlight>

<translate>
== Switch statements == 
Case labels are on the same column as the switch


Example:
</translate>
<syntaxhighlight lang="cpp-qt">
switch (myEnum) {
case Value1:
doSomething();
break;
case Value2:
doSomethingElse();
// fall through
default:
defaultHandling();
break;
}
</syntaxhighlight>

<translate>
== Line breaks == 
Try to keep lines shorter than 100 characters, inserting line breaks as necessary.

== Qt Includes == 
* If you add #includes for Qt classes, use both the module and class name. This allows library code to be used by applications without excessive compiler include paths.


Example:
</translate>
<syntaxhighlight lang="cpp-qt">
<translate>
// wrong</translate>
#include <QString>

<translate>
// correct</translate>
#include <QtCore/QString>
</syntaxhighlight>

<translate>
== Artistic Style (astyle) automatic code formatting == 
You can use [http://astyle.sourceforge.net/ astyle] (>=1.23) to format code or to test if you have followed this document. Run the following command:
</translate>
<syntaxhighlight lang="text">
astyle --indent=spaces=4 --brackets=linux \
--indent-labels --pad=oper --unpad=paren \
--one-line=keep-statements --convert-tabs \
--indent-preprocessor \
`find -type f -name '*.cpp'-or -name '*.cc' -or -name '*.h'`
</syntaxhighlight>

<translate>

With astyle (>=2.01) you need to run the following command:
</translate>
<syntaxhighlight lang="text">
astyle --indent=spaces=4 --brackets=linux \
--indent-labels --pad-oper --unpad-paren --pad-header \
--keep-one-line-statements --convert-tabs \
--indent-preprocessor \
`find -type f -name '*.cpp' -or -name '*.cc' -or -name '*.h'`
</syntaxhighlight>

<translate>

A related shell script could be found for unix in [http://websvn.kde.org/*checkout*/trunk/KDE/kdesdk/scripts/astyle-kdelibs kdesdk/scripts/astyle-kdelibs] and for windows in [http://websvn.kde.org/*checkout*/trunk/KDE/kdesdk/scripts/astyle-kdelibs.bat kdesdk/scripts/astyle-kdelibs.bat].

== Emacs and Vim scripts == 
The "scripts" directory in the kdesdk module contains, among other useful things, some useful additions to the Emacs and Vim text editors that make it easier to edit KDE code with them.

=== Emacs ===
The [http://websvn.kde.org/trunk/KDE/kdesdk/scripts/kde-emacs kde-emacs] directory contains a set of key bindings, macros and general useful code. It is compatible with both GNU Emacs and XEmacs.


To start using kde-emacs, add the following to your .emacs:
</translate>

<syntaxhighlight lang="text">
(add-to-list 'load-path "/path/to/kde-emacs")
(require 'kde-emacs)
</syntaxhighlight>

<translate>

Many settings can be changed by editing the "kde-emacs" group via <tt>M-x customize-group</tt>.


For more information, including what the key bindings are and what additional settings you could add to your .emacs, please check <tt>kde-emacs.el</tt> itself.

=== Vim === 
You can find a vim script in [http://websvn.kde.org/*checkout*/trunk/KDE/kdesdk/scripts/kde-devel-vim.vim kdesdk/scripts/kde-devel-vim.vim] that helps you to keep the coding style correct. In addition to defaulting to the kdelibs coding style it will automatically use the correct style for Solid and kdepim code. If you want to add rules for other projects feel free to add them in the SetCodingStyle function.


To use the script, include it in your {{path|~/.vimrc}} like this:
</translate>
<syntaxhighlight lang="text">
source /path/to/kde/sources/kdesdk/scripts/kde-devel-vim.vim
</syntaxhighlight>

<translate>

Document started by Urs Wolfer. Some parts of this document have been adopted from the Qt Coding Style document posted by Zack Rusin on kde-core-devel.


[[Category:Policies]] [[Category:C++]]
</translate>

Policies/Kdelibs Coding Style

2012-01-05T12:39:25Z

Icwiener: /* Artistic Style (astyle) automatic code formatting */ Use more compact find syntax.

<languages />
<translate>

This document describes the recommended coding style for kdelibs. Nobody is forced to use this style, but to have consistent formatting of the source code files it is recommended to make use of it.


'''In short: Kdelibs coding style follows the [http://wiki.qt-project.org/Coding_Style Qt 4 coding style].'''

== Indentation == 
* No tabs
* 4 Spaces instead of one tab

== Variable declaration == 
* Each variable declaration on a new line
* Each new word in a variable name starts with a capital letter (so-called camelCase)
* Avoid abbreviations
* Take useful names. No short names, except:
** Single character variable names can denote counters and temporary variables whose purpose is obvious
** Variables and functions start with a lowercase letter


Example:
</translate>
<syntaxhighlight lang="cpp-qt">
<translate>
// wrong</translate>
KProgressBar *prbar;
QString prtxt, errstr;

<translate>
// correct</translate>
KProgressBar *downloadProgressBar;
QString progressText;
QString errorString;
</syntaxhighlight>

<translate>
== Whitespace == 
* Use blank lines to group statements
* Use only one empty line
* Use one space after each keyword
* For pointers or references, use a single space before '*' or '&', but not after
* No space after a cast


Example:
</translate>
<syntaxhighlight lang="cpp-qt">
<translate>
// wrong</translate>
QString* myString;
if(true){
}

<translate>
// correct</translate>
QString *myString;
if (true) {
}
</syntaxhighlight>

<translate>
== Braces == 
As a base rule, the left curly brace goes on the same line as the start of the statement.


Example:
</translate>
<syntaxhighlight lang="cpp-qt">
<translate>
// wrong</translate>
if (true)
{
}

<translate>
// correct</translate>
if (true) {
}
</syntaxhighlight>

<translate>

Exception: Function implementations, class, struct and namespace declarations always have the opening brace on the start of a line.


Example:
</translate>
<syntaxhighlight lang="cpp-qt">
void debug(int i)
{
qDebug("foo: %i", i);
}

class Debug
{
};
</syntaxhighlight>

<translate>

Use curly braces even when the body of a conditional statement contains only one line.


Example:
</translate>
<syntaxhighlight lang="cpp-qt">
<translate>
// wrong</translate>
if (true)
return true;

for (int i = 0; i < 10; ++i)
qDebug("%i", i);

<translate>
// correct</translate>
if (true) {
return true;
}

for (int i = 0; i < 10; ++i) {
qDebug("%i", i);
}
</syntaxhighlight>

<translate>
== Switch statements == 
Case labels are on the same column as the switch


Example:
</translate>
<syntaxhighlight lang="cpp-qt">
switch (myEnum) {
case Value1:
doSomething();
break;
case Value2:
doSomethingElse();
// fall through
default:
defaultHandling();
break;
}
</syntaxhighlight>

<translate>
== Line breaks == 
Try to keep lines shorter than 100 characters, inserting line breaks as necessary.

== Qt Includes == 
* If you add #includes for Qt classes, use both the module and class name. This allows library code to be used by applications without excessive compiler include paths.


Example:
</translate>
<syntaxhighlight lang="cpp-qt">
<translate>
// wrong</translate>
#include <QString>

<translate>
// correct</translate>
#include <QtCore/QString>
</syntaxhighlight>

<translate>
== Artistic Style (astyle) automatic code formatting == 
You can use [http://astyle.sourceforge.net/ astyle] (>=1.23) to format code or to test if you have followed this document. Run the following command:
</translate>
<syntaxhighlight lang="text">
astyle --indent=spaces=4 --brackets=linux \
--indent-labels --pad=oper --unpad=paren \
--one-line=keep-statements --convert-tabs \
--indent-preprocessor \
`find -type f -name '*.cpp'-or '*.cc' -or '*.h'`
</syntaxhighlight>

<translate>

With astyle (>=2.01) you need to run the following command:
</translate>
<syntaxhighlight lang="text">
astyle --indent=spaces=4 --brackets=linux \
--indent-labels --pad-oper --unpad-paren --pad-header \
--keep-one-line-statements --convert-tabs \
--indent-preprocessor \
`find -type f -name '*.cpp' -or '*.cc' -or '*.h'`
</syntaxhighlight>

<translate>

A related shell script could be found for unix in [http://websvn.kde.org/*checkout*/trunk/KDE/kdesdk/scripts/astyle-kdelibs kdesdk/scripts/astyle-kdelibs] and for windows in [http://websvn.kde.org/*checkout*/trunk/KDE/kdesdk/scripts/astyle-kdelibs.bat kdesdk/scripts/astyle-kdelibs.bat].

== Emacs and Vim scripts == 
The "scripts" directory in the kdesdk module contains, among other useful things, some useful additions to the Emacs and Vim text editors that make it easier to edit KDE code with them.

=== Emacs ===
The [http://websvn.kde.org/trunk/KDE/kdesdk/scripts/kde-emacs kde-emacs] directory contains a set of key bindings, macros and general useful code. It is compatible with both GNU Emacs and XEmacs.


To start using kde-emacs, add the following to your .emacs:
</translate>

<syntaxhighlight lang="text">
(add-to-list 'load-path "/path/to/kde-emacs")
(require 'kde-emacs)
</syntaxhighlight>

<translate>

Many settings can be changed by editing the "kde-emacs" group via <tt>M-x customize-group</tt>.


For more information, including what the key bindings are and what additional settings you could add to your .emacs, please check <tt>kde-emacs.el</tt> itself.

=== Vim === 
You can find a vim script in [http://websvn.kde.org/*checkout*/trunk/KDE/kdesdk/scripts/kde-devel-vim.vim kdesdk/scripts/kde-devel-vim.vim] that helps you to keep the coding style correct. In addition to defaulting to the kdelibs coding style it will automatically use the correct style for Solid and kdepim code. If you want to add rules for other projects feel free to add them in the SetCodingStyle function.


To use the script, include it in your {{path|~/.vimrc}} like this:
</translate>
<syntaxhighlight lang="text">
source /path/to/kde/sources/kdesdk/scripts/kde-devel-vim.vim
</syntaxhighlight>

<translate>

Document started by Urs Wolfer. Some parts of this document have been adopted from the Qt Coding Style document posted by Zack Rusin on kde-core-devel.


[[Category:Policies]] [[Category:C++]]
</translate>

Thread:Talk:Development/Tutorials/KWin/Scripting/Copyright/reply (2)

2011-12-15T12:10:53Z

Icwiener: Reply to Copyright

Even if it was a Code-In task, it's still his blog. I do not know about the specifics of the contracts the applicants have to sign, but I think it's better to have the author's permission.
Thanks.

Thread:Talk:Development/Tutorials/KWin/Scripting/Copyright

2011-12-14T23:21:34Z

Icwiener: typo

Do we have the permission to have this here?

Thread:Talk:Development/Tutorials/KWin/Scripting/Copyright

2011-12-14T23:20:42Z

Icwiener: New thread: Copyright

Do we have the permission to have his here?

Talk:Development/Tutorials/KWin/Scripting

2011-12-14T23:20:42Z

Icwiener: Talk page autocreated when first thread was posted

Thread:Talk:Getting Started/Using an IDE with KDE4/Update svn links to git?/reply

2011-11-08T23:34:26Z

Icwiener: Reply to Update svn links to git?

Please make the change, if you know it works. In this case KDEPIM indeed moved to Git, so it is save to change it.

In general if the page is about development, I think linking to URL renaming and using kde:foo URL is alright. If it is about building an application by hand, just stating anongit should be enough.

Thanks for your contribution.

Getting Started/Build/KDE Applications

2011-11-08T23:25:45Z

Icwiener: Use syntaxhighlight.

= Introduction =
The process to build applications is easy. It can get tedious in the beginning but with time it's easy to understand.

In this page I'll discuss the compilation and installation of a simple KDE application or project on a regular GNU/Linux system. It can get more complicated but I'd prefer to keep this document simple.

= Preparing your system a little =
First of all you probably will need to know the dependencies to compile the program you want to compile. In my experience, a great portion of the problems that people have forgot to install the development packages for the system libraries. Keep that in mind.

In general, the needed packages will be: cmake, git-core, libqt4(-dev), kdelibs(-dev). Depends on the distribution but the naming should be something like this.

= Steps =

Here we will try to compile an application, let's say blinken. You can find a full compendium of the KDE projects in http://projects.kde.org

First we will download the code

<syntaxhighlight lang="bash">
git clone git://anongit.kde.org/blinken
</syntaxhighlight>

This will create a directory with blinken's source code inside. We get in and we create a directory where it's going to be built

<syntaxhighlight lang="bash">
cd blinken; mkdir build; cd build
</syntaxhighlight>

Now we'll set up the development system by calling cmake. We're passing two parameters here CMAKE_INSTALL_PREFIX that will tell where the application will be installed and CMAKE_BUILD_TYPE that will tell the optimization of the produced binaries. (not entirely accurate, but there's heaps of documentation about that).

<syntaxhighlight lang="bash">
cmake .. -DCMAKE_INSTALL_PREFIX=<install_path> -DCMAKE_BUILD_TYPE=debugfull
</syntaxhighlight>

The moment we were all expecting has arrived, now you can start compiling.

<syntaxhighlight lang="bash">
make
</syntaxhighlight>

Some applications can work without installing but that's usually not the case so just do it if you know what you're doing, otherwise you will want to install probably.

<syntaxhighlight lang="bash">
make install
</syntaxhighlight>

If you're installing it to a directory where the owner is root, then you'll probably need some extended privileges to install. That's not the only option, though. You can create a specific install directory by pointing the PATH and KDEDIRS variables to it, more information here: [[Getting_Started/Build/Environment]]

Schedules/Extragear

2011-10-30T21:39:19Z

Icwiener: KMymoney 4.6.1

This page is intended to be a central location for Extragear projects to keep users and contributors (translators, packagers, etc.) informed about upcoming releases in a very accessible way.

 

{| border="1"
|-
! Project
! Next release (roughly)
! Next Release Code branch
! Next Release Translation branch
! Comments
|-
| K3b
| 1 March 2010
| [http://websvn.kde.org/trunk/extragear/multimedia/k3b/ trunk]
| [http://websvn.kde.org/trunk/l10n-kde4/templates/messages/extragear-multimedia/ trunk kde4]
| String freeze starting from January 31 2010 (in effect)
|-
| KAudiocreator
|
|
|
|
|-
| Kaffeine
|
|
|
|
|-
| [http://extragear.kde.org/apps/kcoloredit/ KColorEdit]
| KDE release
| [http://websvn.kde.org/trunk/extragear/graphics/kcoloredit/ trunk]
| [http://websvn.kde.org/trunk/l10n-kde4/templates/messages/extragear-graphics/ trunk kde4]
|
|-
| [http://www.kde-apps.org/content/show.php/KDE+Partition+Manager?content=89595 KDE Partition Manager]
| Q2/2010
| [http://websvn.kde.org/trunk/extragear/sysadmin/partitionmanager/ trunk]
| [http://websvn.kde.org/trunk/l10n-kde4/templates/messages/extragear-sysadmin/ trunk kde4]
| 
|
|-
| [http://ww.kdevelop.org KDevelop]
| 1 May 2010
| [http://websvn.kde.org/trunk/extragear/sdk/kdevelop/ trunk]
| [http://websvn.kde.org/trunk/l10n-kde4/templates/messages/extragear-sdk/ trunk kde4]
| string freeze starting 31 March 2010
|-
| KDiff3
| January 31, 2009
| [http://websvn.kde.org/trunk/extragear/utils/kdiff3/ trunk]
| [http://websvn.kde.org/trunk/l10n-kde4/templates/messages/extragear-utils/ trunk kde4]
|
|-
| KFax
| KDE release
|
|
|
|-
| KFTPGrabber
|
|
|
|
|-
| KGrab
| KDE release
|
|
|
|-
| [http://extragear.kde.org/apps/kgraphviewer/ KGraphViewer]
| KDE release
| [http://websvn.kde.org/trunk/extragear/graphics/kgraphviewer/ trunk]
| [http://websvn.kde.org/trunk/l10n-kde4/templates/messages/extragear-graphics/ trunk kde4]
|
|-
| KIconedit
| KDE release
|
|
|
|-
| [http://www.kmldonkey.org KMLDonkey]
| KDE release
| [http://websvn.kde.org/trunk/extragear/network/kmldonkey/ trunk]
| [http://websvn.kde.org/trunk/l10n-kde4/templates/messages/extragear-network/ trunk kde4]
|
|-
| KNemo
| January 17, 2010
| [http://websvn.kde.org/trunk/extragear/network/knemo/ trunk]
| [http://websvn.kde.org/trunk/l10n-kde4/templates/messages/extragear-network/ trunk kde4]
| String freeze in effect
|
|-
| [http://konversation.kde.org Konversation]
| In the week beginning June 7th 2010
| [http://gitorious.org/konversation/konversation/trees/master git master]
| [http://websvn.kde.org/trunk/l10n-kde4/templates/messages/extragear-network/ trunk kde4]
|
|-
| KPager
|
|
|
|
|-
| KPhotoalbum
| May 9 2009
| trunk
| trunk
| Message freeze, April 3 2009
|-
| KPlayer
|
|
|
|
|-
| KPovmodeler
| KDE release
|
|
|
|-
| KRecipes
|
|
|
|
|-
| KSig
|
|
|
|
|-
| [http://ktorrent.org/ KTorrent]
| 8 november 2009
| [http://websvn.kde.org/branches/stable/extragear-kde4/network/ktorrent stable kde4]
| [http://websvn.kde.org/branches/stable/l10n-kde4/templates/messages/extragear-network/ stable kde4]
| String freeze in effect
|-
| Kuickshow
|
|
|
|
|-
| KWlan
|
|
|
|
|-
| RSIBreak
|
|
|
|
|-
| Skanlite
| KDE release
| trunk
|
|
|-
| [http://skrooge.org Skrooge]
| 2010-02-06 (version 0.6.0)
| [http://websvn.kde.org/trunk/extragear/office/skrooge trunk]
| [http://websvn.kde.org/trunk/l10n-kde4/templates/messages/extragear-office/ trunk kde4]
| String freeze in effect
|-
| [http://www.kde-apps.org/content/show.php?content=29153 Yakuake]
| July 8th, 2010
| [http://websvn.kde.org/trunk/extragear/utils/yakuake/ trunk]
| [http://websvn.kde.org/trunk/l10n-kde4/templates/messages/extragear-utils/ trunk kde4]
| String freeze started June 24th, 2010
|-
| Kile
| June 8th, 2011 (Version 2.1)
|
|
| String freeze started 23 May 2011
|-
| [http://www.krusader.org/ Krusader]
| 2.4.0-beta1 released on June 26, 2011.
| [http://websvn.kde.org/trunk/extragear/utils/krusader/ trunk]
| [http://websvn.kde.org/trunk/l10n-kde4/templates/messages/extragear-utils/ trunk kde4]
| String freeze since June 26, 2011 until 2.4.0 release.
|-
| BlueDevil
| 1.0.5 (stable) and 1.1.1 (trunk) released planned on July 15, 2011.
|
| stable, trunk
| String freeze since June 29, 2011 until 1.0.5 and 1.1.1 releases.
|-
| [http://amarok.kde.org Amarok]
| July 22, 2011 (Amarok 2.4.2)
| git master
| git master
| string freeze: July 4, 2011 — July 22, 2011
|-
| [http://digikam.org digiKam]
| July 27th 2011 [http://www.digikam.org/drupal/about/releaseplan]
| [https://projects.kde.org/projects/extragear/graphics git master]
| [http://websvn.kde.org/trunk/l10n-kde4/templates/messages/extragear-graphics/ trunk kde4]
| String freeze starting June 30th 2011.
|-
| [http://techbase.kde.org/Projects/KMyMoney KMyMoney]
| 4.6.1 from Stable around November 5th, 2011
| [http://websvn.kde.org/trunk/extragear/office/kmymoney/ trunk]
| [http://websvn.kde.org/trunk/l10n-kde4/templates/messages/extragear-office/ trunk kde4]
| String freeze started October 22nd, 2011
|-
| massif-visualizer
| 0.3 is planned to be released on September 4, 2011
|
|
| String freeze started on August 8, 2011
|-
| [http://tellico-project.org Tellico]
| 2.3.4
| [http://websvn.kde.org/trunk/extragear/office/tellico/ trunk]
| [http://websvn.kde.org/trunk/l10n-kde4/templates/messages/extragear-office/ trunk kde4]
| String freeze: September 5th, 2011 -- September 18th, 2011.
|-
| [http://www.rekonq.sourceforge.net rekonq]
| ~ October 11, 2011 (Version 0.8)
| [http://gitorious.org/rekonq/mainline/trees/master git master]
| [http://gitorious.org/rekonq/mainline/trees/master git master]
| String freeze for 3 weeks starting September 21, 2011 (0.8 release)
|-
| KDE Telepathy
| November 18th, 2011 (version 0.2)
|
|
| String freeze starting October 26th, 2011.
|-
| Calligra
| After November 23th, 2011 [http://mail.kde.org/pipermail/calligra-devel/2011-July/001957.html schedule]
|
|
| String freeze starting October 12th, 2011.
|}

Welcome to KDE TechBase/de

2011-10-30T19:13:35Z

Icwiener: foo

{{Template:I18n/Language Navigation Bar|Welcome to KDE TechBase}}

<languages />

{| style="margin: 1em 2.5% 0 2.5%; padding: 0 5px;" cellpadding="5"
|-
|colspan=2|[[Image:Discover.png|noframe]]
|-
| style="padding-left: 50px;" |[[Image:Action_launch.svg|noframe|left|40px]] ||
;[[Special: MyLanguage/Getting Started | Einrichten einer KDE-Entwicklungsumgebung]]: Erfahren Sie, wie Sie KDE bekommen, erstellen und ausführen.
|-
| style="padding-left: 50px;"|[[Image:Action_configure.svg|noframe|left|40px]] ||
;[[Special: MyLanguage/Development | Entwickeln mit KDE]]
:[[Special: MyLanguage/Development/Tutorials | Tutorien]] | [http://api.kde.org API-Dokumentation] | [[Special: MyLanguage/Development/FAQs | Fragen&Antworten]] und vieles mehr.
:''Mehr'': [[Special:myLanguage/Schedules|Release Schedules und Feature Pläne]] | [[Special:myLanguage/Policies|Code-Beisteuerung und Entwicklungsrichtlinien]]
|-
| style="padding-left: 50px;"|[[Image:Devices_system.svg|noframe|left|40px]] ||
;[[Special:myLanguage/KDE System Administration|KDE-Systemadministration]]:Informationen für Systemadministratoren, die KDE-Installationen verwalten.
|-
|colspan=2|[[Image:Interact.png|noframe]]
|-
| style="padding-left: 50px;"|[[Image:Action_favorites.svg|noframe|left|40px]] ||
;[[Special:myLanguage/Contribute|
Join the KDE Team and Contribute]]
:Contribute patches, keep in touch with and join our community.
:''Related:''[[Special:myLanguage/Policies|
KDE Project Policies]] | [http://www.kde.org/support/support.php Donate Money]
|-
| style="padding-left: 50px;"|[[Image:Action_contents.svg|noframe|left|40px]] ||
;[[Special:myLanguage/ISV|ISV Information]]:Developer information for Independent Software Vendors.
|-
|colspan=2|[[Image:Develop.png|noframe]]
|-
| style="padding-left: 50px;" |[[Image:Action_wizard.svg|noframe|left|40px]] ||
;[[Special:myLanguage/Projects|
KDE projects]]
:Links to development wikis, task lists, etc. for various KDE Projects.

|}

Translations:Welcome to KDE TechBase/3/de

2011-10-30T19:13:35Z

Icwiener: foo

[[Special: MyLanguage/Development/Tutorials | Tutorien]] | [http://api.kde.org API-Dokumentation] | [[Special: MyLanguage/Development/FAQs | Fragen&Antworten]] und vieles mehr.

Development/Tutorials/Plasma/QML/GettingStarted

2011-10-15T22:38:36Z

Icwiener: /* Minimum size */ Fix typo.

== Abstract ==

Writing a plasma applet in QML is very easy, in fact, with KDE 4.6 and Qt 4.7 it just works.

== QML Basics ==

It is recommended that you have read through the [http://doc.qt.nokia.com/4.7/qtquick.html Qt QML Tutorials], as there are quite a few and they are explained thoroughly. There is also a list of all [http://doc.qt.nokia.com/4.7/qdeclarativeelements.html standard QML elements].

Essentially, most of the content is the same. The exceptions to be noted are how data is gathered...since we use Data Engines, it is a bit different. Text color and font should be made to use PlasmaCore.Theme.

See the [https://projects.kde.org/projects/kde/kdeexamples/repository KDE Examples] repository for more KDE-related helpful resources. Also of use (which use QML and Plasma) are: [https://projects.kde.org/projects/playground/base/plasma-mobile/repository Plasma Mobile], [https://projects.kde.org/projects/playground/base/declarative-plasmoids/repository Declarative Plasmoids (playground)], for WIP ports of C++ originals

=== Root Item ===

The root item can be anything that inherits QGraphicsItem. For example, in this case it is QGraphicsWidget which is a plasmoid. It can also simply be an Item. I also noticed that PathView does not respond to mouse inputs automatically (so flicking doesn't work). Probably because events are being intercepted. So take note, it'll have to be e.g. an Item, for that case.

=== Layouts ===

==== Row and Column ====

==== Anchors ====
Anchor layouts offer a nice way of grouping UI elements nicely together. The idea is that you connect edges or corners of one element to the edge or corner of another widget.
Some examples:
<syntaxhighlight lang="javascript">
import QtQuick 1.0
import org.kde.plasma.core 0.1 as PlasmaCore

Item {
width: 200
height: 300

Text {
id: first
text: i18n("1st line")
anchors {
top: parent.top;
left: parent.left;
right: parent.right;
}
}
Text {
id: second
text: i18n("2nd line")
anchors {
top: first.bottom;
left: parent.left;
right: parent.right;
bottom: parent.bottom;
}
}
}
</syntaxhighlight>

=== Buttons ===

=== Animations ===

== Package Structure ==

You create a .desktop file and the .qml file. They have to be in the usual plasma package structure:

* plasmoid-qml/metadata.desktop
* plasmoid-qml/contents/ui/main.qml

=== <tt>metadata.desktop</tt> ===
<syntaxhighlight lang="ini">
[Desktop Entry]
Name=Hello QML
Comment=A hello world widget in QML
Icon=chronometer

X-Plasma-API=declarativeappletscript
X-Plasma-MainScript=ui/main.qml
X-Plasma-DefaultSize=200,100

X-KDE-PluginInfo-Author=Frederik Gladhorn
X-KDE-PluginInfo-Email=gladhorn@kde.org
X-KDE-PluginInfo-Website=http://plasma.kde.org/
X-KDE-PluginInfo-Category=Examples
X-KDE-PluginInfo-Name=org.kde.hello-qml
X-KDE-PluginInfo-Version=0.0

X-KDE-PluginInfo-Depends=
X-KDE-PluginInfo-License=GPL
X-KDE-PluginInfo-EnabledByDefault=true
X-KDE-ServiceTypes=Plasma/Applet
Type=Service
</syntaxhighlight>

The line below indicates the default size of the plasmoid. The applet's starting size will be this, when added to a scene:

<syntaxhighlight lang="ini">
X-Plasma-DefaultSize=200,100
</syntaxhighlight>

=== <tt>main.qml</tt> ===
<syntaxhighlight lang="javascript">
import QtQuick 1.0

Text {
text: "Hello world!";
}
</syntaxhighlight>

== Installing ==
You can install your plasmoid, though obviously this is just temporary. CMake, below, is recommended:
<syntaxhighlight lang="bash">
plasmapkg --install plasmoid-qml
</syntaxhighlight>

=== Installation through CMake ===
In your CMakeLists.txt:

<syntaxhighlight lang="cmake">
project(helloqml)

install(DIRECTORY package/
DESTINATION ${DATA_INSTALL_DIR}/plasma/plasmoids/org.kde.plasma.applet.myapplet)

install(FILES package/metadata.desktop
DESTINATION ${SERVICES_INSTALL_DIR} RENAME plasma-applet-myapplet.desktop)
</syntaxhighlight>

Your directory structure should now be as follows:

<syntaxhighlight lang="bash">
myproject/CMakeLists.txt
myproject/package/
myproject/package/metadata.desktop
myproject/package/contents/
myproject/package/contents/ui/
myproject/package/contents/ui/helloworld.qml
</syntaxhighlight>

(if you have a configuration file (.ui file) to load the right-click 'plasmoid settings' menu, then your structure will also have myproject/package/contents/config/config.ui, or so)

== plasmoidviewer ==
You can run it in plasmoidviewer as usual:
plasmoidviewer plasmoid-qml

== qmlviewer ==
It's possible to use Plasma specific imports in qml files loaded by qmlviewer:

qmlviewer -I /usr/lib/kde4/imports/ plasmoid-qml/contents/qml/main.qml

Where the -I is the path to the plasma plugin for qml. Try to look for the path of
/usr/lib/kde4/imports/org/kde/plasma/graphicswidgets/libgraphicswidgetsbindingsplugin.so
and use everything up to org of that path.

Hovewer it's '''strongly discouraged''' to use qmlviewer to develop plasmoids, because '''some features won't be available there, like the following''':
* localization with i18n()
* access to the global ''plasmoid'' object
* device specific qml files imported with plasmapackage:// urls
* bindings for qicons, KJobs, services and KConfig
* retrieving data from a DataEngine

Therefore, it is recommended to simply use '''plasmoidviewer'''

= Features only available in Plasma widgets =
In order to have a better integration with the KDE platform and to reach an higher degree of expressivity, the stock features of QML have been expanded with the following features, that strictly follow the Plasmoid JavaScript API:

== Minimum size ==
if the root object of the plasmoid has the properties minimumWidth and minimumHeight, they will be used as the minimum size for the plasmoid. If they will change during the plasmoid execution, the plasmoid minimum size will be updated accordingly.
<syntaxhighlight lang="javascript">
import QtQuick 1.0

Text {
property int minimumWidth: paintedWidth
property int minimumHeight: paintedHeight
text: "Hello world!";
}
</syntaxhighlight>

In the above example, the minimum size is bound to the paintedWidth/paintedHeight properties of the Text element, ensuring there will always be enough room for the whole text to be displayed.

== Plasmoid object ==
Every QML plasmoid will have an object called ''plasmoid'', that will give access to the configuration, the formfactor, immutability and so on. It offers the same api as the object with the same name in the Javascript API.

For specific info on this, see [http://techbase.kde.org/Development/Tutorials/Plasma/JavaScript/API-PlasmoidObject Javascript API-Plasmoid Object]

== Localization ==
It is possible to localize strings with the usual i18n(), i18nc(), i18np() global functions.

== Extra types ==
Some extra types are available from withing JavaScript, namely

* KConfigGroup: it's an object with its config keys readable and writable as properties
* QIcon: can be constructed with QIcon("fdo name") such as QIcon("konqueror")
* KJob
* Plasma Service api

= Plasma specific imports =
To use some Plasma specific features and to take advantage of them in order for your applet to become a true Plasma applet, it is necessary to use some particular QML imports. See [http://techbase.kde.org/Development/Tutorials/Plasma/QML/API Plasma QML API].

== Extra Qt features ==
org.kde.qtextraimports
To use, do:

<syntaxhighlight lang="javascript">
import org.kde.qtextracomponents 0.1 as QtExtraComponents
</syntaxhighlight>

* QPixmapItem
* QImageItem
* QIconItem

== Plasma Widgets in QML ==
To use standard plasma widgets (e.g. Plasma::LineEdit, etc.), you simply add an import line for them.
All properties, signals and slots from ordinary Plasma widgets are available there.
'''These widgets are provided as a transition tool, intended to be replaced by the Plasma version of QtComponents''', which is currently in development by a gsoc. (note that the Plasma QtComponents have nothing to do with the QtExtraComponents module described above)

<syntaxhighlight lang="javascript">
import QtQuick 1.0
import org.kde.plasma.graphicswidgets 0.1 as PlasmaWidgets

Item {
width: 64
height: 64
PlasmaWidgets.IconWidget {
id: icon
Component.onCompleted: setIcon("flag-red")
anchors.centerIn: parent
}
}
</syntaxhighlight>

Schedules/KDE4/4.8 Feature Plan

2011-10-15T03:41:59Z

Icwiener: Added kdegames table

This is a list of planned features for the SC 4.8 release.

See also:

*[[Schedules/KDE4/4.8 Release Schedule]]
*[[Schedules/KDE4/4.8 Release Goals]]
*[[Schedules/KDE4/4.7 Feature Plan]] (previous major release)

 Legend:

*todo => not started yet
*in-progress => started, but not completed yet
*done => completed

__TOC__

 

= kde-workspace =

{| cellspacing="0" cellpadding="5" border="1" style="border: 1px solid gray; border-collapse: collapse; text-align: left; width: 100%;" class="sortable"
|- style="background: rgb(236, 236, 236) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous; white-space: nowrap;"

! Status
! Project
! Description
! Contact

{{FeatureInProgress|KWin|Take over screensaver/locking management from KRunner|alex.merry@kdemail.net|Alex Merry}}
{{FeatureInProgress|KCM|make mouse cursor size configurable (http://git.reviewboard.kde.org/r/101701/)|SommerLuk@gmail.com|Lukas Sommer}}
{{FeatureDone|powerdevil|Remove Desktop Effects Management|drf@kde.org|Dario Freddi}}
{{FeatureInProgress|powerdevil|Allow static profiles only|drf@kde.org|Dario Freddi}}
{{FeatureInProgress|powerdevil|Allow activity interaction|drf@kde.org|Dario Freddi}}
|}
 

= kdelibs =

{| cellspacing="0" cellpadding="5" border="1" style="border: 1px solid gray; border-collapse: collapse; text-align: left; width: 100%;" class="sortable"
|- style="background: rgb(236, 236, 236) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous; white-space: nowrap;"

! Status
! Project
! Description
! Contact

{{FeatureDone|Kate Part|Line modification system|dhaumann@kde.org|Dominik Haumann}}
{{FeatureDone|Kate Part|Modeline Editor|dhaumann@kde.org|Dominik Haumann}}
{{FeatureDone|Kate Part|Search & Replace in files plugin|kare.sars@iki.fi|Kåre Särs}}
{{FeatureDone|Kate Part|Reliable code folding|adrian.lungu89@gmail.com|Adrian Lungu}}
{{FeatureDone|Kate Part|Improved vi input mode|svatoslav1@gmail.com|Svyatoslav Kuzmich}}
|}
 

= kde-baseapps =

{| cellspacing="0" cellpadding="5" border="1" style="border: 1px solid gray; border-collapse: collapse; text-align: left; width: 100%;" class="sortable"
|- style="background: rgb(236, 236, 236) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous; white-space: nowrap;"

! Status
! Project
! Description
! Contact

{{FeatureInProgress|Dolphin|Implement new view-engine for Dolphin 2.0 (see http://ppenz.blogspot.com/2011/08/introducing-dolphin-20.html)|peter.penz19@gmail.com|Peter Penz}}
|}
 

= kdeedu =

{| cellspacing="0" cellpadding="5" border="1" style="border: 1px solid gray; border-collapse: collapse; text-align: left; width: 100%;" class="sortable"
|- style="background: rgb(236, 236, 236) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous; white-space: nowrap;"

! Status
! Project
! Description
! Contact

{{FeatureInProgress|KTouch|New organisation of keyboard and lecture files according to languages|peter.ruethemann@gmail.com|Rüthemann Peter}}
{{FeatureInProgress|KTouch|New organisation of menu system: Training, Statistic, Settings|peter.ruethemann@gmail.com|Rüthemann Peter}}
{{FeatureTodo|KTouch|End of lecture statistics|peter.ruethemann@gmail.com|Rüthemann Peter}}
{{FeatureDone|Rocs|Alignment Actions to minimize crossing graph edges|cola@uni-paderborn.de|Andreas Cord-Landwehr}}
{{FeatureTodo|Rocs|Project Files to combine graphs and algorithms|cola@uni-paderborn.de|Andreas Cord-Landwehr}}
{{FeatureTodo|Rocs|Stepped Execution of Algorithms|cola@uni-paderborn.de|Andreas Cord-Landwehr}}
{{FeatureInProgress|Rocs|User Interface Cleanup|cola@uni-paderborn.de|Andreas Cord-Landwehr}}
{{FeatureInProgress|Cantor|Add Qalculate backend|matteo@agostinelli.me|Matteo Agostinelli}}
{{FeatureDone|Marble|Marble Runner plugins for Parsing files|tgridel@freedotfr|Thibaut Gridel}}
{{FeatureDone|Marble|(GSoC) OSM file rendering|oblaukhov.konstantin@gmail.com|Konstantin Oblaukhov}}
{{FeatureDone|Marble|Marble Graphics Scene (Performance of Vector Drawing)|oblaukhov.konstantin@gmail.com|Konstantin Oblaukhov}}
{{FeatureDone|Marble|Gps Info Plugin|tgridel@freedotfr|Thibaut Gridel}}
{{FeatureInProgress|Marble|Routing API|earthwings@gentoo.org|Dennis Nienhüser}}
|}
 

= kdepim =

{| cellspacing="0" cellpadding="5" border="1" style="border: 1px solid gray; border-collapse: collapse; text-align: left; width: 100%;" class="sortable"
|- style="background: rgb(236, 236, 236) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous; white-space: nowrap;"

! Status
! Project
! Description
! Contact

{{FeatureTodo
|attachment:/ kio-slave
|Implement kio-slave to access (email) attachments in Akonadi
|kossebau@kde.org|Friedrich W. H. Kossebau}}
{{FeatureInProgress|KAlarm|Port to Akonadi|djarvie@kde.org|David Jarvie}}

|}

 

= kdesdk =

{| cellspa/cing="0" cellpadding="5" border="1" style="border: 1px solid gray; border-collapse: collapse; text-align: left; width: 100%;" class="sortable"
|- style="background: rgb(236, 236, 236) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous; white-space: nowrap;"
! Status
! Project
! Description
! Contact
{{FeatureTodo|Okteta|Add a general KPart adapter to Kasten, than finish port of Okteta KPart to Okteta Kasten|kossebau@kde.org|Friedrich W. H. Kossebau}}
{{FeatureTodo|Okteta|Add global toggle option for the offset display, hex or decimal|kossebau@kde.org|Friedrich W. H. Kossebau}}
{{FeatureTodo|Okteta|Add Kate-like combined dialogs to query for actions on files|kossebau@kde.org|Friedrich W. H. Kossebau}}
{{FeatureTodo|Okteta|add Kate-like search tool|kossebau@kde.org|Friedrich W. H. Kossebau}}
{{FeatureTodo|Okteta|Add Okular like embedded notifications|kossebau@kde.org|Friedrich W. H. Kossebau}}
{{FeatureTodo|Okteta|add support for import by drop, both url and data|kossebau@kde.org|Friedrich W. H. Kossebau}}
{{FeatureTodo|Okteta|add support for memory mapping of files and 64-bit addressing|kossebau@kde.org|Friedrich W. H. Kossebau}}
{{FeatureTodo|Okteta|add support for jobs like io, printing, string search or filter|kossebau@kde.org|Friedrich W. H. Kossebau}}
{{FeatureTodo|Okteta|Add view profiles, incl. editor/manager|kossebau@kde.org|Friedrich W. H. Kossebau}}
{{FeatureTodo|Okteta|copy again puts also a value or char variant of the data to clipboard|kossebau@kde.org|Friedrich W. H. Kossebau}}
{{FeatureTodo|Okteta|Improve the titels of the changes to the bytearray to be more descriptive, best using ids to avoid text string|kossebau@kde.org|Friedrich W. H. Kossebau}}
{{FeatureTodo|Okteta|Make all user interaction in the KastenCore managers plugin-based|kossebau@kde.org|Friedrich W. H. Kossebau}}
{{FeatureTodo|Okteta|Merge row and column widgets into one|kossebau@kde.org|Friedrich W. H. Kossebau}}
{{FeatureTodo|Okteta|Store bookmarks|kossebau@kde.org|Friedrich W. H. Kossebau}}
{{FeatureTodo|Okteta|Store bookmarks and other view settings for next load|kossebau@kde.org|Friedrich W. H. Kossebau}}
|}
 

= kdegames=
{| cellspa/cing="0" cellpadding="5" border="1" style="border: 1px solid gray; border-collapse: collapse; text-align: left; width: 100%;" class="sortable"
|- style="background: rgb(236, 236, 236) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous; white-space: nowrap;"
! Status
! Project
! Description
! Contact
{{FeatureTodo|KSudoku|Description|iandw.au@gmail.com|Ian Wadham}}
|}

Development/Tutorials/Plasma/QML/API

2011-10-11T01:25:26Z

Icwiener: /* ServiceJob */ Fix typo.

= Introduction to the Plasmoid QML Declarative API =

This document provides an overview/reference of the Declarative QML API for Plasmoids. It isn't a full binding to all of Qt or KDE's libraries, but a focused set of bindings designed to make writing Plasmoids fast and easy, while remaining powerful.

The API in this documentation covers the API of the Plasma specific QML components, so only the Declarative part of the API.

The QML ScriptEngine is based upon the Plasma JavaScript engine, making the API of the JavaScript part identical to the one of the JavaScript plasmoids engine.
To see the api of the global ''Plasmoid'' object, see the [http://techbase.kde.org/Development/Tutorials/Plasma/JavaScript/API#The_Global_plasmoid_Object JavaScript API] documentation.
(TODO: the JavaScript api page should probably be copied and stripped down the imperative bits not present there, it would make it harder to update tough)

== What Is a Declarative Plasmoid? ==

To denote that this Plasmoid is a Declarative widget, ensure that in the metadata.desktop file there is this line:

X-Plasma-API=declarativeappletscript

What follows is a description of the Plasma declarative classes instantiable from QML.

= Main Plasma QML Classes =

== Data Engines ==
While it's possible to fetch data from a Plasma DataEngine in the same way as the [http://techbase.kde.org/Development/Tutorials/Plasma/JavaScript/API#DataEngine JavaScript API], it is preferrable to use the following declarative classes:

=== DataSource ===
DataSource is a receiver for a dataEngine and can be declared inside QML:

<syntaxhighlight lang="javascript">
import org.kde.plasma.core 0.1 as PlasmaCore

PlasmaCore.DataSource {
id: dataSource
engine: "time"
connectedSources: ["Local"]
interval: 500
}
</syntaxhighlight>

==== Properties ====
It has the following properties:
* bool '''valid''' (read only): true when the DataSource is successfully connected to a data engine
* int '''interval''': interval of polling of the dataengine, if 0 (default value, so no need to specify if you don't need it) no polling will be executed
* string '''engine''': the plugin name of the dataengine to load, e.g. "nowplaying", etc.
* Array(string) '''connectedSources''': all the sources of the dataengine we are connected to (and whose data will appear in the '''data''' property)
* Array(string) '''sources''' (read only): all the sources available from the dataengine
* variant map '''data''' (read only): It's the most important property, it's a map of all the data available from the dataengine: its structure will be as follows:
** each key of the map will be a source name, in '''connectedSources'''
** each value will be a variant hash, so an hash with strings as keys and any variant as value
** example: dataSource.data["Local"]["Time"] indicates the '''Time''' key of the dataengine source called "Local"

==== Signals ====
It has the following signals:

Note that javascript/qml applies the 'on' prefix to signals. So the actual signal name in C++ which is e.g. '''newData'''(...) becomes '''onNewData'''(...).

* '''onNewData'''(String sourceName, Plasma::DataEngine::Data data)
* '''onSourceAdded'''(String source)
* '''onSourceRemoved'''(String source)
* '''onSourceConnected'''(String source)
* '''onSourceDisconnected'''(String source)
* '''onIntervalChanged'''()
* '''onEngineChanged'''()
* '''onDataChanged'''()
* '''onConnectedSourcesChanged'''()
* '''onSourcesChanged'''()

==== Methods ====
It has the following methods:
* StringList keysForSource(String source): lists all the keys corresponding to a certain source: for instance in the "time" dataengine, for the "Local" source, keys will be:
** "Timezone Continent"
** "Offset"
** "Timezone"
** "Time"
** "Date"
** "Timezone City"
* Service serviceForSource(String source): returns a Plasma service that corresponds a given source: see the section about services for how to use it.
* void connectSource(String source): adds to '''connectedSources''' the new source
* void disconnectSource(String source): removes that source from '''connectedSources'''

=== Service ===
Due to their imperative nature, Plasma Services are not instantiated as QML classes, but rather created out of a '''DataSource''' with the method '''serviceForSource''' and used in the JavaScript portions of the QML files.
This following example is a simplified version from the Now Playing QML widget in the kdeexamples git repository:

<syntaxhighlight lang="javascript">
var service = dataSource.serviceForSource(activeSource)
var operation = service.operationDescription("seek")
operation.seconds = 10

var job = service.startOperationCall(operation)
</syntaxhighlight>
Here dataSource is the id of a DataSource object, and activeSource is a source contained in one of its '''connectedSources'''.
The service provides an operation called "seek", with a parameter called "seconds", that can be written on it as a property of a JavaScript object.

=== ServiceJob ===
It is necessary to monitor the result of a Service operation, it's possible to connect to the '''finished''' signal provided by the job return paramenter of the '''startOperationCall''' service method.
The '''finished''' signal has the same job as parameter, from which is possible to check the variant '''result''' property, to check the result.

=== DataModel ===
Some data engines return as their data something that can be interpreted as a list of items, rather than simple key/value pairs.
QML provides some item views such as '''ListView''', '''GridView''' and '''Repeater'''.
The '''DataModel''' QML object can provide, based on a DataSource a model suitable for those QML item views.

It has the following properties:
* DataSource '''dataSource''': the id of an existing (and connected) DataSource
* String '''sourceFilter''': it's a regular expression. If the DataSource is connected to more than one source, only inserts data from sources matching this filter expression in the model. To, for example, have a source watch all sources beginning with say "name:", the required regexp would be sourceFilter: "name:.*"
* String '''keyRoleFilter''': it's a regular expression. Only data with keys that match this filter expression will be inserted in the model
* int '''count''' (read only): how many items are in the model

Example:

<syntaxhighlight lang="javascript">
ListView {
model: PlasmaCore.DataModel {
dataSource: microblogSource
keyRoleFilter: "[\\d]*"
}
delegate: Text {
text: title
}
}
</syntaxhighlight>

In the example, ''microblogSource'' is the id of a DataSource, and inserts in the model only entries that have a number as the key name (matched with [\\d]*, in this case tweets ids)

Each item in the model will have the form of a variant hash: all the keys of the hash will be registered as model role names, in the example, "title" is a role of the model containing a string (also reachable with model["title"]).

A special reserved role will always be present: '''"DataEngineSource"''': it will contain the name of the data engine source that gave origin to this item. Therefore, if you want merely the string of the current source that the model is at...do model["DataEngineSource"].

Note that view.currentItem holds the item currently selected. However, due to (http://bugreports.qt.nokia.com/browse/QTBUG-16347) this does not work in PathView. A workaround is to make your own.

=== SortFilterModel ===
SortFilterModel is a proxy model for easy sorting and/or filtering of the items in a DataModel (or any other QAbstractItemModel subclass that has been registered in QML with setContextProperty from a C++ application)
Properties:
* model '''sourceModel'''
* String '''filterRegExp'''
* String '''filterRole'''
* String '''sortRole'''
* Qt::SortOrder '''sortOrder'''
* int '''count''' (read only)

== Popup Applet ==
So you want your QML applet to be a popup applet, like the device notifier (an icon in the panel shows and expands the applet)?

Why, that's easy.

To change your plasmoid from being a regular boring one, in your '''metadata.desktop''', simply change this following line:

<syntaxhighlight lang="ini">
ServiceTypes=Plasma/Applet
</syntaxhighlight>

To:

<syntaxhighlight lang="ini">
ServiceTypes=Plasma/Applet,Plasma/PopupApplet
</syntaxhighlight>

Then in the main QML item's Component.onCompleted, do:

NOTE: the below code presently has no affect, yet the icons seems to get retrieved from the desktop file (FIXME - is this needed? It has no affect presently).

<syntaxhighlight lang="javascript">
plasmoid.popupIcon("konqueror")
</syntaxhighlight>

== Plasma Themes ==

=== Theme ===
This class instantiable from QML provides access to the Plasma Theme colors and other facilities such as fonts.
It has the following properties:
* String '''themeName''' (read only)
* QFont '''font''' (read only)
* bool '''windowTranslucentEnabled''' (read only)
* Url '''homepage''' (read only)
* bool '''useGlobalSettings''' (read only)
* QString '''wallpaperPath''' (read only)
* color '''textColor''' (read only)
* color '''highlightColor''' (read only)
* color '''backgroundColor''' (read only)
* color '''buttonTextColor''' (read only)
* color '''buttonBackgroundColor''' (read only)
* color '''linkColor''' (read only)
* color '''visitedLinkColor''' (read only)
* color '''visitedLinkColor''' (read only)
* color '''buttonHoverColor''' (read only)
* color '''buttonFocusColor''' (read only)
* color '''viewTextColor''' (read only)
* color '''viewBackgroundColor''' (read only)
* color '''viewHoverColor''' (read only)
* color '''viewFocusColor''' (read only)
* String '''styleSheet''' (read only)

=== Svg ===
Declaring a Svg element instantiates a Plasma Svg instance. This class doesn't draw anything. For drawing, SvgItem is used.
Properties:
* QSize '''size'''
* bool '''multipleImages'''
* String '''imagePath''' can be anything in the '''desktoptheme/''' folder. For more information on what is available, see [http://techbase.kde.org/Projects/Plasma/Theme#Current_Theme_Elements Plasma Theme Elements]
* bool '''usingRenderingCache'''

Methods:
* QPixmap pixmap(QString elementID)
* void resize(qreal width, qreal height)
* void resize(): resets the image to its default dimension
* QSize elementSize(QString elementId)
* QRectF elementRect(QString elementId)
* bool hasElement(QString elementId)
* bool isValid(): true if valid svg file

Sample Code:
<syntaxhighlight lang="javascript">
PlasmaCore.Svg {
id: mySvg
imagePath: "widgets/line"
}
</syntaxhighlight>

=== SvgItem ===
It's a graphical element that will actually paint a Svg instance.
Properties:
* String '''elementId''': what element to render. If null, the whole svg will be rendered
* Svg '''svg''': instance of the Svg class mentioned above
* QSizeF '''naturalSize''' (read only): default size of the Svg
* bool '''smooth''': paint with antialias (default false)

Sample Code:

<syntaxhighlight lang="javascript">
PlasmaCore.SvgItem {
id: mySvgItem
anchors {
top: parent.top
left: parent.left
}

width: 300
height: 3

svg: mySvg
elementId: "horizontal-line"
}
</syntaxhighlight>

=== FrameSvgItem ===
It's a graphical element that paints a Plasma::FrameSvg, so a rectangular image composed by 9 elements contained in a Svg file, useful for things like buttons and frames.

Flags
* EnabledBorders: combination of TopBorder | BottomBorder | LeftBorder | RightBorder, NoBorder if no border of the frame is enabled

Properties:
* String '''imagePath''': path of the file relative to the Plasma Theme, for instance "widgets/background"
* String '''prefix''': a FrameSvg can contain multiple frames, for instance a button contains "normal", "raised" and "pressed"
* Margins '''margins''' (read only): the margins of the frame, see documentation below
* EnabledBorders '''enabledBorders''': what borders are enabled

==== Margins ====
Properties:
* real '''left''' (read only)
* real '''top''' (read only)
* real '''right''' (read only)
* real '''bottom''' (read only)

Sample Code:

<syntaxhighlight lang="javascript">
PlasmaCore.FrameSvgItem {
id: myFrameSvgItem
anchors.fill: parent
imagePath: "translucent/dialogs/background"
}
</syntaxhighlight>

== Top Level windows ==

=== Dialog ===
Dialog instantiates a Plasma::Dialog, it will be a Plasma themed top level window that can contain any QML component.

Properties:
* Item mainItem: the Item contained in the Dialog, it can be any QML Item instance
* bool '''visible''': if the window (not the mainItem) is visible
* int '''x''': x position of the window in screen coordinates
* int '''y''': y position of the window in screen coordinates
* int '''width''' (read only): total width of the dialog, including margins
* int '''height''' (read only): total height of the dialog, including margins
* int '''windowFlags''': Qt window flags of the Dialog
* Margins '''margins''' (read only): margins of the Dialog

Methods:
* QPoint popupPosition(Item item, Qt::Alignment alignment=Qt::AlignLeft): the suggested position for the Dialog if it has to be correctly placed as popup of the QML item passed as parameter.
* void setAttribute(Qt::WindowAttribute attribute, bool on): set an attribute for the dialog window

==== Margins ====
Properties:
* real '''left''' (read only)
* real '''top''' (read only)
* real '''right''' (read only)
* real '''bottom''' (read only)

=== ToolTip ===
Declaring a ToolTip instance makes it possible to use Plasma tooltips with any QML item.

Properties:
* Item '''target''': the QML item we want to show a tooltip of
* String '''mainText'''
* String '''subText'''
* String '''image''': freedesktop compliant icon name as image of the tooltip

= Plasma QtComponents (4.8) =
TODO

Development/Tutorials/Plasma/QML/API

2011-10-11T01:21:43Z

Icwiener: /* Signals */ Fix markup.

= Introduction to the Plasmoid QML Declarative API =

This document provides an overview/reference of the Declarative QML API for Plasmoids. It isn't a full binding to all of Qt or KDE's libraries, but a focused set of bindings designed to make writing Plasmoids fast and easy, while remaining powerful.

The API in this documentation covers the API of the Plasma specific QML components, so only the Declarative part of the API.

The QML ScriptEngine is based upon the Plasma JavaScript engine, making the API of the JavaScript part identical to the one of the JavaScript plasmoids engine.
To see the api of the global ''Plasmoid'' object, see the [http://techbase.kde.org/Development/Tutorials/Plasma/JavaScript/API#The_Global_plasmoid_Object JavaScript API] documentation.
(TODO: the JavaScript api page should probably be copied and stripped down the imperative bits not present there, it would make it harder to update tough)

== What Is a Declarative Plasmoid? ==

To denote that this Plasmoid is a Declarative widget, ensure that in the metadata.desktop file there is this line:

X-Plasma-API=declarativeappletscript

What follows is a description of the Plasma declarative classes instantiable from QML.

= Main Plasma QML Classes =

== Data Engines ==
While it's possible to fetch data from a Plasma DataEngine in the same way as the [http://techbase.kde.org/Development/Tutorials/Plasma/JavaScript/API#DataEngine JavaScript API], it is preferrable to use the following declarative classes:

=== DataSource ===
DataSource is a receiver for a dataEngine and can be declared inside QML:

<syntaxhighlight lang="javascript">
import org.kde.plasma.core 0.1 as PlasmaCore

PlasmaCore.DataSource {
id: dataSource
engine: "time"
connectedSources: ["Local"]
interval: 500
}
</syntaxhighlight>

==== Properties ====
It has the following properties:
* bool '''valid''' (read only): true when the DataSource is successfully connected to a data engine
* int '''interval''': interval of polling of the dataengine, if 0 (default value, so no need to specify if you don't need it) no polling will be executed
* string '''engine''': the plugin name of the dataengine to load, e.g. "nowplaying", etc.
* Array(string) '''connectedSources''': all the sources of the dataengine we are connected to (and whose data will appear in the '''data''' property)
* Array(string) '''sources''' (read only): all the sources available from the dataengine
* variant map '''data''' (read only): It's the most important property, it's a map of all the data available from the dataengine: its structure will be as follows:
** each key of the map will be a source name, in '''connectedSources'''
** each value will be a variant hash, so an hash with strings as keys and any variant as value
** example: dataSource.data["Local"]["Time"] indicates the '''Time''' key of the dataengine source called "Local"

==== Signals ====
It has the following signals:

Note that javascript/qml applies the 'on' prefix to signals. So the actual signal name in C++ which is e.g. '''newData'''(...) becomes '''onNewData'''(...).

* '''onNewData'''(String sourceName, Plasma::DataEngine::Data data)
* '''onSourceAdded'''(String source)
* '''onSourceRemoved'''(String source)
* '''onSourceConnected'''(String source)
* '''onSourceDisconnected'''(String source)
* '''onIntervalChanged'''()
* '''onEngineChanged'''()
* '''onDataChanged'''()
* '''onConnectedSourcesChanged'''()
* '''onSourcesChanged'''()

==== Methods ====
It has the following methods:
* StringList keysForSource(String source): lists all the keys corresponding to a certain source: for instance in the "time" dataengine, for the "Local" source, keys will be:
** "Timezone Continent"
** "Offset"
** "Timezone"
** "Time"
** "Date"
** "Timezone City"
* Service serviceForSource(String source): returns a Plasma service that corresponds a given source: see the section about services for how to use it.
* void connectSource(String source): adds to '''connectedSources''' the new source
* void disconnectSource(String source): removes that source from '''connectedSources'''

=== Service ===
Due to their imperative nature, Plasma Services are not instantiated as QML classes, but rather created out of a '''DataSource''' with the method '''serviceForSource''' and used in the JavaScript portions of the QML files.
This following example is a simplified version from the Now Playing QML widget in the kdeexamples git repository:

<syntaxhighlight lang="javascript">
var service = dataSource.serviceForSource(activeSource)
var operation = service.operationDescription("seek")
operation.seconds = 10

var job = service.startOperationCall(operation)
</syntaxhighlight>
Here dataSource is the id of a DataSource object, and activeSource is a source contained in one of its '''connectedSources'''.
The service provides an operation called "seek", with a parameter called "seconds", that can be written on it as a property of a JavaScript object.

=== ServiceJob ===
If is necessary to monitor the result of a Service operation, it's possible to connect to the '''finished''' signal provided by the job return paramenter of the '''startOperationCall''' service method.
The '''finished''' signal has the same job as parameter, from which is possible to check the variant '''result''' property, to check the result.

=== DataModel ===
Some data engines return as their data something that can be interpreted as a list of items, rather than simple key/value pairs.
QML provides some item views such as '''ListView''', '''GridView''' and '''Repeater'''.
The '''DataModel''' QML object can provide, based on a DataSource a model suitable for those QML item views.

It has the following properties:
* DataSource '''dataSource''': the id of an existing (and connected) DataSource
* String '''sourceFilter''': it's a regular expression. If the DataSource is connected to more than one source, only inserts data from sources matching this filter expression in the model. To, for example, have a source watch all sources beginning with say "name:", the required regexp would be sourceFilter: "name:.*"
* String '''keyRoleFilter''': it's a regular expression. Only data with keys that match this filter expression will be inserted in the model
* int '''count''' (read only): how many items are in the model

Example:

<syntaxhighlight lang="javascript">
ListView {
model: PlasmaCore.DataModel {
dataSource: microblogSource
keyRoleFilter: "[\\d]*"
}
delegate: Text {
text: title
}
}
</syntaxhighlight>

In the example, ''microblogSource'' is the id of a DataSource, and inserts in the model only entries that have a number as the key name (matched with [\\d]*, in this case tweets ids)

Each item in the model will have the form of a variant hash: all the keys of the hash will be registered as model role names, in the example, "title" is a role of the model containing a string (also reachable with model["title"]).

A special reserved role will always be present: '''"DataEngineSource"''': it will contain the name of the data engine source that gave origin to this item. Therefore, if you want merely the string of the current source that the model is at...do model["DataEngineSource"].

Note that view.currentItem holds the item currently selected. However, due to (http://bugreports.qt.nokia.com/browse/QTBUG-16347) this does not work in PathView. A workaround is to make your own.

=== SortFilterModel ===
SortFilterModel is a proxy model for easy sorting and/or filtering of the items in a DataModel (or any other QAbstractItemModel subclass that has been registered in QML with setContextProperty from a C++ application)
Properties:
* model '''sourceModel'''
* String '''filterRegExp'''
* String '''filterRole'''
* String '''sortRole'''
* Qt::SortOrder '''sortOrder'''
* int '''count''' (read only)

== Popup Applet ==
So you want your QML applet to be a popup applet, like the device notifier (an icon in the panel shows and expands the applet)?

Why, that's easy.

To change your plasmoid from being a regular boring one, in your '''metadata.desktop''', simply change this following line:

<syntaxhighlight lang="ini">
ServiceTypes=Plasma/Applet
</syntaxhighlight>

To:

<syntaxhighlight lang="ini">
ServiceTypes=Plasma/Applet,Plasma/PopupApplet
</syntaxhighlight>

Then in the main QML item's Component.onCompleted, do:

NOTE: the below code presently has no affect, yet the icons seems to get retrieved from the desktop file (FIXME - is this needed? It has no affect presently).

<syntaxhighlight lang="javascript">
plasmoid.popupIcon("konqueror")
</syntaxhighlight>

== Plasma Themes ==

=== Theme ===
This class instantiable from QML provides access to the Plasma Theme colors and other facilities such as fonts.
It has the following properties:
* String '''themeName''' (read only)
* QFont '''font''' (read only)
* bool '''windowTranslucentEnabled''' (read only)
* Url '''homepage''' (read only)
* bool '''useGlobalSettings''' (read only)
* QString '''wallpaperPath''' (read only)
* color '''textColor''' (read only)
* color '''highlightColor''' (read only)
* color '''backgroundColor''' (read only)
* color '''buttonTextColor''' (read only)
* color '''buttonBackgroundColor''' (read only)
* color '''linkColor''' (read only)
* color '''visitedLinkColor''' (read only)
* color '''visitedLinkColor''' (read only)
* color '''buttonHoverColor''' (read only)
* color '''buttonFocusColor''' (read only)
* color '''viewTextColor''' (read only)
* color '''viewBackgroundColor''' (read only)
* color '''viewHoverColor''' (read only)
* color '''viewFocusColor''' (read only)
* String '''styleSheet''' (read only)

=== Svg ===
Declaring a Svg element instantiates a Plasma Svg instance. This class doesn't draw anything. For drawing, SvgItem is used.
Properties:
* QSize '''size'''
* bool '''multipleImages'''
* String '''imagePath''' can be anything in the '''desktoptheme/''' folder. For more information on what is available, see [http://techbase.kde.org/Projects/Plasma/Theme#Current_Theme_Elements Plasma Theme Elements]
* bool '''usingRenderingCache'''

Methods:
* QPixmap pixmap(QString elementID)
* void resize(qreal width, qreal height)
* void resize(): resets the image to its default dimension
* QSize elementSize(QString elementId)
* QRectF elementRect(QString elementId)
* bool hasElement(QString elementId)
* bool isValid(): true if valid svg file

Sample Code:
<syntaxhighlight lang="javascript">
PlasmaCore.Svg {
id: mySvg
imagePath: "widgets/line"
}
</syntaxhighlight>

=== SvgItem ===
It's a graphical element that will actually paint a Svg instance.
Properties:
* String '''elementId''': what element to render. If null, the whole svg will be rendered
* Svg '''svg''': instance of the Svg class mentioned above
* QSizeF '''naturalSize''' (read only): default size of the Svg
* bool '''smooth''': paint with antialias (default false)

Sample Code:

<syntaxhighlight lang="javascript">
PlasmaCore.SvgItem {
id: mySvgItem
anchors {
top: parent.top
left: parent.left
}

width: 300
height: 3

svg: mySvg
elementId: "horizontal-line"
}
</syntaxhighlight>

=== FrameSvgItem ===
It's a graphical element that paints a Plasma::FrameSvg, so a rectangular image composed by 9 elements contained in a Svg file, useful for things like buttons and frames.

Flags
* EnabledBorders: combination of TopBorder | BottomBorder | LeftBorder | RightBorder, NoBorder if no border of the frame is enabled

Properties:
* String '''imagePath''': path of the file relative to the Plasma Theme, for instance "widgets/background"
* String '''prefix''': a FrameSvg can contain multiple frames, for instance a button contains "normal", "raised" and "pressed"
* Margins '''margins''' (read only): the margins of the frame, see documentation below
* EnabledBorders '''enabledBorders''': what borders are enabled

==== Margins ====
Properties:
* real '''left''' (read only)
* real '''top''' (read only)
* real '''right''' (read only)
* real '''bottom''' (read only)

Sample Code:

<syntaxhighlight lang="javascript">
PlasmaCore.FrameSvgItem {
id: myFrameSvgItem
anchors.fill: parent
imagePath: "translucent/dialogs/background"
}
</syntaxhighlight>

== Top Level windows ==

=== Dialog ===
Dialog instantiates a Plasma::Dialog, it will be a Plasma themed top level window that can contain any QML component.

Properties:
* Item mainItem: the Item contained in the Dialog, it can be any QML Item instance
* bool '''visible''': if the window (not the mainItem) is visible
* int '''x''': x position of the window in screen coordinates
* int '''y''': y position of the window in screen coordinates
* int '''width''' (read only): total width of the dialog, including margins
* int '''height''' (read only): total height of the dialog, including margins
* int '''windowFlags''': Qt window flags of the Dialog
* Margins '''margins''' (read only): margins of the Dialog

Methods:
* QPoint popupPosition(Item item, Qt::Alignment alignment=Qt::AlignLeft): the suggested position for the Dialog if it has to be correctly placed as popup of the QML item passed as parameter.
* void setAttribute(Qt::WindowAttribute attribute, bool on): set an attribute for the dialog window

==== Margins ====
Properties:
* real '''left''' (read only)
* real '''top''' (read only)
* real '''right''' (read only)
* real '''bottom''' (read only)

=== ToolTip ===
Declaring a ToolTip instance makes it possible to use Plasma tooltips with any QML item.

Properties:
* Item '''target''': the QML item we want to show a tooltip of
* String '''mainText'''
* String '''subText'''
* String '''image''': freedesktop compliant icon name as image of the tooltip

= Plasma QtComponents (4.8) =
TODO

Development/Tutorials/Plasma/QML/API

2011-10-11T01:19:49Z

Icwiener: /* Introduction to the Plasmoid QML Declarative API */ Fix typos.

= Introduction to the Plasmoid QML Declarative API =

This document provides an overview/reference of the Declarative QML API for Plasmoids. It isn't a full binding to all of Qt or KDE's libraries, but a focused set of bindings designed to make writing Plasmoids fast and easy, while remaining powerful.

The API in this documentation covers the API of the Plasma specific QML components, so only the Declarative part of the API.

The QML ScriptEngine is based upon the Plasma JavaScript engine, making the API of the JavaScript part identical to the one of the JavaScript plasmoids engine.
To see the api of the global ''Plasmoid'' object, see the [http://techbase.kde.org/Development/Tutorials/Plasma/JavaScript/API#The_Global_plasmoid_Object JavaScript API] documentation.
(TODO: the JavaScript api page should probably be copied and stripped down the imperative bits not present there, it would make it harder to update tough)

== What Is a Declarative Plasmoid? ==

To denote that this Plasmoid is a Declarative widget, ensure that in the metadata.desktop file there is this line:

X-Plasma-API=declarativeappletscript

What follows is a description of the Plasma declarative classes instantiable from QML.

= Main Plasma QML Classes =

== Data Engines ==
While it's possible to fetch data from a Plasma DataEngine in the same way as the [http://techbase.kde.org/Development/Tutorials/Plasma/JavaScript/API#DataEngine JavaScript API], it is preferrable to use the following declarative classes:

=== DataSource ===
DataSource is a receiver for a dataEngine and can be declared inside QML:

<syntaxhighlight lang="javascript">
import org.kde.plasma.core 0.1 as PlasmaCore

PlasmaCore.DataSource {
id: dataSource
engine: "time"
connectedSources: ["Local"]
interval: 500
}
</syntaxhighlight>

==== Properties ====
It has the following properties:
* bool '''valid''' (read only): true when the DataSource is successfully connected to a data engine
* int '''interval''': interval of polling of the dataengine, if 0 (default value, so no need to specify if you don't need it) no polling will be executed
* string '''engine''': the plugin name of the dataengine to load, e.g. "nowplaying", etc.
* Array(string) '''connectedSources''': all the sources of the dataengine we are connected to (and whose data will appear in the '''data''' property)
* Array(string) '''sources''' (read only): all the sources available from the dataengine
* variant map '''data''' (read only): It's the most important property, it's a map of all the data available from the dataengine: its structure will be as follows:
** each key of the map will be a source name, in '''connectedSources'''
** each value will be a variant hash, so an hash with strings as keys and any variant as value
** example: dataSource.data["Local"]["Time"] indicates the '''Time''' key of the dataengine source called "Local"

==== Signals ====
It has the following signals:

Note that javascript/qml applies the 'on' prefix to signals. So the actual signal name in C++ which is e.g. '''newData''(...) becomes '''onNewData'''(...).

* '''onNewData'''(String sourceName, Plasma::DataEngine::Data data)
* '''onSourceAdded'''(String source)
* '''onSourceRemoved'''(String source)
* '''onSourceConnected'''(String source)
* '''onSourceDisconnected'''(String source)
* '''onIntervalChanged'''()
* '''onEngineChanged'''()
* '''onDataChanged'''()
* '''onConnectedSourcesChanged'''()
* '''onSourcesChanged'''()

==== Methods ====
It has the following methods:
* StringList keysForSource(String source): lists all the keys corresponding to a certain source: for instance in the "time" dataengine, for the "Local" source, keys will be:
** "Timezone Continent"
** "Offset"
** "Timezone"
** "Time"
** "Date"
** "Timezone City"
* Service serviceForSource(String source): returns a Plasma service that corresponds a given source: see the section about services for how to use it.
* void connectSource(String source): adds to '''connectedSources''' the new source
* void disconnectSource(String source): removes that source from '''connectedSources'''

=== Service ===
Due to their imperative nature, Plasma Services are not instantiated as QML classes, but rather created out of a '''DataSource''' with the method '''serviceForSource''' and used in the JavaScript portions of the QML files.
This following example is a simplified version from the Now Playing QML widget in the kdeexamples git repository:

<syntaxhighlight lang="javascript">
var service = dataSource.serviceForSource(activeSource)
var operation = service.operationDescription("seek")
operation.seconds = 10

var job = service.startOperationCall(operation)
</syntaxhighlight>
Here dataSource is the id of a DataSource object, and activeSource is a source contained in one of its '''connectedSources'''.
The service provides an operation called "seek", with a parameter called "seconds", that can be written on it as a property of a JavaScript object.

=== ServiceJob ===
If is necessary to monitor the result of a Service operation, it's possible to connect to the '''finished''' signal provided by the job return paramenter of the '''startOperationCall''' service method.
The '''finished''' signal has the same job as parameter, from which is possible to check the variant '''result''' property, to check the result.

=== DataModel ===
Some data engines return as their data something that can be interpreted as a list of items, rather than simple key/value pairs.
QML provides some item views such as '''ListView''', '''GridView''' and '''Repeater'''.
The '''DataModel''' QML object can provide, based on a DataSource a model suitable for those QML item views.

It has the following properties:
* DataSource '''dataSource''': the id of an existing (and connected) DataSource
* String '''sourceFilter''': it's a regular expression. If the DataSource is connected to more than one source, only inserts data from sources matching this filter expression in the model. To, for example, have a source watch all sources beginning with say "name:", the required regexp would be sourceFilter: "name:.*"
* String '''keyRoleFilter''': it's a regular expression. Only data with keys that match this filter expression will be inserted in the model
* int '''count''' (read only): how many items are in the model

Example:

<syntaxhighlight lang="javascript">
ListView {
model: PlasmaCore.DataModel {
dataSource: microblogSource
keyRoleFilter: "[\\d]*"
}
delegate: Text {
text: title
}
}
</syntaxhighlight>

In the example, ''microblogSource'' is the id of a DataSource, and inserts in the model only entries that have a number as the key name (matched with [\\d]*, in this case tweets ids)

Each item in the model will have the form of a variant hash: all the keys of the hash will be registered as model role names, in the example, "title" is a role of the model containing a string (also reachable with model["title"]).

A special reserved role will always be present: '''"DataEngineSource"''': it will contain the name of the data engine source that gave origin to this item. Therefore, if you want merely the string of the current source that the model is at...do model["DataEngineSource"].

Note that view.currentItem holds the item currently selected. However, due to (http://bugreports.qt.nokia.com/browse/QTBUG-16347) this does not work in PathView. A workaround is to make your own.

=== SortFilterModel ===
SortFilterModel is a proxy model for easy sorting and/or filtering of the items in a DataModel (or any other QAbstractItemModel subclass that has been registered in QML with setContextProperty from a C++ application)
Properties:
* model '''sourceModel'''
* String '''filterRegExp'''
* String '''filterRole'''
* String '''sortRole'''
* Qt::SortOrder '''sortOrder'''
* int '''count''' (read only)

== Popup Applet ==
So you want your QML applet to be a popup applet, like the device notifier (an icon in the panel shows and expands the applet)?

Why, that's easy.

To change your plasmoid from being a regular boring one, in your '''metadata.desktop''', simply change this following line:

<syntaxhighlight lang="ini">
ServiceTypes=Plasma/Applet
</syntaxhighlight>

To:

<syntaxhighlight lang="ini">
ServiceTypes=Plasma/Applet,Plasma/PopupApplet
</syntaxhighlight>

Then in the main QML item's Component.onCompleted, do:

NOTE: the below code presently has no affect, yet the icons seems to get retrieved from the desktop file (FIXME - is this needed? It has no affect presently).

<syntaxhighlight lang="javascript">
plasmoid.popupIcon("konqueror")
</syntaxhighlight>

== Plasma Themes ==

=== Theme ===
This class instantiable from QML provides access to the Plasma Theme colors and other facilities such as fonts.
It has the following properties:
* String '''themeName''' (read only)
* QFont '''font''' (read only)
* bool '''windowTranslucentEnabled''' (read only)
* Url '''homepage''' (read only)
* bool '''useGlobalSettings''' (read only)
* QString '''wallpaperPath''' (read only)
* color '''textColor''' (read only)
* color '''highlightColor''' (read only)
* color '''backgroundColor''' (read only)
* color '''buttonTextColor''' (read only)
* color '''buttonBackgroundColor''' (read only)
* color '''linkColor''' (read only)
* color '''visitedLinkColor''' (read only)
* color '''visitedLinkColor''' (read only)
* color '''buttonHoverColor''' (read only)
* color '''buttonFocusColor''' (read only)
* color '''viewTextColor''' (read only)
* color '''viewBackgroundColor''' (read only)
* color '''viewHoverColor''' (read only)
* color '''viewFocusColor''' (read only)
* String '''styleSheet''' (read only)

=== Svg ===
Declaring a Svg element instantiates a Plasma Svg instance. This class doesn't draw anything. For drawing, SvgItem is used.
Properties:
* QSize '''size'''
* bool '''multipleImages'''
* String '''imagePath''' can be anything in the '''desktoptheme/''' folder. For more information on what is available, see [http://techbase.kde.org/Projects/Plasma/Theme#Current_Theme_Elements Plasma Theme Elements]
* bool '''usingRenderingCache'''

Methods:
* QPixmap pixmap(QString elementID)
* void resize(qreal width, qreal height)
* void resize(): resets the image to its default dimension
* QSize elementSize(QString elementId)
* QRectF elementRect(QString elementId)
* bool hasElement(QString elementId)
* bool isValid(): true if valid svg file

Sample Code:
<syntaxhighlight lang="javascript">
PlasmaCore.Svg {
id: mySvg
imagePath: "widgets/line"
}
</syntaxhighlight>

=== SvgItem ===
It's a graphical element that will actually paint a Svg instance.
Properties:
* String '''elementId''': what element to render. If null, the whole svg will be rendered
* Svg '''svg''': instance of the Svg class mentioned above
* QSizeF '''naturalSize''' (read only): default size of the Svg
* bool '''smooth''': paint with antialias (default false)

Sample Code:

<syntaxhighlight lang="javascript">
PlasmaCore.SvgItem {
id: mySvgItem
anchors {
top: parent.top
left: parent.left
}

width: 300
height: 3

svg: mySvg
elementId: "horizontal-line"
}
</syntaxhighlight>

=== FrameSvgItem ===
It's a graphical element that paints a Plasma::FrameSvg, so a rectangular image composed by 9 elements contained in a Svg file, useful for things like buttons and frames.

Flags
* EnabledBorders: combination of TopBorder | BottomBorder | LeftBorder | RightBorder, NoBorder if no border of the frame is enabled

Properties:
* String '''imagePath''': path of the file relative to the Plasma Theme, for instance "widgets/background"
* String '''prefix''': a FrameSvg can contain multiple frames, for instance a button contains "normal", "raised" and "pressed"
* Margins '''margins''' (read only): the margins of the frame, see documentation below
* EnabledBorders '''enabledBorders''': what borders are enabled

==== Margins ====
Properties:
* real '''left''' (read only)
* real '''top''' (read only)
* real '''right''' (read only)
* real '''bottom''' (read only)

Sample Code:

<syntaxhighlight lang="javascript">
PlasmaCore.FrameSvgItem {
id: myFrameSvgItem
anchors.fill: parent
imagePath: "translucent/dialogs/background"
}
</syntaxhighlight>

== Top Level windows ==

=== Dialog ===
Dialog instantiates a Plasma::Dialog, it will be a Plasma themed top level window that can contain any QML component.

Properties:
* Item mainItem: the Item contained in the Dialog, it can be any QML Item instance
* bool '''visible''': if the window (not the mainItem) is visible
* int '''x''': x position of the window in screen coordinates
* int '''y''': y position of the window in screen coordinates
* int '''width''' (read only): total width of the dialog, including margins
* int '''height''' (read only): total height of the dialog, including margins
* int '''windowFlags''': Qt window flags of the Dialog
* Margins '''margins''' (read only): margins of the Dialog

Methods:
* QPoint popupPosition(Item item, Qt::Alignment alignment=Qt::AlignLeft): the suggested position for the Dialog if it has to be correctly placed as popup of the QML item passed as parameter.
* void setAttribute(Qt::WindowAttribute attribute, bool on): set an attribute for the dialog window

==== Margins ====
Properties:
* real '''left''' (read only)
* real '''top''' (read only)
* real '''right''' (read only)
* real '''bottom''' (read only)

=== ToolTip ===
Declaring a ToolTip instance makes it possible to use Plasma tooltips with any QML item.

Properties:
* Item '''target''': the QML item we want to show a tooltip of
* String '''mainText'''
* String '''subText'''
* String '''image''': freedesktop compliant icon name as image of the tooltip

= Plasma QtComponents (4.8) =
TODO

Development/Tutorials/Plasma/QML/GettingStarted

2011-10-11T00:21:58Z

Icwiener: /* Package Structure */ Fix bullet points.

== Abstract ==

Writing a plasma applet in QML is very easy, in fact, with KDE 4.6 and Qt 4.7 it just works.

== QML Basics ==

It is recommended that you have read through the [http://doc.qt.nokia.com/4.7/qtquick.html Qt QML Tutorials], as there are quite a few and they are explained thoroughly. There is also a list of all [http://doc.qt.nokia.com/4.7/qdeclarativeelements.html standard QML elements].

Essentially, most of the content is the same. The exceptions to be noted are how data is gathered...since we use Data Engines, it is a bit different. Text color and font should be made to use PlasmaCore.Theme.

See the [https://projects.kde.org/projects/kde/kdeexamples/repository KDE Examples] repository for more KDE-related helpful resources. Also of use (which use QML and Plasma) are: [https://projects.kde.org/projects/playground/base/plasma-mobile/repository Plasma Mobile], [https://projects.kde.org/projects/playground/base/declarative-plasmoids/repository Declarative Plasmoids (playground)], for WIP ports of C++ originals

=== Root Item ===

The root item can be anything that inherits QGraphicsItem. For example, in this case it is QGraphicsWidget which is a plasmoid. It can also simply be an Item. I also noticed that PathView does not respond to mouse inputs automatically (so flicking doesn't work). Probably because events are being intercepted. So take note, it'll have to be e.g. an Item, for that case.

=== Layouts ===

==== Row and Column ====

==== Anchors ====
Anchor layouts offer a nice way of grouping UI elements nicely together. The idea is that you connect edges or corners of one element to the edge or corner of another widget.
Some examples:
<syntaxhighlight lang="javascript">
import QtQuick 1.0
import org.kde.plasma.core 0.1 as PlasmaCore

Item {
width: 200
height: 300

Text {
id: first
text: i18n("1st line")
anchors {
top: parent.top;
left: parent.left;
right: parent.right;
}
}
Text {
id: second
text: i18n("2nd line")
anchors {
top: first.bottom;
left: parent.left;
right: parent.right;
bottom: parent.bottom;
}
}
}
</syntaxhighlight>

=== Buttons ===

=== Animations ===

== Package Structure ==

You create a .desktop file and the .qml file. They have to be in the usual plasma package structure:

* plasmoid-qml/metadata.desktop
* plasmoid-qml/contents/ui/main.qml

=== <tt>metadata.desktop</tt> ===
<syntaxhighlight lang="ini">
[Desktop Entry]
Name=Hello QML
Comment=A hello world widget in QML
Icon=chronometer

X-Plasma-API=declarativeappletscript
X-Plasma-MainScript=ui/main.qml
X-Plasma-DefaultSize=200,100

X-KDE-PluginInfo-Author=Frederik Gladhorn
X-KDE-PluginInfo-Email=gladhorn@kde.org
X-KDE-PluginInfo-Website=http://plasma.kde.org/
X-KDE-PluginInfo-Category=Examples
X-KDE-PluginInfo-Name=org.kde.hello-qml
X-KDE-PluginInfo-Version=0.0

X-KDE-PluginInfo-Depends=
X-KDE-PluginInfo-License=GPL
X-KDE-PluginInfo-EnabledByDefault=true
X-KDE-ServiceTypes=Plasma/Applet
Type=Service
</syntaxhighlight>

The line below indicates the default size of the plasmoid. The applet's starting size will be this, when added to a scene:

<syntaxhighlight lang="ini">
X-Plasma-DefaultSize=200,100
</syntaxhighlight>

=== <tt>main.qml</tt> ===
<syntaxhighlight lang="javascript">
import QtQuick 1.0

Text {
text: "Hello world!";
}
</syntaxhighlight>

== Installing ==
You can install your plasmoid, though obviously this is just temporary. CMake, below, is recommended:
<syntaxhighlight lang="bash">
plasmapkg --install plasmoid-qml
</syntaxhighlight>

=== Installation through CMake ===
In your CMakeLists.txt:

<syntaxhighlight lang="cmake">
project(helloqml)

install(DIRECTORY package/
DESTINATION ${DATA_INSTALL_DIR}/plasma/plasmoids/org.kde.plasma.applet.myapplet)

install(FILES package/metadata.desktop
DESTINATION ${SERVICES_INSTALL_DIR} RENAME plasma-applet-myapplet.desktop)
</syntaxhighlight>

Your directory structure should now be as follows:

<syntaxhighlight lang="bash">
myproject/CMakeLists.txt
myproject/package/
myproject/package/metadata.desktop
myproject/package/contents/
myproject/package/contents/ui/
myproject/package/contents/ui/helloworld.qml
</syntaxhighlight>

(if you have a configuration file (.ui file) to load the right-click 'plasmoid settings' menu, then your structure will also have myproject/package/contents/config/config.ui, or so)

== plasmoidviewer ==
You can run it in plasmoidviewer as usual:
plasmoidviewer plasmoid-qml

== qmlviewer ==
It's possible to use Plasma specific imports in qml files loaded by qmlviewer:

qmlviewer -I /usr/lib/kde4/imports/ plasmoid-qml/contents/qml/main.qml

Where the -I is the path to the plasma plugin for qml. Try to look for the path of
/usr/lib/kde4/imports/org/kde/plasma/graphicswidgets/libgraphicswidgetsbindingsplugin.so
and use everything up to org of that path.

Hovewer it's '''strongly discouraged''' to use qmlviewer to develop plasmoids, because '''some features won't be available there, like the following''':
* localization with i18n()
* access to the global ''plasmoid'' object
* device specific qml files imported with plasmapackage:// urls
* bindings for qicons, KJobs, services and KConfig
* retrieving data from a DataEngine

Therefore, it is recommended to simply use '''plasmoidviewer'''

= Features only available in Plasma widgets =
In order to have a better integration with the KDE platform and to reach an higher degree of expressivity, the stock features of QML have been expanded with the following features, that strictly follow the Plasmoid JavaScript API:

== Minimum size ==
if the root object of the plasmoid has the properties minimumWidth and minimumHeight, they will be used as the minimum size for the plasmoid. If they will change during the plasmoid execution, the plasmoid minimum size will be updated accordingly.
<syntaxhighlight lang="javascript">
import QtQuick 1.0

Text {
property int minimumWidth: paintedWidth
property int minimumHeight: paintedHeight
text: "Hello world!";
}
</syntaxhighlight>

In the above example, the minimum size is binded to the paintedWidth/paintedHeight properties of the Text element, ensuring there will always be enough room for the whole text to be displayed.

== Plasmoid object ==
Every QML plasmoid will have an object called ''plasmoid'', that will give access to the configuration, the formfactor, immutability and so on. It offers the same api as the object with the same name in the Javascript API.

For specific info on this, see [http://techbase.kde.org/Development/Tutorials/Plasma/JavaScript/API-PlasmoidObject Javascript API-Plasmoid Object]

== Localization ==
It is possible to localize strings with the usual i18n(), i18nc(), i18np() global functions.

== Extra types ==
Some extra types are available from withing JavaScript, namely

* KConfigGroup: it's an object with its config keys readable and writable as properties
* QIcon: can be constructed with QIcon("fdo name") such as QIcon("konqueror")
* KJob
* Plasma Service api

= Plasma specific imports =
To use some Plasma specific features and to take advantage of them in order for your applet to become a true Plasma applet, it is necessary to use some particular QML imports. See [http://techbase.kde.org/Development/Tutorials/Plasma/QML/API Plasma QML API].

== Extra Qt features ==
org.kde.qtextraimports
To use, do:

<syntaxhighlight lang="javascript">
import org.kde.qtextracomponents 0.1 as QtExtraComponents
</syntaxhighlight>

* QPixmapItem
* QImageItem
* QIconItem

== Plasma Widgets in QML ==
To use standard plasma widgets (e.g. Plasma::LineEdit, etc.), you simply add an import line for them.
All properties, signals and slots from ordinary Plasma widgets are available there.
'''These widgets are provided as a transition tool, intended to be replaced by the Plasma version of QtComponents''', which is currently in development by a gsoc. (note that the Plasma QtComponents have nothing to do with the QtExtraComponents module described above)

<syntaxhighlight lang="javascript">
import QtQuick 1.0
import org.kde.plasma.graphicswidgets 0.1 as PlasmaWidgets

Item {
width: 64
height: 64
PlasmaWidgets.IconWidget {
id: icon
Component.onCompleted: setIcon("flag-red")
anchors.centerIn: parent
}
}
</syntaxhighlight>

Development/Tutorials/Plasma/QML/GettingStarted

2011-10-11T00:20:39Z

Icwiener: /* Localization */ Fix typo.

== Abstract ==

Writing a plasma applet in QML is very easy, in fact, with KDE 4.6 and Qt 4.7 it just works.

== QML Basics ==

It is recommended that you have read through the [http://doc.qt.nokia.com/4.7/qtquick.html Qt QML Tutorials], as there are quite a few and they are explained thoroughly. There is also a list of all [http://doc.qt.nokia.com/4.7/qdeclarativeelements.html standard QML elements].

Essentially, most of the content is the same. The exceptions to be noted are how data is gathered...since we use Data Engines, it is a bit different. Text color and font should be made to use PlasmaCore.Theme.

See the [https://projects.kde.org/projects/kde/kdeexamples/repository KDE Examples] repository for more KDE-related helpful resources. Also of use (which use QML and Plasma) are: [https://projects.kde.org/projects/playground/base/plasma-mobile/repository Plasma Mobile], [https://projects.kde.org/projects/playground/base/declarative-plasmoids/repository Declarative Plasmoids (playground)], for WIP ports of C++ originals

=== Root Item ===

The root item can be anything that inherits QGraphicsItem. For example, in this case it is QGraphicsWidget which is a plasmoid. It can also simply be an Item. I also noticed that PathView does not respond to mouse inputs automatically (so flicking doesn't work). Probably because events are being intercepted. So take note, it'll have to be e.g. an Item, for that case.

=== Layouts ===

==== Row and Column ====

==== Anchors ====
Anchor layouts offer a nice way of grouping UI elements nicely together. The idea is that you connect edges or corners of one element to the edge or corner of another widget.
Some examples:
<syntaxhighlight lang="javascript">
import QtQuick 1.0
import org.kde.plasma.core 0.1 as PlasmaCore

Item {
width: 200
height: 300

Text {
id: first
text: i18n("1st line")
anchors {
top: parent.top;
left: parent.left;
right: parent.right;
}
}
Text {
id: second
text: i18n("2nd line")
anchors {
top: first.bottom;
left: parent.left;
right: parent.right;
bottom: parent.bottom;
}
}
}
</syntaxhighlight>

=== Buttons ===

=== Animations ===

== Package Structure ==

You create a .desktop file and the .qml file. They have to be in the usual plasma package structure:

- plasmoid-qml/metadata.desktop

- plasmoid-qml/contents/ui/main.qml

=== <tt>metadata.desktop</tt> ===
<syntaxhighlight lang="ini">
[Desktop Entry]
Name=Hello QML
Comment=A hello world widget in QML
Icon=chronometer

X-Plasma-API=declarativeappletscript
X-Plasma-MainScript=ui/main.qml
X-Plasma-DefaultSize=200,100

X-KDE-PluginInfo-Author=Frederik Gladhorn
X-KDE-PluginInfo-Email=gladhorn@kde.org
X-KDE-PluginInfo-Website=http://plasma.kde.org/
X-KDE-PluginInfo-Category=Examples
X-KDE-PluginInfo-Name=org.kde.hello-qml
X-KDE-PluginInfo-Version=0.0

X-KDE-PluginInfo-Depends=
X-KDE-PluginInfo-License=GPL
X-KDE-PluginInfo-EnabledByDefault=true
X-KDE-ServiceTypes=Plasma/Applet
Type=Service
</syntaxhighlight>

The line below indicates the default size of the plasmoid. The applet's starting size will be this, when added to a scene:

<syntaxhighlight lang="ini">
X-Plasma-DefaultSize=200,100
</syntaxhighlight>

=== <tt>main.qml</tt> ===
<syntaxhighlight lang="javascript">
import QtQuick 1.0

Text {
text: "Hello world!";
}
</syntaxhighlight>

== Installing ==
You can install your plasmoid, though obviously this is just temporary. CMake, below, is recommended:
<syntaxhighlight lang="bash">
plasmapkg --install plasmoid-qml
</syntaxhighlight>

=== Installation through CMake ===
In your CMakeLists.txt:

<syntaxhighlight lang="cmake">
project(helloqml)

install(DIRECTORY package/
DESTINATION ${DATA_INSTALL_DIR}/plasma/plasmoids/org.kde.plasma.applet.myapplet)

install(FILES package/metadata.desktop
DESTINATION ${SERVICES_INSTALL_DIR} RENAME plasma-applet-myapplet.desktop)
</syntaxhighlight>

Your directory structure should now be as follows:

<syntaxhighlight lang="bash">
myproject/CMakeLists.txt
myproject/package/
myproject/package/metadata.desktop
myproject/package/contents/
myproject/package/contents/ui/
myproject/package/contents/ui/helloworld.qml
</syntaxhighlight>

(if you have a configuration file (.ui file) to load the right-click 'plasmoid settings' menu, then your structure will also have myproject/package/contents/config/config.ui, or so)

== plasmoidviewer ==
You can run it in plasmoidviewer as usual:
plasmoidviewer plasmoid-qml

== qmlviewer ==
It's possible to use Plasma specific imports in qml files loaded by qmlviewer:

qmlviewer -I /usr/lib/kde4/imports/ plasmoid-qml/contents/qml/main.qml

Where the -I is the path to the plasma plugin for qml. Try to look for the path of
/usr/lib/kde4/imports/org/kde/plasma/graphicswidgets/libgraphicswidgetsbindingsplugin.so
and use everything up to org of that path.

Hovewer it's '''strongly discouraged''' to use qmlviewer to develop plasmoids, because '''some features won't be available there, like the following''':
* localization with i18n()
* access to the global ''plasmoid'' object
* device specific qml files imported with plasmapackage:// urls
* bindings for qicons, KJobs, services and KConfig
* retrieving data from a DataEngine

Therefore, it is recommended to simply use '''plasmoidviewer'''

= Features only available in Plasma widgets =
In order to have a better integration with the KDE platform and to reach an higher degree of expressivity, the stock features of QML have been expanded with the following features, that strictly follow the Plasmoid JavaScript API:

== Minimum size ==
if the root object of the plasmoid has the properties minimumWidth and minimumHeight, they will be used as the minimum size for the plasmoid. If they will change during the plasmoid execution, the plasmoid minimum size will be updated accordingly.
<syntaxhighlight lang="javascript">
import QtQuick 1.0

Text {
property int minimumWidth: paintedWidth
property int minimumHeight: paintedHeight
text: "Hello world!";
}
</syntaxhighlight>

In the above example, the minimum size is binded to the paintedWidth/paintedHeight properties of the Text element, ensuring there will always be enough room for the whole text to be displayed.

== Plasmoid object ==
Every QML plasmoid will have an object called ''plasmoid'', that will give access to the configuration, the formfactor, immutability and so on. It offers the same api as the object with the same name in the Javascript API.

For specific info on this, see [http://techbase.kde.org/Development/Tutorials/Plasma/JavaScript/API-PlasmoidObject Javascript API-Plasmoid Object]

== Localization ==
It is possible to localize strings with the usual i18n(), i18nc(), i18np() global functions.

== Extra types ==
Some extra types are available from withing JavaScript, namely

* KConfigGroup: it's an object with its config keys readable and writable as properties
* QIcon: can be constructed with QIcon("fdo name") such as QIcon("konqueror")
* KJob
* Plasma Service api

= Plasma specific imports =
To use some Plasma specific features and to take advantage of them in order for your applet to become a true Plasma applet, it is necessary to use some particular QML imports. See [http://techbase.kde.org/Development/Tutorials/Plasma/QML/API Plasma QML API].

== Extra Qt features ==
org.kde.qtextraimports
To use, do:

<syntaxhighlight lang="javascript">
import org.kde.qtextracomponents 0.1 as QtExtraComponents
</syntaxhighlight>

* QPixmapItem
* QImageItem
* QIconItem

== Plasma Widgets in QML ==
To use standard plasma widgets (e.g. Plasma::LineEdit, etc.), you simply add an import line for them.
All properties, signals and slots from ordinary Plasma widgets are available there.
'''These widgets are provided as a transition tool, intended to be replaced by the Plasma version of QtComponents''', which is currently in development by a gsoc. (note that the Plasma QtComponents have nothing to do with the QtExtraComponents module described above)

<syntaxhighlight lang="javascript">
import QtQuick 1.0
import org.kde.plasma.graphicswidgets 0.1 as PlasmaWidgets

Item {
width: 64
height: 64
PlasmaWidgets.IconWidget {
id: icon
Component.onCompleted: setIcon("flag-red")
anchors.centerIn: parent
}
}
</syntaxhighlight>

Development/Tutorials/Plasma/QML/GettingStarted

2011-10-11T00:19:26Z

Icwiener: /* Installation through CMake */ Fix display.

== Abstract ==

Writing a plasma applet in QML is very easy, in fact, with KDE 4.6 and Qt 4.7 it just works.

== QML Basics ==

It is recommended that you have read through the [http://doc.qt.nokia.com/4.7/qtquick.html Qt QML Tutorials], as there are quite a few and they are explained thoroughly. There is also a list of all [http://doc.qt.nokia.com/4.7/qdeclarativeelements.html standard QML elements].

Essentially, most of the content is the same. The exceptions to be noted are how data is gathered...since we use Data Engines, it is a bit different. Text color and font should be made to use PlasmaCore.Theme.

See the [https://projects.kde.org/projects/kde/kdeexamples/repository KDE Examples] repository for more KDE-related helpful resources. Also of use (which use QML and Plasma) are: [https://projects.kde.org/projects/playground/base/plasma-mobile/repository Plasma Mobile], [https://projects.kde.org/projects/playground/base/declarative-plasmoids/repository Declarative Plasmoids (playground)], for WIP ports of C++ originals

=== Root Item ===

The root item can be anything that inherits QGraphicsItem. For example, in this case it is QGraphicsWidget which is a plasmoid. It can also simply be an Item. I also noticed that PathView does not respond to mouse inputs automatically (so flicking doesn't work). Probably because events are being intercepted. So take note, it'll have to be e.g. an Item, for that case.

=== Layouts ===

==== Row and Column ====

==== Anchors ====
Anchor layouts offer a nice way of grouping UI elements nicely together. The idea is that you connect edges or corners of one element to the edge or corner of another widget.
Some examples:
<syntaxhighlight lang="javascript">
import QtQuick 1.0
import org.kde.plasma.core 0.1 as PlasmaCore

Item {
width: 200
height: 300

Text {
id: first
text: i18n("1st line")
anchors {
top: parent.top;
left: parent.left;
right: parent.right;
}
}
Text {
id: second
text: i18n("2nd line")
anchors {
top: first.bottom;
left: parent.left;
right: parent.right;
bottom: parent.bottom;
}
}
}
</syntaxhighlight>

=== Buttons ===

=== Animations ===

== Package Structure ==

You create a .desktop file and the .qml file. They have to be in the usual plasma package structure:

- plasmoid-qml/metadata.desktop

- plasmoid-qml/contents/ui/main.qml

=== <tt>metadata.desktop</tt> ===
<syntaxhighlight lang="ini">
[Desktop Entry]
Name=Hello QML
Comment=A hello world widget in QML
Icon=chronometer

X-Plasma-API=declarativeappletscript
X-Plasma-MainScript=ui/main.qml
X-Plasma-DefaultSize=200,100

X-KDE-PluginInfo-Author=Frederik Gladhorn
X-KDE-PluginInfo-Email=gladhorn@kde.org
X-KDE-PluginInfo-Website=http://plasma.kde.org/
X-KDE-PluginInfo-Category=Examples
X-KDE-PluginInfo-Name=org.kde.hello-qml
X-KDE-PluginInfo-Version=0.0

X-KDE-PluginInfo-Depends=
X-KDE-PluginInfo-License=GPL
X-KDE-PluginInfo-EnabledByDefault=true
X-KDE-ServiceTypes=Plasma/Applet
Type=Service
</syntaxhighlight>

The line below indicates the default size of the plasmoid. The applet's starting size will be this, when added to a scene:

<syntaxhighlight lang="ini">
X-Plasma-DefaultSize=200,100
</syntaxhighlight>

=== <tt>main.qml</tt> ===
<syntaxhighlight lang="javascript">
import QtQuick 1.0

Text {
text: "Hello world!";
}
</syntaxhighlight>

== Installing ==
You can install your plasmoid, though obviously this is just temporary. CMake, below, is recommended:
<syntaxhighlight lang="bash">
plasmapkg --install plasmoid-qml
</syntaxhighlight>

=== Installation through CMake ===
In your CMakeLists.txt:

<syntaxhighlight lang="cmake">
project(helloqml)

install(DIRECTORY package/
DESTINATION ${DATA_INSTALL_DIR}/plasma/plasmoids/org.kde.plasma.applet.myapplet)

install(FILES package/metadata.desktop
DESTINATION ${SERVICES_INSTALL_DIR} RENAME plasma-applet-myapplet.desktop)
</syntaxhighlight>

Your directory structure should now be as follows:

<syntaxhighlight lang="bash">
myproject/CMakeLists.txt
myproject/package/
myproject/package/metadata.desktop
myproject/package/contents/
myproject/package/contents/ui/
myproject/package/contents/ui/helloworld.qml
</syntaxhighlight>

(if you have a configuration file (.ui file) to load the right-click 'plasmoid settings' menu, then your structure will also have myproject/package/contents/config/config.ui, or so)

== plasmoidviewer ==
You can run it in plasmoidviewer as usual:
plasmoidviewer plasmoid-qml

== qmlviewer ==
It's possible to use Plasma specific imports in qml files loaded by qmlviewer:

qmlviewer -I /usr/lib/kde4/imports/ plasmoid-qml/contents/qml/main.qml

Where the -I is the path to the plasma plugin for qml. Try to look for the path of
/usr/lib/kde4/imports/org/kde/plasma/graphicswidgets/libgraphicswidgetsbindingsplugin.so
and use everything up to org of that path.

Hovewer it's '''strongly discouraged''' to use qmlviewer to develop plasmoids, because '''some features won't be available there, like the following''':
* localization with i18n()
* access to the global ''plasmoid'' object
* device specific qml files imported with plasmapackage:// urls
* bindings for qicons, KJobs, services and KConfig
* retrieving data from a DataEngine

Therefore, it is recommended to simply use '''plasmoidviewer'''

= Features only available in Plasma widgets =
In order to have a better integration with the KDE platform and to reach an higher degree of expressivity, the stock features of QML have been expanded with the following features, that strictly follow the Plasmoid JavaScript API:

== Minimum size ==
if the root object of the plasmoid has the properties minimumWidth and minimumHeight, they will be used as the minimum size for the plasmoid. If they will change during the plasmoid execution, the plasmoid minimum size will be updated accordingly.
<syntaxhighlight lang="javascript">
import QtQuick 1.0

Text {
property int minimumWidth: paintedWidth
property int minimumHeight: paintedHeight
text: "Hello world!";
}
</syntaxhighlight>

In the above example, the minimum size is binded to the paintedWidth/paintedHeight properties of the Text element, ensuring there will always be enough room for the whole text to be displayed.

== Plasmoid object ==
Every QML plasmoid will have an object called ''plasmoid'', that will give access to the configuration, the formfactor, immutability and so on. It offers the same api as the object with the same name in the Javascript API.

For specific info on this, see [http://techbase.kde.org/Development/Tutorials/Plasma/JavaScript/API-PlasmoidObject Javascript API-Plasmoid Object]

== Localization ==
It's possible to localize strings with the usual i18n(), i18nc(), i18np() global functions

== Extra types ==
Some extra types are available from withing JavaScript, namely

* KConfigGroup: it's an object with its config keys readable and writable as properties
* QIcon: can be constructed with QIcon("fdo name") such as QIcon("konqueror")
* KJob
* Plasma Service api

= Plasma specific imports =
To use some Plasma specific features and to take advantage of them in order for your applet to become a true Plasma applet, it is necessary to use some particular QML imports. See [http://techbase.kde.org/Development/Tutorials/Plasma/QML/API Plasma QML API].

== Extra Qt features ==
org.kde.qtextraimports
To use, do:

<syntaxhighlight lang="javascript">
import org.kde.qtextracomponents 0.1 as QtExtraComponents
</syntaxhighlight>

* QPixmapItem
* QImageItem
* QIconItem

== Plasma Widgets in QML ==
To use standard plasma widgets (e.g. Plasma::LineEdit, etc.), you simply add an import line for them.
All properties, signals and slots from ordinary Plasma widgets are available there.
'''These widgets are provided as a transition tool, intended to be replaced by the Plasma version of QtComponents''', which is currently in development by a gsoc. (note that the Plasma QtComponents have nothing to do with the QtExtraComponents module described above)

<syntaxhighlight lang="javascript">
import QtQuick 1.0
import org.kde.plasma.graphicswidgets 0.1 as PlasmaWidgets

Item {
width: 64
height: 64
PlasmaWidgets.IconWidget {
id: icon
Component.onCompleted: setIcon("flag-red")
anchors.centerIn: parent
}
}
</syntaxhighlight>

Development/Tutorials/Plasma/QML/GettingStarted

2011-10-11T00:18:36Z

Icwiener: /* Installing */ Fix highlighting.

== Abstract ==

Writing a plasma applet in QML is very easy, in fact, with KDE 4.6 and Qt 4.7 it just works.

== QML Basics ==

It is recommended that you have read through the [http://doc.qt.nokia.com/4.7/qtquick.html Qt QML Tutorials], as there are quite a few and they are explained thoroughly. There is also a list of all [http://doc.qt.nokia.com/4.7/qdeclarativeelements.html standard QML elements].

Essentially, most of the content is the same. The exceptions to be noted are how data is gathered...since we use Data Engines, it is a bit different. Text color and font should be made to use PlasmaCore.Theme.

See the [https://projects.kde.org/projects/kde/kdeexamples/repository KDE Examples] repository for more KDE-related helpful resources. Also of use (which use QML and Plasma) are: [https://projects.kde.org/projects/playground/base/plasma-mobile/repository Plasma Mobile], [https://projects.kde.org/projects/playground/base/declarative-plasmoids/repository Declarative Plasmoids (playground)], for WIP ports of C++ originals

=== Root Item ===

The root item can be anything that inherits QGraphicsItem. For example, in this case it is QGraphicsWidget which is a plasmoid. It can also simply be an Item. I also noticed that PathView does not respond to mouse inputs automatically (so flicking doesn't work). Probably because events are being intercepted. So take note, it'll have to be e.g. an Item, for that case.

=== Layouts ===

==== Row and Column ====

==== Anchors ====
Anchor layouts offer a nice way of grouping UI elements nicely together. The idea is that you connect edges or corners of one element to the edge or corner of another widget.
Some examples:
<syntaxhighlight lang="javascript">
import QtQuick 1.0
import org.kde.plasma.core 0.1 as PlasmaCore

Item {
width: 200
height: 300

Text {
id: first
text: i18n("1st line")
anchors {
top: parent.top;
left: parent.left;
right: parent.right;
}
}
Text {
id: second
text: i18n("2nd line")
anchors {
top: first.bottom;
left: parent.left;
right: parent.right;
bottom: parent.bottom;
}
}
}
</syntaxhighlight>

=== Buttons ===

=== Animations ===

== Package Structure ==

You create a .desktop file and the .qml file. They have to be in the usual plasma package structure:

- plasmoid-qml/metadata.desktop

- plasmoid-qml/contents/ui/main.qml

=== <tt>metadata.desktop</tt> ===
<syntaxhighlight lang="ini">
[Desktop Entry]
Name=Hello QML
Comment=A hello world widget in QML
Icon=chronometer

X-Plasma-API=declarativeappletscript
X-Plasma-MainScript=ui/main.qml
X-Plasma-DefaultSize=200,100

X-KDE-PluginInfo-Author=Frederik Gladhorn
X-KDE-PluginInfo-Email=gladhorn@kde.org
X-KDE-PluginInfo-Website=http://plasma.kde.org/
X-KDE-PluginInfo-Category=Examples
X-KDE-PluginInfo-Name=org.kde.hello-qml
X-KDE-PluginInfo-Version=0.0

X-KDE-PluginInfo-Depends=
X-KDE-PluginInfo-License=GPL
X-KDE-PluginInfo-EnabledByDefault=true
X-KDE-ServiceTypes=Plasma/Applet
Type=Service
</syntaxhighlight>

The line below indicates the default size of the plasmoid. The applet's starting size will be this, when added to a scene:

<syntaxhighlight lang="ini">
X-Plasma-DefaultSize=200,100
</syntaxhighlight>

=== <tt>main.qml</tt> ===
<syntaxhighlight lang="javascript">
import QtQuick 1.0

Text {
text: "Hello world!";
}
</syntaxhighlight>

== Installing ==
You can install your plasmoid, though obviously this is just temporary. CMake, below, is recommended:
<syntaxhighlight lang="bash">
plasmapkg --install plasmoid-qml
</syntaxhighlight>

=== Installation through CMake ===
In your CMakeLists.txt:

<syntaxhighlight lang="cmake">
project(helloqml)

install(DIRECTORY package/
DESTINATION ${DATA_INSTALL_DIR}/plasma/plasmoids/org.kde.plasma.applet.myapplet)

install(FILES package/metadata.desktop DESTINATION ${SERVICES_INSTALL_DIR} RENAME plasma-applet-myapplet.desktop)
</syntaxhighlight>

Your directory structure should now be as follows:

<syntaxhighlight lang="bash">
myproject/CMakeLists.txt
myproject/package/
myproject/package/metadata.desktop
myproject/package/contents/
myproject/package/contents/ui/
myproject/package/contents/ui/helloworld.qml
</syntaxhighlight>

(if you have a configuration file (.ui file) to load the right-click 'plasmoid settings' menu, then your structure will also have myproject/package/contents/config/config.ui, or so)

== plasmoidviewer ==
You can run it in plasmoidviewer as usual:
plasmoidviewer plasmoid-qml

== qmlviewer ==
It's possible to use Plasma specific imports in qml files loaded by qmlviewer:

qmlviewer -I /usr/lib/kde4/imports/ plasmoid-qml/contents/qml/main.qml

Where the -I is the path to the plasma plugin for qml. Try to look for the path of
/usr/lib/kde4/imports/org/kde/plasma/graphicswidgets/libgraphicswidgetsbindingsplugin.so
and use everything up to org of that path.

Hovewer it's '''strongly discouraged''' to use qmlviewer to develop plasmoids, because '''some features won't be available there, like the following''':
* localization with i18n()
* access to the global ''plasmoid'' object
* device specific qml files imported with plasmapackage:// urls
* bindings for qicons, KJobs, services and KConfig
* retrieving data from a DataEngine

Therefore, it is recommended to simply use '''plasmoidviewer'''

= Features only available in Plasma widgets =
In order to have a better integration with the KDE platform and to reach an higher degree of expressivity, the stock features of QML have been expanded with the following features, that strictly follow the Plasmoid JavaScript API:

== Minimum size ==
if the root object of the plasmoid has the properties minimumWidth and minimumHeight, they will be used as the minimum size for the plasmoid. If they will change during the plasmoid execution, the plasmoid minimum size will be updated accordingly.
<syntaxhighlight lang="javascript">
import QtQuick 1.0

Text {
property int minimumWidth: paintedWidth
property int minimumHeight: paintedHeight
text: "Hello world!";
}
</syntaxhighlight>

In the above example, the minimum size is binded to the paintedWidth/paintedHeight properties of the Text element, ensuring there will always be enough room for the whole text to be displayed.

== Plasmoid object ==
Every QML plasmoid will have an object called ''plasmoid'', that will give access to the configuration, the formfactor, immutability and so on. It offers the same api as the object with the same name in the Javascript API.

For specific info on this, see [http://techbase.kde.org/Development/Tutorials/Plasma/JavaScript/API-PlasmoidObject Javascript API-Plasmoid Object]

== Localization ==
It's possible to localize strings with the usual i18n(), i18nc(), i18np() global functions

== Extra types ==
Some extra types are available from withing JavaScript, namely

* KConfigGroup: it's an object with its config keys readable and writable as properties
* QIcon: can be constructed with QIcon("fdo name") such as QIcon("konqueror")
* KJob
* Plasma Service api

= Plasma specific imports =
To use some Plasma specific features and to take advantage of them in order for your applet to become a true Plasma applet, it is necessary to use some particular QML imports. See [http://techbase.kde.org/Development/Tutorials/Plasma/QML/API Plasma QML API].

== Extra Qt features ==
org.kde.qtextraimports
To use, do:

<syntaxhighlight lang="javascript">
import org.kde.qtextracomponents 0.1 as QtExtraComponents
</syntaxhighlight>

* QPixmapItem
* QImageItem
* QIconItem

== Plasma Widgets in QML ==
To use standard plasma widgets (e.g. Plasma::LineEdit, etc.), you simply add an import line for them.
All properties, signals and slots from ordinary Plasma widgets are available there.
'''These widgets are provided as a transition tool, intended to be replaced by the Plasma version of QtComponents''', which is currently in development by a gsoc. (note that the Plasma QtComponents have nothing to do with the QtExtraComponents module described above)

<syntaxhighlight lang="javascript">
import QtQuick 1.0
import org.kde.plasma.graphicswidgets 0.1 as PlasmaWidgets

Item {
width: 64
height: 64
PlasmaWidgets.IconWidget {
id: icon
Component.onCompleted: setIcon("flag-red")
anchors.centerIn: parent
}
}
</syntaxhighlight>

Development/Tutorials/Plasma/QML/GettingStarted

2011-10-11T00:16:47Z

Icwiener: /* Package Structure */ Fix layout

== Abstract ==

Writing a plasma applet in QML is very easy, in fact, with KDE 4.6 and Qt 4.7 it just works.

== QML Basics ==

It is recommended that you have read through the [http://doc.qt.nokia.com/4.7/qtquick.html Qt QML Tutorials], as there are quite a few and they are explained thoroughly. There is also a list of all [http://doc.qt.nokia.com/4.7/qdeclarativeelements.html standard QML elements].

Essentially, most of the content is the same. The exceptions to be noted are how data is gathered...since we use Data Engines, it is a bit different. Text color and font should be made to use PlasmaCore.Theme.

See the [https://projects.kde.org/projects/kde/kdeexamples/repository KDE Examples] repository for more KDE-related helpful resources. Also of use (which use QML and Plasma) are: [https://projects.kde.org/projects/playground/base/plasma-mobile/repository Plasma Mobile], [https://projects.kde.org/projects/playground/base/declarative-plasmoids/repository Declarative Plasmoids (playground)], for WIP ports of C++ originals

=== Root Item ===

The root item can be anything that inherits QGraphicsItem. For example, in this case it is QGraphicsWidget which is a plasmoid. It can also simply be an Item. I also noticed that PathView does not respond to mouse inputs automatically (so flicking doesn't work). Probably because events are being intercepted. So take note, it'll have to be e.g. an Item, for that case.

=== Layouts ===

==== Row and Column ====

==== Anchors ====
Anchor layouts offer a nice way of grouping UI elements nicely together. The idea is that you connect edges or corners of one element to the edge or corner of another widget.
Some examples:
<syntaxhighlight lang="javascript">
import QtQuick 1.0
import org.kde.plasma.core 0.1 as PlasmaCore

Item {
width: 200
height: 300

Text {
id: first
text: i18n("1st line")
anchors {
top: parent.top;
left: parent.left;
right: parent.right;
}
}
Text {
id: second
text: i18n("2nd line")
anchors {
top: first.bottom;
left: parent.left;
right: parent.right;
bottom: parent.bottom;
}
}
}
</syntaxhighlight>

=== Buttons ===

=== Animations ===

== Package Structure ==

You create a .desktop file and the .qml file. They have to be in the usual plasma package structure:

- plasmoid-qml/metadata.desktop

- plasmoid-qml/contents/ui/main.qml

=== <tt>metadata.desktop</tt> ===
<syntaxhighlight lang="ini">
[Desktop Entry]
Name=Hello QML
Comment=A hello world widget in QML
Icon=chronometer

X-Plasma-API=declarativeappletscript
X-Plasma-MainScript=ui/main.qml
X-Plasma-DefaultSize=200,100

X-KDE-PluginInfo-Author=Frederik Gladhorn
X-KDE-PluginInfo-Email=gladhorn@kde.org
X-KDE-PluginInfo-Website=http://plasma.kde.org/
X-KDE-PluginInfo-Category=Examples
X-KDE-PluginInfo-Name=org.kde.hello-qml
X-KDE-PluginInfo-Version=0.0

X-KDE-PluginInfo-Depends=
X-KDE-PluginInfo-License=GPL
X-KDE-PluginInfo-EnabledByDefault=true
X-KDE-ServiceTypes=Plasma/Applet
Type=Service
</syntaxhighlight>

The line below indicates the default size of the plasmoid. The applet's starting size will be this, when added to a scene:

<syntaxhighlight lang="ini">
X-Plasma-DefaultSize=200,100
</syntaxhighlight>

=== <tt>main.qml</tt> ===
<syntaxhighlight lang="javascript">
import QtQuick 1.0

Text {
text: "Hello world!";
}
</syntaxhighlight>

== Installing ==
You can install your plasmoid, though obviously this is just temporary. CMake, below, is recommended:
plasmapkg --install plasmoid-qml

=== Installation through CMake ===
In your CMakeLists.txt:

<syntaxhighlight lang="bash">
project(helloqml)

install(DIRECTORY package/
DESTINATION ${DATA_INSTALL_DIR}/plasma/plasmoids/org.kde.plasma.applet.myapplet)

install(FILES package/metadata.desktop DESTINATION ${SERVICES_INSTALL_DIR} RENAME plasma-applet-myapplet.desktop)
</syntaxhighlight>

Your directory structure should now be as follows:

<syntaxhighlight lang="bash">
myproject/CMakeLists.txt
myproject/package/
myproject/package/metadata.desktop
myproject/package/contents/
myproject/package/contents/ui/
myproject/package/contents/ui/helloworld.qml
</syntaxhighlight>

(if you have a configuration file (.ui file) to load the right-click 'plasmoid settings' menu, then your structure will also have myproject/package/contents/config/config.ui, or so)

== plasmoidviewer ==
You can run it in plasmoidviewer as usual:
plasmoidviewer plasmoid-qml

== qmlviewer ==
It's possible to use Plasma specific imports in qml files loaded by qmlviewer:

qmlviewer -I /usr/lib/kde4/imports/ plasmoid-qml/contents/qml/main.qml

Where the -I is the path to the plasma plugin for qml. Try to look for the path of
/usr/lib/kde4/imports/org/kde/plasma/graphicswidgets/libgraphicswidgetsbindingsplugin.so
and use everything up to org of that path.

Hovewer it's '''strongly discouraged''' to use qmlviewer to develop plasmoids, because '''some features won't be available there, like the following''':
* localization with i18n()
* access to the global ''plasmoid'' object
* device specific qml files imported with plasmapackage:// urls
* bindings for qicons, KJobs, services and KConfig
* retrieving data from a DataEngine

Therefore, it is recommended to simply use '''plasmoidviewer'''

= Features only available in Plasma widgets =
In order to have a better integration with the KDE platform and to reach an higher degree of expressivity, the stock features of QML have been expanded with the following features, that strictly follow the Plasmoid JavaScript API:

== Minimum size ==
if the root object of the plasmoid has the properties minimumWidth and minimumHeight, they will be used as the minimum size for the plasmoid. If they will change during the plasmoid execution, the plasmoid minimum size will be updated accordingly.
<syntaxhighlight lang="javascript">
import QtQuick 1.0

Text {
property int minimumWidth: paintedWidth
property int minimumHeight: paintedHeight
text: "Hello world!";
}
</syntaxhighlight>

In the above example, the minimum size is binded to the paintedWidth/paintedHeight properties of the Text element, ensuring there will always be enough room for the whole text to be displayed.

== Plasmoid object ==
Every QML plasmoid will have an object called ''plasmoid'', that will give access to the configuration, the formfactor, immutability and so on. It offers the same api as the object with the same name in the Javascript API.

For specific info on this, see [http://techbase.kde.org/Development/Tutorials/Plasma/JavaScript/API-PlasmoidObject Javascript API-Plasmoid Object]

== Localization ==
It's possible to localize strings with the usual i18n(), i18nc(), i18np() global functions

== Extra types ==
Some extra types are available from withing JavaScript, namely

* KConfigGroup: it's an object with its config keys readable and writable as properties
* QIcon: can be constructed with QIcon("fdo name") such as QIcon("konqueror")
* KJob
* Plasma Service api

= Plasma specific imports =
To use some Plasma specific features and to take advantage of them in order for your applet to become a true Plasma applet, it is necessary to use some particular QML imports. See [http://techbase.kde.org/Development/Tutorials/Plasma/QML/API Plasma QML API].

== Extra Qt features ==
org.kde.qtextraimports
To use, do:

<syntaxhighlight lang="javascript">
import org.kde.qtextracomponents 0.1 as QtExtraComponents
</syntaxhighlight>

* QPixmapItem
* QImageItem
* QIconItem

== Plasma Widgets in QML ==
To use standard plasma widgets (e.g. Plasma::LineEdit, etc.), you simply add an import line for them.
All properties, signals and slots from ordinary Plasma widgets are available there.
'''These widgets are provided as a transition tool, intended to be replaced by the Plasma version of QtComponents''', which is currently in development by a gsoc. (note that the Plasma QtComponents have nothing to do with the QtExtraComponents module described above)

<syntaxhighlight lang="javascript">
import QtQuick 1.0
import org.kde.plasma.graphicswidgets 0.1 as PlasmaWidgets

Item {
width: 64
height: 64
PlasmaWidgets.IconWidget {
id: icon
Component.onCompleted: setIcon("flag-red")
anchors.centerIn: parent
}
}
</syntaxhighlight>

Development/Tutorials/Icons

2011-09-28T20:23:03Z

Icwiener: improve markup

__TOC__

When you create your own KDE application you will probably want icons in it like this:

[[File:Snapshot-krep-arrow.png]]

These icons are called [http://api.kde.org/4.x-api/kdelibs-apidocs/kdeui/html/classKIcon.html KIcon]s. This article shows you how to do this using the software [http://www.staerk.de/thorsten/krep krep] as an example. In case of a [[Development/Tutorials/CMake|
CMake]]-based project you will need to
* [http://websvn.kde.org/trunk/playground/utils/krep/main.cpp?r1=1154359&r2=1249871 modify main.cpp (as it is typically called)]
* [http://websvn.kde.org/trunk/playground/utils/krep/CMakeLists.txt?r1=813330&r2=1249871&sortby=date modify CMakeLists.txt]

How to use icons in QMake-based projects is discussed [http://appdeveloper.intel.com/en-us/Qt%20C%20Plus%20Plus%20app%20MeeGo%20SDK elsewhere].

= Your KDE project =
If you have a KDE project and want to use icons within it, and want these icons installed seamlessly, you will have to name the icons after the project. In the following we look at a project named ''krep''. The important lines in CMakeLists.txt are the ones printed bold below:
<syntaxhighlight lang="cmake">
PROJECT( krep )
FIND_PACKAGE( KDE4 REQUIRED )
INCLUDE_DIRECTORIES( ${KDE4_INCLUDES} . )

SET( krepSources main.cpp krep.cpp krep.h )

qt4_add_dbus_adaptor( krepSources
org.kde.krep.xml
krep.h
krep
mainadaptor
MainAdaptor )

kde4_add_ui_files( krepSources krepui.ui )

kde4_add_app_icon]]( krepSources "hi*-app-krep.png" )

KDE4_ADD_EXECUTABLE( krep ${krepSources} )

TARGET_LINK_LIBRARIES( krep ${KDE4_KPARTS_LIBS} )

install( TARGETS krep ${INSTALL_TARGETS_DEFAULT_ARGS} )

'''kde4_install_icons( ${ICON_INSTALL_DIR]]} )
</syntaxhighlight>
Weitere Informationen:
* [[Development/CMake/Addons_for_KDE#Macros|kde4_add_app_icon]]
* [[Development/CMake/Addons_for_KDE#The_locations_of_install_directories|ICON_INSTALL_DIR]]

= How to test it =
* delete a file
<syntaxhighlight lang="bash">
rm /usr/local/share/icons/hicolor/22x22/apps/krep.png
</syntaxhighlight>
{{Note| We are assuming your icon path is /usr/local/share/icons.
Find it out with the command
<syntaxhighlight lang="bash">
kde4-config --path icon
</syntaxhighlight>
}}
* delete your cache
<syntaxhighlight lang="bash">
rm -rf /var/tmp/kdecache-''user''/icon-cache.kcache
</syntaxhighlight>

According to [[Development/CMake/Addons_for_KDE#Macros]] you need to provide a 128x128 pixels icon.

= The icon naming scheme =
Example for icon names:
* hisc-apps-bla.svgz will be installed e.g. to /usr/local/share/icons/hicolor/scalable/apps/bla.svgz. <tt>hi</tt> stands for "hicolor", <tt>sc</tt> for "scalable", <tt>apps</tt> for "applications", <tt>bla</tt> for the application's name and <tt>.svgz</tt> is the suffix for gzipped scalable vector graphic files.
* hi128-app-ktimetracker.png will be installed e.g. to /usr/share/icons/hicolor/128x128/apps/ktimetracker.png. <tt>hi</tt> stands for "hicolor", <tt>128</tt> for a resolution of 128x128 pixels, <tt>app</tt> for "applications", <tt>ktimetracker</tt> for the application's name and <tt>.png</tt> is the suffix for portable network graphic files.

= example application =
In this chapter we will build - on top of the [[Development/Tutorials/Using_KActions|KAction example]] - an example application ''kicons'' that looks like this:

[[File:Snapshot-tutorial-kicon.png]]

You can obtain its source code as part of kdeexamples by calling
git clone git://anongit.kde.org/kdeexamples

== files ==
The example application consists of
* [http://quickgit.kde.org/?p=kdeexamples.git&a=blob&f=kicons/main.cpp main.cpp]
: just taken from the [[Development/Tutorials/Using_KActions|KAction example]]
* [http://quickgit.kde.org/?p=kdeexamples.git&a=blob&f=kicons/mainwindow.cpp mainwindow.cpp]
: Note the command <syntaxhighlight lang="bash">clearAction->setIcon(KIcon("tutorial-kicon"));</syntaxhighlight> that sets the icon
* [http://quickgit.kde.org/?p=kdeexamples.git&a=blob&f=kicons/mainwindow.h mainwindow.h]
: just taken from the [[Development/Tutorials/Using_KActions|KAction example]]
* [http://quickgit.kde.org/?p=kdeexamples.git&a=blob&f=kicons/world.svg world.svg]
: This is a file that defines our icon in (almost natural) english language. It is a scalable vector graphic file. Before being used, it must be converted into a zipped scalable vector graphic named ''hisc-apps-tutorial-kicon.svgz'', see below.
* [http://quickgit.kde.org/?p=kdeexamples.git&a=blob&f=kicons/tutorial-kiconui.rc tutorial-kiconui.rc]
: just taken from the [[Development/Tutorials/Using_KActions|KAction example]]
* [http://quickgit.kde.org/?p=kdeexamples.git&a=blob&f=kicons/hisc-apps-tutorial-kicon.svgz hisc-apps-tutorial-kicon.svgz]
: sorry for the name, but there are [[#The_icon_naming_scheme|naming conventions]]. Create this file with the ''convert'' command from the ''ImageMagick'' package <syntaxhighlight lang="bash">convert world.svg hisc-apps-tutorial-kicon.svgz</syntaxhighlight>
* [http://quickgit.kde.org/?p=kdeexamples.git&a=blob&f=kicons/CMakeLists.txt CMakeLists.txt]
: Note the commands <syntaxhighlight lang="bash">kde4_install_icons(${ICON_INSTALL_DIR})</syntaxhighlight> and <syntaxhighlight lang="bash">kde4_update_iconcache()</syntaxhighlight> which integrate the icons.

== build it ==
To compile, link and install the example application, do a
<syntaxhighlight lang="bash">
cmake . && make && make install
</syntaxhighlight>
To run it, call
<syntaxhighlight lang="bash">
tutorial-kicon
</syntaxhighlight>

= Analyzing the KApplications =
Maybe you have already searched for yourself how a KDE application finds its icons. You will not be successful like this:
<syntaxhighlight lang="bash">
# [http://www.linuxintro.org/wiki/Strace#Search_for_a_syscall strace -e open] ktimetracker 2>&1 | grep icon
open("/usr/lib64/libkemoticons.so.4", O_RDONLY) = 3
#
</syntaxhighlight>
You see, a KDE application (in this case ktimetracker) does not open icon files or even look for them. However, it spawns a process to look for these icons:
<syntaxhighlight lang="bash">
linux-qgla:~/repos/kdepim/ktimetracker # strace -ffe open ktimetracker 2>&1 | grep icon
open("/usr/lib64/libkemoticons.so.4", O_RDONLY) = 3
[pid 3457] open("/root/.icons/DMZ/cursors/left_ptr", O_RDONLY) = -1 ENOENT (No such file or directory)
[pid 3457] open("/root/.icons/DMZ/index.theme", O_RDONLY) = -1 ENOENT (No such file or directory)
[pid 3457] open("/usr/share/icons/DMZ/cursors/left_ptr", O_RDONLY) = 10
[pid 3457] open("/var/tmp/kdecache-root/icon-cache.kcache", O_RDWR|O_CREAT|O_CLOEXEC, 0666) = 10
[pid 3457] open("/var/tmp/kdecache-root/kpc/kde-icon-cache.data", O_RDONLY|O_CLOEXEC) = 10
[pid 3457] open("/var/tmp/kdecache-root/kpc/kde-icon-cache.index", O_RDONLY|O_CLOEXEC) = 10
[...]
</syntaxhighlight>

= Moving On =
Now you can move on to [[Development/Tutorials/Desktop_File|how to place your application in the K-Menu using .desktop files]].

[[Category:C++]]

Development/Tutorials/Using Qt Creator

2011-09-28T20:21:24Z

Icwiener: Proofreading.

{{Template:I18n/Language Navigation Bar|Development/Tutorials/Using Qt Creator}}

QtCreator is an IDE from Nokia for Qt. It contains QtDesigner for UI design. This article describes:
* why to use Qt Creator
* how to create a new application
* how to load an existing application

= Why use Qt Creator =
{|align="right"
|[[image:Snapshot-qtcreator.png|right|thumb|200px|KDE4's ktimetracker loaded as QtCreator project]]
|}
To create your C++ applications you can use any text editor. But life will be much easier if you gain QtCreator's features. That means
* you can get your source code saved, built and run with one click
* you get code-completion
* you can find all places in your source code where you call a function (e.g. "where do I call refresh()")
* you can go back to a more recent cursor position with your editor, even if this is in another file
* you can checkout and commit to Subversion or Git repositories without leaving your workflow

= Creating a new program =
Here is a short example of how you can create a "hello world" application. For more information read the [http://qt.nokia.com/doc/designer-manual.html user documentation].

;Step 0:
Call QtCreator
<syntaxhighlight lang="bash">
qtcreator
</syntaxhighlight>
Then select New File or Project -> Qt C++ Project -> Qt Gui Application -> name = helloworld -> Next -> Next -> Finish

;Step 1:
Select Edit -> Forms -> mainwindow.ui. Add the widgets you want by drag-and-drop:

[[File:Designer-step1.png|200px]]

;Step 2:
Select the mainwindow. This is the one un-intuitive step. To lay out the objects in the mainwindow, you do not select the objects in the mainwindow, but the mainwindow itself.

[[File:Designer-step2.png|200px]]

;Step 3:
Select Form -> Lay Out in a Grid

[[File:Designer-step3.png|200px]]

;Result:
You get a decent look, and if you resize the window, the widgets resize as well.

[[File:Designer-result.png|200px]]

== Using KDE libraries ==
To use KDE classes like KMessageBox, you need to tell QtCreator to use the KDE libraries when building. Go to your home directory, change into ''yourproject'' and modify ''yourproject.pro''. Add the line
<syntaxhighlight lang="make">
LIBS += -lkdeui
</syntaxhighlight>
Then you can start using KDE classes in your code.

== Adding a toolbar ==
To add a toolbar, right-click on the UI and choose "Add Toolbar". Then you can set icons and text in your mainwindow's constructor with code like this:
<syntaxhighlight lang="cpp-qt">
ui->toolBar->addAction(QIcon("/usr/share/icons/oxygen/22x22/apps/ktip.png"),"hello world");
</syntaxhighlight>
[[Development/Tutorials/Using_Qt_Designer|More Info...]]

= Load an existing project =
This describes how to use QtCreator to integrate existing KDE 4 applications. It has been tested with QtCreator 1.2.80 and SUSE Linux 11.1 but should work same or similar with every combination. As an example KDE application we use [http://userbase.kde.org/ktimetracker ktimetracker] from the kdepim module, other applications should work likewise.

You can either work with code on your disk or have QtCreator do the Subversion checkout.

== use code from your disk ==
* import the CMakeLists.txt file (File -> Open -> kdepim/CMakeLists.txt)
* as build directory choose kdepim
* you will automatically come to a screen where you can run CMake
* continue with the step "Run cmake"

== have QtCreator do the subversion checkout ==
* choose File -> New File or Project -> Version Control -> Subversion Checkout.
* enter a Subversion URL like svn://anonsvn.kde.org/home/kde/trunk/KDE/kdepim
* enter a checkout directory, i.e. the local directory where the code will be checked-out to
* type finish, see how the checkout starts
* you will automatically come to a screen where you can run CMake
* continue with the step "Run cmake"

== have QtCreator do the git checkout ==
* choose File -> New File or Project -> Version Control -> Git Checkout.
* enter a Git URL like git@git.kde.org:/kdepim
* accept kdepim as checkout directory
* type finish, see how the checkout starts
* you will automatically come to a screen where you can run CMake
* continue with the step "Run cmake"

== Run cmake ==
* enter arguments for CMake like
<syntaxhighlight lang="bash">
/root/kdepim -DCMAKE_INSTALL_PREFIX=/usr/local -DLIB_SUFFIX=64 -DCMAKE_BUILD_TYPE=debugfull
</syntaxhighlight>
<tt>DLIB_SUFFIX=64</tt> means that you want to install your libraries into directories named <tt>lib64</tt>, not <tt>lib</tt>. ''/root/kdepim'' is where your source code is.
* click "Run cmake"
* note: a .cbp file is created containing many information about the build
* click "Finish"

== Build it ==
* configure QtCreator to build only ktimetracker:
Projects -> Active run configuration=ktimetracker -> build settings -> build steps -> make -> show details -> activate ktimetracker.
* configure QtCreator to use 8 logical processors:
Projects -> Active run configuration=ktimetracker -> build settings -> build steps -> make -> show details -> addtional Arguments = -j8
* choose Build -> Build All

= See also =
* [[Development/Tutorials/Using Qt Designer]]
* [[Getting_Started/Using_an_IDE_with_KDE4#QtCreator]]

[[Category:KDE4]]

Development/Tutorials/Icons

2011-09-28T20:09:28Z

Icwiener: /* files */ Fix code tags.

__TOC__

When you create your own KDE application you will probably want icons in it like this:

[[File:Snapshot-krep-arrow.png]]

These icons are called [http://api.kde.org/4.x-api/kdelibs-apidocs/kdeui/html/classKIcon.html KIcon]s. This article shows you how to do this using the software [http://www.staerk.de/thorsten/krep krep] as an example. In case of a [[Development/Tutorials/CMake|
CMake]]-based project you will need to
* [http://websvn.kde.org/trunk/playground/utils/krep/main.cpp?r1=1154359&r2=1249871 modify main.cpp (as it is typically called)]
* [http://websvn.kde.org/trunk/playground/utils/krep/CMakeLists.txt?r1=813330&r2=1249871&sortby=date modify CMakeLists.txt]

How to use icons in QMake-based projects is discussed [http://appdeveloper.intel.com/en-us/Qt%20C%20Plus%20Plus%20app%20MeeGo%20SDK elsewhere].

= Your KDE project =
If you have a KDE project and want to use icons within it, and want these icons installed seamlessly, you will have to name the icons after the project. In the following we look at a project named ''krep''. The important lines in CMakeLists.txt are the ones printed bold below:
<syntaxhighlight lang="cmake">
PROJECT( krep )
FIND_PACKAGE( KDE4 REQUIRED )
INCLUDE_DIRECTORIES( ${KDE4_INCLUDES} . )

SET( krepSources main.cpp krep.cpp krep.h )

qt4_add_dbus_adaptor( krepSources
org.kde.krep.xml
krep.h
krep
mainadaptor
MainAdaptor )

kde4_add_ui_files( krepSources krepui.ui )

kde4_add_app_icon]]( krepSources "hi*-app-krep.png" )

KDE4_ADD_EXECUTABLE( krep ${krepSources} )

TARGET_LINK_LIBRARIES( krep ${KDE4_KPARTS_LIBS} )

install( TARGETS krep ${INSTALL_TARGETS_DEFAULT_ARGS} )

'''kde4_install_icons( ${ICON_INSTALL_DIR]]} )
</syntaxhighlight>
Weitere Informationen:
* [[Development/CMake/Addons_for_KDE#Macros|kde4_add_app_icon]]
* [[Development/CMake/Addons_for_KDE#The_locations_of_install_directories|ICON_INSTALL_DIR]]

= How to test it =
* delete a file
<syntaxhighlight lang="bash">
rm /usr/local/share/icons/hicolor/22x22/apps/krep.png
</syntaxhighlight>
{{Note| We are assuming your icon path is /usr/local/share/icons.
Find it out with the command
<syntaxhighlight lang="bash">
kde4-config --path icon
</syntaxhighlight>
}}
* delete your cache
<syntaxhighlight lang="bash">
rm -rf /var/tmp/kdecache-''user''/icon-cache.kcache
</syntaxhighlight>

According to [[Development/CMake/Addons_for_KDE#Macros]] you need to provide a 128x128 pixels icon.

= The icon naming scheme =
Example for icon names:
* hisc-apps-bla.svgz will be installed e.g. to /usr/local/share/icons/hicolor/scalable/apps/bla.svgz. ''hi'' stands for "hicolor", ''sc'' for "scalable", ''apps'' for "applications", ''bla'' for the application's name and ''.svgz'' is the suffix for gzipped scalable vector graphic files.
* hi128-app-ktimetracker.png will be installed e.g. to /usr/share/icons/hicolor/128x128/apps/ktimetracker.png. ''hi'' stands for "hicolor", ''128'' for a resolution of 128x128 pixels, ''app'' for "applications", ''ktimetracker'' for the application's name and ''.png'' is the suffix for portable network graphic files.

= example application =
In this chapter we will build - on top of the [[Development/Tutorials/Using_KActions|KAction example]] - an example application ''kicons'' that looks like this:

[[File:Snapshot-tutorial-kicon.png]]

You can obtain its source code as part of kdeexamples by calling
git clone git://anongit.kde.org/kdeexamples

== files ==
The example application consists of
* [http://quickgit.kde.org/?p=kdeexamples.git&a=blob&f=kicons/main.cpp main.cpp]
: just taken from the [[Development/Tutorials/Using_KActions|KAction example]]
* [http://quickgit.kde.org/?p=kdeexamples.git&a=blob&f=kicons/mainwindow.cpp mainwindow.cpp]
: Note the command <syntaxhighlight lang="bash">clearAction->setIcon(KIcon("tutorial-kicon"));</syntaxhighlight> that sets the icon
* [http://quickgit.kde.org/?p=kdeexamples.git&a=blob&f=kicons/mainwindow.h mainwindow.h]
: just taken from the [[Development/Tutorials/Using_KActions|KAction example]]
* [http://quickgit.kde.org/?p=kdeexamples.git&a=blob&f=kicons/world.svg world.svg]
: This is a file that defines our icon in (almost natural) english language. It is a scalable vector graphic file. Before being used, it must be converted into a zipped scalable vector graphic named ''hisc-apps-tutorial-kicon.svgz'', see below.
* [http://quickgit.kde.org/?p=kdeexamples.git&a=blob&f=kicons/tutorial-kiconui.rc tutorial-kiconui.rc]
: just taken from the [[Development/Tutorials/Using_KActions|KAction example]]
* [http://quickgit.kde.org/?p=kdeexamples.git&a=blob&f=kicons/hisc-apps-tutorial-kicon.svgz hisc-apps-tutorial-kicon.svgz]
: sorry for the name, but there are [[#The_icon_naming_scheme|naming conventions]]. Create this file with the ''convert'' command from the ''ImageMagick'' package <syntaxhighlight lang="bash">convert world.svg hisc-apps-tutorial-kicon.svgz</syntaxhighlight>
* [http://quickgit.kde.org/?p=kdeexamples.git&a=blob&f=kicons/CMakeLists.txt CMakeLists.txt]
: Note the commands <syntaxhighlight lang="bash">kde4_install_icons(${ICON_INSTALL_DIR})</syntaxhighlight> and <syntaxhighlight lang="bash">kde4_update_iconcache()</syntaxhighlight> which integrate the icons.

== build it ==
To compile, link and install the example application, do a
<syntaxhighlight lang="bash">
cmake . && make && make install
</syntaxhighlight>
To run it, call
<syntaxhighlight lang="bash">
tutorial-kicon
</syntaxhighlight>

= Analyzing the KApplications =
Maybe you have already searched for yourself how a KDE application finds its icons. You will not be successful like this:
<syntaxhighlight lang="bash">
# [http://www.linuxintro.org/wiki/Strace#Search_for_a_syscall strace -e open] ktimetracker 2>&1 | grep icon
open("/usr/lib64/libkemoticons.so.4", O_RDONLY) = 3
#
</syntaxhighlight>
You see, a KDE application (in this case ktimetracker) does not open icon files or even look for them. However, it spawns a process to look for these icons:
<syntaxhighlight lang="bash">
linux-qgla:~/repos/kdepim/ktimetracker # strace -ffe open ktimetracker 2>&1 | grep icon
open("/usr/lib64/libkemoticons.so.4", O_RDONLY) = 3
[pid 3457] open("/root/.icons/DMZ/cursors/left_ptr", O_RDONLY) = -1 ENOENT (No such file or directory)
[pid 3457] open("/root/.icons/DMZ/index.theme", O_RDONLY) = -1 ENOENT (No such file or directory)
[pid 3457] open("/usr/share/icons/DMZ/cursors/left_ptr", O_RDONLY) = 10
[pid 3457] open("/var/tmp/kdecache-root/icon-cache.kcache", O_RDWR|O_CREAT|O_CLOEXEC, 0666) = 10
[pid 3457] open("/var/tmp/kdecache-root/kpc/kde-icon-cache.data", O_RDONLY|O_CLOEXEC) = 10
[pid 3457] open("/var/tmp/kdecache-root/kpc/kde-icon-cache.index", O_RDONLY|O_CLOEXEC) = 10
[...]
</syntaxhighlight>

= Moving On =
Now you can move on to [[Development/Tutorials/Desktop_File|how to place your application in the K-Menu using .desktop files]].

[[Category:C++]]

Development/Tutorials/Icons

2011-09-28T20:06:18Z

Icwiener: Proofreading

__TOC__

When you create your own KDE application you will probably want icons in it like this:

[[File:Snapshot-krep-arrow.png]]

These icons are called [http://api.kde.org/4.x-api/kdelibs-apidocs/kdeui/html/classKIcon.html KIcon]s. This article shows you how to do this using the software [http://www.staerk.de/thorsten/krep krep] as an example. In case of a [[Development/Tutorials/CMake|
CMake]]-based project you will need to
* [http://websvn.kde.org/trunk/playground/utils/krep/main.cpp?r1=1154359&r2=1249871 modify main.cpp (as it is typically called)]
* [http://websvn.kde.org/trunk/playground/utils/krep/CMakeLists.txt?r1=813330&r2=1249871&sortby=date modify CMakeLists.txt]

How to use icons in QMake-based projects is discussed [http://appdeveloper.intel.com/en-us/Qt%20C%20Plus%20Plus%20app%20MeeGo%20SDK elsewhere].

= Your KDE project =
If you have a KDE project and want to use icons within it, and want these icons installed seamlessly, you will have to name the icons after the project. In the following we look at a project named ''krep''. The important lines in CMakeLists.txt are the ones printed bold below:
<syntaxhighlight lang="cmake">
PROJECT( krep )
FIND_PACKAGE( KDE4 REQUIRED )
INCLUDE_DIRECTORIES( ${KDE4_INCLUDES} . )

SET( krepSources main.cpp krep.cpp krep.h )

qt4_add_dbus_adaptor( krepSources
org.kde.krep.xml
krep.h
krep
mainadaptor
MainAdaptor )

kde4_add_ui_files( krepSources krepui.ui )

kde4_add_app_icon]]( krepSources "hi*-app-krep.png" )

KDE4_ADD_EXECUTABLE( krep ${krepSources} )

TARGET_LINK_LIBRARIES( krep ${KDE4_KPARTS_LIBS} )

install( TARGETS krep ${INSTALL_TARGETS_DEFAULT_ARGS} )

'''kde4_install_icons( ${ICON_INSTALL_DIR]]} )
</syntaxhighlight>
Weitere Informationen:
* [[Development/CMake/Addons_for_KDE#Macros|kde4_add_app_icon]]
* [[Development/CMake/Addons_for_KDE#The_locations_of_install_directories|ICON_INSTALL_DIR]]

= How to test it =
* delete a file
<syntaxhighlight lang="bash">
rm /usr/local/share/icons/hicolor/22x22/apps/krep.png
</syntaxhighlight>
{{Note| We are assuming your icon path is /usr/local/share/icons.
Find it out with the command
<syntaxhighlight lang="bash">
kde4-config --path icon
</syntaxhighlight>
}}
* delete your cache
<syntaxhighlight lang="bash">
rm -rf /var/tmp/kdecache-''user''/icon-cache.kcache
</syntaxhighlight>

According to [[Development/CMake/Addons_for_KDE#Macros]] you need to provide a 128x128 pixels icon.

= The icon naming scheme =
Example for icon names:
* hisc-apps-bla.svgz will be installed e.g. to /usr/local/share/icons/hicolor/scalable/apps/bla.svgz. ''hi'' stands for "hicolor", ''sc'' for "scalable", ''apps'' for "applications", ''bla'' for the application's name and ''.svgz'' is the suffix for gzipped scalable vector graphic files.
* hi128-app-ktimetracker.png will be installed e.g. to /usr/share/icons/hicolor/128x128/apps/ktimetracker.png. ''hi'' stands for "hicolor", ''128'' for a resolution of 128x128 pixels, ''app'' for "applications", ''ktimetracker'' for the application's name and ''.png'' is the suffix for portable network graphic files.

= example application =
In this chapter we will build - on top of the [[Development/Tutorials/Using_KActions|KAction example]] - an example application ''kicons'' that looks like this:

[[File:Snapshot-tutorial-kicon.png]]

You can obtain its source code as part of kdeexamples by calling
git clone git://anongit.kde.org/kdeexamples

== files ==
The example application consists of
* [http://quickgit.kde.org/?p=kdeexamples.git&a=blob&f=kicons/main.cpp main.cpp]
: just taken from the [[Development/Tutorials/Using_KActions|KAction example]]
* [http://quickgit.kde.org/?p=kdeexamples.git&a=blob&f=kicons/mainwindow.cpp mainwindow.cpp]
: Note the command <code> clearAction->setIcon(KIcon("tutorial-kicon"));</code> that sets the icon
* [http://quickgit.kde.org/?p=kdeexamples.git&a=blob&f=kicons/mainwindow.h mainwindow.h]
: just taken from the [[Development/Tutorials/Using_KActions|KAction example]]
* [http://quickgit.kde.org/?p=kdeexamples.git&a=blob&f=kicons/world.svg world.svg]
: This is a file that defines our icon in (almost natural) english language. It is a scalable vector graphic file. Before being used, it must be converted into a zipped scalable vector graphic named ''hisc-apps-tutorial-kicon.svgz'', see below.
* [http://quickgit.kde.org/?p=kdeexamples.git&a=blob&f=kicons/tutorial-kiconui.rc tutorial-kiconui.rc]
: just taken from the [[Development/Tutorials/Using_KActions|KAction example]]
* [http://quickgit.kde.org/?p=kdeexamples.git&a=blob&f=kicons/hisc-apps-tutorial-kicon.svgz hisc-apps-tutorial-kicon.svgz]
: sorry for the name, but there are [[#The_icon_naming_scheme|naming conventions]]. Create this file with the ''convert'' command from the ''ImageMagick'' package
<syntaxhighlight lang="bash">
convert world.svg hisc-apps-tutorial-kicon.svgz
</syntaxhighlight>
* [http://quickgit.kde.org/?p=kdeexamples.git&a=blob&f=kicons/CMakeLists.txt CMakeLists.txt]
: Note the commands
<syntaxhighlight lang="bash">
kde4_install_icons(${ICON_INSTALL_DIR})
</syntaxhighlight>
and
<syntaxhighlight lang="bash">
kde4_update_iconcache()
</syntaxhighlight>
which integrate the icons.

== build it ==
To compile, link and install the example application, do a
<syntaxhighlight lang="bash">
cmake . && make && make install
</syntaxhighlight>
To run it, call
<syntaxhighlight lang="bash">
tutorial-kicon
</syntaxhighlight>

= Analyzing the KApplications =
Maybe you have already searched for yourself how a KDE application finds its icons. You will not be successful like this:
<syntaxhighlight lang="bash">
# [http://www.linuxintro.org/wiki/Strace#Search_for_a_syscall strace -e open] ktimetracker 2>&1 | grep icon
open("/usr/lib64/libkemoticons.so.4", O_RDONLY) = 3
#
</syntaxhighlight>
You see, a KDE application (in this case ktimetracker) does not open icon files or even look for them. However, it spawns a process to look for these icons:
<syntaxhighlight lang="bash">
linux-qgla:~/repos/kdepim/ktimetracker # strace -ffe open ktimetracker 2>&1 | grep icon
open("/usr/lib64/libkemoticons.so.4", O_RDONLY) = 3
[pid 3457] open("/root/.icons/DMZ/cursors/left_ptr", O_RDONLY) = -1 ENOENT (No such file or directory)
[pid 3457] open("/root/.icons/DMZ/index.theme", O_RDONLY) = -1 ENOENT (No such file or directory)
[pid 3457] open("/usr/share/icons/DMZ/cursors/left_ptr", O_RDONLY) = 10
[pid 3457] open("/var/tmp/kdecache-root/icon-cache.kcache", O_RDWR|O_CREAT|O_CLOEXEC, 0666) = 10
[pid 3457] open("/var/tmp/kdecache-root/kpc/kde-icon-cache.data", O_RDONLY|O_CLOEXEC) = 10
[pid 3457] open("/var/tmp/kdecache-root/kpc/kde-icon-cache.index", O_RDONLY|O_CLOEXEC) = 10
[...]
</syntaxhighlight>

= Moving On =
Now you can move on to [[Development/Tutorials/Desktop_File|how to place your application in the K-Menu using .desktop files]].

[[Category:C++]]

Getting Started/Using an IDE with KDE4

2011-09-28T19:43:07Z

Icwiener: Proofreading

== Eclipse ==

{|align="right"
|[[image:Snapshot-eclipse.png|right|thumb|200px|KDE4's ktimetracker loaded as eclipse project]]
|}
This describes how to use Eclipse to develop KDE 4 applications. It has been tested with Eclipse Ganymede and SUSE Linux 11.1 but should work same or similar with every combination. As an example KDE application we use [http://userbase.kde.org/ktimetracker ktimetracker] from the kdepim module, other applications should work likewise.

Using this description you will be able to
* update your working copy of KDE source code using the ''svn'' command
* build your KDE module using CMake
* build your KDE application from within Eclipse using Make
* compile and run your application with one click from Eclipse
* get auto-completion when editing KDE source code
* have an overview and navigation about your classes within Eclipse
* have call trees for your functions

=== Set up Eclipse with KDE ===

* Check your requirements
: Trying with a virtual machine [[User:Tstaerk|I]] had problems starting Eclipse with less than 1 GB RAM. After assigning 3 GB RAM to the virtual machine, Eclipse finally started.

* Install Eclipse

: Download Eclipse IDE for C/C++ developers from http://www.eclipse.org. Unpack it to /home/user/eclipse.

* Install the CDT

: Download the Eclipse IDE for C/C++ Developers (68 MB) from http://www.eclipse.org/cdt/ and unpack it into your Eclipse folder, in our case /home/user/eclipse.

* Download kdepim

: As said, we use kdepim as example here. So, download ("checkout") kdepim using Subversion, e.g. as anonymous:
<syntaxhighlight lang="bash">
svn co svn://anonsvn.kde.org/home/kde/trunk/KDE/kdepim
</syntaxhighlight>
: We assume you checked out into /home/user/kdepim.

* Compile kdepim

: Compile kdepim so the usual makefiles are present for all kdepim applications. If you have problems doing this, follow our [[Getting Started/Build|build instructions]].

* Import your project into Eclipse

: Surprise: To import your project, you cannot use "File -> Import". Rather do: File -> New -> C++ Project -> Makefile project -> Empty Project -> un-tag "use default location" -> choose /home/user/kdepim/ktimetracker. Call it "ktimetracker".

* Build your project
: Make sure Project -> Properties -> C/C++ Build -> Builder Settings -> Build location -> Build directory is set correctly.
: Choose Project -> Build Project

* Run the project
: Choose Project -> Properties -> Run/Debug Settings -> New. As project, enter ''ktimetracker'', as C/C++ Application, enter /home/user/kdepim/ktimetracker/ktimetracker. Choose Apply -> Ok -> Ok. Now you can click on the "Run" button and start it.

=== Know-How ===

==== Custom builders ====

If you want to integrate the CMake build step into your build toolchain, you will need to
* create a custom ''builder'' like this:
<syntaxhighlight lang="bash">
echo "cmake . && make -j4 && make install" >/bin/eclipsebuild
chmod 777 /bin/eclipsebuild
</syntaxhighlight>
* Add your builder
: Choose Project -> Properties -> Builders. Un-tag all existing builders. Click "new" -> Program -> (name it "Builder for KDE"). -> Location: /bin/eclipsebuild -> Working directory /home/user/workspace/myproject1/kdepim.

* Build
: Now you can build your project. Every time you restart eclipse, choose myproject1 -> Project -> Properties -> C/C++ Build -> Ok -> Project -> Build.

==== Revert what eclipse did ====

To revert what eclipse did to your project simply run
<syntaxhighlight lang="bash">
rm -rf .externalToolBuilders/ .project .cproject
</syntaxhighlight>

==== Why Subversion does not work ====

When using Eclipse's svn plugin and building a KDE program, you will get error messages complaining that your svn binary is too old. If you want to try and change this, here is how you get to that error:

* Install the Subversion plug-ins
: Help -> Software Updates -> Available Software -> Add Site -> http://download.eclipse.org/technology/subversive/0.7/update-site/ -> Add Site -> http://www.polarion.org/projects/subversive/download/eclipse/2.0/update-site/

: Now add it: Subversive Site -> Subversive SVN Team Provider Plugin

: Subversive SVN Connectors Site -> Subversive SVN Connectors -> SVNKit 1.3.0 Implementation (Optional)

* Click on Install

* Restart Eclipse

* Import your KDE module
: Choose File -> New -> Other -> SVN -> Project from SVN -> https://svn.kde.org/home/kde/trunk/KDE/kdepim -> Check out as project configured using the New Project Wizard -> C++ Project -> Makefile Project -> Empty Project. As name, we choose kdepim5 -> Finish

* Set cmake as build environment
: Choose Project -> Properties -> C/C++ Build -> Builder Settings. Un-tag "use default build command", set "cmake" instead. Choose Project -> Properties -> C/C++ Build -> Behavior. Replace "all" by ".".

=== See also ===

* http://javathreads.de/2008/07/subversion-unter-eclipse-ganymede-konfigurieren/
* http://nienhueser.de/blog/?p=19

== QtCreator ==
{|align="right"
|[[image:Snapshot-qtcreator.png|right|thumb|200px|KDE4's ktimetracker loaded as QtCreator project]]
|}

Main article: [[Development/Tutorials/Using_Qt_Creator]]

This describes how to use QtCreator to develop KDE 4 applications. It has been tested with QtCreator 1.2.80 and SUSE Linux 11.1 but should work same or similar with every combination. As an example KDE application we use [http://userbase.kde.org/ktimetracker ktimetracker] from the kdepim module, other applications should work likewise.

=== Load an existing project ===
As discussed here we use ktimetracker as example project.
* Import the CMakeLists.txt file
File -> Open -> kdepim/CMakeLists.txt.
* Configure QtCreator to build only ktimetracker
Projects -> ktimetracker -> build settings -> Add a configuration ktimetracker.

As build directory choose kdepim. As arguments for CMake use e.g.
<syntaxhighlight lang="cmake">
. -DCMAKE_INSTALL_PREFIX=/usr/local -DLIB_SUFFIX=64 -DCMAKE_BUILD_TYPE=debugfull
</syntaxhighlight>

=== Start a KDE project ===
To start a new project you need to tell QtCreator to use the KDE libraries when building. So, choose File -> New... and create your project. We will call it ''yourproject'' here. To be able to use KDE's libraries, go to your home directory, change into ''yourproject'' and modify the file ''yourproject.pro''. Add the line
<syntaxhighlight lang="cmake">
LIBS += -lkdeui
</syntaxhighlight>

== KDevelop 3 (outdated by KDevelop 4) ==

This section will explain how to use KDevelop 3.4 to develop KDE 4 applications. If you have any questions, corrections or rants about this section, please post them on the discussion page.

=== Prerequisites ===

You need at least KDevelop 3.4 for this, which is still a KDE 3 application. Versions lower than 3.4 do not have Qt 4 support among other things. You can get KDevelop at the [http://www.kdevelop.org/index.html?filename=3.4/download.html KDevelop homepage]. Make sure you install KDevelop like all other KDE 3 applications, '''not''' with your ''kde-devel'' user.

You also need the lastest ''GDB'' version, which is currently 6.6.0.
Note that the GDB version which is shipped with '''openSuse 10.3 is broken''', it constantly crashes when examining variables (which KDevelop does automatically). Use the GDB version from [http://download.opensuse.org/repositories/home:/amilcarlucas/openSUSE_10.3/ this repository] instead.

You need to have the kdelibs API documentation locally, which is described in the [[Development/Tools/apidox|build instructions]].

You also need ''ctags'', ''htdig'', ''htmerge'' and ''htsearch''. ''valgrind'' and ''callgrind'' can also be useful.

Be sure you followed the steps in the KDE 4 [[Getting_Started/Build|build instructions]] and have a working KDE 4 environment. Make sure simple KDE 4 applications like ''Konsole'' or ''KWrite'' can be started from the command line of the ''kde-devel'' user without problems.

The following steps are all done with the ''kde-devel'' user. You need to login as that user by typing
<syntaxhighlight lang="bash">
su - kde-devel
</syntaxhighlight>

KDevelop has no native support for CMake projects. Fortunately, CMake has the ability to generate KDevelop project files itself. In order to do this, you need to pass the ''-GKDevelop3'' flag to the ''cmake'' command. This tells CMake to generate project files for KDevelop alongside the normal makefiles. The best way to do this is to modify your ''cmakekde'' function in your [[Getting_Started/Increased_Productivity_in_KDE4_with_Scripts/.bashrc|{{path|.bashrc}}]]. Just change
<syntaxhighlight lang="bash">
cmake $srcFolder -DCMAKE_INSTALL_PREFIX=$KDEDIR \
-DCMAKE_BUILD_TYPE=debugfull&& \
make && \
make install;
</syntaxhighlight>
to
<syntaxhighlight lang="bash">
cmake $srcFolder -GKDevelop3 -DCMAKE_INSTALL_PREFIX=$KDEDIR \
-DCMAKE_BUILD_TYPE=debugfull&& \
make && \
make install;
</syntaxhighlight>

After you have done that, re-login so that the changes to the {{path|.bashrc}} file take effect. Then you need to rerun ''cmakekde'' in the (root) build directory of the project you want to work on with KDevelop (if you didn't use ''-GKDevelop3'' on the [[Getting_Started/Build/Environment|building step]]). For example, if you want to work on Konsole, which lives in ''kdebase'', you need to run cmakekde in the {{path|$KDE_BUILD/KDE/kdebase}} directory. This unfortunately completely rebuilds everything, but only once when you change the generator.

Since all environment variables of the kde-devel user are KDE 4 specific, these need to be set back to match your KDE 3 environment before starting KDevelop.
A simple way to do this is to add the following function to your {{path|.bashrc}}:

<syntaxhighlight lang="bash">
function start3app {
mkdir -p /tmp/$USER-kde
export PATH=/opt/kde3/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/bin/X11:/usr/games
export LD_LIBRARY_PATH=
export KDETMP=/tmp/$USER-kde
export KDEVARTMP=/var/tmp/$USER-kde
export KDEHOME=$HOME/.kde
export KDEDIR=/usr
export KDEDIRS=$KDEDIR
export DISPLAY=:0
eval "$@"
source $HOME/.bashrc #Reset environment variables again
}
</syntaxhighlight>

The ''PATH'' and ''LD_LIBRARY_PATH'' variables are taken from the KDE 3 user, and they may be different on your system. Type <syntaxhighlight lang="bash">echo $PATH</syntaxhighlight> and <syntaxhighlight lang="bash">echo $LD_LIBRARY_PATH</syntaxhighlight> as normal KDE 3 user to get these values. The above function assumes that KDE 3 is installed in the {{path|/usr}} prefix, as it is the case on Debian-based systems. If your KDE 3 is installed to a different prefix, you need to change the line setting ''KDEDIR'' accordingly. Here's an example how you find out your KDE installation prefix; in this example it is /opt/kde3:

<syntaxhighlight lang="bash">
kde-config --prefix
/opt/kde3
</syntaxhighlight>

Now you should be able to start KDevelop by typing <tt>start3app kdevelop</tt>. Do that now.

{{tip|
You can start any KDE 3 application with the <tt>start3app</tt> function. Useful candidates include ''Kompare'' and ''kdesvn''.

However, you can not start ''KDbg'' this way to debug KDE 4 applications, since then the environment variables for the debugged application are wrong.
}}


==== TroubleShooting ====

'''Symptome:''' kdevelop says "cannot talk to klauncher". You cannot open a file.

'''Solution:''' add your KDE library path to LD_LIBRARY_PATH, e.g.:
export LD_LIBRARY_PATH=/opt/kde3/lib

=== Setting up KDevelop ===

Now that KDevelop has started, you need to adjust a few settings. Go to ''Settings->Configure KDevelop...->Documentation'' for this. Remove all entries that are not relevant to KDE 4 coding.

{{note|Although environment variables like $HOME are used in this section, you should replace them with real paths because KDevelop does not resolve environment variables.}}

Optionally, you can add the kdelibs API documentation. You must [[Development/Tools/apidox|create it beforehand]]. Then add the documentation by clicking ''Add...''. In this dialog, use the following settings:
* ''Type'': Doxygen Documentation Collection (needs to be set first)
* ''Location'': {{path|$KDE_SRC/KDE/kdelibs/kdelibs-apidocs/index.html}}

Now add the Qt API documentation, which also must be [[Development/Tools/apidox|created beforehand]], using the following settings:
* ''Type'': Qt Documentation Collection (needs to be set first)
* ''Location'': {{path|$HOME/qt-copy/doc/html/qt.dcf}}

After you have added kdelibs and Qt API documentation, make sure all checkboxes (''TOC'',''Index'' and ''Search'') are enabled. Then, go to the ''Full Text Search'' tab and make sure the paths to the ''htdig'', ''htmerge'' and ''htsearch'' executables are correct. You can then close the settings dialog.

Now it is time to open the project you want to work on by clicking ''Project->Open Project...''. The project files are located in the build directory. For example, if you want to work on Konsole, you need to open {{path|$KDE_BUILD/KDE/kdebase/apps/konsole/konsole.kdevelop}}. You now need to adjust a few project-specific settings in ''Project->Project Options''. You need to do this every time you start to work on a different project.

{{note|
Sometimes, a KDevelop project file is not present for the folder you want to work on.

This can have several reasons, it depends on how the CMake files are written. Usually, CMake files which have a <tt>project(projectname)</tt> statement in them should work fine. Once you are familiar enough with CMake, you can try adding the statement.

A workaround for this is to simply use the KDevelop project file of the parent folder, or even higher. In this case, you need to use the <tt>Make Active Directory</tt> entry in the context menu of the <tt>File Selector</tt> sidetab. With this, you can ignore the other unwanted folders when building and installing.
}}

* ''C++ Support->Code Completion''
:Here you need to add code completion databases for Qt and kdelibs, and more if you like, for example you might need a database for ''kdepimlibs'' when working on ''kdepim''.

:For kdelibs, click the ''Add...'' button and choose ''KDevelop Custom Directory PCS Importer'', then add your KDE include directory ({{path|$HOME/kde/include}}) to the list and proceed. You can use the file selection dialog and the ''Add'' button to add it.

:Now, add the database for Qt 4 by selecting ''KDevelop Qt4 PCS Importer'' this time. You need to select the Qt 4 include directory, which is {{path|$HOME/qt-copy/include}}.

{{note|The Qt4 PCS Importer is only needed if you didn't install Qt4, i.e. you use it directly from the build directory. The drawback of using the Qt4 importer is that it doesn't show progress and the application seems to hang while it imports. The alternative is to use the Custom Directory PCS Importer for this too}}

* ''C++ Support->Qt Options''
:Check ''Enable Qt options'' and choose Qt4 as your version. Set the ''QMake Binary'' path to {{path|$HOME/qt-copy/bin/qmake}}. Then choose ''Qt 4 style'' as ''Qt include syntax''. Use {{path|$HOME/qt-copy/bin/designer}} as ''Designer Binary''. Make sure to use the ''Change Plugin Paths'' dialog to add the plugin directory from KDE so you see the KDE widgets when designer is started. To do this add {{path|$HOME/kde/lib/kde4/plugins}} to the lineedit and then click the ''Add'' button.

* ''Run Options''
:Make sure you use the correct binary as ''Executable''. For example, if you want to run Konsole, this is {{path|$KDE_BUILD/KDE/kdebase/apps/konsole/src/konsole}}. You should add ''--nofork'' to the ''Debug Arguments'' or debugging some applications like ''KMail'' will not work at all.

:Because the ''start3app'' functions changes some environment variables, you need to change them back here so the KDE 4 applications can be run without problems from within KDevelop.
:For some applications, like Konsole, this is not strictly necessary, but others like KMail will crash if you do not change this.
:Simply click the ''Add / Copy'' button to add new environment variables. You will need the following, which are the same as in your [[Getting_Started/Increased_Productivity_in_KDE4_with_Scripts/.bashrc|{{path|.bashrc}}]]:

:{| border="1"
|-
! Name
! Value
|-
| KDEHOME
| $HOME/.kde4
|-
| PATH
| $KDEDIR/bin:$QTDIR/bin:/usr/local/bin:$PATH
|-
| LD_LIBRARY_PATH
| $KDEDIR/lib:$QTDIR/lib:$LD_LIBRARY_PATH
|-
| KDETMP
| /tmp/$USER-kde4
|-
| KDEVARTMP
| /var/tmp/$USER-kde4
|-
| KDEDIR
| $HOME/kde
|-
| KDEDIRS
| $KDEDIR
|-
| LD_BIND_NOW
| 42
|}

* ''Build Options->Build''
:Make sure the correct build directory is selected. Again, for Konsole, this would be {{path|$KDE_BUILD/KDE/kdebase/apps/konsole}}.

* ''Build Options->Make''
:You might want to check ''Abort on first error''. You also might want to add ''VERBOSE='' or ''VERBOSE=1'' to ''Additional make options'' to control the level of verbosity for the build process.

:If you have more than one processor or if you have access to an icecream cluster, you might want to check the ''Run multiple jobs'' option and set the ''Number of simultaneous jobs'' to the number of available processors. This increases the compile speed. It is the same as the <tt>-j</tt> option for ''make''.

* ''Formatting''
:You should set all options here to match the coding style of the project you are working on.

* ''CTags->General''
:You need to correctly set the ''Path to ctags binary'', which is {{path|/usr/bin/ctags}} on Debian-based systems.

:You probably want to enable the <tt>When more than one hit, go directly to the first</tt> option.

Now you have finished adjusting your project-specific settings. Now you should remove some plugins you do not need, in ''Settings->Configure Plugins...''. I for example disable the following plugins:

Abbreviation Expansion, Code Snippets, Doxygen Support, Embedded Konsole, File Tree, '''Final Packaging Support''', "Open with" Menu Addon, QuickOpen, Regular Expression Tester, Scripting, '''Security Checker''', Shell Filtering and Insertion, Text Structure and Tools Menu Addition.

You should at least disable the bold ones.

Now, open any source file if none is open already. This will enable the ''Settings->Configure Editor...'' entry, where you need to set the tab options to match the tab style used by the project you are working on. The important settings are:
* ''Appearance->Borders->Show line numbers'': Should be checked.
* ''Appearance->Borders->Show icon border'': Should be checked.
* ''Editing->Tabulators''
* ''Editing->Static Word Wrap->Show marker'': Should be checked
* ''Indentation->Automatic Indentation->Indentation mode'': Should be ''C Style''
* ''Indentation'' in general

In the mainwindow, click the ''CTags'' tab on the bottom tabbar, then click the ''Regenerate'' button to create a CTags database for easier source code navigation.

Now you have completed all essential configuration, congratulations!

=== Using KDevelop ===

Refer to the [http://docs.kde.org/development/en/kdevelop/kdevelop/ KDevelop manual] for general help using KDevelop. The following section will only deal with special cases for KDE 4.

==== Debugging ====

KDE apps have many symbols, which means that you need a lot of memory to get a decent loading times for debugging. To quote a GDB developer: "I would be reluctant to debug KDE on something with <1GB RAM."
If the stepping function of the debugger is slow for you, try the following tips:
* Hide local variables. The <tt>Locals</tt> part of the variable tab on the left causes a big slowdown when stepping if you have many local variables. Simple collapse the <tt>Locals</tt> part of the tree, the local variables are then not updated every step. You can still examine variables by using the <tt>Evaluate expression</tt> function.
* Use the patch at http://bugs.kde.org/show_bug.cgi?id=143977. It prevents the update of the framestack widget at each step, speeding up stepping considerably. The patch introduces some minor glitches, which is why it is not yet commited.

{{Note|
KDevelop does not yet support modifing the CMake build system. This means you can not use KDevelop to add or remove files from the project or to change any other aspect of your project's build process.

You need to modify the CMake files by hand and then rerun <tt>cmakekde</tt> instead. Read the [[Development/Tutorials/CMake|CMake tutorial]] to learn how to do this.
}}

{{tip|When you work on libraries, you first need to install them before you can test or debug your changes.
Since this is cumbersome and time consuming, you should create symlinks ''(ln -s)'' pointing from the build directory to the installation directory for all affected libraries.

Often, even simple programs use libraries internally, for example the settings dialog of Konsole is really a library.}}

Projects/MovetoGit/Progress

2011-08-20T19:55:38Z

Icwiener: Fix colours.

=== What to take from where for release? ===

{| cellspacing="0" cellpadding="5" border="1" style="border:1px solid gray; border-collapse:collapse; width:100%;"
|- style="background:#afafaf;"
! Module/Application
! branch name scheme / comment
! 4.7
! 4.8
|- style="background:#dfdfdf;"
| '''kdeaccessibility'''
| align="right" | rules done, migration pending
| style="background-color: lightpink;" | SVN
| style="background-color: lightpink;" | SVN
|- style="background:#dfdfdf;"
| '''kdeadmin'''
| not yet
| style="background-color: lightpink;" | SVN
| style="background-color: lightpink;" | SVN
|- style="background:#dfdfdf;"
| '''kdeartwork'''
| not yet
| style="background-color: lightpink;" | SVN
| style="background-color: lightpink;" | SVN
|- style="background:#dfdfdf;"
| '''kdebase'''
| -
| -
| -
|-
| style="padding-left:50px;" | kde-runtime
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kde-workspace
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kde-baseapps
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kate
| align="right" | in 4.6 released from kdelibs/kdesdk
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | konsole
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|- style="background:#dfdfdf;"
| '''kdebindings'''
| -
| -
| -
|-
| style="padding-left:50px;" | kimono
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | qyoto
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kross-interpreters
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | perlkde
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | perlqt
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | pykde4
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | korundum
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | qtruby
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | smokegen
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | smokekde
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | smokeqt
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
|- style="background:#dfdfdf;"
| '''kdeedu'''
| -
| -
| -
|-
| style="padding-left:50px;" | blinken
| 1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | cantor
| 1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kalgebra
| 1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kalzium
| 1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kanagram
| 1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kbruch
| 1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kgeography
| 1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | khangman
| 1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kig
| 1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kiten
| 1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | klettres
| 1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kmplot
| 1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kstars
| 1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | ktouch
| 1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kturtle
| 1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kwordquiz
| 1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | libkdeedu
| 1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | marble
| kde-1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | parley
| 1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | rocs
| 1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | step
| 1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|- style="background:#dfdfdf;"
| '''kdegames'''
| not yet
| style="background-color: lightpink;" | SVN
| style="background-color: lightpink;" | SVN
|- style="background:#dfdfdf;"
| '''kdegraphics'''
| -
| -
| -
|-
| style="padding-left:50px;" | libksane
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | libkexiv2
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | libkdcraw
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | libkipi
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | ksaneplugin
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kolourpaint
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | ksnapshot
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | gwenview
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kruler
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | mobipocket
| 1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | svgpart
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kcolorchooser
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kgamma
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kdegraphics-strigi-analyzer
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kdegraphics-thumbnailers
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kamera
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | okular
| 1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|- style="background:#dfdfdf;"
| '''kdelibs'''
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|- style="background:#dfdfdf;"
| '''kdemultimedia'''
| not yet
| style="background-color: lightpink;" | SVN
| style="background-color: lightpink;" | SVN
|- style="background:#dfdfdf;"
| '''kdenetwork'''
| not yet
| style="background-color: lightpink;" | SVN
| style="background-color: lightpink;" | SVN
|- style="background:#dfdfdf;"
| '''kdepim'''
| -
| -
| -
|-
| style="padding-left:50px;" | kdepim
| 1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kdepim-runtime
| 1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kdepimlibs
| 1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|- style="background:#dfdfdf;"
| '''kdeplasma-addons'''
| 1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|- style="background:#dfdfdf;"
| '''kdesdk'''
| not yet
| style="background-color: lightpink;" | SVN
| style="background-color: lightpink;" | SVN
|- style="background:#dfdfdf;"
| '''kdetoys'''
| not yet
| style="background-color: lightpink;" | SVN
| style="background-color: lightpink;" | SVN
|- style="background:#dfdfdf;"
| '''kdeutils''' (TODO: split this section into its apps)
| 1.2
| style="background-color: lightpink;" | SVN
| style="background-color: lightgreen;" | Git
|- style="background:#dfdfdf;"
| '''kdewebdev'''
| not yet
| style="background-color: lightpink;" | SVN
| style="background-color: lightpink;" | SVN
|- style="background:#dfdfdf;"
| '''kdesupport (somewhat)'''
|
| -
| -
|-
| style="padding-left:50px;" | kde-wallpapers
|
| style="background-color: white;" | ?
| style="background-color: lightpink;" | SVN
|-
| style="padding-left:50px;" | oxygen-icons
|
| style="background-color: lightpink;" | SVN
| style="background-color: lightpink;" | SVN
|-
|}

Projects/MovetoGit/Progress

2011-08-20T19:53:22Z

Icwiener: Update

=== What to take from where for release? ===

{| cellspacing="0" cellpadding="5" border="1" style="border:1px solid gray; border-collapse:collapse; width:100%;"
|- style="background:#afafaf;"
! Module/Application
! branch name scheme / comment
! 4.7
! 4.8
|- style="background:#dfdfdf;"
| '''kdeaccessibility'''
| align="right" | rules done, migration pending
| style="background-color: lightpink;" | SVN
| style="background-color: lightpink;" | SVN
|- style="background:#dfdfdf;"
| '''kdeadmin'''
| not yet
| style="background-color: lightpink;" | SVN
| style="background-color: lightpink;" | SVN
|- style="background:#dfdfdf;"
| '''kdeartwork'''
| not yet
| style="background-color: lightpink;" | SVN
| style="background-color: lightpink;" | SVN
|- style="background:#dfdfdf;"
| '''kdebase'''
| -
| -
| -
|-
| style="padding-left:50px;" | kde-runtime
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kde-workspace
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kde-baseapps
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kate
| align="right" | in 4.6 released from kdelibs/kdesdk
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | konsole
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|- style="background:#dfdfdf;"
| '''kdebindings'''
| -
| -
| -
|-
| style="padding-left:50px;" | kimono
| KDE/1.2
| style="background-color: lightpink;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | qyoto
| KDE/1.2
| style="background-color: lightpink;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kross-interpreters
| KDE/1.2
| style="background-color: lightpink;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | perlkde
| KDE/1.2
| style="background-color: lightpink;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | perlqt
| KDE/1.2
| style="background-color: lightpink;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | pykde4
| KDE/1.2
| style="background-color: lightpink;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | korundum
| KDE/1.2
| style="background-color: lightpink;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | qtruby
| KDE/1.2
| style="background-color: lightpink;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | smokegen
| KDE/1.2
| style="background-color: lightpink;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | smokekde
| KDE/1.2
| style="background-color: lightpink;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | smokeqt
| KDE/1.2
| style="background-color: lightpink;" | Git
| style="background-color: lightgreen;" | Git
|-
|- style="background:#dfdfdf;"
| '''kdeedu'''
| -
| -
| -
|-
| style="padding-left:50px;" | blinken
| 1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | cantor
| 1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kalgebra
| 1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kalzium
| 1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kanagram
| 1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kbruch
| 1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kgeography
| 1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | khangman
| 1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kig
| 1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kiten
| 1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | klettres
| 1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kmplot
| 1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kstars
| 1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | ktouch
| 1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kturtle
| 1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kwordquiz
| 1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | libkdeedu
| 1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | marble
| kde-1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | parley
| 1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | rocs
| 1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | step
| 1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|- style="background:#dfdfdf;"
| '''kdegames'''
| not yet
| style="background-color: lightpink;" | SVN
| style="background-color: lightpink;" | SVN
|- style="background:#dfdfdf;"
| '''kdegraphics'''
| -
| -
| -
|-
| style="padding-left:50px;" | libksane
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | libkexiv2
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | libkdcraw
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | libkipi
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | ksaneplugin
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kolourpaint
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | ksnapshot
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | gwenview
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kruler
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | mobipocket
| 1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | svgpart
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kcolorchooser
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kgamma
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kdegraphics-strigi-analyzer
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kdegraphics-thumbnailers
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kamera
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | okular
| 1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|- style="background:#dfdfdf;"
| '''kdelibs'''
| KDE/1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|- style="background:#dfdfdf;"
| '''kdemultimedia'''
| not yet
| style="background-color: lightpink;" | SVN
| style="background-color: lightpink;" | SVN
|- style="background:#dfdfdf;"
| '''kdenetwork'''
| not yet
| style="background-color: lightpink;" | SVN
| style="background-color: lightpink;" | SVN
|- style="background:#dfdfdf;"
| '''kdepim'''
| -
| -
| -
|-
| style="padding-left:50px;" | kdepim
| 1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kdepim-runtime
| 1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|-
| style="padding-left:50px;" | kdepimlibs
| 1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|- style="background:#dfdfdf;"
| '''kdeplasma-addons'''
| 1.2
| style="background-color: lightgreen;" | Git
| style="background-color: lightgreen;" | Git
|- style="background:#dfdfdf;"
| '''kdesdk'''
| not yet
| style="background-color: lightpink;" | SVN
| style="background-color: lightpink;" | SVN
|- style="background:#dfdfdf;"
| '''kdetoys'''
| not yet
| style="background-color: lightpink;" | SVN
| style="background-color: lightpink;" | SVN
|- style="background:#dfdfdf;"
| '''kdeutils'''
| 1.2
| style="background-color: lightpink;" | SVN
| style="background-color: lightpink;" | Git
|- style="background:#dfdfdf;"
| '''kdewebdev'''
| not yet
| style="background-color: lightpink;" | SVN
| style="background-color: lightpink;" | SVN
|- style="background:#dfdfdf;"
| '''kdesupport (somewhat)'''
|
| -
| -
|-
| style="padding-left:50px;" | kde-wallpapers
|
| style="background-color: white;" | ?
| style="background-color: lightpink;" | SVN
|-
| style="padding-left:50px;" | oxygen-icons
|
| style="background-color: lightpink;" | SVN
| style="background-color: lightpink;" | SVN
|-
|}

Development/Tutorials/Creating Libraries

2011-06-30T11:57:01Z

Icwiener: Fix syntax highlighting.

{{Template:I18n/Language Navigation Bar|Development/Tutorials/Creating Libraries}}

==Abstract==

If a part of your code could be used by more than one software module, like other programs or plugins, you should put that part in a shared library. This tutorial tells how to add the library to the buildsystem and how to prepare the source code.

==Separating the code==

It is good practise to put all source files for a library in a separate directory.

This tutorial assumes you want to create a shared library named '''myshare''', which contains the classes '''MyAClass''' and '''MyBClass'''. Both classes use internally the classes '''MyInternalCClass''' and '''MyInternalDClass''', but these are not found in their public interfaces.

The classes are declared and defined in the files ''myaclass.h'', ''myaclass.cpp'', ''mybclass.h'', ''mybclass.cpp'', ''myinternalcclass.h'', ''myinternalcclass.cpp'', ''myinternaldclass.h'', and ''myinternaldclass.cpp''.

==Adding the library to the buildsystem==

You also need a file CMakeLists.txt in the same directory as the source files:
<syntaxhighlight lang="cmake">
include_directories(
# any directories needed by the sources of the library
)

set( myshared_LIB_SRCS
myaclass.cpp
mybclass.cpp
myinternalcclass.cpp
myinternaldclass.cpp
)

kde4_add_library( myshared SHARED ${myshared_LIB_SRCS} )

target_link_libraries( myshared
${KDE4_KDECORE_LIBS}
)
set_target_properties( myshared
PROPERTIES VERSION ${GENERIC_LIB_VERSION} SOVERSION ${GENERIC_LIB_SOVERSION}
)

install( TARGETS myshared ${INSTALL_TARGETS_DEFAULT_ARGS} )
</syntaxhighlight>

The instructions are similar to the ones for a program. But instead of calling <tt>kde4_add_executable()</tt> you use <tt>kde4_add_library()</tt> to register the library <tt>myshared</tt>. The parameter <tt>SHARED</tt> is needed as this declares the library is a shared one, not a static.

Like with a program, other libraries that are used have to be defined with <tt>target_link_libraries()</tt>.

The version number of the library is set by <tt>set_target_properties()</tt>.

And <tt>install()</tt> moves the library to a place where it can be loaded.

==Declaring exported classes and methods==

If a library gets compiled, all functions or class methods it offers get listed as so called symbols in a table. Each symbol points to the offset in the library where the corresponding code can be found.

Adding also functions or class methods to the table which are not intended to be called from the outside is of no use. It just bloats the table and asks others to make calls to them against your will. For the library myshared you do not want to add the methods of the classes MyInternalCClass and MyInternalDClass.

In the KDE buildsystem you need to put explicitly a tag to all the classes and functions which the library should provide externally. This tag has to have a different name for each library.

For this add a file myshared_export.h to the directory of the library, containing:

<syntaxhighlight lang="cpp-qt">
#ifndef MYSHARED_EXPORT_H
#define MYSHARED_EXPORT_H

// needed for KDE_EXPORT and KDE_IMPORT macros
#include <kdemacros.h>

#ifndef MYSHARED_EXPORT
# if defined(MAKE_MYSHARED_LIB)
// We are building this library
# define MYSHARED_EXPORT KDE_EXPORT
# else
// We are using this library
# define MYSHARED_EXPORT KDE_IMPORT
# endif
#endif

# ifndef MYSHARED_EXPORT_DEPRECATED
# define MYSHARED_EXPORT_DEPRECATED KDE_DEPRECATED MYSHARED_EXPORT
# endif

#endif
</syntaxhighlight>

This macro code defines the tag <tt>MYSHARED_EXPORT</tt> for the library.

Now you prepare all classes by adding a include for the header with the library's export tag and putting the export tag defined above in front of the class name, like this:
<syntaxhighlight lang="cpp-qt">
#include "myshared_export.h"

class MYSHARED_EXPORT MyAClass {
// class declaration as usual
};
</syntaxhighlight>

And the same with the other class:
<syntaxhighlight lang="cpp-qt">
#include "myshared_export.h"

class MYSHARED_EXPORT MyBClass {
// class declaration as usual
};
</syntaxhighlight>

{{warning|
Beware that header-only classes, even additionally based on templates, must not have an export tag. Their methods do not end as any symbol in the library. Instead all machine code is created on demand in the external calling software, if compiled.}}

==Enabling others to compile using your library==

You need also tell the buildsystem to install the header files. Without this external code can not build, as it can not include the files and thus the class and methods declarations of your library. You do this by adding to the library's CMakeLists.txt:

<syntaxhighlight lang="cmake">
set( myshared_LIB_HDRS
myshared_export.h
myaclass.h
mybclass.h
)
install( FILES ${myshared_LIB_HDRS}
DESTINATION ${INCLUDE_INSTALL_DIR}/myshared
COMPONENT Devel
)
</syntaxhighlight>

Of course also myshared_export.h is installed, as it gets included by the headers of both classes.

External KDE code which should use the library's classes and functions now can include the headers by the lines:

<syntaxhighlight lang="cpp-qt">
#include <myshared/myaclass.h>
#include <myshared/mybclass.h>
</syntaxhighlight>

==Getting the version numbers right==

By installing the header files you are releasing your library officially. External code will rely on the interfaces declared by the headers. So you need to care for binary and behaviour compatibility if developing your library further. Any changes in the next release should be reflected in the version number, so external code gets compiled, linked and run with the matching version of your library.

As you already saw above the version of your library is defined by <tt>set_target_properties()</tt>:
<syntaxhighlight lang="cmake">
set_target_properties( myshared
PROPERTIES VERSION ${GENERIC_LIB_VERSION} SOVERSION ${GENERIC_LIB_SOVERSION}
)
</syntaxhighlight>

So there are two different kind of versions, the development version <tt>VERSION</tt> and the ABI version <tt>SOVERSION</tt>. Both will be explained now.

=== Defining the development version ===
The value of <tt>VERSION</tt> defines the development state of your library. It is good practice to use a pattern "major.minor.patch-level".
For each release you need to update or reset the different parts:
* Only bug fixes added: increase the patch-level, e.g. 2.3.10 -> 2.3.11
* New functionality added, while keeping the old functionality: increase the minor number, reset the patch-level, e.g. 2.3.10 -> 2.4.0
* Binary or behaviour changes of old functionality, regardless of any new functionality: increase the major number, reset the minor number and the patch-level, e.g. 2.3.10 -> 3.0.0
This version ends in the name of the resulting library file, e.g. on Linux "libmyshared.so.2.3.10" or "libmyshared.2.3.10.so".

=== Defining the ABI version ===
The value of <tt>SOVERSION</tt> defines the ABI variant of your library. It is a single always increasing integer, numbering the versions with non-backward-compatibel changes. So if you release a new version with some binary or behaviour changes you need to increase this version number by one, e.g. 2->3, otherwise you keep it.

{{tip|
If you follow the rules given above for the <tt>VERSION</tt> version, the value of <tt>SOVERSION</tt> will of course match the major number of it. So with a <tt>VERSION</tt> of 2.3.10 the <tt>SOVERSION</tt> value would be 2. But this is no necessity.}}

This version ends in a reference with ABI versioning to the resulting library file, e.g. on Linux in the symbolic link "libmyshared.so.2", which points to the real library file. These versioned references are used by the dynamic linker to load the version of the library with the matching ABI variant to a running executable. Executables which are linked to a shared library have a note which ABI variant of these libray is needed.

{{warning|
This concept of ABI versioning breaks if the executable got linked to a newer version of the library (e.g. 2.4.0) which is backward-compatible to older versions (all 2.0-3.*) but additionally offers new functionality that also gets used by the executable.

Because conforming to the concept the older versions have the same ABI version like the newer one (e.g. 2). So if only an older version of the library is installed (e.g. 2.1.8) the executable is still started as the tested prerequisites (ABI version) are matched, but it will crash due to the missing functionality if the library gets finally loaded.

In a compilation-from-sourcecode-based system this just should not happen, unless you downgrade a library again. And in a package-based system dependency checks on de-/installations of packages which also care for the <tt>VERSION</tt> version should prevent this. So you might also forget about this problem.
}}

===Using the generic versions===
If you are developing your library inside a normal KDE module, e.g. kdeutils, and all new versions of your library are only released together with the usual KDE releases, of course following the policies regarding ABI as demanded, you do not need to take care of the versioning yourself. Just use the generic variables <tt>${GENERIC_LIB_VERSION}</tt> and <tt>${GENERIC_LIB_SOVERSION}</tt> as shown above. Using the generic version numbers also helps to identify a version of your library by the general KDE version.

E.g. for KDE 4.1.0 these variables are defined in kdelibs/cmake/modules/KDE4Defaults.cmake with
<syntaxhighlight lang="cmake">
set(GENERIC_LIB_VERSION "4.1.0")
set(GENERIC_LIB_SOVERSION "4")
</syntaxhighlight>

==Making localization work==

If your shared library contains translations you have to help a little so a program which uses your library can make use of them.

You mark the strings to be translated [[Development/Tutorials/Localization/i18n|as usual]]. And
[[Development/Tutorials/Localization/i18n Build Systems|like you do with programs]] you have to add a shell script named <tt>Messages.sh</tt> in the toplevel directory of your shared library to collect all the strings, e.g.:
<syntaxhighlight lang="bash">
#!bin/sh
# fetch all strings in files that are not source code
$EXTRACTRC `find . -name \*.rc -o -name \*.ui -o -name \*.kcfg` >> rc.cpp
# fetch all strings in source code files
$XGETTEXT `find . -name \*.cc -o -name \*.cpp -o -name \*.h` -o $podir/libmyshare.pot
</syntaxhighlight>
So all strings will end in a catalog named <tt>libmyshare</tt>.

While for programs and most plugins the translations are loaded automatically, for shared libraries you have to do it manually. You do so by adding in the program after the creation of the <tt>KApplication</tt> or <tt>KCoreApplication</tt> instance the line:
<syntaxhighlight lang="cpp-qt">
KGlobal::locale()->insertCatalog( "libmyshare" );
</syntaxhighlight>
The method <tt>insertCatalog()</tt> will load the translated strings in the current language from the catalog named <tt>libmyshare</tt>.

==Organizing your program code with static libraries==
Sharing code with others is one reason to separate code into libraries.
Another reason is the need to organize a large code base.

A useful approach to give a structure to code is to separate the source files in different subdirectories, each subdirectory containing only code for a certain domain, e.g. a subdirectory "utils" for all utility classes or "gui" for all gui related code.

Instead of one big central CMakeLists.txt file you also use an own CMakeLists.txt file per subdirectory, which is also placed in that subdirectory. In each of these CMakeLists.txt files you advise the build system to construct a separate package of the compiled sources in the given directory, a so called convenience library or, in technical terms, static library.

E.g. for the subdirectory "myutils" "myutils/CMakeLists.txt" looks like:

<syntaxhighlight lang="cmake">
include_directories(
# only as needed for the sources of this directory/library
)

set( myutils_LIB_SRCS
myutilaclass.cpp
myutilbclass.cpp
myinternalutilcclass.cpp
myinternalutildclass.cpp
)

kde4_add_library( myutils STATIC ${myutils_LIB_SRCS} )
</syntaxhighlight>

The instructions are similar to the ones for a shared library. In the call <tt>kde4_add_library()</tt> you just use the parameter <tt>STATIC</tt> instead to declare the library is a static one.

This library is only used as an intermediate product in the total build process. So you neither need to set a version number with <tt>set_target_properties()</tt> or declare at this point other libraries to link against with <tt>target_link_libraries()</tt>, like you do with a shared library. And you do not install anything, neither the lib or any header files. You also do not mark exported classes or functions, all will be available to external code. You declare any dynamic libraries used by the library at another place, see below.

With <tt>include_directories()</tt> you also have to list the include directories needed for the source files in the directory, and only these. So you get more control with regard to dependencies than with one big central CMakeLists.txt file.

To have all the local CMakeLists.txt files get used by the build system you need to add each subdirectory to the CMakeLists.txt file in the upper directory, with the call <tt>add_subdirectory()</tt>, e.g.
<syntaxhighlight lang="cmake">
add_subdirectory( myutils )
add_subdirectory( mygui )
</syntaxhighlight>

This inclusion can be done recursively, so in a subdirectory you can add again the subsubdirectory.

Finally you need to tell the buildsystem to also use the static libraries to construct the complete program. You do so by including their names in the <tt>target_link_libraries()</tt> call for the program. There you also add any not already listed shared library which is used by code in your static libraries, as told above. So to construct the program myprogram using the static libraries mygui and myutils you write the CMakeLists.txt like e.g.:

<syntaxhighlight lang="cmake">
target_link_libraries( myprogram
mygui
myutils
# and all needed dynamic libraries, like the KDE ones and else,
# also the ones needed by your static libraries mygui and myutils
)
</syntaxhighlight>

Make sure that you list those libraries, static or shared, which are also used by other libraries in the list below these, e.g. if mygui uses myutils, first list mygui, then myutils, as in the example above.

{{warning|
The buildsystem up to KDE 4.1 supports the use of static libraries only for programs, not for shared libraries. So use this structuring method only for programs.

This restriction is due to the fact that the linker utilities on most platforms supported only import those parts of static libraries into the end product which are referenced by the other code in the product, not simply everything. Which is useful, if the product is a program. But it isn't useful for the product dynamic library. If a function "foo()" from the static library is not used by the other code in the shared library this function will not be found in resulting shared library product. Yet third party code linking to this shared library might expect the function if it is defined as exported. Which creates a problem.
}}

It is not uncommon for a static library to become a shared dynamic library later in development, if the code in the library proves to be complete and useful for others.

Development/Tutorials/Using Qt Creator

2011-06-30T11:53:56Z

Icwiener: /* Run cmake */ Fix syntax highlighting.

{{Template:I18n/Language Navigation Bar|Development/Tutorials/Using Qt Creator}}

QtCreator is an IDE from Nokia for Qt. It contains QtDesigner for UI design. This article describes:
* how to create a new program
* how to load an existing program

= Creating a new program =

Qt Designer is a graphical program which allows you to easily build user interfaces, using a ''drag n drop'' interface. Here is a short example how it can go, for more information read the [http://qt.nokia.com/doc/designer-manual.html user documentation].

;Step 0:
Call Qt Designer from within the [http://labs.trolltech.com/page/Projects/Tools/QtCreator QtCreator] [http://en.wikipedia.org/wiki/Integrated_development_environment IDE]:
<pre>
qtcreator
</pre>

;Step 1:
Add the widgets you want by drag-and-drop

[[File:Designer-step1.png|200px]]

;Step 2:
Select the mainwindow. This is the one un-intuitive step. To lay out the objects in the mainwindow, you do not select the objects in the mainwindow, but the mainwindow itself.

[[File:Designer-step2.png|200px]]

;Step 3:
Select Form -> Lay Out in a Grid

[[File:Designer-step3.png|200px]]

;Result:
You get a decent look, and if you resize the window, the widgets resize as well.

[[File:Designer-result.png|200px]]

== Using KDE libraries ==
To use KDE classes like KMessageBox, you need to tell qtcreator to use the KDE libraries when building. Go to your home directory, cd into ''yourproject'' and modify ''yourproject.pro''. Add a line
<pre>
LIBS += -lkdeui
</pre>
Then you can start using KDE classes in your code.

== Adding a toolbar ==
To add a toolbar, right-click on the UI and choose "Add Toolbar". Then you can set icons and text in your mainwindow's constructor with code like this:
<syntaxhighlight lang="cpp-qt">
ui->toolBar->addAction(QIcon("/usr/share/icons/oxygen/22x22/apps/ktip.png"),"hello world");
</syntaxhighlight>
[[Development/Tutorials/Using_Qt_Designer|More Info...]]

= Load an existing project =
This describes how to use QtCreator to integrate existing KDE 4 applications. It has been tested with QtCreator 1.2.80 and SUSE Linux 11.1 but should work same or similar with every combination. As an example KDE application we use [http://userbase.kde.org/ktimetracker ktimetracker] from the kdepim module, other applications should work analog.

You can either work with code on your disk or have QtCreator do the subversion checkout.

== use code from your disk ==
* Import the CMakeLists.txt file (File -> Open -> kdepim/CMakeLists.txt)
* As build directory choose kdepim.
* You will automatically come to a screen where you can run cmake
* Continue with the step "Run cmake"

== have QtCreator do the subversion checkout ==
* Choose File -> New File or Project -> Version Control -> Subversion Checkout.
* Enter a subversion URL like svn://anonsvn.kde.org/home/kde/trunk/KDE/kdepim
* Enter a checkout directory, so the local directory where the checkout will be loaded in
* Type finish, see how the checkout starts
* You will automatically come to a screen where you can run cmake
* Continue with the step "Run cmake"

== have QtCreator do the git checkout ==
* Choose File -> New File or Project -> Version Control -> Git Checkout.
* Enter a git URL like git@git.kde.org:/kdepim
* accept kdepim as checkout directory
* Type finish, see how the checkout starts
* You will automatically come to a screen where you can run cmake
* Continue with the step "Run cmake"

== Run cmake ==
* Enter arguments for cmake like
<syntaxhighlight lang="bash">
/root/kdepim -DCMAKE_INSTALL_PREFIX=/usr/local -DLIB_SUFFIX=64 -DCMAKE_BUILD_TYPE=debugfull
</syntaxhighlight>
<tt>DLIB_SUFFIX=64</tt> means that you want to install your libraries into directories named <tt>lib64</tt>, not <tt>lib</tt>. ''/root/kdepim'' is where your source code is.
* click "Run cmake"
* Note a .cbp file gets created containing many information about the build.
* click "Finish"

== Build it ==
* Configure qtcreator to build only ktimetracker:
Projects -> Active run configuration=ktimetracker -> build settings -> build steps -> make -> show details -> activate ktimetracker.
* Configure qtcreator to use 8 logical processors:
Projects -> Active run configuration=ktimetracker -> build settings -> build steps -> make -> show details -> addtional Arguments = -j8
* Choose Build -> Build All

= See also =
* [[Development/Tutorials/Using Qt Designer]]
* [[Getting_Started/Set_up_KDE_4_for_development#QtCreator]]

[[Category:KDE4]]

Development/Tutorials/Using Qt Designer

2011-06-30T11:53:11Z

Icwiener: Fix syntax highlighting.

{{Template:I18n/Language Navigation Bar|Development/Tutorials/Using Qt Designer}}

== Qt Designer User Interfaces in KDE ==

In this tutorial, we will explore how to programatically insert user interfaces
(UIs) created with Qt Designer, into your KDE project.

== Designing the UI ==

Qt Designer is a graphical program which allows you to easily build user interfaces, using a ''drag n drop'' interface. Here is a short example how it can go, for more information read the [http://qt.nokia.com/doc/designer-manual.html user documentation].

;Step 0:
Call Qt Designer
<syntaxhighlight lang="bash">
designer
</syntaxhighlight>
;Note:
You can also use Qt Designer from within the [http://labs.trolltech.com/page/Projects/Tools/QtCreator QtCreator] [http://en.wikipedia.org/wiki/Integrated_development_environment IDE] [[Getting_Started/Set_up_KDE_4_for_development#QtCreator|(here is how)]].
;Step 1:
Add the widgets you want by drag-and-drop

[[File:Designer-step1.png|200px]]
;Step 2:
Select the mainwindow. This is the one un-intuitive step. To lay out the objects in the mainwindow, you do not select the objects in the mainwindow, but the mainwindow itself.

[[File:Designer-step2.png|200px]]
;Step 3:
Select Form -> Lay Out in a Grid

[[File:Designer-step3.png|200px]]
;Result:
You get a decent look, and if you resize the window, the widgets resize as well.

[[File:Designer-result.png|200px]]

=== Adding a toolbar ===
To add a toolbar, right-click on the UI and choose "Add Toolbar". Then you can set icons and text in your mainwindow's constructor with code like this:
<syntaxhighlight lang="cpp-qt">
ui->toolBar->addAction(QIcon("/usr/share/icons/oxygen/22x22/apps/ktip.png"),"hello world");
</syntaxhighlight>

== Adding the UI File to Your KDE Project ==

For our purposes, the most important part of using Designer is the
<tt>*.ui</tt> file that it creates. This is simply an XML file that
encodes the user interface in a machine-readable (and human-readable!) way.

Let's imagine that you've created a UI named "MyDialog" with Designer, and
saved it as the file <tt>mydialog.ui</tt>. To add this UI to your KDE
project, simply add a command like the following to your CMakeLists.txt file:

<syntaxhighlight lang="cmake">
kde4_add_ui_files(myapp_SRCS mydialog.ui)
</syntaxhighlight>

Replace "<tt>myapp_SRCS</tt>" with the name of the main block in
your CMakeLists.txt file, defining all of the source code files. It is usually the
name of your application, with "<tt>_SRCS</tt>" appended.

When you do this, the build system will run the Qt program <tt>uic</tt>
on <tt>mydialog.ui</tt>, to auto-generate a C++ header file that
defines the UI. The generated file will be named <tt>ui_mydialog.h</tt>.

== Using the UI in Your Code ==

The <tt>ui_mydialog.h</tt> file defines a class named
"<tt>Ui_MyDialog</tt>", that contains all of the widgets you created in
Designer as public members of the class. It also contains the public function
"<tt>setupUi(QWidget *parent)</tt>", which instantiates all of the widgets,
sets up their properties, and inserts them into layout managers, all according
to what you specified in Designer.

Note that <tt>setupUi()</tt> takes a <tt>QWidget*</tt>
argument. This argument represents the parent container widget, into which
all of the widgets in your UI will be inserted. In other words,
'''<tt>Ui_MyDialog</tt> is not itself derived from QWidget''', and
'''it does not contain a toplevel widget itself'''. You have to supply the toplevel widget
when you call <tt>setupUi()</tt>. This is an important point.

One more important semantic detail: the <tt>Ui_MyDialog</tt> class
also creates a <tt>Ui</tt> namespace, which simply creates an alias
for the class. So you can use <tt>Ui::MyDialog</tt> to refer to the
same class.

Now, on to actually using the generated UI in your code. The Qt documentation
shows three ways of [http://qt.nokia.com/doc/latest/designer-using-a-ui-file.html how to use ui-files];
here only the ''direct approach'' is discussed. The goal is to create a KDialog
which embeds the UI from the ui-file. First, we have to subclass MyDialog from
KDialog and add a member variable of type Ui::MyDialog. The header file of
"<tt>mydialog.h</tt>" looks like the following:

<syntaxhighlight lang="cpp-qt">
#ifndef MYDIALOG_H
#define MYDIALOG_H

#include <KDialog>

// include the automatically generated header file for the ui-file
#include "ui_mydialog.h"

class MyDialog : public KDialog
{
Q_OBJECT
public:
MyDialog( QWidget *parent=0 );
~MyDialog();

private slots:
void slotButtonClicked();

private:
// accessor to the ui. we can access all gui elements
// specified in Designer. If mydialog.ui contains a
// button "myButton", we will be able to access it
// with ui.myButton in the cpp file.
Ui::MyDialog ui;
};

#endif
</syntaxhighlight>

Now we are going to look at the implementation of MyDialog, which is in the file
"<tt>mydialog.cpp</tt>".

<syntaxhighlight lang="cpp-qt">
#include <KLocale>
#include <KMessageBox>

// include the header file of the dialog
#include "mydialog.h"

MyDialog::MyDialog( QWidget *parent )
: KDialog( parent )
{
QWidget *widget = new QWidget( this );

// create the user interface, the parent widget is "widget"
ui.setupUi(widget); // this is the important part

// set the widget with all its gui elements as the dialog's
// main widget
setMainWidget( widget );

// other KDialog options
setCaption( i18n("This is my Dialog window!") );
setButtons( KDialog::Close );

// Example Signal/Slot connection using widgets in your UI.
// Note that you have to prepend "ui." when referring
// to your UI elements.
connect( ui.myButton, SIGNAL( clicked() ),
this, SLOT( slotButtonClicked() ) );
}

MyDialog::~MyDialog()
{
}

void MyDialog::slotButtonClicked()
{
KMessageBox::information( this,
i18n("You pressed the button!" ),
i18n( "Hooray!" ) );
}

#include "mydialog.moc"
</syntaxhighlight>

So, basically, we create a new Ui::MyDialog and then call
<tt>ui.setupUi(widget)</tt> in the constructor of <tt>MyDialog</tt>. This
places the UI elements into the given widget. Then we set the parent-widget
as the KDialog's main widget. We can then interact with all of the UI elements
by prepending "<tt>ui.</tt>" to their names, just like it is often done
with the prefix "<tt>m_</tt>".

== Final Thoughts ==

The cascade of files and classes in this tutorial may seem daunting at
first, but the naming scheme layed out here has one nice intuitive
feature: the source code files that you will be editing directly (either as
text or with Designer) are all named with the same scheme:
* '''mydialog.ui''': the user interface, created with Designer
* '''ui_mydialog.h''': auto-generated by uic, Qt's user interface compiler
* '''mydialog.h/cpp''': the dialog implementation
The steps in short are
# create <tt>mydialog.ui</tt>
# create <tt>mydialog.h/cpp</tt>
# add variable Ui::MyDialog ui; in <tt>mydialog.h</tt>
# call <tt>ui.setupUi(widget);</tt>
# access the ui elements with <tt>ui.</tt>

== Qt Documentation ==

The Qt documentation contains a good article about
[http://qt.nokia.com/doc/latest/designer-using-a-ui-file.html Using a Designer .ui File in Your Application].
[[Category:C++]]
[[Category:KDE4]]

Development/Tutorials/CMake

2011-06-30T11:49:42Z

Icwiener: /* Using CMake for a KDE Project */ Fix syntax highlighting.

{{Template:I18n/Language Navigation Bar|Development/Tutorials/CMake}}

== Introduction ==
[http://www.cmake.org CMake] reads script files and produces input files for the native buildsystem of the platform where it runs on. It can create GNU Makefiles, KDevelop project files, XCode project files, and Visual Studio project files.

[http://www.cmake.org CMake] is free software and released under a BSD license. It is developed by [http://www.kitware.com Kitware Inc.]

You can find more CMake related information on the [[Development/CMake | main CMake page]] here on TechBase.

== Why use CMake ? ==
CMake is the official tool of KDE 4 release, decided in March 2006, primarily due to technical merits as compared to the older KDE tools automake and unsermake:
* CMake is developed independently of KDE, it can be used by other projects as well
* Compilation time is much faster, mainly due to not using libtool anymore
* The build files are easier to write

== How to compile KDE using CMake==

=== Get and install CMake ===
==== Linux, BSD, and other Unix Systems ====
Retrieve the latest stable version of CMake from [http://www.cmake.org/HTML/Download.html here].

Once downloaded, unpack and compile it:
<syntaxhighlight lang="bash">
$ mkdir cmake-build
$ cd cmake-build
$ ../bootstrap
$ make
$ make install
</syntaxhighlight>

By default, this will install CMake in /usr/local, so make sure to have /usr/local/bin in your execute path. To change the installation prefix (e.g. to /usr in debian), add the '--prefix=PATH' option to the bootstrap command.

Please follow the instructions located [http://cmake.org/HTML/Download.html#cvs here] if you would like to use the current development version.

==== Windows ====
Retrieve the latest stable version of CMake from [http://www.cmake.org/HTML/Download.html here].

Once downloaded, run the cmake installer.

By default, this will install CMake in C:\Program Files\CMake 2.8, so make sure to have <installpath>\bin in your execute path.

Please follow the instructions at [http://cmake.org/HTML/Download.html#cvs here] if you would like to use the current development version.

=== Run CMake ===

==== Linux, BSD, and other Unix Systems ====
You have to run CMake so that it generates the build files for your system. Both in-source and out-of-source builds are supported by CMake, but currently in-source builds are prevented by the KDE implementation.

So, let's say you have kdelibs/ in ~/src/kdelibs/, then do the following:
<syntaxhighlight lang="bash">
$ ls
kdelibs/
$ mkdir kdelibs-build
$ cd kdelibs-build
$ cmake ../kdelibs
</syntaxhighlight>
This will generate the Makefiles for building kdelibs/ in kdelibs-build/.

==== Windows ====
You have to run CMake so that it generates the build files for your system. Both in-source and out-of-source builds are supported by CMake, but currently in-source builds are prevented by the KDE implementation.

So, let's say you have kdelibs\ in c:\daten\kde4, then do the following:
<syntaxhighlight lang="dos">
c:\daten\kde4> cd kdelibs\win
c:\daten\kde4> cmake
c:\daten\kde4> make
c:\daten\kde4> make install
c:\daten\kde4> cd ..
c:\daten\kde4> mkdir kdelibs-build
c:\daten\kde4> cd kdelibs-build
c:\daten\kde4\kdelibs-build> cmake ..\kdelibs
</syntaxhighlight>

This will generate the Makefiles for building kdelibs\ in kdelibs-build\. See [[Projects/KDE_on_Windows|KDE on Windows]] for more informations about compiling KDE on Windows.

==== KDevelop 3 Project Files ====
If you prefer project files for KDevelop 3 (which will basically be Makefiles accompanied by some extra files for KDevelop), run it like this:
<syntaxhighlight lang="bash">
$ cmake ../kdelibs -GKDevelop3
</syntaxhighlight>
Use 'cmake -h' to find out which generators CMake supports and the other options.

==== CMake and Qt4 ====
To locate Qt 4, CMake searches for qmake in your execute path. CMake does ''not'' use the QTDIR environment variable. So make sure that the first qmake found in the execution path is the one you like to use.

==== More Details ====
When CMake has finished, it will have created a file called "CMakeCache.txt". This file contains all the settings CMake has detected on your system. If you want to run CMake with another generator or you want CMake to detect everything again, delete this file.

If CMake didn't find something, but you know it is somewere on your box, you can tell CMake manually where to find it. CMake uses variables to store this information. These variables are cached in the already mentioned file CMakeCache.txt. You have three options to adjust these variables manually:
* tell CMake the correct value via the command line: cmake ../kdelibs -DNAME_OF_THE_VARIABLE=value
* use ccmake, which provides a curses based GUI to adjust the CMake variables (run: ccmake ../kdelibs)
* edit the file CMakeCache.txt directly (not recommended)

You should run "ccmake ../kdelibs" at least once so that you get an impression which variables CMake uses. Press "T" to see also the "advanced" variables. So, if CMake didn't find something, start ccmake and adjust it manually.

==== Command Line Variables ====

Some cmake command line variables you may want to set:
* '''CMAKE_INSTALL_PREFIX''': cmake ../kdelibs -DCMAKE_INSTALL_PREFIX=/opt/kde4 is the equivalent to ./configure --prefix=/opt/kde4
* '''[[Development/CMake/Addons_for_KDE#Buildtypes|CMAKE_BUILD_TYPE]]''': decide which type of build you want. You can choose between "DebugFull", "Debug", "Profile", "RelWithDebInfo" and "Release". The default is "RelWithDebInfo". Please refer to page [[Development/CMake/Addons_for_KDE#Buildtypes|CMake Build Types]] for a more detailed explanation.
* '''KDE4_BUILD_TESTS=ON''': creates Makefiles with build test programs and also provides 'test' targets
* '''KDE4_TEST_OUTPUT=xml''': Unit tests using the QTestLib framework will create xml formatted logfiles.
* '''KDE4_DISABLE_MULTIMEDIA=ON''': Build KDE without any multimedia (audio and video) support.
* '''BUILD_foo=OFF''': disables the build for the project in subdirectory 'foo'.
* '''WITH_foo''': there are several options, e.g. WITH_CUPS or WITH_Jasper. If you disable them, cmake will not even try to find this package. If it is enabled, cmake will try to find it. If it fails with this, you can still adjust it manually as described above.

=== Environment Variables ===
If you have headers and libraries installed in non-standard locations that cmake cannot find (e.g., fink on Mac OSX installs to /sw), then populate the environment variable CMAKE_PREFIX_PATH with a list of paths to these locations. When searching for headers, libraries and binaries, CMake will search all the paths in CMAKE_PREFIX_PATH as well as their standard subdirectories ("lib" for libraries, "include" for headers and "bin" for binaries). This can be also very useful e.g. if you install kdesupport to ~/install/kdesupport.
* '''CMAKE_PREFIX_PATH''', eg. export CMAKE_PREFIX_PATH=/sw

If you need to further tweak the search behavior, you can additionally set the
following environment variables in order to add library, include or binary
directories to your search path:
* '''CMAKE_INCLUDE_PATH''', eg. export CMAKE_PREFIX_PATH=/sw/include
* '''CMAKE_LIBRARY_PATH''', eg. export CMAKE_LIBRARY_PATH=/sw/lib
* '''CMAKE_PROGRAM_PATH''', eg. export CMAKE_PROGRAM_PATH=/sw/bin

For more information on variables, see [http://www.cmake.org/Wiki/CMake_Useful_Variables this cmake.org wiki page]

=== Going Further ===
If cmake finishes with "Generating done" then there was no errors, but if it finishes with "Configuring done" then there was errors that you have to fix. Once cmake finishes successfully, run your buildtool (i.e. make, KDevelop, XCode or MSVC) and build and wait until it has finished. Then "make install".

If you got a failure that says something like
<pre>
CMake Error: This project requires some variables to be set,
and cmake can not find them.
Please set the following variables:
X11_XTest_LIB (ADVANCED)
</pre>
then you may have a missing library (or other dependency). To find
out which library, search in the cmake/modules directory for
the variable that cmake can't find. In the example above, it is
<syntaxhighlight lang="cmake">
find_library(X11_XTest_LIB Xtst ${X11_LIB_SEARCH_PATH})
</syntaxhighlight>
So the missing library is Xtst. You then need to find it (perhaps installing a libXtst-devel library) and re-run cmake.

== Using CMake for a Simple Application ==

Here's the most simple CMakeLists.txt:
<syntaxhighlight lang="cmake">
add_executable(hello main.cpp)
</syntaxhighlight>
This will create an executable named "hello" (or "hello.exe" under Windows) from the source file main.cpp. You can mix C and C++ files as you want. You can have multiple executables and libraries in one CMakeLists.txt. The same source file can be used in multiple targets, it will be compiled for each target independently from the other targets. Probably the most important part of the cmake language are the variables:
<syntaxhighlight lang="cmake">
set( MY_SOURCES main.cpp widget.cpp)
message(STATUS "my sources: ${MY_SOURCES}")
</syntaxhighlight>
So, use the SET() command to set the value of a variable. If you list more than one string, the variable will be a list. A list is a list of strings separated by semicolons. If you set it to only one item, it will have just that value. To get the value of a variable, use ${VAR}.
You can iterate over a list using FOREACH():
<syntaxhighlight lang="cmake">
foreach(next_ITEM ${MY_SOURCES})
message(STATUS "next item: ${next_ITEM}")
endforeach(next_ITEM ${MY_SOURCES})
</syntaxhighlight>
The commands in CMake are case-insensitive. Names of variables and names of parameter are case-sensitive.

You can also test for various things:
<syntaxhighlight lang="cmake">
if (UNIX)
message(STATUS "This is UNIX (including OS X and CygWin)")
endif (UNIX)

if (MSVC)
set(MY_SRCS ${MY_SRCS} winextra.cpp)
endif (MSVC)
</syntaxhighlight>
In this second example you can see also how to append items to a list.

In the cmake Wiki there is also a [http://www.cmake.org/Wiki/HowToBuildKDE4Software tutorial] on using cmake to build KDE 4 software. It is recommended reading.

== Using CMake for a KDE Project ==

Here's a basic CMakeList file that builds a small KDE 4 project:
<syntaxhighlight lang="cmake">
project( kde4project )
find_package( KDE4 REQUIRED )
include(KDE4Defaults)

include_directories( ${KDE4_INCLUDES} )

set( KDE4ProjectSources kde4mainapp.cpp someclass.cpp someotherclass.cpp )

kde4_add_executable( kde4project ${KDE4ProjectSources} )

target_link_libraries( kde4project ${KDE4_KDEUI_LIBS} ${KDE4_KPARTS_LIBS} )

install( TARGETS kde4project ${INSTALL_TARGETS_DEFAULT_ARGS} )
</syntaxhighlight>

''target_link_libraries'' contains the development libraries that are linked to your program. E.g. if you want to link to libtidy-devel, your library file name may be called /usr/local/lib/libtidy.a. You would then add -ltidy to a gcc call. Here, you add ''tidy'' to your target_link_libraries. If possible, use pre-defined variables or macros like ${KDE4_KDEUI_LIBS}.

''install (TARGETS'' is where the target will finally be installed. If you do not have this line, make install will not be available.

Variables, macros and other useful information specific to KDE can be found at the [[Development/CMake/Addons for KDE|CMake addons for KDE]] page.

== Extending CMake ==
CMake can be extended using cmake scripts. CMake comes with a number of scripts; under UNIX they are by default installed to /usr/local/share/CMake/Modules/. The KDE libraries install also a set of cmake modules into share/apps/cmake/modules/. The files located there will be preferred over the ones in the system global cmake module path.
For detecting software packages there are FindFOO.cmake files, see [http://www.cmake.org/Wiki/CMake_HowToFindInstalledSoftware here] for more information.
You can also write macros in CMake. They are powerful enough to do most things you will need to build software, but they are not intended to be used as a general purpose programming language.

== Converting autotools-based KDE software to CMake ==
In kdesdk/cmake/ you can find a script am2cmake . This is a ruby script, so you need to have ruby installed. Run am2cmake in the toplevel directory of your sources:
<syntaxhighlight lang="bash">
$ cd src/mykooltool/
$ am2cmake --kde4
</syntaxhighlight>
Don't forget the switch <tt>--kde4</tt>, otherwise it won't generate files suitable for KDE 4 software. The converted files 'may' work as they are, but complicated projects will require some additional editing.

You may have to:
* add more include direcories, using INCLUDE_DIRECTORIES()
* add more link libraries, using TARGET_LINK_LIBRARIES()
* add some compile switches, using ADD_DEFINITIONS()
* add some "configure" checks, see [http://www.cmake.org/Wiki/CMake_HowToDoPlatformChecks How To Do Platform Checks] and [http://www.cmake.org/Wiki/CMake_HowToFindInstalledSoftware How To Find Installed Software]
* take special care of former libtool convenience libraries. They are not supported by cmake, instead there will be a file ConvenienceLibs.cmake created. In this file you will find for every convenience lib a variable, which contains all source files of this convenience lib. For the targets which linked to this convenience lib, just add the variable to the sources.
* a file AdditionalInfo.txt will be created. There you will see all *.in and *.in.in files of your project. The stuff done in these files will have to be converted manually to cmake.

[[Category:Programming]]
[[Category:Tutorial]]
[[Category:FAQs]]

Development/Tutorials/CMake

2011-06-30T11:49:12Z

Icwiener: /* Using CMake for a Simple Application */ Fix syntax highlighting.

{{Template:I18n/Language Navigation Bar|Development/Tutorials/CMake}}

== Introduction ==
[http://www.cmake.org CMake] reads script files and produces input files for the native buildsystem of the platform where it runs on. It can create GNU Makefiles, KDevelop project files, XCode project files, and Visual Studio project files.

[http://www.cmake.org CMake] is free software and released under a BSD license. It is developed by [http://www.kitware.com Kitware Inc.]

You can find more CMake related information on the [[Development/CMake | main CMake page]] here on TechBase.

== Why use CMake ? ==
CMake is the official tool of KDE 4 release, decided in March 2006, primarily due to technical merits as compared to the older KDE tools automake and unsermake:
* CMake is developed independently of KDE, it can be used by other projects as well
* Compilation time is much faster, mainly due to not using libtool anymore
* The build files are easier to write

== How to compile KDE using CMake==

=== Get and install CMake ===
==== Linux, BSD, and other Unix Systems ====
Retrieve the latest stable version of CMake from [http://www.cmake.org/HTML/Download.html here].

Once downloaded, unpack and compile it:
<syntaxhighlight lang="bash">
$ mkdir cmake-build
$ cd cmake-build
$ ../bootstrap
$ make
$ make install
</syntaxhighlight>

By default, this will install CMake in /usr/local, so make sure to have /usr/local/bin in your execute path. To change the installation prefix (e.g. to /usr in debian), add the '--prefix=PATH' option to the bootstrap command.

Please follow the instructions located [http://cmake.org/HTML/Download.html#cvs here] if you would like to use the current development version.

==== Windows ====
Retrieve the latest stable version of CMake from [http://www.cmake.org/HTML/Download.html here].

Once downloaded, run the cmake installer.

By default, this will install CMake in C:\Program Files\CMake 2.8, so make sure to have <installpath>\bin in your execute path.

Please follow the instructions at [http://cmake.org/HTML/Download.html#cvs here] if you would like to use the current development version.

=== Run CMake ===

==== Linux, BSD, and other Unix Systems ====
You have to run CMake so that it generates the build files for your system. Both in-source and out-of-source builds are supported by CMake, but currently in-source builds are prevented by the KDE implementation.

So, let's say you have kdelibs/ in ~/src/kdelibs/, then do the following:
<syntaxhighlight lang="bash">
$ ls
kdelibs/
$ mkdir kdelibs-build
$ cd kdelibs-build
$ cmake ../kdelibs
</syntaxhighlight>
This will generate the Makefiles for building kdelibs/ in kdelibs-build/.

==== Windows ====
You have to run CMake so that it generates the build files for your system. Both in-source and out-of-source builds are supported by CMake, but currently in-source builds are prevented by the KDE implementation.

So, let's say you have kdelibs\ in c:\daten\kde4, then do the following:
<syntaxhighlight lang="dos">
c:\daten\kde4> cd kdelibs\win
c:\daten\kde4> cmake
c:\daten\kde4> make
c:\daten\kde4> make install
c:\daten\kde4> cd ..
c:\daten\kde4> mkdir kdelibs-build
c:\daten\kde4> cd kdelibs-build
c:\daten\kde4\kdelibs-build> cmake ..\kdelibs
</syntaxhighlight>

This will generate the Makefiles for building kdelibs\ in kdelibs-build\. See [[Projects/KDE_on_Windows|KDE on Windows]] for more informations about compiling KDE on Windows.

==== KDevelop 3 Project Files ====
If you prefer project files for KDevelop 3 (which will basically be Makefiles accompanied by some extra files for KDevelop), run it like this:
<syntaxhighlight lang="bash">
$ cmake ../kdelibs -GKDevelop3
</syntaxhighlight>
Use 'cmake -h' to find out which generators CMake supports and the other options.

==== CMake and Qt4 ====
To locate Qt 4, CMake searches for qmake in your execute path. CMake does ''not'' use the QTDIR environment variable. So make sure that the first qmake found in the execution path is the one you like to use.

==== More Details ====
When CMake has finished, it will have created a file called "CMakeCache.txt". This file contains all the settings CMake has detected on your system. If you want to run CMake with another generator or you want CMake to detect everything again, delete this file.

If CMake didn't find something, but you know it is somewere on your box, you can tell CMake manually where to find it. CMake uses variables to store this information. These variables are cached in the already mentioned file CMakeCache.txt. You have three options to adjust these variables manually:
* tell CMake the correct value via the command line: cmake ../kdelibs -DNAME_OF_THE_VARIABLE=value
* use ccmake, which provides a curses based GUI to adjust the CMake variables (run: ccmake ../kdelibs)
* edit the file CMakeCache.txt directly (not recommended)

You should run "ccmake ../kdelibs" at least once so that you get an impression which variables CMake uses. Press "T" to see also the "advanced" variables. So, if CMake didn't find something, start ccmake and adjust it manually.

==== Command Line Variables ====

Some cmake command line variables you may want to set:
* '''CMAKE_INSTALL_PREFIX''': cmake ../kdelibs -DCMAKE_INSTALL_PREFIX=/opt/kde4 is the equivalent to ./configure --prefix=/opt/kde4
* '''[[Development/CMake/Addons_for_KDE#Buildtypes|CMAKE_BUILD_TYPE]]''': decide which type of build you want. You can choose between "DebugFull", "Debug", "Profile", "RelWithDebInfo" and "Release". The default is "RelWithDebInfo". Please refer to page [[Development/CMake/Addons_for_KDE#Buildtypes|CMake Build Types]] for a more detailed explanation.
* '''KDE4_BUILD_TESTS=ON''': creates Makefiles with build test programs and also provides 'test' targets
* '''KDE4_TEST_OUTPUT=xml''': Unit tests using the QTestLib framework will create xml formatted logfiles.
* '''KDE4_DISABLE_MULTIMEDIA=ON''': Build KDE without any multimedia (audio and video) support.
* '''BUILD_foo=OFF''': disables the build for the project in subdirectory 'foo'.
* '''WITH_foo''': there are several options, e.g. WITH_CUPS or WITH_Jasper. If you disable them, cmake will not even try to find this package. If it is enabled, cmake will try to find it. If it fails with this, you can still adjust it manually as described above.

=== Environment Variables ===
If you have headers and libraries installed in non-standard locations that cmake cannot find (e.g., fink on Mac OSX installs to /sw), then populate the environment variable CMAKE_PREFIX_PATH with a list of paths to these locations. When searching for headers, libraries and binaries, CMake will search all the paths in CMAKE_PREFIX_PATH as well as their standard subdirectories ("lib" for libraries, "include" for headers and "bin" for binaries). This can be also very useful e.g. if you install kdesupport to ~/install/kdesupport.
* '''CMAKE_PREFIX_PATH''', eg. export CMAKE_PREFIX_PATH=/sw

If you need to further tweak the search behavior, you can additionally set the
following environment variables in order to add library, include or binary
directories to your search path:
* '''CMAKE_INCLUDE_PATH''', eg. export CMAKE_PREFIX_PATH=/sw/include
* '''CMAKE_LIBRARY_PATH''', eg. export CMAKE_LIBRARY_PATH=/sw/lib
* '''CMAKE_PROGRAM_PATH''', eg. export CMAKE_PROGRAM_PATH=/sw/bin

For more information on variables, see [http://www.cmake.org/Wiki/CMake_Useful_Variables this cmake.org wiki page]

=== Going Further ===
If cmake finishes with "Generating done" then there was no errors, but if it finishes with "Configuring done" then there was errors that you have to fix. Once cmake finishes successfully, run your buildtool (i.e. make, KDevelop, XCode or MSVC) and build and wait until it has finished. Then "make install".

If you got a failure that says something like
<pre>
CMake Error: This project requires some variables to be set,
and cmake can not find them.
Please set the following variables:
X11_XTest_LIB (ADVANCED)
</pre>
then you may have a missing library (or other dependency). To find
out which library, search in the cmake/modules directory for
the variable that cmake can't find. In the example above, it is
<syntaxhighlight lang="cmake">
find_library(X11_XTest_LIB Xtst ${X11_LIB_SEARCH_PATH})
</syntaxhighlight>
So the missing library is Xtst. You then need to find it (perhaps installing a libXtst-devel library) and re-run cmake.

== Using CMake for a Simple Application ==

Here's the most simple CMakeLists.txt:
<syntaxhighlight lang="cmake">
add_executable(hello main.cpp)
</syntaxhighlight>
This will create an executable named "hello" (or "hello.exe" under Windows) from the source file main.cpp. You can mix C and C++ files as you want. You can have multiple executables and libraries in one CMakeLists.txt. The same source file can be used in multiple targets, it will be compiled for each target independently from the other targets. Probably the most important part of the cmake language are the variables:
<syntaxhighlight lang="cmake">
set( MY_SOURCES main.cpp widget.cpp)
message(STATUS "my sources: ${MY_SOURCES}")
</syntaxhighlight>
So, use the SET() command to set the value of a variable. If you list more than one string, the variable will be a list. A list is a list of strings separated by semicolons. If you set it to only one item, it will have just that value. To get the value of a variable, use ${VAR}.
You can iterate over a list using FOREACH():
<syntaxhighlight lang="cmake">
foreach(next_ITEM ${MY_SOURCES})
message(STATUS "next item: ${next_ITEM}")
endforeach(next_ITEM ${MY_SOURCES})
</syntaxhighlight>
The commands in CMake are case-insensitive. Names of variables and names of parameter are case-sensitive.

You can also test for various things:
<syntaxhighlight lang="cmake">
if (UNIX)
message(STATUS "This is UNIX (including OS X and CygWin)")
endif (UNIX)

if (MSVC)
set(MY_SRCS ${MY_SRCS} winextra.cpp)
endif (MSVC)
</syntaxhighlight>
In this second example you can see also how to append items to a list.

In the cmake Wiki there is also a [http://www.cmake.org/Wiki/HowToBuildKDE4Software tutorial] on using cmake to build KDE 4 software. It is recommended reading.

== Using CMake for a KDE Project ==

Here's a basic CMakeList file that builds a small KDE 4 project:
<pre>
project( kde4project )
find_package( KDE4 REQUIRED )
include(KDE4Defaults)

include_directories( ${KDE4_INCLUDES} )

set( KDE4ProjectSources kde4mainapp.cpp someclass.cpp someotherclass.cpp )

kde4_add_executable( kde4project ${KDE4ProjectSources} )

target_link_libraries( kde4project ${KDE4_KDEUI_LIBS} ${KDE4_KPARTS_LIBS} )

install( TARGETS kde4project ${INSTALL_TARGETS_DEFAULT_ARGS} )
</pre>

''target_link_libraries'' contains the development libraries that are linked to your program. E.g. if you want to link to libtidy-devel, your library file name may be called /usr/local/lib/libtidy.a. You would then add -ltidy to a gcc call. Here, you add ''tidy'' to your target_link_libraries. If possible, use pre-defined variables or macros like ${KDE4_KDEUI_LIBS}.

''install (TARGETS'' is where the target will finally be installed. If you do not have this line, make install will not be available.

Variables, macros and other useful information specific to KDE can be found at the [[Development/CMake/Addons for KDE|CMake addons for KDE]] page.

== Extending CMake ==
CMake can be extended using cmake scripts. CMake comes with a number of scripts; under UNIX they are by default installed to /usr/local/share/CMake/Modules/. The KDE libraries install also a set of cmake modules into share/apps/cmake/modules/. The files located there will be preferred over the ones in the system global cmake module path.
For detecting software packages there are FindFOO.cmake files, see [http://www.cmake.org/Wiki/CMake_HowToFindInstalledSoftware here] for more information.
You can also write macros in CMake. They are powerful enough to do most things you will need to build software, but they are not intended to be used as a general purpose programming language.

== Converting autotools-based KDE software to CMake ==
In kdesdk/cmake/ you can find a script am2cmake . This is a ruby script, so you need to have ruby installed. Run am2cmake in the toplevel directory of your sources:
<syntaxhighlight lang="bash">
$ cd src/mykooltool/
$ am2cmake --kde4
</syntaxhighlight>
Don't forget the switch <tt>--kde4</tt>, otherwise it won't generate files suitable for KDE 4 software. The converted files 'may' work as they are, but complicated projects will require some additional editing.

You may have to:
* add more include direcories, using INCLUDE_DIRECTORIES()
* add more link libraries, using TARGET_LINK_LIBRARIES()
* add some compile switches, using ADD_DEFINITIONS()
* add some "configure" checks, see [http://www.cmake.org/Wiki/CMake_HowToDoPlatformChecks How To Do Platform Checks] and [http://www.cmake.org/Wiki/CMake_HowToFindInstalledSoftware How To Find Installed Software]
* take special care of former libtool convenience libraries. They are not supported by cmake, instead there will be a file ConvenienceLibs.cmake created. In this file you will find for every convenience lib a variable, which contains all source files of this convenience lib. For the targets which linked to this convenience lib, just add the variable to the sources.
* a file AdditionalInfo.txt will be created. There you will see all *.in and *.in.in files of your project. The stuff done in these files will have to be converted manually to cmake.

[[Category:Programming]]
[[Category:Tutorial]]
[[Category:FAQs]]

Development/Tutorials/CMake

2011-06-30T11:48:19Z

Icwiener: /* Going Further */ Fix syntax highlighting.

{{Template:I18n/Language Navigation Bar|Development/Tutorials/CMake}}

== Introduction ==
[http://www.cmake.org CMake] reads script files and produces input files for the native buildsystem of the platform where it runs on. It can create GNU Makefiles, KDevelop project files, XCode project files, and Visual Studio project files.

[http://www.cmake.org CMake] is free software and released under a BSD license. It is developed by [http://www.kitware.com Kitware Inc.]

You can find more CMake related information on the [[Development/CMake | main CMake page]] here on TechBase.

== Why use CMake ? ==
CMake is the official tool of KDE 4 release, decided in March 2006, primarily due to technical merits as compared to the older KDE tools automake and unsermake:
* CMake is developed independently of KDE, it can be used by other projects as well
* Compilation time is much faster, mainly due to not using libtool anymore
* The build files are easier to write

== How to compile KDE using CMake==

=== Get and install CMake ===
==== Linux, BSD, and other Unix Systems ====
Retrieve the latest stable version of CMake from [http://www.cmake.org/HTML/Download.html here].

Once downloaded, unpack and compile it:
<syntaxhighlight lang="bash">
$ mkdir cmake-build
$ cd cmake-build
$ ../bootstrap
$ make
$ make install
</syntaxhighlight>

By default, this will install CMake in /usr/local, so make sure to have /usr/local/bin in your execute path. To change the installation prefix (e.g. to /usr in debian), add the '--prefix=PATH' option to the bootstrap command.

Please follow the instructions located [http://cmake.org/HTML/Download.html#cvs here] if you would like to use the current development version.

==== Windows ====
Retrieve the latest stable version of CMake from [http://www.cmake.org/HTML/Download.html here].

Once downloaded, run the cmake installer.

By default, this will install CMake in C:\Program Files\CMake 2.8, so make sure to have <installpath>\bin in your execute path.

Please follow the instructions at [http://cmake.org/HTML/Download.html#cvs here] if you would like to use the current development version.

=== Run CMake ===

==== Linux, BSD, and other Unix Systems ====
You have to run CMake so that it generates the build files for your system. Both in-source and out-of-source builds are supported by CMake, but currently in-source builds are prevented by the KDE implementation.

So, let's say you have kdelibs/ in ~/src/kdelibs/, then do the following:
<syntaxhighlight lang="bash">
$ ls
kdelibs/
$ mkdir kdelibs-build
$ cd kdelibs-build
$ cmake ../kdelibs
</syntaxhighlight>
This will generate the Makefiles for building kdelibs/ in kdelibs-build/.

==== Windows ====
You have to run CMake so that it generates the build files for your system. Both in-source and out-of-source builds are supported by CMake, but currently in-source builds are prevented by the KDE implementation.

So, let's say you have kdelibs\ in c:\daten\kde4, then do the following:
<syntaxhighlight lang="dos">
c:\daten\kde4> cd kdelibs\win
c:\daten\kde4> cmake
c:\daten\kde4> make
c:\daten\kde4> make install
c:\daten\kde4> cd ..
c:\daten\kde4> mkdir kdelibs-build
c:\daten\kde4> cd kdelibs-build
c:\daten\kde4\kdelibs-build> cmake ..\kdelibs
</syntaxhighlight>

This will generate the Makefiles for building kdelibs\ in kdelibs-build\. See [[Projects/KDE_on_Windows|KDE on Windows]] for more informations about compiling KDE on Windows.

==== KDevelop 3 Project Files ====
If you prefer project files for KDevelop 3 (which will basically be Makefiles accompanied by some extra files for KDevelop), run it like this:
<syntaxhighlight lang="bash">
$ cmake ../kdelibs -GKDevelop3
</syntaxhighlight>
Use 'cmake -h' to find out which generators CMake supports and the other options.

==== CMake and Qt4 ====
To locate Qt 4, CMake searches for qmake in your execute path. CMake does ''not'' use the QTDIR environment variable. So make sure that the first qmake found in the execution path is the one you like to use.

==== More Details ====
When CMake has finished, it will have created a file called "CMakeCache.txt". This file contains all the settings CMake has detected on your system. If you want to run CMake with another generator or you want CMake to detect everything again, delete this file.

If CMake didn't find something, but you know it is somewere on your box, you can tell CMake manually where to find it. CMake uses variables to store this information. These variables are cached in the already mentioned file CMakeCache.txt. You have three options to adjust these variables manually:
* tell CMake the correct value via the command line: cmake ../kdelibs -DNAME_OF_THE_VARIABLE=value
* use ccmake, which provides a curses based GUI to adjust the CMake variables (run: ccmake ../kdelibs)
* edit the file CMakeCache.txt directly (not recommended)

You should run "ccmake ../kdelibs" at least once so that you get an impression which variables CMake uses. Press "T" to see also the "advanced" variables. So, if CMake didn't find something, start ccmake and adjust it manually.

==== Command Line Variables ====

Some cmake command line variables you may want to set:
* '''CMAKE_INSTALL_PREFIX''': cmake ../kdelibs -DCMAKE_INSTALL_PREFIX=/opt/kde4 is the equivalent to ./configure --prefix=/opt/kde4
* '''[[Development/CMake/Addons_for_KDE#Buildtypes|CMAKE_BUILD_TYPE]]''': decide which type of build you want. You can choose between "DebugFull", "Debug", "Profile", "RelWithDebInfo" and "Release". The default is "RelWithDebInfo". Please refer to page [[Development/CMake/Addons_for_KDE#Buildtypes|CMake Build Types]] for a more detailed explanation.
* '''KDE4_BUILD_TESTS=ON''': creates Makefiles with build test programs and also provides 'test' targets
* '''KDE4_TEST_OUTPUT=xml''': Unit tests using the QTestLib framework will create xml formatted logfiles.
* '''KDE4_DISABLE_MULTIMEDIA=ON''': Build KDE without any multimedia (audio and video) support.
* '''BUILD_foo=OFF''': disables the build for the project in subdirectory 'foo'.
* '''WITH_foo''': there are several options, e.g. WITH_CUPS or WITH_Jasper. If you disable them, cmake will not even try to find this package. If it is enabled, cmake will try to find it. If it fails with this, you can still adjust it manually as described above.

=== Environment Variables ===
If you have headers and libraries installed in non-standard locations that cmake cannot find (e.g., fink on Mac OSX installs to /sw), then populate the environment variable CMAKE_PREFIX_PATH with a list of paths to these locations. When searching for headers, libraries and binaries, CMake will search all the paths in CMAKE_PREFIX_PATH as well as their standard subdirectories ("lib" for libraries, "include" for headers and "bin" for binaries). This can be also very useful e.g. if you install kdesupport to ~/install/kdesupport.
* '''CMAKE_PREFIX_PATH''', eg. export CMAKE_PREFIX_PATH=/sw

If you need to further tweak the search behavior, you can additionally set the
following environment variables in order to add library, include or binary
directories to your search path:
* '''CMAKE_INCLUDE_PATH''', eg. export CMAKE_PREFIX_PATH=/sw/include
* '''CMAKE_LIBRARY_PATH''', eg. export CMAKE_LIBRARY_PATH=/sw/lib
* '''CMAKE_PROGRAM_PATH''', eg. export CMAKE_PROGRAM_PATH=/sw/bin

For more information on variables, see [http://www.cmake.org/Wiki/CMake_Useful_Variables this cmake.org wiki page]

=== Going Further ===
If cmake finishes with "Generating done" then there was no errors, but if it finishes with "Configuring done" then there was errors that you have to fix. Once cmake finishes successfully, run your buildtool (i.e. make, KDevelop, XCode or MSVC) and build and wait until it has finished. Then "make install".

If you got a failure that says something like
<pre>
CMake Error: This project requires some variables to be set,
and cmake can not find them.
Please set the following variables:
X11_XTest_LIB (ADVANCED)
</pre>
then you may have a missing library (or other dependency). To find
out which library, search in the cmake/modules directory for
the variable that cmake can't find. In the example above, it is
<syntaxhighlight lang="cmake">
find_library(X11_XTest_LIB Xtst ${X11_LIB_SEARCH_PATH})
</syntaxhighlight>
So the missing library is Xtst. You then need to find it (perhaps installing a libXtst-devel library) and re-run cmake.

== Using CMake for a Simple Application ==

Here's the most simple CMakeLists.txt:
<pre>
add_executable(hello main.cpp)
</pre>
This will create an executable named "hello" (or "hello.exe" under Windows) from the source file main.cpp. You can mix C and C++ files as you want. You can have multiple executables and libraries in one CMakeLists.txt. The same source file can be used in multiple targets, it will be compiled for each target independently from the other targets. Probably the most important part of the cmake language are the variables:
<pre>
set( MY_SOURCES main.cpp widget.cpp)
message(STATUS "my sources: ${MY_SOURCES}")
</pre>
So, use the SET() command to set the value of a variable. If you list more than one string, the variable will be a list. A list is a list of strings separated by semicolons. If you set it to only one item, it will have just that value. To get the value of a variable, use ${VAR}.
You can iterate over a list using FOREACH():
<pre>
foreach(next_ITEM ${MY_SOURCES})
message(STATUS "next item: ${next_ITEM}")
endforeach(next_ITEM ${MY_SOURCES})
</pre>
The commands in CMake are case-insensitive. Names of variables and names of parameter are case-sensitive.

You can also test for various things:
<pre>
if (UNIX)
message(STATUS "This is UNIX (including OS X and CygWin)")
endif (UNIX)

if (MSVC)
set(MY_SRCS ${MY_SRCS} winextra.cpp)
endif (MSVC)
</pre>
In this second example you can see also how to append items to a list.

In the cmake Wiki there is also a [http://www.cmake.org/Wiki/HowToBuildKDE4Software tutorial] on using cmake to build KDE 4 software. It is recommended reading.

== Using CMake for a KDE Project ==

Here's a basic CMakeList file that builds a small KDE 4 project:
<pre>
project( kde4project )
find_package( KDE4 REQUIRED )
include(KDE4Defaults)

include_directories( ${KDE4_INCLUDES} )

set( KDE4ProjectSources kde4mainapp.cpp someclass.cpp someotherclass.cpp )

kde4_add_executable( kde4project ${KDE4ProjectSources} )

target_link_libraries( kde4project ${KDE4_KDEUI_LIBS} ${KDE4_KPARTS_LIBS} )

install( TARGETS kde4project ${INSTALL_TARGETS_DEFAULT_ARGS} )
</pre>

''target_link_libraries'' contains the development libraries that are linked to your program. E.g. if you want to link to libtidy-devel, your library file name may be called /usr/local/lib/libtidy.a. You would then add -ltidy to a gcc call. Here, you add ''tidy'' to your target_link_libraries. If possible, use pre-defined variables or macros like ${KDE4_KDEUI_LIBS}.

''install (TARGETS'' is where the target will finally be installed. If you do not have this line, make install will not be available.

Variables, macros and other useful information specific to KDE can be found at the [[Development/CMake/Addons for KDE|CMake addons for KDE]] page.

== Extending CMake ==
CMake can be extended using cmake scripts. CMake comes with a number of scripts; under UNIX they are by default installed to /usr/local/share/CMake/Modules/. The KDE libraries install also a set of cmake modules into share/apps/cmake/modules/. The files located there will be preferred over the ones in the system global cmake module path.
For detecting software packages there are FindFOO.cmake files, see [http://www.cmake.org/Wiki/CMake_HowToFindInstalledSoftware here] for more information.
You can also write macros in CMake. They are powerful enough to do most things you will need to build software, but they are not intended to be used as a general purpose programming language.

== Converting autotools-based KDE software to CMake ==
In kdesdk/cmake/ you can find a script am2cmake . This is a ruby script, so you need to have ruby installed. Run am2cmake in the toplevel directory of your sources:
<syntaxhighlight lang="bash">
$ cd src/mykooltool/
$ am2cmake --kde4
</syntaxhighlight>
Don't forget the switch <tt>--kde4</tt>, otherwise it won't generate files suitable for KDE 4 software. The converted files 'may' work as they are, but complicated projects will require some additional editing.

You may have to:
* add more include direcories, using INCLUDE_DIRECTORIES()
* add more link libraries, using TARGET_LINK_LIBRARIES()
* add some compile switches, using ADD_DEFINITIONS()
* add some "configure" checks, see [http://www.cmake.org/Wiki/CMake_HowToDoPlatformChecks How To Do Platform Checks] and [http://www.cmake.org/Wiki/CMake_HowToFindInstalledSoftware How To Find Installed Software]
* take special care of former libtool convenience libraries. They are not supported by cmake, instead there will be a file ConvenienceLibs.cmake created. In this file you will find for every convenience lib a variable, which contains all source files of this convenience lib. For the targets which linked to this convenience lib, just add the variable to the sources.
* a file AdditionalInfo.txt will be created. There you will see all *.in and *.in.in files of your project. The stuff done in these files will have to be converted manually to cmake.

[[Category:Programming]]
[[Category:Tutorial]]
[[Category:FAQs]]

Development/Tutorials/KCmdLineArgs

2011-06-30T11:47:05Z

Icwiener: /* Make, Install And Run */ Fix syntax highlighting.

{{Template:I18n/Language Navigation Bar|Development/Tutorials/KCmdLineArgs}}

{{TutorialBrowser|

series=Beginner Tutorial|

name=Command line arguments (Under construction [[User:milliams]])|

pre=[[Development/Tutorials/Saving and loading|Tutorial 4 - Loading and saving]]|

next=[[Development/Tutorials/###|Tutorial 6 - ###]] (TODO [[User:milliams]])|

reading={{class|KCmdLineArgs}} {{class|KCmdLineOptions}}
}}

==Abstract==

Now that we have a text editor which can open and save files. We will now make the editor act more like a desktop application by enabling it to open files from command line arguments or even using ''Open with'' from within Dolphin.

[[image:introtokdetutorial5.png|frame|center]]

== The Code ==

===main.cpp===
<syntaxhighlight lang="cpp-qt">
#include <KApplication>
#include <KAboutData>
#include <KCmdLineArgs>
#include <KUrl> //new

#include "mainwindow.h"

int main (int argc, char *argv[])
{
KAboutData aboutData( "tutorial5", "tutorial5",
ki18n("Tutorial 5"), "1.0",
ki18n("A simple text area which can load and save."),
KAboutData::License_GPL,
ki18n("Copyright (c) 2007 Developer") );
KCmdLineArgs::init( argc, argv, &aboutData );

KCmdLineOptions options; //new
options.add("+[file]", ki18n("Document to open")); //new
KCmdLineArgs::addCmdLineOptions(options); //new

KApplication app;

MainWindow* window = new MainWindow();
window->show();

KCmdLineArgs *args = KCmdLineArgs::parsedArgs(); //new
if(args->count()) //new
{
window->openFile(args->url(0).url()); //new
}

return app.exec();
}
</syntaxhighlight>

===mainwindow.h===
<syntaxhighlight lang="cpp-qt">
#ifndef MAINWINDOW_H
#define MAINWINDOW_H

#include <KXmlGuiWindow>
#include <KTextEdit>

class MainWindow : public KXmlGuiWindow
{
Q_OBJECT

public:
MainWindow(QWidget *parent=0);
void openFile(const QString &inputFileName); //new

private:
KTextEdit* textArea;
void setupActions();
QString fileName;

private slots:
void newFile();
void openFile();
void saveFile();
void saveFileAs();
void saveFileAs(const QString &outputFileName);
};

#endif
</syntaxhighlight>

===mainwindow.cpp===
<syntaxhighlight lang="cpp-qt">
#include "mainwindow.h"

#include <KApplication>
#include <KAction>
#include <KLocale>
#include <KActionCollection>
#include <KStandardAction>
#include <KFileDialog>
#include <KMessageBox>
#include <KIO/NetAccess>
#include <KSaveFile>
#include <QTextStream>

MainWindow::MainWindow(QWidget *parent)
: KXmlGuiWindow(parent),
fileName(QString())
{
textArea = new KTextEdit;
setCentralWidget(textArea);

setupActions();
}

void MainWindow::setupActions()
{
KAction* clearAction = new KAction(this);
clearAction->setText(i18n("Clear"));
clearAction->setIcon(KIcon("document-new"));
clearAction->setShortcut(Qt::CTRL + Qt::Key_W);
actionCollection()->addAction("clear", clearAction);
connect(clearAction, SIGNAL(triggered(bool)),
textArea, SLOT(clear()));

KStandardAction::quit(kapp, SLOT(quit()),
actionCollection());

KStandardAction::open(this, SLOT(openFile()),
actionCollection());

KStandardAction::save(this, SLOT(saveFile()),
actionCollection());

KStandardAction::saveAs(this, SLOT(saveFileAs()),
actionCollection());

KStandardAction::openNew(this, SLOT(newFile()),
actionCollection());

setupGUI();
}

void MainWindow::newFile()
{
fileName.clear();
textArea->clear();
}

void MainWindow::saveFileAs(const QString &outputFileName)
{
KSaveFile file(outputFileName);
file.open();

QByteArray outputByteArray;
outputByteArray.append(textArea->toPlainText());
file.write(outputByteArray);
file.finalize();
file.close();

fileName = outputFileName;
}

void MainWindow::saveFileAs()
{
saveFileAs(KFileDialog::getSaveFileName());
}

void MainWindow::saveFile()
{
if(!fileName.isEmpty())
{
saveFileAs(fileName);
}
else
{
saveFileAs();
}
}

void MainWindow::openFile() //changed
{
openFile(KFileDialog::getOpenFileName());
}

void MainWindow::openFile(const QString &inputFileName) //new
{
QString tmpFile;
if(KIO::NetAccess::download(inputFileName, tmpFile,
this))
{
QFile file(tmpFile);
file.open(QIODevice::ReadOnly);
textArea->setPlainText(QTextStream(&file).readAll());
fileName = inputFileName;

KIO::NetAccess::removeTempFile(tmpFile);
}
else
{
KMessageBox::error(this,
KIO::NetAccess::lastErrorString());
}
}
</syntaxhighlight>

===tutorial5ui.rc===
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<gui name="tutorial5"
version="1"
xmlns="http://www.kde.org/standards/kxmlgui/1.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.kde.org/standards/kxmlgui/1.0
http://www.kde.org/standards/kxmlgui/1.0/kxmlgui.xsd" >

<MenuBar>
<Menu name="file" >
<Action name="clear" />
</Menu>
</MenuBar>

<ToolBar name="mainToolBar" >
<text>Main Toolbar</text>
<Action name="clear" />
</ToolBar>

</gui>
</syntaxhighlight>
This is identical to the <tt>tutorial''x''ui.rc</tt> from the last two tutorials except <tt>tutorial''x''</tt> is now <tt>tutorial5</tt>.

==Explanation==

===mainwindow.h===

Here we have done nothing but add a new <tt>openFile</tt> function which takes a <tt>QString</tt>
<syntaxhighlight lang="cpp-qt">
void openFile(const QString &inputFileName);
</syntaxhighlight>

===mainwindow.cpp===

There's no new code here, only rearranging. Everything from <tt>void openFile()</tt> has been moved into <tt>void openFile(const QString &inputFileName)</tt> except the call to <tt>KFileDialog::getOpenFileName()</tt>.

This way, we can call <tt>openFile()</tt> if we want to display a dialog, or we can call <tt>openFile(QString)</tt> if we know the name of the file already.

===main.cpp===

This is where all the {{class|KCmdLineArgs}} magic happens.

==Make, Install And Run==

===CMakeLists.txt===
<syntaxhighlight lang="cmake">
project(tutorial5)

find_package(KDE4 REQUIRED)
include_directories( ${KDE4_INCLUDES} )

set(tutorial5_SRCS
main.cpp
mainwindow.cpp
)

kde4_add_executable(tutorial5 ${tutorial5_SRCS})

target_link_libraries(tutorial5 ${KDE4_KDEUI_LIBS}
${KDE4_KIO_LIBS})

install(TARGETS tutorial5 DESTINATION ${BIN_INSTALL_DIR})
install( FILES tutorial5ui.rc
DESTINATION ${DATA_INSTALL_DIR}/tutorial5 )
</syntaxhighlight>

With this file, the tutorial can built and run in the same way as tutorial 3 and 4. For more information, see tutorial 3.
<syntaxhighlight lang="bash">
mkdir build && cd build
cmake .. -DCMAKE_INSTALL_PREFIX=$HOME
make install
$HOME/bin/tutorial5
</syntaxhighlight>

==Moving On==
Now you can move on to the ### (TODO [[User:milliams]]) tutorial.

[[Category:C++]]

Development/Tutorials/Saving and loading

2011-06-30T11:46:19Z

Icwiener: /* Make, Install And Run */ Fix syntax highlighting.

{{Template:I18n/Language Navigation Bar|Development/Tutorials/Saving_and_loading}}

{{TutorialBrowser|

series=Beginner Tutorial|

name=Loading and saving files|

pre=[[Development/Tutorials/Using_KActions|Tutorial 3 - KActions]]|

next=[[Development/Tutorials/KCmdLineArgs|Tutorial 5 - Using KCmdLineArgs]]|

reading=[[Development/Tutorials/KIO Slaves/Using KIO Slaves in your Program|Tutorial: Using KIO Slaves in your Program]] KIO::{{class|NetAccess}} {{qt|QFile}}
}}

==Abstract==

Now that we have a basic text editor interface, it's time to make it do something useful. At the most basic, a text editor needs to be able to load files from disc, save files that you've created/edited and create new files.

KDE provides a number of classes for working with files which make life a lot easier for developers. The KIO library allows you to easily access files through network-transparent protocols as well as providing standard file dialogs.

[[image:introtokdetutorial4.png|frame|center]]

== The Code ==

===main.cpp===
<syntaxhighlight lang="cpp-qt">
#include <KApplication>
#include <KAboutData>
#include <KCmdLineArgs>

#include "mainwindow.h"

int main (int argc, char *argv[])
{
KAboutData aboutData( "tutorial4", "tutorial4",
ki18n("Tutorial 4"), "1.0",
ki18n("A simple text area which can load and save."),
KAboutData::License_GPL,
ki18n("Copyright (c) 2007 Developer") );
KCmdLineArgs::init( argc, argv, &aboutData );
KApplication app;

MainWindow* window = new MainWindow();
window->show();
return app.exec();
}
</syntaxhighlight>
<tt>main.cpp</tt> hasn't changed from tutorial 3 except to change any reference from tutorial 3 to tutorial 4.

===mainwindow.h===
<syntaxhighlight lang="cpp-qt">
#ifndef MAINWINDOW_H
#define MAINWINDOW_H

#include <KXmlGuiWindow>
#include <KTextEdit>

class MainWindow : public KXmlGuiWindow
{
Q_OBJECT //new from tutorial3

public:
MainWindow(QWidget *parent=0);

private:
KTextEdit* textArea;
void setupActions();
QString fileName; //new

private slots: //new
void newFile(); //new
void openFile(); //new
void saveFile(); //new
void saveFileAs(); //new
void saveFileAs(const QString &outputFileName); //new
};

#endif
</syntaxhighlight>
Since we want to add the ability to load and save files, we must add the functions which will do the work. Since the functions will be called through Qt's [http://doc.trolltech.com/latest/signalsandslots.html signal/slot] mechanism we must specify that these functions are slots as we do on line 19. Since we are using slots in this header file, we must also add the [http://doc.trolltech.com/latest/qobject.html#Q_OBJECT <tt>Q_OBJECT</tt>] macro.

We also want to keep track of the filename of the currently opened file so we declare a <tt>{{qt|QString}} fileName</tt>.

===mainwindow.cpp===
<syntaxhighlight lang="cpp-qt">
#include "mainwindow.h"

#include <KApplication>
#include <KAction>
#include <KLocale>
#include <KActionCollection>
#include <KStandardAction>
#include <KFileDialog> //new
#include <KMessageBox> //new
#include <KIO/NetAccess> //new
#include <KSaveFile> //new
#include <QTextStream> //new

MainWindow::MainWindow(QWidget *parent)
: KXmlGuiWindow(parent),
fileName(QString()) //new
{
textArea = new KTextEdit;
setCentralWidget(textArea);

setupActions();
}

void MainWindow::setupActions()
{
KAction* clearAction = new KAction(this);
clearAction->setText(i18n("Clear"));
clearAction->setIcon(KIcon("document-new"));
clearAction->setShortcut(Qt::CTRL + Qt::Key_W);
actionCollection()->addAction("clear", clearAction);
connect(clearAction, SIGNAL(triggered(bool)),
textArea, SLOT(clear()));

KStandardAction::quit(kapp, SLOT(quit()),
actionCollection());

KStandardAction::open(this, SLOT(openFile()),
actionCollection()); //new

KStandardAction::save(this, SLOT(saveFile()),
actionCollection()); //new

KStandardAction::saveAs(this, SLOT(saveFileAs()),
actionCollection()); //new

KStandardAction::openNew(this, SLOT(newFile()),
actionCollection()); //new

setupGUI();
}

//New from here on

void MainWindow::newFile()
{
fileName.clear();
textArea->clear();
}

void MainWindow::saveFileAs(const QString &outputFileName)
{
KSaveFile file(outputFileName);
file.open();

QByteArray outputByteArray;
outputByteArray.append(textArea->toPlainText().toUtf8());
file.write(outputByteArray);
file.finalize();
file.close();

fileName = outputFileName;
}

void MainWindow::saveFileAs()
{
saveFileAs(KFileDialog::getSaveFileName());
}

void MainWindow::saveFile()
{
if(!fileName.isEmpty())
{
saveFileAs(fileName);
}
else
{
saveFileAs();
}
}

void MainWindow::openFile()
{
QString fileNameFromDialog = KFileDialog::getOpenFileName();

QString tmpFile;
if(KIO::NetAccess::download(fileNameFromDialog, tmpFile, this))
{
QFile file(tmpFile);
file.open(QIODevice::ReadOnly);
textArea->setPlainText(QTextStream(&file).readAll());
fileName = fileNameFromDialog;

KIO::NetAccess::removeTempFile(tmpFile);
}
else
{
KMessageBox::error(this,
KIO::NetAccess::lastErrorString());
}
}
</syntaxhighlight>

===tutorial4ui.rc===
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<gui name="tutorial4"
version="1"
xmlns="http://www.kde.org/standards/kxmlgui/1.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.kde.org/standards/kxmlgui/1.0
http://www.kde.org/standards/kxmlgui/1.0/kxmlgui.xsd" >

<MenuBar>
<Menu name="file" >
<Action name="clear" />
</Menu>
</MenuBar>

<ToolBar name="mainToolBar" >
<text>Main Toolbar</text>
<Action name="clear" />
</ToolBar>

</gui>
</syntaxhighlight>
This is identical to <tt>tutorial3ui.rc</tt> from tutorial 3 except the <tt>name</tt> has changed to 'tutorial4'. We do not need to add any information about any of the <tt>KStandardAction</tt>s since the placement of those actions is handled automatically by KDE.

==Explanation==

Okay, now to implement the code that will do the loading and saving. This will all be happening in <tt>mainwindow.cpp</tt>

The first thing we do is add <tt>fileName(QString())</tt> to the <tt>MainWindow</tt> constructor list on line 16. This makes sure that <tt>fileName</tt> is empty right from the beginning.

===Adding the actions===

The first thing we are going to do is provide the outward interface for the user so they can tell the application to load and save. Like with the <tt>quit</tt> action in tutorial 3, we will use <tt>KStandardActions</tt>. On lines 37 to 47 we add the actions in the same way as for the <tt>quit</tt> action. For each one, we connect it to the appropriate slot that we declared in the header file.

===Creating a new document===

The first function we create is the <tt>newFile()</tt> function.
<syntaxhighlight lang="cpp-qt">
void MainWindow::newFile()
{
fileName.clear();
textArea->clear();
}
</syntaxhighlight>
<tt>fileName.clear()</tt> sets the <tt>fileName</tt> QString to be empty to reflect the fact that this document does not yet have a presence on disc. <tt>textArea->clear()</tt> then clears the central text area using the same function that we connected the <tt>clear</tt> <tt>KAction</tt> to in tutorial 3.

===Saving a file===

====saveFileAs(QString)====

Now we get onto our first file handling code. We're going to implement a function which will save the contents of the text area to the file name given as a parameter. KDE provides a class for safely saving a file called {{class|KSaveFile}} which is derived from Qt's {{qt|QFile}}.

The function's prototype is
<syntaxhighlight lang="cpp-qt">
void MainWindow::saveFileAs(const QString &outputFileName)
</syntaxhighlight>

We then create our <tt>KSaveFile</tt> object and open it with
<syntaxhighlight lang="cpp-qt">
KSaveFile file(outputFileName);
file.open();
</syntaxhighlight>

Now that we have our file to write to, we need to format the text in the text area to a format which can be written to file. For this, we create a {{qt|QByteArray}} and fill it with the plain text version of whatever is in the text area:
<syntaxhighlight lang="cpp-qt">
QByteArray outputByteArray;
outputByteArray.append(textArea->toPlainText().toUtf8());
</syntaxhighlight>
Now that we have our <tt>QByteArray</tt>, we use it to write to the file with <tt>KSaveFile::write()</tt>. If we were using a normal <tt>QFile</tt>, this would make the changes immediately. However, if a problem occurred partway through writing, the file would become corrupted. For this reason, <tt>KSaveFile</tt> works by first writing to a temporary file and then, when you call <tt>KSaveFile::finalize()</tt> the changes are made to the actual file.
<syntaxhighlight lang="cpp-qt">
file.write(outputByteArray);
file.finalize();
file.close();
</syntaxhighlight>
Finally, we set <tt>MainWindows</tt>'s <tt>fileName</tt> member to point to the file name we just saved to.
<syntaxhighlight lang="cpp-qt">
fileName = outputFileName;
</syntaxhighlight>

====saveFileAs()====

This is the function that the <tt>saveAs</tt> slot is connected to. It simply calls the generic <tt>saveFileAs(QString)</tt> function and passes the file name returned by <tt>{{class|KFileDialog}}::[http://api.kde.org/4.0-api/kdelibs-apidocs/kio/html/classKFileDialog.html#8891356c249c5911e1ab15cc2739a89b getSaveFileName()]</tt>.

<syntaxhighlight lang="cpp-qt">
void MainWindow::saveFileAs()
{
saveFileAs(KFileDialog::getSaveFileName());
}
</syntaxhighlight>

This is our first actual use of the KIO library. {{class|KFileDialog}} provides a number of static functions for displaying the common file dialog that is used by all KDE applications. Calling <tt>KFileDialog::getSaveFileName()</tt> will display a dialog where the user can select the name of the file to save to or choose a new name. The function returns the full file name, which we then pass to <tt>saveFileAs(QString)</tt>.

====saveFile()====

<syntaxhighlight lang="cpp-qt">
void MainWindow::saveFile()
{
if(!fileName.isEmpty())
{
saveFileAs(fileName);
}
else
{
saveFileAs();
}
}
</syntaxhighlight>

There's nothing exciting or new in this function, just the logic to decide whether or not to show the save dialog. If <tt>fileName</tt> is not empty, then the file is saved to <tt>fileName</tt>. But if it is, then the dialog is shown to allow the user to select a file name.

===Loading a file===

Finally, we get round to being able to load a file from disc. The code for this is all contained in <tt>MainWindow::openFile()</tt>.

First we must ask the user for the name of the file they wish to open. We do this using another one of the <tt>KFileDialog</tt> functions, this time <tt>getOpenFileName()</tt>:
<syntaxhighlight lang="cpp-qt">
QString fileNameFromDialog = KFileDialog::getOpenFileName();
</syntaxhighlight>

Then we use the KIO library to retrieve our file. This allows us to open the file with QFile even if it's stored in a remote location like an FTP site. We make the following call to {{class|NetAccess}}'s <tt>download()</tt> function
<syntaxhighlight lang="cpp-qt">
KIO::NetAccess::download(fileNameFromDialog, tmpFile, this)
</syntaxhighlight>
The first argument is the name of the file you wish to download. The second is a QString which, after the download is complete, will contain the location of the temporary copy of the file. It is this <tt>tmpFile</tt> we will work with from now on.

The function returns <tt>true</tt> or <tt>false</tt> depending on whether the transfer was successful. If it failed, we display a message box giving the error:
<syntaxhighlight lang="cpp-qt">
KMessageBox::error(this, KIO::NetAccess::lastErrorString());
</syntaxhighlight>

Otherwise, we continue with opening the file.

We create a QFile by passing the temporary file created by <tt>NetAccess::download()</tt> to its constructor and then open it in read-only mode
<syntaxhighlight lang="cpp-qt">
QFile file(tmpFile);
file.open(QIODevice::ReadOnly);
</syntaxhighlight>

In order to display the contents of the file, we must use a {{qt|QTextStream}}. We create one by passing the contents of our file to its constructor and then call QFile's <tt>readAll()</tt> function to get the text from the file. This is then passed to the <tt>setPlainText()</tt> function of our text area.

<syntaxhighlight lang="cpp-qt">
textArea->setPlainText(QTextStream(&file).readAll());
</syntaxhighlight>

We then store the path of the file we just opened:
<syntaxhighlight lang="cpp-qt">
fileName = fileNameFromDialog;
</syntaxhighlight>
and finally, we remove the temporary file that was created by <tt>NetAccess::download()</tt>:
<syntaxhighlight lang="cpp-qt">
KIO::NetAccess::removeTempFile(tmpFile);
</syntaxhighlight>

==Make, Install And Run==

===CMakeLists.txt===
<syntaxhighlight lang="cmake">
project(tutorial4)

find_package(KDE4 REQUIRED)
include_directories(${KDE4_INCLUDES})

set(tutorial4_SRCS
main.cpp
mainwindow.cpp
)

kde4_add_executable(tutorial4 ${tutorial4_SRCS})

target_link_libraries(tutorial4 ${KDE4_KDEUI_LIBS}
${KDE4_KIO_LIBS})

install(TARGETS tutorial4 DESTINATION ${BIN_INSTALL_DIR})
install(FILES tutorial4ui.rc
DESTINATION ${DATA_INSTALL_DIR}/tutorial4)
</syntaxhighlight>
Since we are now using the KIO library, we must tell CMake to link against it. We do this by passing <tt>${KDE4_KIO_LIBS}</tt> to the <tt>target_link_libraries()</tt> function.

With this file, the tutorial can be built and run in the same way as tutorial 3. For more information, see tutorial 3.
<syntaxhighlight lang="bash">
mkdir build && cd build
cmake .. -DCMAKE_INSTALL_PREFIX=$HOME
make install
$HOME/bin/tutorial4
</syntaxhighlight>

{{note|Changed settings are saved in your KDE directory, in this case into $HOME/.kde/share/apps/tutorial4.}}

==Moving On==
Now you can move on to the [[Development/Tutorials/KCmdLineArgs|KCmdLineArgs]] tutorial.

[[Category:C++]]

Development/Tutorials/Using KActions

2011-06-30T11:45:25Z

Icwiener: /* CMake */ Fix syntax highlighting.

{{Template:I18n/Language Navigation Bar|Development/Tutorials/Using_KActions}}

{{TutorialBrowser|

series=Beginner Tutorial|

name=How To Use KActions and XMLGUI|

pre=[[Development/Tutorials/Using_KXmlGuiWindow|Tutorial 2 - KXmlGuiWindow]], Basic XML knowledge|

next=[[Development/Tutorials/Saving_and_loading|Tutorial 4 - Saving and loading]]|

reading=None
}}

==Abstract==
This tutorial introduces the concept of actions. Actions are a unified way of supplying the user with ways to interact with your program.

For example, if we wanted to let the user of [[Development/Tutorials/Using_KXmlGuiWindow|Tutorial 2 ]] clear the text box by clicking a button in the toolbar, from an option in the File menu or through a keyboard shortcut, it could all be done with 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 that is associated with a certain action. The action is then connected to a [http://doc.trolltech.com/latest/signalsandslots.html slot] which carries out the work of your action.

== The Code ==

===main.cpp===
<syntaxhighlight lang="cpp-qt">
#include <KApplication>
#include <KAboutData>
#include <KCmdLineArgs>

#include "mainwindow.h"

int main (int argc, char *argv[])
{
KAboutData aboutData( "tutorial3", "tutorial3",
ki18n("Tutorial 3"), "1.0",
ki18n("A simple text area using KAction etc."),
KAboutData::License_GPL,
ki18n("Copyright (c) 2007 Developer") );
KCmdLineArgs::init( argc, argv, &aboutData );
KApplication app;

MainWindow* window = new MainWindow();
window->show();
return app.exec();
}
</syntaxhighlight>
This time, very little has changed in <tt>main.cpp</tt>, only the KAboutData constructor has been updated to show that we are now on tutorial 3.

===mainwindow.h===
<syntaxhighlight lang="cpp-qt">
#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
</syntaxhighlight>
Only a function <tt>void setupActions()</tt> has been added which will do all the work setting up the KActions.

===mainwindow.cpp===
<syntaxhighlight lang="cpp-qt">
#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()
{
KAction* clearAction = new KAction(this);
clearAction->setText(i18n("&Clear"));
clearAction->setIcon(KIcon("document-new"));
clearAction->setShortcut(Qt::CTRL + Qt::Key_W);
actionCollection()->addAction("clear", clearAction);
connect(clearAction, SIGNAL(triggered(bool)),
textArea, SLOT(clear()));

KStandardAction::quit(kapp, SLOT(quit()),
actionCollection());

setupGUI(Default, "tutorial3ui.rc");
}
</syntaxhighlight>

==Explanation==
This builds upon the KXmlGuiWindow code from [[Development/Tutorials/Using_KXmlGuiWindow|Tutorial 2]]. Most of the changes are to <tt>mainwindow.cpp</tt>, an important structural change being that the constructor for MainWindow now calls <tt>setupActions()</tt> instead of <tt>setupGUI()</tt>. <tt>setupActions()</tt> is where the new KAction code goes before finally calling <tt>setupGUI()</tt> itself.

===Creating the KAction object===
The KAction is built up in a number of steps. The first is including the <tt>KAction</tt> library and then creating the KAction:
<syntaxhighlight lang="cpp-qt">
#include <KAction>
...
KAction* clearAction = new KAction(this);
</syntaxhighlight>
This creates a new KAction called <tt>clearAction</tt>.

===Setting KAction Properties===
====Text====
Now that we have our KAction object, we can start setting its properties. The following code sets the text that will be displayed in the menu and under the <tt>KAction</tt>'s icon in the toolbar.
<syntaxhighlight lang="cpp-qt">
clearAction->setText(i18n("&Clear"));
</syntaxhighlight>
Note that the text is passed through the <tt>i18n()</tt> function; this is necessary for the UI to be translatable (more information on this can be found in the [[Development/Tutorials/Localization/i18n|i18n tutorial]]).

The text of the action should contain a <tt>&</tt> because that makes it easier to translate in non-latin1 languages. In Japanese, the translation might be <tt>ソース(&S)</tt> and without the <tt>&</tt> in the english text the translators cannot know if they have to add a <tt>&</tt> or not.

====Icon====
If the action is going to be displayed in a toolbar, it is nice to have an icon depicting the action. The following code sets the icon to the standard KDE <tt>document-new</tt> icon through the use of the <tt>setIcon()</tt> function:
<syntaxhighlight lang="cpp-qt">
clearAction->setIcon(KIcon("document-new"));
</syntaxhighlight>

====Keyboard Shortcut====
Setting a keyboard shortcut to perform our action is equally simple:
<syntaxhighlight lang="cpp-qt">
clearAction->setShortcut(Qt::CTRL + Qt::Key_W);
</syntaxhighlight>
This associates Ctrl+W with the KAction.

===Adding to the Collection===
In order for the action to be accessed by the XMLGUI framework (explained in depth later) it must be added to the application's ''action collection''. The action collection is accessed via the <tt>actionCollection()</tt> function like this:
<syntaxhighlight lang="cpp-qt">
actionCollection()->addAction("clear", clearAction);
</syntaxhighlight>
Here, the <tt>clearAction</tt> KAction is added to the collection and given a name of ''clear''. This name (''clear'') is used by the XMLGUI framework to refer to the action, ergo, it should not be localized, since it is used internally only.

====Connecting the action====
Now that the action is fully set up, it needs to be connected to something useful. In this case (because we want to clear the text area), we connect our action to the <tt>clear()</tt> action belonging to a KTextEdit (which, unsurprisingly, clears the KTextEdit)
<syntaxhighlight lang="cpp-qt">
connect( clearAction, SIGNAL( triggered(bool) ),
textArea, SLOT( clear() ) );
</syntaxhighlight>
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 [http://api.kde.org/4.0-api/kdelibs-apidocs/kdeui/html/namespaceKStandardAction.html KStandardAction].

They are very simple to use. Once the library has been included (<tt>#include <KStandardAction></tt>), simply supply it with what you want the function to do and which KActionCollection to add it to. For example:
<syntaxhighlight lang="cpp-qt">
KStandardAction::quit(kapp, SLOT(quit()), actionCollection());
</syntaxhighlight>
This creates a KAction with the correct icon, text and shortcut and even adds it to the File menu.

==Adding the action to menus and toolbars==
At the moment, the new "Clear" action has been created but it hasn't been associated with any menus or toolbars. This is done with a KDE technology called XMLGUI, which does nice things like movable toolbars for you.

{{note|In a later version of KDE4, XMLGUI, may be replaced with a new framework called liveui. For now, XMLGUI, is the only and correct way to set up the UI.}}

==Defining your own help menu==
The help menu is god-given, that is why all KDE help menus look the same. If you want to create your own help menu, go [http://websvn.kde.org/trunk/KDE/kdelibs/kdeui/widgets/khelpmenu.h?revision=1002779&view=markup here] and search for the explanation around showAboutApplication().

==XMLGUI==

The <tt>setupGUI()</tt> function in {{class|KXmlGuiWindow}} depends on the XMLGUI system to construct the GUI, which XMLGUI does by parsing an XML file description of the interface.

The rule for naming this XML file is <tt>appnameui.rc</tt>, where <tt>appname</tt> is the name you set in {{class|KAboutData}} (in this case, ''tutorial3''). So in our example, the file is called <tt>tutorial3ui.rc</tt>, and is located in the build directory. Where the file will ultimately be placed is handled by CMake.

''See also'' [http://developer.kde.org/documentation/library/kdeqt/kde3arch/xmlgui.html developer.kde.org] which still provides valid information for KDE4.

==''appname''ui.rc File==

Since the description of the UI is defined with XML, the layout must follow strict rules. This tutorial will not go into great depth on this topic, but for more information, see the [[Development/Architecture/KDE4/XMLGUI_Technology|detailed XMLGUI page]] (here is an older tutorial: [http://developer.kde.org/documentation/tutorials/xmlui/preface.html]).

===tutorial3ui.rc===
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<gui name="tutorial3"
version="1"
xmlns="http://www.kde.org/standards/kxmlgui/1.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.kde.org/standards/kxmlgui/1.0
http://www.kde.org/standards/kxmlgui/1.0/kxmlgui.xsd" >

<MenuBar>
<Menu name="file" >
<Action name="clear" />
</Menu>
</MenuBar>

<ToolBar name="mainToolBar" >
<text>Main Toolbar</text>
<Action name="clear" />
</ToolBar>

</gui>
</syntaxhighlight>

The <tt><Toolbar></tt> tag allows you to describe the toolbar, which is the bar across the top of the window normally with icons. Here it is given the unique name ''mainToolBar'' and its user visible name set to ''Main Toolbar'' using the <tt><text></tt> tag. The clear action is added to the toolbar using the <tt><Action></tt> tag, the name parameter in this tag being the string that was passed to the KActionCollection with <tt>addAction()</tt> in <tt>mainwindow.cpp</tt>.

Besides having the action in the toolbar, it can also be added to the menubar. Here the action is being added to the ''File'' menu of the <tt>MenuBar</tt> the same way it was added to the toolbar.

Change the 'version' attribute of the <tt><nowiki><gui></nowiki></tt> tag if you changed .rc file since the last install to force a system cache update. Be sure it is an integer, if you use a decimal value, it will not work, but will not notify that it didn't. '

{{Warning|The version attribute must be an integer number, if you type in version<nowiki>=</nowiki>"1.2" it will dispose of your kittens (but not eat them).}}

Some notes on the interaction between code and the .rc file: Menus appear automatically and should have a <tt><nowiki><text/></nowiki></tt> child tag unless they refer to standard menus. Actions need to be created manually and inserted into the actionCollection() using the name in the .rc file. Actions can be hidden or disabled, whereas menus can't.

==CMake==
Finally, the <tt>tutorial3ui.rc</tt> needs to go somewhere where KDE can find it (can't just leave it in the source directory!). '''This means the project needs to be installed somewhere.'''
===CMakeLists.txt===
<syntaxhighlight lang="cmake">
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)
</syntaxhighlight>

This file is almost identical to the one for tutorial2, but with two extra lines at the end that describe where the files are to be installed. Firstly, the <tt>tutorial3</tt> target is installed to the <tt>BIN_INSTALL_DIR</tt> then the <tt>tutorial3ui.rc</tt> file that describes the layout of the user interface is installed to the application's data directory.

===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. You probably 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), so the following might be appropriate:
<syntaxhighlight lang="bash">
mkdir build && cd build
cmake .. -DCMAKE_INSTALL_PREFIX=$HOME
make install
$HOME/bin/tutorial3
</syntaxhighlight>
which will create a KDE-like directory structure in your user's home directory and will install the executable to {{path|$HOME/bin/tutorial3}}.

==Moving On==
Now you can move on to [[Development/Tutorials/Saving_and_loading|saving and loading]].

[[Category:C++]]

Development/Tutorials/Using KXmlGuiWindow

2011-06-30T11:43:53Z

Icwiener: /* CMake */ Fix syntax highlighting.

{{Template:I18n/Language Navigation Bar|Development/Tutorials/Using_KXmlGuiWindow}}
{{TutorialBrowser|

series=Beginner Tutorial|

name=How To Use KXmlGuiWindow|

pre=[[Development/Tutorials/First_program|Tutorial 1 - Hello World]]|

next=[[Development/Tutorials/Using_KActions|Tutorial 3 - KActions and XMLGUI]]|

reading={{class|KXmlGuiWindow}}
}}

==Abstract==
This tutorial carries on from [[Development/Tutorials/First_program|First Program Tutorial]] and will introduce the {{class|KXmlGuiWindow}} class.

In the previous tutorial, the program caused a dialog box to pop up but we're going to take steps towards a functioning application.

[[image:introtokdetutorial2.png|frame|center]]

==KXmlGuiWindow==

{{class|KXmlGuiWindow}} provides a full main window view with menubars, toolbars, a statusbar and a main area in the centre for a large widget. Most KDE applications will derive from this class as it provides an easy way to define menu and toolbar layouts through XML files (this technology is called XMLGUI). While we will not be using XMLGUI in ''this'' tutorial, we will use it in the next.

In order to have a useful KXmlGuiWindow, we must subclass it. So we create two files, a <tt>mainwindow.cpp</tt> and a <tt>mainwindow.h</tt> which will contain our code.

===mainwindow.h===
<syntaxhighlight lang="cpp-qt">
#ifndef MAINWINDOW_H
#define MAINWINDOW_H

#include <KXmlGuiWindow>
#include <KTextEdit>

class MainWindow : public KXmlGuiWindow
{
public:
MainWindow(QWidget *parent=0);

private:
KTextEdit* textArea;
};

#endif
</syntaxhighlight>
First we Subclass KXmlGuiWindow on line 7 with <tt>class MainWindow : public KXmlGuiWindow</tt>.

Then we declare the constructor with <tt>MainWindow(QWidget *parent=0);</tt>.

And finally we declare a pointer to the object that will make up the bulk of our program. {{class|KTextEdit}} is a generic richtext editor with some KDE niceties like cursor auto-hiding.

===mainwindow.cpp===
<syntaxhighlight lang="cpp-qt">
#include "mainwindow.h"

MainWindow::MainWindow(QWidget *parent) : KXmlGuiWindow(parent)
{
textArea = new KTextEdit();
setCentralWidget(textArea);
setupGUI();
}
</syntaxhighlight>
First, of course, on line 1 we have to include the header file containing the class declaration.

On line 5, we initialise our text editor with an object. Then on line 6 we use KXmlGuiWindow's built-in setCentralWidget() function which tells the KXmlGuiWindow what should appear in the central section of the window.

Finally, KXmlGuiWindow::setupGUI() is called which does a lot of behind-the-scenes stuff and creates the default menu bars (Settings, Help).

==Back to main.cpp==
In order to actually run this window, we need to add a few lines in main.cpp:
===main.cpp===
<syntaxhighlight lang="cpp-qt">
#include <KApplication>
#include <KAboutData>
#include <KCmdLineArgs>
#include <KLocale>

#include "mainwindow.h"

int main (int argc, char *argv[])
{
KAboutData aboutData( "tutorial2", 0,
ki18n("Tutorial 2"), "1.0",
ki18n("A simple text area"),
KAboutData::License_GPL,
ki18n("Copyright (c) 2007 Developer") );
KCmdLineArgs::init( argc, argv, &aboutData );

KApplication app;

MainWindow* window = new MainWindow();
window->show();

return app.exec();
}
</syntaxhighlight>
The only new lines here (compared to Tutorial 1) are 6, 19 and 20. On line 19, we create our MainWindow object and then on line 20, we display it.

==CMake==
The best way to build the program is to use CMake. All that's changed since tutorial 1 is that <tt>mainwindow.cpp</tt> has been added to the sources list and any <tt>tutorial1</tt> has become <tt>tutorial2</tt>.
===CMakeLists.txt===
<syntaxhighlight lang="cmake">
project (tutorial2)

find_package(KDE4 REQUIRED)
include_directories(${KDE4_INCLUDES})

set(tutorial2_SRCS
main.cpp
mainwindow.cpp
)

kde4_add_executable(tutorial2 ${tutorial2_SRCS})
target_link_libraries(tutorial2 ${KDE4_KDEUI_LIBS})
</syntaxhighlight>

===Compile it===
To compile, link and run it, use:
<syntaxhighlight lang="bash">
mkdir build && cd build
cmake ..
make
./tutorial2
</syntaxhighlight>

==Moving On==
Now you can move on to [[Development/Tutorials/Using_KActions|using KActions]].

[[Category:C++]]

Development/Tutorials/First program

2011-06-30T11:42:50Z

Icwiener: /* Make And Run */ Fix syntax highlighting.

{{Template:I18n/Language Navigation Bar|Development/Tutorials/First_program}}
{{TutorialBrowser|

series=Beginner Tutorial|

name=Hello World|

pre=[http://mindview.net/Books/TICPP/ThinkingInCPP2e.html C++], [http://qt.nokia.com Qt], [[Getting_Started/Build|Building KDE]]|

next=[[Development/Tutorials/Using_KXmlGuiWindow|Tutorial 2 - KXmlGuiWindow]]|

reading=[[Development/Tutorials/CMake|CMake]]
}}

==Abstract==
Your first program shall greet the world with a friendly "Hello World", what else? For that, we will use a {{class|KMessageBox}} and customise one of the buttons.
[[image:introtokdetutorial1.png|frame|center]]

{{tip|To get more information about any class you come across, Konqueror offers a quick shortcut. So to look for information about KMessageBox, just type "kde:kmessagebox" into Konqueror and you'll be taken to the documentation.}}

{{tip|
You might want to use KDevelop for your projects, which does many nice things like code completion, easy access to API documentation or debugging support.

Read [[Getting_Started/Set_up_KDE_4_for_development#KDevelop|this tutorial]] to set up KDevelop correctly for this task. You probably want to check if the setup is working by testing opening an existing KDE 4 application with KDevelop first.

You still need to edit the CMake files by hand though.
}}

==The Code==
All the code we need will be in one file, <tt>main.cpp</tt>. Create that file with the code below:
<syntaxhighlight lang="cpp-qt">
#include <KApplication>
#include <KAboutData>
#include <KCmdLineArgs>
#include <KMessageBox>
#include <KLocale>

int main (int argc, char *argv[])
{
KAboutData aboutData(
// The program name used internally.
"tutorial1",
// The message catalog name
// If null, program name is used instead.
0,
// A displayable program name string.
ki18n("Tutorial 1"),
// The program version string.
"1.0",
// Short description of what the app does.
ki18n("Displays a KMessageBox popup"),
// The license this code is released under
KAboutData::License_GPL,
// Copyright Statement
ki18n("(c) 2007"),
// Optional text shown in the About box.
// Can contain any information desired.
ki18n("Some text..."),
// The program homepage string.
"http://example.com/",
// The bug report email address
"submit@bugs.kde.org");

KCmdLineArgs::init( argc, argv, &aboutData );
KApplication app;
KGuiItem yesButton( i18n( "Hello" ), QString(),
i18n( "This is a tooltip" ),
i18n( "This is a WhatsThis help text." ) );
KMessageBox::questionYesNo( 0, i18n( "Hello World" ),
i18n( "Hello" ), yesButton );
return 0;
}
</syntaxhighlight>
The first KDE specific code we come across in this program is {{class|KAboutData}}. This is the class used to store information about the program such as a short description, authors or license information. Pretty much every KDE application should use this class.

Then we come to {{class|KCmdLineArgs}}. This is the class one would use to specify command line switches to, for example, open the program with a specific file. However, in this tutorial, we simply initialise it with the {{class|KAboutData}} object we created so we can use the <tt>--version</tt> or <tt>--author</tt> switches.

Then we create a {{class|KApplication}} object. This needs to be done exactly once in each program since it is needed for things such as [[Development/Tutorials/Localization/i18n|i18n]].

Now we've done all the necessary KDE setup, we can move on to doing interesting things with our application. We're going to create a popup box but we're going to customise one of the buttons. To do this customisation, we need to use a {{class|KGuiItem}} object. The first argument in the {{class|KGuiItem}} constructor is the text that will appear on the item (in our case, a button). Then we have an option of setting an icon for the button but we don't want one so we just give it <tt>QString()</tt>. We then set the tooltip (what appears when you hover over an item) and finally the "What's This?" (accessed through right-clicking or Shift-F1) text.

Now we have our item, we can create our popup. We call the <tt>{{class|KMessageBox}}::questionYesNo()</tt> function which, by default, creates a message box with a "Yes" and a "No" button. The second argument is the text that will appear in the message box above the buttons. The third is the caption the window will have and finally we set the KGuiItem for (what would normally be) the "Yes" button to the <tt>KGuiItem yesButton</tt> we created.

Note that all user-visible text is passed through the i18n() function; this is necessary for the UI to be translatable. More information on localization can be found in the [[Development/Tutorials/Localization/i18n|localization tutorial]].

We're all done as far as the code is concerned. Now to build it and try it out.

== Build ==
You want to [[Development/Tutorials/CMake|use CMake]] for your build environment. You provide a file CMakeLists.txt, cmake uses this file to generate all Makefiles out of it.

=== CMakeLists.txt ===
Create a file named CMakeLists.txt in the same directory as main.cpp with this content:
<syntaxhighlight lang="cmake">
project (tutorial1)
find_package(KDE4 REQUIRED)
include (KDE4Defaults)
include_directories(${KDE4_INCLUDES})
set(tutorial1_SRCS main.cpp)
kde4_add_executable(tutorial1 ${tutorial1_SRCS})
target_link_libraries(tutorial1 ${KDE4_KDEUI_LIBS})
install(TARGETS tutorial1 ${INSTALL_TARGETS_DEFAULT_ARGS})
</syntaxhighlight>
The <tt>find_package()</tt> function locates the package that you ask it for (in this case KDE4) and sets some variables describing the location of the package's headers and libraries. In this case we will use the <tt>KDE4_INCLUDES</tt> variable which contains the path to the KDE4 header files.

In order to allow the compiler to find these files, we pass that variable to the <tt>include_directories()</tt> function which adds the KDE4 headers to the header search path.

Next we create a variable called <tt>tutorial1_SRCS</tt> using the <tt>set()</tt> function. In this case we simply set it to the name of our only source file.

Then we use <tt>kde4_add_executable()</tt> to create an executable called <tt>tutorial1</tt> from the source files listed in our <tt>tutorial1_SRCS</tt> variable. Afterwards, we link our executable to the KDE4 kdeui library using <tt>target_link_libraries()</tt> and the <tt>KDE4_KDEUI_LIBS</tt> variable which was set by the <tt>find_package()</tt> function. The line starting with <tt>install</tt> writes a default "install" target into the Makefile.

=== Make And Run ===
You can invoke CMake and make manually:
<syntaxhighlight lang="bash">
mkdir build && cd build
cmake .. # Note the two dots - this is no ellipsis, but "parent directory".
make
</syntaxhighlight>
Or, if you set up your environment as described in [[Getting_Started/Build/Environment|Getting Started/Build/Environemnt]], you can compile this code with:
<syntaxhighlight lang="bash">
cmakekde
</syntaxhighlight>

And launch it with:
<syntaxhighlight lang="bash">
./tutorial1
</syntaxhighlight>

==Moving On==
Now you can move on to [[Development/Tutorials/Using_KXmlGuiWindow|using KXmlGuiWindow]].

[[Category:C++]]

Development/Tutorials/First program

2011-06-30T11:41:42Z

Icwiener: /* CMakeLists.txt */ fix syntax highlight

{{Template:I18n/Language Navigation Bar|Development/Tutorials/First_program}}
{{TutorialBrowser|

series=Beginner Tutorial|

name=Hello World|

pre=[http://mindview.net/Books/TICPP/ThinkingInCPP2e.html C++], [http://qt.nokia.com Qt], [[Getting_Started/Build|Building KDE]]|

next=[[Development/Tutorials/Using_KXmlGuiWindow|Tutorial 2 - KXmlGuiWindow]]|

reading=[[Development/Tutorials/CMake|CMake]]
}}

==Abstract==
Your first program shall greet the world with a friendly "Hello World", what else? For that, we will use a {{class|KMessageBox}} and customise one of the buttons.
[[image:introtokdetutorial1.png|frame|center]]

{{tip|To get more information about any class you come across, Konqueror offers a quick shortcut. So to look for information about KMessageBox, just type "kde:kmessagebox" into Konqueror and you'll be taken to the documentation.}}

{{tip|
You might want to use KDevelop for your projects, which does many nice things like code completion, easy access to API documentation or debugging support.

Read [[Getting_Started/Set_up_KDE_4_for_development#KDevelop|this tutorial]] to set up KDevelop correctly for this task. You probably want to check if the setup is working by testing opening an existing KDE 4 application with KDevelop first.

You still need to edit the CMake files by hand though.
}}

==The Code==
All the code we need will be in one file, <tt>main.cpp</tt>. Create that file with the code below:
<syntaxhighlight lang="cpp-qt">
#include <KApplication>
#include <KAboutData>
#include <KCmdLineArgs>
#include <KMessageBox>
#include <KLocale>

int main (int argc, char *argv[])
{
KAboutData aboutData(
// The program name used internally.
"tutorial1",
// The message catalog name
// If null, program name is used instead.
0,
// A displayable program name string.
ki18n("Tutorial 1"),
// The program version string.
"1.0",
// Short description of what the app does.
ki18n("Displays a KMessageBox popup"),
// The license this code is released under
KAboutData::License_GPL,
// Copyright Statement
ki18n("(c) 2007"),
// Optional text shown in the About box.
// Can contain any information desired.
ki18n("Some text..."),
// The program homepage string.
"http://example.com/",
// The bug report email address
"submit@bugs.kde.org");

KCmdLineArgs::init( argc, argv, &aboutData );
KApplication app;
KGuiItem yesButton( i18n( "Hello" ), QString(),
i18n( "This is a tooltip" ),
i18n( "This is a WhatsThis help text." ) );
KMessageBox::questionYesNo( 0, i18n( "Hello World" ),
i18n( "Hello" ), yesButton );
return 0;
}
</syntaxhighlight>
The first KDE specific code we come across in this program is {{class|KAboutData}}. This is the class used to store information about the program such as a short description, authors or license information. Pretty much every KDE application should use this class.

Then we come to {{class|KCmdLineArgs}}. This is the class one would use to specify command line switches to, for example, open the program with a specific file. However, in this tutorial, we simply initialise it with the {{class|KAboutData}} object we created so we can use the <tt>--version</tt> or <tt>--author</tt> switches.

Then we create a {{class|KApplication}} object. This needs to be done exactly once in each program since it is needed for things such as [[Development/Tutorials/Localization/i18n|i18n]].

Now we've done all the necessary KDE setup, we can move on to doing interesting things with our application. We're going to create a popup box but we're going to customise one of the buttons. To do this customisation, we need to use a {{class|KGuiItem}} object. The first argument in the {{class|KGuiItem}} constructor is the text that will appear on the item (in our case, a button). Then we have an option of setting an icon for the button but we don't want one so we just give it <tt>QString()</tt>. We then set the tooltip (what appears when you hover over an item) and finally the "What's This?" (accessed through right-clicking or Shift-F1) text.

Now we have our item, we can create our popup. We call the <tt>{{class|KMessageBox}}::questionYesNo()</tt> function which, by default, creates a message box with a "Yes" and a "No" button. The second argument is the text that will appear in the message box above the buttons. The third is the caption the window will have and finally we set the KGuiItem for (what would normally be) the "Yes" button to the <tt>KGuiItem yesButton</tt> we created.

Note that all user-visible text is passed through the i18n() function; this is necessary for the UI to be translatable. More information on localization can be found in the [[Development/Tutorials/Localization/i18n|localization tutorial]].

We're all done as far as the code is concerned. Now to build it and try it out.

== Build ==
You want to [[Development/Tutorials/CMake|use CMake]] for your build environment. You provide a file CMakeLists.txt, cmake uses this file to generate all Makefiles out of it.

=== CMakeLists.txt ===
Create a file named CMakeLists.txt in the same directory as main.cpp with this content:
<syntaxhighlight lang="cmake">
project (tutorial1)
find_package(KDE4 REQUIRED)
include (KDE4Defaults)
include_directories(${KDE4_INCLUDES})
set(tutorial1_SRCS main.cpp)
kde4_add_executable(tutorial1 ${tutorial1_SRCS})
target_link_libraries(tutorial1 ${KDE4_KDEUI_LIBS})
install(TARGETS tutorial1 ${INSTALL_TARGETS_DEFAULT_ARGS})
</syntaxhighlight>
The <tt>find_package()</tt> function locates the package that you ask it for (in this case KDE4) and sets some variables describing the location of the package's headers and libraries. In this case we will use the <tt>KDE4_INCLUDES</tt> variable which contains the path to the KDE4 header files.

In order to allow the compiler to find these files, we pass that variable to the <tt>include_directories()</tt> function which adds the KDE4 headers to the header search path.

Next we create a variable called <tt>tutorial1_SRCS</tt> using the <tt>set()</tt> function. In this case we simply set it to the name of our only source file.

Then we use <tt>kde4_add_executable()</tt> to create an executable called <tt>tutorial1</tt> from the source files listed in our <tt>tutorial1_SRCS</tt> variable. Afterwards, we link our executable to the KDE4 kdeui library using <tt>target_link_libraries()</tt> and the <tt>KDE4_KDEUI_LIBS</tt> variable which was set by the <tt>find_package()</tt> function. The line starting with <tt>install</tt> writes a default "install" target into the Makefile.

=== Make And Run ===
You can invoke CMake and make manually:

mkdir build && cd build
cmake .. # Note the two dots - this is no ellipsis, but "parent directory".
make

Or, if you set up your environment as described in [[Getting_Started/Build/Environment|Getting Started/Build/Environemnt]], you can compile this code with:
cmakekde

And launch it with:
./tutorial1

==Moving On==
Now you can move on to [[Development/Tutorials/Using_KXmlGuiWindow|using KXmlGuiWindow]].

[[Category:C++]]

Schedules/Extragear

2011-06-30T11:39:22Z

Icwiener: Fix repo link.

This page is intended to be a central location for Extragear projects to keep users and contributors (translators, packagers, etc.) informed about upcoming releases in a very accessible way.

 

{| border="1"
|-
! Project
! Next release (roughly)
! Next Release Code branch
! Next Release Translation branch
! Comments
|-
| [http://amarok.kde.org Amarok]
| 1 March 2010
| git master
| git master
| string freeze starting 9 February 2010
|-
| [http://digikam.org digiKam]
| July 24th 2011 [http://www.digikam.org/drupal/about/releaseplan]
| [https://projects.kde.org/projects/extragear/graphics git master]
| [http://websvn.kde.org/trunk/l10n-kde4/templates/messages/extragear-graphics/ trunk kde4]
| String freeze starting June 30th.
|-
| K3b
| 1 March 2010
| [http://websvn.kde.org/trunk/extragear/multimedia/k3b/ trunk]
| [http://websvn.kde.org/trunk/l10n-kde4/templates/messages/extragear-multimedia/ trunk kde4]
| String freeze starting from January 31 2010 (in effect)
|-
| KAudiocreator
|
|
|
|
|-
| Kaffeine
|
|
|
|
|-
| [http://extragear.kde.org/apps/kcoloredit/ KColorEdit]
| KDE release
| [http://websvn.kde.org/trunk/extragear/graphics/kcoloredit/ trunk]
| [http://websvn.kde.org/trunk/l10n-kde4/templates/messages/extragear-graphics/ trunk kde4]
|
|-
| [http://www.kde-apps.org/content/show.php/KDE+Partition+Manager?content=89595 KDE Partition Manager]
| Q2/2010
| [http://websvn.kde.org/trunk/extragear/sysadmin/partitionmanager/ trunk]
| [http://websvn.kde.org/trunk/l10n-kde4/templates/messages/extragear-sysadmin/ trunk kde4]
| 
|
|-
| [http://ww.kdevelop.org KDevelop]
| 1 May 2010
| [http://websvn.kde.org/trunk/extragear/sdk/kdevelop/ trunk]
| [http://websvn.kde.org/trunk/l10n-kde4/templates/messages/extragear-sdk/ trunk kde4]
| string freeze starting 31 March 2010
|-
| KDiff3
| January 31, 2009
| [http://websvn.kde.org/trunk/extragear/utils/kdiff3/ trunk]
| [http://websvn.kde.org/trunk/l10n-kde4/templates/messages/extragear-utils/ trunk kde4]
|
|-
| KFax
| KDE release
|
|
|
|-
| KFTPGrabber
|
|
|
|
|-
| KGrab
| KDE release
|
|
|
|-
| [http://extragear.kde.org/apps/kgraphviewer/ KGraphViewer]
| KDE release
| [http://websvn.kde.org/trunk/extragear/graphics/kgraphviewer/ trunk]
| [http://websvn.kde.org/trunk/l10n-kde4/templates/messages/extragear-graphics/ trunk kde4]
|
|-
| KIconedit
| KDE release
|
|
|
|-
| [http://www.kmldonkey.org KMLDonkey]
| KDE release
| [http://websvn.kde.org/trunk/extragear/network/kmldonkey/ trunk]
| [http://websvn.kde.org/trunk/l10n-kde4/templates/messages/extragear-network/ trunk kde4]
|
|-
| KNemo
| January 17, 2010
| [http://websvn.kde.org/trunk/extragear/network/knemo/ trunk]
| [http://websvn.kde.org/trunk/l10n-kde4/templates/messages/extragear-network/ trunk kde4]
| String freeze in effect
|
|-
| [http://konversation.kde.org Konversation]
| In the week beginning June 7th 2010
| [http://gitorious.org/konversation/konversation/trees/master git master]
| [http://websvn.kde.org/trunk/l10n-kde4/templates/messages/extragear-network/ trunk kde4]
|
|-
| KPager
|
|
|
|
|-
| KPhotoalbum
| May 9 2009
| trunk
| trunk
| Message freeze, April 3 2009
|-
| KPlayer
|
|
|
|
|-
| KPovmodeler
| KDE release
|
|
|
|-
| KRecipes
|
|
|
|
|-
| KSig
|
|
|
|
|-
| [http://ktorrent.org/ KTorrent]
| 8 november 2009
| [http://websvn.kde.org/branches/stable/extragear-kde4/network/ktorrent stable kde4]
| [http://websvn.kde.org/branches/stable/l10n-kde4/templates/messages/extragear-network/ stable kde4]
| String freeze in effect
|-
| Kuickshow
|
|
|
|
|-
| KWlan
|
|
|
|
|-
| RSIBreak
|
|
|
|
|-
| Skanlite
| KDE release
| trunk
|
|
|-
| [http://skrooge.org Skrooge]
| 2010-02-06 (version 0.6.0)
| [http://websvn.kde.org/trunk/extragear/office/skrooge trunk]
| [http://websvn.kde.org/trunk/l10n-kde4/templates/messages/extragear-office/ trunk kde4]
| String freeze in effect
|-
| [http://tellico-project.org Tellico]
|
| [http://websvn.kde.org/trunk/extragear/office/tellico/ trunk]
| [http://websvn.kde.org/trunk/l10n-kde4/templates/messages/extragear-office/ trunk kde4]
|
|-
| [http://www.kde-apps.org/content/show.php?content=29153 Yakuake]
| July 8th, 2010
| [http://websvn.kde.org/trunk/extragear/utils/yakuake/ trunk]
| [http://websvn.kde.org/trunk/l10n-kde4/templates/messages/extragear-utils/ trunk kde4]
| String freeze started June 24th, 2010
|-
| [http://www.rekonq.sourceforge.net rekonq]
| 30 June, 2010 (Version 0.5)
| [http://gitorious.org/rekonq/mainline/trees/master git master]
| [http://gitorious.org/rekonq/mainline/trees/master git master]
| String freeze starting 8 June 2010 (0.5 beta2 release)
|-
| Kile
| June 8th, 2011 (Version 2.1)
|
|
| String freeze started 23 May 2011
|-
| [http://www.krusader.org/ Krusader]
| 2.4.0-beta1 released on June 26, 2011.
| [http://websvn.kde.org/trunk/extragear/utils/krusader/ trunk]
| [http://websvn.kde.org/trunk/l10n-kde4/templates/messages/extragear-utils/ trunk kde4]
| String freeze since June 26, 2011 until 2.4.0 release.
|-
| BlueDevil
| 1.0.5 (stable) and 1.1.1 (trunk) released planned on July 15, 2011.
|
| stable, trunk
| String freeze since June 29, 2011 until 1.0.5 and 1.1.1 releases.
|}

Schedules/Extragear

2011-06-30T11:36:51Z

Icwiener: Add Digicam plan for 2.0.0.

This page is intended to be a central location for Extragear projects to keep users and contributors (translators, packagers, etc.) informed about upcoming releases in a very accessible way.

 

{| border="1"
|-
! Project
! Next release (roughly)
! Next Release Code branch
! Next Release Translation branch
! Comments
|-
| [http://amarok.kde.org Amarok]
| 1 March 2010
| git master
| git master
| string freeze starting 9 February 2010
|-
| [http://digikam.org digiKam]
| July 24th 2011 [http://www.digikam.org/drupal/about/releaseplan]
| [http://websvn.kde.org/trunk/extragear/graphics trunk]
| [http://websvn.kde.org/trunk/l10n-kde4/templates/messages/extragear-graphics/ trunk kde4]
| String freeze starting June 30th.
|-
| K3b
| 1 March 2010
| [http://websvn.kde.org/trunk/extragear/multimedia/k3b/ trunk]
| [http://websvn.kde.org/trunk/l10n-kde4/templates/messages/extragear-multimedia/ trunk kde4]
| String freeze starting from January 31 2010 (in effect)
|-
| KAudiocreator
|
|
|
|
|-
| Kaffeine
|
|
|
|
|-
| [http://extragear.kde.org/apps/kcoloredit/ KColorEdit]
| KDE release
| [http://websvn.kde.org/trunk/extragear/graphics/kcoloredit/ trunk]
| [http://websvn.kde.org/trunk/l10n-kde4/templates/messages/extragear-graphics/ trunk kde4]
|
|-
| [http://www.kde-apps.org/content/show.php/KDE+Partition+Manager?content=89595 KDE Partition Manager]
| Q2/2010
| [http://websvn.kde.org/trunk/extragear/sysadmin/partitionmanager/ trunk]
| [http://websvn.kde.org/trunk/l10n-kde4/templates/messages/extragear-sysadmin/ trunk kde4]
| 
|
|-
| [http://ww.kdevelop.org KDevelop]
| 1 May 2010
| [http://websvn.kde.org/trunk/extragear/sdk/kdevelop/ trunk]
| [http://websvn.kde.org/trunk/l10n-kde4/templates/messages/extragear-sdk/ trunk kde4]
| string freeze starting 31 March 2010
|-
| KDiff3
| January 31, 2009
| [http://websvn.kde.org/trunk/extragear/utils/kdiff3/ trunk]
| [http://websvn.kde.org/trunk/l10n-kde4/templates/messages/extragear-utils/ trunk kde4]
|
|-
| KFax
| KDE release
|
|
|
|-
| KFTPGrabber
|
|
|
|
|-
| KGrab
| KDE release
|
|
|
|-
| [http://extragear.kde.org/apps/kgraphviewer/ KGraphViewer]
| KDE release
| [http://websvn.kde.org/trunk/extragear/graphics/kgraphviewer/ trunk]
| [http://websvn.kde.org/trunk/l10n-kde4/templates/messages/extragear-graphics/ trunk kde4]
|
|-
| KIconedit
| KDE release
|
|
|
|-
| [http://www.kmldonkey.org KMLDonkey]
| KDE release
| [http://websvn.kde.org/trunk/extragear/network/kmldonkey/ trunk]
| [http://websvn.kde.org/trunk/l10n-kde4/templates/messages/extragear-network/ trunk kde4]
|
|-
| KNemo
| January 17, 2010
| [http://websvn.kde.org/trunk/extragear/network/knemo/ trunk]
| [http://websvn.kde.org/trunk/l10n-kde4/templates/messages/extragear-network/ trunk kde4]
| String freeze in effect
|
|-
| [http://konversation.kde.org Konversation]
| In the week beginning June 7th 2010
| [http://gitorious.org/konversation/konversation/trees/master git master]
| [http://websvn.kde.org/trunk/l10n-kde4/templates/messages/extragear-network/ trunk kde4]
|
|-
| KPager
|
|
|
|
|-
| KPhotoalbum
| May 9 2009
| trunk
| trunk
| Message freeze, April 3 2009
|-
| KPlayer
|
|
|
|
|-
| KPovmodeler
| KDE release
|
|
|
|-
| KRecipes
|
|
|
|
|-
| KSig
|
|
|
|
|-
| [http://ktorrent.org/ KTorrent]
| 8 november 2009
| [http://websvn.kde.org/branches/stable/extragear-kde4/network/ktorrent stable kde4]
| [http://websvn.kde.org/branches/stable/l10n-kde4/templates/messages/extragear-network/ stable kde4]
| String freeze in effect
|-
| Kuickshow
|
|
|
|
|-
| KWlan
|
|
|
|
|-
| RSIBreak
|
|
|
|
|-
| Skanlite
| KDE release
| trunk
|
|
|-
| [http://skrooge.org Skrooge]
| 2010-02-06 (version 0.6.0)
| [http://websvn.kde.org/trunk/extragear/office/skrooge trunk]
| [http://websvn.kde.org/trunk/l10n-kde4/templates/messages/extragear-office/ trunk kde4]
| String freeze in effect
|-
| [http://tellico-project.org Tellico]
|
| [http://websvn.kde.org/trunk/extragear/office/tellico/ trunk]
| [http://websvn.kde.org/trunk/l10n-kde4/templates/messages/extragear-office/ trunk kde4]
|
|-
| [http://www.kde-apps.org/content/show.php?content=29153 Yakuake]
| July 8th, 2010
| [http://websvn.kde.org/trunk/extragear/utils/yakuake/ trunk]
| [http://websvn.kde.org/trunk/l10n-kde4/templates/messages/extragear-utils/ trunk kde4]
| String freeze started June 24th, 2010
|-
| [http://www.rekonq.sourceforge.net rekonq]
| 30 June, 2010 (Version 0.5)
| [http://gitorious.org/rekonq/mainline/trees/master git master]
| [http://gitorious.org/rekonq/mainline/trees/master git master]
| String freeze starting 8 June 2010 (0.5 beta2 release)
|-
| Kile
| June 8th, 2011 (Version 2.1)
|
|
| String freeze started 23 May 2011
|-
| [http://www.krusader.org/ Krusader]
| 2.4.0-beta1 released on June 26, 2011.
| [http://websvn.kde.org/trunk/extragear/utils/krusader/ trunk]
| [http://websvn.kde.org/trunk/l10n-kde4/templates/messages/extragear-utils/ trunk kde4]
| String freeze since June 26, 2011 until 2.4.0 release.
|-
| BlueDevil
| 1.0.5 (stable) and 1.1.1 (trunk) released planned on July 15, 2011.
|
| stable, trunk
| String freeze since June 29, 2011 until 1.0.5 and 1.1.1 releases.
|}

Development/Tutorials/Decibel/Handling TextChannels

2011-06-30T11:33:46Z

Icwiener: Text replace - "<syntaxhighlight lang="bash"" to "<syntaxhighlight lang="cmake""

{{TutorialBrowser|

series=Decibel Tutorial|

name=Handling TextChannels|

pre=[http://mindview.net/Books/TICPP/ThinkingInCPP2e.html C++], [http://www.trolltech.com/products/qt/ Qt], [[Development/Tutorials/Decibel/GettingStarted|Getting Started with Decibel]]|
next=|

reading=[[Development/Tutorials/CMake|CMake]]
}}
==Abstract==
This tutorial will walk you through the process of creating a simple application that uses Decibel's TextChannels to communicate via arbitrary instant messaging networks using telepathy. From the result of this tutorial, only a few more lines of code are needed to produce a functioning text based instant messaging client.

This tutorial is based on the simpleclient demo included with Decibel. An explanation of using the simpleclient demo can be [[Development/Tutorials/Decibel/GettingStarted#simpleclient|found here]].

In this tutorial, we only pick out the important parts of the source code to discuss. The complete working source code for this example can be found [http://websvn.kde.org/trunk/kdesupport/decibel/demos/simpleclient here in KDE's SVN Repository].

==ChannelHandler class==
The first class we will need to create is an implementation of the <tt>Decibel::ChannelHandler</tt> interface.

===The Class Definition===
Here is the class definition for our implementation of the <tt>Decibel::ChannelHandler</tt> interface. It is explained below.

<syntaxhighlight lang="cpp-qt">
class MyTextChannelHandler : public Decibel::ChannelHandler
{
Q_OBJECT

public:
explicit MyTextChannelHandler(QObject * parent = 0);
~MyTextChannelHandler();

bool handleChannel(QtTapioca::Connection *, QtTapioca::Channel *, const bool);

public slots:
void onMessageReceived();
void onCloseChannel();

private:
QtTapioca::Connection * m_connection;
QtTapioca::TextChannel * m_channel;
};
</syntaxhighlight>

We must inherit from <tt>Decibel::ChannelHandler</tt> which is the interface definition for handling incoming Channels. We reimplement the constructor, Destructor and the <tt>handleChannel()</tt> method as well as adding two slots of our own. We also create the member variables <tt>m_connecion</tt> and <tt>m_channel</tt> which will hold the <tt>QtTapioca::Connection</tt> and <tt>QtTapioca::Channel</tt> objects that are received by the <tt>handleChannel</tt> method.

===The Class Implementation===

Now that we have defined our <tt>Decibel::ChannelHandler</tt> subclass, we need to implement its methods.

====Constructor====
<syntaxhighlight lang="cpp-qt">
MyTextChannelHandler::MyTextChannelHandler(QObject * parent) :
ChannelHandler(parent),
m_connection(0),
m_channel(0)
{ }
</syntaxhighlight>
The constructor is very simple. We just pass the <tt>parent</tt> object on to the parent class and initialise our member variables to <tt>0</tt>.

====Destructor====
<syntaxhighlight lang="cpp-qt">
MyTextChannelHandler::~MyTextChannelHandler()
{ }
</syntaxhighlight>
The destructor is even simpler. We don't need to do anything in it because Qt will handle the deletion of child objects automatically.

====handleChannel()====
<syntaxhighlight lang="cpp-qt">
bool MyTextChannelHandler::handleChannel(QtTapioca::Connection * connection,
QtTapioca::Channel * channel,
const bool)
{
Q_ASSERT(connection != 0);
Q_ASSERT(channel != 0);

if (m_connection != 0) { return false; }

m_channel = dynamic_cast<QtTapioca::TextChannel*>(channel);
if (m_channel == 0)
{
return false;
}
m_connection = connection;

connect(m_channel, SIGNAL(messageReceived(const QtTapioca::TextChannel *, const QtTapioca::TextChannel::Message &)),
this, SLOT(onMessageReceived()));
connect(m_channel, SIGNAL(closed()), this, SLOT(onCloseChannel()));

onMessageReceived();

return true;
}
</syntaxhighlight>
This method is reimplemented from the <tt>Decibel::ChannelHandler</tt> interface. It is called when ever a new incoming communication channel (<tt>QtTapioca::Channel</tt>) comes into existence. In this method, we must decide whether to accept the incoming channel, and if so, to deal with it appropriately.

First we check the incoming channel and connection objects are not invalid (=0) and we fail if this is the case. In a proper application, these error cases should be handled more gracefully, but for the purpose of this demo, we will just use <tt>Q_ASSERT()</tt> to handle them.

Next we check if the <tt>m_connection</tt> member variable is set to 0. If it is not, then we are already handling a channel. This demo can only handle one channel at a time, so we return <tt>false</tt> to reject the new incoming channel.

There are multiple types of channel we could possible receive. In this demo we are only interested in the <tt>TextChannel</tt> type. So the next step is to try and cast it to a <tt>QtTapioca::TextChannel</tt> object. We then evaluate if this cast was successful (not = 0) and if it was not, we again return <tt>false</tt> to reject the channel. If the cast is successful, we assign the <tt>QtTapioca::TextChannel</tt> object to the member variable <tt>m_channel</tt> to store it.

Now that we are sure the incoming channel is one we want to handle, we assign the incoming connection object to a member variable <tt>m_connection</tt> as well.

We are also ready to connect the channel's signals to the slots in our class. We connect the channel's <tt>messageReceived()</tt> signal to our <tt>onMessageReceived()</tt> slot, and the channel's <tt>closed()</tt> signal to our <tt>onCloseChannel()</tt> slot.

Finally, we call the <tt>onMessageReceived()</tt> slot to process any messages that have already arrived on the channel, before returning <tt>true</tt> to tell Decibel that we have accepted the channel and are handling it.

====onCloseChannel()====
<syntaxhighlight lang="cpp-qt">
void MyTextChannelHandler::onCloseChannel()
{
m_connection = 0;
m_channel = 0;
}
</syntaxhighlight>
This slot is called when the current TextChannel is closed. It resets the <tt>m_connection</tt> and <tt>m_channel</tt> member variables to <tt>0</tt> so that the <tt>handleChannel()</tt> method will accept the next incoming channel.

====onMessageReceived()====
<syntaxhighlight lang="cpp-qt">
void MyTextChannelHandler::onMessageReceived()
{
QList<QtTapioca::TextChannel::Message> message_list = m_channel->pendingMessages();

for (QList<QtTapioca::TextChannel::Message>::const_iterator
message = message_list.constBegin();
message != message_list.constEnd(); ++message)
{
if (message->type() == QtTapioca::TextChannel::Message::Normal &&
message->contents() == QString("ping?"))
{ m_channel->sendMessage(QString("pong!")); }

m_channel->acknowledge(*message);
}
}
</syntaxhighlight>
This slot is called when a new message is received on the channel we are currently handling. It is where the processing of the message takes place.

The first thing we do is to call the <tt>pendingMessages()</tt> method of the channel to receive *all* the unprocessed received messages on that channel.

Next we iterate over the list of these messages. For each message in the list, we check that it is a message of type <tt>Normal</tt>, as oposed to another type like <tt>Avatar</tt> or <tt>Emoticon</tt> which we are not interested in for this tutorial.

If it is a normal type of message, we check its contents, and if they are the string <tt>ping?</tt>, we reply with the string <tt>pong!</tt>.

We then call the <tt>acknowledge()</tt> method on the channel to confirm to the sender that we received the message.

==The main() function==

<syntaxhighlight lang="cpp-qt">
int main(int argc, char ** argv)
{
QCoreApplication app(argc, argv);
app.setOrganizationName(Decibel::organisation_name);
app.setApplicationName("SimpleClient");

MyTextChannelHandler thandler(&app);

Decibel::registerTypes();

QDBusConnection::sessionBus().registerService(Decibel::organisation_name + '.' + "SimpleClient");
QDBusConnection::sessionBus().registerObject("/TextChannelHandler", thandler);

return app.exec();
}
</syntaxhighlight>
Since this is a console application, we set up a <tt>QCoreApplication</tt> first.

Then we create an instance of the <tt>MyTextChannelHandler</tt> (which is our implementation of the <tt>Decibel::ChannelHandler</tt> interface).

Before registering any of the DBus interfaces for our app, it is necessary to call <tt>Decibe::registerTypes()</tt> to set up the types used by Decibel.

Next we register our application as a DBus service, and a <tt>TextChannelHandler</tt> so that decibel can communicate with it and can pass incoming TextChannels to it.

Finally, we start the application event-loop.

==The .component File==
Since we want Decibel to pass incoming channels to our application, we need to tell it that our program exists. We do this by creating a <tt>.component</tt> file. A component file is a simple <tt>.ini</tt>/<tt>.desktop</tt> style file.

The contents of our demo application's <tt>.component</tt> file are as follows.
<syntaxhighlight lang="ini">
[Component]
Name=Simpleclient
Protocols=
Types=0
Targets=
Service%20Name=org.kde.SimpleClient
Object%20Path=/TextChannelHandler
</syntaxhighlight>

The only group in this file is the <tt><nowiki>[Component]</nowiki></tt> group. It contains a series of keys identifying our application to Decibel and detailing the funcionality it supports.

In this example, the important keys are the <tt>Service%20Name</tt> which tells Decibel the dbus name of our application, and the <tt>Object%20Path</tt> which tells Decibel the dbus object path that should be called on our application.

==The .service File==
In order to have dbus automatically start our application when Decibel tries to communicate with it, we must create a <tt>.service</tt> file.

<syntaxhighlight lang="ini">
[D-BUS Service]
Name=org.kde.SimpleClient
Exec=@INSTALL_DIR@/decibel_simpleclient_demo
</syntaxhighlight>
This is a standard dbus autostart file. It contains the dbus name of our application and the absolute path to it. <tt>@INSTALL_DIR</tt> will be replaced automatically by the installation directory using cmake in the next step.

==CMakeLists.txt==
Since this example program is built as part of the main Decibel sources, I will not explain here how to create a standalone <tt>CMakeLists.txt</tt> file to build it, but will instead explain the important parts of the <tt>CMakeLists.txt</tt> file as found in the Decibel sources for this subdirectory. For more information on how <tt>CMakeLists.txt</tt> files work, please see the [[Development/Tutorials/CMake|Introduction to cmake]] tutorial.
<syntaxhighlight lang="cmake">
SET(QT_DONT_USE_QTGUI "YES")
INCLUDE(${QT_USE_FILE})

SET(SERVICE_FILE "org.kde.SimpleClient.service")

INCLUDE_DIRECTORIES(${CMAKE_SOURCE_DIR}/include
${CMAKE_BINARY_DIR}/src/client
${CMAKE_SOURCE_DIR}/src/client
${QT_QTCORE_INCLUDE_DIR}
${TELEPATHY_QT_INCLUDE_DIR}
${TAPIOCA_QT_INCLUDE_DIR}
${CMAKE_CURRENT_BINARY_DIR}
${CMAKE_CURRENT_SOURCE_DIR}
)

CONFIGURE_FILE("${CMAKE_CURRENT_SOURCE_DIR}/${SERVICE_FILE}.cmake"
"${CMAKE_CURRENT_BINARY_DIR}/${SERVICE_FILE}"
)
</syntaxhighlight>

The <tt>CONFIGURE_FILE</tt> line above tells cmake tp fill in the variable to the <tt>.service.cmake</tt> file we previously created.

<syntaxhighlight lang="cpp">
# ######### simpleclient demo #########

SET(simpleclient_SRCS
simpleclient.cpp
mytextchannelhandler.cpp
)

SET(simpleclient_MOC_HDRS
mytextchannelhandler.h
)

QT4_WRAP_CPP(simpleclient_MOC_SRCS ${simpleclient_MOC_HDRS})

ADD_EXECUTABLE(decibel_simpleclient_demo ${simpleclient_SRCS}
${simpleclient_MOC_SRCS}
)
TARGET_LINK_LIBRARIES(decibel_simpleclient_demo
${QT_LIBRARIES}
${TAPIOCA_QT_LIBRARIES}
decibel
)

INSTALL(TARGETS decibel_simpleclient_demo DESTINATION ${DEMO_INSTALL_DIR})
INSTALL(FILES ${CMAKE_CURRENT_BINARY_DIR}/${SERVICE_FILE}
DESTINATION ${DBUS_SERVICES_INSTALL_DIR}
)
INSTALL(FILES org.kde.SimpleClient.TextChannel.component
DESTINATION ${COMPONENT_SEARCH_DIR}
)
</syntaxhighlight>

==Running our Application==
In this tutorial, we have only looked at the important parts of the code of this application. The easiest way to build a working example from this tutorial is to check out the Decibel source code from the KDE SVN repository. The <tt>simpleclient</tt> demo which this tutorial explains will be built and installed automatically along with the rest of Decibel.

To see it working, you need to register an account with Decibel and bring it online. For information on how to do this, please see [[Development/Tutorials/Decibel/GettingStarted|Getting Started with Decibel]]. Then you should use another instant messaging program to send the message <tt>ping?</tt> to that account. The <tt>simpleclient</tt> demo will reply with the message <tt>pong!</tt>.

KDE System Administration/PlasmaDesktopScripting

2011-06-30T11:32:52Z

Icwiener: Fix syntax highlighting.

== ECMA Script Interaction With Plasma Shells ==

It is possible to control and interact with a Plasma user interface shell such as a plasma-desktop or (starting in KDE SC 4.5) plasma-netbook session using ECMA Script (aka JavaScript). This scripting mechanism exposes containments (Desktop Activities and Panels), widgets and various other aspects of plasma-desktop configuration using the widely known and used ECMA Script language. The QtScript engine is used for the runtime environment.

This document describes the API that is provided along with how to
run such scripts in plasma-desktop.

== Examples ==

A set of examples can be found [https://projects.kde.org/projects/kde/kdeexamples/repository/revisions/master/show/plasma/javascript/plasma-shell-scripting here] that demonstrate the use of various aspects of Plasma shell scripting.

Contributions of additional examples are welcome and an be sent to the Plasma development mailing list (plasma-devel at kde.org) for inclusion if you do not have commit rights to the kdeexamples module.

== Running Scripts ==
There are three ways that scripts can be executed in plasma-desktop:

* '''on first run''': when plasma-desktop is started without any pre-existing configuration, any scripts in $APPDATA/plasma-desktop/init/ with a ".js" suffix are run. If there is more than one script, they are run sequentially in the alphabetical order of the file names.

{{note|For security reasons, scripts located in the user's home directory will '''not''' be run during this phase.}}

* '''on update''': when plasma-desktop is started, it will check in
<syntaxhighlight lang="bash">
`kde4-config --path data`/plasma-desktop/updates/
</syntaxhighlight>
with a ".js" suffix for scripts that have not yet been run. If there is more than one script which has not been run yet they will be executed serially in the alphabetical order of the file names.

A record of which update scripts have been run is kept in the application's config file in the [Updates] group. This means that if the plasma-desktop configuraiton file is removed, all the update scripts will be run again.

{{note|For security reasons, scripts located in the user's home directory will '''not''' be run during this phase.}}

* '''interactively''': an interactive scripting dialog can be requested either via the KRunner window (Alt+F2, by default, or via the "Run Command" entry in various desktop menus) by entering "desktop console" as the search term. It can also be triggered directly via dbus with <syntaxhighlight lang="bash">qdbus org.kde.plasma-desktop /MainApplication showInteractiveConsole</syntaxhighlight>

{{note|This method is not available for plasma-netbook.}}

:ECMA Script may be entered directly into this window for execution and output appears in the lower half of the window. Ctrl+E is a shortcut to run scripts, and scripts can be saved to and loaded from disk.

:Scripts from files can also be loaded using KRunner with "desktop console /path/to/file" or via dbus with
<syntaxhighlight lang="bash">qdbus org.kde.plasma-desktop /MainApplication loadScriptInInteractiveConsole /path/to/file</syntaxhighlight>

== Templates ==

Templates are named packages that contain scripts. This provides a way for common functionality to be easily reused, helping to increase consistency and lower maintenance costs. Templates can be loaded from other scripts by name and they are also used to populate some parts of the user interface, such as the entries in the Add Panels menu.

A template is a small set of files in a specified file hierarchy (or, in Plasma terms, a "Package"). In particular, a Template package contains the following files:

* metadata.desktop: a .desktop file describing the template
* contents/layout.js: a Javascript file containing the actual script

Templates are stored under share/apps/plasma/layout-templates and may be installed using `plasmapkg -t layout-template -i /path/to/package`. Template packages may also be provided as a .zip file with a .plasmalayout suffix.

The metadata.desktop file contains the usual .desktop entries such as Name and Icon but must also contain Type=Service and ServiceTypes=Plasma/LayoutTemplate entries. If the layout is specific to a given Plasma application, such as plasma-desktop, this can be specific using X-Plasma-Shell. X-Plasma-ContainmentCategories defines what kind of layout it is with possible values being panel and desktop. Finally a X-KDE-PluginInfo-Name entry is required to provide a globally unique internal name for the Template. Here is an example of a Template that provides a Panel layout for Plasma Netbook:

<syntaxhighlight lang="ini">
[Desktop Entry]
Encoding=UTF-8
Name=Cool Panel
Type=Service
ServiceTypes=Plasma/LayoutTemplate
X-Plasma-Shell=plasma-netbook
X-Plasma-ContainmentCategories=panel
X-KDE-PluginInfo-Author=Aaron Seigo
X-KDE-PluginInfo-Email=aseigo@kde.org
X-KDE-PluginInfo-Name=org.kde.CoolNetbookPanel
X-KDE-PluginInfo-Version=1.0
X-KDE-PluginInfo-Website=http://plasma.kde.org/
X-KDE-PluginInfo-Category=
X-KDE-PluginInfo-Depends=
X-KDE-PluginInfo-License=GPL
X-KDE-PluginInfo-EnabledByDefault=true
</syntaxhighlight>

When running a template, two global variables will be accessible in read-only mode: templateName and templateComment. They will contain the Name and Comment fields of the above desktop file, and are translated if a localization is available.

=== Examples of Usage ===

==== Creating panels ====
A good example of the use of templates is the use case that triggered the creation of this feature: the desire to make it easy for users to re-create the default panel that is created on first start. There is a Template called org.kde.plasma-desktop.defaultPanel that ships with the KDE Plasma Workspace which contains the layout for the initial default panel. This is referenced by the default Plasma Desktop init script and, because it is marked as a Panel Template in the metadata.desktop file it also shows up to the user in the Add Panels menu. When selected by the user from the menu, the exact same panel that is created on desktop start up is created for them, complete with Plasma Widgets and configuration.

==== Automating tasks ====
Another example of the usefulness of templates is the "Find Widgets" template. This template, which first shipped with Plasma Desktop v4.5, provides a function for finding widgets by name. It appears in the toolbar "Load" and "Use" menus in the Desktop Console in plasma-desktop, and makes finding widgets as simple as:

<syntaxhighlight lang="javascript">
var template = loadTemplate('org.kde.plasma-desktop.findWidgets')
template.findWidgets('systemtray')
</syntaxhighlight>

==== Activity templates ====
Probably the most user visible use of templates are "Activity templates". The structure of Activity templates is similar to the other use of templates, but a few extra features are provided in the metadata.desktop file. Here is an example of such an activity template:

<syntaxhighlight lang="ini">
[Desktop Entry]
Encoding=UTF-8
Name=Cool Activity Template
Icon=user-desktop
Type=Service
ServiceTypes=Plasma/LayoutTemplate
X-Plasma-Shell=plasma-desktop
X-Plasma-ContainmentCategories=desktop
X-Plasma-ContainmentLayout-ExecuteOnCreation=dolphin $desktop, gwenview $pictures
X-Plasma-ContainmentLayout-ShowAsExisting=true
X-KDE-PluginInfo-Author=John Doe
X-KDE-PluginInfo-Email=john@doe.org
X-KDE-PluginInfo-Name=org.kde.plasma-desktop.CoolTemplate
X-KDE-PluginInfo-Version=1.0
X-KDE-PluginInfo-Website=http://john.doe.org
X-KDE-PluginInfo-Category=
X-KDE-PluginInfo-Depends=
X-KDE-PluginInfo-License=GPL
X-KDE-PluginInfo-EnabledByDefault=true
</syntaxhighlight>

The layout itself is still created from the layout.js file as usual, but this template also shows as a precreated activity to the user thanks to the <tt>X-Plasma-ContainmentLayout-ShowAsExisting</tt> key. Additionally, it starts applications in the newly created activity using the <tt>X-Plasma-ContainmentLayout-ExecuteOnCreation</tt> key.

That key is a list of commands to execute, and it supports the following variables:
* $desktop
* $autostart
* $documents
* $music
* $video
* $downloads
* $pictures

They all expand into the path toward the user corresponding default folder.

== API ==

In addition to the normal ECMA Script API and the Qt-specific extensions (such as signal/slot support) provided by QtScript, the following API is provided for use by scripts.

All of the API below, unless otherwise noted with a version noticed, appear as below in the KDE Software Compilation v4.4.0 and later. API that is not noted as being part of a given class or object is part of the global namespace.

{{note|API compatibility is guaranteed from version to version starting with KDE Software Compilation v4.4.0.}}

=== Version Numbers ===

Starting with KDE SC 4.5, the version number of both the scripting API and the application is available to the script via the following read-only properties:

* ''String'' '''applicationVersion''': the version of the application, e.g. 0.3
* ''String'' '''platformVersion''': the version of the KDE Platform, e.g. 0.3
* ''number'' '''scriptingVersion''': the version of the scripting API; e.g. in KDE SC 4.5 this is 2

=== Activities ===
Activities are the desktop layer in a plasma-desktop session and may contain widgts. In sightly more technical terms, they are desktop containments. Activities can be created, enumerated, modified and destroyed.

New Activities can be created using the Activity constructor, like this:
<syntaxhighlight lang="javascript">
var activity = new Activity("folderview")
</syntaxhighlight>

The string passed into the constructor maps to the X-KDE-PluginInfo-Name= entry
in the plugin's .desktop file). See the documentation on the Containment object class below.

Read-only properties:
* ''Array[number]'' '''activityIds''': returns a list of integer ids of all existing Plasma activities
* ''Array[String]'' '''knownActivityTypes''': (scripting version >= 2) a list of types of activities that can be created. This is useful to check if an Activity type is available on the system before trying to construct one.

Functions:
* ''Activity'' '''activityById(number id)''': return an object representing the activity with the given id
* ''Activity'' '''activityForScreen(number screen[, number dekstop])''': returns an object representing the activity currently associated with the given screen and, optionally, the given desktop.
* ''Array[Activity]'' '''activities()''': returns an array of all activities that currently exist

=== Panels ===
Panels can be created, enumerated, modified and destroyed. A panel object combines both a containment as well as the container itself, allowing for full control of things such as where it appears on screen and the hiding features associated with them.

New Panels can be created using the Panel constructor, like this:
<syntaxhighlight lang="javascript">
var panel = new Panel("dock")
</syntaxhighlight>
The string passed into the constructor maps to the X-KDE-PluginInfo-Name= entry
in the plugin's .desktop file).

Read-only properties:
* ''Array[number]'' '''panelIds''': returns a list of integer ids of all existing Plasma panels
* ''Array[String]'' '''knownPanelTypes''': (scripting version >= 2) a list of types of panels that can be created. This is useful to check if a Panel type is available on the system before trying to construct one.

Functions:
* ''Panel'' '''panelById(int id)''': returns an object representing the Panel that matches the given id
* ''Array[Panels]'' '''panels()''': returns an array of all panels that currently exist

=== Activities and Panels ===
Activity and Panel objects, once created by the script, or as returned by activityById, activityForScreen,
or panelById) provide the following read-only properties:

* ''number'' '''id: the integer id of this activity
* ''String'' '''formFactor''': returns the form factor of the activity, e.g. "planar" for most desktop activities,"mediacenter" for media centers and either "horizontal" or "vertical" for panels.
* ''Array[number]'' '''widgetIds''': a list of integer ids of all the widgets in this Activity
* ''Array[String]'' '''configKeys''': (scriptingVersion >= 2) a list of all keys that are set in the current configuration group
* ''Array[String]'' '''configGroups''': (scriptingVersion >= 2) a list of all the groups in the current configuration group
* ''Array[String]'' '''globalConfigKeys''': (scriptingVersion >= 2) a list of all keys that are set in the current global configuration group
* ''Array[String]'' '''globalConfigGroups''': (scriptingVersion >= 2) a list of all the groups in the current global configuration group

as well as the following read/write properties:

* ''number'' '''desktop''': the virtual desktop this activity is associated with, or -1 for none
* ''number'' '''screen''': the screen this activity is associated with, or -1 for none
* ''String'' '''name''': the name of this activity
* ''String'' '''wallpaperPlugin''': (scriptingVersion >= 2) the wallpaper plugin to use with the Activity
* ''String'' '''wallpaperMode''': (scriptingVersion >= 2) the wallpaper plugin mode to use with the Activity
* ''Array[String]'' '''currentConfigGroup''': (scriptingVersion >= 2) the current configuration group path, with each entry in the array representing a sub-group. This allows one to access trees of groups with code such as: widget.currentConfigGroup = new Array('topGroup', 'subGroupOfTopGroup'). An empty Array means the default (top-level) configuration group for the widget
* ''String'' '''version''': (scriptingVersion >= 2) the version of the Activity or Panel

and the following methods:

* '''remove()''': deletes this activity and all widgets inside of it
* ''Widget'' '''widgetById(number id)''': returns an object representing the widget with the given id
* ''Widget'' '''addWidget(String name)''': adds a new widget to the activity; the name maps to the <tt>X-KDE-PluginInfo-Name=</tt> entry in the widget's .desktop file
* ''Widget'' '''addWidget(Widget widget)''': adds an existing widget to this activity; useful for moving widgets between Activities and Panels
* '''showConfigurationInteface()''': shows the configuration user interface for this Activity or Panel on the screen
* '''readConfig(String key, any default)''': (scriptingVersion >= 2) reads the value of key in the config with default for the default value
* '''writeConfig(String key, any value)''': (scriptingVersion >= 2) sets key to value in the config
* '''readGlobalConfig(String key, any default)''': (scriptingVersion >= 2) reads the value of key in the global config with default for the default value
* '''writeGlobalConfig(String key, any value)''': (scriptingVersion >= 2) sets key to value in the global config
* '''reloadConfig()''': (scriptingVersion >= 2) causes the Activity or Panel to reload its configuration; reaction to configuration changes made using readConfig are usually activated on script exit, but this can be triggered earlier on a per-widget basis using this method
* ''Array[String]'' '''currentGlobalConfigGroup''': (scriptingVersion >= 2) the current global configuration group path, with each entry in the array representing a sub-group, similar to currentConfigGroup. However, global configuration is shared by all instances of panels and activities of the same type.
* ''Array[Widget]'' '''widgets([String type])''': (scriptingVersion >= 2) returns all the widgets in the Panel or Activity. If the optional type is specified, only widgets matching that type will be returned.

In addition to all of the above properties and functions, Panel objects also provide the folowing read/write properties:
* ''number'' '''length''': the number of pixels along the screen edge used
* ''number'' '''height''': the height (or for vertical panels, the width) of the panel
* ''String'' '''hiding''': the hiding mode of the panel, one of "none" (for no hiding), "autohide", "windowscover" or "windowsbelow"
* ''String'' '''alignment''': right, left or center alignment of the panel (for vertical panels, right corrsponds to top and left to bottom)
* ''String'' '''location''': returns the location of the activity (only relevant for Panels); valid values include "top", "bottom", "left", "right" and "floating"

=== Widgets ===
Widgets may be enumerated by calling the widgetIds property on a Activity or Panel object. With a widget id in hand, a Widget object can be retrieved by calling widgetById(id) on an Activity or Panel object. New Widgets can be created with add addWidget(String) function provided by Activity and Panel objects.

A list of all installed widget types can be retrieved the following read-only property:

* ''Array[String]'' '''knownWidgetTypes''' (scripting version >= 2)

A Widget object provides the following read-only properties:

* ''number'' '''id''': the id of the widget
* ''String'' '''type''': the plugin type of this widget
* ''Array[String]'' '''configKeys''': a list of all keys that are set in the current configuration
* ''Array[String]'' '''configGroups''': a list of all the groups in the current configuration
* ''Array[String]'' '''globalConfigKeys''': (scriptingVersion >= 2) a list of all keys that are set in the current global configuration group
* ''Array[String]'' '''globalConfigGroups''': (scriptingVersion >= 2) a list of all the groups in the current global configuration group
* ''String'' '''version''': (scriptingVersion >= 2) the version of the Activity or Panel

as well as the following read-write properties:

* ''Array[String]'' '''currentConfigGroup''': the current configuration group path, with each entry in the array representing a sub-group. This allows one to access trees of groups with code such as: widget.currentConfigGroup = new Array('topGroup', 'subGroupOfTopGroup'). An empty Array means the default (top-level) configuration group for the widget
* ''Array[String]'' '''currentGlobalConfigGroup''': (scriptingVersion >= 2) the current global configuration group path, with each entry in the array representing a sub-group, similar to currentConfigGroup. However, global configuration is shared by all instances of widgets of the same type.
* ''QRectF'' '''geometry''': the geometry of the widget (settable)
* ''String'' '''globalShortcut''': the shortcut sequence (in the format used by QKeySequence, e.g. "Alt+F1") associated with this widget
* ''number'' '''index''': the layout index of the widget; in a Panel this corresponds to the order the widget appears in. Changing the value of the index will change the position of the widget in Panels and may do so in some Activities as well.

and the following methods:

* '''remove()''': deletes this widget
* '''readConfig(String key, any default)''': reads the value of key in the config with default for the default value
* '''writeConfig(String key, any value)''': sets key to value in the config
* '''readGlobalConfig(String key, any default)''': (scriptingVersion >= 2) reads the value of key in the global config with default for the default value
* '''writeGlobalConfig(String key, any value)''': (scriptingVersion >= 2) sets key to value in the global config
* '''reloadConfig()''': causes the widget to reload its configuration; reaction to configuration changes made using readConfig are usually activated on script exit, but this can be triggered earlier on a per-widget basis using this method
* '''showConfigurationInteface()''': shows the configuration user interface for this widget on the screen

=== Screen Geometry ===
Read-only properties:
* ''number'' '''screenCount''': returns the number of screens connected to the computer

Functions:
* ''QRectF'' '''screenGeometry(number screen)''': returns a rect object representing the geometry of a screen

=== Wallpaper Plugins ===

* ''Array[String => Array[String]]'' '''knownWallpaperPlugins()''': (scripting version >= 4) returns a list of all installed wallpaper plugins. They keys of the array are the wallpaper plugin names. The values are arrays containing the modes available for that wallpaper plugin. The mode array may be empty, as most wallpaper plugins only offer one mode.

=== Locating Applications and Paths ===
* ''boolean'' '''applicationExists(String name)''': (scripting version >= 4) searches $PATH first, then tries in the application menu system by application storage name (aka the .desktop file name), then Name= entries for apps with installed .desktop files, then GenericName= entries for same
* ''mixed'' '''defaultApplication(String kind [, boolean storageId = false])''': (scripting version >= 4) returns the executable (or if storageId is true, then the app menu system id, e.g. its .desktop file name) of the default app. The "kind" parameter may be a well-known application type including "browser", "mailer", "filemanager", "terminal", "imClient" and "windowmanager" (or any other entry in share/apps/kcm_componentchooser/kcm_*.desktop); it may also be a mimetype (e.g. "application/pdf"). On failure, it returns false.
* ''String'' '''applicationPath(String name)''': (scripting version >= 4) returns the full local path to a given application or .desktop file if it exists.
* ''String'' '''userDataPath([String type, String path])''': (scripting version >= 4) returns the default path for user data. Called with no parameters, it returns the user's home directory. If only one string is passed in, the standard directory for that type of data in the user's home directory will be located; the following values are recognized:
** documents
** music
** video
** downloads
** pictures
** autostart
** desktop (should be considered deprecated for Plasma workspaces)

If a second string is passed in, it is considered a request for a specific path and the following types are recognized:
** apps - Applications menu (.desktop files).
** autostart - Autostart directories (both XDG and kde-specific)
** cache - Cached information (e.g. favicons, web-pages)
** cgi - CGIs to run from kdehelp.
** config - Configuration files.
** data - Where applications store data.
** emoticons - Emoticons themes
** exe - Executables in $prefix/bin. findExe() for a function that takes $PATH into account.
** html - HTML documentation.
** icon - Icons, see KIconLoader.
** kcfg - KConfigXT config files.
** lib - Libraries.
** locale - Translation files for KLocale.
** mime - Mime types defined by KDE-specific .desktop files.
** module - Module (dynamically loaded library).
** qtplugins - Qt plugins (dynamically loaded objects for Qt)
** services - Services.
** servicetypes - Service types.
** sound - Application sounds.
** templates - Templates for the "Create new file" functionality.
** wallpaper - Wallpapers.
** tmp - Temporary files (specific for both current host and current user)
** socket - UNIX Sockets (specific for both current host and current user)
** xdgconf-menu - Freedesktop.org standard location for menu layout (.menu) files.
** xdgdata-apps - Freedesktop.org standard location for application desktop files.
** xdgdata-dirs - Freedesktop.org standard location for menu descriptions (.directory files).
** xdgdata-mime - Freedesktop.org standard location for MIME type definitions.
** xdgdata-icon - Freedesktop.org standard location for icons.
** xdgdata-pixmap - Gnome-compatibility location for pixmaps.

The second parameter should be a specific resource to find the path to. An example might be userDataPath("data", "plasma-desktop").

=== Misc. Global Properties and Functions ===
Read-write properties:
* ''boolean'' '''locked''': whether the desktop shell and widgets are locked or not (settable)
* ''string'' '''theme''': (scripting version >= 3) the name of the desktop theme to use for the interface, e.g. default, Air, Oxygen, etc.

Read-only properties:
* ''boolean'' '''hasBattery''': whether or not the system has the ability to run on battery power, e.g. a laptop or mobile device
* ''boolean'' '''multihead''': (scripting version >= 3) true if the system is running with multiple screens in a "Xaphod" multiple display server configuration
* ''int'' '''multiheadScreen''': (scripting version >= 3) if multihead is true, contains the (real) screen id of the current screen

Functions:
* '''sleep(number ms)''': sleeps the script for the specified number of millseconds

=== QRectF ===
A rectangle class is also provided for use with Widget, Panel and screen geometry properties and functions.

Read-only properites:
* ''boolean'' '''empty''': true if the rectangle's width or height is less than, or equal to, 0; an empty rectangle is also invalid
* ''boolean'' '''null''': true if the rectangle has both the width and the height set to 0; a null rectangle is also empty and not valid
* ''boolean'' '''valid''': true if the rectangle has a width > 0 and height 0.

Read-write properties:
* ''number'' '''left'''
* ''number'' '''top'''
* ''number'' '''bottom'''
* ''number'' '''right'''
* ''number'' '''height'''
* ''number'' '''width'''
* ''number'' '''x'''
* ''number'' '''y'''

Constructors:
* '''QRectF'''
* '''QRectF(number x, number y, number width, number height)''': Sets the coordinates of the rectangle's top-left corner to (x, y), and its size to the given width and height.

Functions:
* '''adjust(number dx1, number dy1, number dx2, number dy2)''': adds dx1, dy1, dx2 and dy2 respectively to the existing coordinates of the rectangle
* ''QRectF'' '''adjusted(number dx1, number dy1, number dx2, number dy2)''': returns a new QRectF with dx1, dy1, dx2 and dy2 added respectively to the existing coordinates of the rectangle
* '''translate(number dx, number dy)''': translates the rect by dx, dy
* '''setCoords(number x1, number y1, number x2, number y2)''': sets the coordinates of the rectangle's top-left corner to (x1, y1), and the coordinates of its bottom-right corner to (x2, y2).
* '''setRect(number x, number y, number width, number height)''': sets the coordinates of the rectangle's top-left corner to (x, y), and its size to the given width and height.
* ''boolean'' '''contains(number x, number y)''': returns true if the rect contains the point (x, y)
* '''moveBottom(number delta)'': moves the bottom by delta pixels
* '''moveLeft(number delta)''': moves the left by delta pixels
* '''moveRight(number delta)''': moves the right by delta pixels
* '''moveTo(number x, number y)''': moves the top left of the rect to point (x, y)
* '''moveTop(number delta)''': moves the top by delta pixels

== Configuration Keys ==
Here you find a list of commonly used configuration keys to use with the '''writeConfig''' command. Where the documentation notes that a key is in a subgroup, remember to first use '''currentConfigGroup'''.

=== Common configuration keys ===
Here are some keys that can be used with all widgets:

* '''Share''' (true/false): Whether or not the widget is to be announces throughout the network (Share tab)

=== Common time and date keys ===
Most of the settings listed below apply to all widgets dealing with date and time (clock, digital-clock, binary-clock, …)
Settings for individual plasmoids can be found in their respective category and usually only affect the plasmoid’s appearance.
* '''announceInterval''' (number ≥ 0): Interval in minutes that the time is read out loud
* '''calendarType''' (local/coptic/ethopian/gregorian/gregorian-proleptic/hebrew/hijri/indian-national/jalali/japanese/julian/minguo/thai): Calendar system to be used, defaults to local
* '''defaultTimezone''' (Local/…): Time zone to be used
* '''displayHolidays''' (true/false): Whether holidays are to be displayed
* '''holidayRegions''' (tbd): tbd
* '''holidayRegionaDaysOff''' (tbd): tbd
* '''timeZones''' (Europe/Andorra,…): Comma-separated list of timezones to be used (e. g. Europe/Andorra,Indian/Antananarivo,Asia/Aqtau)

=== Analog clock (clock) ===
* '''showSecondHand''' (true/false): self-explanatory
* '''showTimezoneString''' (true/false): self-explanatory

=== Battery status (battery) ===
* '''showBatteryString''' (true/false): Whether or not battery status is shown as overlay for the battery icon (if in systemtray or panel)
* '''showMultipleBatteries''' (true/false): Whether or not battery status is shown for each battery separately

=== Digital clock (digital-clock) ===
* '''plainClockColor''' (rrr,ggg,bbb): Color set for clock font (e. g. 192,0,0 - to be used with useCustomColor=true!)
* '''plainClockDrawShadow''' (true/false): Whether a shadow is to bed drawn (defaults to true)
* '''plainClockShadowColor''' (rrr,ggg,bbb): Color set for clock shadow (e. g. 64,97,128 - to be used with useCustomShadowColor=true!)
* '''plainClockFont''' (tbd): Font to be used for clock (e. g. Serif,12,-1,5,75,0,0,0,0,0)
* '''showDate''' (true/false): self-explanatory
* '''showDay''' (true/false): self-explanatory
* '''showSeconds''' (true/false): self-explanatory
* '''showTimezone''' (true/false): self-explanatory
* '''showYear''' (true/false): self-explanatory
* '''useCustomColor''' (true/false): Whether or not a custom color is to be used (use with plainClockColor=rrr,ggg,bbb!)
* '''useCustomShadowColor''' (true/false): Whether or not a custom shadow color is to be used (use with plainClockShadowColor=rrr,ggg,bbb!)

=== Folderview (folderview) ===
* '''alignToGrid''' (true/false): self-explanatory
* '''customIconSize''' (16/22/24/32/48/…): Use custom icon size for files/folders (use only default/common icon sizes, powers of 2)
* '''customLabel''': Use custom title rather than default path or place name
* '''drawShadows''' (true/false): Whether or not file labels are to draw shadows
* '''filter''' (0/1/2): Defines whether a filter is to be used or not (0 = No filter, 1 = Show only matching files, 2 = Hide matching files)
* '''filterFiles''': Wildcard filter to filter file names
* '''mimeFilter''': Comma-separated list of mimetypes to be filtered (shown/hidden depends on filter-setting)
* '''iconsLocked''' (true/false): Whether or not icons can be moved
* '''numTextLines''' (number > 0): Amount of lines a file name can have before it is truncated
* '''url''': Folder URL to be displayed (e. g. desktop:/// or file:///home/yourusername)
* '''sortColumn''' (-1/0/1/2/3/4/5): The way files and folders are sorted (-1 = No sorting, 0 = By name, 1 = By size, 2 = By type, 3 = By date)
* '''sortDirsFirst''' (true/false): Whether or not folders are displayed before files (defaults to true)
* '''textColor''' (rrr,ggg,bbb): Color the icon labels will have

=== Kickoff menu (launcher) ===
* '''SwitchTabsOnHover''' (true/false): self-explanatory
* '''ShowAppsByName''' (true/false): Apps are sorted by name rather than by description

=== Pager (pager) ===
* '''displayedText''' (0/1/2): Text to be shown on individual virtual desktops (0 = Workspace number, 1 = Workspace title, 2 = None)
* '''ShowWindowIcons''' (true/false): Whether or not the application icon is to be shown on each individual window
* '''currentDesktopSelected''' (0/1/2): Defines what should happen if the user clicks on the virtual desktop that is currently active (0 = Nothing, 1 = Show Workspace, i. e. minimize windows, 2 = Show Dashboard)
* '''rows''' (number > 0): Amount of rows the pager should have. (Note: ''This is a global option, so you need to use '''writeGlobalConfig''' instead'')

=== Notifications (notifications) ===
{{note|This applet is likely to be embedded to system tray. For Systrem Tray specific tasks, i. e. how to add, manage and remove plasmoids inside it, see sections below}}
* '''AutoHidePopup''' (true/false): Whether or not popups are to be hidden automatiaclly
* '''ShowJobs''' (true/false): Whether or not jobs are to be shown (e. g. file transfer progress)
* '''ShowNotifications''' (true/false): Whether or not notifications are to be shown

=== Removable media notifier (notifier) ===
* '''ShowDevices''' (0/1/2): Defines what kind of devices are to be shown (0 = Removable media only, 1 = Non-removable media only, 2 = All)
{{note|Auto-mount settings and device actions are not stored in this Plasmoid’s settings.}}

=== Taskbar (tasks) ===
* '''groupingStrategy''' (0/1/2): Defines how taskbar entries are to be grouped (0 = Never, 1 = Manually, 2 = By Program Name)
* '''groupWhenFull''' (true/false): Only group when taskbar is full (to be used with groupingStrategy=2 only!)
* '''highlightWindows''' (true/false): Highlight a window if your mouse cursor is hovering its taskbar entry (requires Desktop Compositing and “Highlight windows” effect enabled to work)
* '''maxRows''' (number > 0): Amount of rows taskbar entries can take
* '''forceRows''' (true/false): Force row setting for taskbar entries
* '''showOnlyCurrentActivity''' (true/false): Show only windows from current activity
* '''showOnlyCurrentDesktop''' (true/false): Show only windows from current virtual desktop
* '''showOnlyCurrentScreen''' (true/false): Show only windows from current screen (multi monitor setup)
* '''showTooltip''' (true/false): Whether or not tooltips are to be shown
* '''sortingStrategy''' (0/1/2/3): How taskbar entries are to be sorted (0 = Never, 1 = Manually, 2 = Alphabetically, 3 = By Desktop)

=== System Tray ===
The System Tray has some unique behaviors since it can host widgets and configuring it is not as easy as most other widgets, particularly when adding and removing widgets. This section will help you deal with its specific behavior.

==== Generic System Tray configuration keys ====
* '''DefaultAppletAdded''' (true/false): Remembers whether the default plasmoids (networkmanagement, device manager, notifications) have already been added(??)
* '''ShowApplicationStatus''' (true/false): Show system tray icons of applications that belong to the group “Applications”
* '''ShowCommunications''' (true/false): Show system tray icons of applications that belong to the group “Applications” (i. e. Messenger, IRC chat)
* '''ShowHardware''' (true/false): Show system tray icons of applications that belong to the group “Hardware” (i. e. volume control, printer applet)
* '''ShowSystemServices''' (true/false): Show system tray icons of applications that belong to the group “System Services” (i. e. Nepomuk Indexing Agent)
* '''ShowUnknown''' (true/false): Show system tray icons that do not belong into one of the categories mentioned above (or that do not use KDE’s system tray protocol and thus do not provide such information)
* '''alwaysShown''': Comma-separated list of widgets and entries that are to be shown all the time (e. g. KMix,notifier)
* '''hidden''': Comma-separated list of widgets and entries that are to be hidden all the time (e. g. Nepomuk Indexing Agent,Klipper,kmail)
{{note|Although notifications appear to be part of the System Tray, they are handled by a separate plasmoid which is embedded to the system tray. For its configuration keys, see section above}}

==== Add a widget to systemtray ====
You can not add widgets to the systemtray in a similar way like you would add them to a panel or containment using addWidget. Instead, to add, manage and remove them, you need to utilize writeConfig changing the currentConfigGroup.
<syntaxhighlight lang="cpp-qt">
systray = panel.addWidget("systemtray") // First add a systemtray to your panel
systray.currentConfigGroup = Array("Applets","0") // then change the currentConfig Group

// to the subnode [Applets][0]. Use any number you like(?)
</syntaxhighlight>

Now you can “create” the plasmoid by adding a “plugin” configuration entry
<syntaxhighlight lang="cpp-qt">
systray.writeConfig("plugin","notifier") // This will add a Device Notifier Plasmoid
</syntaxhighlight>
You can modify the plasmoid’s configuration by using writeConfig.
<syntaxhighlight lang="cpp-qt">
systray.writeConfig("property","value")
</syntaxhighlight>
To change back to the top configuration level and thus edit the systemtray plasmoid itself pass an empty array to currentConfigGroup.

==== Edit existing widgets in systemtray ====

==== Remove a widget from systemtray ====

To remove a widget, simply delete the corresponding configuration group.

Development/Tutorials/Plasma/JavaScript/CheatSheet

2011-06-30T11:18:54Z

Icwiener: Fix syntax highlighting.

{{TutorialBrowser|

series=JavaScript Plasmoids|

name=Getting Data|

name=JavaScript Plasmoid Cheat Sheet|

pre=[[../DataEngine|Now Playing: Advanced DataEngine Usage Example]]|

reading=[[../API|JavaScript Plasmoid API reference]]
}}

== Basics ==

* Everything but the metadata.desktop file goes in a directory named <tt>contents</tt>
* <tt>X-Plasma-MainScript</tt> in the metadata.desktop file should point to the main script, relative to the contents directory
* <tt>X-Plasma-DefaultSize</tt> in the metadata.desktop file specifies the default widget size in width,height format (eg: 200,100)
* <tt>plasmoidviewer</tt> is an immensely useful tool
* To connect to a signal use <tt>object.signalName.connect(function() {});</tt>
* Enumeration values can be used like
<syntaxhighlight lang="javascript">
if (plasmoid.formFactor() == Vertical) {
layout.setOrientation(QtVertical);
} else {
layout.setOrientation(QtHorizontal);
}
</syntaxhighlight>

== Global variables and functions ==

* The <tt>plasmoid</tt> variable contains all the main plasmoid functionality and represents the main plasmoid widget, and corresponds to the <tt>Applet</tt> class in C++
* The <tt>startupArguments</tt> variable contains any arguments that were passed to the plasmoid when it was started (such as when the plasmoid is registered as a handler for a mimetype)
* The <tt>loadui</tt> function can be used to load a Qt UI file. Beware that a relative path is relative to plasma's working directory (in 4.2 at least), and so may not do what you want.
* The <tt>print</tt> function prints debug output
* There are several constructor methods:
** <tt>PlasmaSvg(file, parent)</tt> constructs a <tt>Plasma::Svg</tt>. The second argument is optional.
** <tt>PlasmaFrameSvg(file, parent)</tt> constructs a <tt>Plasma:FrameSvg</tt>. The second argument is optional.
** <tt>QPainter()</tt>
** <tt>QGraphicsItem()</tt>
** <tt>QTimer()</tt>
** <tt>QFont()</tt>
** <tt>QRectF()</tt>
** <tt>QSizeF()</tt>
** <tt>QPoint()</tt>
** <tt>LinearLayout()</tt> constructs a <tt>QGraphicsLinearLayout</tt>
** <tt>Url()</tt> constructs a <tt>KUrl</tt>
* Plus constructors for all the Plasma widgets (eg: <tt>IconWidget()</tt>).

== Languages ==

* The Name and Comment fields in the <tt>metadata.desktop</tt> file can be translated like <tt>Name[nl]=Hallo JavaScript</tt>
* <tt>i18n()</tt> takes a string (in English) as the first argument, and substitutes in the following arguments to replace %1, %2, %3 etc. Eg: <tt>i18n("The file is called %1", fileName);</tt>
* <tt>i18nc()</tt> works just the same, but has an extra argument at the start that provides some context for translators. Eg: <tt>i18nc("Player name - score", "%1 - %2", playerName, score);</tt>
* <tt>i18np()</tt> is for cases where plural forms might be important. Eg: <tt>i18np("One image in album %2", "%1 images in album %2", imageCount, albumName);</tt>
* <tt>i18ncp()</tt> is a combination of the previous two. Eg: <tt>i18ncp("Personal file", "One file", "%1 files", numFiles);</tt>

== DataEngines ==

* Add a <tt>dataUpdate</tt> method to <tt>plasmoid</tt> to receive updates: <tt>plasmoid.dataUpdate = function(name, data) { /* ... */ }</tt> - <tt>data</tt> contains an object mapping keys to values
* <tt>plasmoid.dataEngine("engine name").connectSource("source name", plasmoid, 500);</tt> updates every half second
* <tt>plasmoid.dataEngine("engine name").connectSource("source name", plasmoid);</tt> updates when new data is available
* <tt>plasmaengineexplorer</tt> is your friend

== Services ==

* Prior to KDE 4.4, DO NOT use <tt>plasmoid.dataEngine("engine name").serviceForSource("source name")</tt> - you will get a dummy service back. Instead, use <tt>plasmoid.service("engine name", "source name")</tt>

=== Notifications ===

If you want to use the standard notifications in KDE, you can using Services, with the following code:

<syntaxhighlight lang="javascript">
engine = dataEngine("notifications");
service = engine.serviceForSource("notification");
op = service.operationDescription("createNotification");
op["appName"] = "foo";
op["appIcon"] = "konqueror";
op["summary"] = "this is a summary";
op["body"] = "body of notification";
op["timeout"] = 2000;

service.startOperationCall(op);
</syntaxhighlight>

Development/Tutorials/Plasma/JavaScript/SystemMonitor

2011-06-30T11:17:47Z

Icwiener: Fix syntax highlighting.

This example assumes that you are familiar with previous examples such as [[Development/Tutorials/Plasma/JavaScript/NowPlaying|NowPlaying]] (from which this example was adapted).

Following code illustrates how to connect to systemmonitor and how to receive updates from various data sources.

You should have a working plasmoid application from previous examples. Take a copy of the plasmoid and rename it. After this you can replace contents of the <tt>contents/code/main.js</tt> with following:
<syntaxhighlight lang="javascript">
layout = new LinearLayout(plasmoid);

label = new Label();
layout.addItem(label);
label.text = "No connection";

// current values
var systemData = new Array();

function printData() {
label.text = "";
for (var name in systemData) {
var data = systemData[name];
label.text = label.text + name + ": ";
for (var elt in data) {
label.text = label.text + " " + data[elt];
}
label.text = label.text + "\n";
}
}

plasmoid.dataUpdated = function(name, data) {
systemData[name] = data;
printData();
};

smDataEngine = dataEngine("systemmonitor");

smDataEngine.sourceRemoved.connect(function(name) {
// unsubscribe
smDataEngine.disconnectSource(name, plasmoid);
});

smDataEngine.sourceAdded.connect(function(name) {
if (name.toString().match("^mem/physical")) {
// subscribe
smDataEngine.connectSource(name, plasmoid, 500);
}
});

</syntaxhighlight>

In <tt>smDataEngine.sourceAdded.connect()</tt> we give a function to connect to signal. The signal connection function is called by the systemmonitor for each data source. In this example we only connect to physical memory data sources.

After this the <tt>plasmoid.dataUpdate()</tt> receives updates. Update values are stored into an array. The array is printed on every update.

Note that this example is bit inefficient since we call <tt>printData()</tt> on every update. One way to optimize is to update label text only when "mem/physical/free" data source is updated.

Development/Tutorials/Plasma/JavaScript/NowPlaying

2011-06-30T11:16:38Z

Icwiener: Fix syntax highlighting.

{{TutorialBrowser|

series=JavaScript Plasmoids|

name=Now Playing: Advanced DataEngine Usage

pre=[[../NowPlaying|Getting Data: How to retreive data from a data engine]]|

next=[[../CheatSheet|Cheat Sheet: Common gotchas and useful tips]]|

reading=[[../API|JavaScript Plasmoid API reference]], [[../SystemMonitor|How to access systemmonitor data engine]]
}}

== Abstract ==

This will show you some slightly more advanced techniques for dealing with data engines, and give you a useful plasmoid at the end that you can easily edit to display custom information about what your favourite media player is playing (providing, of course, that your favourite media player is supported by the <tt>nowplaying</tt> data engine).

We assume you've read the [[Development/Tutorials/Plasma/JavaScript/DataEngine|JavaScript data engine tutorial]].

== Main script ==

Create a <tt>contents/code/main.js</tt> file with the following contents:

<syntaxhighlight lang="javascript">
layout = new LinearLayout(plasmoid);
layout.orientation = QtVertical;

label = new Label();
layout.addItem(label);
label.text = "No player found";

function firstSource() {
var sources = dataEngine("nowplaying").sources;
if (sources.length) {
return sources[0];
} else {
label.text = "No player found";
return '';
}
}

plasmoid.dataUpdated = function(name, data) {
if (source == name) {
label.text = 'Info:\n';
for (var key in data) {
label.text += key + ': ' + data[key] + '\n';
}
}
}

source = firstSource();

npDataEngine = dataEngine("nowplaying");

npDataEngine.sourceRemoved.connect(function(name) {
if (name == source) {
source = firstSource();
if (source) {
npDataEngine.connect(source, plasmoid, 500);
}
}
});

npDataEngine.sourceAdded.connect(function(name) {
if (!source) {
source = name;
npDataEngine.connect(source, plasmoid, 500);
}
});

if (source) {
npDataEngine.connectSource(source, plasmoid, 500);
}
</syntaxhighlight>

It looks complicated, compared to the two previous tutorials, but there is really only one new thing, and that is that we're watching for sources appearing and disappearing.

The <tt>nowplaying</tt> data engine makes sources appear and disappear as media players come and go. This plasmoid is a little stupid and only ever watches the first source in the list, but that will be enough for us.

The magic is in listening to the <tt>sourceAdded</tt> and <tt>sourceRemoved</tt> signals of the data engine. These, unsuprisingly, are emitted when the <tt>sources</tt> property of the data engine, which lists all known sources, changes. Note that it may be possible to sensibly request sources that are not in the <tt>sources</tt> property of a data engine - for example, the <tt>twitter</tt> data engine has a theoretically infinite number of sources available, one for each possible twitter account, and these cannot possibly be listed in the <tt>sources</tt> property.

You can learn more about using signals and slots in JavaScript in the [http://doc.trolltech.com/latest/qtscript.html QtScript documentation]. Remember that any property, signal or slot and any method tagged with <tt>Q_INVOKABLE</tt> (see the [http://api.kde.org/4.x-api/kdelibs-apidocs/plasma/html/index.html Plasma API documentation] for which methods this applies to) can be called from JavaScript.

== Challenge ==

Modify <tt>plasmoid.dataUpdate</tt> to display the information you care about, rather than all the information provided by the <tt>nowplaying</tt> data engine.

Development/Tutorials/Plasma/JavaScript/GettingStarted

2011-06-30T11:14:47Z

Icwiener: Fix syntax highlighting.

{{Template:I18n/Language Navigation Bar|Development/Tutorials/Plasma/JavaScript/GettingStarted}}

{{TutorialBrowser|

series=JavaScript Plasmoids|

name=Introduction To Writing Plasmoids with JavaScript|

next=[[../DataEngine|Getting Data: How to retrieve data from a DataEngine]]|

reading=[[../API|JavaScript Plasmoid API reference]]
}}

== Abstract ==

In this tutorial we'll cover creating a very simple Plasmoid in JavaScript, otherwise known as [http://doc.trolltech.com/latest/qtscript.html QtScript] or [http://www.ecmascript.org/ ECMAScript], to provide a Plasma widget.

Using JavaScript doesn't require any external dependencies, since it is part of the Qt libraries. As of KDE 4.3, the Plasma JavaScript engine is part of kdebase/runtime, and so can be used in any Plasma-based application, not just the Plasma Desktop.

== QtScript ==
The Simplified JavaScript API is powered by Qt's QtScript system which provides access to a full featured ECMA Script interpreter. If it works in ECMA Script, it will work in a Simplified JavaScript Plasmoid.

{{note|QtScript uses the high performance ECMA Script interpreter from WebKit and shares this code with QtWebKit.

However, QtScript does not include things such as a DOM API those familiar with JavaScript from a web browser context may expect. It is ''just'' ECMA Script with Qt integration.}}

On top of the ECMA Script language, QtScript provides Qt integration features. Probably the most useful one in the context of writing Plasmoids is the use of signals and slots which is Qt's callback mechanism. Signals may be emitted in QtScript by calling the signal method in question, a signal can be connected to a slot by using the connect() method (and disconnected with disconnect()) and any function defined in the Plasmoid may be used as a slot. For example:

<syntaxhighlight lang="javascript">
function onClick()
{
print("We got clicked!")
}

function onFirstClick()
{
print("First click!")
button.clicked.disconnect(onFirstClick)
}

button = new PushButton
button.clicked.connect(onClick)
button.clicked.connect(onFirstClick)
button.clicked()
</syntaxhighlight>

This will print out:

<syntaxhighlight lang="text">
We got clicked!
First click!
</syntaxhighlight>

on the console when the Plasmoid starts, and the "We got clicked!" again whenever the button is clicked by the user.

== What is a widget? ==
In the context of Plasma, a "widget" is a single, self-contained graphical object on the canvas. They can be added and removed individually, configured separately from other widgets, etc. These "mini applications" are sometimes referred to in other widget platforms as "applets", "apps", "gadgets", "karambas", "desklets". We chose the word "widget" for Plasma as it is used by other some other existing systems.

The API of a widget is defined by the host "ScriptEngine", with the exception of native Plasma widgets written in C++ which allows plugins in loadable libraries which use the API of the Plasma library directly. Currently Plasma supports both such "native" widgets written in C++, ones written in various dynamic languages (Plasmoids) as well as:

* SuperKaramba's karambas
* Enlightenment 17 edje content
* Google Gadgets
* MacOS dashboard widgets (though not all)

These are loaded via host AppletScriptEngine plugins that bridge between the widget itself and Plasma's canvas.

== What is a Plasmoid? ==

A Plasmoid is a widget that can be loaded into Plasma that uses the native Plasma API and comes packaged in a single archive file which includes the code, metadata, images, configuration definitions, etc. Plasmoids may be currently written using various scripting languages and APIs. This tutorial covers the Simplified JavaScript API for Plasmoids

== Project Structure ==

The first step for any software project is to set up your project's directory on disk. For this tutorial we are going to create a very simple "hello-javascript" plasmoid. Create a directory on somewhere called <tt>hello-javascript</tt> which in turn contains a <tt>contents</tt> directory which then contains a <tt>code</tt> directory. This command below will do all this.
<syntaxhighlight lang="bash">
mkdir -p hello-javascript/contents/code
</syntaxhighlight>

The only required part of the structure, in fact, is the <tt>contents</tt> directory - almost everything will go in this directory. But separating your code into a different directory from application data is a good habit to have.

== Metadata.desktop ==

In the <tt>hello-javascript</tt> directory create a file called <tt>metadata.desktop</tt> and open it in your text editor. Copy the following code into <tt>metadata.desktop</tt>.

<syntaxhighlight lang="ini">
[Desktop Entry]
Name=Hello JavaScript
Comment=An example JavaScript widget
Icon=chronometer

Type=Service
X-KDE-ServiceTypes=Plasma/Applet

X-Plasma-API=javascript
X-Plasma-MainScript=code/main.js
X-Plasma-DefaultSize=200,100

X-KDE-PluginInfo-Author=<Your name here>
X-KDE-PluginInfo-Email=<Your email here>
X-KDE-PluginInfo-Name=hello-javascript
X-KDE-PluginInfo-Version=1.0
X-KDE-PluginInfo-Website=http://plasma.kde.org/
X-KDE-PluginInfo-Category=Examples
X-KDE-PluginInfo-Depends=
X-KDE-PluginInfo-License=GPL
X-KDE-PluginInfo-EnabledByDefault=true
</syntaxhighlight>

This <tt>metadata.desktop</tt> file list important information needed by Plasma to load the widget, and also information about what the widget is and who created it.

<tt>Name</tt> gives the name of widget as seen by the user when they go to the Add Widget dialog on the desktop. There can be additional name entries for different languages. For example, you could add a Dutch translation by inserting the line <tt>Name[nl]=Hallo JavaScript</tt>.

<tt>Comment</tt> gives a more detailed description of the widget. This is also displayed in the Add Widget dialog, and can be translated in the same way as <tt>Name</tt>.

<tt>Icon</tt> gives the name of the icon to associate with this plasmoid. The icon is shown in the Add Widget dialog. It must be the name of an icon that is either distributed with KDE (such as <tt>chronometer</tt>) or provided by your plasmoid. If you want to provide the icon, you can use <tt>Icon=icon.png</tt>.

The <tt>Type</tt>, <tt>X-KDE-ServiceTypes</tt>, <tt>X-Plasma-API</tt> and <tt>X-Plasma-MainScript</tt> fields are required for Plasma to find your plasmoid and know what to do with it. Note that <tt>X-Plasma-MainScript</tt> is a path relative the <tt>contents</tt> directory.

<tt>X-Plasma-DefaultSize</tt> specifies the default size for widget, as <tt>width,height</tt>. While the units aren't technically pixels, they have the same value as pixels providing you don't do anything like zoom in or out on your desktop.

<tt>X-KDE-PluginInfo-Category</tt> gives a category for the widget. This is used in the Add Widgets dialog to group and filter widgets. The value must be one of the category names listed at [[Projects/Plasma/PIG]].

<tt>X-KDE-PluginInfo-Name</tt> is the internal name of the plasmoid (you can think of this as the name of the plasmoid, as opposed to the name of the widget which is given by <tt>Name</tt>). This is the name you will use as an argument to <tt>plasmoidviewer</tt> or <tt>plasmapkg</tt> when you need to provide a plasmoid name rather than a path. It doesn't have to be the same name as the directory containing <tt>metadata.desktop</tt>.

<tt>X-KDE-PluginInfo-Author</tt>, <tt>X-KDE-PluginInfo-Email</tt>, <tt>X-KDE-PluginInfo-Version</tt>, <tt>X-KDE-PluginInfo-Website</tt> and <tt>X-KDE-PluginInfo-License</tt> are informational, and are displayed in the About dialog for the plasmoid (which can be viewed by clicking the information icon next to the corresponding widget in the Add Widgets dialog of plasma).

<tt>X-KDE-PluginInfo-EnabledByDefault</tt> and <tt>X-KDE-PluginInfo-Depends</tt> rarely need to be changed from the values given here.

== Main script ==

The name of the main script file is given by <tt>X-Plasma-MainScript</tt> in metadata.desktop, and is relative to the <tt>contents</tt> directory. In our case, we will need to create the file <tt>hello-javascript/contents/code/main.js</tt>. Put the following code in it:

<syntaxhighlight lang="javascript">
layout = new LinearLayout(plasmoid);

label = new Label();
layout.addItem(label);

label.text = 'Hello JavaScript!';
</syntaxhighlight>

plasmoid is a global variable that represents your widget. It has some useful methods that we'll come to in later tutorials.

First, we create a layout, because plasmoids don't have a layout by default. This just makes sure that the label is the correct size and in the correct place. Passing <tt>plasmoid</tt> to the <tt>LinearLayout</tt> attaches the layout to the widget.

Next we add a label to the layout, and finally we set the label text.

== Testing (KDE 4.3+) ==

If you have KDE 4.3 or later, you can test your plasmoid without installing it by entering the <tt>hello-javascript</tt> directory and running <tt>plasmoidviewer</tt>. Alternatively, call
<syntaxhighlight lang="bash">
plasmoidviewer /path/to/hello-javascript
</syntaxhighlight>

This is very convenient for development as you can edit the Plasmoid and test the changes immediately without re-installing the plasmoid over and over again.

== Installing ==

You can install the plasmoid by running the following command from within the <tt>hello-javascript</tt> directory:
<syntaxhighlight lang="bash">
plasmapkg -i .
</syntaxhighlight>

The final argument to <tt>plasmapkg</tt> is the path to the directory containing <tt>metadata.desktop</tt> and the <tt>contents</tt> directory.

You can now add your widget to the desktop using the Add Widgets dialog, or view it by running
<syntaxhighlight lang="bash">
plasmoidviewer hello-javascript
</syntaxhighlight>

== Packaging ==

If you want to share your plasmoid, you'll have to package it. Run the following from within the <tt>hello-javascript</tt> directory:
<syntaxhighlight lang="bash">
zip -r ../hello-javascript.zip . &&
mv ../hello-javascript.zip ../hello-javascript.plasmoid
</syntaxhighlight>

You now have a plasmoid package you can share with the world. To install it, either use the "Install new widgets" functionality in the Add Widgets dialog, or go to the directory containing <tt>hello-javascript.plasmoid</tt> and run
<syntaxhighlight lang="bash">
plasmapkg -i hello-javascript.plasmoid
</syntaxhighlight>

To uninstall the plasmoid, use <tt>plasmapkg</tt> again with its -r option:
<syntaxhighlight lang="bash">
plasmapkg -r hello-javascript
</syntaxhighlight>

Note that while the argument to <tt>plasmapkg -i</tt> is a file or directory, you need to pass the plasmoid name (given by <tt>X-KDE-PluginInfo-Name</tt> in <tt>metadata.desktop</tt>) to <tt>plasmapkg -r</tt>.

Development/Tutorials/KDE3

2011-06-30T11:07:59Z

Icwiener: Add deletion proposal.

{{Delete|KDE 3 content: should be looked through for useful stuff before deleting.}}

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 KDE3 development.

{{tip|If you are working with a newer version of KDE, such as KDE4, these tutorials are probably of limited use to you. For tutorials covering current KDE development topics, visit the [[Development/Tutorials|main tutorials page]]}}

== Getting Started ==

;[[/Qt Designer and KDevelop 3.0 for Beginners|Qt Designer and KDevelop 3.0 for Beginners]] ([http://women.kde.org/articles/tutorials/kdevelop3/index.html Original Link])
:''Qt is the toolkit used by the KDE project for developing graphical applications. Currently, translations are available through the original link. This paper, written by Anne-Marie Mahfouf, shows a beginner how to create a simple application using Qt Designer 3 and KDevelop 3. This tutorial is based on an application written by Jono Bacon and has been reviewed by Daniel Molkentin (for the KDevelop 2 version) and Thomas Nagy. Translations to German, Russian, French, Italian, and Romanian available at the [http://women.kde.org/articles/tutorials/kdevelop3/index.html original site]. Brought to you by [http://women.kde.org KDE-Women].''

;[http://devel-home.kde.org/~larrosa/tutorial/index.html KDE 3.0 Tutorial]
:''An excellent tutorial by KDE developer Antonio Larrosa Jiménez leading you from nothing to a fairly full featured web browser. Highly recommended for KDE 3.0 developers.''

;[[../Programming Tutorial KDE 3|Programming Tutorial for KDE 3]]

;[[/Makefile.am|Makefile.am HOWTO]]
:''Make the KDE 3 build system work for you. This HOWTO shows you how to do most anything you would need to do to get your application to compile and install''

== Components and Plugins ==

;[http://developer.kde.org/documentation/tutorials/xmlui/preface.html KDE User Interface Tutorial (XML GUI)]
:''Tutorial by KDE developer [mailto:granroth@kde.org Kurt Granroth] showing how to convert an existing KDE application to use the new XML based user interface builder.''

;[http://www-106.ibm.com/developerworks/linux/edu/l-dw-linuxkp1-i.html Creating KParts Component]
:''Tutorial on IBM DeveloperWorks, by [mailto:faure@kde.org David Faure] shows developers how to create KParts components, under KDE 2 and KDE 3.''

;[http://developer.kde.org/documentation/tutorials/developing-a-plugin-structure/index.html Developing a Plugin Structure for a KDE Application]
:''This tutorial will take you through all the steps needed to write a plugin structure, plus plugins for your KDE application.''

;[http://developer.kde.org/documentation/tutorials/kfile-plugin/t1.html Providing file meta-data support with KFile plugins]
:''Tutorial by [mailto:bradh@frogmouth.net Brad Hards] that describes how to write a meta-data plugin for your favourite file format. It is presented as an example based tutorial.''

;[http://developer.kde.org/documentation/tutorials/components/index.html Embedded Components Tutorial]
:''Tutorial by KDE developer [mailto:granroth@kde.org Kurt Granroth] showing how to convert an existing KDE application into a component suitable for embedding in [http://www.konqueror.org Konqueror].''

; [[/How_to_write_Kontact_plugins|How to write Kontact plugins]]
:''Kontact plugins''

; [http://developer.kde.org/documentation/other/kcm_howto.html KConfig Module HOWTO]
:''A small tutorial about writing a module for the KDE Control Center.''

; [[/KDockWidget|Using the KDE dock widget]]
:''Tutorial for creating widgets that dock to other widgets. ''

; [[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.''

== File Access with KIO ==

;[http://www.heise.de/ct/english/01/05/242/ KIO Tutorial] ([http://www.heise.de/ct/01/05/242/default.shtml German version])
:''Tutorial by KDE developers [mailto:pfeiffer@kde.org Carsten Pfeiffer] and [mailto:coolo@kde.org Stephan Kulow] for the [http://www.heise.de/ct/ c't Magazine], giving an introduction into the KDE IO Architecture and an example KIO Slave.''

;[http://developer.kde.org/documentation/design/kde/ioslaves/index.html Using IOSlaves]
:''IOSlaves are the subprocesses KDE uses to fetch remote files without blocking the user interface. This document discusses how they work and how to use them.''
:(Somewhat dated, but might still be useful).

== Components and Plugins ==

=== KWin ===

;[http://www.usermode.org/docs/kwintheme.html KWin decoration styles]
:''Tutorial on creating decoration plugins for the KWin window manager (KDE 3.2 and later).''

== Scripting and Application Automation ==

;[http://developer.kde.org/documentation/tutorials/dot/dcopiface/dcop-interface.html Creating a DCOP Interface]
:''This tutorial shows you how to create a DCOP interface to a KDE application.''

;[http://www-106.ibm.com/developerworks/linux/library/l-dcop/index.html?ca=dgr-kdeml01KDEDCOP Connect KDE applications using DCOP]
:''IBM DeveloperWorks tutorial, shows how to use kdcop and dcop with several examples such as instantly messaging a contact in kopete when he comes online, and also how to create a simple DCOP-aware application.''

=== Konqueror ===
; [[Development/Tutorials/KDE3/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").''

Development/Tutorials/KDE3/How to write Kontact plugins

2011-06-30T10:57:57Z

Icwiener: Add deletion proposal.

{{Template:Delete|KDE 3 content.}}
''by Thorsten Stärk''

This documentation is intended for developers programming on - or
writing plugins for - Kontact. Kontact is a KDE program uniting several
KDE components for personal information management under one roof.
Personal information management is e.g. writing mails, planning your
calendar dates or tracking your time. If you want to learn how to use
Kontact, visit [http://www.kontact.org The Kontact homepage].

== Tutorial FactBox ==

{| border="1" style="text-align: left; width: 247px; height: 58px;"
|-
|style="vertical-align: top;"|lasts || style="vertical-align: top;"|3 hours
|-
|style="vertical-align: top;"|without this tutorial || style="vertical-align: top;"|3 weekends
|}

== How to write a plugin for Kontact ==

This chapter demonstrates how to turn an existing KDE program into a
Kontact plugin. This is done on the example of the program KArm from
KDE 3.4.1. First, we will create a [[Development/Architecture/KDE4/KParts|KPart]] out of the program, then, we
will use this for a Kontact plugin. Then, we will look at some errors
that may occur with that work. A KPart is a KDE component that can be
used as a program, with the difference that it cannot run alone,
because it needs a program building a "mainwindow" for it.

== How to create the KPart ==
To turn our KDE Program into a [[Development/Architecture/KDE4/KParts|KPart]], we create a verbatim KPart with
KDevelop and copy it over to our program's source directory. For this,
I assume, you want to modify the program karm from KDE 3.4.1 and it can
be found in {{path|/home/user/svn/3.4.1/kdepim/karm}}. I assume your home
directory is {{path|/home/user}} and you are on KDevelop 3.2.0.

Start KDevelop, close all open projects (Project -> close), then chose
<tt>Project | New Project -> C++ -> KDE -> Application Framework
(KParts)</tt>. Set "Application Name" to "karm", continue as instructed.
Now test your verbatim KPart by executing it in KDevelop. Expected result
is a "Could not find our part".

This is because you do not yet have the KPart installed. KDevelop will
store your work in {{path|/home/user/karm/}}, so test your verbatim KPart
by doing a make install in {{path|/home/user/karm/}} and executing the
KDevelop project. Expected result is a text-editing window, the verbatim KPart.

KDevelop has created {{path|karm.h}}, {{path|karm.cpp}}, {{path|karm_part.h}},
{{path|karm_part.cpp}}, {{path|karm_part.desktop}} and {{path|Makefile.am}}
in {{path|home/user/karm/src/}}. {{path|karm.h}} and {{path|karm.cpp}}
just open a mainwindow and display the karm_part in it. We do not need
them, as we already have a mainwindow for our program. So
copy the files {{path|karm_part.*}} to {{path|/home/user/svn/3.4.1/kdepim/karm}}
and adapt the files to display your main widget instead of a text
editor. You may want to replace {{qt3|QMultiLineEdit}} by your main widget.
Finally adapt the {{path|Makefile}} {{path|/home/user/svn/3.4.1/kdepim/karm/Makefile.am}}
to include the added files. This is hard to generalize, I show it here
for the KArm program.

You may want to have a look at [http://websvn.kde.org/trunk/KDE/kdepim/karm/Makefile.am?rev=412382&r1=409203&r2=412382 the diff]
between the old and the new {{path|Makefile.am}}. Now replace <tt>karm_SOURCES</tt> by <tt>libkarm_shared_la_SOURCES</tt> and remove main.cpp from the list. Add a <tt>noinst_LTLIBRARIES = libkarm_shared.la</tt>
before that line. That causes that all the karm files will not be bound to a binary karm,
but to a library <tt>libkarm_shared.la</tt>. This binary can then be used to
link as well karm as our KPart. Add <tt>libkarm_shared.la</tt> to <tt>karm_LDADD</tt>
before that line, place a <tt>karm_SOURCES=main.cpp</tt>. These lines now draw the library
<tt>libkarm_shared.la</tt>. Finally, add a kpart section as from {{path|/home/user/karm/src/Makefile.am}} to karm's {{path|Makefile.am}}. This should look like this:

##################
# KPART SECTION
##################
kde_module_LTLIBRARIES = libkarmpart.la
# the Part's source, library search path, and link libraries
libkarmpart_la_SOURCES = karm_part.cpp
libkarmpart_la_LDFLAGS = -module -avoid-version -no-undefined $(KDE_PLUGIN) $(all_libraries)
libkarmpart_la_LIBADD = libkarm_shared.la $(LIB_KPARTS) $(LIB_KFILE) \
-lkdeprint $(top_builddir)/libkcal/libkcal.la \
$(top_builddir)/kresources/remote/libkcal_resourceremote.la \
$(top_builddir)/libkdepim/libkdepim.la $(LIBXSS)

# this is where the desktop file will go
partdesktopdir = $(kde_servicesdir)
partdesktop_DATA = karm_part.desktop

# this is where the part's XML-GUI resource file goes
partrcdir = $(kde_datadir)/karmpart
partrc_DATA = karmui.rc

After that, test your changes of {{path|Makefile.am}}. You have to do <tt>make -f
Makefile.cvs && ./configure && make</tt> in
{{path|/home/user/svn/3.4.1/kdepim/}}.

Warning: running <tt>./configure && make</tt> is not enough. {{path|Makefile.am}}'s are processed by <tt>make -f Makefile.cvs.</tt>

Install your KPart, e.g. with make install. Then test your KPart:

* Start Konqueror, chose Settings | Configure Konqueror ->
File Associations | text -> calendar. File name patterns are
"*.ics". Chose Embedding -> Show files in embedded viewer -> Add
-> karmPart -> Apply.
* right-click onto a .ics-file and chose "preview in embedded
viewer -> karmPart"
* verify that Konqueror now is the "mainwindow" for your KPart.
Konqueror will show what was shown by your application before.

== How to get the Kontact plugin ==

You best clone a little Kontact plugin and then adapt it to your
program.

Warning: Do not copy
any directory within your svn working copy, change it and re-commit.
Every folder in the working copy contains a subfolder <tt>.svn/</tt> which
will direct your commits to the original folder. Better do it that way:

* create a folder {{path|/home/user/svn/3.4.1/kdepim/kontact/plugins/karm}}
* copy ''only'' {{path|Makefile.am}}, {{path|multisynk_plugin.cpp}}, {{path|multisynk_plugin.h}}, {{path|multisynkplugin.desktop}} from {{path|/home/user/svn/3.4.1/kdepim/kontact/plugins/multisynk/}} to {{path|../karm/}}
* rename the four files and adapt them to their new names
* adapt the {{path|karmplugin.desktop}} file to point to your KPart's library, in this case <tt>X-KDE-KontactPartLibraryName=libkarmpart</tt>

You see, the deciding step is to tell a {{path|.desktop}} file to use the libs of a KPart. The only modification on the plugin's code is related to
renaming the files. That is elegant.
* give your plugin a distinct name
* add your plugin folder (karm) to the makefile for kontact plugins (in your kdepim folder under {{path|kontact/plugins/Makefile.am}}):
<syntaxhighlight lang="bash">
SUBDIRS = $(KPILOT_KONTACTPLUGIN) kaddressbook kmail knotes korganizer \
summary weather knode newsticker multisynk specialdates akregator karm
</syntaxhighlight>
* <tt>make -f Makefile.cvs && ./configure && make && make install</tt> your kdepim
* test your plugin
** start Kontact, chose Settings|Configure Kontact -> Configure
** verify that you find your program's plugin to be chosen there.

== Pitfalls ==
* the program no longer sets it icons correctly
** this pitfall occurred as well in the plugin as in the KPart due to the fact that my program was using UserIcon to load the Icons instead of the {{class|KIconLoader}}. UserIcon looks for the application name to find out the icons' path. As there was no application (only a KPart), it gave up on searching the icons.

== Suggested readings ==
* http://www-106.ibm.com/developerworks/linux/edu/l-dw-linuxkp1-i.html : DeveloperWorks article from David Faure on the KPart technology
* http://websvn.kde.org/trunk/KDE/kdepim/karm/Makefile.am?rev=412382&r1=409203&r2=412382 : Code example showing the integration of the karm part, file Makefile.am

[[Category:Tutorial]]
[[Category:C++]]
[[Category:PIM]]

Template:Delete

2011-06-30T10:56:17Z

Icwiener: Add parameter for deletion reason.

{{Warning|'''This page has been nominated for deletion'''.

Reason: {{{1}}}

If you disagree with its deletion, remove the template and discuss it on [[{{TALKPAGENAME}}|its talk page]].

}}<includeonly>[[Category:Marked for Deletion]]</includeonly>
<noinclude>[[Category:Maintenance Templates]].</noinclude>

Template:Delete

2011-06-30T10:52:02Z

Icwiener: Rephrase and shorten it a bit.

{{Warning|'''This page has been nominated for deletion'''.

If you disagree with its deletion, remove the template and discuss it on [[{{TALKPAGENAME}}|its talk page]].

}}<includeonly>[[Category:Marked for Deletion]]</includeonly>
<noinclude>[[Category:Maintenance Templates]].</noinclude>

Development/Tutorials/Introduction to Get Hot New Stuff

2011-06-30T10:29:52Z

Icwiener: /* Preparations */ bash -> make

{{improve}}
{{KDE3}}

== KDE 4 ==
Please read the [[Development/Tutorials#Get_Hot_New_Stuff|KDE 4 tutorials]] about get hot new stuff, unless you really work on KDE 3 apps.

== Introduction ==
Similar to how programming languages shifted focus from algorithms to data structures in the 70s, desktop application development emphasizes more and more on user data, i.e. data intentionally produced or consumed by the user. Both on the internet and in corporate intranets, sharing this data is considered an easy way to customize desktops and to advertise one's creativity. The 'Get Hot New Stuff' (GHNS) framework in KDE exists to support this approach, and the KNewStuff library is the key for application authors to enable GHNS.

== Preparations ==
The first steps are usually made in preparing the usage of KNewStuff. For this matter, the library must be available (a task which could be done using autoconf, but since it's part of kdelibs, we simply assume it's available with any recent KDE installation.) Authors of 3rd pary applications can ensure the availability as part of kdepim-libs in KDE 3.2 using the AC_KNEWSTUFF macro. It must also be included in the set of libraries against which the application is linked, so modifying the {{path|Makefile.am}} and reconfiguring the application are to be done.

<syntaxhighlight lang="make">
bin_PROGRAMS = myapp
myapp_LDADD = $(LIB_KDECORE) ... -lknewstuff
</syntaxhighlight>

The header files are installed under {{path|$KDEDIR/include/knewstuff/}}, so in the relevant files, they're included with statements such as:

<syntaxhighlight lang="cpp">
#include <knewstuff/downloaddialog.h>
</syntaxhighlight>

The following header files are provided by KNewStuff:
* {{path|downloaddialog.h}}: Easy to use download dialog
* {{path|engine.h}}: Access to the complex, but customizable background operations
* {{path|entry.h}}: (internal) Data fields of entries, such as Author or Title
* {{path|ghns.h}}: [not installed]
* {{path|knewstuffgeneric.h}}: Easy to use installation handler for the downloaded files
* {{path|knewstuff.h}}: Main knewstuff functionality
* {{path|providerdialog.h}}: Preconfigured dialog for provider selection
* {{path|provider.h}}: Provider entries, and ProviderLoader
* {{path|testnewstuff.h}}: [not installed]
* {{path|uploaddialog.h}}: Easy to use upload dialog

For more information on the background processes, please have a look at the information provided by [http://www.kstuff.org/docs/ kstuff.org]. However application authors should only need a basic understanding of those.

== Downloading Data ==

Depending on the application, providing additional data can be accomplished using the 'File Import' dialog, 'Internet Level' menu item, or just an 'Update now' {{class|KAction}}. All of those have in common that they invoke a slot which will contain the actual {{class|KNewStuff}} calls.

<syntaxhighlight lang="cpp-qt">
void MyApp::slotDownload()
{
KNewStuff::DownloadDialog::open("myapp/templates");
}
</syntaxhighlight>

This is all. If desired, more control can be exercised on the whole download process, as outlined below. For the beginning, the above is already fully functional, and should be used at first.

== Downloading in Detail ==
The example above implicitely constructs an internal Engine object, retrieves the directory list, fetches the provider lists specified in the directory, and the entries in each of the provider lists, compares them to the data files previously installed, and displays them in the download dialog. This dialog in turn handles all the installation issues. Of course there is no magic involved, and for more control about the subtasks, the following is recommended:

<syntaxhighlight lang="bash">
(to be precised)
</syntaxhighlight>

== Installation ==

Similar to the provider list, the installation procedures are described in the application's configuration file. The default (if these entries are missing) is to just download the file to a temporary location, which is not useful in most of the cases. There are two entries: target location, and post-installation command. The target location can either be StandardResource, matching the KDE resource types, or TargetDir, matching an application directory under {{path|$KDEHOME/share/apps/appname}}. The post installation command can be a binary with '%f' as parameter (note the single quotes to prevent string format attacks), but it can as well be a DCOP call, so the application can directly work with the data.

<syntaxhighlight lang="ini">
[KNewStuff]
StandardResource=wallpaper
InstallationCommand=dcop kdesktop KBackgroundIface setWallpaper '%f' 2

TargetDir=kamikaze
</syntaxhighlight>

== Uploads ==

The beginning of the upload process works similar to downloads. A MasterServer or ProvidersUrl is used to retrieve the provider list, and one of the providers is selected by the user. Only providers which allow uploads are taken into account. After this selection however, the differences begin. The user has to fill in the necessary information such as title, author name or version number into the upload dialog. Also, the payload and preview files have to be selected, this however will in most cases be the application's task. In Kamikaze, the level file is pre-rendered to an invisible {{qt3|QCanvas}}, and the resulting graphics is minimized and automatically specified for the upload. The upload will then happen using the protocol accepted by the provider, which in most cases will be anonymous FTP.

<syntaxhighlight lang="cpp-qt">
#include <knewstuff/knewstuffgeneric.h>
#include <knewstuff/engine.h>
#include <knewstuff/uploaddialog.h>
// ...
QString file, previewfile;
KNewStuffGeneric *ns = new KNewStuffGeneric("myapp/templates", this);
ns->upload(file.name(), previewfile.name());
</syntaxhighlight>

== Finding the provider ==

In order to connect to the provider, you have to add the KNewStuff configuration to the config file of the application.

This can be done by adding the following lines to the ''myapprc'' file (create the file if there was none):

<syntaxhighlight lang="ini">
[KNewStuff]
ProvidersUrl=http://where_my_xml_file_is/providers.xml
</syntaxhighlight>

To install it in the proper location, just add the following line to the {{path|Makefile.am}}:
<syntaxhighlight lang="bash">
kde_conf_DATA = ''myapprc''
</syntaxhighlight>

== Setting up a provider.xml file ==

The {{path|provider.xml}} file holds the general information about the new stuff source (for example the name or the icon), and - most important thing - the location to the XML file containing the stuff for the application.

Here it is a simple {{path|provider.xml}} file, with no upload URL specified:

<syntaxhighlight lang="xml">
<provider downloadurl="http://where_my_newstuff_are/knewstuff.xml"
nouploadurl=""
icon="http://where_my_newstuff_are/myapp_newstuff.png">
<title>New stuff for MyApp!</title>
</provider>
</syntaxhighlight>

== Conclusion ==

Sharing creativity should become a default property of modern desktops, and KDE once again leads the pack by providing both upload and download facilities. If enough applications of different areas make use of them, it helps users to be more productive and have more fun with their computer.

Help:Contents

2011-06-28T12:06:17Z

Icwiener: /* Tips */ Fix syntaxhighlight keyword.

{{Template:I18n/Language Navigation Bar|Help:Contents}}

Before you start to add or change content, please read:
* [[Help:Contribute|Contributing to TechBase]]
* [[Help:Wiki Structure|Wiki Structure]]
* [[Help:Wiki Translation|Translation into other Languages]]
* [[KDE_TechBase:Migrate_content|Migrating Content]]
* [[KDE_TechBase:Contributors|List of active contributors]], also contact points

== Wiki Syntax ==
To get started with the MediaWiki syntax, read:
* [http://en.wikipedia.org/wiki/Help:Editing Help on Editing]
* [http://meta.wikimedia.org/wiki/Help:Table Wikitables]
* [http://en.wikipedia.org/wiki/Wikipedia:Extended_image_syntax Syntax for displaying images]
* [http://en.wikipedia.org/wiki/Help:Magic_words Magic words]

* [http://en.wikipedia.org/wiki/Wikipedia:Cheatsheet The most important commands]
* How to [[KDE TechBase:Migrate content|Migrate content]]

== Tips ==
; Syntax highlighting
: Wrap your C++ Qt/KDE code snippets in <tt><syntaxhighlight lang="cpp"></tt>, <tt><syntaxhighlight lang="cpp" line=""></tt>, <tt><syntaxhighlight lang="cpp-qt"></tt> and <tt></syntaxhighlight></tt> to get syntax highlighting (<tt>cpp</tt> for C++, <tt>cpp-qt</tt> for Qt) and numbered lines (<tt>line=""</tt>). Replace <tt>cpp</tt> with [http://www.mediawiki.org/wiki/Extension:SyntaxHighlight_GeSHi#Supported_languages the language used], e.g. <tt>ruby</tt> for Ruby and <tt>python</tt> for Python (soon). Use <tt>ini</tt> for {{path|.desktop}} files, <tt>xml</tt> for XML files.

== New Templates ==
To get a list of pages using a template, go to corresponding template page (e.g. [[Template:movepage]]) and click "''What links here''" in the toolbox.

; [[Template:movepage|<nowiki>{{movepage|url}}</nowiki>]]
: Use this template to mark a page as not finished.

; [[Template:Improve|<nowiki>{{improve|explanation}}</nowiki>]]
: Pages which need cleanups or contain empty sections and/or todos are marked with this template. Add an explanation if you want (optional)

; [[Template:tip|<nowiki>{{tip|text}}</nowiki>]]
: Use this template to add a tip for the reader.

; [[Template:note|<nowiki>{{note|text}}</nowiki>]]
: Use this template to add an explanatory note.

; [[Template:warning|<nowiki>{{warning|text}}</nowiki>]]
: Use this template to add a warning.

; [[Template:qt|<nowiki>{{qt|class-name}}</nowiki>]] and [[Template:qt3|<nowiki>{{qt3|class-name}}</nowiki>]]
: Use this template to generate a link to a Qt class, e.g. QWidget. For Qt3 classes use <nowiki>{{qt3|class-name}}</nowiki>

; [[Template:class|<nowiki>{{class|class-name}}</nowiki>]]
: Use this template to generate a link to a KDE class, e.g. KDialog.

; [[Template:path|<nowiki>{{path|path-or-filename}}</nowiki>]]
: Use this template for paths and filenames, this way all of them have a consistent style.

; [[Template:bug|<nowiki>{{bug|123456}}</nowiki>]]
: Use this template to automatically create a link to KDE's bugzilla.

; [[Template:KDE3|<nowiki>{{KDE3}}</nowiki>]]
: Use this template to mark the content of a page as applicable for either KDE 3. Don't tag technology agnostic pages. For KDE4 content, use <nowiki>[[Category:KDE4]]</nowiki>.

; [[Template:TutorialBrowser|<nowiki>{{TutorialBrowser|series|name|pre|next|reading}}</nowiki>]]
: A template for tutorial navigation

; [[Template:Box|<nowiki>{{Box|caption|text|width|float}}</nowiki>]]
: Use this template to create a box with a caption and a text. The width parameter is optional and can be specified absolute (400px) or relative (50%). The last parameter is the float value, which is also optional and defaults to center.

User talk:JRT

2011-06-28T11:41:55Z

Icwiener: /* code tag obsolete */ fix another tag ...

== KDE4-both ==

Hey, I removed your link to "KDE4-both", because no one has written that page yet ;) also I find it of questionable usefulness. --[[User:Logixoul|Logixoul]] 20:18, 5 April 2008 (CEST)

Sorry about the link. I couldn't figure out how to change it.

Please also note that your changes screwed up various things to the point the references were contradictory and, in some cases, simply WRONG.

== code tag obsolete ==

Hi,

the code tag is obsolete. But please do not delete contents because of that.
The code tag can be replaced (and we are doing it currently, but it will take another week or so to get them all) by <syntaxhighlight lang="cpp-qt">, with the supported languages being http://www.mediawiki.org/wiki/Extension:SyntaxHighlight_GeSHi#Supported_languages and probably more. I think we have "cmake" as well. :)

User talk:JRT

2011-06-28T11:41:01Z

Icwiener: /* tag obsolete */ fix tag ;)

User talk:JRT

2011-06-28T11:40:35Z

Icwiener: /* tag obsolete */ new section

== KDE4-both ==

Hey, I removed your link to "KDE4-both", because no one has written that page yet ;) also I find it of questionable usefulness. --[[User:Logixoul|Logixoul]] 20:18, 5 April 2008 (CEST)

Sorry about the link. I couldn't figure out how to change it.

Please also note that your changes screwed up various things to the point the references were contradictory and, in some cases, simply WRONG.

== <code> tag obsolete ==

Hi,

the code tag is obsolete. But please do not delete contents because of that.
The code tag can be replaced (and we are doing it currently, but it will take another week or so to get them all) by <syntaxhighlight lang="cpp-qt">, with the supported languages being http://www.mediawiki.org/wiki/Extension:SyntaxHighlight_GeSHi#Supported_languages and probably more. I think we have "cmake" as well. :)

Getting Started/Build/Distributions/Linux From Scratch

2011-06-28T11:35:12Z

Icwiener: Fix syntax highlighting.

{{Template:I18n/Language Navigation Bar|Getting_Started/Build/Distributions/LFS}}

{{TutorialBrowser|

series=Getting Started|

name=Building KDE4 From Source (Linux From Scratch requirements)|

pre=[[Getting_Started/Build|Build KDE]], [[Getting_Started/Tutorials/D-Bus/Configuration|D-Bus Configuration]]|
next=[[Getting_Started/Build|Build KDE]]|

reading=[[Development/Tutorials/CMake |Introduction to CMake]]|
}}

== CMake ==

KDE-4 and some supporting libraries use CMake.

Install the latest version from cmake.org

== Library Requirements ==

===General dependencies===

KDE-4 requires a lot of the same general purpose libraries as KDE-3.

The output from running CMake should list what you are missing -- which generally applicable libraries that you need which I will not discuss further.

===DBus and HAL===

A system should have these installed:

::DBus
::DBus-Glib
::HAL
::HAL-Info
::PolicyKit-0.9
::EggDBus
::polkit-0.97
::ConsoleKit

(and properly configured) although, strictly speaking, they are not all dependencies for KDE-4.x.

See: [http://www.linuxfromscratch.org/blfs/view/svn BLFS] for build and configure instructions.

HOWEVER, KDE-4 and KDESupport libraries may need newer versions of the libraries than those in BLFS. So, it is probably best to install the versions stated above or the latest releases of these dependencies rather than the versions in BLFS.

Some of these libraries are dependent on:

::Linux-PAM-1.1.1
::Shadow-4.1.4.2

which should be installed and configured according to the BLFS instructions.

===DocBook DTD===

KDE-4 still requires version 4.2 of:

::DocBook SGML DTD
::DocBook XML DTD.

See the instructions in this old version of BLFS:

::http://archive.linuxfromscratch.org/blfs-museum/5.0/BLFS-5.0/

===Boost C++ Libraries===

Get the current release (e.g. boost_1_42_0.tar.gz) here:

::http://sourceforge.net/projects/boost/files/boost/

=====Build=====

The current release eliminates the arcane naming issues. Although not the same as using autotools, it is now simple to build and install.

Remove the includes from previous versions:

::/usr/include/boost_<version>

and if you have a link:

::/usr/include/boost

remove that also.

Then:

::./bootstrap.sh --prefix=/usr
::./bjam install

===CLucene===
The CLucene developers suggest using the GIT repository since there are no recent releases. However, KDE-4 currently depends on the last (old) release:

::http://downloads.sourceforge.net/project/clucene/clucene-core-stable/0.9.21b/clucene-core-0.9.21b.tar.bz2

Do NOT use CMake to build it.

===Qt===

=====TRUNK=====

Use kde-qt from:

::git clone git://gitorious.org/+kde-developers/qt/kde-qt.git

This installs as Qt-<version>, so when it updates to the next version, it won't install in the same place. This means that you will need to change the <version> any place where it is specified. You will also have to install QCA (and its plugins) again when the version changes.

=====KDE >= 4.4=====

You can use the GIT clone [see TRUNK above], or your can use the latest release of QT-4.6.x from Nokia:

::http://qt.nokia.com/downloads/linux-x11-cpp

=====BRANCH up to 4.3 or a release up to 4.3.x=====

Use 4.5.3:

::http://qt.nokia.com/downloads/downloads#lgpl

Or a newer release (see above). A newer release may have issues.

=====Build=====

You will probably need to use some options for configuring Qt. Various options may be appropriate and/or needed depending on your system, what you have installed, and where it is installed. Run:

./configure --help

to see the options. There are a lot of them, but the defaults work for most of them.

Suggested configuration:

::./configure -no-separate-debug-info -plugin-sql-mysql -I/usr/include/mysql -plugin-sql-sqlite -optimized-qmake -nomake demos -nomake examples -fast -dbus

{change the include directory for mysql as needed}

If installing Phonon from KDESupport (recommended), or other separate Phonon, add the configure option:

::-no-phonon

to avoid having two versions of libraries with the same SO number.

===QCA-2.0.2 (crypto add on for Qt)===

Do not use the one in KDESupport or KDE's SVN.

Download the current release of qca from:

::http://delta.affinix.com/download/qca/2.0/

and the plugins:

::qca-cyrus-sasl
::qca-gnupg
::qca-ossl

from:

::http://delta.affinix.com/download/qca/2.0/plugins/

NOTE: qca-ossl-2.0.0-beta3 will not build against the current release of OpenSSL without being patched:

::http://home.earthlink.net/~tyrerj/kde/KDE-4/qca-ossl.patch

===LibDBusMenu-Qt===

Required for KDE >= 4.5.0. Appears to be optional for KDE-4.4.

Get release >= 0.3.5 here:

::https://launchpad.net/libdbusmenu-qt/+download

and the current release of the dependency QJson here:

::http://sourceforge.net/projects/qjson/files/

===GMM===

If you don't have Getfem++ installed, get the current release of GMM from:

::http://home.gna.org/getfem/download.html

===Qzion and Qedjie===

Get them:

::http://code.openbossa.org/projects/qedje/pages/Home

You also need the dependency EET. Get either the snapshot there o the current release here:

::http://download.enlightenment.org/releases/

PROBLEM: KDE requires QEdje >= 0.4.0 which depends on QZion >= 0.4.0 and the 0.4.0 release of QZion will not build.

If it won't build, check line 13 of the file:

:: ... /qzion-mainline/python/qzion/qzionobject.sip

It should be:

:: const char *name;

===Eigen2===

Get the current 2.0.x release from:

::http://eigen.tuxfamily.org

===Java Development Kit===

You need a Java compiler with JNI to build the Sesame2 storage backend for Soprano and a Java RunTime (JVM) to run it.

::http://java.sun.com/javase/downloads/widget/jdk6.jsp

Remember to add the "bin" directory to your path and the "lib" directory to your "/etc/ld.so.conf" file.

===Raptor, Rasqal, and Redland===

Get:

::redland-1.0.8
::rasqal-0.9.19
::raptor-1.4.21

From:

::http://download.librdf.org/source/

Note: newer versions of Redland don't work.

and the current release of the (optional) Redland dependency 3Store here:

::http://downloads.sourceforge.net/project/threestore/files/

Note: If 3store3-3.0.17 will not build against Rasqal, then skip it for now -- it is optional.

When building Redland, you will probably need to use:

::--with-bdb=

to point to your Berkeley DB directory.

If your installed SQLite is > 3.6.16, you will probably have to configure Redland with:

::--with-sqlite=no

Install in this order:

::Raptor
::Rasqal
::Redland

===Virtuoso Open-Source===

Only needed for KDE >= 4.4 and TRUNK

Get virtuoso-opensource >= 6.1.1 here:

::http://sourceforge.net/projects/virtuoso/

If you have problems, use the direct link:

::http://downloads.sourceforge.net/project/virtuoso/virtuoso/6.1.1/virtuoso-opensource-6.1.1.tar.gz

and the current release of the dependency iODBC here:

::http://www.iodbc.org/dataspace/iodbc/wiki/iODBC/Downloads

If building iODBC only for KDE, use configure parameter:

::--disable-gui

For building Virtuoso, these configure parameters are useful:

::--with-jdk4=
::--without-internal-zlib
::--with-pthreads
::--with-readline
::--with-iodbc=

If building Virtuoso only for KDE, (to save disk space) use configure parameter:

::--disable-all-vads

===KDE Supporting dependencies===

=====TRUNK=====

use KDESupport:

::svn co svn://anonsvn.kde.org/home/kde/trunk/kdesupport

If you don't want to install all the small SVN icons:

::cd kdesupport/oxygen-icons
::svn rm `find -name "small"`

=====KDE 4.6=====

There is no KDESupport-4.6 so, you need to install these packages with:

::CMAKE_INSTALL_PREFIX:PATH=/opt/KDE-4.6 for the BRANCH.

Or:

::CMAKE_INSTALL_PREFIX:PATH=/opt/KDE-4.6.x for a release.

======Automoc4======

Available here:

::ftp://ftp.kde.org/pub/kde/stable/automoc4/<version>

======Attica======

Available here:

::ftp://ftp.kde.org/pub/kde/stable/attica

======Polkit-Qt======

Available here:

::ftp://ftp.kde.org/pub/kde/stable/apps/KDE4.x/admin

======Polkit-Qt-1======

Available here:

::ftp://ftp.kde.org/pub/kde/stable/apps/KDE4.x/admin

======Soprano======

Available from Source Forge:

::http://sourceforge.net/projects/soprano/

======Akonadi======

Available here:

::http://download.akonadi-project.org

======Cagibi======

Available here:

::ftp://ftp.kde.org/pub/kde/stable/cagibi

======Strigi======

version 0.7.2 is available here:

::http://www.vandenoever.info/software/strigi/strigi-0.7.2.tar.bz2

======QImageBlitz======

Available from Source Forge:

http://sourceforge.net/projects/qimageblitz/files/qimageblitz

=====KDE 4.4 & 4.5=====

Use KDESupport:

::svn co svn://anonsvn.kde.org/home/kde/tags/kdesupport-for-<version>

This does not include: Ontologies. See below.

=====BRANCH up to 4.3 or a release up to 4.3.x=====

Use the KDESupport SVN tag that matches your KDE version. E.G. for 4.3:

::svn co svn://anonsvn.kde.org/home/kde/tags/kdesupport-for-4.3/kdesupport

=====TagLib=====

Since TagLib is also a dependency for GStreamer (gst-plugins-good), you probably don't want to have a redundant installation for the KDE-4 version that will be your 'production' version. Remove it from KDESupport SVN:

::svn rm taglib

And install the current release from:

::http://developer.kde.org/~wheeler/taglib.html

NOTE: To get GST Plugins Good to build the plugin for TagLib you need to set the environment variable:

::HAVE_CXX="yes"

before you run: "configure".

=====QCA=====

The QCA in KDESupport is not currently used (see QCA-2.0.2 above) so:

::svn rm qca

=====Phonon=====

For KDE Support 4.5 and TRUNK:

Do not use the version in KDE Support. Remove if from KDE Support:

::svn rm phonon

See below

=====Build=====

The current KDESupport may not be compatible with LFS installed FFmpeg. Use this patch:

<nowiki>------8<------8<------8<------8<------8<------8<------8<------8<------8<------8<------8<------</nowiki>
<syntaxhighlight lang="diff">
Index: strigi/src/streamanalyzer/endplugins/CMakeLists.txt
--- strigi/src/streamanalyzer/endplugins/CMakeLists.txt (revision 1096146)
+++ strigi/src/streamanalyzer/endplugins/CMakeLists.txt (working copy)
@@ -34,9 +34,3 @@
target_link_libraries(xine ${XINE_LIBRARY})
endif(XINE_FOUND)

-if(FFMPEG_FOUND)
- include_directories(${FFMPEG_INCLUDE_DIRS})
- ADD_STRIGIEA(ffmpeg ffmpegendanalyzer.cpp)
- #set_target_properties( ffmpeg PROPERTIES COMPILE_FLAGS "${FFMPEG_DEFINITIONS}" )
- target_link_libraries(ffmpeg ${FFMPEG_LIBRARIES})
-endif(FFMPEG_FOUND)
</syntaxhighlight>
<nowiki>------8<------8<------8<------8<------8<------8<------8<------8<------8<------8<------8<------</nowiki>

Or, use the FFmpeg snapshot on the CBLFS page:

::http://cblfs.cross-lfs.org/index.php/FFmpeg

This more recent snapshot requires: "libx264.so.83". The x264 snapshot on CBFLS is too old. This Source RPM worked:

::x264-0.83.2245-1plf2010.1.src.rpm

Google is your friend.

NOTE: You may need to add these parameters to the CMake command line:

::-DENABLE_FAM:BOOL=ON
::-DENABLE_EXPAT:BOOL=ON
::-DENABLE_INOTIFY:BOOL=ON
::-DGAIM_LIBS:STRING=<path>/lib
::-DGAMIN_LIBRARIES:STRING=<path>/lib

You must build with the same CMake parameters as the KDE-4 modules; specifically:

::-DCMAKE_INSTALL_PREFIX:PATH=/opt/KDE-<version>
::-DSYSCONF_INSTALL_DIR=/etc/kde-<version>

===Ontologies===

Required for KDE >= 4.4 and TRUNK.

If you checked out KDESupport from TRUNK, you have the package. Otherwise, get TRUNK here:

::git clone git://oscaf.git.sourceforge.net/gitroot/oscaf/oscaf

Or the release from Source Forge:

::http://sourceforge.net/projects/oscaf/files/shared-desktop-ontologies/

and install with CMake with:

:CMAKE_INSTALL_PREFIX:PATH=/usr

===Phonon===

=====TRUNK=====

Phonon has been moved to

::http://gitorious.org/phonon

Get it with the command:

::git clone git://gitorious.org/phonon/phonon.git

=====KDE >= 4.5=====

The current release of Phonon is available here:

::ftp://ftp.kde.org/pub/kde/stable/phonon/<version>/src

Also install back ends as needed. You must install a back end -- either GStreamer or Xine for Linux. They are available here:

::ftp://ftp.kde.org/pub/kde/stable/phonon/phonon-backend-<name>/4.4.4/<version>/src

Where <name> is one of:

:directshow
:gstreamer
:vlc
:xine

=====KDE-4.4=====

<big>KDEBindings-4.4.x will not build against Phonon from the GIT repository.</big>

Use the version in KDESupport-4.4.

=====Build=====

Install with:

::CMAKE_INSTALL_PREFIX=$QTDIR

and the rest of the CMake parameters the same as KDESupport or Supporting dependencies.

===PolKit-KDE-1===

=====KDE >= 4.4 and TRUNK=====

Use:

::ftp://ftp.kde.org/pub/kde/stable/apps/KDE4.x/admin/polkit-kde-1-0.95.1.tar.bz2

=====Build=====

The 0.95.1 tarball from the KDE FTP site will not install correctly. You need to apply this patch:

<nowiki>------8<------8<------8<------8<------8<------8<------8<------8<------8<------8<------8<------</nowiki>
<syntaxhighlight lang="diff">
diff -Naur polkit-kde-1-0.95.1.old/agent/CMakeLists.txt polkit-kde-1-0.95.1/agent/CMakeLists.txt
--- polkit-kde-1-0.95.1.old/agent/CMakeLists.txt 2009-12-23 04:31:29.000000000 -0700
+++ polkit-kde-1-0.95.1/agent/CMakeLists.txt 2010-03-25 15:54:12.000000000 -0700
@@ -11,7 +11,7 @@

target_link_libraries(polkit-kde-authentication-agent-1
${KDE4_KDEUI_LIBS}
- ${POLKITQT-1_AGENT_LIBRARY}
+ ${POLKITQT-1_LIBRARIES}
)

configure_file(polkit-kde-authentication-agent-1.desktop.in ${CMAKE_BINARY_DIR}/polkit-kde-authentication-agent-1.desktop)
@@ -25,4 +25,4 @@
set (DESKTOP_INSTALL_DIR /etc/xdg/autostart)
endif (DESKTOP_INSTALL_DIR)

-install(FILES ${CMAKE_BINARY_DIR}/polkit-kde-authentication-agent-1.desktop DESTINATION ${DESKTOP_INSTALL_DIR})
+install(FILES ${CMAKE_BINARY_DIR}/polkit-kde-authentication-agent-1.desktop DESTINATION ${KDE4_AUTOSTART_INSTALL_DIR})
</syntaxhighlight>
<nowiki>------8<------8<------8<------8<------8<------8<------8<------8<------8<------8<------8<------</nowiki>

You must build with the same CMake parameters as the KDE-4 modules; specifically:

::-DCMAKE_INSTALL_PREFIX:PATH=/opt/KDE-<version>
::-DSYSCONF_INSTALL_DIR=/etc/kde-<version>
::-DKDE4_AUTH_POLICY_FILES_INSTALL_DIR:STRING=/usr/share/PolicyKit/policy

===shared-mime-info===

You should have this installed with a prefix: "/usr". All you need to do is build KDE-4 with:

::-DUPDATE_MIME_DATABASE_EXECUTABLE:FILEPATH=/usr/bin/update-mime-database

However there appears to be a problem for KDE < 4.5

Get the current release from:

::http://www.freedesktop.org/wiki/Software/shared-mime-info

You need to install this with the same prefix as KDE4 (even if you already have it installed in "/usr") to eliminate missing MIME type errors. Currently, KDELibs won't build unless you do this. And, even if it does, you will get run time errors -- popup windows saying that certain MIME types can not be found.

This appears to be a bug that was fixed with KDE-4.5; for ealier versions this workaround does seem to work.

===KIPI Plugins===

Get the current release from:

::http://sourceforge.net/projects/kipi/

This package is dependent on KDEGraphics. The package has a lot of optional dependencies which you need to satisfy only if you want the corresponding plugins built. You should install it in the same directory where you installed KDE-4.x.y.

Be sure that you updated your: "PKG_CONFIG_PATH" to include $CMAKE_INSTALL_PREFIX/lib/pkgconfig (for example):

::/opt/KDE-4/lib/pkgconfig

===Oxygen Icons===

If you checked out KDESupport from TRUNK or the TAG: "kdesupport-for-<version>", you have them.

If you checked out KDESupport from a tag "kdesupport-<version>" up to 4.3 or didn't use KDESupport, you need to get them. If you are using SVN, that would be:

::svn co svn://anonsvn.kde.org/home/kde/tags/KDE/<version>/oxygen-icons

{where <version> is the latest release for the branch you are using (e.g. 4.3.4 for the 4.3 branch)}

Or, you can simply use TRUNK:

::svn co svn://anonsvn.kde.org/home/kde/trunk/kdesupportsvn/oxygen-icons

===LibSSH===

TRUNK and KDE-4.4 require libssh. Get the current release >= 0.4.0 from:

::http://www.libssh.org/

===Dependencies for specific KDE modules===

====KDEBindings====

=====SIP and PyQt=====

To build the Python bindings for KDE, you need the current releases of SIP and PyQt from here:

::http://www.riverbankcomputing.com/software/sip/download
::http://www.riverbankcomputing.com/software/pyqt/download

Install: "SIP" first and then: "PyQt". These are both Python add-ons so they install with:

::python configure.py
::make
::make install

=====Build Notes for PyQt=====

Unless you want to get into serious complications, you should only build PyQt against one version of Qt and you should only install one version of KDEBindings. If you try to build against multiple versions of Qt or install multiple versions of KDEBindings, with a single instance of Python (or other languages), you will install two versions of the same file in the same place.

PyQt will find Qt based on your environment variables. So, if you want to install for a version of KDE other than the one that you are currently using, be sure that these are set correctly:

::QTDIR
::QT_PLUGIN_PATH

KDEBindings is dependent on KDEGraphics (specifically Okular).

Other language dependencies are optional. If you have other supported languages installed on your system, installing KDEBindings will build bindings for them.

=====QScintilla2=====

QScintilla2 is optional. If you are installing it, get it here:

::http://www.riverbankcomputing.com/software/qscintilla/download

Install it after SIP & PyQt. It has a Qt build system, so install for Qt4 it with:

::cd Qt4
::qmake qscintilla.pro
::make
::make install

====KDEEdu====

KDEEdu might be dependent on KDEBindings.

====KDENetwork====

LibV4l

Only required for KDE >= 4.4 and TRUNK

Get the current release here:

::http://people.fedoraproject.org/~jwrdegoede/

and follow the build instructions in the README file.

=====Optional Dependencies=====

Telepathy-Qt4 is the Qt bindings for Telepathy. Since this has general usage, you should probably install it along with its semi-optional dependency telepathy-glib.

Get the current releases here:

::http://telepathy.freedesktop.org/releases/telepathy-glib/
::http://telepathy.freedesktop.org/releases/telepathy-qt4/

Install: "telepathy-glib" first and then: 'telepathy-qt4".

The output from CMake lists several other optional dependencies. It appears that these are needed to support specific functions in KDENetwork. So, if you need those functions, you need to install them. You will probably also need to install the corresponding Telepathy addons from here:

::http://telepathy.freedesktop.org/releases/

TO DO: more information needed.

Getting Started/Build/Distributions/Linux From Scratch

2011-06-28T11:31:11Z

Icwiener: Undo revision 59360 by JRT (talk) Please do not remove content just because it is shown in a broken matter.

{{Template:I18n/Language Navigation Bar|Getting_Started/Build/Distributions/LFS}}

{{TutorialBrowser|

series=Getting Started|

name=Building KDE4 From Source (Linux From Scratch requirements)|

pre=[[Getting_Started/Build|Build KDE]], [[Getting_Started/Tutorials/D-Bus/Configuration|D-Bus Configuration]]|
next=[[Getting_Started/Build|Build KDE]]|

reading=[[Development/Tutorials/CMake |Introduction to CMake]]|
}}

== CMake ==

KDE-4 and some supporting libraries use CMake.

Install the latest version from cmake.org

== Library Requirements ==

===General dependencies===

KDE-4 requires a lot of the same general purpose libraries as KDE-3.

The output from running CMake should list what you are missing -- which generally applicable libraries that you need which I will not discuss further.

===DBus and HAL===

A system should have these installed:

::DBus
::DBus-Glib
::HAL
::HAL-Info
::PolicyKit-0.9
::EggDBus
::polkit-0.97
::ConsoleKit

(and properly configured) although, strictly speaking, they are not all dependencies for KDE-4.x.

See: [http://www.linuxfromscratch.org/blfs/view/svn BLFS] for build and configure instructions.

HOWEVER, KDE-4 and KDESupport libraries may need newer versions of the libraries than those in BLFS. So, it is probably best to install the versions stated above or the latest releases of these dependencies rather than the versions in BLFS.

Some of these libraries are dependent on:

::Linux-PAM-1.1.1
::Shadow-4.1.4.2

which should be installed and configured according to the BLFS instructions.

===DocBook DTD===

KDE-4 still requires version 4.2 of:

::DocBook SGML DTD
::DocBook XML DTD.

See the instructions in this old version of BLFS:

::http://archive.linuxfromscratch.org/blfs-museum/5.0/BLFS-5.0/

===Boost C++ Libraries===

Get the current release (e.g. boost_1_42_0.tar.gz) here:

::http://sourceforge.net/projects/boost/files/boost/

=====Build=====

The current release eliminates the arcane naming issues. Although not the same as using autotools, it is now simple to build and install.

Remove the includes from previous versions:

::/usr/include/boost_<version>

and if you have a link:

::/usr/include/boost

remove that also.

Then:

::./bootstrap.sh --prefix=/usr
::./bjam install

===CLucene===
The CLucene developers suggest using the GIT repository since there are no recent releases. However, KDE-4 currently depends on the last (old) release:

::http://downloads.sourceforge.net/project/clucene/clucene-core-stable/0.9.21b/clucene-core-0.9.21b.tar.bz2

Do NOT use CMake to build it.

===Qt===

=====TRUNK=====

Use kde-qt from:

::git clone git://gitorious.org/+kde-developers/qt/kde-qt.git

This installs as Qt-<version>, so when it updates to the next version, it won't install in the same place. This means that you will need to change the <version> any place where it is specified. You will also have to install QCA (and its plugins) again when the version changes.

=====KDE >= 4.4=====

You can use the GIT clone [see TRUNK above], or your can use the latest release of QT-4.6.x from Nokia:

::http://qt.nokia.com/downloads/linux-x11-cpp

=====BRANCH up to 4.3 or a release up to 4.3.x=====

Use 4.5.3:

::http://qt.nokia.com/downloads/downloads#lgpl

Or a newer release (see above). A newer release may have issues.

=====Build=====

You will probably need to use some options for configuring Qt. Various options may be appropriate and/or needed depending on your system, what you have installed, and where it is installed. Run:

./configure --help

to see the options. There are a lot of them, but the defaults work for most of them.

Suggested configuration:

::./configure -no-separate-debug-info -plugin-sql-mysql -I/usr/include/mysql -plugin-sql-sqlite -optimized-qmake -nomake demos -nomake examples -fast -dbus

{change the include directory for mysql as needed}

If installing Phonon from KDESupport (recommended), or other separate Phonon, add the configure option:

::-no-phonon

to avoid having two versions of libraries with the same SO number.

===QCA-2.0.2 (crypto add on for Qt)===

Do not use the one in KDESupport or KDE's SVN.

Download the current release of qca from:

::http://delta.affinix.com/download/qca/2.0/

and the plugins:

::qca-cyrus-sasl
::qca-gnupg
::qca-ossl

from:

::http://delta.affinix.com/download/qca/2.0/plugins/

NOTE: qca-ossl-2.0.0-beta3 will not build against the current release of OpenSSL without being patched:

::http://home.earthlink.net/~tyrerj/kde/KDE-4/qca-ossl.patch

===LibDBusMenu-Qt===

Required for KDE >= 4.5.0. Appears to be optional for KDE-4.4.

Get release >= 0.3.5 here:

::https://launchpad.net/libdbusmenu-qt/+download

and the current release of the dependency QJson here:

::http://sourceforge.net/projects/qjson/files/

===GMM===

If you don't have Getfem++ installed, get the current release of GMM from:

::http://home.gna.org/getfem/download.html

===Qzion and Qedjie===

Get them:

::http://code.openbossa.org/projects/qedje/pages/Home

You also need the dependency EET. Get either the snapshot there o the current release here:

::http://download.enlightenment.org/releases/

PROBLEM: KDE requires QEdje >= 0.4.0 which depends on QZion >= 0.4.0 and the 0.4.0 release of QZion will not build.

If it won't build, check line 13 of the file:

:: ... /qzion-mainline/python/qzion/qzionobject.sip

It should be:

:: const char *name;

===Eigen2===

Get the current 2.0.x release from:

::http://eigen.tuxfamily.org

===Java Development Kit===

You need a Java compiler with JNI to build the Sesame2 storage backend for Soprano and a Java RunTime (JVM) to run it.

::http://java.sun.com/javase/downloads/widget/jdk6.jsp

Remember to add the "bin" directory to your path and the "lib" directory to your "/etc/ld.so.conf" file.

===Raptor, Rasqal, and Redland===

Get:

::redland-1.0.8
::rasqal-0.9.19
::raptor-1.4.21

From:

::http://download.librdf.org/source/

Note: newer versions of Redland don't work.

and the current release of the (optional) Redland dependency 3Store here:

::http://downloads.sourceforge.net/project/threestore/files/

Note: If 3store3-3.0.17 will not build against Rasqal, then skip it for now -- it is optional.

When building Redland, you will probably need to use:

::--with-bdb=

to point to your Berkeley DB directory.

If your installed SQLite is > 3.6.16, you will probably have to configure Redland with:

::--with-sqlite=no

Install in this order:

::Raptor
::Rasqal
::Redland

===Virtuoso Open-Source===

Only needed for KDE >= 4.4 and TRUNK

Get virtuoso-opensource >= 6.1.1 here:

::http://sourceforge.net/projects/virtuoso/

If you have problems, use the direct link:

::http://downloads.sourceforge.net/project/virtuoso/virtuoso/6.1.1/virtuoso-opensource-6.1.1.tar.gz

and the current release of the dependency iODBC here:

::http://www.iodbc.org/dataspace/iodbc/wiki/iODBC/Downloads

If building iODBC only for KDE, use configure parameter:

::--disable-gui

For building Virtuoso, these configure parameters are useful:

::--with-jdk4=
::--without-internal-zlib
::--with-pthreads
::--with-readline
::--with-iodbc=

If building Virtuoso only for KDE, (to save disk space) use configure parameter:

::--disable-all-vads

===KDE Supporting dependencies===

=====TRUNK=====

use KDESupport:

::svn co svn://anonsvn.kde.org/home/kde/trunk/kdesupport

If you don't want to install all the small SVN icons:

::cd kdesupport/oxygen-icons
::svn rm `find -name "small"`

=====KDE 4.6=====

There is no KDESupport-4.6 so, you need to install these packages with:

::CMAKE_INSTALL_PREFIX:PATH=/opt/KDE-4.6 for the BRANCH.

Or:

::CMAKE_INSTALL_PREFIX:PATH=/opt/KDE-4.6.x for a release.

======Automoc4======

Available here:

::ftp://ftp.kde.org/pub/kde/stable/automoc4/<version>

======Attica======

Available here:

::ftp://ftp.kde.org/pub/kde/stable/attica

======Polkit-Qt======

Available here:

::ftp://ftp.kde.org/pub/kde/stable/apps/KDE4.x/admin

======Polkit-Qt-1======

Available here:

::ftp://ftp.kde.org/pub/kde/stable/apps/KDE4.x/admin

======Soprano======

Available from Source Forge:

::http://sourceforge.net/projects/soprano/

======Akonadi======

Available here:

::http://download.akonadi-project.org

======Cagibi======

Available here:

::ftp://ftp.kde.org/pub/kde/stable/cagibi

======Strigi======

version 0.7.2 is available here:

::http://www.vandenoever.info/software/strigi/strigi-0.7.2.tar.bz2

======QImageBlitz======

Available from Source Forge:

http://sourceforge.net/projects/qimageblitz/files/qimageblitz

=====KDE 4.4 & 4.5=====

Use KDESupport:

::svn co svn://anonsvn.kde.org/home/kde/tags/kdesupport-for-<version>

This does not include: Ontologies. See below.

=====BRANCH up to 4.3 or a release up to 4.3.x=====

Use the KDESupport SVN tag that matches your KDE version. E.G. for 4.3:

::svn co svn://anonsvn.kde.org/home/kde/tags/kdesupport-for-4.3/kdesupport

=====TagLib=====

Since TagLib is also a dependency for GStreamer (gst-plugins-good), you probably don't want to have a redundant installation for the KDE-4 version that will be your 'production' version. Remove it from KDESupport SVN:

::svn rm taglib

And install the current release from:

::http://developer.kde.org/~wheeler/taglib.html

NOTE: To get GST Plugins Good to build the plugin for TagLib you need to set the environment variable:

::HAVE_CXX="yes"

before you run: "configure".

=====QCA=====

The QCA in KDESupport is not currently used (see QCA-2.0.2 above) so:

::svn rm qca

=====Phonon=====

For KDE Support 4.5 and TRUNK:

Do not use the version in KDE Support. Remove if from KDE Support:

::svn rm phonon

See below

=====Build=====

The current KDESupport may not be compatible with LFS installed FFmpeg. Use this patch:

<nowiki>------8<------8<------8<------8<------8<------8<------8<------8<------8<------8<------8<------</nowiki>
<code>
Index: strigi/src/streamanalyzer/endplugins/CMakeLists.txt
--- strigi/src/streamanalyzer/endplugins/CMakeLists.txt (revision 1096146)
+++ strigi/src/streamanalyzer/endplugins/CMakeLists.txt (working copy)
@@ -34,9 +34,3 @@
target_link_libraries(xine ${XINE_LIBRARY})
endif(XINE_FOUND)

-if(FFMPEG_FOUND)
- include_directories(${FFMPEG_INCLUDE_DIRS})
- ADD_STRIGIEA(ffmpeg ffmpegendanalyzer.cpp)
- #set_target_properties( ffmpeg PROPERTIES COMPILE_FLAGS "${FFMPEG_DEFINITIONS}" )
- target_link_libraries(ffmpeg ${FFMPEG_LIBRARIES})
-endif(FFMPEG_FOUND)
</code>
<nowiki>------8<------8<------8<------8<------8<------8<------8<------8<------8<------8<------8<------</nowiki>

Or, use the FFmpeg snapshot on the CBLFS page:

::http://cblfs.cross-lfs.org/index.php/FFmpeg

This more recent snapshot requires: "libx264.so.83". The x264 snapshot on CBFLS is too old. This Source RPM worked:

::x264-0.83.2245-1plf2010.1.src.rpm

Google is your friend.

NOTE: You may need to add these parameters to the CMake command line:

::-DENABLE_FAM:BOOL=ON
::-DENABLE_EXPAT:BOOL=ON
::-DENABLE_INOTIFY:BOOL=ON
::-DGAIM_LIBS:STRING=<path>/lib
::-DGAMIN_LIBRARIES:STRING=<path>/lib

You must build with the same CMake parameters as the KDE-4 modules; specifically:

::-DCMAKE_INSTALL_PREFIX:PATH=/opt/KDE-<version>
::-DSYSCONF_INSTALL_DIR=/etc/kde-<version>

===Ontologies===

Required for KDE >= 4.4 and TRUNK.

If you checked out KDESupport from TRUNK, you have the package. Otherwise, get TRUNK here:

::git clone git://oscaf.git.sourceforge.net/gitroot/oscaf/oscaf

Or the release from Source Forge:

::http://sourceforge.net/projects/oscaf/files/shared-desktop-ontologies/

and install with CMake with:

:CMAKE_INSTALL_PREFIX:PATH=/usr

===Phonon===

=====TRUNK=====

Phonon has been moved to

::http://gitorious.org/phonon

Get it with the command:

::git clone git://gitorious.org/phonon/phonon.git

=====KDE >= 4.5=====

The current release of Phonon is available here:

::ftp://ftp.kde.org/pub/kde/stable/phonon/<version>/src

Also install back ends as needed. You must install a back end -- either GStreamer or Xine for Linux. They are available here:

::ftp://ftp.kde.org/pub/kde/stable/phonon/phonon-backend-<name>/4.4.4/<version>/src

Where <name> is one of:

:directshow
:gstreamer
:vlc
:xine

=====KDE-4.4=====

<big>KDEBindings-4.4.x will not build against Phonon from the GIT repository.</big>

Use the version in KDESupport-4.4.

=====Build=====

Install with:

::CMAKE_INSTALL_PREFIX=$QTDIR

and the rest of the CMake parameters the same as KDESupport or Supporting dependencies.

===PolKit-KDE-1===

=====KDE >= 4.4 and TRUNK=====

Use:

::ftp://ftp.kde.org/pub/kde/stable/apps/KDE4.x/admin/polkit-kde-1-0.95.1.tar.bz2

=====Build=====

The 0.95.1 tarball from the KDE FTP site will not install correctly. You need to apply this patch:

<nowiki>------8<------8<------8<------8<------8<------8<------8<------8<------8<------8<------8<------</nowiki>
<code>
diff -Naur polkit-kde-1-0.95.1.old/agent/CMakeLists.txt polkit-kde-1-0.95.1/agent/CMakeLists.txt
--- polkit-kde-1-0.95.1.old/agent/CMakeLists.txt 2009-12-23 04:31:29.000000000 -0700
+++ polkit-kde-1-0.95.1/agent/CMakeLists.txt 2010-03-25 15:54:12.000000000 -0700
@@ -11,7 +11,7 @@

target_link_libraries(polkit-kde-authentication-agent-1
${KDE4_KDEUI_LIBS}
- ${POLKITQT-1_AGENT_LIBRARY}
+ ${POLKITQT-1_LIBRARIES}
)

configure_file(polkit-kde-authentication-agent-1.desktop.in ${CMAKE_BINARY_DIR}/polkit-kde-authentication-agent-1.desktop)
@@ -25,4 +25,4 @@
set (DESKTOP_INSTALL_DIR /etc/xdg/autostart)
endif (DESKTOP_INSTALL_DIR)

-install(FILES ${CMAKE_BINARY_DIR}/polkit-kde-authentication-agent-1.desktop DESTINATION ${DESKTOP_INSTALL_DIR})
+install(FILES ${CMAKE_BINARY_DIR}/polkit-kde-authentication-agent-1.desktop DESTINATION ${KDE4_AUTOSTART_INSTALL_DIR})
</code>
<nowiki>------8<------8<------8<------8<------8<------8<------8<------8<------8<------8<------8<------</nowiki>

You must build with the same CMake parameters as the KDE-4 modules; specifically:

::-DCMAKE_INSTALL_PREFIX:PATH=/opt/KDE-<version>
::-DSYSCONF_INSTALL_DIR=/etc/kde-<version>
::-DKDE4_AUTH_POLICY_FILES_INSTALL_DIR:STRING=/usr/share/PolicyKit/policy

===shared-mime-info===

You should have this installed with a prefix: "/usr". All you need to do is build KDE-4 with:

::-DUPDATE_MIME_DATABASE_EXECUTABLE:FILEPATH=/usr/bin/update-mime-database

However there appears to be a problem for KDE < 4.5

Get the current release from:

::http://www.freedesktop.org/wiki/Software/shared-mime-info

You need to install this with the same prefix as KDE4 (even if you already have it installed in "/usr") to eliminate missing MIME type errors. Currently, KDELibs won't build unless you do this. And, even if it does, you will get run time errors -- popup windows saying that certain MIME types can not be found.

This appears to be a bug that was fixed with KDE-4.5; for ealier versions this workaround does seem to work.

===KIPI Plugins===

Get the current release from:

::http://sourceforge.net/projects/kipi/

This package is dependent on KDEGraphics. The package has a lot of optional dependencies which you need to satisfy only if you want the corresponding plugins built. You should install it in the same directory where you installed KDE-4.x.y.

Be sure that you updated your: "PKG_CONFIG_PATH" to include $CMAKE_INSTALL_PREFIX/lib/pkgconfig (for example):

::/opt/KDE-4/lib/pkgconfig

===Oxygen Icons===

If you checked out KDESupport from TRUNK or the TAG: "kdesupport-for-<version>", you have them.

If you checked out KDESupport from a tag "kdesupport-<version>" up to 4.3 or didn't use KDESupport, you need to get them. If you are using SVN, that would be:

::svn co svn://anonsvn.kde.org/home/kde/tags/KDE/<version>/oxygen-icons

{where <version> is the latest release for the branch you are using (e.g. 4.3.4 for the 4.3 branch)}

Or, you can simply use TRUNK:

::svn co svn://anonsvn.kde.org/home/kde/trunk/kdesupportsvn/oxygen-icons

===LibSSH===

TRUNK and KDE-4.4 require libssh. Get the current release >= 0.4.0 from:

::http://www.libssh.org/

===Dependencies for specific KDE modules===

====KDEBindings====

=====SIP and PyQt=====

To build the Python bindings for KDE, you need the current releases of SIP and PyQt from here:

::http://www.riverbankcomputing.com/software/sip/download
::http://www.riverbankcomputing.com/software/pyqt/download

Install: "SIP" first and then: "PyQt". These are both Python add-ons so they install with:

::python configure.py
::make
::make install

=====Build Notes for PyQt=====

Unless you want to get into serious complications, you should only build PyQt against one version of Qt and you should only install one version of KDEBindings. If you try to build against multiple versions of Qt or install multiple versions of KDEBindings, with a single instance of Python (or other languages), you will install two versions of the same file in the same place.

PyQt will find Qt based on your environment variables. So, if you want to install for a version of KDE other than the one that you are currently using, be sure that these are set correctly:

::QTDIR
::QT_PLUGIN_PATH

KDEBindings is dependent on KDEGraphics (specifically Okular).

Other language dependencies are optional. If you have other supported languages installed on your system, installing KDEBindings will build bindings for them.

=====QScintilla2=====

QScintilla2 is optional. If you are installing it, get it here:

::http://www.riverbankcomputing.com/software/qscintilla/download

Install it after SIP & PyQt. It has a Qt build system, so install for Qt4 it with:

::cd Qt4
::qmake qscintilla.pro
::make
::make install

====KDEEdu====

KDEEdu might be dependent on KDEBindings.

====KDENetwork====

LibV4l

Only required for KDE >= 4.4 and TRUNK

Get the current release here:

::http://people.fedoraproject.org/~jwrdegoede/

and follow the build instructions in the README file.

=====Optional Dependencies=====

Telepathy-Qt4 is the Qt bindings for Telepathy. Since this has general usage, you should probably install it along with its semi-optional dependency telepathy-glib.

Get the current releases here:

::http://telepathy.freedesktop.org/releases/telepathy-glib/
::http://telepathy.freedesktop.org/releases/telepathy-qt4/

Install: "telepathy-glib" first and then: 'telepathy-qt4".

The output from CMake lists several other optional dependencies. It appears that these are needed to support specific functions in KDENetwork. So, if you need those functions, you need to install them. You will probably also need to install the corresponding Telepathy addons from here:

::http://telepathy.freedesktop.org/releases/

TO DO: more information needed.

Development/Tutorials/Localization/i18n Krazy

2011-06-27T17:25:49Z

Icwiener: Fix syntax highlighting.

== Abstract ==

There are small technical details of i18n which are not that easy to keep in mind at all times, as well as number of i18n recommendations to uphold during the development. To help you with this, the [[Development/Tutorials/Code_Checking|Krazy code checker]] also looks for some frequently encountered i18n issues. This article documents these issues as reported by Krazy, for cases when you are not sure what the remedy should be.

== Placeholders and Arguments ==

The i18n API is very strict about congruence between the <tt>%''number''</tt> placeholders in the message, and the arguments actually supplied to substitute them. Effectively, the placeholders directly index arguments, albeit one- rather than zero-based.

; <tt>"wrong argument count, have ''num1'' need ''num2''"</tt>
:: Either some of the arguments have not been provided, or there is a stray placeholder inside the message string. A likely cause is forgetting that in KDE4, arguments are added as parameters to the i18n call itself, rather than appended via <tt>arg()</tt> methods as in KDE3:
<syntaxhighlight lang="cpp-qt">
i18n("Found key: %1", key); // correct
i18n("Found key: %1").arg(key); // ***wrong
</syntaxhighlight>

; <tt>"too many arguments, have ''num'' max 9"</tt>
:: i18n calls can take at most 9 arguments as parameters to the call. If more than that is needed, the <tt>ki18n*()</tt> series of calls must be used, see the documentation to {{class|KLocalizedString}} class. The calls with more than 9 parameters are extremely rare, though.

; <tt>"gaps in placeholder numbering, ..."</tt>
:: Except in case of plural i18n calls, there must be no gaps in placeholder sequence, starting from <tt>%1</tt>. In plural calls, the placeholder of the first number (which determines plural) form, may be omitted, both in singular and plural:
<syntaxhighlight lang="cpp-qt">
i18n("Line: %1 Column: %2", lineNo, colNo); // correct
i18n("Line: %1 Column: %3", lineNo, colNo); // ***wrong

i18np("Found a file in folder %2",
"Found %1 files in folder %2", nfiles, folder); // correct
i18np("Found a file in folder %2",
"Found some files in folder %2", nfiles, folder); // also correct
i18np("Found a file in folder %1",
"Found some files in folder %1", folder, nfiles); // ***wrong
</syntaxhighlight>

; <tt>"legacy %n placeholder in plural call"</tt>
:: This is a remnant from KDE3, where in plural i18n calls, the argument determining the plural form had special <tt>%n</tt> placeholder. In KDE4, all arguments have ordinary <tt>%''number''</tt> placeholders, as in the examples above (the plural form is decided upon the lowest-numbered argument that is an integer).

== Ambiguous Short Messages ==

English is a rather noninflected language compared to many others; single English word can frequently be noun, verb, or adjective, while retaining its original form. This presents frequent problems for the translator while translating into inflected languages when the original message is short, especially single-worded. The solution is to [[Development/Tutorials/Localization/i18n#Adding_Context|add context]] to the message via <tt>i18nc()</tt> call.

; <tt>"single adjective as message, probably ambiguous; ..."</tt>
:: Words that can be treated as adjectives are especially prone to ambiguities. Therefore Krazy checks single-worded messages against a list of adjectives collected from the KDE codebase, and issues this warning if the matching message does not have a context. For example:
<syntaxhighlight lang="cpp-qt">
titleFinal = title.isEmpty() ?
i18n("Unknown") : title; // ambiguous
titleFinal = title.isEmpty() ?
i18nc("An unknown title", "Unknown") : title; // clarified
</syntaxhighlight>

; <tt>"reported ambiguous message by translators; ..."</tt>
:: There are other troublesome words, or even phrases, which were explicitly reported by translators as ambiguous. This warning means that such a message without context has been detected.

While you are at adding contexts, consider providing the appropriate [[Development/Tutorials/Localization/i18n_Semantics#Context_Markers|KUIT context marker]] as well, which will further zero-in translators' job:
<syntaxhighlight lang="cpp-qt">
titleFinal = title.isEmpty() ?
i18nc("@item:intable An unknown title", "Unknown") : title;
// way to go!
</syntaxhighlight>

The ambiguity warning can also be issued for <tt>.ui</tt>, <tt>.rc</tt> and <tt>.kcfg</tt> files. In <tt>.ui</tt> files, text labels can have the <tt>comment</tt> attribute (accessible in Qt Designer as a "disambiguation" property to the label, or "comment" prior to Qt 4.5), which can be used for adding contexts same as the first argument of the <tt>i18nc()</tt> call. In <tt>.rc</tt> and <tt>.kcfg</tt> files, contexts are added via the <tt>context</tt> attribute.

== Number Formatting ==

The number-valued (either integer or real) arguments to i18n messages are formatted automatically into given language, without programmer's intervention. Using other methods to format numbers into strings may circumvent proper formatting for the language.

; <tt>"use of QString::number() on an argument"</tt>
:: <tt>QString::number()</tt> should never be used to format "amount" numbers, because within KDE code it will do so using English conventions. However, sometimes the number is not an amount, e.g. port number 15000 should not be formatted as "15,000" in English; use <tt><numid></tt> KUIT tag in this situation:
<syntaxhighlight lang="cpp-qt">
i18n("Number of pages: %1", numPages); // good, localized amount format
i18n("Connected to port %1.", port); // bad, amount format not desired
i18n("Connected to port %1.", QString::number(port)); // bad, not localized
i18n("Connected to port <numid>%1</numid>.", port); // good
</syntaxhighlight>

;; <tt>"use of KLocale::formatNumber() on an argument (...)"</tt>
:: A smarter way to format numbers is using <tt>KLocale::formatNumber()</tt>, which will honor user's settings. However, then the format cannot be decided upon the language of the particular message in question (some applications may not have translations), so it's best avoided in i18n arguments. Use it for "live numbers", e.g. in spreadsheet tables and calculator displays, where the format should match user's number-typing habit.

Even when the complete message is a single number, it should be i18n'd, with a proper context:
<syntaxhighlight lang="cpp-qt">
result = QString::number(z); // bad
result = i18nc("Atomic number", "%1", z); // good
</syntaxhighlight>

When the number is to be formatted in a special way (field width, number of decimals, etc.) into the message, still neither <tt>QString::number()</tt> nor <tt>KLocale::formatNumber()</tt> should be used, but <tt>ki18n*()</tt> series of calls with <tt>subs()</tt> methods (see {{class|KLocalizedString}} documentation):
<syntaxhighlight lang="cpp-qt">
i18n("Percent complete: %1", QString::number(percent, 'f', 1)); // bad
ki18n("Percent complete: %1").subs(percent, 0, 'f', 1).toString(); // good
</syntaxhighlight>

== HTML and KUIT Markup ==

Every i18n message in KDE4 is effectively XML markup. HTML tags come from Qt's rich text, and can be used only in rich-text capable widgets; KUIT tags are new KDE4 [[Development/Tutorials/Localization/i18n_Semantics|semantic markup]], which should be preferred to HTML, and can be used in ''any'' i18n message (plain or rich-text output is decided on the basis of [[Development/Tutorials/Localization/i18n_Semantics#Context_Markers|context marker]]).

; <tt>"malformed markup (unmatched tags, etc.)"</tt>
:: Since every message is XML, all tags must be properly closed. Opening <tt></tt> must not miss closing <tt></tt>, etc. This also holds for breaking HTML tags like <tt> </tt> and <tt><hr></tt>, which must be closed in place: <tt> </tt>, <tt><hr/></tt>.

: Verbatim greater-than sign means opening of a tag, which is not always meant. This can be avoided by use of predefined XML <tt>&lt;</tt> entity (other predefined entities are <tt>&gt;</tt>, <tt>&amp;</tt>, <tt>&apos;</tt>, and <tt>&quot;</tt>), but for a frequent case of marking generic or user-replaceable text, it is better to use <tt><placeholder></tt> KUIT tag:
<syntaxhighlight lang="cpp-qt" line="">
i18n("headers go into <includes>"); // ***error in XML markup
i18n("headers go into <includes>"); // no markup problem, but...
i18n("headers go into <placeholder>includes</placeholder>"); // better
</syntaxhighlight>

: Given it's frequency, it is not needed to use <tt>&amp;</tt> for shortcut markers; there is some heuristics around XML parsing to allow presence of naked &. Basically, <tt>&amp;</tt> is needed only in the rare case of <tt>&''no_whitespace_sequence'';</tt> pattern which is ''not'' meant as an XML entity.

; <tt>"unclosed ... use proper paragraphs ... instead"</tt>
:: This just signals a particularly frequent markup problem, that of <tt> </tt> not closed in place, like <tt> </tt>. Also, sometimes <tt> </tt> is used to split logical paragraphs (especially when doubled, <tt> </tt>), where proper paragraph tags should be used instead.

; <tt>"''tag'' is neither KUIT nor HTML tag"</tt>
:: Some of the tags in the message is simply unknown, and will not be understood at runtime. If it is not a typo, but the message is really speaking about tags to the user (e.g. in a HTML editing application), use <tt>&lt;foo&gt;</tt> pattern.

; <tt>"HTML tag ''tag'' is not advised with KUIT markup"</tt>
:: When Krazy encounters the KUIT context marker in a message, it assumes that message is semantically tagged, and disapproves of some HTML tags which are best replaced with semantic equivalents. For example:
<syntaxhighlight lang="cpp-qt">
i18n("@info:whatsthis",
"...this cannot be undone."); // Krazy complains
i18n("@info:whatsthis",
"...this <emphasis>cannot</emphasis> be undone."); // fine

i18n("@info",
"Really delete %1?", filename); // complains
i18n("@info",
"Really delete <filename>%1</filename>?", filename); // fine
</syntaxhighlight>

; <tt>"tag ''tag1'' cannot be subtag of ''tag2''"</tt>
; <tt>"tag ''tag'' has no ''att'' attribute"</tt>
; <tt>"tag ''tag'' cannot have text content"</tt>
:: These are validity checks for KUIT markup, a bit relaxed form of formal XML validation. The rules of which KUIT tag can contain which, and so on, are given with [[Development/Tutorials/Localization/i18n_Semantics#Semantic_Tags|tag descriptions]].

== KUIT Context Markers ==

Semantic [[Development/Tutorials/Localization/i18n_Semantics#Context_Markers|context markers]] give great deal of information to translators of where and how the message is used at runtime. Providing them for ''any'' future messages is strongly encouraged, and even equipping existing messages when not in message freeze is welcomed. Krazy helps with the following checks.

; <tt>"missing KUIT context marker"</tt>
:: If Krazy detects that the source file has a number of messages equipped with KUIT context markers, above some threshold, it assumes that developer's intention was to have all messages marked (as is recommended), and issues this warning for any non-marked message.

; <tt>"invalid semantic role ''role''"</tt>
; <tt>"invalid interface subcue ''cue'' to role ''role''"</tt>
; <tt>"invalid visual format ''fmt''"</tt>
:: Krazy checks that all ingredients of the context marker are defined, and that a particular combination of them is valid.

; <tt>"expected context marker ''ctxmark1'', got ''ctxmark2''"</tt>
:: For messages used in some boiler-plate situations, canonical context markers have been established. Krazy warns if the context marker to such a message, although valid by itself, was not the expected one. For example, such messages are encountered in setting up the {{class|KAboutData}} information.

== UI files ==
When Krazy complains about ambiguity in i18n translation in an UI file. You can either add a comment="" attribute using QtDesigner or using a text editor.

== Contact ==

For any questions or suggestions, Krazy i18n checks are presently maintained by Chusslove Illich <caslav.ilic@gmx.net>.

Development/Tutorials/Localization/i18n Semantics

2011-06-27T17:20:13Z

Icwiener: Fix syntax highlighting.

== 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 context marker is present, sometimes the programmer may want to provide an additional "free-form" description to translators, in order 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 withing 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.

Development/Tutorials/Localization/i18n Challenges

2011-06-27T17:09:28Z

Icwiener: Fix syntax highlighting.

{{Template:I18n/Language Navigation Bar|Development/Tutorials/Localization/i18n Challenges}}

{{TutorialBrowser|

series=Localization|

pre=[[../i18n| Writing Applications With Localization in Mind]] [[../i18n Build Systems|Incorporating i18n Into the Build System]]|

name=Common i18n Challenges and Solutions|

}}

== Abstract ==

The localization process can, at times, be tricky. 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, or moving applications between KDE modules.

{{note|The references to Makefile.am's needs to be ported to CMake.}}

== Message Freezes ==

As a release date starts getting close, most software projects (including the KDE project) will freeze all changes to user visible strings. This allows translators a chance to do their work without it being constantly disrupted by changes to strings thereby wasting their efforts. If you change i18n strings in your application during such freezes it creates more work (and confusion) for the teams and could prevent your application from being released with translations.

{{note|If your application is part of KDE that is periodically announced and released, you must pay attention to announcements on the mailing lists for message freezes. When a message freeze is in place, you must not change any of the translatable strings in your application or its Handbook.}}

If you find a GUI string that you feel must be fixed or added during a message freeze, ask your translation teams first. In the KDE project, that would be done by emailing the kde-i18n-doc list. Changing a string or adding a new one will not invalidate the entire translation, but annoys the translation teams who are trying to provide a complete and proper translation for your application.

=== Fixing Messages During A Freeze ===

It's message freeze time and you forgot to code with the <tt>i18n()</tt> function or forgot to include a file in the Makefile.am messages target, or you need to make some changes to existing strings. What should you do?

If you need to change an existing string, ask the translators first for permission first before you make the fixes. In KDE, that would be the kde-i18n-doc mailing list.

If you need to add untranslated strings due to forgotten <tt>i18n()</tt> or mistakes in the build system, go ahead and make the fixes. When you commit the fixes, write "untranslated strings" in the commit message so that translators will know why you are committing string changes during a message freeze. It is a good idea to email the translation teams to let the translators know that you've added additional strings.

{{note|If the translator's don't have time to translate the additional strings, they will display in English at runtime.}}

It is considered a violation of the message freeze to add a brand new translated string to your code where the string did not exist untranslated before. So changing this:

<syntaxhighlight lang="cpp-qt">
QMessageBox::warning(0, "Starting KTTSD Failed", error );
</syntaxhighlight>

to this:

<syntaxhighlight lang="cpp-qt">
QMessageBox::warning(0, i18n( "Starting KTTSD Failed"), error );
</syntaxhighlight>

is OK, but adding the call to QMessageBox where it didn't exist before will raise objections from the translators.

In the latter case, ask on the kde-i18n-doc mailing list first. In general, the criteria for modifying or adding strings is a potentially severe misunderstanding of a message, especially if it means a risk of losing data.

{{tip|You may see translators refer to "fuzzy" strings. Fuzzy strings come about when a string has already been translated and then is changed a little bit later. xgettext leaves the original translation in the .po file, but marks the string as fuzzy. The translator must look at the translation to determine if a change is needed and remove the fuzzy flag, otherwise the translation will not be used at runtime. In short, if you change strings in your app, they will generate fuzzies for the translators.}}

=== Handbooks ===

Handbooks especially should not be touched during a message freeze. This is because changing a Handbook (even a small change) can prevent the entire translated Handbook from being released. For this reason, you should watch the release cycle plans carefully and try to complete your Handbook at least 3 to 4 weeks before the message freeze.

If you do make a late change to a Handbook, it will be up to the translation team whether to apply the fix to their translation or not. If the team has already generated the translated Handbook, the uncorrected version may end up being released.

Freezes are often announced in two phases. A feature freeze means GUI string changes should not be made without first asking permission on the kde-i18n-doc mailing list. Handbook changes are OK at this time. A hard freeze means you must not make any more changes to code or to the Handbook.

If you find a Handbook string that you feel must be fixed or added during a freeze, ask first on the kde-doc-english mailing list. Changing the Handbook, even a tiny change, can invalidate the entire Handbook. Once a hard freeze is in place, fixes should be sent to kde-doc-english as patch files (svn diff). The fixes will not be translated, but they will be incorporated into the English-only version of the Handbook.

Questions about Handbook translation should be sent to the kde-doc-english mailing list.

== Independent Releases ==

If your application is not part of an official KDE release cycle (e.g. it is in KDE Extra Gear or in an outside repository altogether), it will be up to you to plan releases and coordinate with the translation teams. When you want to do a release, send an email to the kde-i18n-doc mailing list with the following information:

* The name of your application and its repository location.
* Your planned message freeze date, the date after which you will not make any more changes that affect i18n strings.
* Your planned code freeze date, the date after which no more changes except for severe bug fixes will be made.
* Your planned release date.

You should provide at least 3 weeks between the message freeze date and release date - more if your application is large and complex. If your application has a Handbook, you should provide even more time.

It is a good idea to avoid time periods when KDE or KOffice are in message freeze, since the translators will be very busy at these times.

If you are distributing your code to translators via a source tarball, you should first ask for volunteers. Of course, the message freeze occurs when you send them the tarball. Your tarball must have all the .pot files and prepared po folders.

== KDE Extra Gear Releases ==

Applications in the extragear module have a special procedure for handling translations. When an extragear application becomes stable (mostly at message freeze), the maintainer should copy the application to the appropriate extragear directory in branches/stable/extragear. In addition the whole set of translation template files (.pot) and translation files (.po), including eventual documentation, of the application must be copied to the appropriate places in branches/stable/l10n. This serves as a signal to translators that the application is ready for final translation work in preparation for release.

== Translating UI, RC, and KCFG files ==

User visible strings usually origin not only from code files, but also from three other file types, ui, rc and kcfg files. UI files are the user interface descriptions, which are edited using QtDesigner. Here the text of labels and other ui elements are in need of localized versions. Likewise for the RC files, which are KXmlGui interface descriptions for embedded components. The KCFG files are the configuration data descriptions, which are used to automatically create configuration control code. While that is not related to the user interface, the same KCFG files are also used as the base for the generic runtime editing with [http://extragear.kde.org/apps/kconfigeditor/ KConfigEditor], so the parameter descriptions also need localized versions.

The strings are handled by the translation system by having them extracted by a program called extractrc, which creates a temporary code file that is than simply included by gettext. So extend the messages target in Makefile.am this way:

messages: rc.cpp
$(EXTRACTRC) */*.kcfg >> rc.cpp
$(EXTRACTRC) */*.ui >> rc.cpp
$(EXTRACTRC) */*.rc >> rc.cpp
$(XGETTEXT) rc.cpp */*.cpp */*.h -o $(podir)/my_program.pot

If there are strings translators need context information for, they can be supplied via <tt>context</tt> attribute in RC and KCFG files:

<text context="Create new cup of tea">&New...</text>
<label context="Fancy for mixture">Concoction</label>
<whatsthis context="A concoction">Not entirely unlike tea</whatsthis>

and in QtDesigner as the "disambiguation" property to text labels (or "comment" prior to Qt 4.5), which become <tt>comment</tt> attributes in the UI file itself.

Also, if that is more suitable, a parameter can be added to the call to extractrc by which the same context is provided to all strings extracted from the file. Example:

messages: rc.cpp
$(EXTRACTRC) --context=my_context my_config.kcfg >> rc.cpp
$(EXTRACTRC) --context=other_context */*.ui >> rc.cpp
$(EXTRACTRC) --context=and_some_more */*.rc >> rc.cpp
$(XGETTEXT) rc.cpp */*.cpp */*.h -o $(podir)/my_program.pot

== Translating Data ==

If your application uses data that you want the translators to translate for you, there are a couple of solutions. If the data is a single string, and you want to use a translation of the string that is different from the user's desktop language setting, you can create a .desktop file and extract the translated string from it. For example, the KDE text-to-speech daemon (KTTSD) has the following {{path|kcmkttsd_testmessage.desktop}} file:
<syntaxhighlight lang="ini">
[Desktop Entry]
Encoding=UTF-8
NoDisplay=true
Name=The text-to-speech system seems to be functioning properly.
</syntaxhighlight>
Notice the <tt>NoDisplay=true</tt> line. The translators will translate the Name line and scripty will insert the translations back into the .desktop file. At runtime, KTTSD uses the following code to get a test message to speak in the language of the synthesizer's voice, not the user's desktop language:

<syntaxhighlight lang="cpp-qt">
QString key = "Name[" + languageCode + "]";
QString result;
QString def;
QFile file(locate("data", "kttsd/kcmkttsd_testmessage.desktop"));
if (file.open(IO_ReadOnly))
{
QTextStream stream(&file);
stream.setEncoding(QTextStream::UnicodeUTF8);
while ( !stream.atEnd() ) {
QString line = stream.readLine(); // line of text excluding '\n'
QStringList keyAndValue = QStringList::split("=", line);
if (keyAndValue.count() == 2)
{
if (keyAndValue[0] == key)
{
result = keyAndValue[1];
break;
}
// Use English default if not found.
if (keyAndValue[0] == "Name") def = keyAndValue[1];
}
}
file.close();
}
if (result.isEmpty()) {
result = def;
}
return result;
</syntaxhighlight>

If your program has larger amounts of data, an XML file is a good way to go. For example, KTTSD maintains a list of Festival synthesizer voices in an XML file called voices. Here's a sample portion from that file:
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<voices>
<voice>
<code>kal_diphone</ code>
<language>en_US</language>
<codec>ISO 8859-1</codec>
<gender>male</gender>
<name>American Male</name>
</voice>
</syntaxhighlight>
{{improve}}

The Makefile.am extracts the name strings from this file like this:

messages: rc.cpp
$(EXTRACTRC) */*.rc */*/*.rc >> rc.cpp
$(EXTRACTRC) */*.ui */*/*.ui >> rc.cpp
$(EXTRACTRC) --tag=name --context=FestivalVoiceName plugins/festivalint/voices >> rc.cpp
$(XGETTEXT) rc.cpp */*.cpp */*.h */*/*.cpp */*/*.h -o $(podir)/kttsd.pot

Notice that the translators are given a context to help them to translate the voice names. At runtime, KTTSD parses the voices file and displays the translated name of each voice (in the user's desktop language) using code like this:

<syntaxhighlight lang="cpp-qt">
QDomNode childNode = node.namedItem("name");
if (!childNode.isNull())
QString name = i18n("FestivalVoiceName", childNode.toElement().text().utf8());
</syntaxhighlight>

== Examining .po Files ==

You can look at the translated .po files to see if a string is present and has been translated. For example, here's a portion of {{path|l10n/de/messages/kdebase/konqueror.po}}:

#: konq_mainwindow.cc:3707 konq_tabs.cc:84
msgid "&New Tab"
msgstr "Neues &Unterfenster"

The string to be translated is given on the <tt>msgid</tt> line. The translated string is on the <tt>msgstr</tt> line. Notice that the exact same string to translate came from {{path|konq_mainwindow.cc}} and also from {{path|konq_tabs.cc}}. This saves the translators from having to translate the same identical string twice.

You can also use KBabel to examine .po files. KBabel is part of the {{path|kdesdk}} module.

== Coding in a Foreign Language ==

If you are not comfortable with the English language, you may have coded your application using strings in your native language. You must convert all your code to English before it can be translated by the translation teams.

One solution is to get someone who understands both English and your language to help you with this. You can also ask for a volunteer on the kde-i18n-doc mailing list. You will create your .pot file (see Distributing message catalogs [*]) and send it to them. They will translate it to English and send you back a .po file. Using cut and paste, put the English strings into your code.

If you do this, it is still a good idea to have an English speaker review your code for any mistakes. You can use [http://cli-apps.org/content/show.php/poreviewtool?content=132789 poreviewtool], a tool which makes the review of the English strings easier (relays also on .po files, but makes the handling much easier if you want to review continuously.)

== Merging .po Files ==

If you made the mistake of creating a single .pot file for all the components in my application and the translators have already created the .po files what should you do so that no work (and translations) are lost ?

Correct your code and the build system. Commit the changes to the repository. Ask one of the KDE admins to merge the existing .po files. She will need to know the exact names of all the .po files, which module they are in, and the name of the desired merged .po file. The admin will have to wait for scripty to generate your new .pot file before doing the merge.

== Deleting obsolete .pot files ==

If you change the build for you application so that it no longer generates a .pot file, or generates a .pot file with a different name, the old .pot file will not automatically disappear from the code repository.

You must delete it yourself from the templates folder in the l10n module. You should also send an email to the kde-i18n-doc mailing list advising translators that they may delete the .po file. If you do not do this, the translators will waste their time working on an obsolete file.

== Handbook entity errors ==

Sometimes, when building Handbooks in the {{path|l10n/xx/docs}} folders, you may get entity errors. First of all, make sure your kdelibs/kdoctools folder is up-to-date and installed. If that doesn't fix the problem, it may be that the translator made an error, leaving an entity in the .docbook file that is defined in English but not in the translated language. In many cases, the translators haven't finished the translation. Contact the translation team.

For example, the English entity eg is defined in the {{path|kdelibs/kdoctools/customizations/en/user.entities}} file but is not defined in the German kdelibs/kdoctools/customizations/de/user.entities. It must be replaced by the translator with the entity zb (Zum Beispiel).

[[Category:Programming]]

Development/Tutorials/Localization/i18n Build Systems

2011-06-27T17:04:11Z

Icwiener: Fix syntax highlighting.

{{Template:I18n/Language Navigation Bar|Development/Tutorials/Localization/i18n Build Systems}}

{{TutorialBrowser|

series=Localization|

name=Building KDE's l10n Module|

pre=[[../i18n|Writing Applications With Localization in Mind]]|
next=[[../Language Change|Dealing with language changes]]|
}}

== Abstract ==

Now that your application is ready to be localized, we next look at how to incorporate the necessary mechanisms into the CMake build system of your application.

First we'll explain the "theory" of the steps that need to happen from extracting message strings to installing the generated .po files. After that we'll look at how to implement those steps ([[#Theory: The xgettext toolchain]]). If your application is developed in KDE's subversion repository, many of those steps will happen automatically (see [[#handling i18n in KDE's subversion repository]]). Else you will want to read on in the [[#handling i18n in third party applications]] section.

== Theory: The xgettext toolchain ==

Making translations work consists of the following steps:
# Extract the translatable strings
# Merge the new or changed strings with existing translations
# Compile the translations into message catalogs
# Install the message catalogs
# Use the message catalogs in the application

=== Extracting the strings ===

In this step, all the strings you marked as i18n()/ki18n()/etc. in your sources need to be collected into a translation template (.pot) file. Some translateable strings are also contained in .ui, .rc, or .kcfg files. Also tips-of-the-day need to be collected into the .pot file.

These steps are handled by {{path|xgettext}}, {{path|extractrc}}, and {{path|preparetips}} programs, respectively. In some cases you may also need {{path|extractattr}}.

=== Merging translations ===

Generally, only a few translatable string will change at a time, in an application. Some will be removed, some will be added, some will be changed into different strings, and some will be moved around in the source files. These changes need to be reflected in the translations, but of course it would be a huge effort to redo the entire translation every time a string was changed. Rather the changes should be merged with the existing translations. This is the job of the {{path|msgmerge}} tool.

=== Compiling the translations ===

In order to make message lookup fast, the .po files need to be compiled into so-called "message catalogs" (.mo / .gmo). This is done using the {{path|msgfmt}} tool.

=== Installing the message catalogs ===

The compiled message catalogs need to be installed alongside the application. In KDE, the standard location for message catalogs is {{path|$KDEDIR/share/locale/xx/LC_MESSAGES/}}.

=== Using the message catalogs ===

Finally, when the application is run, it needs to load the appropriate message catalog in order to be able to look up and show translated strings. In KDE applications, this is the job of the {{class|KLocale}} class, and in the great majority of cases happens automatically.

For some special cases, such as plugins, look at [[#Runtime Loading Of Catalogs]].

== handling i18n in KDE's subversion repository ==

If your application is developed inside KDE's subversion repository, most of the steps outlined above are automated. In this case, generally, all you will need to do is provide a simple script called {{path|Messages.sh}}, which we will look at below.

In addition, if your top-level folder and .pot file have the same name, the svn2dist script will automatically include .po files when you use it to make a source tarball for your app.

Of course, for the curious, a more detailed account of what happens behind the scences is also provided.

=== Writing a Messages.sh script ===

Basically, the only thing that is necessary to prepare and install translations for applications in KDE's subversion repository, is to provide information, which sources, ui-files or tips need to be translated. For this purpose, you write a small script called {{path|Messages.sh}} and place it in your sources. Here is an example with inline comments:

<syntaxhighlight lang="cpp-qt">
#!bin/sh

# invoke the extractrc script on all .ui, .rc, and .kcfg files in the sources
# the results are stored in a pseudo .cpp file to be picked up by xgettext.
$EXTRACTRC `find . -name \*.rc -o -name \*.ui -o -name \*.kcfg` >> rc.cpp
# if your application contains tips-of-the-day, call preparetips as well.
$PREPARETIPS > tips.cpp
# call xgettext on all source files. If your sources have other filename
# extensions besides .cc, .cpp, and .h, just add them in the find call.
$XGETTEXT `find . -name \*.cc -o -name \*.cpp -o -name \*.h` -o $podir/APPNAME.pot
</syntaxhighlight>

As you can see, this script contains only three actual lines of code, and not all may even be needed. The $XGETTEXT, $PREPARETIPS, $EXTRACTRC, and $podir environment variables are predefined, you do not need to worry about setting these. The only thing that you will need to do is to replace "APPNAME" with the name of your application (but see [[#Naming .pot Files]] for exceptions).

Translatable strings are automatically extracted from C++ files. For non-C++ files, the following scripts are used
* $EXTRACTRC - Extract translatable strings from xml configuration and ui files.
* $EXTRACTQML - Extract translatable strings from QML files.
* $EXTRACT_GRANTLEE_TEMPLATE_STRINGS - Extract translatable strings from Grantlee template files.

Try to make sure your Messages.sh script collects only those messages that are really needed. If in doubt, look at other Messages.sh files in the KDE subversion repository for inspiration, or -- of course -- ask.

=== What's happening behind the scenes ===

{{tip|If your application is in the KDE code repository, all this happens automatically. If your code is not in the KDE repository, you must perform these steps yourself. See [[#handling i18n in third party applications]].}}

Periodically, the script {{path|extract-messages.sh}} (a.k.a. scripty) runs on the KDE server. This program basically calls all Messages.sh scripts in the repository with the appropriate parameters. The extracted messages are stored in template (.pot) files in the templates folder of the l10n module. See [[What Is Scripty]] for more information.

The KDE translation teams translate the messages and commit them into a messages folder corresponding to the language, which is further broken down by module. For example, German translated messages for konqueror are committed to {{path|l10n/de/messages/kdebase/konqueror.po}}.

When the l10n module is built, the .po files are compiled into a binary format for fast lookup and installed as .mo files to {{path|$KDEDIR/share/locale/xx/LC_MESSAGES/}}, where xx is the two-letter ISO 639 code for the language. These are called the message catalogs.

At runtime, the <tt>i18n(...)</tt> function, using the original string you coded, looks up the string in the message catalog of the user's desktop language and returns the translated string. If the message catalog is missing, or the specific string is not found, <tt>i18n(...)</tt> falls back to the original string in your code.

.desktop files in your project are handled separately. {{path|makemessages}} extracts strings, such as Name and Comment from the .desktop files and places them into a file named {{path|desktop_mmmm.pot}}, where mmmm is the module name, in the templates folder. Once translators have translated this file, makemessages inserts the translated strings back into the .desktop files. The list of strings extracted is in {{path|l10n/scripts/apply.cc}}. Here's the code that checks for them:

<syntaxhighlight lang="cpp-qt">
if (checkTag("Name", in, argc, argv, newFile))
continue;
if (checkTag("Comment", in, argc, argv, newFile))
continue;
if (checkTag("Language", in, argc, argv, newFile))
continue;
if (checkTag("Keywords", in, argc, argv, newFile))
continue;
if (checkTag("About", in, argc, argv, newFile))
continue;
if (checkTag("Description", in, argc, argv, newFile))
continue;
if (checkTag("GenericName", in, argc, argv, newFile))
continue;
if (checkTag("Query", in, argc, argv, newFile))
continue;
if (checkTag("ExtraNames", in, argc, argv, newFile))
continue;
</syntaxhighlight>

== handling i18n in third party applications ==

If your application is developed outside of KDE's subversion repository, you need to take care of generating and installing message catalogs yourself. This is not too hard to do, but you should make sure you have a basic understanding of all steps involved, so you will probably want to read [[#Theory: The xgettext toolchain]], first.

Also, there is more than one way to deal with i18n in your application. We will outline one approach to do so for simple applications, but you may want to diverge from this, if you like to.

=== General considerations ===

The i18n generation process can roughly be divided into two steps:

# Extracting and merging messages
# Compiling and installing message catalogs

The first step really concerns the ''sources'', while the second step is a natural part of compiling and installing an application. Hence, while the second step should definitely be incorporated into the build system for your application (we assume CMake, here), there is no striking reason for the first step to be handled by the build system.

In fact, the extraction and merging of messages does not map well onto the CMake concept of out-of-source builds, and CMake can't provide too much help for this step, either.

Hence, in this tutorial, we will handle the first step with a standalone shell script, and only the second step will be handled by CMake.

=== Extracting and merging messages ===

If you have read the section [[#handling i18n in KDE's subversion repository]] you will know that in the KDE repository, message extraction and merging is handled by a simple script called Messages.sh, which is invoked by a script called {{path|extract-messages.sh}}. Outside of KDE's repository, you will need to take care of both parts, but fortunately, this is easy enough. Here's a sample script:

<syntaxhighlight lang="bash">
#!/bin/sh
BASEDIR="../rkward/" # root of translatable sources
PROJECT="rkward" # project name
BUGADDR="http://sourceforge.net/tracker/?group_id=50231&atid=459007" # MSGID-Bugs
WDIR=`pwd` # working dir

echo "Preparing rc files"
cd ${BASEDIR}
# we use simple sorting to make sure the lines do not jump around too much from system to system
find . -name '*.rc' -o -name '*.ui' -o -name '*.kcfg' | sort > ${WDIR}/rcfiles.list
xargs --arg-file=${WDIR}/rcfiles.list extractrc > ${WDIR}/rc.cpp
# additional string for KAboutData
echo 'i18nc("NAME OF TRANSLATORS","Your names");' >> ${WDIR}/rc.cpp
echo 'i18nc("EMAIL OF TRANSLATORS","Your emails");' >> ${WDIR}/rc.cpp
cd ${WDIR}
echo "Done preparing rc files"

echo "Extracting messages"
cd ${BASEDIR}
# see above on sorting
find . -name '*.cpp' -o -name '*.h' -o -name '*.c' | sort > ${WDIR}/infiles.list
echo "rc.cpp" >> ${WDIR}/infiles.list
cd ${WDIR}
xgettext --from-code=UTF-8 -C -kde -ci18n -ki18n:1 -ki18nc:1c,2 -ki18np:1,2 -ki18ncp:1c,2,3 -ktr2i18n:1 \
-kI18N_NOOP:1 -kI18N_NOOP2:1c,2 -kaliasLocale -kki18n:1 -kki18nc:1c,2 -kki18np:1,2 -kki18ncp:1c,2,3 \
--msgid-bugs-address="${BUGADDR}" \
--files-from=infiles.list -D ${BASEDIR} -D ${WDIR} -o ${PROJECT}.pot || { echo "error while calling xgettext. aborting."; exit 1; }
echo "Done extracting messages"

echo "Merging translations"
catalogs=`find . -name '*.po'`
for cat in $catalogs; do
echo $cat
msgmerge -o $cat.new $cat ${PROJECT}.pot
mv $cat.new $cat
done
echo "Done merging translations"

echo "Cleaning up"
cd ${WDIR}
rm rcfiles.list
rm infiles.list
rm rc.cpp
echo "Done"
</syntaxhighlight>

Of course you will want to adjust the variable definitions at the top, and -- if needed -- add code to extract tips-of-the-day or other additional strings.

The example script assumes that all .po files and the .pot file are kept in a single directory, which is appropriate for most projects.

=== Compiling and installing message catalogs ===

Assuming you use the script from the previous section, you can place the following CMakeLists.txt in the directory containing the .po files:

<pre>
FIND_PROGRAM(GETTEXT_MSGFMT_EXECUTABLE msgfmt)

IF(NOT GETTEXT_MSGFMT_EXECUTABLE)
MESSAGE(
"------
NOTE: msgfmt not found. Translations will *not* be installed
------")
ELSE(NOT GETTEXT_MSGFMT_EXECUTABLE)

SET(catalogname rkward)

ADD_CUSTOM_TARGET(translations ALL)

FILE(GLOB PO_FILES *.po)

FOREACH(_poFile ${PO_FILES})
GET_FILENAME_COMPONENT(_poFileName ${_poFile} NAME)
STRING(REGEX REPLACE "^${catalogname}_?" "" _langCode ${_poFileName} )
STRING(REGEX REPLACE "\\.po$" "" _langCode ${_langCode} )

IF( _langCode )
GET_FILENAME_COMPONENT(_lang ${_poFile} NAME_WE)
SET(_gmoFile ${CMAKE_CURRENT_BINARY_DIR}/${_lang}.gmo)

ADD_CUSTOM_COMMAND(TARGET translations
COMMAND ${GETTEXT_MSGFMT_EXECUTABLE} --check -o ${_gmoFile} ${_poFile}
DEPENDS ${_poFile})
INSTALL(FILES ${_gmoFile} DESTINATION ${LOCALE_INSTALL_DIR}/${_langCode}/LC_MESSAGES/ RENAME ${catalogname}.mo)
ENDIF( _langCode )

ENDFOREACH(_poFile ${PO_FILES})

ENDIF(NOT GETTEXT_MSGFMT_EXECUTABLE)
</pre>

This iterates over all .po files in the directory, compiles them using msgfmt, and installs them to the standard location. You will want to change "catalogname" to the name of your application.

=== Getting translations ===

Now you just have to find translators to translate the extracted messages into the various languages. As your application gets used by more people, you will find that translators will volunteer to do this. Translated PO files then have to be stored in the po folder with the naming scheme <languagecode>.po.

=== Translating .desktop Files ===

Translating .desktop files is a bit tricky because the translation of .desktop files isn't fetched from .po/.gmo files, but must be part of the .desktop file itself. So we have 2 tasks:

* extract messages from the .desktop file
* merge the translations in the .desktop file

Our friends from Gnome provide the [http://freedesktop.org/wiki/Software/intltool intltool] package. While this tools is mainly written for the old autotools build system (but KDE uses CMake since KDE 4), we can use this package nevertheless for our purpose. Here is a step-by-step guide:

# Install the [http://freedesktop.org/wiki/Software/intltool intltool] package
# We assume that your .desktop file is named "MYPROGRAM.desktop".
# Make a copy of "MYPROGRAM.desktop" which is named "MYPROGRAM.desktop.template".
# In MYPROGRAM.desktop.template substitute the keys "Name" by "_Name", "GenericName" by "_GenericName" and "Comment" by "_Comment".
# Remove all translations from "MYPROGRAM.desktop.template".
# Add the following lines to the above described build script, at the end of the section "Preparing rc files":
<syntaxhighlight lang="bash">
intltool-extract --quiet --type=gettext/ini PATH/MYPROGRAM.desktop.template
cat PATH/MYPROGRAM.desktop.template.h >> ${WDIR}/rc.cpp
rm PATH/MYPROGRAM.desktop.template.h
cd ${WDIR}
</syntaxhighlight>
intltool-extract will create a dummy C++ header (PATH/MYPROGRAM.desktop.template.h) with the strings whose key starts with "_". We append the content of this header file into our "rc.cpp" and remove remove the file than. (We assume that "PATH" is the path to "MYPROGRAM.desktop.template", relative to the working directory of the script.)
# Add "-kN_:1" as additional parameter to the xgettext call in the section "Extracting messages". This is necessary because dummy code that intltool-extract produces uses "N_()" instead of "i18n()".
# Add the following lines to the above described build script, at the end of the section "Merging translations":
<syntaxhighlight lang="bash">
cd ${WDIR}
intltool-merge --quiet --desktop-style ${WDIR} PATH/MYPROGRAM.desktop.template PATH2/MYPROGRAM.desktop
</syntaxhighlight>
This will produce MYPROGRAM.desktop from MYPROGRAM.desktop.template, inserting all available translations in the .po files in the directory ${WDIR}. (We assume that "PATH" is the path to "MYPROGRAM.desktop.template", relative to the working directory of the script. We assume that "PATH2" is the path to the final location of "MYPROGRAM.desktop", relative to the working directory of the script.)

{{note|Names of .po files):For intltool, it is ''required'' that the .po files have the name <languagecode>.po without other characters (NOT programname_<languagecode>.po). This is important because intltool-merge simply uses the .po file name (without ".po") as language key in the .desktop file.}}

== Special cases (plugins, multiple catalogs, etc.) ==

=== Runtime Loading Of Catalogs ===

To have translations show up properly in an application, the name of the .pot file must match the name of the message catalog (.mo) file that your application will read at runtime. But what name will be used at runtime?

In general, it will be the value returned by <tt>{{class|KGlobal}}::instance()->instanceName()</tt>. But what will that be? The general rules for standalone applications are:
* the message catalog will default to the name of the application passed as the first argument to {{class|KAboutData}}
* if your code calls <tt>{{class|KLocale}}::setMainCatalog()</tt>, that name will be used instead
* if your code calls <tt>{{class|KLocale}}::insertCatalog(const QString&)</tt>, the specified catalog will also be searched in addition to the main catalog

If your code does not call either of the {{class|KLocale}} methods mentioned above and your application is a plugin, it gets a little more complicated. If your code exports your plugin using the <tt>K_EXPORT_COMPONENT_FACTORY</tt> macro, like this:

<syntaxhighlight lang="cpp-qt">
K_EXPORT_COMPONENT_FACTORY( libkhtmlkttsdplugin, KGenericFactory<KHTMLPluginKTTSD>("khtmlkttsd") )
</syntaxhighlight>

then the catalog name will be the name passed in the {{class|KGenericFactory}} constructor - in the example above that woudl be <tt>khtmlkttsd</tt>. This is because the macro creates a {{class|Kinstance}} for you with the specified name.

However, some classes, such as <tt>KTextEditor</tt> create a <tt>KPart</tt> containing your component and the name passed in the macro is not used. In this case, you should call <tt>{{class|KLocale}}::insertCatalog(const QString&)</tt> in the component's constructor.

If in doubt, the safest thing to do is to call <tt>{{class|KLocale}}::insertCatalog(const QString&)</tt>.

{{tip|If you are not using the export macro for your plugin, you probably should be. See the API documentation of KGenericFactory for more information.}}

Calling <tt>{{class|KLocale}}::insertCatalog(const QString&)</tt> if the catalog has already been inserted does nothing. However, calling <tt>{{class|KLocale}}::removeCatalog(const QString&)</tt> removes the catalog no matter how many times it has been inserted. Therefore, take care that you do not inadvertently remove the catalog when multiple components are sharing a single catalog. For example, the following sequence will break translations:

<syntaxhighlight lang="cpp-qt">
// Component A loads and uses catalog xyz by calling
insertCatalogue("xyz");
// Component B loads and also uses the same catalog.
insertCatalogue("xyz");
// component B unloads and calls
removeCatalogue("xyz")
// Component A now doesn't translate properly.
</syntaxhighlight>

Notice that a sequence such as above will occur automatically if both components A and B are loaded using the <tt>K_EXPORT_COMPONENT_FACTORY</tt> macro and pass the same name argument to the KGenericFactory constructor.

=== Naming .pot Files ===

The name that you settle on for both the .pot file and catalog should be governed by where your code resides. If it is a component of another application and resides in that application's source tree, you'll want to share the main catalog of the application.

If is a component of another application but resides elsewhere in the code repository, you will probably have to create a separate .pot, but keep in mind that .pot filenames must be unique across all of KDE.

If it is a component of another application, but resides in the source tree of a second application, you should share with the second application. For example, the KDE text-to-speach daemon (KTTSD) includes a plugin for embedded Kate in {{path|kdeaccessibility/kttsd}} source tree. Since the plugin is not installed unless kttsd is installed, it shares its catalog with kttsd and calls <tt>{{class|KLocale}}::insertCatalog("kttsd")</tt> to do this.

== Handbooks ==

Handbooks, which are written in docbook format, are handled different from applications. The translated Handbooks are committed into the l10n module in the docs folder under each language. In addition, the docs folder is broken down by module and application. For example, the German Kate Handbook is committed to the {{path|l10n/de/docs/kdebase/kate/}} folder. When compiled, the German Kate Handbook is installed to {{path|$KDEDIR/share/doc/HTML/de/kate/index.cache.bz2}}.

Note that it is up to each translation team to generate the translated Handbook when they feel it is complete.

[[Category:Programming]]

Development/Tutorials/Localization/Building KDE's l10n Module

2011-06-27T16:50:50Z

Icwiener: Fix syntax highlighting.

{{TutorialBrowser|

series=Localization|

name=Building KDE's l10n Module|

pre=[[Getting_Started/Sources/Using_Subversion_with_KDE|Using Subversion with KDE]] [[Getting_Started/Build|Building KDE From Subversion]] [[../i18n|Writing Applications With Localization in Mind]]|

}}

== Abstract ==

For those working on applications in KDE's main repository, building and installing language support from KDE's localization (l10n) module is a good idea. Doing so will allow you to test applications in other languages so as to spot problems related to localization that may exist in KDE. Learn how to do just that in this tutorial.

== Step 1: l10n ==

You must download, build and install each language in the l10n module separately. You can check out and build just the German, and XX languages using the following procedure:
<syntaxhighlight lang="bash">
svn co -N svn://anonsvn.kde.org/home/kde/trunk/l10n-kde4 l10n
cd l10n
svn up scripts
svn up templates
svn up x-test
svn up de
./scripts/autogen.sh de
./scripts/autogen.sh x-test
</syntaxhighlight>

Once this is done, switch to your build directory, start cmake in the <tt>l10n/x-test</tt>, <tt>l10n/de</tt>, etc directories that you wish to build the language support for one at a time. You may then make and install from the build directory.

{{note|You need revpath (may be found in package {{program|imake}} or {{program|xutils-dev}}) to run <tt>autogen.sh</tt>}}
{{tip|Do not combine make and make install in a single step. It will not install anything.}}

== Step 2: Test An Application ==

To run your application using, for instance, the German catalogs open a terminal (e.g. {{program|konsole}}) and type:
<syntaxhighlight lang="bash">
KDE_LANG=de myapp
</syntaxhighlight>
where <tt>myapp</tt> is the name of the application you wish to test. Replace the <tt>de</tt> with the language code you wish to test, e.g. <tt>x-test</tt>.

The German language is a good choice for testing the layout of your application, as German translated strings tend to be quite long. French is also a good choice. The x-test language is useful for identifying strings in your application that are not translated.

Development/Tutorials/Localization/i18n Mistakes

2011-06-27T16:47:20Z

Icwiener: Fix syntax hightlighting.

{{Template:I18n/Language Navigation Bar|Development/Tutorials/Localization/i18n Mistakes}}

{{TutorialBrowser|

series=Localization|

name=Avoiding Common Localization Pitfalls|

pre=[[../i18n|Writing Applications With Localization in Mind]]|

next=[[../i18n_Build_Systems|Incorporating i18n Into the Build System]]|

}}

== Abstract ==

There are a few common pitfalls that prevent applications from being properly translated or otherwise localized. These include using pixel based layouts, "word puzzles" and writing code that does not deal with Unicode characters properly. This tutorial covers each of these issues, explaining what to avoid and how to do it properly.

== Pitfall #1: Pixel Based Layouts ==

English text is often very compact compared to other languages where the translated text is often substantially longer. Therefore the interface must be able to adjust size to accommodate the length of translations provided at runtime. If it can't do this, then messages will end up misaligned and truncated.

The answer is to use layout managers. Qt provides a number of such layout managers pre-made for you. They include <tt>QHBoxLayout</tt>, <tt>QVBoxLayout</tt>, <tt>QGridLayout</tt> and <tt>QStackedLayout</tt>, all of which are subclasses of <tt>QLayout</tt>. You may also create your own <tt>QLayout</tt> based classes, but this is generally not needed.

These layout classes manage the pixel positioning of widgets for you at runtime, so no matter what the size of the translated strings your interface will adjust properly. For more information look at the documentation for {{qt|QLayout}}.

== Pitfall #2: Word Puzzles ==

Another thing to be aware of is to not concatenate pieces of sentences together like this:

<syntaxhighlight lang="cpp-qt">
QString msg=i18n("Do you want to replace ") +
oldFile+i18n(" with ") +
newFile + "?"
</syntaxhighlight>

Such "word puzzles" are very hard or even impossible to translate. This is because the structure of the sentence will often be completely different in another language and thus must be controlled by the translator. When the order of words and phrases is hard-coded as in the above example, the translator can not create a proper translation.

Adding to this problem, a translator will only see parts of the sentence while translating and will have to guess at what belongs together.

The solution thankfully is quite simple: use <tt>%number</tt> placeholder substitution, which lets the translators not only make good translations because they can see the entirety of the sentence during translation, but which also lets them change the order of the arguments freely. The arguments themselves are passed as extra parameters to <tt>i18n()</tt>.

The above example written properly would then look like this:

<syntaxhighlight lang="cpp-qt">
QString msg = i18n("Do you want to replace %1 with %2?",
oldFile, newFile)
</syntaxhighlight>

It would be even better, if you wrote it more explictly:

<syntaxhighlight lang="cpp-qt">
QString msg = i18n("Do you want to replace file %1 with file %2?",
oldFile, newFile)
</syntaxhighlight>

Or another way is to write a comment prior to sentence like this:

<syntaxhighlight lang="cpp-qt">
/* TRANSLATORS: Replacing an old file (%1) with a new one (%2). */
QString msg = i18n("Do you want to replace %1 with %2?",
oldFile, newFile)
</syntaxhighlight>

{{note|Avoid inserting anything other than numbers or nouns with this method, since in some languages the translation depends on the inserted words. It is therefore best to create strings that are as complete sentences as possible.}}

A related mistake is not including markup tags in rich text, such as or , in the translatable string. Not all languages use such markup in an identical fashion to English and so it is necessary for the translator to be able to "translate" the markup accordingly as well.

Similarly, messages that contain a version string or other often changing parts should be inserted by placeholders into the message. This prevents unnecessary changes that cause the translators to have to change the translated messages as well.

Since KDE is translated into more than 65 languages a single string change causes at least 65 people to open the file, find the changed message, look carefully if this is the only thing that has changed, change the translation, save the file again and commit the changed file into the code repository. All in all such a small change might create hours of work which could be easily avoided.

== Pitfall #3: Lack of Unicode Support ==

Whenever there is source code that handles strings using a datatype (such as <tt>char</tt>) or class (such as <tt>std::string</tt>) that can not handle Unicode, translations will break.

To avoid this, never call <tt>QString::latin1()</tt> or <tt>QString::ascii()</tt> on translated strings. This also applies to information resulting from user input such as passwords, URLs and filenames. If you really need a plain <tt>char*</tt> representation of a string, it is better to use <tt>QString::utf8()</tt>.

{{note|For more information on character sets and Unicode, see the [[Development/Tutorials/Localization/Unicode|Unicode tutorial]].}}

KIO slaves may also provide paths and file names encoded using UTF-8. It is up to the programmer, however, to take care of passing properly encoded filenames to any KIO method in question. The correct way to do this is not to guess at user's filesystem encoding but to use <tt>QFile::encodeName()</tt> and <tt>QFile::decodeName()</tt> instead.

{{tip|You can turn KIO's UTF-8 file name support on for testing by exporting the KDE_UTF8_FILENAMES environment variable in your shell's startup file (e.g. <tt>~/.bashrc</tt>).}}

== Pitfall #4: Complex Text Flow ==

When designing an application that needs non-standard text flow, don't assume that the same rules apply for all languages. Given vertical writing as an example East-Asian languages using Chinese characters have a long history of vertical writing, even longer then horizontal. Strings are not rotated by 90 degrees but instead single characters are placed under one another. There might be just a different behaviour with different scripts. Expect the need to implement specialised versions.

== Success! ==

If you avoid the four common categories of pitfalls detailed in this tutorial, your application should be fully localizable by the various KDE translation teams around the world and open up your application to the majority of people on the planet.

[[Category:Programming]]