CUIFrameMgr Class Reference

#include <custcont.h>

Class Description

See also

Class ICustToolbar, Class ICustomControl, Class ICustStatus, Class MAXBmpFileIcon.

Description:

reflect changes with MAXBMPFileIcon class***

This object controls the overall operation of the individual CUI Frames (the name given to the windows that contain toolbars, menus, the command panel, etc.). There is one instance of this CUIFrameMgr class (obtained by calling the global function GetCUIFrameMgr()). Methods of this class are available to do things like get pointers to button and status controls, and bring up the standard toolbar right click menu .

Note: Developers may use their own images on icon buttons that are managed by this class but the following guidelines must be followed:

BMP files must be put in the /UI/icons folder. This is the UI directory under the 3ds Max EXE directory. This is hard coded because it must be retrieved before 3ds Max is fully started and thus there is no configurable path for it. There is a command line option however, (-c), which specifies for 3ds Max to look in an alternate directory for the CUI file. In that case the bitmap files should be located in the same directory.

For more information on the new icon image system refer to the chapter on Icons.

Inheritance diagram for CUIFrameMgr:

Public Member Functions
CoreExport const MCHAR *	GetCUIDirectory ()
CoreExport void	SetMacroButtonStates (BOOL force)
CoreExport void	SetMode (int md)
CoreExport int	GetMode ()
CoreExport HWND	GetItemHwnd (int id)
CoreExport ICustButton *	GetICustButton (int id)
CoreExport ICustStatus *	GetICustStatus (int id)
CoreExport void	HorizTextButtons (BOOL b)
CoreExport int	GetHorizTextButtons ()
CoreExport void	FixedWidthTextButtons (BOOL b)
CoreExport int	GetFixedWidthTextButtons ()
CoreExport void	SetTextButtonWidth (int w)
CoreExport int	GetTextButtonWidth ()
CoreExport int	SetConfigFile (const MCHAR *cfg)
CoreExport const MCHAR *	GetConfigFile ()
CoreExport void	SetImageSize (int size)
CoreExport int	GetImageSize ()
CoreExport int	GetButtonHeight (int sz=0)
CoreExport int	GetButtonWidth (int sz=0)
CoreExport int	GetDefaultImageListBaseIndex (SClass_ID sid, Class_ID cid)
CoreExport MSTR *	GetDefaultImageListFilePrefix (SClass_ID sid, Class_ID cid)
CoreExport int	AddToRawImageList (const MCHAR *pFilePrefix, int sz, HBITMAP image, HBITMAP mask)
CoreExport int	LoadBitmapFile (const MCHAR *filename)
CoreExport int	FindAndLoadBitmapFiles (const MaxSDK::Util::Path &filePath)
CoreExport int	LoadBitmapImages ()
CoreExport int	ReadConfig ()
CoreExport int	WriteConfig ()
CoreExport void	SetLockLayout (BOOL lock)
CoreExport BOOL	GetLockLayout ()
virtual CoreExport bool	ResolveReadPath (const MSTR &aFilename, MSTR &aResult)=0
	Given a configuration filename, will attempt to find the best match. More...
virtual CoreExport bool	ResolveWritePath (const MSTR &aFilename, MSTR &aResult)=0
	Given a configuration filename, will resolve the correct write absolute path. More...
Public Member Functions inherited from BaseInterfaceServer
virtual UtilExport BaseInterface *	GetInterface (Interface_ID id)
virtual UtilExport int	NumInterfaces () const
virtual UtilExport BaseInterface *	GetInterfaceAt (int i) const
virtual UtilExport	~BaseInterfaceServer ()
Public Member Functions inherited from InterfaceServer
virtual UtilExport	~InterfaceServer ()
	Destructor. More...

Protected Member Functions
CoreExport	CUIFrameMgr ()
	Constructor made protected to prevent instantiation. More...
	CUIFrameMgr (CUIFrameMgr &frame)
	Copy Constructor made protected to prevent instantiation. More...
virtual CoreExport	~CUIFrameMgr ()

Protected Attributes
CUIFrameMgrPrivate *	mPrivate
Protected Attributes inherited from BaseInterfaceServer
Tab< BaseInterface * >	interfaces

Additional Inherited Members
Static Public Member Functions inherited from MaxHeapOperators
static UtilExport void *	operator new (size_t size)
	Standard new operator used to allocate objects If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new (size_t size, const std::nothrow_t &e)
	Standard new operator used to allocate objects if there is insufficient memory, NULL will be returned. More...
