Detailed Description

See also:: Class ICUIFrame, Class CUIFrameMsgHandler, 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 float and dock individual windows, get pointers to frames, 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 external icons.

#include <custcont.h>

Inheritance diagram for CUIFrameMgr:

Public Member Functions
CoreExport void	SetAppHWnd (HWND hApp)
HWND	GetAppHWnd ()
CoreExport const MCHAR *	GetCUIDirectory ()
CoreExport void	ProcessCUIMenu (HWND hWnd, int x, int y)
CoreExport void	DockCUIWindow (HWND hWnd, int panel, RECT *rp=NULL, int init=FALSE)
CoreExport void	FloatCUIWindow (HWND hWnd, RECT *rp=NULL, int init=FALSE)
CoreExport void	MinimizeCUIWindow (HWND hWnd, int init=FALSE)
CoreExport void	SetReservedSize (int panel, int size)
CoreExport int	GetReservedSize (int panel)
CoreExport int	GetPanelSize (int panel, int incReserved=FALSE)
CoreExport int	GetPanelWidth (int panel)
CoreExport void	RecalcLayout (int entireApp=FALSE)
CoreExport void	DrawCUIWindows (int panels=CUI_ALL_PANELS)
CoreExport void	SetMacroButtonStates (BOOL force)
CoreExport void	ResetIconImages ()
CoreExport int	OverDockRegion (LPPOINT pt, DWORD posType, int override=FALSE)
CoreExport void	SetMode (int md)
CoreExport int	GetMode ()
CoreExport void	ExpertMode (int onOff)
CoreExport void	HideFloaters (int onOff)
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	GetCount ()
CoreExport ICUIFrame *	GetICUIFrame (int i)
CoreExport ICUIFrame *	GetICUIFrame (const MCHAR *name)
CoreExport ICUIFrame *	GetICUIFrame (int panel, int rank, int subrank)
CoreExport int	SetConfigFile (const MCHAR *cfg)
CoreExport const MCHAR *	GetConfigFile ()
CoreExport int	DeleteSystemWindows (int toolbarsOnly=TRUE)
CoreExport int	CreateSystemWindows (int reset=FALSE)
CoreExport int	GetSystemWindowCount ()
CoreExport void	SetImageSize (int size)
CoreExport int	GetImageSize ()
CoreExport int	GetButtonHeight (int sz=0)
CoreExport int	GetButtonWidth (int sz=0)
CoreExport void	SetDefaultData (CUIFrameMsgHandler *msg, HIMAGELIST img16, HIMAGELIST img24=NULL)
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	LoadBitmapImages ()
CoreExport CUIFrameMsgHandler *	GetDefaultMsgHandler ()
CoreExport int	ReadConfig ()
CoreExport int	WriteConfig ()
CoreExport void	SetLockLayout (BOOL lock)
CoreExport BOOL	GetLockLayout ()
CoreExport void	EnableAllCUIWindows (int enabled)
virtual CoreExport bool	ResolveReadPath (const MSTR &aFilename, MSTR &aResult)=0
	Given a configuration filename, will attempt to find the best match.
virtual CoreExport bool	ResolveWritePath (const MSTR &aFilename, MSTR &aResult)=0
	Given a configuration filename, will resolve the correct write absolute path.
Protected Member Functions
CoreExport	CUIFrameMgr ()
	Constructor made protected to prevent instantiation.
	CUIFrameMgr (CUIFrameMgr &frame)
	Copy Constructor made protected to prevent instantiation.
virtual CoreExport	~CUIFrameMgr ()
Protected Attributes
MSTR	cfgFile

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 ( ) [protected, virtual]

Remarks:: Destructor.

Member Function Documentation

CoreExport void SetAppHWnd ( HWND hApp )

Search for all occurrences

Remarks:: This method is for internal use only.

HWND GetAppHWnd ( ) [inline]

Search for all occurrences

{ return hApp; }

CoreExport const MCHAR* GetCUIDirectory ( )

Search for all occurrences

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

CoreExport void ProcessCUIMenu	(	HWND	hWnd,
		int	x,
		int	y
	)

Search for all occurrences

Remarks:: This brings up the CUI right click menu (with the Add Tab, Delete Tab, etc selections). Also see the global function DoCUICustomizeDialog().

Parameters:

hWnd	The handle of the window there the mouse was clicked.
x	The x coordinate of the mouse when right clicked.
y	The y coordinate of the cursor when right clicked.

CoreExport void DockCUIWindow	(	HWND	hWnd,
		int	panel,
		RECT *	rp = `NULL`,
		int	init = `FALSE`
	)

Search for all occurrences

Remarks:: This method docks the CUI window whose handle is passed. Developers who want to dock a window should use this method by passing a rectangle which specifies the general area of the screen where the window is to be docked. This will cause 3ds Max reorganize the existing windows.

Parameters:

hWnd	The handle of the window to dock.
panel	The CUI docking panel location. One of the following values: CUI_TOP_DOCK Docked at the top. CUI_BOTTOM_DOCK Docked at the bottom. CUI_LEFT_DOCK Docked on the left. CUI_RIGHT_DOCK Docked on the right.
rp	This is the rectangle which specifies where to dock the window. This is the rectangle that a user moves around the screen when dragging a floating window over top of a docking region. This is specified in screen coordinates. If NULL is passed the window is docked using CUI_TOP_DOCK.
init	This is used internally by 3ds Max when it's starting up. This should always default to FALSE (don't override this and pass TRUE).

CoreExport void FloatCUIWindow	(	HWND	hWnd,
		RECT *	rp = `NULL`,
		int	init = `FALSE`
	)

Search for all occurrences

Remarks:: Floats (un-docks) the specified CUI Window.

Parameters:

hWnd	The window to float.
rp	Specifies the rectangle in screen coordinates where the floating window should reside. If NULL is passed the window is restored to the position it was before it was docked (this information is stored in the CUI file). Note: Calling this method on an already floating window will explicitly NOT resize the window, but rather just move it to the new origin. Said another way, only the left and top members of the rectangle are used on an already floating window. Developers should call the Win32 API MoveWindow or SetWindowPlacement to size the window. See GetFloatingCUIFrameSize() below to compute a size.
init	This is used internally by 3ds Max when it's starting up. This should always default to FALSE (don't override this and pass TRUE).

CoreExport void MinimizeCUIWindow	(	HWND	hWnd,
		int	init = `FALSE`
	)

Search for all occurrences

Remarks:: Switch CUI window to "minimize docked" state. A minimized CUI window can be expanded when user hover the cursor onto the minimized strip. The window is minimized to where it used to be docked. So there's no need to provide another docking panel location nor rectangle as parameter. This will cause 3ds Max reorganize the existing windows.

Parameters:

hWnd	The handle of the window to minimize.
init	This is used internally by 3ds Max when it's starting up. This should always default to FALSE (don't override this and pass TRUE).

CoreExport void SetReservedSize	(	int	panel,
		int	size
	)

Search for all occurrences

Remarks:: This method is for internal use only.

CoreExport int GetReservedSize ( int panel )

Search for all occurrences

Remarks:: This method is for internal use only.

CoreExport int GetPanelSize	(	int	panel,
		int	incReserved = `FALSE`
	)

Search for all occurrences

Remarks:: This method is for internal use only.

CoreExport int GetPanelWidth ( int panel )

Search for all occurrences

CoreExport void RecalcLayout ( int entireApp = FALSE )

Search for all occurrences

Remarks:: This method may be called to recalculates the layout of the CUI. Developers need to call this method after they, for example, add new tool palettes. A developer would create the new palettes and then call this method when done. Otherwise the changes wouldn't be reflected until the user redrew the viewports or resized 3ds Max.

Parameters:

entireApp TRUE to recalculate the entire application, including the viewports. This can be expensive (basically like an Interface::ForceCompleteRedraw()); FALSE will recalculate the top, bottom, left and right panels but won't redraw the viewports.

CoreExport void DrawCUIWindows ( int panels = CUI_ALL_PANELS )

Search for all occurrences

Remarks:: This method redraws the specified panels. Typically developers don't need to call this method.

Parameters:

panels See CUI Docking Panel Locations.

CoreExport void SetMacroButtonStates ( BOOL force )

Search for all occurrences

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 ResetIconImages ( )

Search for all occurrences

Remarks:: This method is for internal use only. This is automatically called when the system changes its custom colors. It tells all the buttons on toolbars to toss their icon image cache.

This method only resets the icons for toolbars that are part of the CUI system, not for toolbars created by other code, which is why the ICustToolbar method ResetIconImages() is needed. See the method ICustToolbar::ResetIconImages.

CoreExport int OverDockRegion	(	LPPOINT	pt,
		DWORD	posType,
		int	override = `FALSE`
	)

Search for all occurrences

Remarks:: Given a point and a position type this method returns nonzero if the point is over the specified docking region; otherwise zero.

Parameters:

pt	The input point to check in screen coordinates.
posType	See CUI Frame Position Types.
override	Passing TRUE overrides the docking function so that it won't dock. Passing FALSE will cause it to dock. Also note that if the UI layout is locked, passing TRUE here will override that lock. In the code fragment below the state of the Ctrl key is checked and used as the docking override.

Sample Code:

    GetCursorPos(&pt);
    overDockRegion = GetCUIFrameMgr()->OverDockRegion(&pt, cf->GetPosType(), (GetKeyState(VK_CONTROL) & 0x8000));

CoreExport void SetMode ( int md )

Search for all occurrences

Remarks:: This method is for internal use only.

CoreExport int GetMode ( )

Search for all occurrences

Remarks:: This method is for internal use only.

CoreExport void ExpertMode ( int onOff )

Search for all occurrences

Remarks:: This method is for internal use only. Calling this method alone will not put 3ds Max in Expert mode.

