From df5b3c08ff575ae98233f0755c588a28794bc7a2 Mon Sep 17 00:00:00 2001 From: Robert Knight Date: Mon, 7 May 2007 15:14:57 +0000 Subject: [PATCH] Rearrange the developer documentation folder. Add some notes on compliance with the KDE 4 HIG / dialog design ( basically a TODO of problems to fix ). Small tweaks to the Edit Profile dialog. svn path=/trunk/KDE/kdebase/apps/konsole/; revision=662161 --- BRANCH-INFO | 5 -- developer-doc/README | 41 +++++++++++--- .../{kde4 => design}/architecture-overview | 0 .../developer-documentation-template | 0 .../{kde4 => design}/historic/README | 0 .../historic/split-screen-design | 0 .../{ => old-documents}/konsole.Doxyfile | 0 developer-doc/{ => old-documents}/mkDocs | 0 .../{ => research}/konsole-survey-findings | 0 .../dialog-reviews/edit-profile-dialog | 56 +++++++++++++++++++ src/EditProfileDialog.cpp | 14 +++-- src/EditProfileDialog.ui | 28 +++++++++- 12 files changed, 124 insertions(+), 20 deletions(-) delete mode 100644 BRANCH-INFO rename developer-doc/{kde4 => design}/architecture-overview (100%) rename developer-doc/{kde4 => design}/developer-documentation-template (100%) rename developer-doc/{kde4 => design}/historic/README (100%) rename developer-doc/{kde4 => design}/historic/split-screen-design (100%) rename developer-doc/{ => old-documents}/konsole.Doxyfile (100%) rename developer-doc/{ => old-documents}/mkDocs (100%) rename developer-doc/{ => research}/konsole-survey-findings (100%) create mode 100644 developer-doc/user-interface/dialog-reviews/edit-profile-dialog diff --git a/BRANCH-INFO b/BRANCH-INFO deleted file mode 100644 index f1e1dac6d..000000000 --- a/BRANCH-INFO +++ /dev/null @@ -1,5 +0,0 @@ - -konsole-split-view BRANCH - -This branch is for work on implementing the split view functionality into Konsole. -This touches most of the Konsole front-end, mainly the Konsole class. diff --git a/developer-doc/README b/developer-doc/README index 07b28bb86..e3658f021 100644 --- a/developer-doc/README +++ b/developer-doc/README @@ -2,7 +2,7 @@ Developer Documentation for Konsole Authors: Robert Knight < robertknight@gmail.com > -Last Updated: 14-02-2007 +Last Updated: 7th May 2007 Summary: Introduction to Konsole developer documentation =============================================================== @@ -21,8 +21,8 @@ Contents: 1. Introduction -The document explains the format used for Konsole documentation -since KDE 4. Any queries about +This document explains the layout of the developer documentation folder, +and basic guidelines for contributors. 2. Documentation format @@ -36,7 +36,7 @@ questions is encouraged: - What is it about? - Where can I find information about within this document? -The current template can be found in kde4/developer-documentation-template +The current template can be found in design/developer-documentation-template There is older documentation in the old-documents/ folder which does not follow this format. This is kept as a reference. Assistance @@ -45,9 +45,15 @@ template would be appreciated. 3. Documentation layout - kde4/ - Documentation which is relevant to the KDE 4.0x release of Konsole - kde4/historic - Documentation which was prepared during the KDE 4.0x development - cycle but which is no longer relevant. + design/ - Documentation about the design of Konsole, and templates + for developer documentation. + design/historic - Documentation which was prepared during the KDE 4.0x development + cycle but which is no longer relevant. + + research/ - Results of research into user's experiences with Konsole + + user-interface/ - Documentation concerning design and analysis of the user interface. + old-documents/ - An assortment of documentation which was created during earlier releases of Konsole. There is useful inforamtion here, particularly about the type of terminal which Konsole emulates, but it is not @@ -96,8 +102,25 @@ Patches can be submitted for Konsole in a number of places: 4.2.2 Code style guidelines - Generally speaking, the code follows the style of API used in Qt classes, and favours - verbosity. The naming of methods and classes follows the Qt style, roughly speaking. + The API style roughly follows that used in the Qt and KDE classes. + + There are no strict guidelines on aspects of the code such as indentation, braces + or spacing, although following the style of the existing code is a good idea. + + Below is a list of the most important style considerations which have been developed + following experience working on earlier Konsole code: + + - Variables and methods should have CLEAR, verbose names. The use of abbreviations + should be avoided except for very common cases. + + - The use of named constants is preferred over literals for clarity, and also to prevent + the need to edit each instance of a literal if the value needs to be changed. + + - The use of macros ( #define ) should be avoided where possible. enums, inline methods + templates, static constants etc. are strongly preferred. + - Inside classes, private member fields have an underscore prefix ( eg. _myPrivateField ) + - Private slots in classes DO NOT have a "slot" prefix before their name which is often + seen in other KDE applications. Earlier Konsole code had a proliferation of two-letter variable names, which made it hard to read and understand in some places, and let directly to bugs in others. Descriptive naming diff --git a/developer-doc/kde4/architecture-overview b/developer-doc/design/architecture-overview similarity index 100% rename from developer-doc/kde4/architecture-overview rename to developer-doc/design/architecture-overview diff --git a/developer-doc/kde4/developer-documentation-template b/developer-doc/design/developer-documentation-template similarity index 100% rename from developer-doc/kde4/developer-documentation-template rename to developer-doc/design/developer-documentation-template diff --git a/developer-doc/kde4/historic/README b/developer-doc/design/historic/README similarity index 100% rename from developer-doc/kde4/historic/README rename to developer-doc/design/historic/README diff --git a/developer-doc/kde4/historic/split-screen-design b/developer-doc/design/historic/split-screen-design similarity index 100% rename from developer-doc/kde4/historic/split-screen-design rename to developer-doc/design/historic/split-screen-design diff --git a/developer-doc/konsole.Doxyfile b/developer-doc/old-documents/konsole.Doxyfile similarity index 100% rename from developer-doc/konsole.Doxyfile rename to developer-doc/old-documents/konsole.Doxyfile diff --git a/developer-doc/mkDocs b/developer-doc/old-documents/mkDocs similarity index 100% rename from developer-doc/mkDocs rename to developer-doc/old-documents/mkDocs diff --git a/developer-doc/konsole-survey-findings b/developer-doc/research/konsole-survey-findings similarity index 100% rename from developer-doc/konsole-survey-findings rename to developer-doc/research/konsole-survey-findings diff --git a/developer-doc/user-interface/dialog-reviews/edit-profile-dialog b/developer-doc/user-interface/dialog-reviews/edit-profile-dialog new file mode 100644 index 000000000..987f02498 --- /dev/null +++ b/developer-doc/user-interface/dialog-reviews/edit-profile-dialog @@ -0,0 +1,56 @@ +Review of the Edit Profile Dialog based on the KDE 4 HIG + +Authors: Robert Knight < robertknight@gmail.com > +Last Updated: 07-05-2007 +Summary: A basic review of the edit profile dialog + checking conformance with the KDE 4 HIG + +========================================= + +Contents: + 1. Introduction + 2. Visual vertical lines + 3. Inline editing + 4. Dialog depth + +========================================= + +1. Introduction + +This is a basic review of the Edit Profile Dialog, checking compliance against the +KDE 4 HIG guidelines posted here and documenting problems found. + +http://wiki.openusability.org/guidelines/index.php/Design_and_Layout:Layout:Dialogs + +2. Visual vertical lines + +The guidelines suggest that there should be "one or two major vertical axis" to guide the user's +attention, that is there should be a vertical axis which widgets do not cross +( except for section titles ), but should be on one side or the other. + +The "General" and "Advanced" tabs do not comply with this. In the General tab, +each section ( main , Tab Titles , Window & Tab Bar Options ) has its own visual line. + +This is quite difficult to handle in Qt Designer at present and a problem for most +KDE applications. Particularly checkboxes and radio buttons since the label and +check/radio box are part of the same widget, but they may belong on +different sides of the vertical line. + +2.1 Inline editing + +The tab title format section has a separate dialog to help editing these formats. +The guidelines suggest the use of inline editing where possible. + +2.2 Dialog depth + +The guidelines suggest not nesting dialogs more than two levels deep. +If the user opens the dialog via Settings -> Edit Current Profile, then +there are no dialogs more than two levels deep. + +If they go through the Manage Profiles dialog first ( Settings -> Manage Profiles ) +then the Color Scheme Editor / Key Bindings Editor dialogs are three levels deep. + +3. Modality + +The "Manage Profiles" and "Edit Profile" dialogs are generally used in a modal +fashion. This is not necessary. diff --git a/src/EditProfileDialog.cpp b/src/EditProfileDialog.cpp index d9231319d..168c250c4 100644 --- a/src/EditProfileDialog.cpp +++ b/src/EditProfileDialog.cpp @@ -128,6 +128,9 @@ void EditProfileDialog::setupGeneralPage(const Profile* info) _ui->initialDirEdit->setClearButtonShown(true); _ui->iconSelectButton->setIcon( KIcon(info->icon()) ); + // tab title format + _ui->tabTitleEdit->setClearButtonShown(true); + _ui->remoteTabTitleEdit->setClearButtonShown(true); _ui->tabTitleEdit->setText( info->property(Profile::LocalTabTitleFormat).value() ); _ui->remoteTabTitleEdit->setText( info->property(Profile::RemoteTabTitleFormat).value()); @@ -135,10 +138,13 @@ void EditProfileDialog::setupGeneralPage(const Profile* info) // tab mode int tabMode = info->property(Profile::TabBarMode).value(); - RadioOption tabModes[] = { {_ui->alwaysHideTabBarButton,Profile::AlwaysHideTabBar,SLOT(alwaysHideTabBar())}, - {_ui->alwaysShowTabBarButton,Profile::AlwaysShowTabBar,SLOT(alwaysShowTabBar())}, - {_ui->autoShowTabBarButton,Profile::ShowTabBarAsNeeded,SLOT(showTabBarAsNeeded())}, - {0,0,0} }; + RadioOption tabModes[] = { {_ui->alwaysHideTabBarButton,Profile::AlwaysHideTabBar, + SLOT(alwaysHideTabBar()) }, + {_ui->alwaysShowTabBarButton,Profile::AlwaysShowTabBar, + SLOT(alwaysShowTabBar()) }, + {_ui->autoShowTabBarButton,Profile::ShowTabBarAsNeeded, + SLOT(showTabBarAsNeeded()) }, + {0,0,0} }; setupRadio( tabModes , tabMode ); _ui->showMenuBarButton->setChecked( info->property(Profile::ShowMenuBar).value() ); diff --git a/src/EditProfileDialog.ui b/src/EditProfileDialog.ui index c60034c69..150753730 100644 --- a/src/EditProfileDialog.ui +++ b/src/EditProfileDialog.ui @@ -43,6 +43,9 @@ Profile Name: + + Qt::AlignRight|Qt::AlignTrailing|Qt::AlignVCenter + @@ -57,6 +60,9 @@ Command: + + Qt::AlignRight|Qt::AlignTrailing|Qt::AlignVCenter + @@ -71,6 +77,9 @@ Initial Directory: + + Qt::AlignRight|Qt::AlignTrailing|Qt::AlignVCenter + @@ -95,6 +104,9 @@ Icon: + + Qt::AlignRight|Qt::AlignTrailing|Qt::AlignVCenter + @@ -158,10 +170,13 @@ Tab Title Format: + + Qt::AlignRight|Qt::AlignTrailing|Qt::AlignVCenter + - + Normal tab title format @@ -182,10 +197,13 @@ Remote Tab Title Format: + + Qt::AlignRight|Qt::AlignTrailing|Qt::AlignVCenter + - + Tab title format used when a remote command (eg. connection to another computer via SSH) is being executed @@ -394,6 +412,9 @@ Text Size: + + Qt::AlignRight|Qt::AlignTrailing|Qt::AlignVCenter + @@ -703,6 +724,9 @@ Word characters for double-click selection: + + Qt::AlignRight|Qt::AlignTrailing|Qt::AlignVCenter +