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

		IMFTextPopupPart.h

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

		Author:	Emil
		Date:	10/12/98

		COM interface to internal Text Popup objects.

		Revision History

		when		who			what & why
		==========	==========	======================================================
		8/29/99		Yann		Added a few Setters and Getters to the IMFTextPopupPart API
		7/18/99		Ian			Menu API change (inserts take a before item, not an after item).
		7/13/99		Ian			SetArrowImageId() needed to take a ResourceID, not a uint32.
		07/11/99	Pierre		Added SetItemActionNumber to the COM API
		5/25/99		Greg		Added a way to create separators with text
		02/02/99    Benjamin    Add AppendSeparator & InsertSeparator
		10/13/98	cph			changed include MCString.h to forward decl
		10/12/98	cph			added include MCString.h

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

#ifndef __IMFTextPopupPart__
#define __IMFTextPopupPart__

#if CP_PRAGMA_ONCE
#pragma once
#endif

#include "MCCompObj.h"

class TMCString;
struct IMFPart;
struct IMFMenu;


//*********************** Globally Unique Ids ********************************
MCDEFINE_GUID(IID_IMFTextPopupPart, 0x5ebc310, 0x6211, 0x11d2, 0x83, 0x98, 0x0, 0x60, 0x97, 0xb, 0xc5, 0x21);
MCDEFINE_GUID(IID_ITextPopupBuilder, 0x51422b28, 0xeb93, 0x456c, 0xa4, 0x90, 0xc7, 0x99, 0x86, 0x30, 0x92, 0x38);
//****************************************************************************

struct ITextPopupBuilder;

/******************************************************************************\
*                                                                              *
*           IMFTextPopupPart                                                   *
*                                                                              *
\******************************************************************************/
/// \addtogroup MCF
/// \{

/// Interface for Text Popups.  These are pick boxes which, when clicked, pop up to present
/// a list of choices for selection.  Member functions allow you to choose whether or not to 
/// have checkmarks next to items, whether to enable items for selection, etc.
/// <P>To use a text popup inside your user interface, you can create the part in MCSketch
/// from "Plugin Group #7" in the MFWindow menu.  To fill the popup with menu items, 
/// you would either add them manually from your code (by finding the part and then using
/// AppendMenuItem() etc, or you can define a fixed set of menu items in a CMNU resource in
/// MCSketch, and then set the Popup's context menu ID property to the ID of the CMNU resource.
/// <P> There may be times when you need to update a large list of menu items frequently to
/// correspond to changes in the scene, and the updates could be very wasteful and time-consuming.
/// In these cases, it can be useful to delegate the task of rebuilding the menu to another 
/// object that implements the ITextPopupBuilder interface, by using the SetPopupBuilder() function.  
/// This object will be called to build the menu when the popup is invalid and needs to be displayed.
/// This way, the menu only gets rebuilt once, when it's about to be displayed, rather than every
/// time anything in the scene changes.
/// 
/// \see ITextPopupBuilder
///
struct IMFTextPopupPart : public IMCUnknown
{
	// Insertion and deletion of items
	virtual void	MCCOMAPI AppendMenuItem		(const TMCString& inItemText) = 0;
	virtual void	MCCOMAPI InsertMenuItem		(const TMCString& inItemText, uint32 inBeforeItem) = 0;
	virtual void	MCCOMAPI DeleteMenuItem		(uint32 inIndex)	= 0;
	virtual void	MCCOMAPI RemoveAll			() = 0;

	virtual void	MCCOMAPI AppendSeparator	() = 0;
	virtual void	MCCOMAPI InsertSeparator	(uint32 inIndex) = 0;

	virtual void	MCCOMAPI AppendSeparator	(const TMCString& inItemText) = 0;
	virtual void	MCCOMAPI InsertSeparator	(const TMCString& inItemText, uint32 inIndex) = 0;

	// Set/Get
	virtual void	MCCOMAPI SetArrowImageId	(ResourceID arrowId) = 0;
	virtual	void	MCCOMAPI SetItemActionNumber(uint32 inItem, ActionNumber inActionNumber) = 0;
	virtual	void	MCCOMAPI SetItemChecked		(uint32 inItem, boolean check) = 0;
	virtual	void	MCCOMAPI SetItemEnabled		(uint32 inItem, boolean enable) = 0;
	virtual void	MCCOMAPI SetItemText		(uint32 inItem, const TMCString& inItemText) = 0;
	virtual void	MCCOMAPI SetSelectedAction	(ActionNumber inAction, boolean inNotify = true) = 0;
	virtual void	MCCOMAPI SetSelectedItem	(uint32 inMenuItem, boolean inNotify = true) = 0;

	virtual uint32	MCCOMAPI GetMenuItemsCount	() const = 0;
	virtual void	MCCOMAPI GetItemText		(uint32 inItem, TMCString& outItemText) const = 0;
	virtual uint32	MCCOMAPI GetSelectedItem  	() const = 0;

	// -Returns: the interface to IMFPart (always supported by IMFTextPopupPart)
	virtual IMFPart*	MCCOMAPI GetThisPart() = 0;

	// Julien: 03/2002: need a pointer on the subMenu for vetExporter interface
	virtual IMFMenu* MCCOMAPI GetPopupMenu(void) = 0;

	// ****************************************************************************
	//								SetPopupBuilder
	// 
	/// Enables deferred filling for big dynamic popup menus that change often (like the Find menu in Carrara).
	/// 
	/// \param builder  The object that will be called to fill the menu, when the popup is invalid and needs to be displayed, as on mousedown.
	/// \note The builder is assumed to own this popup menu, so the internal pointer to the builder is not counted.
	/// Therefore, it is a good idea to call SetPopupBuilder(NULL) when you don't need it any more (eg in a SelfPrepareToDestroy function)
	/// 
	virtual void	MCCOMAPI SetPopupBuilder	(ITextPopupBuilder* builder) = 0;

	// ****************************************************************************
	//								InvalidatePopup
	// 
	/// Empties the menu and flags it as invalid 
	/// (so that the BuildPopup method of the menu's builder will be called when needed).
	/// 
	virtual void	MCCOMAPI InvalidatePopup	(boolean removeAll= true) = 0;
};

/// An object that implements the ITextPopupBuilder interface keeps track of an IMFTextPopupPart
/// and rebuilds it when necessary.
struct ITextPopupBuilder : public IMCUnknown
{
	// ****************************************************************************
	//								BuildPopup
	// 
	/// Object callback to enable deferred filling for big popup menus that change often
	/// 
	/// \param popupToBuild   the popup menu that needs to be constructed
	/// 
	virtual void	MCCOMAPI BuildPopup(IMFTextPopupPart* popupToBuild)= 0;
};

/// \}
#endif