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

		IShUtilities.h

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

		IShUtilities definition                                                   
		IShComponentUtilities definition   
		IShMenuUtilities definition
		IShFileStream definition
		
		Author:	Ray Dream
		Date:	3/2/98

		Revision History

		when		who			what & why
		==========	==========	======================================================
		11/9/99		Ian			Added GetMultipleFiles() api.
		10/19/99	EricB		Added IShComponentUtilities::ReadComponent() that takes a familySignature
								as third argument. Note : This method does exactly what the other ReadComponent() does;
								it assumes that you already read the familySignature's token from the stream, but not the begin token.
		10/18/99	Ian			Removed include of files.h!?!?! in MAC only section, it
								was included to define FSSpec which is used in
								FSSpecFromFullPathname()!?!!?.
		10/14/99	Yann		IMCFontList support
		10/05/99	EricB		IShMouseAction can now be 'not constrained to the view' they apply to.
								To do so, you just need to override the method ConstrainedToView, and return false.
								Default (TBasicMouseAction) returns true, to keep the previous behavior.
		9/11/99		Ian			Fixes for new refcounting stuff.
		8/17/99		Yann		Added IShMenuUtilities::InvalidateMenus
		8/16/99		Ian			Added NeedsToPrepareMenus to IShAction and IShMouseAction
		08/04/99	EricB		Added IShMenuUtilities::FindMenuByID
		07/26/99	Luc			Added GetUIImage in IShUtilities
		07/19/99	Arnaud		OpenDocument directly opens the doc and returns it as an out-parameter.
		7/13/99		cph			cleaned up method names of random calls in shell utils (now setrandomseed & randomstep)
		06/07/99	Arnaud		Added GetCreator in IShUtilities
		5/25/99		Ian			Added CreateCompatiblePixelBucket() and DestroyCompatiblePixelBucket()
								use these to create and destroy a pixel bucket
								that can be blit to the screen quickly.
		05/21/99	Arnaud		Added OpenDocument and a new GetFileTypes
		4/20/99		Greg		Added StringWidth and GetTextMetrics
		4/5/99		Greg		Added debug-only counted ptr reference checker support
								and CreateToolWindow
		3/31/99		psq			fix WIN_MCGlobals.h
		3/26/99		Greg		Added GetUITextStyle to personality utils
		3/26/99		Joshua		New progress API
		3/26/99		Yann		Changed IShUtilities::DoAlert() API
		3/16/99		Joshua		Added fields to TComponentClassInfo
		03/10/99	Nba			Added MCRandomStep in utilities
		03/10/99	Nba			Added MCRandomStep in utilities
		03/10/99	Arnaud		Added IShUtilities::GetOpenDocumentsCount and GetOpenDocumentByIndex
		03/05/99	Mathieu		GetUIImageInfo and GetUIImageBucket - load an UI image from an plugin
		02/29/99	Arnaud		Removed GetIndString from IShUtilities and made the one defined in
								ResourceUtilities use TMCString (instead of C strings)
		2/23/99		Greg		Changed IShPersonalityUtilities to do UIColors
		2/22/99		Joshua		Added IShMenuUtilities::CreateMenu
		2/17/99		EricB		Added 'nextAction' as a return argument to IShMouseAction::Track
		2/16/99		Greg		Added DragAndDropUtilities
		2/11/99		Joshua		Added IShComponentUtilities::CreateIUnknown
		2/4/99		psq			fix const problem
		02/02/99	EricB		Removed the last occurence of IShContext (replaced by IMFResponder)
		01/27/99	Nba			Added mem utils for new/delete
		1/18/99		Joshua		Added IShComponentUtilities::GetComponentClassInfoArrayByFamilyID
		1/18/99		Greg		Added IShPersonalityUtilities
		1/11/99		tsh			use Debug_ _never_ _DEBUG
		01/08/99	Yann		Fixed 'const' mess in IShMouseAction::Track(), etc.
		11/11/98	Arnaud		Added physical memory functions to IShMemoryUtilities
		10/14/98	cph			added IShAssertUtiltities
		10/12/98	Greg		Added some tool routines to IShMenuUtilities
		10/5/98		dsm			changed uint32 to IDType
		9/29/98		Eml			Added IShComponentUtilities::GetDefaultComponent
		9/28/98		tsh			added FSSpecFromFullPathname (Mac only) to IShFileUtilities
		9/21/98		tsh			added IID_IShFileUtilities, moved GetSeparator, GetAppPath=>GetAppDirectory
		9/14/98		tsh/cph		added GetSeparator and GetAppPath to IShFileStream
		8/7/98		Greg		merged IShMenuManager into IShMenuUtilities, added IShPartUtilities,
								added IShResourceUtilities
		8/4/98		cph			brought over IShMenuManager, IShAction, IShMouseAction, IShActionManager from ISh3DUtilties
		7/29/98		cph			cleanup - removed unnec. forward declarations
		6/18/98		Greg		Added IShMenuUtilities (with only a few calls)

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

#ifndef __ISHUTILITIES__
#define __ISHUTILITIES__

#if CP_PRAGMA_ONCE
#pragma once
#endif

#include "IShSMP.h"
#include "IMCFile.h"
#include "MCCountedPtrArray.h"
#include "MCTextStyle.h"
#include "MCUIColor.h"
#include "MCVKeyDefines.h"
#include "MCFileType.h"
#include "MCErrorMessages.h"
#include "MCCoreTypes.h"
#include "MFTypes.h"


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

MCDEFINE_GUID_H(IID_IShUtilities);


MCDEFINE_GUID_H(IID_IShFileUtilities);
MCDEFINE_GUID_H(IID_IShFileFormatUtilities);
MCDEFINE_GUID_H(IID_IShFileStream);

MCDEFINE_GUID_H(IID_IShComponentUtilities);
MCDEFINE_GUID_H(IID_IShMenuUtilities); 

MCDEFINE_GUID_H(CLSID_StandardFileStream);
MCDEFINE_GUID_H(CLSID_StandardTokenStream);

MCDEFINE_GUID_H(IID_IShActionManager);
MCDEFINE_GUID_H(IID_IShAction);
MCDEFINE_GUID_H(IID_IShMouseAction);
MCDEFINE_GUID_H(IID_IShPartUtilities);
MCDEFINE_GUID_H(IID_IShResourceUtilities);

MCDEFINE_GUID_H(IID_IShPersonalityUtilities);
MCDEFINE_GUID_H(IID_IShDragAndDropUtilities);

MCDEFINE_GUID_H(IID_IShMouseUtilities);
MCDEFINE_GUID_H(IID_IShSoundUtilities);

MCDEFINE_GUID_H(IID_IShNetworkUtilities);

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

typedef void* BufferChunk;

struct IShView;
struct IShComponent;
struct IShParameterComponent;
struct IShTokenStream;
struct IMCGraphicContext;
struct IMFPart;
struct IMFResponder;
struct IMFDocument;
struct IMFDropCandidate;
struct IMFDropArea;
struct IMFMenu;
struct IMCFile;
struct IMCLargeFile;
struct IMCFontList;
struct IMCSocket;
struct IMFWindow;
struct IMFPerpetualMouse;
struct IMFBrowserDialog;
struct IShowBackBufferWindow;
struct TMCVersionNumber;
struct IMCAudioBuffer;
struct IMCAudioPlayer;
struct IExSound;
struct IShSoundProcessor;
struct IShTokenStream;

class  TMCRect;
class  TMCPoint;
class  TMCAsciiTranslationTable;
class  TMFMenuInfo;
class  TMCPixelBucket;
class  TMCCompatiblePixelBucket;
class  TMCUIImage;
class  TMCPlatformEvent;
class  TMCWindowInfo;
class  TMCModifiers;
class  TMCCommandBindingGroup;
class  TComponentClass;
class  TMCRGBColor;
class  TMCResource;
class  TMCOffscreen;
class  TMFTabletMouseSample;

#if MAC
struct FSSpec;
#endif

/*****************************************************************************\
*  IShUtilities                                                               *
*                                                                             *
*    Misc. OS utilities provided by the shell.                                *
*                                                                             *
\*****************************************************************************/

/// \addtogroup Utilities
/// \{


// Alert type. Used for IShUtilities::DoAlert()
enum EAlerts
{
	kShNotificationAlert,
	kShCautionAlert,
	kShStopAlert
};

enum EAlertButtons
{
	kOneButton,
	kTwoButtons,
	kThreeButtons,
	kCustomButtons
};




/// General utilities.
struct IShUtilities: public IMCUnknown
{
public:
	// ****************************************************************************
	//								BeginProgress
	// 
	/// Progress bar support function.  Begins a new progress bar (you can have more than one displayed at a time).
	/// BeginProgress returns a progress key which is passed to the other progress bar functions to identify which 
	/// progress bar we're modifying.
	/// \see EndProgress, SetProgressPrompt, IncrementProgress, SetProgressValue, SetProgressValue0to1
	/// 
	/// \param prompt          Title string for this bar
	/// \param outProgressKey  Returns a progress key to be passed to other progress bar functions
	/// \param inMaxValue      Max value for the progress (ie when the progress value reaches this value, the bar is filled)
	/// 
	virtual void 	 	MCCOMAPI BeginProgress				(const TMCString& prompt, IMCUnknown** outProgressKey, real32 inMaxValue = 100.0f) = 0;
	

	// ****************************************************************************
	//								SetProgressDelay
	// 
	/// Sets the time that the progress will wait before being displayed
	/// 
	/// \param seconds			The time to wait before displaying the progress bar on the screen.
	/// \param inProgressKey	The key that identify the progress bar.
	/// 
	virtual void		MCCOMAPI SetProgressDelay(const real seconds,IMCUnknown* inProgressKey)=0;

	// ****************************************************************************
	//								EndProgress
	// 
	/// Progress bar support function.  Ends a progress bar.  
	///
	/// \see BeginProgress, SetProgressPrompt, IncrementProgress, SetProgressValue, SetProgressValue0to1
	/// \param inProgressKey  Pointer to the progress key associated with the progress bar to end.  If NULL, ends the first progress bar.
	/// 
	virtual void 		MCCOMAPI EndProgress				(IMCUnknown* inProgressKey) = 0;
	
	// ****************************************************************************
	//								SetProgressPrompt
	// 
	/// Progress bar support function.  Sets the progress bar's title prompt.  You can use this if you 
	/// want to alter the prompt midway through the progress bar process.
	/// 
	/// \see EndProgress, BeginProgress, IncrementProgress, SetProgressValue, SetProgressValue0to1
	/// \param inPrompt      Title string for this bar
	/// \param inProgressKey Pointer to the progress key associated with the progress bar to adjust.  If NULL, applies to the first progress bar.
	/// 
	virtual void 		MCCOMAPI SetProgressPrompt			(TMCString& inPrompt, 	IMCUnknown* inProgressKey = NULL) = 0;

	// ****************************************************************************
	//								IncrementProgress
	// 
	/// Progress bar support function.  Increments the progress bar by inIncrement.
	/// \see EndProgress, SetProgressPrompt, BeginProgress, SetProgressValue, SetProgressValue0to1
	/// 
	/// \param inIncrement    Increment to add to the progress value.
	/// \param inProgressKey  Pointer to the progress key associated with the progress bar to adjust.  If NULL, applies to the first progress bar.
	/// 
	virtual void		MCCOMAPI IncrementProgress			(real32 inIncrement, 	IMCUnknown* inProgressKey = NULL) = 0;
	
	// ****************************************************************************
	//								SetProgressValue
	// 
	/// Progress bar support function.  Sets the progress value to inValue.
	/// 
	/// \see EndProgress, SetProgressPrompt, IncrementProgress, BeginProgress, SetProgressValue0to1
	/// \param inValue        Value to set the progress value to
	/// \param inProgressKey  Pointer to the progress key associated with the progress bar to adjust.  If NULL, applies to the first progress bar.
	/// 
	virtual void		MCCOMAPI SetProgressValue			(real32 inValue, 		IMCUnknown* inProgressKey = NULL) = 0;

	// ****************************************************************************
	//								SetProgressValue0to1
	// 
	/// Progress bar support function.  Sets the progress value to a fraction of its maximum value determined by inValue.
	/// Sets the value of the progress bar to inValue * max value.
	/// \see EndProgress, SetProgressPrompt, IncrementProgress, SetProgressValue, BeginProgress
	/// 
	/// \param inValue        Value to set the progress value to
	/// \param inProgressKey  Pointer to the progress key associated with the progress bar to adjust.  If NULL, applies to the first progress bar.
	/// 
	virtual void		MCCOMAPI SetProgressValue0to1		(real32 inValue, 		IMCUnknown* inProgressKey = NULL) = 0;
	

	// ****************************************************************************
	//								TickCount
	// 
	/// \return The system Tick Count.
	/// 
	virtual uint32   MCCOMAPI TickCount					() = 0;

