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

		IMFExPart.h

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

		Author:	Greg and Josh
		Date:	4/20/98

		Part extension COM interface.

		Revision History

		when		who			what & why
		==========	==========	======================================================
		10/27/99	Yann		Added BaseWindowBecameVisible
		10/14/99	Pierre		Added GetCursorID
		10/13/99	Yann		Added IMFExPart::SetShown
		09/12/99	Pierre		Added BecameFirstResponder
		8/1/99		Ian			Mouse moved API change.
		05/25/99	Jerome		Changed TMCPoint to TMCPoint
		4/5/99		Greg		Added SelfPrepareToDestroy
		04/04/99	Pbk			Added ChangedBounds
		3/3/99		Greg		Added GetValue/SetValue 
		2/16/99		Greg		Added GetDropArea()
		2/11/99		Joshua		Added IMFExPart::ParentChangedBounds
		1/13/99		Eml			Added IMFExPart::FinishRead
		6/10/98		Ian			SelfMouseEnter() & SelfCursor() became SelfMouseMoved().
		5/15/98		Joshua		New API calls

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

#ifndef __IMFEXPART__
#define __IMFEXPART__

#if CP_PRAGMA_ONCE
#pragma once
#endif

#include "MCCompObj.h"
#include "MFPartTypes.h"
#include "MCEvent.h"
#include "MCFInterfaceIDs.h"

struct IMCGraphicContext;
struct IMFDropCandidate;
struct IMFDropArea;
struct IMFMenu;
class TMFDragFlavors;

class  TMCPoint;
class  TMCRect;
class  TComponentClass;
class  TMCPlatformWindow;

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

MCDEFINE_GUID2(IID_IMFExPart, R_IID_IMFExPart);

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



/******************************************************************************\
*                                                                              *
*           IMFExPart                                                          *
*                                                                              *
\******************************************************************************/

#ifndef qDemoVersion //regular interface

/// \addtogroup MCF
/// \{

/// This is the interface for an external part. To implement your own part you should
/// derive your object from TBasicPart which provides a basic implementation of the
/// methods of IMFExPart.
///
/// Note that you only need to implement a few methods to get a valid part (SelfDraw
/// is sometimes enough).
///
/// The family ID for a part extension is 'part'. For more information on custom parts,
/// see the Overview of the SDK.
///
struct IMFExPart : public IMCUnknown
{
	// ****************************************************************************
	//								ValidateCaches
	// 
	/// Tells us that we can validate our caches because we're going to need them in the next draw
	/// 
	/// 
	virtual void	MCCOMAPI ValidateCaches			() = 0;

	// ****************************************************************************
	//								SelfActivate
	// 
	/// Called when the part is activated/deactivated.
	/// 
	/// \param beActive  True if the part is activated. False if it is deactivated.
	/// 
	virtual void	MCCOMAPI SelfActivate			(boolean beActive) = 0;
	
	// ****************************************************************************
	//								SetShown
	// 
	/// Sets the visibility of the part.
	/// 
	/// \param inShown  
	/// 
	virtual void	MCCOMAPI SetShown				(boolean inShown) = 0;
	
	// ****************************************************************************
	//								BaseWindowBecameVisible
	// 
	/// When the window that contains the part just became visible/invisible.
	/// 
	virtual void	MCCOMAPI BaseWindowBecameVisible(boolean inShown) = 0;

	// ****************************************************************************
	//								SelfMouseMoved
	// 
	/// Called when the mouse has moved over the part.
	/// 
	/// \param inWhere      The position of the mouse.
	/// \param inModifiers  The modifier keys (Shift, Ctrl...)
	/// 
	virtual boolean	MCCOMAPI SelfMouseMoved			(const TMCPoint& inWhere, const TMCModifiers& inModifiers) = 0;
	
	// ****************************************************************************
	//								SelfMouseEntering
	// 
	/// Called when the mouse cursor enters the part.
	/// 
	/// \param inWhere      The position of the mouse.
	/// \param inModifiers  The modifier keys (Shift, Ctrl...)
	/// 
	virtual void	MCCOMAPI SelfMouseEntering		(const TMCPoint& inWhere, const TMCModifiers& inModifiers) = 0;
	
	// ****************************************************************************
	//								SelfMouseStillInside
	// 
	/// Called when the mouse cursor moves inside the part.
	/// 
	/// \param inWhere      The position of the mouse.
	/// \param inModifiers  The modifier keys (Shift, Ctrl...)
	/// 
	virtual void	MCCOMAPI SelfMouseStillInside	(const TMCPoint& inWhere, const TMCModifiers& inModifiers) = 0;
	
