- restructure opieui example directory

- start work on ONamedListViewItem providing a slightly higher level interface

9 files changed, 378 insertions, 54 deletions

diff --git a/libopie2/examples/opieui/olistviewdemo/.cvsignore b/libopie2/examples/opieui/olistviewdemo/.cvsignore
new file mode 100644
index 0000000..1317f7e
--- a/dev/null
+++ b/libopie2/examples/opieui/olistviewdemo/.cvsignore
@@ -0,0 +1,8 @@
+Makefile*
+moc*
+*moc
+*.o
+~*
+moc
+obj
+
diff --git a/libopie2/examples/opieui/olistviewdemo/main.cpp b/libopie2/examples/opieui/olistviewdemo/main.cpp
new file mode 100644
index 0000000..a93f361
--- a/dev/null
+++ b/libopie2/examples/opieui/olistviewdemo/main.cpp
@@ -0,0 +1,26 @@
+/**********************************************************************
+** Copyright (C) 2002 Michael 'Mickey' Lauer.  All rights reserved.
+**
+** This file is part of Opie Environment.
+**
+** This file may be distributed and/or modified under the terms of the
+** GNU General Public License version 2 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file.
+**
+** This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
+** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+**
+**********************************************************************/
+
+#include "olistviewdemo.h"
+#include <opie2/oapplication.h>
+
+int main( int argc, char **argv )
+{
+    OApplication a( argc, argv, "OListViewDemo" );
+    OListViewDemo e;
+    a.showMainWidget(&e);
+    return a.exec();
+}
+
diff --git a/libopie2/examples/opieui/olistviewdemo/olistviewdemo.cpp b/libopie2/examples/opieui/olistviewdemo/olistviewdemo.cpp
new file mode 100644
index 0000000..31bda9d
--- a/dev/null
+++ b/libopie2/examples/opieui/olistviewdemo/olistviewdemo.cpp
@@ -0,0 +1,54 @@
+/*
+                             This file is part of the Opie Project
+
+                             Copyright (C) 2003 Michael 'Mickey' Lauer
+                             <mickey@tm.informatik.uni-frankfurt.de>
+              =.
+            .=l.
+           .>+-=
+ _;:,     .>    :=|.         This program is free software; you can
+.> <`_,   >  .   <=          redistribute it and/or  modify it under
+:`=1 )Y*s>-.--   :           the terms of the GNU Library General Public
+.="- .-=="i,     .._         License as published by the Free Software
+ - .   .-<_>     .<>         Foundation; either version 2 of the License,
+     ._= =}       :          or (at your option) any later version.
+    .%`+i>       _;_.
+    .i_,=:_.      -<s.       This program is distributed in the hope that
+     +  .  -:.       =       it will be useful,  but WITHOUT ANY WARRANTY;
+    : ..    .:,     . . .    without even the implied warranty of
+    =_        +     =;=|`    MERCHANTABILITY or FITNESS FOR A
+  _.=:.       :    :=>`:     PARTICULAR PURPOSE. See the GNU
+..}^=.=       =       ;      Library General Public License for more
+++=   -.     .`     .:       details.
+ :     =  ...= . :.=-
+ -.   .:....=;==+<;          You should have received a copy of the GNU
+  -_. . .   )=.  =           Library General Public License along with
+    --        :-=`           this library; see the file COPYING.LIB.
+                             If not, write to the Free Software Foundation,
+                             Inc., 59 Temple Place - Suite 330,
+                             Boston, MA 02111-1307, USA.
+
+*/
+
+#include "olistviewdemo.h"
+#include <opie2/olistview.h>
+
+#include <qstring.h>
+#include <qpixmap.h>
+#include <qlistview.h>
+
+OListViewDemo::OListViewDemo( QWidget* parent, const char* name, WFlags f )
+                   :QVBox( parent, name, f )
+{
+    lv = new ONamedListView( this );
+    lv->addColumns( QStringList::split( ' ', "Column1 Column2 Column3 Column4" ) );
+
+    ONamedListViewItem* item = new ONamedListViewItem( lv, QStringList::split( ' ', "Text1 Text2 Text3 Text4" ) );
+    item->setText( "Column2", "ModifiedText" );
+    item->setText( "Column5", "ThisColumnDoesNotExits" );
+}
+
+OListViewDemo::~OListViewDemo()
+{
+}
+
diff --git a/libopie2/examples/opieui/olistviewdemo/olistviewdemo.h b/libopie2/examples/opieui/olistviewdemo/olistviewdemo.h
new file mode 100644
index 0000000..8a5986a
--- a/dev/null
+++ b/libopie2/examples/opieui/olistviewdemo/olistviewdemo.h
@@ -0,0 +1,51 @@
+/*
+                             This file is part of the Opie Project
+
+                             Copyright (C) 2003 Michael 'Mickey' Lauer <mickey@tm.informatik.uni-frankfurt.de>
+              =.
+            .=l.
+           .>+-=
+ _;:,     .>    :=|.         This program is free software; you can
+.> <`_,   >  .   <=          redistribute it and/or  modify it under
+:`=1 )Y*s>-.--   :           the terms of the GNU Library General Public
+.="- .-=="i,     .._         License as published by the Free Software
+ - .   .-<_>     .<>         Foundation; either version 2 of the License,
+     ._= =}       :          or (at your option) any later version.
+    .%`+i>       _;_.
+    .i_,=:_.      -<s.       This program is distributed in the hope that
+     +  .  -:.       =       it will be useful,  but WITHOUT ANY WARRANTY;
+    : ..    .:,     . . .    without even the implied warranty of
+    =_        +     =;=|`    MERCHANTABILITY or FITNESS FOR A
+  _.=:.       :    :=>`:     PARTICULAR PURPOSE. See the GNU
+..}^=.=       =       ;      Library General Public License for more
+++=   -.     .`     .:       details.
+ :     =  ...= . :.=-
+ -.   .:....=;==+<;          You should have received a copy of the GNU
+  -_. . .   )=.  =           Library General Public License along with
+    --        :-=`           this library; see the file COPYING.LIB.
+                             If not, write to the Free Software Foundation,
+                             Inc., 59 Temple Place - Suite 330,
+                             Boston, MA 02111-1307, USA.
+
+*/
+
+#ifndef OLISTVIEWDEMO_H
+#define OLISTVIEWDEMO_H
+
+#include <qvbox.h>
+#include <opie2/olistview.h>
+
+class OListViewDemo: public QVBox
+{
+  Q_OBJECT
+
+  public:
+    OListViewDemo( QWidget* parent=0, const char* name=0, WFlags f=0 );
+    virtual ~OListViewDemo();
+
+  private:
+    ONamedListView* lv;
+
+};
+
+#endif
diff --git a/libopie2/examples/opieui/oversatileviewdemo/opieui.pro b/libopie2/examples/opieui/olistviewdemo/olistviewdemo.pro
index 8ad5fc9..aabe733 100644
--- a/libopie2/examples/opieui/oversatileviewdemo/opieui.pro
+++ b/libopie2/examples/opieui/olistviewdemo/olistviewdemo.pro
@@ -1,17 +1,15 @@
 TEMPLATE        = app
 CONFIG          = qt warn_on debug
-HEADERS         = opieuidemo.h \
-                  oversatileviewdemo.h
-SOURCES         = opieuidemo.cpp \
-                  oversatileviewdemo.cpp \
+HEADERS         = olistviewdemo.h
+SOURCES         = olistviewdemo.cpp \
                   main.cpp
 INCLUDEPATH     += $(OPIEDIR)/include
 DEPENDPATH      += $(OPIEDIR)/include
 LIBS            += -lopieui2 -lopiecore2
-TARGET          = opieuidemo
+TARGET          = olistviewdemo
 MOC_DIR     = moc
 OBJECTS_DIR = obj
 
 include ( $(OPIEDIR)/include.pro )
 
 
diff --git a/libopie2/examples/opieui/opieui.pro b/libopie2/examples/opieui/opieui.pro
new file mode 100644
index 0000000..b52f013
--- a/dev/null
+++ b/libopie2/examples/opieui/opieui.pro
@@ -0,0 +1,3 @@
+TEMPLATE        = subdirs
+SUBDIRS         = olistviewdemo oversatileviewdemo
+
diff --git a/libopie2/examples/opieui/oversatileviewdemo/opieui.pro b/libopie2/examples/opieui/oversatileviewdemo/oversatileviewdemo.pro
index 8ad5fc9..8ad5fc9 100644
--- a/libopie2/examples/opieui/oversatileviewdemo/opieui.pro
+++ b/libopie2/examples/opieui/oversatileviewdemo/oversatileviewdemo.pro
diff --git a/libopie2/opieui/olistview.cpp b/libopie2/opieui/olistview.cpp
index 2b2f09a..8f97cc6 100644
--- a/libopie2/opieui/olistview.cpp
+++ b/libopie2/opieui/olistview.cpp
@@ -1,423 +1,532 @@
 /*
                              This file is part of the Opie Project
 
               =.             (C) 2003 Michael 'Mickey' Lauer <mickey@tm.informatik.uni-frankfurt.de>
             .=l.
            .>+-=
  _;:,     .>    :=|.         This program is free software; you can
 .> <`_,   >  .   <=          redistribute it and/or  modify it under
 :`=1 )Y*s>-.--   :           the terms of the GNU Library General Public
 .="- .-=="i,     .._         License as published by the Free Software
  - .   .-<_>     .<>         Foundation; either version 2 of the License,
      ._= =}       :          or (at your option) any later version.
     .%`+i>       _;_.
     .i_,=:_.      -<s.       This program is distributed in the hope that
      +  .  -:.       =       it will be useful,  but WITHOUT ANY WARRANTY;
     : ..    .:,     . . .    without even the implied warranty of
     =_        +     =;=|`    MERCHANTABILITY or FITNESS FOR A
   _.=:.       :    :=>`:     PARTICULAR PURPOSE. See the GNU
 ..}^=.=       =       ;      Library General Public License for more
 ++=   -.     .`     .:       details.
  :     =  ...= . :.=-
  -.   .:....=;==+<;          You should have received a copy of the GNU
   -_. . .   )=.  =           Library General Public License along with
     --        :-=`           this library; see the file COPYING.LIB.
                              If not, write to the Free Software Foundation,
                              Inc., 59 Temple Place - Suite 330,
                              Boston, MA 02111-1307, USA.
 
 */
 
 /* QT */
 
 #include <qcolor.h>
 #include <qheader.h>
 #include <qpainter.h>
 #include <qpixmap.h>
 
 /* OPIE */
 
 #include <opie2/olistview.h>
 
 /*======================================================================================
  * OListView
  *======================================================================================*/
 
 OListView::OListView( QWidget *parent, const char *name )
           :QListView( parent, name )
 {
     //FIXME: get from global settings and calculate ==> see oglobalsettings.*
 
     m_alternateBackground = QColor( 238, 246, 255 );
     m_columnSeparator = QPen( QColor( 150, 160, 170 ), 0, DotLine );
     m_fullWidth = true;
 }
 
 OListView::~OListView()
 {
 }
 
 void OListView::setFullWidth( bool fullWidth )
 {
     m_fullWidth = m_fullWidth;
     #if QT_VERSION > 290
     header()->setStretchEnabled( fullWidth, columns()-1 );
     #endif
 }
 
 bool OListView::fullWidth() const
 {
     return m_fullWidth;
 }
 
 int OListView::addColumn( const QString& label, int width )
 {
     int result = QListView::addColumn( label, width );
     #if QT_VERSION > 290
     if (m_fullWidth) {
         header()->setStretchEnabled( false, columns()-2 );
         header()->setStretchEnabled( true, columns()-1  );
     }
     #endif
     return result;
 }
 
 int OListView::addColumn( const QIconSet& iconset, const QString& label, int width )
 {
     int result = QListView::addColumn( iconset, label, width );
     #if QT_VERSION > 290
     if (m_fullWidth) {
         header()->setStretchEnabled( false, columns()-2 );
         header()->setStretchEnabled( true, columns()-1 );
     }
     #endif
     return result;
 }
 
 void OListView::removeColumn( int index )
 {
     QListView::removeColumn(index);
     #if QT_VERSION > 290
     if ( m_fullWidth && index == columns() )
     {
         header()->setStretchEnabled( true, columns()-1 );
     }
     #endif
 }
 
 const QColor& OListView::alternateBackground() const
 {
     return m_alternateBackground;
 }
 
 void OListView::setAlternateBackground( const QColor &c )
 {
     m_alternateBackground = c;
     repaint();
 }
 
 const QPen& OListView::columnSeparator() const
 {
     return m_columnSeparator;
 }
 
 void OListView::setColumnSeparator( const QPen& p )
 {
     m_columnSeparator = p;
     repaint();
 }
 
 OListViewItem* OListView::childFactory()
 {
     return new OListViewItem( this );
 }
 
 #ifndef QT_NO_DATASTREAM
 void OListView::serializeTo( QDataStream& s ) const
 {
     #warning Caution... the binary format is still under construction...
     qDebug( "storing OListView..." );
 
     // store number of columns and the labels
     s << columns();
     for ( int i = 0; i < columns(); ++i )
         s << columnText( i );
 
     // calculate the number of top-level items to serialize
     int items = 0;
     QListViewItem* item = firstChild();
     while ( item )
     {
         item = item->nextSibling();
         items++;
     }
 
     // store number of items and the items itself
     s << items;
     item = firstChild();
     for ( int i = 0; i < items; ++i )
     {
         s << *static_cast<OListViewItem*>( item );
         item = item->nextSibling();
     }
 
     qDebug( "OListview stored." );
 }
 
 void OListView::serializeFrom( QDataStream& s )
 {
     #warning Caution... the binary format is still under construction...
     qDebug( "loading OListView..." );
 
     int cols;
     s >> cols;
     qDebug( "read number of columns = %d", cols );
 
     while ( columns() < cols ) addColumn( QString::null );
 
     for ( int i = 0; i < cols; ++i )
     {
         QString coltext;
         s >> coltext;
         qDebug( "read text '%s' for column %d", (const char*) coltext, i );
         setColumnText( i, coltext );
     }
 
     int items;
     s >> items;
     qDebug( "read number of items = %d", items );
 
     for ( int i = 0; i < items; ++i )
     {
         OListViewItem* item = childFactory();
         s >> *item;
     }
 
     qDebug( "OListView loaded." );
 
 }
 
 QDataStream& operator<<( QDataStream& s, const OListView& lv )
 {
     lv.serializeTo( s );
 }
 
 QDataStream& operator>>( QDataStream& s, OListView& lv )
 {
     lv.serializeFrom( s );
 }
 #endif // QT_NO_DATASTREAM
 
 /*======================================================================================
  * OListViewItem
  *======================================================================================*/
 
 OListViewItem::OListViewItem(QListView *parent)
   : QListViewItem(parent)
 {
     init();
 }
 