	// ****************************************************************************
	//								Random
	// 
	/// \return A pseudorandom number
	/// 
	virtual uint32	 MCCOMAPI Random					() = 0;
	
	// ****************************************************************************
	//								SetRandomSeed
	// 
	/// Sets the random number seed.
	/// 
	/// \param newSeed  Seed to use for random number generation.
	/// 
	virtual MCCOMErr MCCOMAPI SetRandomSeed				(uint32 newSeed) = 0;  
	
	// ****************************************************************************
	//								RandomStep
	// 
	/// Given a previous pseudorandom number, generates the next one.
	/// 
	/// \param before  The number at which to start the random number generation process.
	/// 
	virtual int32	 MCCOMAPI RandomStep				(int32 before) = 0;  

	// ****************************************************************************
	//								RandomStep
	// 
	/// Given a previous pseudorandom number, generates the steps-th one.
	/// 
	/// \param before  The number at which to start the random number generation process.
	/// \param steps   The number of steps to do.
	/// 
	virtual int32	 MCCOMAPI RandomSteps				(int32 before, int32 steps) = 0;  

	// ****************************************************************************
	//								GetAPINumber
	// 
	/// Returns the API version.
	/// 
	/// 
	virtual uint32	 MCCOMAPI GetAPINumber				() = 0;	
	
	// ****************************************************************************
	//								Gestalt
	// 
	/// Unlikely to need to use this.  Returns state information corresponding to an ID code.
	/// 
	/// \param data  
	/// \param id    
	/// 
	virtual MCCOMErr MCCOMAPI Gestalt					(void* data,uint32 id) = 0;
	
	// ****************************************************************************
	//								DoAlert
	// 
	/// Opens a basic alert box.  Use this to post an alert and get a response from the user.  
	/// The strings button0, button1, and button2 are optional.  If they are empty strings, 
	/// default values will be used.  If buttonCount == 1, "OK".  If buttonCount == 2, "OK  Cancel",
	/// and if buttonCount == 3, "Yes  No  Cancel".
	///
	/// <B>This function is thread safe.</B> (it can be called from a preemptive thread)
	/// 
	/// \param alertSeverity  Alert severity icon.  See EAlerts
	/// \param mainMessage    Main message to display
	/// \param arg0           Substitution string.  Any "^0" in mainMessage will be replaced by this
	/// \param arg1           Substitution string.  Any "^1" in mainMessage will be replaced by this
	/// \param arg2           Substitution string.  Any "^2" in mainMessage will be replaced by this
	/// \param buttonsCount   Number of buttons (1, 2, or 3)
	/// \param button0        Text for default button
	/// \param button1        Text for second button
	/// \param button2        Text for third button
	/// \return The value of the button hit (0, 1, or 2)
	/// 
	virtual int16	 MCCOMAPI DoAlert					(EAlerts alertSeverity,
														 const TMCString& mainMessage,
														 const TMCString& arg0, 
														 const TMCString& arg1,
														 const TMCString& arg2,
														 int32 buttonsCount,
														 const TMCString& button0,
														 const TMCString& button1,
														 const TMCString& button2
														) = 0;

	// ****************************************************************************
	//								ErrorToString
	// 
	/// Translates from a MCCOMErr value to a text string.
	/// 
	/// \param inErr           The error value to convert
	/// \param outErrorString  Returns the text string for that error
	/// 
	virtual MCCOMErr MCCOMAPI ErrorToString				(MCCOMErr inErr, TMCString& outErrorString) = 0;

	// ****************************************************************************
	//								BuildAlertMessage
	// 
	/// Constructs an alert message for display to the user, including the context
	/// for where the alert occurred.
	/// 
	/// \param inErr       Error value to convert
	/// \param inContext   String giving alert context
	/// \param outMessage  Returns the output message
	/// 
	virtual void	 MCCOMAPI BuildAlertMessage			(MCCOMErr inErr, 
														 const TMCString& inContext, 
														 TMCString& outMessage) = 0;

	// Opens a modal dialog based on a View resource and a PMap resource. 
	// IMPORTANT: The top view must be a TWindow with a Class Name of 'TStdPMAPWindow'.
	// The value returned is the ID of the item that dismissed the dialog.

/*	virtual int32	 MCCOMAPI DoDialog						(int16 viewAndPMapID,	// ID of the View and PMap resources
															 void* dataBuffer,		// Data buffer used to communicate with the dialog. Works like IExDataExchanger: the PMap resource describes the format of the Data Buffer
															 void (*onMessageCallBack)(int32 messageID, int32 sourceID, TMCPlatformEvent* event, IShView* topWindow, void* privData), // This call-back will be called everytime an event occur, so your code can react. Can be NULL.
															 void* privData) = 0;	// Callback's private data */

	
	// ****************************************************************************
	//								RestoreResources
	// 
	///  Deprecated.
	///  \see CWhileInCompResFile
	///
	virtual MCCOMErr MCCOMAPI RestoreResources				(void* oldResources) = 0;
	
	// ****************************************************************************
	//								BlitUIImage
	// 
	/// Blits an image stored in a UImg resource to a graphics context.  
	/// 
	/// \param inGraphicContext  The graphics context in which to blit the image
	/// \param inRect            TMCRect coordinates of where to blit the image
	/// \param inUpdateBBox      Clipping bounds for where to update the screen (if this doesn't intersect inRect, this function does nothing)
	/// \param inResourceID      Resource ID of the image to blit
	/// 
	virtual MCCOMErr MCCOMAPI BlitUIImage					(IMCGraphicContext* inGraphicContext, const TMCRect& inRect, const TMCRect& inUpdateBBox, uint32 inResourceID) = 0;
	
	// ****************************************************************************
	//								GetUIImageInfo
	// 
	/// Gets information about the UImg resource at a given ID.  Useful for sizing pixel buckets, etc.
	/// 
	/// \param inResourceID  ID of the resource to query
	/// \param width         Returns the width of the image resource
	/// \param height        Returns the height of the image resource
	/// \param planes        Returns the number of planes in the resource
	/// 
	virtual MCCOMErr MCCOMAPI GetUIImageInfo				(uint32 inResourceID, int32& width, int32& height, int32& planes) = 0;
	
	// ****************************************************************************
	//								GetUIImageBucket
	// 
	/// Blits the UI Image directly into a pixel bucket.  The bucket must be allocated before calling this function, so you should use 
	/// GetUIImageInfo() to figure out how large the bucket needs to be, and then allocate it with CreateCompatiblePixelBucket().
	/// 
	/// \param inResourceID  Resource ID of the image to get.
	/// \param bucket        Pointer to the pixel bucket in which to place the image.
	/// 
	virtual MCCOMErr MCCOMAPI GetUIImageBucket				(uint32 inResourceID, TMCPixelBucket* bucket) = 0;
	
	// direcly get the TMCUIImage
	// ****************************************************************************
	//								GetUIImage
	// 
	/// Gets an image from a resource and places it in a TMCUIImage.
	/// 
	/// \param inResourceID  Resource ID of image to get
	/// \param outUiImage    Pass this the address of a TMCCountedPtr<TMCUIImage>, and it will be pointed to the output image.
	/// 
	virtual MCCOMErr MCCOMAPI GetUIImage					(uint32 inResourceID, TMCUIImage** outUiImage ) = 0;

	// ****************************************************************************
	//								CreateCompatiblePixelBucket
	// 
	/// Creates a pixel bucket of a specified size/depth.
	/// 
	/// \param widthParam   Width of pixel bucket to create
	/// \param heightParam  Height of pixel bucket to create
	/// \param depthParam   Depth of pixel bucket to create
	/// \param outBucket    Pass this the address of a TMCCountedPtr<TMCCompatiblePixelBucket> and it will be pointed to the output bucket.
	/// 
	virtual MCCOMErr MCCOMAPI CreateCompatiblePixelBucket	(int32 widthParam,
															 int32 heightParam,
															 int32 depthParam,
															 TMCCompatiblePixelBucket** outBucket) = 0;

	// ****************************************************************************
	//								DestroyCompatiblePixelBucket
	// 
	/// Destroys a passed-in TMCCompatiblePixelBucket, and frees the memory used by the bucket's Offscreen.
	/// 
	/// \param outBucket  Pointer to bucket to be destroyed.
	/// 
	virtual MCCOMErr MCCOMAPI DestroyCompatiblePixelBucket	(TMCCompatiblePixelBucket* outBucket) = 0;

	// ****************************************************************************
	//								GetAsciiTranslationTable
	// 
	/// Returns the global ASCII translation table.  
	/// \see TMCAsciiTranslationTable
	/// \return A pointer to the translation table object
	///
	virtual TMCAsciiTranslationTable* MCCOMAPI GetAsciiTranslationTable() = 0;	
	
	// ****************************************************************************
	//								GetOpenDocumentsCount
	// 
	/// \return The number of open documents in the application.
	/// 
	virtual uint32	 MCCOMAPI GetOpenDocumentsCount			() = 0;
	
	// ****************************************************************************
	//								GetOpenDocumentByIndex
	// 
	/// 
	/// 
	/// \param document  Pass this the address of a TMCCountedPtr<IMFDocument> and it will be pointed to the document at the specified index
	/// \param index     Index of the document to get
	/// 
	virtual MCCOMErr MCCOMAPI GetOpenDocumentByIndex		(IMFDocument** document, uint32 index) = 0;
	
	// ****************************************************************************
	//								GetLastOpenDocPath
	// 
	/// Gets the file path of the last opened document.  This returns the full path including the filename.
	/// 
	/// \param path  Returns the path to the last opened document.
	/// 
	virtual void	 MCCOMAPI GetLastOpenDocPath			(TMCString& path)		= 0;
	
	// ****************************************************************************
	//								GetLastSaveDocPath
	// 
	/// Gets the file path of the last saved document.  This returns the full path including the filename.
	/// 
	/// \param path  Returns the path to the last saved document.
	/// 
	virtual void	 MCCOMAPI GetLastSaveDocPath			(TMCString& path)		= 0;
	
	// ****************************************************************************
	//								SetLastOpenDocPath
	// 
	/// Sets the file path of the last opened document.  Use this if you open a document, to make sure that GetLastOpenDocPath() calls
	/// correctly return the path to the document you opened.
	/// 
	/// \param path  The path to the last opened document
	/// 
	virtual void	 MCCOMAPI SetLastOpenDocPath			(const TMCString& path) = 0;

	// ****************************************************************************
	//								SetLastSaveDocPath
	// 
	/// Sets the file path of the last saved document.  Use this if you save a document, to make sure that GetLastSaveDocPath() calls
	/// correctly return the path to the document you saved.
	/// 
	/// \param path  The path to the last saved document
	/// 
	virtual void	 MCCOMAPI SetLastSaveDocPath			(const TMCString& path) = 0;

	// MMX Stuff
#if WIN
	// ****************************************************************************
	//								UseMMX
	// 
	/// \return True if this processor supports MMX, and if we want to use it.
	/// 
	/// 
	virtual boolean MCCOMAPI	UseMMX						() = 0;
	
	// ****************************************************************************
	//								IsPentiumProcessor
	// 
	/// \return True if this processor is in the Pentium family (Pentium, Pentium Pro, PentiumII, Pentium III...)
	/// 
	virtual boolean MCCOMAPI	IsPentiumProcessor			() = 0;
	
	// ****************************************************************************
	//								IsPentiumIIProcessor
	// 
	/// \return True if this processor is a Pentium II
	/// 
	/// 
	virtual boolean MCCOMAPI	IsPentiumIIProcessor		() = 0;   // return true if the processor is a PII
	
	// ****************************************************************************
	//								IsPentiumIIIProcessor
	// 
	/// \return True if this processor is a Pentium III
	/// 
	/// 
	virtual boolean MCCOMAPI	IsPentiumIIIProcessor		() = 0;	  // return true if the processor is a PIII
#endif

//	virtual void* GetStackLists() = 0;
//	
	// ****************************************************************************
	//								StringWidth
	// 
	/// Utility to calculate the width in pixels of a string in a given text style.  Useful for 
	/// calculating formatting for text you need to display dynamically.
	/// 
	/// \param inStyle   A TMCTextStyle to use for width calculations
	/// \param inString  The string whose screen width we want to find
	/// \return The pixel width of the string
	///
	virtual int16	 MCCOMAPI StringWidth					(const TMCTextStyle& inStyle, const TMCString& inString) = 0;
	
	// ****************************************************************************
	//								GetTextMetrics
	// 
	/// Returns the font metrics associated with a given TMCTextStyle.
	/// 
	/// \param inStyle     The text style to query
	/// \param outMetrics  Returns the TMCTextMetrics associated with the given style
	/// 
	virtual void 	 MCCOMAPI GetTextMetrics				(const TMCTextStyle& inStyle, TMCTextMetrics& outMetrics) = 0;

