Commit df5b3c08 authored by Robert Knight's avatar Robert Knight
Browse files

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
parent 0ab65a6f
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.
......@@ -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
......
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.
......@@ -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>() );
......
......@@ -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>
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment