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


		IMFClipboard.h


		Copyright: (c) 2001 Eovia Corp. All rights reserved.


		Author:	Brice
		Date:	9/6/99

		This file contains the declaration of the IMFClipboard interface.

		How to use clipboards interfaces:
		=================================

		From an extension you should have access to the gClipboardUtilities interface.
		This interface will allow you to call Get/Put in order to store or
		retrieve some object from/to the clipboard.

		Clipped objects must inherits from IMFClipping & TBasicUnknown in order to be refcounted properly.

		Data you will store in your clipping could be whatever you want (TMCCountedPtr are welcome), since
		your object is responsible for their destructions.

		Here is a code example:
		=======================

		
		File MyClipping.h
		-----------------

		#include "IMFClipboard.h"
		MCDEFINE_GUID( IID_MyClipping,  <whatever GUID you generated> );

		class cMyClipping : public TBasicUnknown, public IMFClipping
		{
			public:
				static void	Create(cMyClipping** outClipping,IDType	inDataType, void *MyData, uint32 Size);
			protected:
									 cMyClipping(IDType	inDataType, void*	MyData, uint32 Size);
				virtual		~cMyClipping(void);

			public:
				/ * IMCUnknown **************************************************
				virtual		MCCOMErr	MCCOMAPI QueryInterface(const MCIID& riid, void** ppvObj);
				virtual		uint32		MCCOMAPI AddRef();
				STANDARD_RELEASE;

				/ * IMFClipping**************************************************
				virtual		IDType	MCCOMAPI GetType(void) const { return fType; }
				virtual		void*		MCCOMAPI GetData(void) const { return fData; } 
				virtual		uint32	MCCOMAPI GetSize(void) const { return fSize; }
				virtual		IDType	MCCOMAPI GetFlattenedType(void) const { return kMFClipping_Empty; }
				virtual		boolean	MCCOMAPI Flatten(IMFClipping**	outFlatClipping, boolean &outAllocatedMemory,	uint32 inFlags) { return false; }

			private:
				IDType		 fType;
				void			*fData;
				uint32		 fSize;
		};

		File MyClipping.cpp
		-------------------
				
		//  ______________________________________________________________________ 
		// |                                                                     
		// |  Name:  Create()                            
		// |  Class: cMyClipping
		// | 		To create a new cBlobClipping
		// |______________________________________________________________________
		void cMyClipping::Create(cMyClipping** outClipping, IDType	inDataType, void*	inData, uint32 Size)
		{
			TMCCountedCreateHelper<cMyClipping> result(outClipping);
			result = new cBlobClipping(inDataType, inData);
		} // END OF cMyClipping::Create

		//  ______________________________________________________________________ 
		// |                                                                     
		// |  Name:  QueryInterface(const MCIID& riid, void** ppvObj)                            
		// |  Class: cMyClipping
		// | 		return IID_IMFClipping interface
		// |______________________________________________________________________
		MCCOMErr cMyClipping::QueryInterface(const MCIID& riid, void** ppvObj)
		{
			if (MCIsEqualIID(riid, IID_IMFClipping))
			{
				TMCCountedGetHelper<IMFClipping> result(ppvObj);
				result = static_cast<IMFClipping*>(this);
				return MC_S_OK;
			}
			else if (MCIsEqualIID(riid, IID_MyClipping))
			{
				TMCCountedGetHelper<cMyClipping> result(ppvObj);
				result = static_cast<cMyClipping*>(this);
				return MC_S_OK;
			}
			return TBasicUnknown::QueryInterface(riid, ppvObj);
		} // END OF cMyClipping::QueryInterface

		//  ______________________________________________________________________ 
		// |                                                                     
		// |  Name:  AddRef()                            
		// |  Class: cMyClipping
		// | 		Add a reference
		// |______________________________________________________________________
		uint32 cMyClipping::AddRef()
		{
			return TBasicUnknown::AddRef();
		} // END OF cMyClipping::AddRef


		cMyClipping::cMyClipping(	IDType	inDataType,	void*	inData, uint32 Size)
		: fData(inData),
			fType(inDataType),
			fSize(Size)
		{
		}

		cMyClipping::~cMyClipping(void)
		{
			// Do whatever you want to release the fData member
		}

		
		How to Put a clip object into the Clipboard:
		--------------------------------------------
		...
		TMCCountedPtr<cMyClipping> MyClipping;
		cBlobClipping::Create( &MyClipping, kMyType, <Your Data>, <Size of Your Data>);
		ThrowIfNil( MyClipping );
		gClipboardUtilities->Put( MyClipping, 0 );
		...

		How to get a clip object from the Clipboard
		-------------------------------------------

		boolean MustFree;
		TMCCountedPtr<IMFClipping> Clip;

		if ( gClipboardUtilities->Get(kMyType, &Clip, MustFree, 0 ) == kNoErr)
		{
			TMCCountedPtr<cMyClipping> MyClipping;
			
			Clip->QueryInterface( IID_MyClipping, (void**)&MyClipping );
			ThrowIfNil( MyClipping );
			
			// retrieve the data through MyClipping->GetData()...
		}
		
		
		
		
		
		Revision History

		when		who			what & why
		==========	==========	======================================================
		10/13/99	EricB		Added IMFClipboard::Append to the API (it was already coded, but not given in the API)
		9/9/99		Ian			Cleaned up formatting, and got rid of parameter that
								become redundant when the clippings were made into
								counted objects.
		9/6/99		Brice		Added interface for clipboard

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

#if CP_PRAGMA_ONCE
#pragma once
#endif

#ifndef __IMFClipboard__
#define __IMFClipboard__

#include "MCCompObj.h"
#include "MFTypes.h"

template <class T> class TMCArray;

//*********************** Globally Unique Ids ********************************

MCDEFINE_GUID_H(IID_IMFClipping);
MCDEFINE_GUID_H(IID_IMFClipboard);

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

enum EMFEmptyClipping
{
	kMFClipping_Empty = '****'						//Empty clipping.
};

enum EMFClipboardData
{
	kClipboard_CopyData				= 0x00000001,	//Clipboard will make a copy of the data.
	kClipboard_AquireData			= 0x00000002,	//Clipboard becomes the owner of the data.
	kClipboard_DeferedData			= 0x00000004,	//Will provide the data on demand.
};

enum EMFClipboardTranslation
{
	kClipboard_Get_AllowTranslation	= 0x00000001,	//Allow translated data.
};

enum EMFClipboardTranslator
{
	kClipboardTranslator_OneWay		= 0x00000001,	//Can only translate from -> to.
	kClipboardTranslator_BothWays	= 0x00000002	//can translate from <-> to.
};


/*****************************************************************************\
*                                                                             *
*        IMFClipping                                                          *
*                                                                             *
*        Basic clipping interface                                             *
*                                                                             *
\*****************************************************************************/

/// \addtogroup MCF
/// \{

// ****************************************************************************
//								IMFClipping
// 
/// Basic clipping interface
///
struct IMFClipping : public IMCUnknown
{
	virtual IDType  MCCOMAPI	GetType				(void) const = 0; 
	virtual void*   MCCOMAPI	GetData				(void) const = 0;
	virtual uint32  MCCOMAPI	GetSize				(void) const = 0;
	virtual IDType  MCCOMAPI	GetFlattenedType	(void) const = 0;
	virtual boolean MCCOMAPI	Flatten				(IMFClipping** outFlatClipping, uint32 inFlags) = 0;
};

/// \}


/// \addtogroup Utilities
/// \{

// ****************************************************************************
//								IMFClipboard
// 
/// General Clipboard interface mechanism
///
struct IMFClipboard : public IMCUnknown
{
	virtual void  MCCOMAPI	Clear				(void) = 0;
	virtual void  MCCOMAPI	Put					(IMFClipping* inEntry, uint32 inFlags = 0) = 0; // Flags is not used
	virtual void  MCCOMAPI	Append				(IMFClipping* inEntry, uint32 inFlags = 0) = 0; // Flags is not used
	virtual MCErr MCCOMAPI	Get					(IDType	inDataType, IMFClipping** outClipping, uint32 inFlags) = 0;
	virtual void  MCCOMAPI	GetAvailableTypes	(TMCArray<IDType>& outTypes, boolean inIncludeTranslatedTypes) const = 0;
};

/// \}

#endif // __IMFClipboard__