	// ****************************************************************************
	//								GetCreator
	// 
	/// Deprecated.
	/// 
	virtual IDType	 MCCOMAPI GetCreator					() = 0;

	// ****************************************************************************
	//								SetCursor
	// 
	/// Sets the mouse cursor.  See MCCursorTypes.h
	/// 
	/// \param cursorId  ID of the cursor to set
	/// 
	virtual void	 MCCOMAPI SetCursor						(int32 cursorId) = 0;

	// ****************************************************************************
	//								GetFontList
	// 
	/// Accessor for the Font list.
	/// 
	/// \param outFontList  Pass this a TMCCountedPtr<IMCFontList> and it will be pointed to the font list.
	/// 
	virtual void	 MCCOMAPI GetFontList					(IMCFontList** outFontList) = 0;

	// ****************************************************************************
	//								CheckForUserCancel
	// 
	/// Checks the application's message queue for a user cancel request.  This should be called within time-consuming operations to
	/// make sure that the operation can be cancelled if the user hits the escape key.
	/// 
	/// \return True if the user has requested a cancel.
	virtual boolean	 MCCOMAPI CheckForUserCancel() = 0;

	
	// ****************************************************************************
	//								GetCurrentModifiers
	// 
	/// Returns the state of the keyboard modifiers.  (Things like "shift key down" and "ctrl key down".)  
	/// This is generally used to enable different behaviors of mouse clicks or other keypresses.  
	/// \return TMCModifiers& describing the various modifiers currently active
	/// 
	virtual const TMCModifiers&	 MCCOMAPI GetCurrentModifiers() = 0;
	
	// ****************************************************************************
	//								CheckKeyDown
	// 
	/// Checks to see if a given key is currently down.
	/// 
	/// \param inVirtualKey  Pass this the key code for the key you wish to check 
	/// \return True if the key is currently pressed
	///
	virtual boolean	 MCCOMAPI CheckKeyDown(int16 inVirtualKey) = 0;

	// ****************************************************************************
	//								WerePrefsBad
	// 
	/// \return True if the application had to rebuild the prefs file on startup.   
	/// 
	virtual boolean	 MCCOMAPI WerePrefsBad() = 0;

	// ****************************************************************************
	//								Alert
	// 
	/// Pops up an alert message with a 'skip from now on' checkbox.
	/// This function is thread safe.
	/// \see DoAlert()
	/// 
	/// \param inAlertType  An EAlertButtons that tells the function how many buttons to display (1, 2, or 3).
	/// \param message      The message to display to the user.
	/// \param doSkip       Pass this false to display the alert, or true to skip.  Returns a boolean corresponding to the state of the "skip from now on" checkbox.  Use to avoid future alerts of this type.
	/// \return 0 - kAlert_Okay, 1 - kAlert_Cancel, 2 - kAlert_Other.
	///
	virtual int16	 MCCOMAPI Alert					(EAlertButtons		inAlertType,
													const TMCString&	message,
													boolean&			doSkip)=0;

    // ****************************************************************************
	//								CustomizedAlertWithSkip
	// 
	/// Pops up an alert message with a 'skip from now on' checkbox.
    /// The number of displayed buttons would be equal to the number of button texts not empty.
	/// This function is thread safe.
	/// \see DoAlert()
	/// 
    /// \param message      The message to display to the user.
    /// \param[in] button0  Text for default button
	/// \param[in] button1  Text for second button
	/// \param[in] button2  Text for third button
	/// \param doSkip       Pass this false to display the alert, or true to skip.  Returns a boolean corresponding to the state of the "skip from now on" checkbox.  Use to avoid future alerts of this type.
	/// \return The value of the button hit (0, 1, or 2)
	///
	virtual int16	 MCCOMAPI CustomizedAlertWithSkip  (const TMCString& message,
                                                        const TMCString& button0,
                                                        const TMCString& button1,
                                                        const TMCString& button2,
                                                        boolean&  doSkip)=0;
    
	// ****************************************************************************
	//								BlitTMCUIImage
	// 
	/// Blits an image in a graphics context.
	/// 
	/// \param inGraphicContext  The graphics context in which to blit the image
	/// \param inRect            TMCRect coordinates of where to blit the image
	/// \param inUpdateBBox      Clipping bounds for where to update the screen (if this doesn't intersect inRect, this function does nothing)
	/// \param image             Pointer to the TMCUIImage to blit
	/// 
	virtual void	MCCOMAPI BlitTMCUIImage( IMCGraphicContext* inGraphicContext, TMCRect& inRect, const TMCRect& inUpdateBBox, TMCUIImage* image) = 0;

	// ****************************************************************************
	//								CreateBrowserDialog
	// 
	/// Creates a browser dialog.  Do not forget to call CallPrepareToDestroy before
	/// you release the dialog.
	/// 
	/// \param browserDialog  Returns a pointer to the new browser dialog.
	/// 
	virtual void	MCCOMAPI CreateBrowserDialog(IMFBrowserDialog** browserDialog)=0;

	// ****************************************************************************
	//								WriteComponentToBrowserFile
	// 
	/// Writes a component to a browser file.
	/// 
	/// \param component  A pointer to the component to write
	/// \param file       A pointer to the file where the component will be saved
	/// \param preview	  An optional pointer to a bucket to use as a preview
	/// \see LoadComponentFromBrowserFile
	///
	virtual void	MCCOMAPI WriteComponentToBrowserFile(IShComponent* component, IMCFile* file, const TMCPixelBucket* preview=NULL)=0;

	// ****************************************************************************
	//								LoadComponentFromBrowserFile
	// 
	/// Loads a component from a browser file
	/// \see WriteComponentToBrowserFile
	/// \param component          Returns a pointer to the component loaded
	/// \param componentFamilyID  ID of the component family being loaded
	/// \param file               A pointer to the file from which the component will be loaded
	///	 \return MC_S_OK if the file contained the right type of component
	///
	virtual MCCOMErr MCCOMAPI LoadComponentFromBrowserFile(IShComponent** component,const IDType componentFamilyID,IMCFile* file)=0;

	// ****************************************************************************
	//								LoadComponentDataFromBrowserFile
	// 
	/// Loads a component's data from a browser file.  (The file must of course have been
	/// created from the same class as the component passed.)
	/// 
	/// \param component  A pointer to the component whose data you'd like to load
	/// \param file       A pointer to the file where the component is stored.
	/// \return MC_S_OK If the file contained the right type of component.
	///
	virtual MCCOMErr MCCOMAPI LoadComponentDataFromBrowserFile(IShComponent* component,IMCFile* file)=0;
	
	// ****************************************************************************
	//								EventLoop
	// 
	/// Creates a local event loop.
	/// 
	/// \param isDone  a reference to the flag that ends the loop when it goes to true
	/// 
	virtual void	 MCCOMAPI EventLoop( boolean& isDone ) = 0;

	// ****************************************************************************
	//								CreateAAGraphicContext
	// 
	/// Creates an antialiased graphics context
	/// 
	/// \param inOffscreen  The offscreen used by the graphics context
	/// \param gc           Returns a pointer to the graphics context
	/// 
	virtual void	 MCCOMAPI CreateAAGraphicContext(TMCOffscreen& inOffscreen, IMCGraphicContext** gc) = 0;

	// ****************************************************************************
	//								QuitApplication
	// 
	/// Posts an action to quit the application.
	/// 
	virtual void	 MCCOMAPI QuitApplication() = 0;

	// ****************************************************************************
	//								GetVersion
	// 
	/// Returns the current version number of the application
	/// 
	/// \param outVersionNumber  Returns the version number
	/// 
	virtual void	 MCCOMAPI GetVersion(TMCVersionNumber& outVersionNumber) =0;

	// ****************************************************************************
	//								GetApplicationFullName
	// 
	/// Returns the full name of the application (ex: Carrara 4 Pro)
	/// 
	/// \param string  Returns the application name
	/// 
	virtual void	 MCCOMAPI GetApplicationFullName(TMCString& string)=0;


	// ****************************************************************************
	//								GetErrorMessage
	// 
	/// Internal use only. Use ::GetErrorMessage() instead (See MCErrorMessages.h)
	///
	virtual const TMCString* MCCOMAPI GetErrorMessage(EMCErrorCode errorCode)=0;
	
		// ****************************************************************************
	//								StoreSecretInfo
	// 
	/// Returns true if the info was written.
	/// 
	virtual boolean	MCCOMAPI StoreSecretInfo(const TMCString& fileName, 
											 const TMCString& infoName, 
											 const TMCArray<uint8>& data,
											 boolean silent) = 0;

	// ****************************************************************************
	//								GetSecretInfo
	// 
	/// Returns true if the info could be read.
	/// 
	virtual boolean	MCCOMAPI GetSecretInfo(	const TMCString& fileName, 
											const TMCString& infoName, 
											TMCArray<uint8>& data) = 0;
												
	// ****************************************************************************
	//								GetStandardPath
	// 
	/// Returns the component class of a component (Very rarely used)
	/// 
	///	\param inStandardPathID id of the path you need (see EStandardPathID)
	///	\param outPath			The (platform) full path of the folder corresponding to inStandardPathID
	/// 
	virtual void MCCOMAPI GetStandardPath(const EStandardPathID&	inStandardPathID,TMCDynamicString& outPath) = 0;


	// ****************************************************************************
	//								IsAnyMenuActive
	// 
	/// Returns true if a menu is active
	/// 
	virtual boolean MCCOMAPI IsAnyMenuActive() = 0;


	// ****************************************************************************
	//								GetFileForCurrentLanguage
	// 
	/// Modify the given file to point to the correct file for the current language.
	///
	///	\param file					The file that need to be modify.
	/// \param checkIfFileExists	If true, the function will check if the file corresponding to
	///								the current language actually exists.
	/// \param addSpace				If true, adds a space between the file name and the language id
	/// 
	virtual void	MCCOMAPI GetFileForCurrentLanguage(IMCFile* file, boolean checkIfFileExists = true, boolean addSpace = false) = 0;

		// ****************************************************************************
	//								DoAlertAsync
	// 
	/// Opens a basic alert box to display a message. You will not be able to any return
	//  value from the user. The action will be posted but will be executed later.
	/// <B>This function is thread safe.</B> (it can be called from a preemptive thread)
	/// \see DoAlert()
	/// \see Alert()
	/// 
	/// \param alertSeverity  Alert severity icon.  See EAlerts
	/// \param mainMessage    Main message to display
	/// \param arg0           Substitution string.  Any "^0" in mainMessage will be replaced by this
	/// \param arg1           Substitution string.  Any "^1" in mainMessage will be replaced by this
	/// \param arg2           Substitution string.  Any "^2" in mainMessage will be replaced by this
	/// 
	virtual void	MCCOMAPI DoAlertAsync				(EAlerts alertSeverity,
														 const TMCString& mainMessage,
														 const TMCString& arg0, 
														 const TMCString& arg1,
														 const TMCString& arg2) = 0;

	/// Returns the number of keys that are pressed
	virtual int32	MCCOMAPI	CountKeysDown		() = 0;

	// ****************************************************************************
	//								ApplicationStillRunning
	// 
	/// This function must be called at least every 5 seconds on Windows to avoid
	/// the not responding message to show up. Note that this is called by CheckForUserCancel
	/// as well as calls that update the progress bars.
	/// 
	virtual void MCCOMAPI ApplicationStillRunning()=0;
};

/// \}
/*****************************************************************************\
*  IShFileFormatUtilities                                                     *
*                                                                             *
*    File format utilities provided by the shell                              *
*                                                                             *
\*****************************************************************************/

/// Used to pass around ID/name pairs
struct APITypeAndName : public TMCObject
{
	IDType fID;
	TMCString31 fName;
};


/// \addtogroup Utilities
///
/// \{
struct IShNetworkUtilities: public IMCUnknown
{
	// ****************************************************************************
	//								InitializeSockets
	// 
	/// Initialize the sockets
	/// 
	virtual void MCCOMAPI InitializeSockets() = 0;

	virtual void MCCOMAPI CreateSocket(IMCSocket** socket) = 0;

	virtual int32 MCCOMAPI CheckForRead(const TMCCountedPtrArray<IMCSocket>& socketList,real timeOutInSeconds) = 0;
};
/// \}


/// \addtogroup Utilities
///
/// \{

/// Utilities for handling file formats.  Includes file open/save dialog boxes, file format families and lists.
struct IShFileFormatUtilities: public IMCUnknown
{
public:

	// ****************************************************************************
	//								RegisterFileFamily
	// 
	/// Registers a new file family
	/// 
	/// \param inFamily        ID type of the family to register (ie 'imag')
	/// \param fileFamilyName  String with the name of the file family (ie "Image Files")
	/// 
	virtual MCCOMErr MCCOMAPI RegisterFileFamily (IDType inFamily, const TMCString& fileFamilyName) =0;