+
 OListViewItem::OListViewItem(QListViewItem *parent)
   : QListViewItem(parent)
 {
     init();
 }
 
+
 OListViewItem::OListViewItem(QListView *parent, QListViewItem *after)
   : QListViewItem(parent, after)
 {
     init();
 }
 
+
 OListViewItem::OListViewItem(QListViewItem *parent, QListViewItem *after)
   : QListViewItem(parent, after)
 {
     init();
 }
 
+
 OListViewItem::OListViewItem(QListView *parent,
     QString label1, QString label2, QString label3, QString label4,
     QString label5, QString label6, QString label7, QString label8)
   : QListViewItem(parent, label1, label2, label3, label4, label5, label6, label7, label8)
 {
     init();
 }
 
+
 OListViewItem::OListViewItem(QListViewItem *parent,
     QString label1, QString label2, QString label3, QString label4,
     QString label5, QString label6, QString label7, QString label8)
   : QListViewItem(parent, label1, label2, label3, label4, label5, label6, label7, label8)
 {
     init();
 }
 
+
 OListViewItem::OListViewItem(QListView *parent, QListViewItem *after,
     QString label1, QString label2, QString label3, QString label4,
     QString label5, QString label6, QString label7, QString label8)
   : QListViewItem(parent, after, label1, label2, label3, label4, label5, label6, label7, label8)
 {
     init();
 }
 
