tdemultimedia/juk/tagtransactionmanager.h

/***************************************************************************
    begin                : Wed Sep 22 2004
    copyright            : (C) 2004 by Michael Pyne
    email                : michael.pyne@kdemail.net
***************************************************************************/

/***************************************************************************
 *                                                                         *
 *   This program is free software; you can redistribute it and/or modify  *
 *   it under the terms of the GNU General Public License as published by  *
 *   the Free Software Foundation; either version 2 of the License, or     *
 *   (at your option) any later version.                                   *
 *                                                                         *
 ***************************************************************************/

#ifndef _TAGTRANSACTIONMANAGER_H
#define _TAGTRANSACTIONMANAGER_H



class PlaylistItem;
class TQWidget;
class Tag;

/**
 * Class to encapsulate a change to the tag, and optionally the file name, of
 * a PlaylistItem.
 *
 * @author Michael Pyne <michael.pyne@kdemail.net>
 * @see TagTransactionManager
 */
class TagTransactionAtom
{
    public:
    /**
     * Default constructor, for use by TQValueList.
     */
    TagTransactionAtom();

    /**
     * Copy constructor.  This takes ownership of the m_tag pointer, so the
     * object being copied no longer has access to the tag.  This function also
     * exists mainly for TQValueList's benefit.
     *
     * @param other The TagTransactionAtom to copy.
     */
    TagTransactionAtom(const TagTransactionAtom &other);

    /**
     * Creates an atom detailing a change made by \p tag to \p item.
     *
     * @param tag Contains the new tag to apply to item.
     * @param item The PlaylistItem to change.
     */
    TagTransactionAtom(PlaylistItem *item, Tag *tag);

    /**
     * Destroys the atom.  This function deletes the tag, so make sure you've
     * already copied out any data you need.  The PlaylistItem is unaffected.
     */
    ~TagTransactionAtom();

    /**
     * Assignment operator.  This operator takes ownership of the m_tag pointer,
     * so the object being assigned from no longer has access to the tag.  This
     * function exists mainly for the benefit of TQValueList.
     *
     * @param other The TagTransactionAtom to copy from.
     * @return The TagTransactionAtom being assigned to.
     */
    TagTransactionAtom &operator=(const TagTransactionAtom &other);

    /**
     * Accessor function to retrieve the PlaylistItem.
     *
     * @return The PlaylistItem being changed.
     */
    PlaylistItem *item() const { return m_item; }

    /**
     * Accessor function to retrieve the changed Tag.
     *
     * @return The Tag containing the changes to apply to item().
     */
    Tag *tag() const { return m_tag; }

    private:
    PlaylistItem *m_item;
    mutable Tag *m_tag;
};

typedef TQValueList<TagTransactionAtom> TagAlterationList;

/**
 * This class manages alterations of a group of PlaylistItem's FileHandles.  What this
 * means in practice is that you will use this class to change the tags and/or
 * filename of a PlaylistItem.
 *
 * This class supports a limited transactional interface.  Once you commit a
 * group of changes, you can call the undo() method to revert back to the way
 * things were (except possibly for file renames).  You can call forget() to
 * forget a series of changes as well.
 *
 * @author Michael Pyne <michael.pyne@kdemail.net>
 */
class TagTransactionManager : public TQObject
{
    Q_OBJECT
  

    public:
    /**
     * Constructs a TagTransactionManager, owned by @p parent.
     *
     * @param parent The parent TQWidget.
     */
    TagTransactionManager(TQWidget *parent = 0);

    /**
     * Returns the global TagTransactionManager instance.
     *
     * @return The global TagTransactionManager.
     */
    static TagTransactionManager *instance();

    /**
     * Adds a change to the list of changes to apply.  Internally this
     * function extracts the CollectionListItem of @p item, and uses that
     * instead, so there is no need to do so yourself.
     *
     * @param item The PlaylistItem to change.
     * @param newTag The Tag containing the changed data.
     */
    void changeTagOnItem(PlaylistItem *item, Tag *newTag);

    /**
     * Convienience function to duplicate a Tag object, since the Tag
     * object doesn't have a decent copy constructor.
     *
     * @param tag The Tag to duplicate.
     * @param fileName The filename to assign to the tag.  If TQString()
     *        (the default) is passed, the filename of the existing tag is
     *        used.
     * @bug Tag should have a correct copy ctor and assignment operator.
     * @return The duplicate Tag.
     */
    static Tag *duplicateTag(const Tag *tag, const TQString &fileName = TQString());

    /**
     * Commits the changes to the PlaylistItems.  It is important that the
     * PlaylistItems still exist when you call this function, although this
     * shouldn't be a problem in practice.  After altering the tags, and
     * renaming the files if necessary, you can call undo() to back out the
     * changes.
     *
     * If any errors have occurred, the user will be notified with a dialog
     * box, and those files which were unabled to be altered will be excluded
     * from the undo set.
     *
     * @return true if no errors occurred, false otherwise.
     */
    bool commit();

    /**
     * Clears the current update list.  The current undo list is unaffected.
     */
    void forget();

    /**
     * Undoes the changes caused by commit().  Like commit(), if any errors
     * occur changing the state back (for example, it may be impossible to
     * rename a file back to its original name), the user will be shown notified
     * via a dialog box.
     *
     * After performing the undo operation, it is impossible to call undo()
     * again on the same set of files.  Namely, you can't repeatedly call
     * undo() to switch between two different file states.
     *
     * @return true if no errors occurred, false otherwise.
     */
    bool undo();

    signals:
    void signalAboutToModifyTags();
    void signalDoneModifyingTags();

    private:
    /**
     * Renames the file identified by @p from to have the name given by @p to,
     * prompting the user to confirm if necessary.
     *
     * @param from TQFileInfo with the filename of the original file.
     * @param to TQFileInfo with the new filename.
     * @return true if no errors occurred, false otherwise.
     */
    bool renameFile(const TQFileInfo &from, const TQFileInfo &to) const;

    /**
     * Used internally by commit() and undo().  Performs the work of updating
     * the PlaylistItems and then updating the various GUI elements that need
     * to be updated.
     *
     * @param undo true if operating in undo mode, false otherwise.
     */
    bool processChangeList(bool undo = false);

    TagAlterationList m_list; ///< holds a list of changes to commit
    TagAlterationList m_undoList; ///< holds a list of changes to undo
    static TagTransactionManager *m_manager; ///< used by instance()
};

#endif /* _TAGTRANSACTIONMANAGER_H */