	// ****************************************************************************
	//								SelfMouseLeaving
	// 
	/// Called when the mouse has just left the part.
	/// 
	/// \param inModifiers  The modifier keys (Shift, Ctrl...)
	/// 
	virtual void	MCCOMAPI SelfMouseLeaving		(const TMCModifiers& inModifiers) = 0;

	// ****************************************************************************
	//								SelfTrackDragAndDropEntering
	// 
	/// Function called when the mouse enters the Part during a drag and drop.
	/// 
	/// \param inWhere			 Point in local coordinate space where the cursor is
	/// \param inOfferedTypeList Flavors offered by the current drop candiadate.
	/// 
	virtual void		MCCOMAPI SelfTrackDragAndDropEntering(const TMCPoint& inWhere,
															  const TMFDragFlavors& inOfferedTypeList) = 0;

	// ****************************************************************************
	//								SelfTrackDragAndDropStillInside
	// 
	/// Function called when the mouse track within the Part during a drag and drop.
	/// 
	/// \param inWhere			 Point in local coordinate space where the cursor is
	/// \param inOfferedTypeList Flavors offered by the current drop candiadate.
	/// 
	virtual void		MCCOMAPI SelfTrackDragAndDropStillInside(const TMCPoint& inWhere,
																 const TMFDragFlavors& inOfferedTypeList) = 0;

	// ****************************************************************************
	//								SelfTrackDragAndDropLeaving
	// 
	/// Function called when the mouse leaves the Part during a drag and drop.
	/// 
	/// \param inOfferedTypeList Flavors offered by the current drop candiadate.
	/// 
	virtual void		MCCOMAPI SelfTrackDragAndDropLeaving(const TMFDragFlavors& inOfferedTypeList) = 0;

	// ****************************************************************************
	//								SelfMouseDown
	// 
	/// Handles a click with the left button of the mouse within the part's bounds
	/// 
	/// Note: When the previous implementation returned a boolean result,
	/// you should now return TMFEventResult(result, result) in most cases.
	///
	/// \param inWhere  point in local coordinates of the mouse down
	/// \param inEvent  event information (like clickcount)
	/// 
	virtual TMFEventResult MCCOMAPI SelfMouseDown	(const TMCPoint& inWhere, const TMCPlatformEvent& inEvent) = 0;

	// ****************************************************************************
	//								SelfContextMouseDown
	// 
	/// Handles a click with the right button of the mouse within the part's bounds
	/// 
	/// \param inWhere  point in local coordinates of the mouse down
	/// \param inEvent  event information (like clickcount)
	/// 
	virtual boolean	MCCOMAPI SelfContextMouseDown	(const TMCPoint& inWhere, const TMCPlatformEvent& inEvent) = 0;
	
	// ****************************************************************************
	//								SelfMiddleMouseDown
	// 
	/// Handles a click with the middle button of the mouse within the part's bounds
	/// 
	/// \param inWhere  point in local coordinates of the mouse down
	/// \param inEvent  event information (like clickcount)
	/// 
	virtual boolean	MCCOMAPI SelfMiddleMouseDown(const TMCPoint& inWhere, const TMCPlatformEvent& inEvent) = 0;

	// ****************************************************************************
	//								SelfDraw
	// 
	/// Called to ask the part to draw itself.
	/// 
	/// \param inContext     The graphic context to use for the drawing.
	/// \param inUpdateBBox  The rectangle that should be drawn.
	/// 
	virtual void	MCCOMAPI SelfDraw				(IMCGraphicContext* inContext, const TMCRect& inUpdateBBox) = 0;

	// ****************************************************************************
	//								SelfPrepareToDestroy
	// 
	/// Called when the part is about to be destroyed to give it an opportunity to
	/// release all counted references and caches.
	/// 
	virtual void	MCCOMAPI SelfPrepareToDestroy	() = 0;
	
	// ****************************************************************************
	//								FinishRead
	// 
	/// Called just after reading the part from the resource.
	/// 
	virtual void	MCCOMAPI FinishRead				() = 0;

	// ****************************************************************************
	//								ParentChangedBounds
	// 
	/// Called each time the bounds of the parent's part were changed.
	/// 
	/// \param oldBounds  The old bounds of the parent.
	/// \param newBounds  The new bounds of the parent.
	/// \param inval      True if the part should be invalidated.
	/// 
	virtual boolean	MCCOMAPI ParentChangedBounds	(const TMCRect& oldBounds,
													 const TMCRect& newBounds,
													 boolean inval)=0;