+
 OListViewItem::OListViewItem(QListViewItem *parent, QListViewItem *after,
     QString label1, QString label2, QString label3, QString label4,
     QString label5, QString label6, QString label7, QString label8)
   : QListViewItem(parent, after, label1, label2, label3, label4, label5, label6, label7, label8)
 {
     init();
 }
 
+
 OListViewItem::~OListViewItem()
 {
 }
 
+
 void OListViewItem::init()
 {
     m_known = false;
 }
 
+
 const QColor &OListViewItem::backgroundColor()
 {
     return isAlternate() ? static_cast<OListView*>(listView())->alternateBackground() :
                            listView()->viewport()->colorGroup().base();
 }
 
+
 bool OListViewItem::isAlternate()
 {
     OListView *lv = static_cast<OListView*>( listView() );
 
     // check if the item above is an OListViewItem
     OListViewItem *above = static_cast<OListViewItem*>( itemAbove() );
     /*if (! itemAbove()->inherits( "OListViewItem" )) return false;*/
 
     // check if we have a valid alternate background color
     if (!(lv && lv->alternateBackground().isValid())) return false;
 
     m_known = above ? above->m_known : true;
     if (m_known)
     {
        m_odd = above ? !above->m_odd : false;
     }
     else
     {
         OListViewItem *item;
         bool previous = true;
         if (parent())
         {
             item = static_cast<OListViewItem *>(parent());
             if ( item /*&& item->inherits( "OListViewItem" )*/ ) previous = item->m_odd;
             item = static_cast<OListViewItem *>(parent()->firstChild());
             /* if ( !item.inherits( "OListViewItem" ) item = 0; */
         }
         else
         {
             item = static_cast<OListViewItem *>(lv->firstChild());
         }
 
         while(item)
         {
             item->m_odd = previous = !previous;
             item->m_known = true;
             item = static_cast<OListViewItem *>(item->nextSibling());
             /* if (!item.inherits( "OListViewItem" ) ) break; */
         }
     }
     return m_odd;
 }
 