CoreExport void HideFloaters ( int onOff )

Search for all occurrences

CoreExport HWND GetItemHwnd ( int id )

Search for all occurrences

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 )

Search for all occurrences

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 )

Search for all occurrences

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 )

Search for all occurrences

Remarks:: This method is for internal use only.

CoreExport int GetHorizTextButtons ( )

Search for all occurrences

Remarks:: This method is for internal use only.

CoreExport void FixedWidthTextButtons ( BOOL b )

Search for all occurrences

Remarks:: This method is for internal use only.

CoreExport int GetFixedWidthTextButtons ( )

Search for all occurrences

Remarks:: This method is for internal use only.

CoreExport void SetTextButtonWidth ( int w )

Search for all occurrences

Remarks:: This method is for internal use only.

CoreExport int GetTextButtonWidth ( )

Search for all occurrences

Remarks:: This method is for internal use only.

CoreExport int GetCount ( )

Search for all occurrences

Remarks:: Returns the number of frames that exist.

CoreExport ICUIFrame* GetICUIFrame ( int i )

Search for all occurrences

Remarks:: Returns a pointer to the CUI Frame as specified by the index passed.

Parameters:

i	The zero based index in the list of frames (between 0 and GetCount()-1).

CoreExport ICUIFrame* GetICUIFrame ( const MCHAR * name )

Search for all occurrences

Remarks:: Returns a pointer to the CUI Frame as specified by the name passed.

Parameters:

name	The name of the frame.

CoreExport ICUIFrame* GetICUIFrame	(	int	panel,
		int	rank,
		int	subrank
	)

Search for all occurrences

Remarks:: Returns a pointer to the CUI Frame as specified by the panel, rank and subrank passed.

Parameters:

panel	One of a set of values.
rank	The zero based rank index.
subrank	The zero based sub-rank index.

CoreExport int SetConfigFile ( const MCHAR * cfg )

Search for all occurrences

Remarks:: This method is for internal use only.

CoreExport const MCHAR* GetConfigFile ( )

Search for all occurrences

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

CoreExport int DeleteSystemWindows ( int toolbarsOnly = TRUE )

Search for all occurrences

Remarks:: This method is for internal use only.

CoreExport int CreateSystemWindows ( int reset = FALSE )

Search for all occurrences

Remarks:: This method is for internal use only.

CoreExport int GetSystemWindowCount ( )

Search for all occurrences

CoreExport void SetImageSize ( int size ) [inline]

Search for all occurrences

Remarks:: This method is for internal use only.

{ imageSize = size; }

CoreExport int GetImageSize ( ) [inline]

Search for all occurrences

Remarks:: This method is for internal use only.

{ return imageSize; }

CoreExport int GetButtonHeight ( int sz = 0 ) [inline]

Search for all occurrences

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

{ if(!sz) sz=imageSize; return sz==CUI_SIZE_16 ? 22 : 31; }

CoreExport int GetButtonWidth ( int sz = 0 ) [inline]

Search for all occurrences

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

{ if(!sz) sz=imageSize; return sz==CUI_SIZE_16 ? 23 : 32; }

CoreExport void SetDefaultData	(	CUIFrameMsgHandler *	msg,
		HIMAGELIST	img16,
		HIMAGELIST	img24 = `NULL`
	)

Search for all occurrences

Remarks:: This method is for internal use only.

CoreExport int GetDefaultImageListBaseIndex	(	SClass_ID	sid,
		Class_ID	cid
	)

Search for all occurrences

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
	)

Search for all occurrences

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
	)

Search for all occurrences

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 )

Search for all occurrences

Remarks:: This method is for internal use only.

CoreExport int LoadBitmapImages ( )

Search for all occurrences

Remarks:: This method is for internal use only.

CoreExport CUIFrameMsgHandler* GetDefaultMsgHandler ( ) [inline]

Search for all occurrences

Remarks:: Returns a pointer to the default CUI Frame Message Handler.

{ return defMsgHandler; }

CoreExport int ReadConfig ( )

Search for all occurrences

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

CoreExport int WriteConfig ( )

Search for all occurrences

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

CoreExport void SetLockLayout ( BOOL lock ) [inline]

Search for all occurrences

Remarks:: This method is for internal use only.

{ lockLayout = lock; }

CoreExport BOOL GetLockLayout ( ) [inline]

Search for all occurrences

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

{ return lockLayout; }

CoreExport void EnableAllCUIWindows ( int enabled )

Search for all occurrences

Remarks:: This method is for internal use only.

virtual CoreExport bool ResolveReadPath	(	const MSTR &	aFilename,
		MSTR &	aResult
	)		`[pure virtual]`

Search for all occurrences

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]`

Search for all occurrences

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

MSTR cfgFile [protected]

Search for all occurrences

CUIFrameMgr Class Reference

Detailed Description

Public Member Functions

Protected Member Functions

Protected Attributes

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation