File indexing completed on 2022-11-22 17:50:15

0001 /*
0002     SPDX-FileCopyrightText: 2005, 2006 Carsten Niehaus <cniehaus@kde.org>
0003     SPDX-FileCopyrightText: 2005-2007 Pino Toscano <pino@kde.org>
0004 
0005     SPDX-License-Identifier: GPL-2.0-or-later
0006 */
0007 
0008 #ifndef KDEEDUGLOSSARY_H
0009 #define KDEEDUGLOSSARY_H
0010 
0011 #include <QDialog>
0012 #include <QUrl>
0013 
0014 class QDomDocument;
0015 class GlossaryItem;
0016 
0017 /**
0018  * @class Glossary
0019  * @author Carsten Niehaus
0020  * @author Pino Toscano
0021  *
0022  * This class stores all items to be displayed. It also
0023  * has access-methods to the items
0024  */
0025 class Glossary
0026 {
0027 public:
0028     /**
0029      * Creates a new glossary and add contents from an XML file.
0030      * Use isEmpty() to know if any items were loaded.
0031      *
0032      * @param url the path of the file to load
0033      * @param path the path of the pictures
0034      */
0035     explicit Glossary(const QUrl &url, const QString &path = QString());
0036 
0037     /**
0038      * Creates a new empty glossary
0039      */
0040     Glossary();
0041 
0042     virtual ~Glossary();
0043 
0044     /**
0045      * add the item @p item to the glossary
0046      */
0047     void addItem(GlossaryItem *item);
0048 
0049     QList<GlossaryItem *> itemlist() const;
0050 
0051     /**
0052      * clear the Glossary
0053      */
0054     void clear();
0055 
0056     /**
0057      * does this glossary have items?
0058      */
0059     bool isEmpty() const;
0060 
0061     /**
0062      * Every glossary can have a name. It will be
0063      * set to @p name
0064      */
0065     void setName(const QString &name);
0066 
0067     /**
0068      * @returns the name of the glossary
0069      */
0070     QString name() const;
0071 
0072     /**
0073      * sets the internal list of items to @p list
0074      */
0075     void setItemlist(QList<GlossaryItem *> list);
0076 
0077     /**
0078      * Every glossaryitem can show pictures. [img src="foo.png]
0079      * will look for the file foo.png in the path defined by
0080      * @p path
0081      */
0082     void setPicturePath(const QString &path);
0083 
0084     QString picturePath() const;
0085 
0086     /**
0087      * defines which picture to use as the background
0088      * of the htmlview. The dialog
0089      * will use the file specific by the @p filename
0090      */
0091     void setBackgroundPicture(const QString &filename);
0092 
0093     /**
0094      * @return the picture used as the background in
0095      * this background
0096      */
0097     QString backgroundPicture() const;
0098 
0099 protected:
0100     void init(const QUrl &url, const QString &path);
0101 
0102 private:
0103     /**
0104      * This methods parses the given XML code. It will extract
0105      * the information of the items and return them as a
0106      * QList<GlossaryItem*>
0107      */
0108     virtual QList<GlossaryItem *> readItems(QDomDocument &itemDocument);
0109 
0110     QString m_backgroundpicture;
0111 
0112     /**
0113      * replaces the [img]-pseudocode with valid HTML. The path where
0114      * the pictures are stored will be used for pictures
0115      */
0116     void fixImagePath();
0117 
0118     /**
0119      * the path in which pictures of the glossary will be searched
0120      */
0121     QString m_picturepath;
0122 
0123     /**
0124      * Load the layout from an XML file.
0125      *
0126      * @param doc The QDomDocument which will contain the read XML
0127      *            contents.
0128      * @param url The path of the file to load
0129      *
0130      * @return a bool indicating whether the loading of the XML was
0131      *         successful or not
0132      */
0133     bool loadLayout(QDomDocument &doc, const QUrl &url);
0134 
0135     QList<GlossaryItem *> m_itemlist;
0136 
0137     /**
0138      * the name of the glossary
0139      */
0140     QString m_name;
0141 };
0142 
0143 /**
0144  * @class GlossaryItem
0145  * @author Carsten Niehaus
0146  *
0147  * A GlossaryItem stores the information of the content of
0148  * the item and its name. Furthermore, every item can have
0149  * a number of pictures or references associated to it.
0150  * These are stored as QStringLists.
0151  */
0152 class GlossaryItem
0153 {
0154 public:
0155     GlossaryItem() = default;
0156     ~GlossaryItem() = default;
0157 
0158     void setName(const QString &s);
0159 
0160     void setDesc(const QString &s);
0161 
0162     /**
0163      * Set the references for the current GlossaryItem to
0164      * @p s.
0165      * There's no need to sort the list before, as they
0166      * will be sorted automatically
0167      */
0168     void setRef(const QStringList &s);
0169 
0170     void setPictures(const QString &s);
0171 
0172     QString name() const;
0173 
0174     QString desc() const;
0175 
0176     QStringList ref() const;
0177 
0178     QStringList pictures() const;
0179 
0180     /**
0181      * @return the formatted HTML code for current item.
0182      */
0183     QString toHtml() const;
0184 
0185     /**
0186      * This method parses the references.
0187      * @return the HTML code with the references as HTML links
0188      */
0189     QString parseReferences() const;
0190 
0191 private:
0192     QString m_name;
0193     QString m_desc;
0194     QStringList m_ref;
0195     QStringList m_pic;
0196 };
0197 
0198 /**
0199  * @class GlossaryDialog
0200  * @author Pino Toscano
0201  * @author Carsten Niehaus
0202  */
0203 class GlossaryDialog : public QDialog
0204 {
0205     Q_OBJECT
0206 
0207 public:
0208     /**
0209      * Creates a new dialog for a glossary.
0210      *
0211      * @param parent the parent of the new dialog
0212      */
0213     explicit GlossaryDialog(QWidget *parent = nullptr);
0214 
0215     ~GlossaryDialog() override;
0216 
0217     /**
0218      * Add a new glossary.
0219      *
0220      * @param newgloss the new glossary to add
0221      * @param folded whether to fold the various items in subtrees depending on the
0222      * first letter of every item
0223      */
0224     void addGlossary(Glossary *newgloss, bool folded = true);
0225 
0226 protected:
0227     void keyPressEvent(QKeyEvent *) override;
0228 
0229 private:
0230     class Private;
0231     Private *const d;
0232 
0233     Q_PRIVATE_SLOT(d, void itemActivated(QTreeWidgetItem *, int))
0234 };
0235 
0236 #endif // KDEEDUGLOSSARY_H