File indexing completed on 2024-12-08 06:28:22

0001 /*
0002     This file is part of Kiten, a KDE Japanese Reference Tool
0003     SPDX-FileCopyrightText: 2006 Joseph Kerian <jkerian@gmail.com>
0004 
0005     SPDX-License-Identifier: LGPL-2.0-or-later
0006 */
0007 
0008 #ifndef KITEN_DICTFILE_H
0009 #define KITEN_DICTFILE_H
0010 
0011 #include "kiten_export.h"
0012 
0013 #include <QMap>
0014 #include <QStringList>
0015 
0016 class DictQuery;
0017 class DictionaryPreferenceDialog;
0018 class Entry;
0019 class EntryList;
0020 class KConfig;
0021 class KConfigSkeleton;
0022 class QWidget;
0023 
0024 /**
0025  * @short Abstract base class, used internally by the library for handling different types of dictionaries
0026  * This is a virtual class that enforces the interface between the DictionaryManager
0027  * class and the DictionaryManager.handler files. IMPLEMENT in combination with an
0028  * Entry subclass (if needed) to add a new dictionary format. Also see the addDictionary
0029  * method in the DictionaryManager class.
0030  *
0031  * This documentation is mostly for those who are adding a new type of dictionary to
0032  * kiten. This class is not exported outside of the library. */
0033 class /* NO_EXPORT */ DictFile
0034 {
0035 private:
0036     /**
0037      * You are not allowed to create a dictFile subclass without specifying the type-name
0038      */
0039     DictFile() = default;
0040 
0041 public:
0042     /**
0043      * Use this constructor for your subclasses. Dictionary subclasses MUST specify their type
0044      * at creation.
0045      */
0046     explicit DictFile(const QString &dictionaryTypeName)
0047         : m_dictionaryType(dictionaryTypeName)
0048     {
0049     }
0050     /**
0051      * Destructor
0052      */
0053     virtual ~DictFile() = default;
0054     /**
0055      * This method allows the user to test if a dictionary is the proper type for this format.
0056      * This process is allowed to take some time, but nonetheless you should find checking the format
0057      * of a few hundred entries sufficient for this.
0058      *
0059      * @param filename the name of the file, suitable for using with QFile::setFileName() */
0060     virtual bool validDictionaryFile(const QString &filename) = 0;
0061     /**
0062      * Is this query relevant to this dictionary type? Usually this will return true,
0063      * unless the query specifies extended attributes that the dictionary does not provide.
0064      *
0065      * @param query the query to examine for relevance to this dictionary type */
0066     virtual bool validQuery(const DictQuery &query) = 0;
0067     /**
0068      * This actually conducts the search on the given query. This is usually most of the work
0069      *
0070      * @param query the DictQuery that specifies what results to return
0071      */
0072     virtual EntryList *doSearch(const DictQuery &query) = 0;
0073     /**
0074      * Load a dictionary as at system startup.
0075      *
0076      * @param file the file to open, in a format suitable for use with QFile::setFileName()
0077      * @param name the name of the file to open, used in various user-interface aspects.
0078      *             It may be related to the file parameter, but perhaps not.
0079      */
0080     virtual bool loadDictionary(const QString &file, const QString &name) = 0;
0081     /**
0082      * Load a new dictionary. This is called with the assumption that this dictionary
0083      * has not been opened previously, in case you need to build an index or other activity.
0084      * If you do not re-implement this method, it simply calls loadDictionary().
0085      *
0086      * @param file the file to open, in a format suitable for use with QFile::setFileName()
0087      * @param name the name of the file to open, used in various user-interface aspects.
0088      *             It may be related to the file parameter, but perhaps not.
0089      */
0090     virtual bool loadNewDictionary(const QString &file, const QString &name)
0091     {
0092         return loadDictionary(file, name);
0093     }
0094     /**
0095      * Return a list of the fields that can be displayed, note the following
0096      * should probably always be returned: --NewLine--, Word/Kanji, Meaning,
0097      * Reading.  This function is passed a list originally containing those
0098      * four items. This function is used to enumerate possible types the user
0099      * chooses to have displayed in the preferences dialog box.
0100      * This will often be a very similar list to getSearchableAttributes(),
0101      * but due to optional forms of spelling and other situations, it may
0102      * not be exactly the same. Note: The "Dictionary" option will be
0103      * appended to your list at the end.
0104      */
0105     virtual QStringList listDictDisplayOptions(QStringList) const = 0;
0106     /**
0107      * If you want your own dialog to pick preferences for your dict, then override this.
0108      * Leaving it blank will leave your dictionary type without a preferences dialog.
0109      *
0110      * @param config the KConfigSkeleton object that is currently in use
0111      * @param parent the parent widget for your preferences dialog
0112      */
0113     virtual DictionaryPreferenceDialog *preferencesWidget(KConfigSkeleton *config, QWidget *parent = nullptr)
0114     {
0115         Q_UNUSED(parent)
0116         Q_UNUSED(config)
0117         return nullptr;
0118     }
0119     /**
0120      * Load information from the KConfigSkeleton that you've setup in
0121      * the above preferences widget.
0122      */
0123     virtual void loadSettings(KConfigSkeleton *)
0124     {
0125     }
0126 
0127     /**
0128      * Returns the name of the dictionary
0129      */
0130     virtual QString getName() const
0131     {
0132         return m_dictionaryName;
0133     }
0134     /**
0135      * Returns the type of files this dictFile object deals with
0136      */
0137     virtual QString getType() const
0138     {
0139         return m_dictionaryType;
0140     }
0141     /**
0142      * Returns the file that this is working with, usually used in the preferences display
0143      */
0144     virtual QString getFile() const
0145     {
0146         return m_dictionaryFile;
0147     }
0148     /**
0149      * Fetch a list of searchable attributes and their codes
0150      */
0151     virtual const QMap<QString, QString> &getSearchableAttributes() const
0152     {
0153         return m_searchableAttributes;
0154     }
0155 
0156 protected:
0157     /**
0158      * Name is the 'primary key' of the list of dictionaries. You will want to
0159      * place this into your Entry objects to identify where they came from
0160      * (fairly important)
0161      */
0162     QString m_dictionaryName;
0163 
0164     /**
0165      * This is mostly a placeholder, but your class will get asked what file
0166      * it is using, so either be sure to put something here, or override
0167      * getFile() and respond with something that will be sensical in a
0168      * dictionary selection dialog box.
0169      */
0170     QString m_dictionaryFile;
0171 
0172     /**
0173      * This MUST BE SET IN THE CONSTRUCTOR. The dictionary class occasionally
0174      * uses this value and it's important for it to be set at anytime after the
0175      * constructor is called. It also must be unique to the dictionary type. If
0176      * relevant, specify dictionary versions here.
0177      */
0178     QString m_dictionaryType;
0179     /**
0180      * This allows the programming user to see a list
0181      * of possible search types (probably through a drop down menu).
0182      * You may also find it useful in your dictFile implementation
0183      * to translate from extended attribute keys into the simpler one or two letter
0184      * code keys. These should take the format of:
0185      * (Kanji Grade => G), (Strokes => S), (Heisig Number => H)
0186      * for a simple example appropriate to kanji.
0187      */
0188     QMap<QString, QString> m_searchableAttributes;
0189 };
0190 
0191 #endif