static UtilExport void *	operator new (size_t size, const char *filename, int line)
	New operator used to allocate objects that takes the filename and line number where the new was called If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new (size_t size, int block_type, const char *filename, int line)
	New operator used to allocate objects that takes the type of memory, filename and line number where the new was called If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new (size_t size, const std::nothrow_t &e, const char *filename, int line)
	New operator used to allocate objects that takes the filename and line number where the new was called If there is insufficient memory, NULL will be returned. More...
static UtilExport void *	operator new (size_t size, unsigned long flags)
	New operator used to allocate objects that takes extra flags to specify special operations If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new (size_t size, const std::nothrow_t &e, unsigned long flags)
	New operator used to allocate objects that takes extra flags to specify special operations If there is insufficient memory, NULL will be returned. More...
static UtilExport void *	operator new[] (size_t size)
	New operator used to allocate arrays of objects If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new[] (size_t size, const std::nothrow_t &e)
	New operator used to allocate arrays of objects If there is insufficient memory, NULL will be returned. More...
static UtilExport void *	operator new[] (size_t size, const char *filename, int line)
	New operator used to allocate arrays of objects If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new[] (size_t size, int block_type, const char *filename, int line)
	New operator used to allocate arrays of objects. More...
static UtilExport void *	operator new[] (size_t size, const std::nothrow_t &e, const char *filename, int line)
	New operator used to allocate arrays of objects If there is insufficient memory, NULL will be returned. More...
static UtilExport void *	operator new[] (size_t size, unsigned long flags)
	New operator used to allocate arrays of objects If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new[] (size_t size, const std::nothrow_t &e, unsigned long flags)
	New operator used to allocate arrays of objects If there is insufficient memory, NULL will be returned. More...
static UtilExport void	operator delete (void *ptr)
	Standard delete operator used to deallocate an object If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete (void *ptr, const std::nothrow_t &e)
	Standard delete operator used to deallocate an object If the pointer is invalid, nothing will happen. More...
static UtilExport void	operator delete (void *ptr, const char *filename, int line)
	Delete operator used to deallocate an object that takes the filename and line number where the delete was called If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete (void *ptr, int block_type, const char *filename, int line)
	Delete operator used to deallocate an object that takes the type of memory, filename and line number where the delete was called If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete (void *ptr, const std::nothrow_t &e, const char *filename, int line)
	Delete operator used to deallocate an object that takes the filename and line number where the delete was called If the pointer is invalid, nothing will happen. More...
static UtilExport void	operator delete (void *ptr, unsigned long flags)
	Delete operator used to deallocate an object that takes extra flags to specify special operations If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete (void *ptr, const std::nothrow_t &e, unsigned long flags)
	Delete operator used to deallocate an object that takes extra flags to specify special operations If the pointer is invalid, nothing will happen. More...
static UtilExport void	operator delete[] (void *ptr)
	Standard delete operator used to deallocate an array of objects If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete[] (void *ptr, const std::nothrow_t &e)
	Standard delete operator used to deallocate an array of objects If the pointer is invalid, nothing will happen. More...
static UtilExport void	operator delete[] (void *ptr, const char *filename, int line)
	Delete operator used to deallocate an array of objects that takes the filename and line number where the delete was called If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete[] (void *ptr, int block_type, const char *filename, int line)
	Delete operator used to deallocate an array of objects that takes the type of memory, filename and line number where the delete was called If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete[] (void *ptr, const std::nothrow_t &e, const char *filename, int line)
	Delete operator used to deallocate an array of objects that takes the filename and line number where the delete was called If the pointer is invalid, nothing will happen. More...
static UtilExport void	operator delete[] (void *ptr, unsigned long flags)
	Delete operator used to deallocate an array of objects that takes extra flags to specify special operations If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete[] (void *ptr, const std::nothrow_t &e, unsigned long flags)
	Delete operator used to deallocate an array of objects that takes extra flags to specify special operations If the pointer is invalid, an exception will be thrown. More...
static UtilExport void *	operator new (size_t size, void *placement_ptr)
	Placement new operator. More...
static UtilExport void	operator delete (void *ptr, void *placement_ptr)
	Placement delete operator. More...
static UtilExport void *	aligned_malloc (size_t size, size_t alignment)
	Allocates memory on a specified alignment boundary. More...