	// ****************************************************************************
	//								GetFileFamilies
	// 
	// -Description:
	//
	// Returns the list of available file family
	// 
	// -Parameters:
	//
	// outFamilies		: the list of all the file formats families ('imag' for image files, ...)
	// inForOpen		: not used at this point
	//
	// ****************************************************************************
	//								GetFileFamilies
	// 
	/// Returns the list of available file families
	/// 
	/// \param outFamilies  Returns the list
	/// \param inForOpen    
	/// 
	virtual MCCOMErr MCCOMAPI GetFileFamilies	(TMCArray<APITypeAndName> & outFamilies, boolean inForOpen) = 0;
	
	// ****************************************************************************
	//								GetFileTypes
	// 
	/// Returns a list of file API types and names
	/// 
	/// \param outFileTypes  Returns the list of file types in the specified family
	/// \param inFamily      The family of file types to get.  (0 for all available families)  Call GetFileFamilies() for a list of available file families.
	/// \param inForOpen     Not used at this time.
	/// 
	virtual MCCOMErr MCCOMAPI GetFileTypes		(TMCArray<APITypeAndName> & outFileTypes, IDType inFamily, boolean inForOpen) = 0;

	// ****************************************************************************
	//								GetFileTypes
	// 
	/// Returns a list of file type IDs
	/// 
	/// \param outFileTypes  Returns the list of file types in the specified family
	/// \param inFamily      The family of file types to get.  (0 for all available families)  Call GetFileFamilies() for a list of available file families.
	/// \param inForOpen     Not used at this time.
	/// 
	virtual MCCOMErr MCCOMAPI GetFileTypes		(TMCArray<IDType> & outFileTypes, IDType inFamily, boolean inForOpen) = 0;	
													 
	// ****************************************************************************
	//								AddFileType
	// 
	/// Adds a new file type to the list of types the application handles
	/// 
	/// \param inFileType  The file type to add.
	/// 
	virtual void	 MCCOMAPI AddFileType		(const TMCFileType& inFileType) = 0;

	// ****************************************************************************
	//								AddFileTypes
	// 
	/// Adds a a list of file types to the list of types the application handles.
	/// Note: Use LoadResourceFTYP() to load your type list.
	/// 
	/// \param inTypesList  The list of file types to add.
	/// 
	virtual void	 MCCOMAPI AddFileTypes		(const TMCFileTypeList& inTypesList) = 0;

	// -Description:
	//		Loads a FTYP resource
	// -Parameters:
	//		inCompFamilyID and inCompClassID: the id of a component to use to setup the right resoure context
	//		inResID: the ID of the FTYP resource to load
	//		inFileFamily: the id of the family of those files types (0 is ok)
	// ****************************************************************************
	//								LoadResourceFTYP
	// 
	/// Loads a FTYP resource into a TMCFileTypeList.
	/// 
	/// \param inCompFamilyID  ID of the component family owning the FTYP resource
	/// \param inCompClassID   ID of the component class owning the FTYP resource
	/// \param inResID         Resource ID of the FTYP to load
	/// \param inFileFamily    ID of the file family to load
	/// \param outTypeList     Returns the list of file types in the family
	/// 
	virtual void	 MCCOMAPI LoadResourceFTYP(	IDType 				inCompFamilyID,
												IDType 				inCompClassID,
												ResourceID			inResID,
												MCTypeFamilyID		inFileFamily,
												TMCFileTypeList&	outTypeList) = 0;

	// ****************************************************************************
	//								OpenFileDialog
	// 
	/// Opens a system folder-open dialog and returns the file selected by the user.  
	/// 
	/// \param inTitle              The title of the dialog box that will be opened
	/// \param file                 Pointer to the folder selected by the user
	/// 
	virtual MCCOMErr MCCOMAPI OpenFolderDialog	(const TMCString & inTitle, IMCFile * file) = 0;

	// ****************************************************************************
	//								OpenFileDialog
	// 
	/// Opens a system file-open dialog and returns the file selected by the user.  
	/// Note that the file types can be '****' for all files, a file family ID (ie 'imag'), or a file type ID (ie 'JPEG')
	/// \see IShFileFormatUtilities::GetFileTypes()
	/// 
	/// \param inTitle              The title of the dialog box that will be opened
	/// \param file                 Pointer to the file selected by the user
	/// \param inFileTypes          An array of file types that will be selectable.
	/// \param inOutPopupSelection  The file type selected by the user. On entry, it can contain '****'
	///                             for all files, the family ID (for instance 'imag') for FileTypeFamily to be used or
	///								the ID of the FileType to be used
	/// \param outFormat            The type of the file selected by the user
	/// 
	virtual MCCOMErr MCCOMAPI OpenFileDialog	(const TMCString & inTitle, IMCFile * file, TMCArray<IDType> &inFileTypes, IDType& inOutPopupSelection, IDType & outFormat) = 0;

	// ****************************************************************************
	//								SaveFileDialog
	// 
	/// Opens a system file-save dialog and returns the file and format selected by the user.
	/// Note that the file types can be '****' for all files, a file family ID (ie 'imag'), or a file type ID (ie 'JPEG')
	/// \see IShFileFormatUtilities::GetFileTypes()
	/// 
	/// \param inTitle      The title of the dialog box that will be opened
	/// \param file         Pointer to the file selected by the user
	/// \param inFileTypes  An array of file types that will be selectable.
	/// \param inOutFormat  Default file format to present to the user.  This parameter will return the file format actually chosen by the user.
	/// 
	virtual MCCOMErr MCCOMAPI SaveFileDialog	(const TMCString & inTitle, IMCFile * file, TMCArray<IDType> &inFileTypes, IDType & inOutFormat) = 0;

	// ****************************************************************************
	//								OpenDocument
	// 
	/// Given a file and file type ID, opens a document.
	/// 
	/// \param inFile       Pointer to the file containing the document to open
	/// \param fileType     File type ID of the file
	/// \param outDocument  Returns a pointer to the document opened.
	/// 
	virtual MCCOMErr MCCOMAPI OpenDocument		(const IMCFile* inFile, MCFileTypeID fileType, IMFDocument** outDocument) = 0;

	// ****************************************************************************
	//								GetMultipleFiles
	// 
	/// Gets a list of one or more file(s) by popping up a multiple file chooser system dialog.
	/// Note that the file types can be '****' for all files, a file family ID (ie 'imag'), or a file type ID (ie 'JPEG')
	/// \see IShFileFormatUtilities::GetFileTypes()
	/// 
	/// \param inPropmt             Prompt to display in the title of 
	/// \param startingPath         Pointer to an IMCFile providing the initial directory in which to start the dialog
	/// \param outFileList          An array of pointers to the selected files.
	/// \param inFileTypes          An array of types of files that should be selectable
	/// \param inOutPopupSelection  Default file format to present to the user.  This parameter will return the file format actually chosen by the user.
	/// 
	virtual MCCOMErr MCCOMAPI	GetMultipleFiles(
									const TMCString&				inPropmt,
									IMCFile*						startingPath,
									TMCCountedPtrArray<IMCFile>&	outFileList,
									TMCArray<IDType>&				inFileTypes,
									IDType&							inOutPopupSelection) = 0;


	// ****************************************************************************
	//								GetFileTypeByID
	// 
	/// Returns a pointer to a TMCFileType by the ID of the file type.
	/// 
	/// \param fileID  ID of a file type (See TMCFileType)
	/// \return A pointer to the file type if found, NULL if not.
	/// 
	virtual const TMCFileType* MCCOMAPI GetFileTypeByID(MCFileTypeID fileID) = 0;

	// ****************************************************************************
	//								GetFileTypesByFamilyID
	// 
	/// Returns a list of file types that match a given family
	/// 
	/// \param fileTypeList  Returns a list of file types
	/// \param familyID      The ID of the family to query
	/// 
	virtual void MCCOMAPI GetFileTypesByFamilyID(TMCFileTypeList& fileTypeList,MCTypeFamilyID familyID) = 0;

	// ****************************************************************************
	//								FindFile
	// 
	/// This function will try to relocate the file or in last resort ask the user
	/// to find it.
	/// 
	virtual boolean MCCOMAPI FindFile(IMCFile* outFile, TMCArray<IDType>& fileTypes, IDType& popupSelection) = 0;
};

/// \}

/// \addtogroup MCCore
///
/// \{

/// Structure that gives some information about a component class
///
struct TComponentClassInfo : public TMCObject
{
	IDType			fClassSignature;		///< The unique signature of the component class (eg 'schk')
	TMCString63		fSubFamilyName;			///< The name of the sub family or group it belongs to (eg "Pattern Shaders")
	TMCString63		fClassName;				///< The name of the component class (eg "Checker Shader")
	int16			fResID;					///< The ID for all the resources of the component class (COMP, PMap, GUID...)
	TMCResource*	fPrivateData;			///< Do NOT touch
	//int32		fPrivateDataLength;		///< Do NOT touch
};

/// \}


/// \addtogroup Utilities
/// \{

/// Utilities for handling components.  
struct IShComponentUtilities: public IMCUnknown
{
public:
	// ****************************************************************************
	//								CoCreateInstance
	// 
	/// Manually creates a component.  
	/// \code
	///TMCCountedPtr<I3DShInstance> instance;
	///gComponentUtilities->CoCreateInstance(CLSID_StandardInstance, NULL, MC_CLSCTX_INPROC_SERVER, IID_I3DShInstance, (void **) &instance);
	///instance->Set3DObject(masterObject);
	/// \endcode
	/// \param rclsid        Class ID of the component to create
	/// \param pUnkOuter     Pointer to the controlling Unknown object.  Used for COM aggregation - this is the object that maintains the refcount.
	/// \param dwClsContext  Pass MC_CLSCTX_INPROC_SERVER here.
	/// \param riid          Interface ID for the interface we want
	/// \param ppv           Points to the resulting interface of the component created
	/// 
	virtual MCCOMErr MCCOMAPI CoCreateInstance						(const MCCLSID& rclsid, IMCUnknown* pUnkOuter, uint32 dwClsContext, const MCIID& riid, void** ppv) = 0;	

	// ****************************************************************************
	//								CreateComponent
	// 
	/// Creates the most recent version of a component by family ID and class ID.
	/// 
	/// \param familyID   Family ID of the component to create
	/// \param classID    Class ID of the component to create
	/// \param component  Returns a pointer to the IShComponent interface of the component created.
	/// 
	virtual MCCOMErr MCCOMAPI CreateComponent						(IDType familyID, IDType classID, IShComponent** component) = 0;

	// ****************************************************************************
	//								CreateComponent
	// 
	/// Creates a specific version of a component by family ID and class ID
	/// 
	/// \param familyID   Family ID of the component to create
	/// \param classID    Class ID of the component to create
	/// \param version    Version number of the component to create
	/// \param component  Returns a pointer to the IShComponent interface of the component created
	/// 
	virtual MCCOMErr MCCOMAPI CreateComponent						(IDType familyID, IDType classID, int32 version, IShComponent** component) = 0;

	// ****************************************************************************
	//								CreateIUnknown
	// 
	/// This is similar to CoCreateInstance, but creates the component instances by family and class ID.  
	/// For example, CreateInstanceByID('gel ', 'blnd', &gel); creates a "blinds" gel.
	/// 
	/// \param familyID   Family ID of the component to create
	/// \param classID    Class ID of the component to create
	/// \param pUnkOuter  Pointer to the controlling Unknown object.  Used for COM aggregation - this is the object that maintains the refcount.
	/// \param component  Returns a pointer to the component created
	/// 
	virtual MCCOMErr MCCOMAPI CreateIUnknown						(IDType familyID, IDType classID, IMCUnknown* pUnkOuter, IMCUnknown** component) = 0;

	// ****************************************************************************
	//								CreateDefaultComponent
	// 
	/// Creates a default instance of a component family.
	/// 
	/// \param familyID   The family ID whose default component you want to create
	/// \param component  Returns a pointer to the component created
	/// 
	virtual MCCOMErr MCCOMAPI CreateDefaultComponent				(IDType familyID, IShComponent** component) = 0;

	// ****************************************************************************
	//								GetComponentClassInfoArrayByFamilyID
	// 
	/// Gets an array of TComponentClassInfo for the classes that are in a given family
	/// 
	/// \param familyID                 The family ID to query
	/// \param componentClassInfoArray  Returns the class information on the classes in the specified family
	/// \param includeHidden			Include hidden components.
	/// 
	virtual MCCOMErr MCCOMAPI GetComponentClassInfoArrayByFamilyID	(IDType familyID, TMCArray<TComponentClassInfo>& componentClassInfoArray, boolean includeHidden = false) = 0;

