/** \ingroup core
 *  \class QgsComposerMapItem
 *  \brief An item which is drawn inside a QgsComposerMap, e.g., a grid or map overview.
 */
class QgsComposerMapItem : QgsComposerObject
{
%TypeHeaderCode
#include <qgscomposermapitem.h>
%End

  public:

    /** Constructor for QgsComposerMapItem.
     * @param name friendly display name for item
     * @param map QgsComposerMap the item is attached to
     */
    QgsComposerMapItem( const QString &name, QgsComposerMap *map );

    virtual ~QgsComposerMapItem();

    /** Draws the item on to a painter
     * @param painter destination QPainter
     */
    virtual void draw( QPainter *painter ) = 0;

    /** Stores map item state in DOM element
     * @param elem is DOM element corresponding to a 'ComposerMap' tag
     * @param doc DOM document
     * @see readXML
     */
    virtual bool writeXml( QDomElement &elem, QDomDocument &doc ) const;

    /** Sets map item state from a DOM document
     * @param itemElem is DOM node corresponding to a 'ComposerMapGrid' tag
     * @param doc is DOM document
     * @see writeXML
     */
    virtual bool readXml( const QDomElement &itemElem, const QDomDocument &doc );

    /** Sets composer map for the item
     * @param map composer map
     * @see composerMap
     */
    virtual void setComposerMap( QgsComposerMap *map );

    /** Get composer map for the item
     * @returns composer map
     * @see setComposerMap
     */
    virtual const QgsComposerMap *composerMap() const;

    /** Get the unique id for the map item
     * @returns unique id
     */
    QString id() const;

    /** Sets the friendly display name for the item
     * @param name display name
     * @see name
     */
    virtual void setName( const QString &name );

    /** Get friendly display name for the item
     * @returns display name
     * @see setName
     */
    virtual QString name() const;

    /** Controls whether the item will be drawn
     * @param enabled set to true to enable drawing of the item
     * @see enabled
     */
    virtual void setEnabled( const bool enabled );

    /** Returns whether the item will be drawn
     * @returns true if item will be drawn on the map
     * @see setEnabled
     */
    virtual bool enabled() const;

    /** Returns true if the item is drawn using advanced effects, such as blend modes.
     * @returns true if item uses advanced effects
     */
    virtual bool usesAdvancedEffects() const;

};



/** \ingroup core
 * \class QgsComposerMapItemStack
 * \brief A collection of map items which are drawn above the map content in a
 * QgsComposerMap. The item stack controls which items are drawn and the
 * order they are drawn in.
 * \note added in QGIS 2.5
 * \see QgsComposerMapItem
 */
class QgsComposerMapItemStack
{
%TypeHeaderCode
#include <qgscomposermapitem.h>
%End

  public:

    /** Constructor for QgsComposerMapItemStack.
     * @param map QgsComposerMap the item stack is attached to
     */
    QgsComposerMapItemStack( QgsComposerMap *map );

    virtual ~QgsComposerMapItemStack();

    /** Returns the number of items in the stack
     * @returns number of items in the stack
     */
    int size() const;

    /** Stores the state of the item stack in a DOM node
     * @param elem is DOM element corresponding to a 'ComposerMap' tag
     * @param doc DOM document
     * @returns true if write was successful
     * @see readXML
     */
    virtual bool writeXml( QDomElement &elem, QDomDocument &doc ) const;

    /** Sets the item stack's state from a DOM document
     * @param elem is DOM node corresponding to 'a ComposerMap' tag
     * @param doc DOM document
     * @returns true if read was successful
     * @see writeXML
     */
    virtual bool readXml( const QDomElement &elem, const QDomDocument &doc ) = 0;

    /** Draws the items from the stack on a specified painter
     * @param painter destination QPainter
     */
    void drawItems( QPainter *painter );

    /** Returns whether any items within the stack contain advanced effects,
     * such as blending modes
     * @returns true if item stack contains advanced effects
     */
    bool containsAdvancedEffects() const;

  protected:

    /** Adds a new map item to the stack and takes ownership of the item.
     * The item will be added to the end of the stack, and rendered
     * above any existing map items already present in the stack.
     * @param item QgsComposerMapItem to add to the stack
     * @note after adding an item to the stack update()
     * should be called for the QgsComposerMap to prevent rendering artifacts
     * @see removeItem
     */
    void addItem( QgsComposerMapItem *item /Transfer/);

    /** Removes an item from the stack and deletes the corresponding QgsComposerMapItem
     * @param itemId id for the QgsComposerMapItem to remove
     * @note after removing an item from the stack, update()
     * should be called for the QgsComposerMap to prevent rendering artifacts
     * @see addItem
     */
    void removeItem( const QString &itemId );

    /** Moves an item up the stack, causing it to be rendered above other items
     * @param itemId id for the QgsComposerMapItem to move up
     * @note after moving an item within the stack, update() should be
     * called for the QgsComposerMap to redraw the map with the new item stack order
     * @see moveItemDown
     */
    void moveItemUp( const QString &itemId );

    /** Moves an item up the stack, causing it to be rendered above other items
     * @param itemId id for the QgsComposerMapItem to move down
     * @note after moving an item within the stack, update() should be
     * called for the QgsComposerMap to redraw the map with the new item stack order
     * @see moveItemUp
     */
    void moveItemDown( const QString &itemId );

    /** Returns a const reference to an item within the stack
     * @param itemId id for the QgsComposerMapItem to find
     * @returns const reference to item, if found
     * @see item
     */
    const QgsComposerMapItem *constItem( const QString &itemId ) const;

    /** Returns a reference to an item within the stack
     * @param itemId id for the QgsComposerMapItem to find
     * @returns reference to item if found
     * @see constItem
     */
    QgsComposerMapItem *item( const QString &itemId ) const;

    /** Returns a reference to an item within the stack
     * @param index item position in the stack
     * @returns reference to item if found
     * @see constItem
     */
    QgsComposerMapItem *item( const int index ) const;

    /** Returns a reference to an item within the stack
     * @param idx item position in the stack
     * @returns reference to item if found
     * @see constItem
     * @see item
     * @note not available in python bindings
     */
    // QgsComposerMapItem &operator[]( int idx );

    /** Returns a list of QgsComposerMapItems contained by the stack
     * @returns list of items
     */
    QList< QgsComposerMapItem* > asList() const;

  protected:

    /** Clears the item stack and deletes all QgsComposerMapItems contained
     * by the stack
     */
    void removeItems();
};