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

		IMFResponder.h

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

		Author:	Josh
		Date:	6/19/98

		Responder extension COM interface.

		Revision History

		when		who			what & why
		==========	==========	======================================================
		09/12/99	Pierre		Merged BecameFirstResponder and ResignedFirstResponder
		09/06/99	Yann		Added Receive() to the API
		07/11/99	Pierre		Added BroadCastMessageDown to the API
		03/22/99	del			Put those freaking parameter names in the API !!!!
								It helps !!! (ok, I'm just a bit upset)
		2/11/99		Joshua		Added SetWantsToBeFirstResponder
		02/10/99	Mathieu		Added BroadcastMessage
		9/25/98		Greg		Added SetNextIMFResponder()
		8/13/98		Joshua		Added Add and Remove Listener

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

#ifndef __IMFRESPONDER__
#define __IMFRESPONDER__

#if CP_PRAGMA_ONCE
#pragma once
#endif

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

struct IMCGraphicContext;

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

MCDEFINE_GUID(IID_IMFResponder, 0x787a5705, 0xeb6f, 0x11d1, 0xab, 0x25, 0x0, 0x60, 0x8, 0x15, 0xad, 0x45);

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



/******************************************************************************\
*                                                                              *
*           IMFResponder                                                       *
*                                                                              *
\******************************************************************************/
/// \addtogroup MCF
/// \{

/// <P>The IMFResponder interface is for objects that need to be able to respond to broadcast messages.
/// This is extensively used among Parts in the user interface, for example to broadcast notification that 
/// Part values changed, or that bounds have changed.</P>
/// <P>When an event happens, the first Responder is offered the chance to handle it.  Should it not handle
/// the event, it's passed along the chain of Responders until handled and told to stop.  Each responder, on
/// receiving the event, passes it on to the next Responder.  For example, if the user types in an Edit Text Part,
/// the edit text will generally want to be first Responder, and so will receive the keystroke events.  Should 
/// the user do something other than type, though, like right-clicking in the edit text, the Edit Text Part would
/// send the event on to its next Responder, and on upwards until something handles the click.</P>
struct IMFResponder : public IMCUnknown
{
	
	// ****************************************************************************
	//								AddIMFResponderListener
	// 
	/// Adds a new Responder to this Responder's list of listeners, which is used by 
	/// BroadcastMessageToListeners()
	/// 
	/// \param inListener  Pointer to the Responder to add to the list
	/// 
	virtual void	MCCOMAPI AddIMFResponderListener	 (IMFResponder* inListener)=0;
	
	// ****************************************************************************
	//								RemoveIMFResponderListener
	// 
	/// Removes a Responder from this Responder's list of listeners, which is used by 
	/// BroadcastMessageToListeners()
	/// 
	/// \param inListener  Pointer to the Responder to remove from the list
	/// 
	virtual void	MCCOMAPI RemoveIMFResponderListener	 (IMFResponder* inListener)=0;
	
	// ****************************************************************************
	//								GetInstanceID
	// 
	/// Used to get an ID from a Responder, generally in order for an object to choose the 
	/// correct response to the message passed.  For Parts, this is the Part ID.  Responders
	/// without a useful ID to pass will return kNoId.
	/// 
	///  \return The ID of the Responder
	///
	virtual IDType	MCCOMAPI GetInstanceID				 () const = 0;

	// ****************************************************************************
	//								SetNextIMFResponder
	// 
	/// Sets the next Responder to receive messages after this one.
	/// 
	/// \param inNewResponder  Pointer to the Responder to be added as the next Responder
	/// 
	virtual void	MCCOMAPI SetNextIMFResponder		 (IMFResponder* inNewResponder) = 0;

	// ****************************************************************************
	//								SetWantsToBeFirstResponder
	// 
	/// Sets whether or not this Responder wants to be the first Responder
	/// 
	/// \param inWantsTo  If true, the Responder wants to be first
	/// 
	virtual void	MCCOMAPI SetWantsToBeFirstResponder	 (boolean inWantsTo) = 0;

	// ****************************************************************************
	//								BecameFirstResponder
	// 
	/// Called when this Responder becomes first Responder.  
	/// 
	/// \param on  If true, this Part became first responder.
	/// 
	virtual void	MCCOMAPI BecameFirstResponder		 (boolean on) = 0;


	// ****************************************************************************
	//								Receive
	// 
	/// This function is used to try to handle incoming messages.  Generally, it will be used as follows:
	/// \code
	/// if (Receive(...) == kMFReceiveResult_KeepGoing)
	///     BroadcastMessageUp(...);
	/// \endcode
	/// The message can also be passed with a pointer to some data associated with the message.  For example,
	/// a Part value changed message can be passed along with a pointer to the new value.
	///
	/// \param message  The message being passed
	/// \param source   The Responder originating the message
	/// \param data     Data associated with a message.  Optional.
	/// \return True if the message has been handled.
	///
	virtual	boolean	MCCOMAPI Receive					 (MessageID message, IMFResponder* source, void* data) = 0;
	
	// ****************************************************************************
	//								BroadcastMessageUp
	// 
	/// Passes a message up to the next Responder.
	/// \see Receive
	/// 
	/// \param message  The message being passed
	/// \param source   The Responder originating the message
	/// \param data     Data associated with a message.  Optional.
	/// 
	virtual void	MCCOMAPI BroadcastMessageUp			 (MessageID message, IMFResponder* source, void* data) = 0;
	
	// ****************************************************************************
	//								BroadcastMessageToListeners
	// 
	/// Passes a message to the list of this Responder's listeners.
	/// \see Receive
	/// 
	/// \param message  The message being passed
	/// \param source   The Responder originating the message
	/// \param data     Data associated with a message.  Optional.
	/// 
	virtual void	MCCOMAPI BroadcastMessageToListeners (MessageID message, IMFResponder* source, void* data) = 0;
	
	// ****************************************************************************
	//								BroadcastMessageDown
	// 
	/// Broadcasts a message down to the children of a given object.  Generally only 
	/// used between Parts in the UI.
	/// 
	/// \param message  The message being passed
	/// \param source   The Responder originating the message
	/// \param data     Data associated with a message.  Optional.
	/// 
	virtual void	MCCOMAPI BroadcastMessageDown		 (MessageID message, IMFResponder* source, void* data) = 0;

	// ****************************************************************************
	//								BecomeFirstResponder
	// 
	/// Causes this part to become the first Responder.  In the process, makes the former
	/// first Responder resign.
	/// 
	/// \return True if the former first Responder resigned and this Responder became first.
	///
	virtual	boolean	MCCOMAPI BecomeFirstResponder() = 0;


	// ****************************************************************************
	//								GetIsFirstResponder
	// 
	/// Returns true if this responder is the first responder
	/// 
	virtual	boolean	MCCOMAPI GetIsFirstResponder	() = 0;
};

/// \}
#endif