static UtilExport void *	aligned_realloc (void *ptr, size_t size, size_t alignment)
	Reallocates memory on a specified alignment boundary. More...
static UtilExport void	aligned_free (void *ptr)
	Frees a block of memory that was allocated with aligned_malloc/aligned_realloc. More...

Constructor & Destructor Documentation

CoreExport CUIFrameMgr ( )

protected

Constructor made protected to prevent instantiation.

Blocking default constructor - use GetCUIFrameMgr() accessor

Remarks

Constructor.

CUIFrameMgr ( CUIFrameMgr &  frame )

protected

Copy Constructor made protected to prevent instantiation.

Blocking Copy constructor - use GetCUIFrameMgr() accessor

virtual CoreExport ~CUIFrameMgr ( )

protectedvirtual

Remarks

Destructor.

Member Function Documentation

CoreExport const MCHAR* GetCUIDirectory

(

)

Remarks

Returns the directory name of the custom user interface (CUI) file location.

CoreExport void SetMacroButtonStates

(

BOOL

force

)

Remarks

This is a very important method. It redraws all the visible CUI buttons in 3ds Max, calling the "IsEnabled" and
"IsChecked" handlers on the ActionItems associated with each button (if it has one). If a the "IsEnabled" handler returns FALSE, the button is grayed out. If the "IsChecked" handler return TRUE, the button is draw pressed in.

This method is called internally by the system on selection changes and command mode changes. This handles the majority of the cases where buttons need to be redrawn. However, if a 3rd party plug-in changes some sort of internal state that might affect the return value of an ActionItem's IsEnables or IsChecked handler, then the plug-in should call this method to update the button states. If this method isn't called, buttons may look disabled or pressed (or visa versa) when they shouldn't be. See Class ActionItem.

Parameters

force

This parameter, if TRUE, tells the system to redraw the button even if its state hasn't changed since the last time it was redrawn. Normally this argument is FALSE so it only redraws the buttons that changed state.

CoreExport void SetMode

(

int

md

)

Remarks

This method is for internal use only.

CoreExport int GetMode

(

)

Remarks

This method is for internal use only.

CoreExport HWND GetItemHwnd

(

int

id

)

Remarks

Returns the window handle for the item whose ID is passed. This correspond to the method in ICustToolbar but which should no longer be called for Tool Palettes. It is now also a method of this class because the CUI system doesn't know which toolbar a particular button is on. For example, a 3ds Max user in 3.0 can drag a button from one tool palette to another. No longer then can one use the previous GetItemHwnd() method since the button has moved to a different toolbar.

Parameters

id	The ID of the control.

CoreExport ICustButton* GetICustButton

(

int

id

)

Remarks

Returns a pointer to the custom button whose ID is passed (or NULL if not found). In the CUIFrameMgr implementation of this method it loops through each toolbar that it has control over and calls ICustToolbar::GetICustButton() on it. That method returns NULL if it doesn't find the specified ID. The CUIFrameMgr keeps looping through the toolbars until it gets a non-NULL value. When it finds it it returns the ICustButton pointer.

Parameters

id	The ID of the control.

CoreExport ICustStatus* GetICustStatus

(

int

id

)

Remarks

Returns a pointer to the custom status control whose ID is passed.

Returns a pointer to the custom status control whose ID is passed (or NULL if not found). In the CUIFrameMgr implementation of this method it loops through each toolbar that it has control over and calls ICustToolbar::GetICustStatus() on it. That method returns NULL if it doesn't find the specified ID. The CUIFrameMgr keeps looping through the toolbars until it gets a non-NULL value. When it finds it it returns the ICustStatus pointer.

Parameters

id	The ID of the control.

CoreExport void HorizTextButtons

(

BOOL

b

)

Remarks

This method is for internal use only.

CoreExport int GetHorizTextButtons

(

)

Remarks

This method is for internal use only.

CoreExport void FixedWidthTextButtons

(

BOOL

b

)

Remarks

This method is for internal use only.

CoreExport int GetFixedWidthTextButtons

(

)

Remarks

This method is for internal use only.

CoreExport void SetTextButtonWidth

(

int

w

)

Remarks

This method is for internal use only.

CoreExport int GetTextButtonWidth

(

)

Remarks

This method is for internal use only.

CoreExport int SetConfigFile

(

const MCHAR *

cfg

)

Remarks

This method is for internal use only.