	// ****************************************************************************
	//								GetDropArea
	// 
	/// Returns a pointer to a drop area for this part. Called when the users drops
	/// an object on the part.
	/// 
	/// \param inWhere				The position of the mouse
	/// \param inCandidate			The object that is dropped
	/// \param outAcceptedFlavor	Returns the type that is accepted if any.
	/// \param outDropArea          Returns a drop area if there is one, NULL otherwise.
	/// \param outDrawDropCandidate	Draw the drop candidate or not.
	/// 
	virtual void	MCCOMAPI GetDropArea			(const TMCPoint& inWhere,
													 IMFDropCandidate& inCandidate,
													 IDType& outAcceptedFlavor,
													 IMFDropArea** outDropArea,
													 boolean& outDrawDropCandidate) = 0;

	// ****************************************************************************
	//								GetValue
	// 
	/// Returns the value of the part.
	///
	/// \return true if outValue is valid (i.e., the external part handled the
	/// GetValue) and false otherwise
	///
	/// \param outValue     A pointer to a buffer when the value should be stored. 
	/// \param inValueType  The type of value requested.
	/// 
	virtual boolean MCCOMAPI GetValue				(void* outValue, MFPartValueType inValueType) const = 0;

	// ****************************************************************************
	//								SetValueLowLevel
	// 
	/// Sets the value of the part.
	/// 
	/// \param inValue            A pointer to the value
	/// \param inValueType        The type of the value
	/// 
	/// \returns true if the value changed
	///
	virtual boolean MCCOMAPI SetValueLowLevel		(const void* inValue,
													 MFPartValueType inValueType) = 0;

	// ****************************************************************************
	//								ChangedBounds
	// 
	/// Notifies the EXPart that its bounds have changed. It is notification only. the internal has already adjusted
	/// 
	/// \param oldBounds  Old bounds of the part
	/// \param newBounds  New bounds of the part
	/// \param inval      True if the part should be invalidated.
	/// 
	virtual boolean	MCCOMAPI ChangedBounds			(const TMCRect& oldBounds, const TMCRect& newBounds, boolean inval)=0;


	// ****************************************************************************
	//								GetCursorID
	// 
	/// Returns the Identifier of the cursor that should be used when the mouse
	/// pointer is over the part.
	/// 
	/// \param inWhere      The position of the mouse cursor.
	/// \param outCursorID  the Identifier of the cursor
	///	\return a pointer to the component class the app needs to use in order to load the cursor's resource (very rarely needed).
	///			Returning null will use this (IMFExPart) resources.
	/// 
	virtual TComponentClass* MCCOMAPI GetCursorID		(const TMCPoint& inWhere, MFCursorID& outCursorID) const = 0;

	// ****************************************************************************
	//								SelfMouseWheel
	// 
	/// Overide this if you want to handle the mouse wheel.
	/// Return true if you handled it
	///
	/// \param inWhere       The position of the mouse cursor.
	/// \param inModifiers   The state of the modifier keys (Shift, Ctrl,...)
	/// \param inWheelDelta  The delta of the mouse wheel.
	/// 
	virtual boolean		MCCOMAPI SelfMouseWheel		(const TMCPoint& inWhere, const TMCModifiers& inModifiers, int16 inWheelDelta)= 0;

	// ****************************************************************************
	//								ReadAttribute
	// 
	/// Reads an attribute of the part from a stream (file usually).
	/// 
	/// \param inKeyword  The keyword identifying the attribute.
	/// \param inStream   The stream.
	///
	/// \return true if the attribute has been read.
	/// 
	virtual boolean		MCCOMAPI ReadAttribute		(int32 inKeyword, TMCiostream& inStream)=0;

	// ****************************************************************************
	//								FinishCreateFromResource
	// 
	/// Override if you need to perform some initialisations that you couldn't do in FinishRead (eg because you need the part's parent).
	/// 
	virtual void		MCCOMAPI FinishCreateFromResource() = 0;

	// ****************************************************************************
	//								GetPlatformWindow
	// 
	/// Returns the plaform window attached to the part if any. Usually you do not
	/// need to implement this method. Return NULL if no platform windows is attached
	/// to this part in which the platform window of the parent window should be used
	/// 
	virtual TMCPlatformWindow*	MCCOMAPI GetPlatformWindow() = 0;

