1 /* 2 This file is part of Kiten, a KDE Japanese Reference Tool 3 SPDX-FileCopyrightText: 2006 Joseph Kerian <jkerian@gmail.com> 4 5 SPDX-License-Identifier: LGPL-2.0-or-later 6 */ 7 8 #ifndef KITEN_DICTFILE_H 9 #define KITEN_DICTFILE_H 10 11 #include "kiten_export.h" 12 13 #include <QMap> 14 #include <QString> 15 16 class DictQuery; 17 class DictionaryPreferenceDialog; 18 class Entry; 19 class EntryList; 20 class KConfig; 21 class KConfigSkeleton; 22 class QStringList; 23 class QWidget; 24 25 /** 26 * @short Abstract base class, used internally by the library for handling different types of dictionaries 27 * This is a virtual class that enforces the interface between the DictionaryManager 28 * class and the DictionaryManager.handler files. IMPLEMENT in combination with an 29 * Entry subclass (if needed) to add a new dictionary format. Also see the addDictionary 30 * method in the DictionaryManager class. 31 * 32 * This documentation is mostly for those who are adding a new type of dictionary to 33 * kiten. This class is not exported outside of the library. */ 34 class /* NO_EXPORT */ DictFile 35 { 36 private: 37 /** 38 * You are not allowed to create a dictFile subclass without specifying the type-name 39 */ DictFile()40 DictFile() {} 41 public: 42 /** 43 * Use this constructor for your subclasses. Dictionary subclasses MUST specify their type 44 * at creation. 45 */ DictFile(const QString & dictionaryTypeName)46 explicit DictFile( const QString& dictionaryTypeName ) : m_dictionaryType( dictionaryTypeName ) {} 47 /** 48 * Destructor 49 */ ~DictFile()50 virtual ~DictFile() {} 51 /** 52 * This method allows the user to test if a dictionary is the proper type for this format. 53 * This process is allowed to take some time, but nonetheless you should find checking the format 54 * of a few hundred entries sufficient for this. 55 * 56 * @param filename the name of the file, suitable for using with QFile::setFileName() */ 57 virtual bool validDictionaryFile( const QString &filename ) = 0; 58 /** 59 * Is this query relevant to this dictionary type? Usually this will return true, 60 * unless the query specifies extended attributes that the dictionary does not provide. 61 * 62 * @param query the query to examine for relevance to this dictionary type */ 63 virtual bool validQuery( const DictQuery &query ) = 0; 64 /** 65 * This actually conducts the search on the given query. This is usually most of the work 66 * 67 * @param query the DictQuery that specifies what results to return 68 */ 69 virtual EntryList *doSearch( const DictQuery &query ) = 0; 70 /** 71 * Load a dictionary as at system startup. 72 * 73 * @param file the file to open, in a format suitable for use with QFile::setFileName() 74 * @param name the name of the file to open, used in various user-interface aspects. 75 * It may be related to the file parameter, but perhaps not. 76 */ 77 virtual bool loadDictionary( const QString &file, const QString &name ) = 0; 78 /** 79 * Load a new dictionary. This is called with the assumption that this dictionary 80 * has not been opened previously, in case you need to build an index or other activity. 81 * If you do not re-implement this method, it simply calls loadDictionary(). 82 * 83 * @param file the file to open, in a format suitable for use with QFile::setFileName() 84 * @param name the name of the file to open, used in various user-interface aspects. 85 * It may be related to the file parameter, but perhaps not. 86 */ loadNewDictionary(const QString & file,const QString & name)87 virtual bool loadNewDictionary( const QString &file, const QString &name ) 88 { return loadDictionary( file, name ); } 89 /** 90 * Return a list of the fields that can be displayed, note the following 91 * should probably always be returned: --NewLine--, Word/Kanji, Meaning, 92 * Reading. This function is passed a list originally containing those 93 * four items. This function is used to enumerate possible types the user 94 * chooses to have displayed in the preferences dialog box. 95 * This will often be a very similar list to getSearchableAttributes(), 96 * but due to optional forms of spelling and other situations, it may 97 * not be exactly the same. Note: The "Dictionary" option will be 98 * appended to your list at the end. 99 */ 100 virtual QStringList listDictDisplayOptions( QStringList ) const = 0 ; 101 /** 102 * If you want your own dialog to pick preferences for your dict, then override this. 103 * Leaving it blank will leave your dictionary type without a preferences dialog. 104 * 105 * @param config the KConfigSkeleton object that is currently in use 106 * @param parent the parent widget for your preferences dialog 107 */ 108 virtual DictionaryPreferenceDialog *preferencesWidget( KConfigSkeleton *config, QWidget *parent = nullptr ) 109 { Q_UNUSED( parent ); Q_UNUSED( config ); return NULL; } 110 /** 111 * Load information from the KConfigSkeleton that you've setup in 112 * the above preferences widget. 113 */ loadSettings(KConfigSkeleton *)114 virtual void loadSettings( KConfigSkeleton* ) {} 115 116 /** 117 * Returns the name of the dictionary 118 */ getName()119 virtual QString getName() const { return m_dictionaryName; } 120 /** 121 * Returns the type of files this dictFile object deals with 122 */ getType()123 virtual QString getType() const { return m_dictionaryType; } 124 /** 125 * Returns the file that this is working with, usually used in the preferences display 126 */ getFile()127 virtual QString getFile() const { return m_dictionaryFile; } 128 /** 129 * Fetch a list of searchable attributes and their codes 130 */ getSearchableAttributes()131 virtual const QMap<QString,QString> &getSearchableAttributes() const 132 { return m_searchableAttributes; } 133 protected: 134 /** 135 * Name is the 'primary key' of the list of dictionaries. You will want to 136 * place this into your Entry objects to identify where they came from 137 * (fairly important) 138 */ 139 QString m_dictionaryName; 140 141 /** 142 * This is mostly a placeholder, but your class will get asked what file 143 * it is using, so either be sure to put something here, or override 144 * getFile() and respond with something that will be sensical in a 145 * dictionary selection dialog box. 146 */ 147 QString m_dictionaryFile; 148 149 /** 150 * This MUST BE SET IN THE CONSTRUCTOR. The dictionary class occasionally 151 * uses this value and it's important for it to be set at anytime after the 152 * constructor is called. It also must be unique to the dictionary type. If 153 * relevant, specify dictionary versions here. 154 */ 155 QString m_dictionaryType; 156 /** 157 * This allows the programming user to see a list 158 * of possible search types (probably through a drop down menu). 159 * You may also find it useful in your dictFile implementation 160 * to translate from extended attribute keys into the simpler one or two letter 161 * code keys. These should take the format of: 162 * (Kanji Grade => G), (Strokes => S), (Heisig Number => H) 163 * for a simple example appropriate to kanji. 164 */ 165 QMap<QString,QString> m_searchableAttributes; 166 }; 167 168 #endif 169