src/projectM-iTunes-VizKit/source/VisualNotification.h

/*
 * Project: VizKit
 * Version: 2.3
 
 * Date: 20090823
 * File: VisualNotification.h
 *
 */

/***************************************************************************

Copyright (c) 2004-2009 Heiko Wichmann (http://www.imagomat.de/vizkit)


This software is provided 'as-is', without any expressed or implied warranty. 
In no event will the authors be held liable for any damages
arising from the use of this software.

Permission is granted to anyone to use this software for any purpose,
including commercial applications, and to alter it and redistribute it
freely, subject to the following restrictions:

1. The origin of this software must not be misrepresented; 
   you must not claim that you wrote the original software. 
   If you use this software in a product, an acknowledgment 
   in the product documentation would be appreciated 
   but is not required.

2. Altered source versions must be plainly marked as such, 
   and must not be misrepresented as being the original software.

3. This notice may not be removed or altered from any source distribution.

 ***************************************************************************/

#ifndef VisualNotification_h
#define VisualNotification_h


#include "VisualTypes.h"
#include "VisualNotificationKey.h"
#include "VisualObject.h"


namespace VizKit {

	class VisualItemIdentifier; // Forward declaration (to avoid include of header file).
	class VisualActor; // Forward declaration (to avoid include of header file).

	/**
	 * A VisualActor is notified about events and messages with a VisualNotification. 
	 * The VisualActor can query the VisualNotification for details.
	 * The VisualActor can also set a value to pass it back to the caller.
	 */
	class VisualNotification : public VisualObject {

	public:

		/**
		 * The constructor.
		 */
		VisualNotification();

		/**
		 * Another constructor.
		 * @param anIdentifier Identifier of the notification.
		 */
		VisualNotification(const VisualItemIdentifier& anIdentifier);

		/**
		 * The destructor.
		 */
		~VisualNotification();

		/**
		 * Copy constructor.
		 */		
		VisualNotification(const VisualNotification& other);

		/**
		 * Assignment operator.
		 */			
		VisualNotification& operator=(const VisualNotification& other);

		/**
		 * Copies the current VisualNotification and returns a pointer to a new VisualNotification.
		 */
		virtual VisualNotification* clone(void) const;

		/**
		 * Sets the key of a notification. Notification keys are implemented as enums.
		 * @param aKey The enum key.
		 */
		void setKey(const VisualNotificationKey aKey);

		/**
		 * Returns the key of the notification.
		 * @return The key of the notification. Notification keys are implemented as enums.
		 */
		VisualNotificationKey getKey(void) const;

		/**
		 * Sets the value of a notification.
		 * @param someData The pointer to the memory location of the data.
		 * @param dataSizeInBytes The size of the data in bytes.
		 * @remarks The data (not only the pointer) is copied.
		 */
		void setData(const void* const someData, uint32 dataSizeInBytes);

		/**
		 * Returns the untyped data of the notification.
		 * @param[out] dataSizeInBytes The number of bytes the data occupies in memory.
		 * @return The pointer to the memory location of the data.
		 * @remarks To hold the data, the caller has to create and store a copy on his side.
		 */
		void* getData(uint32& dataSizeInBytes) const;

		/**
		 * Sets the object of a notification.
		 * @param anObject The pointer to an object.
		 * @remarks The object is copied by calling clone().
		 */
		void setObject(const VisualObject& anObject);

		/**
		 * Returns a pointer to the object of the notification.
		 * @return A pointer to the object of the notification.
		 * @remarks The object does not get copied automatically. If the caller wants to retain a copy, the data has to be copied by calling its object member function clone().
		 */
		VisualObject* getObject(void) const;

		/**
		 * Sets a pointer to some memory address.
		 * @param pointer A pointer to some memory address.
		 * @remarks If possible, copying the data is preferred (by calling setData()).
		 */
		void setPointer(void* pointer);

		/**
		 * Returns a pointer to some memory address.
		 * @return A pointer to some memory address.
		 * @remarks If possible, copying the data is preferred (by using setData() / getData()).
		 */
		void* getPointer(void);

		/**
		 * The notification is posted to the VisualNotificationQueue (pushed at the end of the VisualNotificationQueue).
		 */
		void post(void);

		/**
		 * Static helper function that converts a VisualNotificationKey to the string. Possibly useful for debugging or tracing purposes.
		 * @param aKey The key of a notification.
		 * @param outString The character string value of the VisualNotificationKey enum value.
		 */
		static void convertNotificationKeyToString(const VisualNotificationKey aKey, char* outString);

		/**
		 * Static function for convenient posting of simple enum value of VisualNotificationKey.
		 * @param aKey The notification key to post.
		 * @remarks The notification is pushed at the end of the VisualNotificationQueue.
		 */
		static void post(const VisualNotificationKey aKey);
		
		/**
		 * A VisualActor can register for an event/message. The notification is passed with VisualActor::handleNotification().
		 * @param aVisualActor A visual actor.
		 * @param aNotificationKey An enum that denotes a notification.
		 */
		static void registerNotification(VisualActor* aVisualActor, const VisualNotificationKey aNotificationKey);
		
		/**
		 * A VisualActor can be removed from the list of observers for a specific notification.
		 * @param aVisualActor A visual actor.
		 * @param aNotificationKey An enum that denotes a notification.
		 */
		static void removeNotification(VisualActor* aVisualActor, const VisualNotificationKey aNotificationKey);
		
	private:
	
		/**
		 * Copy method for assignment operator and copy constructor.
		 * @param other Another VisualNotification.
		 */
		void copy(const VisualNotification& other);
		
		/** Enum value of notification as uint16. */
		VisualNotificationKey notificationEnumKey;
		
		/** Optional data of notification. */
		void* notificationData;
		
		/** The length of the optional data in bytes. */
		uint32 notificationDataSize;
		
		/** Optional object of the notification. */
		VisualObject* notificationObject;
		
		/** Internally stored pointer to some memory address. */
		void* notificationPointer;

	};

}

#endif /* VisualNotification_h */