File indexing completed on 2022-10-04 13:56:34

0001 /*
0002  * Vocabulary Document for KDE Edu
0003  * SPDX-FileCopyrightText: 1999-2001 Ewald Arnold <kvoctrain@ewald-arnold.de>
0004  * SPDX-FileCopyrightText: 2005, 2007 Peter Hedlund <peter.hedlund@kdemail.net>
0005  * SPDX-FileCopyrightText: 2007 Frederik Gladhorn <frederik.gladhorn@kdemail.net>
0006  * SPDX-License-Identifier: GPL-2.0-or-later
0007 */
0008 #ifndef KEDUVOCDOCUMENT_H
0009 #define KEDUVOCDOCUMENT_H
0010 
0011 #include "keduvocdocument_export.h"
0012 
0013 #include "keduvocidentifier.h"
0014 #include "keduvocarticle.h"
0015 #include "keduvocconjugation.h"
0016 
0017 #include <QObject>
0018 #include <QList>
0019 #include <QMap>
0020 #include <QUrl>
0021 
0022 class KEduVocLesson;
0023 class KEduVocWordType;
0024 class KEduVocLeitnerBox;
0025 
0026 /**
0027  * @brief The primary entry point to the hierarchy of objects describing vocabularies.
0028  * @details This class contains the expressions of your vocabulary
0029  * as well as other information about the vocabulary.
0030  */
0031 class KEDUVOCDOCUMENT_EXPORT KEduVocDocument : public QObject
0032 {
0033     Q_OBJECT
0034 public:
0035 
0036     ///@todo in new API change enums to QFlags
0037 
0038     /// known vocabulary file types
0039     enum FileType {
0040         KvdNone,      ///< handles nothing
0041         Automatic,    ///< try to automatically determine file type
0042         Kvtml,        ///< Kvtml 2.0
0043         Wql,          ///< Word Quiz format
0044         Pauker,       ///< Pauker format
0045         Vokabeln,     ///< Vokabeln format
0046         Xdxf,         ///< XDXF format @see https://github.com/soshial/xdxf_makedict/blob/master/format_standard/xdxf_strict.dtd
0047         Csv,          ///< Command separated values
0048         Kvtml1        ///< KVTML 1.0
0049     };
0050 
0051     /// the return code when opening/saving
0052     enum ErrorCode {
0053         NoError = 0,         ///< no error
0054         Unknown,             ///< unspecified error
0055         InvalidXml,          ///< malformed xml or bad file formatting
0056         FileTypeUnknown,     ///< unknown file type
0057         FileCannotWrite,     ///< unwritable file
0058         FileWriterFailed,    ///< file writer failed
0059         FileCannotRead,      ///< unreadable file
0060         FileReaderFailed,    ///< file reader failed
0061         FileDoesNotExist,    ///< unknown file type
0062         FileLocked,          ///< An autosave file exists for this document
0063         FileCannotLock,      ///< Can't create an autosave file for this document
0064         FileIsReadOnly       ///< Can't save this file because it was opened read-only
0065     };
0066 
0067     /// indicates file open/save status locking or readonly
0068     enum FileHandlingFlags
0069     {
0070         FileDefaultHandling = 0x0, ///< Default status
0071         FileIgnoreLock = 0x1,      ///< Ignore the file lock
0072     FileOpenReadOnly = 0x2     ///< Open without any intention to change and save back later. This also implies FileIgnoreLock.
0073     };
0074 
0075     /// used as parameter for pattern
0076     enum FileDialogMode
0077     {
0078         Reading,
0079         Writing
0080     };
0081 
0082     /// delete only empty lessons or also if they have entries
0083     enum LessonDeletion
0084     {
0085         DeleteEmptyLesson,
0086         DeleteEntriesAndLesson
0087     };
0088 
0089     /**
0090      * Constructor for a KDEEdu vocabulary document
0091      *
0092      * @param parent calling object
0093      */
0094     explicit KEduVocDocument( QObject* parent = nullptr );
0095 
0096     /**
0097      * Destructor
0098      */
0099     ~KEduVocDocument() override;
0100 
0101 
0102     /** @name Whole Document Methods
0103      * Methods related to saving/loading and locating the document
0104      * @nosubgrouping
0105      */
0106     ///@{
0107 
0108     /**
0109      * Opens and locks a document file
0110      *
0111      * Note: This is intended to be preserve binary compatible with int open(const QUrl&)
0112      *       When the API increments the major version number, then merge them
0113      *
0114      * @param url      url to file to open
0115      * @param flags How to handle expected unusual conditions (i.e. locking)
0116      * @returns        ErrorCode
0117      */
0118     ErrorCode open(const QUrl &url,  FileHandlingFlags flags = FileDefaultHandling);
0119 
0120     /**
0121      * Close a document file and release the lock on the file
0122      *
0123      */
0124     void close();
0125 
0126     /**
0127      * Saves the data under the given name
0128      *
0129      * @pre generator is set.
0130      *
0131      * Note: This is intended to be preserve binary compatible with
0132      *       int saveAs(const QUrl&, FileType ft, const QString & generator );
0133      *       When the API increments the major version number, then merge them
0134      *
0135      * @param url        if url is empty (or NULL) actual name is preserved
0136      * @param ft         the filetype to be used when saving the document
0137      * @param flags How to handle expected unusual conditions (i.e. locking)
0138      * @returns          ErrorCode
0139      */
0140     ErrorCode saveAs( const QUrl & url, FileType ft,  FileHandlingFlags flags  = FileDefaultHandling);
0141 
0142     /** @details  returns a QByteArray KVTML2 representation of this doc
0143      * @param generator name of the application creating the QByteArray
0144      * @return KVTML2 XML
0145      * @todo in new API if this should be part of save*/
0146     QByteArray toByteArray(const QString &generator);
0147 
0148     /**
0149      * Merges data from another document (UNIMPLEMENTED)
0150      *
0151      * @param docToMerge       document containing the data to be merged
0152      * @param matchIdentifiers if true only entries having identifiers present in the
0153      *                         current document will be mergedurl is empty (or NULL) actual name is preserved
0154      */
0155     void merge( KEduVocDocument *docToMerge, bool matchIdentifiers );
0156 
0157     /**
0158      * Indicates if the document is modified
0159      *
0160      * @param dirty   new state
0161      */
0162     void setModified( bool dirty = true );
0163 
0164     /** @returns the modification state of the doc */
0165     bool isModified() const;
0166 
0167     /**
0168      * Sets the URL of the XML file
0169      * @param url URL
0170      */
0171     void setUrl( const QUrl& url );
0172 
0173     /** @returns the URL of the XML file */
0174     QUrl url() const;
0175 
0176     ///@}
0177 
0178 
0179 
0180     /** @name General Document Properties
0181      *
0182      */
0183     ///@{
0184 
0185     /** Set the title of the file
0186      * @param title title to set */
0187     void setTitle( const QString & title );
0188 
0189     /** @returns the title of the file */
0190     QString title() const;
0191 
0192     /** Set the author of the file
0193      * @param author author to set */
0194     void setAuthor( const QString & author );
0195 
0196     /** @returns the author of the file */
0197     QString author() const;
0198 
0199     /** Set the author contact info
0200      * @param authorContact contact email/contact info to set */
0201     void setAuthorContact( const QString & authorContact );
0202 
0203     /** @returns the author contact information */
0204     QString authorContact() const;
0205 
0206     /** Set the license of the file
0207      * @param license license to set */
0208     void setLicense( const QString & license );
0209 
0210     /** @returns the license of the file */
0211     QString license() const;
0212 
0213     /** Set the comment of the file
0214      * @param comment comment to set */
0215     void setDocumentComment( const QString & comment );
0216 
0217     /** @return the comment of the file */
0218     QString documentComment() const;
0219 
0220     /** Set the category of the file
0221      * @param category category to set */
0222     void setCategory( const QString & category );
0223 
0224     /** @return the category of the file */
0225     QString category() const;
0226 
0227     /**
0228      * Sets the generator of the file
0229      * @param generator name of the application generating the file
0230      */
0231     void setGenerator( const QString & generator );
0232 
0233     /** @returns the generator of the file */
0234     QString generator() const;
0235 
0236     /** Sets version of the loaded file
0237      * @param ver the new version */
0238     void setVersion( const QString & ver );
0239 
0240     /** @returns the version of the loaded file */
0241     QString version() const;
0242 
0243     ///@}
0244 
0245 
0246 
0247     /** @name Identifier Methods
0248      *
0249      */
0250     ///@{
0251 
0252     /**
0253      * @returns the number of different identifiers (usually languages)
0254      */
0255     int identifierCount() const;
0256 
0257     /**
0258      * Appends a new identifier (usually a language)
0259      *
0260      * @param identifier the identifier to append. If empty default names are used.
0261      * @returns the identifier number
0262      */
0263     int appendIdentifier( const KEduVocIdentifier & identifier = KEduVocIdentifier());
0264 
0265     /**
0266      * Sets the identifier of translation
0267      *
0268      * @param index            number of translation 0..x
0269      * @param lang             the language identifier: en=english, de=german, ...
0270      */
0271     void setIdentifier( int index, const KEduVocIdentifier& lang );
0272 
0273     /**
0274      * Returns the identifier of translation @p index
0275      *
0276      * @param index            number of translation 0..x
0277      * @returns                the language identifier: en=english, de=german, ...
0278      */
0279     KEduVocIdentifier& identifier( int index );
0280 
0281     /**
0282      * Const overload of identifier(int);
0283      * @param index of the identifier
0284      * @return reference to the identifier
0285      */
0286     const KEduVocIdentifier& identifier( int index ) const;
0287 
0288     /**
0289      * Removes identifier and the according translation in all entries
0290      *
0291      * @param index            number of translation 0..x
0292      */
0293     void removeIdentifier( int index );
0294 
0295     /**
0296      * Determines the index of a given identifier
0297      *
0298      * @param name             identifier of language
0299      * @returns                index of identifier, 0 = original, 1..n = translation, -1 = not found
0300      */
0301     int indexOfIdentifier( const QString &name ) const;
0302 
0303 
0304     ///@}
0305 
0306 
0307 
0308     /** @name Grade Methods
0309      *
0310      */
0311     ///@{
0312 
0313     /**
0314      * Retrieves the identifiers for the current query
0315      * not written in the new version!
0316      *
0317      * @param org        identifier for original
0318      * @param trans      identifier for translation
0319      */
0320     KEDUVOCDOCUMENT_DEPRECATED void queryIdentifier( QString &org, QString &trans ) const;
0321 
0322     /**
0323      * Sets the identifiers for the current query
0324      * not written in the new version!
0325      *
0326      * @param org        identifier for original
0327      * @param trans      identifier for translation
0328      */
0329     KEDUVOCDOCUMENT_DEPRECATED void setQueryIdentifier( const QString &org, const QString &trans );
0330 
0331 
0332     ///@}
0333 
0334 
0335 
0336     /** @name Lesson Methods
0337      *
0338      */
0339     ///@{
0340 
0341     /** @brief Get the lesson root object
0342      * @returns a pointer to the lesson object
0343      */
0344     KEduVocLesson * lesson();
0345 
0346     /** @brief Returns the root word type object
0347         @return poitner to the internal word type object */
0348     KEduVocWordType * wordTypeContainer();
0349 
0350     /** @brief Returns the root Leitner container
0351         @return poitner to the internal Leitner container object
0352         @todo in new API determine if this is used */
0353     KEduVocLeitnerBox * leitnerContainer();
0354 
0355 
0356     ///@}
0357 
0358 
0359 
0360     /** @name File Format Specific Methods
0361      *
0362      */
0363     ///@{
0364 
0365     /**
0366      * Returns the delimiter (separator) used for csv import and export.
0367      * The default is a single tab character
0368      *
0369      * @returns                the delimiter used
0370      */
0371     QString csvDelimiter() const;
0372 
0373     /**
0374      * Sets the delimiter (separator) used for csv import and export
0375      *
0376      * @param delimiter        the delimiter to use
0377      */
0378     void setCsvDelimiter( const QString &delimiter );
0379 
0380     ///@}
0381 
0382     /**
0383      * @details Detects the file type
0384      * @param fileName filename
0385      * @return enum of filetype
0386      */
0387     static FileType detectFileType(const QString &fileName);
0388 
0389     /**
0390      * Create a string with the supported document types, that can be used
0391      * as filter in KFileDialog. It includes also an entry to match all the
0392      * supported types.
0393      *
0394      * @param mode             the mode for the supported document types
0395      * @returns                the filter string
0396      */
0397     static QString pattern( FileDialogMode mode );
0398 
0399     /**
0400      * @brief Returns a QString description of the errorCode
0401      * @param errorCode the code
0402      * @returns a user useful error string.
0403      */
0404     static QString errorDescription( int errorCode );
0405 
0406 Q_SIGNALS:
0407     /**
0408      * @brief never used
0409      * @param curr_percent
0410      */
0411     void progressChanged( KEduVocDocument *, int curr_percent );
0412 
0413     /**
0414      * @brief Emitted when the document becomes modified or saved.
0415      * @param mod the current modified/dirty state
0416      * @returns state (true=modified)
0417      */
0418     void docModified( bool mod );
0419 
0420 private:
0421     // The private data of this - see KEduVocDocument::Private, implemented in keduvocdocument.cpp
0422     class KEduVocDocumentPrivate;
0423     KEduVocDocumentPrivate* const d;  ///< d pointer to private class
0424 
0425     Q_DISABLE_COPY( KEduVocDocument )
0426 };
0427 
0428 
0429 #endif // KEDUVOCDOCUMENT_H