Initial commit

Lts/Plugins/PlanEditor/symbol_favourites.h

@@ -0,0 +1,240 @@
+/**
+**
+** @RDE_HEADER@
+** Used to store symbol favourites.
+** $Id$
+** $HeadURL$
+** $Author$
+**
+** -----------------------------------------------------------------------------------------------
+**
+** Hardware-Environment: Intel-PC
+** Software-Environment: Windows 7, Qt 5.4. ArcGIS 10.2.5
+**
+** Language ........: C++ 11
+**
+** -----------------------------------------------------------------------------------------------
+**
+** Author ...........: Jörg Turla, SPD G, Tel. 3132
+**
+** -----------------------------------------------------------------------------------------------
+**
+** Notes .........:
+**
+**   25.07.2016, JT  : First edition for use with Qt5
+**
+** -----------------------------------------------------------------------------------------------
+*/
+
+#pragma once
+
+#include <QtCore/QObject>
+#include <QtCore/QString>
+
+#include "logging.h"
+
+
+class QIODevice;
+
+
+namespace PlanEditor
+{
+class PlanEditor;
+
+/**
+  @class SymbolFavourites
+  @brief Manager of symbol favourites for use in context of PlanEditor plugin.
+
+  The class \c SymbolFavourites stores symbol favourites in a single stage hierarchy where by
+  each symbol is assigned to one container, called \b scope here. A symbol  is stored only once
+  in a single scope. A scope is addressed by it's name. This name have to be unique. To address
+  a symbol the sidc symbol code is used, which is unique over all symbols. For use in user
+  interfaces a symbol has also a human readable name.
+*/
+class SymbolFavourites : public QObject
+{
+  Q_OBJECT
+
+public:
+
+  /**
+    @name Construction & Destruction
+    @{
+  */
+  SymbolFavourites();
+  virtual ~SymbolFavourites() = default;
+  /** @} */
+
+
+  /**
+    Returns all symbol codes stores in SymbolFavourites.
+  */
+  virtual QStringList sidcList() const = 0;
+
+  /**
+    Returns all scopes sored in SymbolFavourites
+  */
+  virtual QStringList scopeList() const = 0;
+
+  /**
+    Add new scope to symbol favourites. If the scope already exists the function does nothing.
+  */
+  virtual void addScope(const QString &scope) = 0;
+
+  /**
+    Add symbol to symbol favourites. If there is already a symbol with same sidc symbol code, this symbol
+    will be deleted from symbol favourites first.
+    @param sidc   symbol code
+    @param scope  scope to add the symbol
+    @param name   name of symbol
+  */
+  virtual void addSymbolFavourite(const QString &sidc, const QString &scope, const QString &name) = 0;
+
+  /**
+    Returns true if symbol with sidc symbol code is in symbol favourites.
+    @param sidc symbol code
+  */
+  virtual bool isFavourite(const QString &sidc) const = 0;
+
+
+  /**
+    Returns the scope of a symbol. If the symbol doesn't exist in symbol favourites an empty string is provided.
+    @params sidc symbol code
+  */
+  virtual QString scope(const QString &sidc) const = 0;
+
+  /**
+    Returns the name of a symbol. If the symbol doesn't exist in symbol favourites an empty string is provided.
+    @params sidc symbol code
+  */
+  virtual QString name(const QString &sidc) const = 0;
+
+  /**
+    Removes a symbol from symbol favourites.
+    @params sidc symbol code
+  */
+  virtual void removeSymbolFavourite(const QString &sidc) = 0;
+
+  /**
+    Removes a scope and all corresponding symbols from symbol favourites.
+  */
+  virtual void removeScope(const QString &scope) = 0;
+
+
+  /**
+    Includes another symbol favourite.
+  */
+  virtual void includeSymbolFavourites(const SymbolFavourites &) = 0;
+
+  /**
+    Provides a XML representation as QString.
+  */
+  virtual QString toString() = 0;
+
+  /**
+    Parsing XML representaion to build up symbol favourites.
+  */
+  virtual bool contentFromString(const QString &) = 0;
+
+
+  /**
+    Reades XML representation from device and builds up symbol favourites.
+  */
+  virtual bool contentFromDevice(QIODevice *) = 0;
+
+  /**
+    Copies a scope to another instance of SymbolFavourites
+    @param scope name of scope
+    @param dest  destination instance to copy to
+  */
+  virtual bool copyScope(const QString &scope, SymbolFavourites &dest) = 0;
+
+  /**
+    Creates an empty instance of SymbolFavourites
+  */
+  static SymbolFavourites *create();
+
+  /**
+    Creates an empty instance of SymbolFavourites and calls SymbolFavourites::contentFromString(const QString&).
+    Keep in mind that Qt's signals are not connected at this point of time. In case of using SymbolFavourites
+    signals use contentFromString after installing connections.
+  */
+  static SymbolFavourites *createFromString(const QString &);
+
+  /**
+    Creates an empty instance of SymbolFavourites and calls SymbolFavourites::contentFromString(QIODevice*).
+    Keep in mind that Qt's signals are not connected at this point of time. In case of using SymbolFavourites
+    signals use contentFromDevice after installing connection.
+  */
+  static SymbolFavourites *createFromDevice(QIODevice *);
+
+  /**
+    @class SymbolVisitor
+    @Brief Base class to handle traversing symbol favourites tree structure.
+
+    The element function \c SymbolFavourites::traverse provides a meachnism to travers over the tree structure of
+    symbol favourites. The class \c SymbolVisitor defines the interface to get access to each node
+    this tree (scope or symbol). To implement operations of inherit from \c SymbolVisitor and
+    overload one ore both apply functions.
+  */
+  class SymbolVisitor
+  {
+  public:
+
+    /**
+      @name Construction & Destruction
+      @{
+    */
+    SymbolVisitor()          = default;
+    virtual ~SymbolVisitor() = default;
+    SymbolVisitor(const SymbolVisitor &)                = delete;
+    SymbolVisitor   &operator = (const SymbolVisitor &) = delete;
+    /** @} */
+
+  private:
+
+    /**
+      Friend definition to make SymbolVisitor::apply function accessable in SymbolFavourites::traverse.
+    */
+    friend class VisitorVisitor;
+
+    /**
+      This function will be called for each scope. Overload this function to
+      implement operations of each scope. To continue traversal return true. In
+      case of return value is false the traversal will be aborted.
+      @param scope name of scope
+    */
+    virtual bool apply(const QString &scope) const;
+
+    /**
+      This function will be called for each symbol. Overload this function to
+      implement operations of each symbol. To continue traversal return true. In
+      case of return value is false the traversal will be aborted.
+      @param scope name of scope
+      @param name  name of symbol
+      @param sidc  code of symbol
+    */
+    virtual bool apply(const QString &scope, const QString &name, const QString &sidc) const;
+
+  }; // SymbolVisitor
+
+  /**
+    Traversing the tree structor of symbol favourites to run some operations on each symbol or scope. To implement this
+    inherit from class SymbolVisitor and override the apply functions.
+  */
+  virtual void traverse(const SymbolVisitor &) = 0;
+
+
+signals:
+
+  void signalNewScope(const QString &scope);
+
+  void signalNewSymbol(const QString &scope, const QString &sidc);
+
+  void signalDeleteScope(const QString &scope);
+  void signalDeleteSymbol(const QString &sidc);
+
+}; // SymbolFavourites
+
+
+} // namespace PlanEditor