	// ****************************************************************************
	//								FillContextualMenu
	// 
	/// When the part's contextual menuid is kEmptyMenuID this function will be called
	/// so that you can dynamically fill it. 
	/// SelfMenuAction will give you the chosen menu action
	virtual void		MCCOMAPI FillContextualMenu		(IMFMenu* inMenu) = 0;

	// ****************************************************************************
	//								GetContextualMenuID
	// 
	/// Returns the part's contextual menu id. The id is meaningful only if
	/// OverridesContextualMenuID() returns true.
	virtual boolean		MCCOMAPI OverridesContextualMenuID() = 0;
	virtual ResourceID	MCCOMAPI GetContextualMenuID() = 0;
};
/// \}

#else 	//(qDemoVersion) begin scrambled interface
struct IMFExPart : public IMCUnknown
{
	virtual void	MCCOMAPI SelfActivate			(boolean beActive) = 0;
	virtual void	MCCOMAPI SetShown				(boolean inShown) = 0;
	virtual void	MCCOMAPI FinishCreateFromResource() = 0;
	virtual boolean	MCCOMAPI SelfMouseWheel			(const TMCPoint& inWhere, const TMCModifiers& inModifiers, int16 inWheelDelta)= 0;
	virtual void	MCCOMAPI FillContextualMenu		(IMFMenu* inMenu) = 0;
	virtual void	MCCOMAPI BaseWindowBecameVisible(boolean inShown) = 0;
	virtual boolean	MCCOMAPI SelfMouseMoved			(const TMCPoint& inWhere, const TMCModifiers& inModifiers) = 0;
	virtual void	MCCOMAPI SelfMouseEntering		(const TMCPoint& inWhere, const TMCModifiers& inModifiers) = 0;
	virtual boolean	MCCOMAPI ChangedBounds			(const TMCRect& oldBounds, const TMCRect& newBounds, boolean inval)=0;	
	virtual void	MCCOMAPI SelfMouseLeaving		(const TMCModifiers& inModifiers) = 0;
	virtual TMFEventResult MCCOMAPI SelfMouseDown	(const TMCPoint& inWhere, const TMCPlatformEvent& inEvent) = 0;
	virtual boolean	MCCOMAPI SelfContextMouseDown	(const TMCPoint& inWhere, const TMCPlatformEvent& inEvent) = 0;
	virtual void	MCCOMAPI SelfDraw				(IMCGraphicContext* inContext, const TMCRect& inUpdateBBox) = 0;	
	virtual boolean	MCCOMAPI ReadAttribute			(int32 inKeyword, TMCiostream& inStream)=0;
	virtual void	MCCOMAPI FinishRead				() = 0;
	virtual boolean	MCCOMAPI SelfMiddleMouseDown(const TMCPoint& inWhere, const TMCPlatformEvent& inEvent) = 0;
	virtual void	MCCOMAPI SelfPrepareToDestroy	() = 0;
	virtual void	MCCOMAPI ValidateCaches			() = 0;
	virtual TMCPlatformWindow*	MCCOMAPI GetPlatformWindow() = 0;
	virtual boolean	MCCOMAPI ParentChangedBounds	(const TMCRect& oldBounds,
													 const TMCRect& newBounds,
													 boolean inval)=0;
	virtual void	MCCOMAPI GetDropArea			(const TMCPoint& inWhere,
													 IMFDropCandidate& inCandidate,
													 IDType& outAcceptedFlavor,
													 IMFDropArea** outDropArea,
													 boolean& outDrawDropCandidate) = 0;	
	virtual boolean MCCOMAPI SetValueLowLevel		(const void* inValue,
													 MFPartValueType inValueType) = 0;		
	virtual boolean MCCOMAPI GetValue				(void* outValue, MFPartValueType inValueType) const = 0;	
	virtual TComponentClass* MCCOMAPI GetCursorID	(const TMCPoint& inWhere, MFCursorID& outCursorID) const = 0;
	virtual void	MCCOMAPI SelfMouseStillInside	(const TMCPoint& inWhere, const TMCModifiers& inModifiers) = 0;
	virtual void	MCCOMAPI SelfTrackDragAndDropLeaving(const TMFDragFlavors& inOfferedTypeList) = 0;
	virtual void	MCCOMAPI SelfTrackDragAndDropEntering(const TMCPoint& inWhere, const TMFDragFlavors& inOfferedTypeList) = 0;
	virtual void	MCCOMAPI SelfTrackDragAndDropStillInside(const TMCPoint& inWhere, const TMFDragFlavors& inOfferedTypeList) = 0;
};
#endif	//(qDemoVersion) end scrambled

#endif