CoreExport const MCHAR* GetConfigFile

(

)

Remarks

This returns the path to the CUI file in use. This may be a UNC name.

CoreExport void SetImageSize

(

int

size

)

Remarks

This method is for internal use only.

CoreExport int GetImageSize

(

)

Remarks

This method is for internal use only.

CoreExport int GetButtonHeight

(

int

sz = 0

)

Remarks

Returns the bitmap button image height for the specified size.

Parameters

sz	The size to check. If 0 is passed then the current icon size is checked. One of the following values: CUI_SIZE_16 CUI_SIZE_24

CoreExport int GetButtonWidth

(

int

sz = 0

)

Remarks

Returns the bitmap button image width for the specified size.

Parameters

sz	The size to check. One of the following values: CUI_SIZE_16 CUI_SIZE_24

CoreExport int GetDefaultImageListBaseIndex	(	SClass_ID	sid,
		Class_ID	cid
	)

Remarks

This method is used internally to create a MaxBmpFileIcon for a given object type. These methods retrieve the file name and base index in the file of the icon for the given object class. They are used in the constructor for MaxBmpFileIcon that takes a class ID and super class ID. This method is for internal use only.

CoreExport MSTR* GetDefaultImageListFilePrefix	(	SClass_ID	sid,
		Class_ID	cid
	)

Remarks

This method is used internally to create a MaxBmpFileIcon for a given object type. These methods retrieve the file name and base index in the file of the icon for the given object class. They are used in the constructor for MaxBmpFileIcon that takes a class ID and super class ID. This method is for internal use only.

CoreExport int AddToRawImageList	(	const MCHAR *	pFilePrefix,
		int	sz,
		HBITMAP	image,
		HBITMAP	mask
	)

Remarks

This method is for internal use only. It is used to add images to the icon manager. The icon manager, which is used to implement the MaxBmpFileIcon class, reads all the .bmp files in the UI/Icons directory at startup time. These icons are specified by an image file and an alpha mask. The icons support two sizes. Large, which is 24 by 24 and small, which is 15 by 16. The icon manager stores the unprocessed image and alpha masks (the "raw" images). Whenever an instance of MaxBmpFileIcon needs to draw itself, it gets the image list and index of the icon in the imagelist using GetSmallImageIndex or GetLargeImageIndex.

CoreExport int LoadBitmapFile

(

const MCHAR *

filename

)

Remarks

This method is for internal use only.

CoreExport int FindAndLoadBitmapFiles

(

const MaxSDK::Util::Path &

filePath

)

Remarks

This method is for internal use only.

CoreExport int LoadBitmapImages

(

)

Remarks

This method is for internal use only.

CoreExport int ReadConfig

(

)

Remarks

Plug-In developers should not call this method – it is for internal use only.

CoreExport int WriteConfig

(

)

Remarks

Plug-In developers should not call this method – it is for internal use only.

CoreExport void SetLockLayout

(

BOOL

lock

)

Remarks

This method is for internal use only.

CoreExport BOOL GetLockLayout

(

)

Remarks

Returns TRUE if the layout is locker; FALSE if unlocked.

virtual CoreExport bool ResolveReadPath ( const MSTR &  aFilename, MSTR &  aResult  )

pure virtual

Given a configuration filename, will attempt to find the best match.

If the application is configured to use User Profiles, this function will attempt to match the filename in the user profile UI directory. If this fails, it will check the system directory.

See also

IPathConfigMgr::IsUsingProfileDirectories()

IPathConfigMgr::IsUsingRoamingProfiles()

Parameters

aFilename	[in] the filename to match, with extension
aResult	[out] the resulting absolute path for the matched file, if found

Returns

true if a match is found, false otherwise

virtual CoreExport bool ResolveWritePath ( const MSTR &  aFilename, MSTR &  aResult  )

pure virtual

Given a configuration filename, will resolve the correct write absolute path.

If the application is configured to use User Profiles, this function map this configuration file to a user profile directory. Otherwise, the configuration file will be resolved to the legacy system UI directory.

See also

IPathConfigMgr::IsUsingProfileDirectories()

IPathConfigMgr::IsUsingRoamingProfiles()

Parameters

aFilename	[in] the filename to match, with extension
aResult	[out] the resulting absolute path to which a client should write a config file

Returns

true if resolved correctly, false if any error is encountered

Member Data Documentation

CUIFrameMgrPrivate* mPrivate

protected