File indexing completed on 2024-04-14 05:37:05

0001 /***************************************************************************
0002  *   Copyright (C) 2003-2006 David Saxton <david@bluehaze.org>             *
0003  *                                                                         *
0004  *   This program is free software; you can redistribute it and/or modify  *
0005  *   it under the terms of the GNU General Public License as published by  *
0006  *   the Free Software Foundation; either version 2 of the License, or     *
0007  *   (at your option) any later version.                                   *
0008  ***************************************************************************/
0009 
0010 #ifndef ITEMLIBRARY_H
0011 #define ITEMLIBRARY_H
0012 
0013 #include <KLocalizedString>
0014 
0015 #include <QColor>
0016 #include <QMap>
0017 #include <QObject>
0018 
0019 class Component;
0020 class Document;
0021 class Item;
0022 class ItemDocument;
0023 class ItemLibrary;
0024 class LibraryItem;
0025 inline ItemLibrary *itemLibrary();
0026 
0027 typedef QMap<QString, QString> QStringMap;
0028 typedef QMap<QString, QStringMap> QStringMapMap;
0029 typedef QMap<QString, QImage> ImageMap;
0030 typedef QList<LibraryItem *> LibraryItemList;
0031 
0032 /**
0033 While the program is running, only one instance of this class is created.
0034 You can get it by calling itemLibrary()
0035 @short Holds the list of CNItems
0036 @author David Saxton
0037 */
0038 class ItemLibrary : public QObject
0039 {
0040     Q_OBJECT
0041 public:
0042     ~ItemLibrary() override;
0043     /**
0044      * Append the given item into the library
0045      */
0046     void addLibraryItem(LibraryItem *item);
0047     /**
0048      * Returns a list of items in the library
0049      */
0050     LibraryItemList *items()
0051     {
0052         return &m_items;
0053     }
0054     /**
0055      * @return the LibraryItem for the item with the given type (id) const.
0056      */
0057     LibraryItem *libraryItem(QString type) const;
0058     /**
0059      * Creates a new item with the given id, and returns a pointer to it
0060      */
0061     Item *createItem(const QString &id, ItemDocument *itemDocument, bool newItem, const char *newId = nullptr, bool finishCreation = true);
0062     /**
0063      * Returns an image of the given component. As QPixmap::toImage is
0064      * a slow function, this will cache the result and return that for large
0065      * images.
0066      * @param component A pointer to the Component.
0067      * @param maxSize The maximum size (in pixels) before the image is
0068      * cached.
0069      */
0070     QImage componentImage(Component *component, const uint maxSize = 36000);
0071     /**
0072      * Does similar to that above, but will not be able to return a description
0073      * if there is none saved on file (instead of the above, which falls back to
0074      * calling item->description()).
0075      * @param type the id of the item.
0076      * @param language the language code, e.g. "es".
0077      */
0078     QString description(QString type, const QString &language) const;
0079     /**
0080      * @return if we have a description for the item in language.
0081      */
0082     bool haveDescription(QString type, const QString &language) const;
0083     /**
0084      * Gives the type item the description.
0085      * @param type the type of item this description is for.
0086      * @param language the language code, e.g. "es".
0087      * @return whether the descriptions file could be saved.
0088      */
0089     bool setDescription(QString type, const QString &description, const QString &language);
0090     /**
0091      * @return the directory containing the item descriptions. By default,
0092      * this is something like "/usr/share/apps/ktechlab/contexthelp/". But
0093      * can be changed by calling setDescriptionsDirectory.
0094      */
0095     QString itemDescriptionsDirectory() const;
0096     /**
0097      * Stores the item descriptions directory in the users config.
0098      */
0099     void setItemDescriptionsDirectory(QString dir);
0100     /**
0101      * @return the item description file for the given language.
0102      */
0103     QString itemDescriptionsFile(const QString &language) const;
0104     /**
0105      * @return the string used for an empty item description - something like
0106      * "The help for English does not yet exist..". This is created by inserting
0107      * the current language name into m_emptyItemDescription;
0108      */
0109     QString emptyItemDescription(const QString &language) const;
0110     /**
0111      * @return the list of language-codes that have item descriptions.
0112      */
0113     QStringList descriptionLanguages() const
0114     {
0115         return m_itemDescriptions.keys();
0116     }
0117 
0118 protected:
0119     /**
0120      * Saves the item descriptions to the file specified in the config.
0121      * @return whether successful (e.g. if the file could be opened for
0122      * writing).
0123      */
0124     bool saveDescriptions(const QString &language);
0125     void loadItemDescriptions();
0126     void addComponents();
0127     void addFlowParts();
0128     void addMechanics();
0129     void addDrawParts();
0130 
0131     ItemLibrary();
0132 
0133     LibraryItemList m_items;
0134     ImageMap m_imageMap;
0135     QStringMapMap m_itemDescriptions;               // (Language, type) <--> description
0136     static KLocalizedString m_emptyItemDescription; // Description template for when a description does not yet exist
0137 
0138     friend ItemLibrary *itemLibrary();
0139 };
0140 
0141 inline ItemLibrary *itemLibrary()
0142 {
0143     // are we really sure we aren't calling new over and over again?
0144     static ItemLibrary *_itemLibrary = new ItemLibrary();
0145     return _itemLibrary;
0146 }
0147 
0148 #endif