	// ****************************************************************************
	//								WriteComponent
	// 
	/// Writes a component to an IShTokenStream
	/// 
	/// \param stream     Pointer to the output stream
	/// \param component  Pointer to the component to write
	/// 
	virtual MCCOMErr MCCOMAPI WriteComponent						(IShTokenStream* stream, IShParameterComponent* component) = 0;
	
	// ****************************************************************************
	//								WriteComponent
	// 
	/// Writes a component to an IShTokenStream, with a keyword header
	/// 
	/// \param stream     Pointer to the output stream
	/// \param keyword    Keyword to write as header
	/// \param component  Pointer to the component to write
	/// 
	virtual MCCOMErr MCCOMAPI WriteComponent						(IShTokenStream* stream, IDType keyword, IShParameterComponent* component) = 0;
	
	// ****************************************************************************
	//								ReadComponent
	// 
	/// Reads a component from an IShTokenStream
	/// 
	/// \param stream     Pointer to the input stream
	/// \param component  Returns a pointer to the component read
	/// 
	virtual MCCOMErr MCCOMAPI ReadComponent							(IShTokenStream* stream, IShParameterComponent** component) = 0;
	
	// ****************************************************************************
	//								ReadComponent
	// 
	/// Reads a component from an IShTokenStream when its family ID keyword header has been read.
	/// 
	/// \param stream     Pointer to the input stream
	/// \param component  Returns a pointer to the component read
	/// \param familyID   Family ID read
	/// 
	virtual MCCOMErr MCCOMAPI ReadComponent							(IShTokenStream* stream, IShParameterComponent** component, IDType familyID) = 0; // same as the method above, to be used when the family token has already been read (the begin token is still in the stream).
	
	// ****************************************************************************
	//								ReadComponentData
	// 
	/// Reads a component's data from a TMCiostream.
	/// 
	/// \param stream     Pointer to the input stream
	/// \param component  Pointer to the component whose data we would like to read
	/// 
	virtual MCCOMErr MCCOMAPI ReadComponentData						(TMCiostream* stream,IShParameterComponent* component)=0;

	// ****************************************************************************
	//								AskForParams
	// 
	/// Allows a component to present a dialog box asking for values for its parameters.  Used, for example,
	/// when exporting a file, to present export options appropriate to the file format we're exporting to.
	/// 
	/// \param component  Pointer to the component to ask for its parameters
	/// 
	virtual boolean  MCCOMAPI AskForParams							(IShParameterComponent *component)=0;

	// ****************************************************************************
	//								StartFileReading
	// 
	/// Resets the component reading mechanism when you start reading a file.  Call it before you call RedComponent.
	///
	/// Note that it is called by the shell when starting to read a file, so you only
	/// need to call it if you initiate the reading of the file.
	/// 
	virtual MCCOMErr MCCOMAPI StartFileReading() = 0;


	// ****************************************************************************
	//								FinishFileReading
	// 
	// -Description:
	//
	// Reset the component reading mechanism when you finish reading 
	// a file. You should call it after you call ReadComponent.
	//
	// Note that it is called by the shell when finishing to read a file. So you only
	// need to call it if you initiate the reading of the file.
	// 
	virtual MCCOMErr MCCOMAPI FinishFileReading() = 0;

	// ****************************************************************************
	//								StartFileWriting
	// 
	/// Reset the component writing mechanism when you start writing a file.
	/// You should call it before you call WriteComponent.
	///
	/// Note that it is called by the shell when it starts to write a file, so you only
	/// need to call it if you initiate the writing of a the file.
	/// 
	virtual MCCOMErr MCCOMAPI StartFileWriting() = 0;

	// ****************************************************************************
	//								FinishFileWriting
	// 
	/// Resets the component writing mechanism when finished writing a file.
	/// You should call it before you call WriteComponent.
	/// 
	/// Note that this function is called by the shell when it is finishing writing to a file,
	/// so you only need to call it if you initiate the writing of the file.
	///
	virtual MCCOMErr MCCOMAPI FinishFileWriting() = 0;



	// ****************************************************************************
	//								GetComponentClass
	// 
	/// Returns the component class of a component (Very rarely used)
	/// 
	/// \param familyID  Family ID of the component
	/// \param classID   Class ID of the component
	/// 
	virtual TComponentClass* MCCOMAPI GetComponentClass(IDType familyID, IDType classID) = 0;
	// ****************************************************************************
	//								GetPrefComponent
	// 
	/// Returns the preference from the Preference DB 
	/// 
	/// \param classID   Class ID of the component
	/// 
    virtual IShParameterComponent* MCCOMAPI GetPrefComponent(IDType classID) const  = 0;
};


/*****************************************************************************\
*  IShMenuUtilities                                                           *
*                                                                             *
*    Menu utilities provided by the Shell                                     *
*                                                                             *
\*****************************************************************************/

/// Utilities for handling menus.
struct IShMenuUtilities: public IMCUnknown
{
public:

	// ****************************************************************************
	//								EnableCheckMenu
	// 
	/// Enables a menu action, and determines if the menu item should have a check next to it.
	/// 
	/// \param anAction  ID of the menu action whose menu entry we want to enable/disable and/or checkmark
	/// \param canDo     If true, the menu item will be enabled.
	/// \param checkIt   If true, the menu item will be checked.
	/// 
	virtual MCCOMErr MCCOMAPI EnableCheckMenu		(int32 anAction, boolean canDo, boolean checkIt) = 0;
	
	// ****************************************************************************
	//								EnableMenuAction
	// 
	/// Enables or disables a menu action
	/// 
	/// \param anAction  ID of the menu action whose menu entry we want to enable/disable
	/// \param canDo     If true, the menu item will be enabled.
	/// 
	virtual MCCOMErr MCCOMAPI EnableMenuAction		(int32 anAction, boolean canDo) = 0;
	
	// ****************************************************************************
	//								CreateMenu
	// 
	/// Creates a menu (which can be either a menu or a menu item).  
	/// 
	/// \param inInfo   the TMFMenuInfo information for the menu to create
	/// \param outMenu  Returns a pointer to the created menu
	/// 
	virtual MCCOMErr MCCOMAPI CreateMenu			(TMFMenuInfo& inInfo, IMFMenu** outMenu) = 0;
	
	// ****************************************************************************
	//								MenuActionToMenuItem
	// 
	/// Given a menu action number, returns the corresponding menu and item index
	/// 
	/// \param action  ID of the menu action whose menu entry we're looking for
	/// \param menu    Returns the menu number
	/// \param item    Returns the menu item number
	/// 
	virtual MCCOMErr MCCOMAPI MenuActionToMenuItem	(int32 action,int16& menu, int16& item) = 0;
	
	// ****************************************************************************
	//								MenuActionFromMenuItem
	// 
	/// Given a menu number and item number, returns the corresponding menu action ID.
	/// 
	/// \param commandName  Menu number to query
	/// \param item         Item number to query
	/// \return The menu action ID corresponding to commandName and item
	/// 
	virtual	int32	 MCCOMAPI MenuActionFromMenuItem(int16 commandName, int16 item) = 0;

	// ****************************************************************************
	//								DeleteMenuItem
	// 
	/// Removes a menu item.
	/// 
	/// \param menu  Menu number to remove
	/// \param item  Menu item number to remove
	/// 
	virtual MCCOMErr MCCOMAPI DeleteMenuItem		(int16 menu, int16 item) = 0;
	
	// ****************************************************************************
	//								AddMenuItem
	// 
	/// Adds a new menu item to the menus.
	/// 
	/// \param menu         Menu number to which we're adding an item
	/// \param commandName  String to display in the menu for this item
	/// \param after        Item number of the item to <B>follow</B> the one we're inserting.  Pass -1 to add to the end of the menu.
	/// \param action       Action number to associate with this menu item
	/// 
	virtual MCCOMErr MCCOMAPI AddMenuItem			(int16 menu, TMCString& commandName, int16 after, int32 action) = 0;
	
	// ****************************************************************************
	//								AddSubMenuItem
	// 
	/// Adds a sub-menu item to a given menu item.  This allows for nested menus, as in Carrara's 
	/// View->Zoom menu with its various zoom factors as sub-menus.
	/// 
	/// \param menu         Menu ID number of the parent menu
	/// \param commandName  String to display in the menu for this item
	/// \param submenu      Menu ID number for the menu to create
	/// \param after        Item number of the item to <B>follow</B> the one we're inserting.  Pass -1 to add to the end of the menu.
	/// 
	virtual MCCOMErr MCCOMAPI AddSubMenuItem		(int16 menu, TMCString& commandName, int16 submenu, int16 after) = 0;

	// ****************************************************************************
	//								GetItemCount
	// 
	/// Gets the number of items in a given menu.
	/// 
	/// \param menu  Menu ID number to query
	/// \return The count of menu items in this menu.
	///
	virtual int16	 MCCOMAPI GetItemCount			(int16 menu) = 0;
	
	// ****************************************************************************
	//								FindMenuByID
	// 
	/// Finds a menu item by its menu ID
	/// 
	/// \param menu     ID of the menu to find
	/// \param outMenu  Returns a pointer to the menu, or NULL if not found.
	/// 
	virtual MCCOMErr MCCOMAPI FindMenuByID			(int16 menu, IMFMenu** outMenu) = 0;

	// ****************************************************************************
	//								InvalidateMenus
	// 
	/// Invalidates menus so that SelfPrepareMenus will be called throughout the application at the next event loop.
	/// Call this if the context has changed, and menus should be updated (for example, if you do something like
	/// changing the selection in a SelfMouseDown() but do not post any actions).
	/// 
	virtual MCCOMErr MCCOMAPI InvalidateMenus		() = 0;


// Tools
	// ****************************************************************************
	//								EnableGlobalTool
	// 
	/// Enables or disables a global tool item.
	/// 
	/// \param inToolID     ID of the tool to enable/disable
	/// \param inIsEnabled  If true, enables the tool.  If false, disables it.
	/// \param inIsPressed  Not currently implemented.
	/// 
	virtual MCCOMErr MCCOMAPI EnableGlobalTool		(int32 inToolID, boolean inIsEnabled, boolean inIsPressed) = 0;
	
	// ****************************************************************************
	//								GetCurrentGlobalTool
	// 
	/// Returns the ID of the current active global tool.
	/// 
	/// \param outToolID  Returns the active tool ID
	/// 
	virtual MCCOMErr MCCOMAPI GetCurrentGlobalTool	(int32& outToolID) = 0;
	
	// ****************************************************************************
	//								SetCurrentGlobalTool
	// 
	/// Sets the current active global tool.
	/// 
	/// \param inToolID      ID of the tool to make active
	/// \param inInvalidate  If true, notifies listeners that the tool has changed, causing appropriate redraws 
	/// 
	virtual MCCOMErr MCCOMAPI SetCurrentGlobalTool	(int32 inToolID, boolean inInvalidate) = 0;


	/// Posts a rebuild menus action
	virtual void	 MCCOMAPI RebuildMainMenus		() = 0;
};


/*****************************************************************************\
*  IShFileUtilities                                                           *
*                                                                             *
*    File utilities provided by the shell for IMCFile stuff                   *
*                                                                             *
\*****************************************************************************/

/// File utilities provided by the shell for IMCFile handling
struct IShFileUtilities: public IMCUnknown
{
public:
	// "static" routines in MCFile.h
	
	// ****************************************************************************
	//								GetSeparator
	// 
	/// Returns the string used as a path element separator.
	/// 
	/// \param sepString  Returns the path element separator string
	/// 
	virtual MCCOMErr MCCOMAPI GetSeparator			(TMCString& sepString) = 0;
	
	// ****************************************************************************
	//								GetBaseNameMaxLength
	// 
	/// Returns the maximum length of a file path 
	/// 
	/// \param maxLength  Returns the max length
	/// 
	virtual MCCOMErr MCCOMAPI GetBaseNameMaxLength	(int32& maxLength) = 0;
	
	// ****************************************************************************
	//								CleanPathName
	// 
	/// Modifies a path name string (generally, one read from a file) to use the correct
	/// separators for this platform.  
	/// 
	/// \param thePathName  Returns the modified path string
	/// 
	virtual MCCOMErr MCCOMAPI CleanPathName			(TMCString& thePathName) = 0;
 	
	// ****************************************************************************
	//								GetAppDirectory
	// 
	/// Returns the path to the application.
	/// 
	/// \param outString  Returns the path
	/// 
	virtual MCCOMErr MCCOMAPI GetAppDirectory		(TMCString& outString) = 0;

	// ****************************************************************************
	//								GetExtensionsFolder
	// 
	/// Returns the application's extensions folder.
	/// 
	/// \param outFolder  Returns a pointer to an IMCFile with the path to the extensions folder.
	/// 
	virtual void	 MCCOMAPI GetExtensionsFolder	(IMCFile** outFolder)=0;

