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