+
 void OListViewItem::paintCell(QPainter *p, const QColorGroup &cg, int column, int width, int alignment)
 {
     QColorGroup _cg = cg;
     const QPixmap *pm = listView()->viewport()->backgroundPixmap();
     if (pm && !pm->isNull())
     {
         _cg.setBrush( QColorGroup::Base, QBrush(backgroundColor(), *pm) );
         p->setBrushOrigin( -listView()->contentsX(), -listView()->contentsY() );
     }
     else if ( isAlternate() )
     {
         _cg.setColor( QColorGroup::Base, static_cast<OListView*>( listView() )->alternateBackground() );
     }
     QListViewItem::paintCell( p, _cg, column, width, alignment );
 
     //FIXME: Use styling here!
 
     const QPen& pen = static_cast<OListView*>( listView() )->columnSeparator();
     p->setPen( pen );
     p->drawLine( width-1, 0, width-1, height() );
 }
 
+
 OListViewItem* OListViewItem::childFactory()
 {
     return new OListViewItem( this );
 }
 
+
 #ifndef QT_NO_DATASTREAM
 void OListViewItem::serializeTo( QDataStream& s ) const
 {
     #warning Caution... the binary format is still under construction...
     qDebug( "storing OListViewItem..." );
 
     // store item text
     for ( int i = 0; i < listView()->columns(); ++i )
     {
         s << text( i );
     }
 
     // calculate the number of children to serialize
     int items = 0;
     QListViewItem* item = firstChild();
     while ( item )
     {
         item = item->nextSibling();
         items++;
     }
 
     // store number of items and the items itself
     s << items;
     item = firstChild();
     for ( int i = 0; i < items; ++i )
     {
         s << *static_cast<OListViewItem*>( item );
         item = item->nextSibling();
     }
 
     qDebug( "OListviewItem stored." );
 }
+
+
 void OListViewItem::serializeFrom( QDataStream& s )
 {
     #warning Caution... the binary format is still under construction...
     qDebug( "loading OListViewItem..." );
 
     for ( int i = 0; i < listView()->columns(); ++i )
     {
         QString coltext;
         s >> coltext;
         qDebug( "read text '%s' for column %d", (const char*) coltext, i );
         setText( i, coltext );
     }
 
     int items;
     s >> items;
     qDebug( "read number of items = %d", items );
 
     for ( int i = 0; i < items; ++i )
     {
         OListViewItem* item = childFactory();
         s >> (*item);
     }
 
     qDebug( "OListViewItem loaded." );
 }
 
+
 QDataStream& operator<<( QDataStream& s, const OListViewItem& lvi )
 {
     lvi.serializeTo( s );
 }
 
+
 QDataStream& operator>>( QDataStream& s, OListViewItem& lvi )
 {
     lvi.serializeFrom( s );
 }
 #endif // QT_NO_DATASTREAM
