File indexing completed on 2024-12-01 06:33:14

0001 /*
0002     This file is part of Kiten, a KDE Japanese Reference Tool
0003     SPDX-FileCopyrightText: 2006 Joseph Kerian <jkerian@gmail.com>
0004     SPDX-FileCopyrightText: 2011 Daniel E. Moctezuma <democtezuma@gmail.com>
0005 
0006     SPDX-License-Identifier: LGPL-2.0-or-later
0007 */
0008 
0009 #ifndef KITEN_DICTIONARYMANAGER_H
0010 #define KITEN_DICTIONARYMANAGER_H
0011 
0012 #include "kiten_export.h"
0013 
0014 #include <QMap>
0015 #include <QPair>
0016 #include <QStringList>
0017 
0018 class DictFile;
0019 class DictQuery;
0020 class DictionaryPreferenceDialog;
0021 class EntryList;
0022 class KConfig;
0023 class KConfigSkeleton;
0024 class QWidget;
0025 
0026 /**
0027  * @short The DictionaryManager class is the fundamental dictionary management class.
0028  * All interfaces with the rest of the programs using the various dictionaries will
0029  * work through this "interface class" to keep the formatting and other such
0030  * nasty details away from programs and sections which just want to use the
0031  * dictionary without bothering with the internal formatting details. As a
0032  * general rule, call this class with a DictQuery to get a list of
0033  * entries as the result.
0034  *
0035  * The idea is that the interfaces need to know how to load a query, pass the
0036  * query to dictionary. DictionaryManager will return to them an EntryList object,
0037  * each Entry knows how to display itself (via the magic of C++ polymorphism).
0038  * There are some setup and preference handling methods which complicate
0039  * things, but generally speaking this is the way this should work.
0040  *
0041  * @author Joseph Kerian <jkerian@gmail.com>
0042  */
0043 
0044 class KITEN_EXPORT DictionaryManager
0045 {
0046 public:
0047     /**
0048      * Basic constructor
0049      */
0050     DictionaryManager();
0051     /**
0052      * Basic destructor
0053      */
0054     virtual ~DictionaryManager();
0055 
0056     /**
0057      * Open a specified dictionary, and load it under this manager's control
0058      *
0059      * @param file the filename, suitable for using with QFile::setFileName()
0060      * @param name the name of the file, which may be related to file, but perhaps not,
0061      *             for all future dealings with this file, this name will be the key value
0062      * @param type the known dictionary type of this file
0063      */
0064     bool addDictionary(const QString &file, const QString &name, const QString &type);
0065     /**
0066      * Removes all previously loaded dictionaries (if any).
0067      */
0068     void removeAllDictionaries();
0069     /**
0070      * Close a dictionary by name
0071      *
0072      * @param name the name of the dictionary file, as given in addDictionary
0073      */
0074     bool removeDictionary(const QString &name);
0075     /**
0076      * List names of each open dictionary
0077      */
0078     QStringList listDictionaries() const;
0079     /**
0080      * Returns type and file for an open dictionary of a given
0081      *
0082      * @param name the name of the dictionary whose information we are looking for
0083      */
0084     QPair<QString, QString> listDictionaryInfo(const QString &name) const;
0085     /**
0086      * Lists all dictionaries of a given type (Convenient for preference dialogs)
0087      *
0088      * @param type the type of dictionaries to list
0089      */
0090     QStringList listDictionariesOfType(const QString &type) const;
0091     /**
0092      * This is the main search routine that most of kiten should use
0093      *
0094      * @param query the DictQuery object describing the search to conduct
0095      */
0096     EntryList *doSearch(const DictQuery &query) const;
0097     /**
0098      * A simple method for searching inside of a given set of results
0099      *
0100      * @param query the new query that will pare down our results list, there is no requirement that
0101      *              this query includes the query that generated the EntryList, the results are calculated
0102      *              only out of the second parameter
0103      * @param list the list of results to search for the above query in
0104      */
0105     EntryList *doSearchInList(const DictQuery &query, const EntryList *list) const;
0106     /**
0107      * Get a list of all supported dictionary types. Useful for preference code
0108      */
0109     static QStringList listDictFileTypes();
0110     /**
0111      * Given a config and parent widget, return a mapping from dictionary types to preference dialogs.
0112      * If a particular dictionary type does not provide a preference dialog, it will not be included in this list,
0113      * so occasionally keys(returnvalue) != listDictFileTypes()
0114      *
0115      * @param config the config skeleton
0116      * @param parent the parent widget, as per the normal Qt widget system
0117      */
0118     static QMap<QString, DictionaryPreferenceDialog *> generatePreferenceDialogs(KConfigSkeleton *config, QWidget *parent = nullptr);
0119     /**
0120      * Compiles a list of all fields beyond the basic three (word/pronunciation/meaning) that all dictionary
0121      * types support. This can be used to generate a preference dialog, or provide more direct references.
0122      * The return value is "full name of the field" => "abbreviation usable in search string"
0123      */
0124     static QMap<QString, QString> generateExtendedFieldsList();
0125     /**
0126      * Trigger loading preferences from a given KConfigSkeleton config object for a dictionary of type dict
0127      *
0128      * @param dict the dictionary type to load settings for
0129      * @param config the config skeleton object */
0130     void loadDictSettings(const QString &dict, KConfigSkeleton *config);
0131     /**
0132      * Load general settings
0133      */
0134     void loadSettings(const KConfig &config);
0135 
0136 private:
0137     /**
0138      * Static method, used to create the polymorphic dictFile object. Do not use externally.
0139      * If you are adding a new dictionary type, see the instructions in the code.
0140      */
0141     static DictFile *makeDictFile(const QString &type);
0142     class Private;
0143     Private *const d;
0144 };
0145 
0146 #endif