	// ****************************************************************************
	//								CreateIMCFile
	// 
	/// Creates a new file record.
	/// 
	/// \param pFile  
	/// 
 	virtual MCCOMErr MCCOMAPI CreateIMCFile			(IMCFile** pFile) = 0;
	
	// ****************************************************************************
	//								CreateIMCFileIterator
	// 
	/// Creates a file iterator.
	/// \see IMCFileIterator
	/// \see TMCFileType
	/// 
	/// \param fileIterator    Returns a pointer to the file iterator
	/// \param dir             Path 
	/// \param fileTypeRec     Pointer to a TMCFileType file type specifier to restrict the set of files over which the iterator iterates.
	/// \param resolveAliases  If true, the file iterator will resolve aliases/shortcuts, pointing at their destination.
	/// 
	virtual MCCOMErr MCCOMAPI CreateIMCFileIterator	(IMCFileIterator** fileIterator, const TMCString& dir,const TMCFileType* fileTypeRec, boolean resolveAliases = true) = 0;

	// ****************************************************************************
	//								CreateTokenStream
	// 
	/// Creates a token stream.
	/// 
	/// \param tokenStream  The token stream that is created
	/// \param stream       The original stream
	/// \param ownsStream   True if the token stream will destroy the io stream when it is deleted.
	/// 
	virtual void MCCOMAPI CreateTokenStream(IShTokenStream** tokenStream,TMCiostream* stream,boolean ownsStream) = 0;

	// ****************************************************************************
	//								CreateInputFileStream
	// 
	/// Creates the correct input (read) iostream to support compressed file (using the zlib).
	/// 
	/// \param outStream    The stream that is created
	/// \param filePathName The name of the file from whom you want to create a stream
	/// \param outFileSize  If not null, it is filled with the size of the file (note that if the
	///						file is compressed this size is the size of the compressed file, note also
	///						that iostream tell() function on a compressed stream returns the position
	///						in the compressed file).
	/// 
	virtual void MCCOMAPI CreateInputFileStream(TMCiostream** outStream, const TMCString& filePathName, TranscoderType encoding, int32* outFileSize = nil) = 0;

	// ****************************************************************************
	//								GetSeparator
	// 
	/// Returns the character that separates files in a path ('\' on Windows for example)
	/// 
	virtual int8 MCCOMAPI GetSeparator(void) =0;

	// ****************************************************************************
	//								GetAppPath
	// 
	/// Returns the path of the application
	/// 
	/// \param outString  The path of the application
	/// 
	virtual MCCOMErr MCCOMAPI GetAppPath(TMCString& outString)=0;


	// put machine-dependent methods at the end...
#if MAC
	// ****************************************************************************
	//								FSSpecFromFullPathname
	//
	///  FSSpec is deprecated 
	/// Mac-specific function to generate a Macintosh FSSpec data structure from a string containing a path name.
	/// 
	/// \param name         Path name of the file
	/// \param isDirectory  Pass true to specify that the file in question is a directory
	/// \param spec         Returns the FSSpec
	/// 
	virtual MCCOMErr MCCOMAPI FSSpecFromFullPathname(const TMCString& name, boolean isDirectory, FSSpec& spec) = 0;
#endif

	// ****************************************************************************
	//								CreateIMCLargeFile
	// 
	/// Creates a new file record.
	/// 
	/// \param pFile  
	/// 
 	virtual MCCOMErr MCCOMAPI CreateIMCLargeFile	(IMCLargeFile** pFile) = 0;

	// ****************************************************************************
	//								CreateITranscoder
	// 
	/// Creates a new transcoder.
	/// 
	/// \param transcoder	The transcoder that is created
	/// \param type			The type of transcoder to create
	/// 
	virtual void MCCOMAPI CreateITranscoder(ITranscoder** outTranscoder, TranscoderType type) = 0;
};

/*****************************************************************************\
*  IShFileStream                                                              *
*                                                                             *
*    Simple stream interface to provide basic file access services.           *
*                                                                             *
\*****************************************************************************/

// mode constants:
#define kShStreamIn 1
#define kShStreamOut 2
// Seek direction constants:
#define kShStreamBegin 0
#define kShStreamCurrent 1
#define kShStreamEnd 2

/// Simple stream interface to provide basic file access services.
struct IShFileStream: public IMCUnknown
{
public:
	
	// ****************************************************************************
	//								InitFileStream
	// 
	/// Initializes the file stream.
	/// 
	/// \param fileName  C string filename for the file to open.
	/// \param mode      Pass kShStreamIn for reading or kShStreamOut for writing.
	/// 
	virtual MCCOMErr MCCOMAPI InitFileStream	(int8* fileName, uint32 mode) = 0;
	
	//-- Seek
	// ****************************************************************************
	//								Tell
	// 
	/// \return Current offset in the file
	/// 
	virtual uint32	 MCCOMAPI Tell				() = 0;
	
	// ****************************************************************************
	//								Seek
	// 
	/// Seek within the file.
	/// 
	/// \param offset     Offset in bytes to seek
	/// \param direction  Direction specifier: pass kShStreamBegin, kShStreamCurrent, or kShStreamEnd
	/// 
	virtual MCCOMErr MCCOMAPI Seek				(uint32 offset, int16 direction) = 0;
	
	//-- Binary io
	// ****************************************************************************
	//								Read
	// 
	/// Binary read of n bytes
	/// 
	/// \param s  Pointer to structure to hold the read
	/// \param n  Number of bytes to read
	/// 
	virtual MCCOMErr MCCOMAPI Read				(int8* s, uint32 n) = 0;
	
	// ****************************************************************************
	//								Write
	// 
	/// Binary write n bytes
	/// 
	/// \param s  Location of data to write
	/// \param n  Number of bytes to write
	/// 
	virtual MCCOMErr MCCOMAPI Write				(int8* s, uint32 n) = 0;
	
	// ****************************************************************************
	//								Append
	// 
	/// Increases file size by n bytes 
	/// 
	/// \param n  Number of bytes to append
	/// 
	virtual MCCOMErr MCCOMAPI Append			(uint32 n) = 0;
	
	//-- Text io
	// ****************************************************************************
	//								Get
	// 
	/// Read one text character
	/// 
	/// \param c  pointer to structure to hold the character
	/// 
	virtual MCCOMErr MCCOMAPI Get				(int8* c) = 0;
	
	// ****************************************************************************
	//								GetString
	// 
	/// Reads a text string
	/// 
	/// \param str    Pointer to structure to hold the string
	/// \param count  Maximum number of characters to read
	/// \param delim  End-of-string delimiter
	/// 
	virtual MCCOMErr MCCOMAPI GetString			(int8* str, uint32 count, int8 delim) = 0;
	
	// ****************************************************************************
	//								GetLine
	// 
	/// Reads one line (terminated by CR or CR/LF) from the stream.
	/// 
	/// \param str    Pointer to structure to hold the string
	/// \param count  Maximum number of characters to read
	/// 
	virtual MCCOMErr MCCOMAPI GetLine			(int8* str, uint32 count) = 0;
	
	// ****************************************************************************
	//								GetInt32
	// 
	/// Reads an int32 from the stream
	/// 
	/// \param num  Pointer to the int32 into which the function will read
	/// 
	virtual MCCOMErr MCCOMAPI GetInt32			(int32* num) = 0;

	// ****************************************************************************
	//								GetDouble
	// 
	/// Reads a double from the stream
	/// 
	/// \param num  Pointer to the double into which the function will read
	/// 
	virtual MCCOMErr MCCOMAPI GetDouble			(double* num) = 0;
	
	// ****************************************************************************
	//								Put
	// 
	/// Writes a character to the stream
	/// 
	/// \param c  character to write
	/// 
	virtual MCCOMErr MCCOMAPI Put				(int8 c) = 0;
	
	// ****************************************************************************
	//								PutString
	// 
	/// Writes a (null-terminated) string to the stream
	/// 
	/// \param str  Pointer to the string to write
	/// 
	virtual MCCOMErr MCCOMAPI PutString			(int8* str) = 0;
	
	// ****************************************************************************
	//								PutLine
	// 
	/// Writes a (\n-terminated) line to the stream
	/// 
	/// \param str  Pointer to the string to write
	/// 
	virtual MCCOMErr MCCOMAPI PutLine			(int8* str) = 0;
	
	// ****************************************************************************
	//								PutEOL
	// 
	/// Writes an EOL to the stream
	/// 
	virtual MCCOMErr MCCOMAPI PutEOL			() = 0;
	
	// ****************************************************************************
	//								PutInt32
	// 
	/// Writes an int32 to the stream
	/// 
	/// \param num  int32 to write
	/// 
	virtual MCCOMErr MCCOMAPI PutInt32			(int32 num) = 0;
	
	// ****************************************************************************
	//								PutDouble
	// 
	/// Writes a double to the stream
	/// 
	/// \param num  double to write
	/// 
	virtual MCCOMErr MCCOMAPI PutDouble			(double num) = 0;
	
	// ****************************************************************************
	//								PutBack
	// 
	/// Returns c to the file stream's buffer, moving the file seek position back by one byte
	/// 
	/// \param c  Character to put back
	/// 
	virtual MCCOMErr MCCOMAPI PutBack			(int8 c) = 0;
	
	//-- Error
	// ****************************************************************************
	//								Good
	// 
	/// \return true if the file stream has not encountered errors. 
	///
	virtual boolean  MCCOMAPI Good				() = 0;
	
	// ****************************************************************************
	//								Fail
	// 
	/// \return true if the file stream has encountered a failure in reading or writing
	/// 
	virtual boolean  MCCOMAPI Fail				() = 0;
	
	// ****************************************************************************
	//								Eof
	// 
	/// \return true if the file stream has reached the end of the file
	/// 
	virtual boolean  MCCOMAPI Eof				() = 0;
	
	//-- Misc.
	// ****************************************************************************
	//								SetMacOSInfo
	// 
	/// Sets the creator and file type designators in the resource fork of a MacOS file.
	/// 
	/// \param creator  Creator type (ie 'CRRA')
	/// \param type     File type (ie 'JPEG')
	/// 
	virtual MCCOMErr MCCOMAPI SetMacOSInfo		(uint32 creator, uint32 type) = 0;
 	
	// ****************************************************************************
	//								GetFileSize
	// 
	/// \return the size of the file in bytes
	/// 
	virtual uint32	 MCCOMAPI GetFileSize		() = 0;
};

/*****************************************************************************\
*  IShAction, IShMouseAction, IShActionManager                                *
*                                                                             *
*                                                                             *
*                                                                             *
\*****************************************************************************/

// Stages for IShMouseAction::GetPartToRedraw
#define	kShDoAction		0 ///< Stage for IShMouseAction::GetPartToRedraw
#define	kShUndoAction	1 ///< Stage for IShMouseAction::GetPartToRedraw
#define	kShRedoAction	2 ///< Stage for IShMouseAction::GetPartToRedraw

// Tracking Stages for IShMouseAction::Track
#define	kShBeginTracking	0 ///< Tracking stage for IShMouseAction::Track
#define	kShContinueTracking	1 ///< Tracking stage for IShMouseAction::Track
#define	kShFinishTracking	2 ///< Tracking stage for IShMouseAction::Track

/// \}

/// \addtogroup ShellInterface
/// \{

/// Interface for basic Actions.  All actions should implement these functions.
struct IShAction: public IMCUnknown
{
public:
	// ****************************************************************************
	//								Do
	// 
	/// Function called to actually perform the action.
	/// \note As the constructor of the action is not protected by the exception mechanism, 
	///       no memory allocations (ie 'pointer = new ...') should be used there.
	///       Only initializations (like 'pointer = NULL;') should be made in the constructor. 
	///       The allocations should be made here in Do().
	/// 
	virtual MCCOMErr MCCOMAPI Do				() = 0;

	// ****************************************************************************
	//								Undo
	// 
	/// Called to undo the action.
	/// \note When undone, an action must restore the database to EXACTLY the same state it was in before Do() was called.
	///       This means that if a pointer is cloned, the action must store the original pointer in Do() and apply its
	///       modifications to the clone.  Then, when Undo() is called, the action simply replaces the cloned and modified
	///       pointer with the original, unmodified one.
	/// 
	virtual MCCOMErr MCCOMAPI Undo				() = 0;

	// ****************************************************************************
	//								Redo
	// 
	/// Called to Redo the action.  This can often simply call Do().
	/// 
	/// 
	virtual MCCOMErr MCCOMAPI Redo				() = 0;

	// ****************************************************************************
	//								WillCauseChange
	// 
	/// \return true if the action will modify the database.
	/// 
	virtual boolean  MCCOMAPI WillCauseChange	() = 0;