+
+
+/*======================================================================================
+ * ONamedListView
+ *======================================================================================*/
+
+ONamedListView::ONamedListView( QWidget *parent, const char *name )
+               :OListView( parent, name )
+{
+}
+
+
+ONamedListView::~ONamedListView()
+{
+}
+
+
+void ONamedListView::addColumns( const QStringList& columns )
+{
+    for ( QStringList::ConstIterator it = columns.begin(); it != columns.end(); ++it )
+    {
+        qDebug( "adding column %s", (const char*) *it );
+        addColumn( *it );
+    }
+}
+
+
+/*======================================================================================
+ * ONamedListViewItem
+ *======================================================================================*/
+
+ONamedListViewItem::ONamedListViewItem( QListView* parent, const QStringList& texts )
+                   :OListViewItem( parent )
+{
+    setText( texts );
+}
+
+
+ONamedListViewItem::ONamedListViewItem( QListViewItem* parent, const QStringList& texts )
+                   :OListViewItem( parent )
+{
+    setText( texts );
+}
+
+
+ONamedListViewItem::ONamedListViewItem( QListView* parent, QListViewItem* after, const QStringList& texts )
+                   :OListViewItem( parent, after )
+{
+    setText( texts );
+}
+
+
+ONamedListViewItem::ONamedListViewItem( QListViewItem* parent, QListViewItem* after, const QStringList& texts )
+                   :OListViewItem( parent, after )
+{
+    setText( texts );
+}
+
+
+ONamedListViewItem::~ONamedListViewItem()
+{
+}
+
+
+void ONamedListViewItem::setText( const QStringList& texts )
+{
+    int col = 0;
+    for ( QStringList::ConstIterator it = texts.begin(); it != texts.end(); ++it )
+    {
+        qDebug( "setting column %d = text %s", col, (const char*) *it );
+        OListViewItem::setText( col++, *it );
+    }
+
+}
+
+
+void ONamedListViewItem::setText( const QString& column, const QString& text )
+{
+    //FIXME: If used excessively, this will slow down performance of updates
+    //FIXME: because of the linear search over all column texts.
+    //FIXME: I will optimize later by using a hash map.
+    for ( int i = 0; i < listView()->columns(); ++i )
+    {
+        if ( listView()->columnText( i ) == column )
+        {
+            OListViewItem::setText( i, text );
+            return;
+        }
+    }
+    qWarning( "ONamedListViewItem::setText(): Warning! Columntext '%s' not found.", (const char*) column );
+}
diff --git a/libopie2/opieui/olistview.h b/libopie2/opieui/olistview.h
index b62e278..99770bf 100644
--- a/libopie2/opieui/olistview.h
+++ b/libopie2/opieui/olistview.h
@@ -1,235 +1,310 @@
 /*
                              This file is part of the Opie Project
 
               =.             (C) 2003 Michael 'Mickey' Lauer <mickey@tm.informatik.uni-frankfurt.de>
             .=l.
            .>+-=
  _;:,     .>    :=|.         This program is free software; you can
 .> <`_,   >  .   <=          redistribute it and/or  modify it under
 :`=1 )Y*s>-.--   :           the terms of the GNU Library General Public
 .="- .-=="i,     .._         License as published by the Free Software
  - .   .-<_>     .<>         Foundation; either version 2 of the License,
      ._= =}       :          or (at your option) any later version.
     .%`+i>       _;_.
     .i_,=:_.      -<s.       This program is distributed in the hope that
      +  .  -:.       =       it will be useful,  but WITHOUT ANY WARRANTY;
     : ..    .:,     . . .    without even the implied warranty of
     =_        +     =;=|`    MERCHANTABILITY or FITNESS FOR A
   _.=:.       :    :=>`:     PARTICULAR PURPOSE. See the GNU
 ..}^=.=       =       ;      Library General Public License for more
 ++=   -.     .`     .:       details.
  :     =  ...= . :.=-
  -.   .:....=;==+<;          You should have received a copy of the GNU
   -_. . .   )=.  =           Library General Public License along with
     --        :-=`           this library; see the file COPYING.LIB.
                              If not, write to the Free Software Foundation,
                              Inc., 59 Temple Place - Suite 330,
                              Boston, MA 02111-1307, USA.
 
 */
 
 #ifndef OLISTVIEW_H
 #define OLISTVIEW_H
 
 #include <qcolor.h>
 #include <qlistview.h>
 #include <qpen.h>
 #include <qdatastream.h>
 
 class OListViewItem;
 
