1 files changed, 78 insertions, 0 deletions

diff --git a/libopie/ofileselector.cpp b/libopie/ofileselector.cpp
index 577e916..9afe9c7 100644
--- a/libopie/ofileselector.cpp
+++ b/libopie/ofileselector.cpp
@@ -503,354 +503,432 @@ void OFileViewFileListView::cdUP() {
 
     emit selector()->dirSelected( m_currentDir );
     reread( m_all );
 }
 void OFileViewFileListView::cdHome() {
     m_currentDir = QDir::homeDirPath();
     emit selector()->dirSelected( m_currentDir );
     reread( m_all );
 }
 void OFileViewFileListView::cdDoc() {
     m_currentDir = QPEApplication::documentDir();
     emit selector()->dirSelected( m_currentDir );
     reread( m_all );
 }
 void OFileViewFileListView::changeDir( const QString& dir ) {
     m_currentDir = dir;
     emit selector()->dirSelected( m_currentDir );
     reread( m_all );
 }
 void OFileViewFileListView::slotFSActivated( int id ) {
     changeDir ( m_dev[m_fsPop->text(id)]  );
 }
 
 /*  check if the mimetype in mime
  *  complies with the  one which is current
  */
 /*
  * We've the mimetype of the file
  * We need to get the stringlist of the current mimetype
  *
  * mime = image@slashjpeg
  * QStringList = 'image@slash*'
  * or QStringList = image/jpeg;image/png;application/x-ogg
  * or QStringList = application/x-ogg;image@slash*;
  * with all these mime filters it should get acceptes
  * to do so we need to look if mime is contained inside
  * the stringlist
  * if it's contained return true
  * if not ( I'm no RegExp expert at all ) we'll look if a '@slash*'
  * is contained in the mimefilter and then we will
  * look if both are equal until the '/'
  */
 bool OFileViewFileListView::compliesMime( const QString& str) {
     if (str.isEmpty() || m_mimes.isEmpty() || str.stripWhiteSpace().isEmpty() )
         return true;
 
     for (QStringList::Iterator it = m_mimes.begin(); it != m_mimes.end(); ++it ) {
         QRegExp reg( (*it) );
         reg.setWildcard( true );
         if ( str.find( reg ) != -1 )
             return true;
 
     }
     return false;
 }
 /*
  * The listView giving access to the file system!
  */
 class OFileViewFileSystem : public OFileViewInterface {
 public:
     OFileViewFileSystem( OFileSelector* );
     ~OFileViewFileSystem();
 
     QString selectedName() const;
     QString selectedPath() const;
 
     QString directory()const;
     void reread();
     int fileCount()const;
 
     QWidget* widget( QWidget* parent );
     void activate( const QString& );
 private:
     OFileViewFileListView* m_view;
     bool m_all : 1;
 };
 OFileViewFileSystem::OFileViewFileSystem( OFileSelector* sel)
     : OFileViewInterface( sel ) {
     m_view = 0;
     m_all = false;
 }
 OFileViewFileSystem::~OFileViewFileSystem() {
 }
 QString OFileViewFileSystem::selectedName()const{
     if (!m_view )
         return QString::null;
 
     QString cFN=currentFileName();
     if (cFN.startsWith("/")) return cFN;
     return m_view->currentDir() + "/" + cFN;
 }
 QString OFileViewFileSystem::selectedPath()const{
     return QString::null;
 }
 QString OFileViewFileSystem::directory()const{
     if (!m_view)
         return QString::null;
 
     OFileSelectorItem* item = m_view->currentItem();
     if (!item )
         return QString::null;
 
     return QDir(item->directory() ).absPath();
 }
 void OFileViewFileSystem::reread() {
     if (!m_view)
         return;
 
     m_view->reread( m_all );
 }
 int OFileViewFileSystem::fileCount()const{
     if (!m_view )
         return -1;
     return m_view->fileCount();
 }
 QWidget* OFileViewFileSystem::widget( QWidget* parent ) {
     if (!m_view ) {
         m_view = new OFileViewFileListView( parent, startDirectory(), selector() );
     }
     return m_view;
 }
 void OFileViewFileSystem::activate( const QString& str) {
     m_all =  (str != QObject::tr("Files") );
 
 
 }
 
 /* Selector */
