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

		IShComponent.h

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

		IShComponent definition                                          

		Author:	Emil
		Date:	7/14/98

		Revision History

		when		who			what & why
		==========	==========	======================================================
		6/23/99		Pierre		added IShMinimalParameterComponent
		06/01/99	del			Inval() won't invalidate the component if the component generate it.
		3/19/99		psq			SetExpanded/IsExpanded
		10/9/98		Eml			Decomified PutInPart and UpdateFromPart, 
								now in IMFParameterComponentPart
		10/5/98		dsm			changed "const IDType" into "#define"
		9/29/98		Eml			Moved TPMapElement definition
		9/29/98		Eml			Added PutInPart/UpdateFromPart API
		9/29/98		Eml			Added CloneComponent

*****************************************************************************************/
#ifndef __IShComponent__
#define __IShComponent__

#if CP_PRAGMA_ONCE
#pragma once
#endif

#include "ComTypes.h"
#include "MCString.h"


// forward declarations

class TPMapElement;
struct IShParameterComponent;
struct IMFPart;

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

MCDEFINE_GUID_H(IID_IShComponent);
MCDEFINE_GUID_H(IID_IShMinimalParameterComponent);
MCDEFINE_GUID_H(IID_IShParameterComponent);


/*****************************************************************************\
*                                                                             *
*  IShComponent                                                               *
*                                                                             *
*    Component interface                                                      *
*                                                                             *
\*****************************************************************************/

/// \addtogroup BasicCOM
/// \{

/// Component interface
///
/// This is the interface for components, as defined by the 'COMP' resource.  Components are created
/// by IShComponentUtilities functions, generally.  They are identified by the family and class signatures 
/// in the resource file.  
struct IShComponent: public IMCUnknown
{
	virtual IDType		MCCOMAPI GetFamilySignature() const = 0;
	virtual IDType		MCCOMAPI GetClassSignature() const = 0;
	virtual MCCOMErr	MCCOMAPI GetClassName(TMCString& name) const = 0;

	// ****************************************************************************
	//								GetComponentVersion
	// 
	/// \return The version number of the component, used for file versioning.
	/// 
	/// 
	virtual int32		MCCOMAPI GetComponentVersion() const = 0;

	// usually returns false, returns true for components who use a default instance ( like dataComponents)
	virtual boolean		MCCOMAPI IsDefaultComponent() const = 0;

	// invalide the component preview ( if there is any )
	virtual void		MCCOMAPI InvalidatePreview() = 0;

	// ****************************************************************************
	//								GetPrefComponent
	// 
	/// Each component may delegate its preferences to a (unique) IShParameterComponent,
	/// returned by this function. 
	/// \return NULL if this component has no preferences component, otherwise, a pointer to the component.
	/// \see IShPrefsComponent
	/// 
	virtual IShParameterComponent* MCCOMAPI GetPrefComponent() = 0;

	/// Returns true when the family of the Component is hidden
	virtual boolean				MCCOMAPI IsFamilyHidden() = 0;
};


/*****************************************************************************\
*                                                                             *
*  IShMinimalParameterComponent                                               *
*                                                                             *
*    Parameter Component interface                                            *
*                                                                             *
\*****************************************************************************/
/// Minimal parameter component.  Holds parameters, doesn't have an interface.
/// \see IShParameterComponent
struct IShMinimalParameterComponent: public IMCUnknown
{
	virtual IDType	 MCCOMAPI GetFamilySignature() const = 0;
	virtual IDType	 MCCOMAPI GetClassSignature() const = 0;
	virtual MCCOMErr MCCOMAPI GetClassName(TMCString& name) const = 0;

	virtual MCCOMErr MCCOMAPI GetParameter(IDType keyword, void* parameter) = 0;
	virtual MCCOMErr MCCOMAPI SetParameter(IDType keyword, void* parameter, boolean inNotify=true) = 0;
	virtual MCCOMErr MCCOMAPI GetParameterType(IDType keyword, IDType& parameterType) = 0;
	virtual uint32	 MCCOMAPI GetParameterCount() = 0;
	virtual MCCOMErr MCCOMAPI GetParameterInfo(uint32 index, TPMapElement& info) = 0;
	virtual void	 MCCOMAPI Inval(boolean inNotifyExternal = true, boolean inNotifyUI = false) = 0;
};


/*****************************************************************************\
*                                                                             *
*  IShParameterComponent                                                      *
*                                                                             *
*    Parameter Component interface                                            *
*                                                                             *
\*****************************************************************************/
/// Parameter component.  Holds parameters, and can provide an interface for display/control.
/// 
struct IShParameterComponent: public IShMinimalParameterComponent
{
	virtual int8*					MCCOMAPI GetParamsBuffer() = 0;
	virtual int16					MCCOMAPI GetResID() = 0;
	virtual int16					MCCOMAPI GetViewID() = 0;
	virtual void					MCCOMAPI GetView(IMFPart** outPart) = 0;
	virtual boolean					MCCOMAPI IsEqual(IShParameterComponent* extension) = 0;
	virtual MCCOMErr				MCCOMAPI GetParameterPointer(IDType keyword, void** parameter) = 0;
	virtual void					MCCOMAPI CloneComponent(IShParameterComponent**) = 0;	
	virtual boolean					MCCOMAPI IsExpanded() const = 0;
	virtual void					MCCOMAPI SetExpanded(boolean isExpanded) = 0;
	virtual boolean					MCCOMAPI IsSelected() const = 0;
	virtual void					MCCOMAPI SetSelected(boolean isExpanded) = 0;

	virtual IDType	 MCCOMAPI GetMiniPartID() const = 0;
	virtual boolean	 MCCOMAPI IsCollapsible() const	= 0;
	virtual uint32	 MCCOMAPI GetStyle()      const = 0;

	///returns the IShComponent interface of IShParameterComponent
	virtual IShComponent* MCCOMAPI GetThisComponent() = 0;

	///returns the number of subcomponents contained in this component
	virtual	uint32	MCCOMAPI GetSubcomponentCount() = 0;

	///returns the component's subcomponent, if any
	virtual IShParameterComponent*	MCCOMAPI GetSubcomponent() = 0;

	///returns the resource id of the view of the parameter with the id "keyword" or
	///		   -1 if no view for this parameter
	virtual int16					MCCOMAPI GetParamViewID(IDType keyword) = 0;

	/// this is called when a new component is created, to set its 
	/// parameters to a default value
	virtual MCCOMErr				MCCOMAPI SetDefaultParameters() = 0;

};

/// \}

#endif