+/*======================================================================================
+ * OListView
+ *======================================================================================*/
+
 /**
+ * @brief A list/tree widget.
+ *
  * A @ref QListView variant featuring visual and functional enhancements
  * like an alternate background for odd rows, an autostretch mode
  * for the width of the widget ( >= Qt 3 only ) and persistence capabilities.
  *
  * @author Michael 'Mickey' Lauer <mickey@tm.informatik.uni-frankfurt.de>
- * @short OListView list/tree widget.
  */
  class OListView: public QListView
 {
   public:
    /**
     * Constructor.
     *
-    * The parameters @p parent and @p name are handled by
+    * The parameters @a parent and @a name are handled by
     * @ref QListView, as usual.
     */
     OListView ( QWidget *parent = 0, const char *name = 0 );
-
    /**
     * Destructor.
     */
     virtual ~OListView();
-
    /**
     * Let the last column fit exactly all the available width.
     */
     void setFullWidth( bool fullWidth );
-
    /**
     * Returns whether the last column is set to fit the available width.
     */
     bool fullWidth() const;
-
    /**
     * Reimplemented for full width support
     */
     virtual int addColumn( const QString& label, int width = -1 );
-
    /**
     * Reimplemented for full width support
     */
     virtual int addColumn( const QIconSet& iconset, const QString& label, int width = -1 );
-
    /**
     * Reimplemented for full width support
     */
     virtual void removeColumn(int index);
-
    /**
-    * sets the alternate background background color.
+    * Set the alternate background background @a color.
+    * Set to an invalid color to disable alternate colors.
     * This only has an effect if the items are OListViewItems
-    *
-    * @param c the color to use for every other item. Set to an invalid
-    *        color to disable alternate colors.
     */
-    void setAlternateBackground( const QColor &c );
-
+    void setAlternateBackground( const QColor& color );
    /**
-    * sets the column separator pen.
-    *
-    * @param p the pen used to draw the column separator.
+    * Sets the column separator @a pen.
     */
-    void setColumnSeparator( const QPen &p );
+    void setColumnSeparator( const QPen& pen );
 
    /**
-    * @return the alternate background color
+    * @returns the alternate background color
     */
     const QColor& alternateBackground() const;
-
    /**
     * @return the column separator pen
     */
     const QPen& columnSeparator() const;
-
    /**
-    * create a list view item as child of this object
-    * @return the new object
+    * Create a list view item as child of this object
+    * @returns the new object
     */
     virtual OListViewItem* childFactory();
-
 #ifndef QT_NO_DATASTREAM
    /**
-    * serialize this object to a @ref QDataStream
-    * @param s the stream used to serialize this object.
+    * Serialize this object to @ref QDataStream @a stream
     */
-    virtual void serializeTo( QDataStream& s ) const;
-
+    virtual void serializeTo( QDataStream& stream ) const;
    /**
-    * serialize this object from a @ref QDataStream
-    * @param s the stream used to serialize this object.
+    * Serialize this object from a @ref QDataStream @a stream
     */
     virtual void serializeFrom( QDataStream& s );
 #endif
 
   private:
     QColor m_alternateBackground;
     bool m_fullWidth;
     QPen m_columnSeparator;
 };
 
 #ifndef QT_NO_DATASTREAM
 /**
-  * \relates QListView
-  * Writes a listview to the stream and returns a reference to the stream.
+  * @relates OListView
+  * Writes @a listview to the @a stream and returns a reference to the stream.
   */
-QDataStream& operator<<( QDataStream& s, const OListView& lv );
+QDataStream& operator<<( QDataStream& stream, const OListView& listview );
 /**
-  * \relates QListView
-  * Reads a listview from the stream and returns a reference to the stream.
+  * @relates OListView
+  * Reads @a listview from the @a stream and returns a reference to the stream.
   */
-QDataStream& operator>>( QDataStream& s, OListView& lv );
+QDataStream& operator>>( QDataStream& stream, OListView& listview );
 #endif // QT_NO_DATASTREAM
 
