Rearrange the developer documentation folder. Add some notes on compliance...

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

-
-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.

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 <subject> 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

developer-doc/user-interface/dialog-reviews/edit-profile-dialog

+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.

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<QString>() );
     _ui->remoteTabTitleEdit->setText( 
             info->property(Profile::RemoteTabTitleFormat).value<QString>());
@@ -135,10 +138,13 @@ void EditProfileDialog::setupGeneralPage(const Profile* info)
     // tab mode
     int tabMode = info->property(Profile::TabBarMode).value<int>();
 
-    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<bool>() );

src/EditProfileDialog.ui

@@ -43,6 +43,9 @@
          <property name="text" >
           <string>Profile Name:</string>
          </property>
+         <property name="alignment" >
+          <set>Qt::AlignRight|Qt::AlignTrailing|Qt::AlignVCenter</set>
+         </property>
         </widget>
        </item>
        <item row="0" column="1" colspan="2" >
@@ -57,6 +60,9 @@
          <property name="text" >
           <string>Command:</string>
          </property>
+         <property name="alignment" >
+          <set>Qt::AlignRight|Qt::AlignTrailing|Qt::AlignVCenter</set>
+         </property>
         </widget>
        </item>
        <item row="1" column="1" colspan="2" >
@@ -71,6 +77,9 @@
          <property name="text" >
           <string>Initial Directory:</string>
          </property>
+         <property name="alignment" >
+          <set>Qt::AlignRight|Qt::AlignTrailing|Qt::AlignVCenter</set>
+         </property>
         </widget>
        </item>
        <item row="2" column="1" colspan="2" >
@@ -95,6 +104,9 @@
          <property name="text" >
           <string>Icon:</string>
          </property>
+         <property name="alignment" >
+          <set>Qt::AlignRight|Qt::AlignTrailing|Qt::AlignVCenter</set>
+         </property>
         </widget>
        </item>
        <item row="3" column="1" >
@@ -158,10 +170,13 @@
             <property name="text" >
              <string>Tab Title Format:</string>
             </property>
+            <property name="alignment" >
+             <set>Qt::AlignRight|Qt::AlignTrailing|Qt::AlignVCenter</set>
+            </property>
            </widget>
           </item>
           <item row="0" column="1" >
-           <widget class="QLineEdit" name="tabTitleEdit" >
+           <widget class="KLineEdit" name="tabTitleEdit" >
             <property name="toolTip" >
              <string>Normal tab title format </string>
             </property>
@@ -182,10 +197,13 @@
             <property name="text" >
              <string>Remote Tab Title Format:</string>
             </property>
+            <property name="alignment" >
+             <set>Qt::AlignRight|Qt::AlignTrailing|Qt::AlignVCenter</set>
+            </property>
            </widget>
           </item>
           <item row="1" column="1" >
-           <widget class="QLineEdit" name="remoteTabTitleEdit" >
+           <widget class="KLineEdit" name="remoteTabTitleEdit" >
             <property name="toolTip" >
              <string>Tab title format used when a remote command (eg. connection to another computer via SSH) is being executed</string>
             </property>
@@ -394,6 +412,9 @@
               <property name="text" >
                <string>Text Size:</string>
               </property>
+              <property name="alignment" >
+               <set>Qt::AlignRight|Qt::AlignTrailing|Qt::AlignVCenter</set>
+              </property>
              </widget>
             </item>
             <item>
@@ -703,6 +724,9 @@
               <property name="text" >
                <string>Word characters for double-click selection: </string>
               </property>
+              <property name="alignment" >
+               <set>Qt::AlignRight|Qt::AlignTrailing|Qt::AlignVCenter</set>
+              </property>
              </widget>
             </item>
             <item>