Copyright (c) 2004 Frans Englich . Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License". This file describes the organisational layout and file structure for KDE's KCMs(KControl Modules) as well as design recommendations and conventions used. Writing KCMs is covered in KCM_HOWTO. Issues specific to kdebase's KCMs as well as the current maintainer information can be obtained from README. This file exists in order to make decision regarding KControl and its KCMs centralised as well as bringing some coherency to development. If you have valid reason for not following these guidelines please speak up on the mailinglist kde-usability so your suggestion can be peer reviewed and this file eventually changed to reflect the new conventions. Naturally, do not change the content of this file(except obvious typos) without having reached consensus with other developers. Furthermore, any agreement regarding KControl's design and conventions must be documented in this file. It is essential this file reflects the practices in use, otherwise it will loose it influence. General discussion about usability issues should be done on the mailinglist kde-usability. In order to get in contact with the maintainer of the various modules please consult PACKAGE/KCMs/README where PACKAGE is the relevant kde package, such as kdegraphics. --- Directory Layout and Filename Conventions --- In each KDE package which contains KCMs(for example kdenetwork) a top directory named "KCMs" exists which contains everything related to the KCM's for that package, regardless of what application or functionality the KCM represents. Each "KCMs" contains a README file where the maintainer is listed as well as other information specific information for that package's KCMs(kdebase is one exception which also contains this file). For KCM's and their associated files a set of filename conventions exists with must be followed: * All the KCM's files resides in a sub directory of "KCMs". The name of that directory is the same X-KDE-Library for that module. Ie, if a KCM's desktop file contains "X-KDE-Library=kmix" all its files resides in "KCMs/kmix/". * The name of the desktop file is the KCM's library name prefixed with "kcm_". For example "kcm_kmix.desktop". * If the KCM has an icon specific for the KCM its basename should be the same as the library name. * The main source file and its header should be named main.cpp and main.h, respectively. --- A Valid KCM --- In order for an KCM to be good and valid it must conform to: 1) KDE Licensing Policy. Basically, a OSI approved license as well as correct license and copyright headers. For details see: http://developer.kde.org/policies/licensepolicy.html 2) KDE User Interface Guidelines. Please see: http://developer.kde.org/documentation/standards/kde/style/basics/index.html 3) the conventions and recommendations in this file. If the KCM does not conform, it is considered a broken KCM. These guidelines exist in order to make the KCMs look consistent, be pleasent for the user and blend with the rest of KDE as well as ensuring KDE stay out of legal trouble. It also makes life easier for use developers. --- Name Recommendations --- When picking or changing a name(that is the Name directive in the .desktop file) for a KCM it is good idea keeping the following issues in mind in order to promote usability and consistency between the modules: * Try to keep the phrase short. Shorter phrases is easier and fast to interpret and give better options for designing the layout. From a esthetically perspective it also looks cleaner and simpler. * Avoid complex phrases involving backslashes("/)" and paranteses for the same reasons as above. * Avoid including words like "Management" and "Configuration" etc. since it is abundant - KControl is all about that which the user already is aware of. Furthermore, such terms does not inform the user about what Your module contains, except that it is for configuration or management(and that is already clear since it is in KControl). * KControl as the rest of KDE targets a wide audience where a significant part of the users does not have technical expertise. In order to have a compelling interface it is important to avoid technical and "scary" terms. Words used should an average user be able to understand. The above name recommendations is guidelines and must not be strictly followed. If the name demands to be longer than average in order to be informative that is of course ok. Similarly, don't simplify words in case it then does not reflect the content. The recommendations exist to make the names informative, representative for the content and easy to read - not the opposite. The recommendations can also be applied on phrases used elsewhere in the KCM. --- Technical Recommendations --- When building a new KCM or improving an old a set of KDE technologies is preferred in front of others: * Use .ui files instead of handcrafted Graphical user interfaces designed with QT Designer is preferred instead of handwritten ones because 1) It allows people without C++ experience to modify GUIs; 2) It is safer since it is not manually written code; 3) It allows more obtrusive changes to be done in code freezes; and 4) Usually more efficient and faster code. * KConfigXT framework instead of handcrafted configuration code The rationalis is similar to the above with notable addition: it saves disc space on installed clients. These recommendations exists in order to make development faster and easier resulting in better and bugfree code but neither these recommendations should be followed blindly. For example, if a handcrafted GUI for some rational reason(which is different from "preferred by developer") that should be chosen.