-//****************************** OListViewItem ******************************************************************
+/*======================================================================================
+ * OListViewItem
+ *======================================================================================*/
 
 class OListViewItem: public QListViewItem
 {
   public:
+    /**
+     * Constructors.
+     */
     OListViewItem( QListView * parent );
     OListViewItem( QListViewItem * parent );
     OListViewItem( QListView * parent, QListViewItem * after );
     OListViewItem( QListViewItem * parent, QListViewItem * after );
 
     OListViewItem( QListView * parent,
         QString,     QString = QString::null,
         QString = QString::null, QString = QString::null,
         QString = QString::null, QString = QString::null,
         QString = QString::null, QString = QString::null );
 
     OListViewItem( QListViewItem * parent,
         QString,     QString = QString::null,
         QString = QString::null, QString = QString::null,
         QString = QString::null, QString = QString::null,
         QString = QString::null, QString = QString::null );
 
     OListViewItem( QListView * parent, QListViewItem * after,
         QString,     QString = QString::null,
         QString = QString::null, QString = QString::null,
         QString = QString::null, QString = QString::null,
         QString = QString::null, QString = QString::null );
 
     OListViewItem( QListViewItem * parent, QListViewItem * after,
         QString,     QString = QString::null,
         QString = QString::null, QString = QString::null,
         QString = QString::null, QString = QString::null,
         QString = QString::null, QString = QString::null );
-
+    /**
+     * Destructor.
+     */
     virtual ~OListViewItem();
-
+    /**
+     * @returns the background color of the list item.
+     */
     const QColor& backgroundColor();
+    /**
+     * @returns true, if the item is at an odd position and
+     * thus have to be painted with the alternate background color.
+     */
     bool isAlternate();
+    /**
+     * @note: Reimplemented for internal purposes - the API is not affected
+     *
+     */
     void paintCell( QPainter *p, const QColorGroup &cg, int column, int width, int alignment );
+    /**
+     * Perform object initialization.
+     */
     void init();
-
    /**
     * create a list view item as child of this object
-    * @return the new object
+    * @returns the new object
     */
     virtual OListViewItem* childFactory();
-
     #ifndef QT_NO_DATASTREAM
    /**
     * serialize this object to or from a @ref QDataStream
     * @param s the stream used to serialize this object.
     */
     virtual void serializeTo( QDataStream& s ) const;
 
    /**
     * serialize this object to or from a @ref QDataStream
     * @param s the stream used to serialize this object.
     */
     virtual void serializeFrom( QDataStream& s );
     #endif
 
   private:
     bool m_known;
     bool m_odd;
 };
 
 #ifndef QT_NO_DATASTREAM
 /**
-  * \relates QListViewItem
-  * Writes a listview item and all subitems recursively to the stream
+  * @relates QListViewItem
+  * Writes listview @a item and all subitems recursively to @a stream
   * and returns a reference to the stream.
   */
-QDataStream& operator<<( QDataStream &s, const OListViewItem& lvi );
+QDataStream& operator<<( QDataStream& stream, const OListViewItem& item );
 /**
-  * \relates QListViewItem
-  * Reads a listview item from the stream and returns a reference to the stream.
+  * @relates QListViewItem
+  * Reads listview @a item from @a stream and returns a reference to the stream.
   */
-QDataStream& operator>>( QDataStream &s, OListViewItem& lvi );
+QDataStream& operator>>( QDataStream& stream, OListViewItem& item );
 #endif // QT_NO_DATASTREAM
 
+/*======================================================================================
+ * ONamedListView
+ *======================================================================================*/
+
+/**
+ * @brief An OListView variant with named columns.
+ *
+ * This class provides a higher-level interface to the columns in an OListView.
+ *
+ * @author Michael 'Mickey' Lauer <mickey@tm.informatik.uni-frankfurt.de>
+ */
+class ONamedListView: public OListView
+{
+  public:
+    /**
+     * Constructor.
+     *
+     * The parameters @a parent and @a name are handled by
+     * @ref OListView, as usual.
+     */
+    ONamedListView( QWidget* parent = 0, const char* name = 0 );
+    /**
+     * Destructor.
+     */
+    virtual ~ONamedListView();
+    /**
+     * Add a number of @a columns to the listview.
+     */
+    virtual void addColumns( const QStringList& columns );
+};
+
+/*======================================================================================
+ * ONamedListViewItem
+ *======================================================================================*/
+
+/**
+ * @brief An OListView variant with named columns.
+ *
+ * This class provides a higher-level interface to the columns in an OListViewItem.
+ *
+ * @author Michael 'Mickey' Lauer <mickey@tm.informatik.uni-frankfurt.de>
+ */
+class ONamedListViewItem: public OListViewItem
+{
+  public:
+    /**
+     * Constructor. Accepts the same parameters as a @ref OListViewItem,
+     * plus a @ref QStringList which holds an arbitrary number of @a texts.
+     */
+    ONamedListViewItem( QListView* parent, const QStringList& texts );
+    ONamedListViewItem( QListViewItem* parent, const QStringList& texts );
+    ONamedListViewItem( QListView* parent, QListViewItem* after, const QStringList& texts );
+    ONamedListViewItem( QListViewItem* parent, QListViewItem* after, const QStringList& texts );
+    /**
+     * Destructor.
+     */
+    virtual ~ONamedListViewItem();
+    /**
+     * Sets the text in column @a column to @a text.
+     * This method differs from @ref QListViewItem::setText() in that it
+     * accepts a string as column indicator instead of an int.
+     */
+    virtual void setText( const QString& column, const QString& text );
+    /**
+     * Sets a number of @a texts for this item.
+     */
+    virtual void setText( const QStringList& texts );
+};
+
+
 #endif // OLISTVIEW_H