+/**
+ * @short new and complete c'tor
+ *
+ * Create a OFileSelector to let the user select a file. It can
+ * either be used to open a file, select a save name in a dir or
+ * as a dropin for the FileSelector.
+ *
+ * <pre>
+ *  QMap<QString, QStringList> mimeTypes;
+ *  QStringList types;
+ *  types << "text[slash]* ";
+ *  types << "audio[slash]*";
+ *  mimeTypes.insert( tr("Audio and Text"), types );
+ *  mimeTypes.insert( tr("All"), "*[slash]*);
+ *
+ *  now you could create your fileselector
+ * </pre>
+ *
+ *
+ * @param parent the parent of this widget
+ * @param mode The mode from the enum Mode (Open,Save,FILESELECTOR)
+ * @param sel The  selector to be used
+ * @param dirName The name of the dir to start int
+ * @param fileName The fileName placed in the fileselector lineedit
+ * @param mimetypes The MimeType map of used mimetypes
+ * @param showNew Show a New Button. Most likely to be used in the FileSelector view.
+ * @param showClose Show a Close Button. Most likely to be used in FileSelector view.
+ *
+ */
 OFileSelector::OFileSelector( QWidget* parent, int mode, int sel,
                               const QString& dirName, const QString& fileName,
                               const MimeTypes& mimetypes,
                               bool showNew,  bool showClose)
     : QWidget( parent, "OFileSelector" )
 {
     m_current = 0;
     m_shNew = showNew;
     m_shClose = showClose;
     m_mimeType = mimetypes;
     m_startDir = dirName;
 
     m_mode = mode;
     m_selector = sel;
 
     initUI();
     m_lneEdit->setText( fileName );
     initMime();
     initViews();
 
     QString str;
     switch ( m_selector ) {
     default:
     case Normal:
         str = QObject::tr("Documents");
         m_cmbView->setCurrentItem( 0 );
         break;
     case Extended:
         str = QObject::tr("Files");
         m_cmbView->setCurrentItem( 1 );
         break;
     case ExtendedAll:
         str = QObject::tr("All Files");
         m_cmbView->setCurrentItem( 2 );
         break;
     }
     slotViewChange( str );
 
 }
+
+/**
+ * This a convience c'tor to just substitute the use of FileSelector
+ */
 OFileSelector::OFileSelector( const QString& mimeFilter, QWidget* parent, const char* name,
                               bool showNew, bool showClose )
     : QWidget( parent, name )
 {
     m_current = 0;
     m_shNew   = showNew;
     m_shClose = showClose;
     m_startDir = QPEApplication::documentDir();
 
     if (!mimeFilter.isEmpty() )
         m_mimeType.insert(mimeFilter, QStringList::split(";", mimeFilter ) );
 
     m_mode = OFileSelector::FileSelector;
     m_selector = OFileSelector::Normal;
 
     initUI();
     initMime();
     initViews();
     m_cmbView->setCurrentItem( 0 );
     slotViewChange( QObject::tr("Documents") );
 }
 /*
  * INIT UI will set up the basic GUI
  * Layout: Simple VBoxLayout
  * On top a WidgetStack containing the Views...
  *  - List View
  *  - Document View
  * Below we will have a Label + LineEdit
  * Below we will have two ComoBoxes one for choosing the view one for
  *       choosing the mimetype
  */
 void OFileSelector::initUI() {
     QVBoxLayout* lay = new QVBoxLayout( this );
 
     m_stack = new QWidgetStack( this );
     lay->addWidget( m_stack, 1000 );
 
     m_nameBox = new QHBox( this );
     (void)new QLabel( tr("Name:"), m_nameBox );
     m_lneEdit = new QLineEdit( m_nameBox );
     m_lneEdit ->installEventFilter(this);
     lay->addWidget( m_nameBox );
 
     m_cmbBox = new QHBox( this );
     m_cmbView = new QComboBox( m_cmbBox );
     m_cmbMime = new QComboBox( m_cmbBox );
     lay->addWidget( m_cmbBox );
 }
 
 /*
  * This will make sure that the return key in the name edit causes dialogs to close
  */
 
 bool OFileSelector::eventFilter (QObject *o, QEvent *e) {
     if ( e->type() == QEvent::KeyPress ) {
         QKeyEvent *k = (QKeyEvent *)e;
         if ( (k->key()==Key_Enter) || (k->key()==Key_Return)) {
             emit ok();
             return true;
         }
     }
     return false;
 }
 
 /*
  * This will insert the MimeTypes into the Combo Box
  * And also connect the changed signal
  *
  * AutoMimeTyping is disabled for now. It used to reparse a dir and then set available mimetypes
  */
 void OFileSelector::initMime() {
     MimeTypes::Iterator it;
     for ( it = m_mimeType.begin(); it != m_mimeType.end(); ++it ) {
         m_cmbMime->insertItem( it.key() );
     }
     m_cmbMime->setCurrentItem( 0 );
 
     connect( m_cmbMime, SIGNAL(activated(int) ),
              this, SLOT(slotMimeTypeChanged() ) );
 
 }
 void OFileSelector::initViews() {
     m_cmbView->insertItem( QObject::tr("Documents") );
     m_cmbView->insertItem( QObject::tr("Files") );
     m_cmbView->insertItem( QObject::tr("All Files") );
     connect(m_cmbView, SIGNAL(activated( const QString& ) ),
             this, SLOT(slotViewChange( const QString& ) ) );
 
 
     m_views.insert( QObject::tr("Documents"), new ODocumentFileView(this) );
 
     /* see above why add both */
     OFileViewInterface* in = new OFileViewFileSystem( this );
     m_views.insert( QObject::tr("Files"), in );
     m_views.insert( QObject::tr("All Files"), in );
 }