	// ****************************************************************************
	//								CanUndo
	// 
	/// Returns true if the action is undoable.  If CanUndo() returns false, Undo() and Redo() 
	/// should return MC_E_NOTIMPL and do nothing.
	/// \return true if the action is undoable.
	/// 
	virtual boolean  MCCOMAPI CanUndo			() = 0;

	// ****************************************************************************
	//								GetPartToRedraw
	// 
	/// Gives the action the opportunity to tell the Shell that the returned part should
	/// be redrawn after Do/Undo/Redo.  Return NULL in outPart if no redraw is needed.
	/// 
	/// \param outPart  Returns a pointer to the part that needs to be redrawn after the action runs.
	/// \param stage    Allows you to specify what stage to query for part redraw.  kShDoAction, kShUndoAction, kShRedoAction
	/// 
	virtual void MCCOMAPI GetPartToRedraw		(IMFPart** outPart, int32 stage) = 0;		

	// ****************************************************************************
	//								GetName
	// 
	/// Return the name to display in the undo/redo list.
	/// \note Do not use hardcoded strings inside the code, use strings from resources instead.
	/// 
	/// \param name  The name of the action
	/// 
	virtual MCCOMErr MCCOMAPI GetName			(TMCString& name) = 0;
	
	// ****************************************************************************
	//								NeedsToPrepareMenus
	// 
	/// \return true if execution of the action (Do() or Undo() or Redo()) should cause 
	/// the menus to be prepared (ie if contents of the menus need to be enabled/disabled)
	/// 
	virtual boolean MCCOMAPI NeedsToPrepareMenus(void) = 0;
};


struct IShMouseAction: public IMCUnknown
{
public:
	// ****************************************************************************
	//								Do
	// 
	/// Function called to actually perform the action.
	/// \note As the constructor of the action is not protected by the exception mechanism, 
	///       no memory allocations (ie 'pointer = new ...') should be used there.
	///       Only initializations (like 'pointer = NULL;') should be made in the constructor. 
	///       The allocations should be made here in Do().
	/// 
	virtual MCCOMErr MCCOMAPI Do				() = 0;

	// ****************************************************************************
	//								Undo
	// 
	/// Called to undo the action.
	/// \note When undone, an action must restore the database to EXACTLY the same state it was in before Do() was called.
	///       This means that if a pointer is cloned, the action must store the original pointer in Do() and apply its
	///       modifications to the clone.  Then, when Undo() is called, the action simply replaces the cloned and modified
	///       pointer with the original, unmodified one.
	/// 
	virtual MCCOMErr MCCOMAPI Undo				() = 0;

	// ****************************************************************************
	//								Redo
	// 
	/// Called to Redo the action.  This can often simply call Do().
	/// 
	/// 
	virtual MCCOMErr MCCOMAPI Redo				() = 0;

	// ****************************************************************************
	//								WillCauseChange
	// 
	/// \return true if the action will modify the database.
	/// 
	virtual boolean  MCCOMAPI WillCauseChange	() = 0;

	// ****************************************************************************
	//								CanUndo
	// 
	/// Returns true if the action is undoable.  If CanUndo() returns false, Undo() and Redo() 
	/// should return MC_E_NOTIMPL and do nothing.
	/// \return true if the action is undoable.
	///
	virtual boolean  MCCOMAPI CanUndo			() = 0;

	// ****************************************************************************
	//								GetName
	// 
	/// Return the name to display in the undo/redo list.
	/// \note Do not use hardcoded strings inside the code, use strings from resources instead.
	/// 
	/// \param name  The name of the action
	/// 
	virtual MCCOMErr MCCOMAPI GetName			(TMCString& name) = 0;

	// ****************************************************************************
	//								Track
	// 
	/// Called each time the mouse moves.  At least, Track() is called three times (even if the mouse does not move).
	/// \note The nextAction parameter must return 'this' to continue the current action, or a pointer to a new action, or NULL if the tracking should stop and the Action be discarded.
	/// \note The TMCPoint arguments are input values, but they can also be used as output values.  This is useful to force the initial position of the mouse to be in the middle of a handle.
	///       Constraints on the 'cur' position should be handled in Constrain().
	/// 
	/// \param gc          Graphic context for the mouse action
	/// \param stage       kShBeginTracking, kShContinueTracking, or kShEndTracking.  Tells the function what stage of tracking we're in.
	/// \param first       Initial mouse position when this action started tracking
	/// \param prev        Previous mouse position from the previous call of Track()
	/// \param cur         Current mouse position
	/// \param moved       Pass true here if the mouse has moved since the last call to Track()
	/// \param nextAction  Returns a pointer to the next action whose Track() to call.  See note in function description.
	/// 
	virtual void	 MCCOMAPI Track				(IMCGraphicContext* gc, int16 stage, TMCPoint& first, TMCPoint& prev, TMCPoint& cur, boolean moved, IShMouseAction**	nextAction) = 0;

	// ****************************************************************************
	//								TrackEx
	// 
	/// Called each time the mouse moves when the mouse action is in tablet mode.  At least, TrackEx() is called
	/// three times (even if the mouse does not move).
	///
	/// \note The nextAction parameter must return 'this' to continue the current action, or a pointer to a new action, or NULL if the tracking should stop and the Action be discarded.
	/// 
	/// \param gc          Graphic context for the mouse action
	/// \param stage       kShBeginTracking, kShContinueTracking, or kShEndTracking.  Tells the function what stage of tracking we're in.
	/// \param first       Initial mouse position when this action started tracking
	/// \param prev        Previous mouse position from the previous call of Track()
	/// \param cur         Current mouse position
	/// \param moved       Pass true here if the mouse has moved since the last call to Track()
	/// \param nextAction  Returns a pointer to the next action whose Track() to call.  See note in function description.
	/// 
	virtual void	 MCCOMAPI TrackEx			(IMCGraphicContext* gc, int16 stage, const TMFTabletMouseSample& first, const TMFTabletMouseSample& prev, const TMFTabletMouseSample& cur, boolean moved, IShMouseAction** nextAction) = 0;

	// ****************************************************************************
	//								Feedback
	// 
	/// Allows the action to draw things related to the tracking.  Feedback() is called for the first time right before 
	/// the first call of Track(kShBeginTracking), and then Feedback() is called right after each call to Track().
	/// 
	/// \param gc     Graphic context for the mouse action
	/// \param stage  kShBeginTracking, kShContinueTracking, or kShEndTracking.  Tells the function what stage of tracking we're in.
	/// \param first  Initial mouse position when this action started tracking
	/// \param prev   Previous mouse position from the previous call of Track()
	/// \param cur    Current mouse position
	/// \param moved  Pass true here if the mouse has moved since the last call to Track()
	/// \param show   Pass false here to bypass any drawing, or true to enable drawing.
	/// 
	virtual MCCOMErr MCCOMAPI Feedback			(IMCGraphicContext* gc, int16 stage, const TMCPoint& first, const TMCPoint& prev, const TMCPoint& cur, boolean moved, boolean show) = 0;

	// ****************************************************************************
	//								GetPartToRedraw
	// 
	/// Gives the action the opportunity to tell the Shell that the returned part should
	/// be redrawn after Do/Undo/Redo.  Return NULL in outPart if no redraw is needed.
	/// 
	/// \param outPart  Returns a pointer to the part that needs to be redrawn after the action runs.
	/// \param stage    Allows you to specify what stage to query for part redraw.  kShDoAction, kShUndoAction, kShRedoAction
	/// 
	virtual void MCCOMAPI GetPartToRedraw		(IMFPart** outPart, int32 stage) = 0;

	// ****************************************************************************
	//								Constrain
	// 
	/// Use this method to constrain the 'cur' position to a value, before Track() is called
	/// 
	/// \param gc     Graphic context for the mouse action
	/// \param stage  kShBeginTracking, kShContinueTracking, or kShEndTracking.  Tells the function what stage of tracking we're in.
	/// \param first  Initial mouse position when this action started tracking
	/// \param prev   Previous mouse position from the previous call of Track()
	/// \param cur    Current mouse position - also returns constrained current mouse position
	/// \param moved  Pass true here if the mouse has moved since the last call to Track()
	/// 
	virtual MCCOMErr MCCOMAPI Constrain			(IMCGraphicContext* gc, int16 stage, const TMCPoint& first, const TMCPoint& prev, TMCPoint& cur, boolean moved) = 0; 

	// ****************************************************************************
	//								NeedsToPrepareMenus
	// 
	/// \return true if execution of the action (Do() or Undo() or Redo()) should cause 
	/// the menus to be prepared (ie if contents of the menus need to be enabled/disabled)
	/// 
	virtual boolean MCCOMAPI NeedsToPrepareMenus(void) = 0;

	// ****************************************************************************
	//								ConstrainedToView
	// 
	/// \return true if the action should be constrained to the view.  If so, the cursor locations outside of the view will be clamped to the view's limits. 
	/// 
	virtual boolean MCCOMAPI ConstrainedToView(void) = 0;
	

	// ****************************************************************************
	//								IsPerpetualMouseAction
	// 
	/// \return true if the action wants infinite mouse movement
	/// 
	virtual boolean MCCOMAPI IsPerpetualMouseAction(void) = 0;
	
	// ****************************************************************************
	//								ShouldHideCursor
	// 
	/// \return true if the action wants to hide the cursor
	/// 
	virtual boolean MCCOMAPI ShouldHideCursor(void) = 0;
	
	// ****************************************************************************
	//								ShouldAutoScroll
	// 
	/// \return true if the mouse should autoscroll in a scoll part
	/// 
	virtual boolean MCCOMAPI ShouldAutoScroll(void) = 0;
	
	// ****************************************************************************
	//								KeepTracking
	// 
	/// Returns false if you do not want the mouse action to perform any tracking. This
	/// is useful if you just want to do something on the click.
	///
	/// \return false if the mouse action should stop tracking 
	/// 
	virtual boolean MCCOMAPI KeepTracking() = 0;

	// ****************************************************************************
	//								WantsTabletTracking
	// 
	/// Returns true if the mouse action wants to use the tablet tracking.
	/// 
	virtual boolean	MCCOMAPI WantsTabletTracking() = 0;
		
};

/// \}

/// \addtogroup Utilities
/// \{

/// Interface for the Action Manager, which handles dispatching of actions.
struct IShActionManager: public IMCUnknown
{
public:
	// ****************************************************************************
	//								PostAction
	// 
	/// Call this method to launch an action.
	/// 
	/// \param action     Pointer to the action to post
	/// \param actionNbr  A unique action ID number.  This is used so that the action can be fired off by menu items, and must be unique.
	/// \param context    Pointer to the IMFResponder interface of the document
	/// 
	virtual MCCOMErr MCCOMAPI PostAction		(IShAction* action,int32 actionNbr,IMFResponder *context) = 0;

	// ****************************************************************************
	//								PostMouseAction
	// 
	/// Call this method to launch a mouse action
	/// 
	/// \param action     Pointer to the action to post
	/// \param actionNbr  A unique action ID number.  This is used so that the action can be fired off by menu items, and must be unique.
	/// \param context    Pointer to the IMFResponder interface of the document
	/// \param part       Pointer to the Part that is the view for this action
	/// \param mouse      Mouse position at which to start the action
	/// 
	virtual MCCOMErr MCCOMAPI PostMouseAction	(IShMouseAction* action,int32 actionNbr,IMFResponder *context, IMFPart *part,const TMCPoint &mouse) = 0;

	// ****************************************************************************
	//								IsOptionDown
	// 
	/// \return true if Option/Alt is pressed
	/// 
	virtual boolean MCCOMAPI IsOptionDown		() = 0;

	// ****************************************************************************
	//								IsShiftDown
	// 
	/// \return true if Shift is pressed
	/// 
	virtual boolean MCCOMAPI IsShiftDown		() = 0;

	// ****************************************************************************
	//								IsCommandDown
	// 
	/// \return true if Command/Ctrl is pressed
	/// 
	/// 
	virtual boolean MCCOMAPI IsCommandDown		() = 0;

	// ****************************************************************************
	//								IsControlDown
	// 
	/// Mac only!  Returns true if Ctrl is pressed.  (On the PC, IsCommandDown() checks for this)
	/// \return true if Ctrl is pressed
	/// 
	virtual boolean MCCOMAPI IsControlDown		() = 0;

	// ****************************************************************************
	//								IsLongStaticClick
	// 
	/// Call this method when the mouse is allready down.   
	/// \return true if the click was long and the mouse did not move too much (ie less than a pixel)
	/// 
	virtual boolean MCCOMAPI IsLongStaticClick	() = 0;

	// ****************************************************************************
	//								IsShortStaticClick
	// 
	/// Call this method when the mouse is allready down. 
	/// \return true if the click was short and the mouse did not move too much (ie less than a pixel)
	/// 
	virtual boolean MCCOMAPI IsShortStaticClick	() = 0;

