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