+
+/**
+ * d'tor
+ */
 OFileSelector::~OFileSelector() {
 
 }
+
+/**
+ * Convience function for the fileselector
+ * make sure to delete the DocLnk
+ *
+ * @see DocLnk
+ * @todo remove in ODP
+ */
 const DocLnk* OFileSelector::selected() {
     DocLnk* lnk = new DocLnk( currentView()->selectedDocument() );
     return lnk;
 }
+
+/**
+ *
+ * @return the name of the selected file
+ */
 QString OFileSelector::selectedName()const{
        return currentView()->selectedName();
 }
+
+/**
+ * @return the selected path
+ */
 QString OFileSelector::selectedPath()const {
     return currentView()->selectedPath();
 }
+
+/**
+ * @return the directory name
+ */
 QString OFileSelector::directory()const {
     return currentView()->directory();
 }
+
+/**
+ * @return a DocLnk for the selected document
+ */
 DocLnk OFileSelector::selectedDocument()const {
     return currentView()->selectedDocument();
 }
+
+/**
+ * @return the number of items for the current view
+ */
 int OFileSelector::fileCount()const {
     return currentView()->fileCount();
 }
+
+/**
+ * @return  reparse the file content
+ */
 void OFileSelector::reread() {
     return currentView()->reread();
 }
 OFileViewInterface* OFileSelector::currentView()const{
     return m_current;
 }
 bool OFileSelector::showNew()const {
     return m_shNew;
 }
 bool OFileSelector::showClose()const {
     return m_shClose;
 }
 MimeTypes OFileSelector::mimeTypes()const {
     return m_mimeType;
 }
+
+/**
+ * @return the Mode of the OFileSelector
+ */
 int OFileSelector::mode()const{
     return m_mode;
 }
+
+/**
+ * @return the Selector of the OFileSelector
+ */
 int OFileSelector::selector()const{
     return m_selector;
 }
 QStringList OFileSelector::currentMimeType()const {
     return m_mimeType[m_cmbMime->currentText()];
 }
 void OFileSelector::slotMimeTypeChanged() {
     reread();
 }
 void OFileSelector::slotDocLnkBridge( const DocLnk& lnk) {
     m_lneEdit->setText( lnk.name() );
     emit fileSelected( lnk );
     emit fileSelected( lnk.name() );
 }
 void OFileSelector::slotFileBridge( const QString& str) {
     DocLnk lnk( str );
     emit fileSelected( lnk );
 }
 void OFileSelector::slotViewChange( const QString& view ) {
     OFileViewInterface* interface = m_views[view];
     if (!interface)
         return;
 
     interface->activate( view );
     if (m_current)
         m_stack->removeWidget( m_current->widget( m_stack ) );
 
     static int id = 1;
 
     m_stack->addWidget( interface->widget(m_stack), id );
     m_stack->raiseWidget( id );
 
     interface->reread();
     m_current = interface;
 
     id++;
 }
 void OFileSelector::setNewVisible( bool b ) {
     m_shNew = b;
     currentView()->reread();
 }
 void OFileSelector::setCloseVisible( bool b ) {
     m_shClose = b;
     currentView()->reread();
 }
 void OFileSelector::setNameVisible( bool b ) {
     if ( b )
         m_nameBox->show();
     else
         m_nameBox->hide();
 }