	// ****************************************************************************
	//								IsDragAndDropClick
	// 
	/// Call this method when the mouse is allready down. 
	/// \return true if the click was "long" and the mouse moved more than a pixel
	/// 
	virtual boolean MCCOMAPI IsDragAndDropClick	() = 0;

	// ****************************************************************************
	//								IsDelayedDrag
	// 
	/// Call this method when the mouse is allready down. 
	/// \return true if the mouse moved more than a pixel and a short amount of time as passed
	/// 
	virtual boolean MCCOMAPI IsDelayedDrag		() = 0;
	
};


/// Utilities for getting and handling resources.
struct IShResourceUtilities: public IMCUnknown
{
public:
	
	// ****************************************************************************
	//								GetIndString
	// 
	/// Gets a string from a STR# resource by index.  This is the most common way to 
	/// get a string for display.  Looks in the current resource file.
	/// \see CWhileInCompResFile
	/// 
	/// \param ioString  Returns the string found
	/// \param inResID   Resource ID of the STR# resource
	/// \param inIndex   Index of the string to get within the resource
	/// 
	virtual MCCOMErr MCCOMAPI GetIndString				(TMCString&			ioString,
														 int16 				inResID,
														 int16 				inIndex) = 0;

	// ****************************************************************************
	//								GetIndString
	// 
	/// Gets a string from a STR# resource by index.  Looks in the resource corresponding to 
	/// the specified family and class IDs.  
	/// 
	/// \param inCompFamilyID  Component family ID for resource
	/// \param inCompClassID   Component class ID for resource
	/// \param ioString        Returns the string found
	/// \param inResID         Resource ID of the STR# resource
	/// \param inIndex         Index of the string to get within the resource
	/// 
	virtual MCCOMErr MCCOMAPI GetIndString				(IDType 	inCompFamilyID,
														 IDType 	inCompClassID,
														 TMCString&			ioString,
														 int16 				inResID,
														 int16 				inIndex) = 0;

	// ****************************************************************************
	//								GetResource
	// 
	/// Gets a resource from the current resource file.  You must call ReleaseResource() to
	/// release the memory allocated in outResource
	/// \see CWhileInCompResFile
	/// 
	/// \param inType       Resource type to get
	/// \param inResID      Resource ID of the resource to get
	/// \param outResource  A pointer to the resource that is returned
	/// 
	virtual MCCOMErr MCCOMAPI GetResource				(const FourCharT 	inType, 
														 const int32 		inResID, 
														 TMCResource*&		outResource) = 0;

	// ****************************************************************************
	//								GetIndResource
	// 
	/// Gets a resource by index from the current resource file.  Generally used when you want 
	/// to operate on every resource of a given type in the resource file.
	/// \see CWhileInCompResFile
	/// 
	/// \param type         Resource type to get
	/// \param index        Index of resource to get
	/// \param outResource  A pointer to the resource that is returned
	/// 
	virtual MCCOMErr MCCOMAPI GetIndResource			(const IDType		type,
														 const int32		index,
														 TMCResource*&		outResource)=0;

	// ****************************************************************************
	//								SetupComponentResources
	// 
	/// Do not use.  You should use CWhileInCompResFile instead of SetupComponentResources in extensions.
	/// 
	/// \param inCompFamilyID   
	/// \param inCompClassID    
	/// \param outOldResources  
	/// 
	virtual MCCOMErr MCCOMAPI SetupComponentResources	(IDType 	inCompFamilyID, 
														 IDType 	inCompClassID,
														 void** 	outOldResources) = 0;
	// ****************************************************************************
	//								RestoreComponentResources
	// 
	/// Do not use.  You should use CWhileInCompResFile instead of RestoreComponentResources in extensions.
	/// 
	/// \param inOldResources  
	/// 
	virtual MCCOMErr MCCOMAPI RestoreComponentResources	(void* 		inOldResources) = 0;

	// ****************************************************************************
	//								ReleaseResource
	// 
	/// Releases a resource returned by GetResource
	/// 
	/// \param resourcePtr  The pointer returned by GetResource
	/// 
	virtual void MCCOMAPI ReleaseResource(TMCResource* resourcePtr) = 0;


	// ****************************************************************************
	//								GetCommandBindingGroup
	// 
	/// Loads a TMCCommandBindingGroup from a 'BnGp' resource
	/// Usually used in the implementation of GetCommandBindingContexts of a prefs component (derived from TBasicPrefsComponent)
	///	For scene commands, you can specify the binding directly in the 'scmd' resource.
	///
	/// \note you must be in the right resource context to load the proper resource, 
	/// so don't forget to use a CWhileInCompResFile object.
	/// 
	/// \param ioGroup  the group to fill
	/// \param inResID  the id of the 'BnGp' resource to load
	/// 
	virtual void MCCOMAPI GetCommandBindingGroup(TMCCommandBindingGroup& ioGroup, int16 inResID) = 0;

};





/*****************************************************************************\
*                                                                             *
*  IShPersonalityUtilities                                                    *
*                                                                             *
\*****************************************************************************/
/// Utility functions to access the application user defined information (UI, shortcuts...).
struct IShPersonalityUtilities: public IMCUnknown
{
public:

	// ****************************************************************************
	//								GetUIColor
	// 
	/// Gets a specified UI color.  Useful when drawing in the UI, so that we have consistent 
	/// colors throughout the UI.
	/// 
	/// \param inColorIndex  Index of the color to get.  See EUIColor
	/// 
	virtual TMCRGBColor		MCCOMAPI GetUIColor			(EUIColor 	inColorIndex) = 0;
	
	// ****************************************************************************
	//								GetUITextStyle
	// 
	/// Gets a specified text style.  Useful to draw text in the UI, so that we have consistent
	/// text style across parts of the application.
	/// 
	/// \param inStyleIndex  Index of the text style to get.  See ETextStyle
	/// 
	virtual TMCTextStyle	MCCOMAPI GetUITextStyle		(ETextStyle inStyleIndex) = 0;
};

/*****************************************************************************\
*                                                                             *
*  IShDragAndDropUtilities                                                    *
*                                                                             *
\*****************************************************************************/


/// Utilities for drag and drop functionality.  Drag and Drop works as follows:
/// - When the drag motion begins, you create a drop candidate that contains information
///   about the object being dragged.
/// - As the object is dragged around the UI, CreateDropArea is called to create a Drop
///   Area for the Part underneath the mouse cursor.  The Drop Area can determine whether
///   or not it is able to accept the Drop Candidate.
/// - If the drop area CAN accept the Drop Candidate, and the user releases the mouse button,
///   the IMFExDropArea::ReceiveDrop() function is called to act on the drop.
struct IShDragAndDropUtilities: public IMCUnknown
{
public:

	// ****************************************************************************
	//								CreateDropCandidate
	// 
	/// Creates a drop candidate for Drag and Drop actions.  Creates an IMFDropCandidate
	/// and associated IMFExropCandidate.
	/// 
	/// \param inDropCandidateExtension  ID type for the drop candidate extension class to create
	/// \param outDropCandidate          Returns a pointer to the drop candidate.
	/// 
	virtual MCCOMErr 	MCCOMAPI CreateDropCandidate	(IDType inDropCandidateExtension, 
														 IMFDropCandidate** outDropCandidate) = 0;
	
	// ****************************************************************************
	//								CreateDropArea
	// 
	/// Creates a drop area for Drag and Drop actions.  Creates an IMFDropArea and 
	/// associated IMFExDropArea.
	/// 
	/// \param inDropAreaExtension  ID type for the drop area extension class to create
	/// \param inAssociatedPart     Pointer to the part associated with this drop area
	/// \param outDropArea          Returns a pointer to the drop area.
	/// 
	virtual MCCOMErr 	MCCOMAPI CreateDropArea			(IDType inDropAreaExtension,
														 IMFPart* inAssociatedPart, 
														 IMFDropArea** outDropArea) = 0;
	
	// ****************************************************************************
	//								StartDragAndDropAction
	// 
	/// Posts a new drag and drop action.  
	/// 
	/// \param inDropCandidate        Pointer to the Drop Candidate for this action
	/// \param inScreenMousePos       Initial mouse position
	/// \param inScreenDragRect       Coordinates in screen space bounding the object being dragged
	/// \param inScreenToleranceRect  Tolerance rectangle for this drag action.  The mouse must exit this rectangle before we start drawing the Drop Canditate under the mouse.
	/// \param inTrackImmediately     If true, begins the tracking immediately, without waiting 
	/// 
	virtual MCCOMErr 	MCCOMAPI StartDragAndDropAction	(IMFDropCandidate* inDropCandidate,
														 const TMCPoint& inScreenMousePos,
														 const TMCRect&	inScreenDragRect,
														 const TMCRect& inScreenToleranceRect,
														 boolean inTrackImmediately) = 0;
};


/*****************************************************************************\
*                                                                             *
*  IShMouseUtilities                                                    *
*                                                                             *
\*****************************************************************************/
/// Utilities for handling the mouse.  
/// \note Mouse visibility is controlled by the cursor level - basically a count of the number of things 
///       that want the cursor to be visible versus the number that want it to be hidden.  If the level 
///       is below 0, the cursor will be hidden, while if it's 0 or larger, it will be visible.  Generally you
///       won't have to worry about that, but it can be useful to know if Hide() and Show() are not behaving
///       as expected.
struct IShMouseUtilities : public IMCUnknown
{
	
	// ****************************************************************************
	//								Hide
	// 
	/// When Hide() is called, it hides the cursor if the cursor level is 0. It then always decrements the cursor level, indicating
	/// that something wants to hide the cursor.
	/// 
	virtual void		MCCOMAPI Hide				(void) = 0;
	
	// ****************************************************************************
	//								Show
	// 
	/// When Show() is called, it increments the cursor level, and if this brings the level to 0, shows the cursor.
	/// 
	virtual void		MCCOMAPI Show				(void) = 0;

	// ****************************************************************************
	//								ForceCursorVisible
	// 
	/// Generally not needed.  Use Show() instead if possible.  This shows the cursor and forces the cursor level to 0.
	/// 
	virtual void		MCCOMAPI ForceCursorVisible	(void) = 0;

	// ****************************************************************************
	//								SetCursorPosition
	// 
	/// Sets the cursor position.  Very slow on MacOS X, so use sparingly.
	/// \see CreatePerpetualMouseHelper()
	/// 
	/// \param inPos  Position to set.
	/// 
	virtual void		MCCOMAPI SetCursorPosition	(TMCPoint& inPos) = 0;

	// ****************************************************************************
	//								SetCursor
	// 
	/// Sets the cursor icon to use.
	/// 
	/// \param inCursorID  ID number of cursor to use.  See MCCursorTypes.h for a list of cursors.
	/// 
	virtual void		MCCOMAPI SetCursor			(uint32 inCursorID) = 0;
	
	// ****************************************************************************
	//								CreatePerpetualMouseHelper
	// 
	/// SetCursorPosition() is very slow on MacOS X, so instead create a PerpetualMouse and use it.
	/// This can be used for supporting perpetual mouse movement.  But usually, it's better and easier to just
	/// derive a class from TBasicMouseAction and override the ConstrainedToView(), IsPerpetualMouseAction(), and
	/// ShouldHideCursor() functions.
	/// 
	/// \param outPerpetualMouse  Returns a pointer to the IMFPerpetualMouse
	/// 
	virtual void		MCCOMAPI CreatePerpetualMouseHelper	(IMFPerpetualMouse** outPerpetualMouse) = 0;
};


/// Utility functions for dealing with system sound.  At the moment, provides a way to create
/// an audio buffer appropriate to the system.
///
struct IShSoundUtilities : public IMCUnknown
{
        // ****************************************************************************
        //                                                              CreateAudioBuffer
        // 
        /// Creates an audio buffer to use for playing sounds.
        /// 
        /// \param outBuffer       Ends up pointing to the audio buffer created
        /// \param inRate          Sampling rate of audio buffer
        /// \param inChannels      Number of channels of audio (1 or 2)
        /// \param inDepth         Bit depth of buffer samples (8 or 16)
        /// \param inBufferLength  Length of buffer in bytes
        /// 
        virtual void    MCCOMAPI        CreateAudioBuffer(IMCAudioBuffer** outBuffer, int32 inRate, int32 inChannels, int32 inDepth, int32 inBufferLength) =0;

		virtual void	MCCOMAPI		CreateAudioPlayer(IMCAudioPlayer** outPlayer, IExSound* inSound) = 0;
		virtual void	MCCOMAPI		CreateAudioPlayer(IMCAudioPlayer** outPlayer, IExSound* inSound, int32 inRate, int32 inChannels, int32 inDepth, int32 inBufferLength) = 0;
		virtual void    MCCOMAPI		CreateSoundProcessor(IShSoundProcessor** ourProcessor) = 0;
};



/// \}

#endif
