Class CUIFrameMgr
See Also: Class ICUIFrame, Class CUIFrameMsgHandler, Class ICustToolbar, Class ICustomControl, Class ICustStatus, Class MAXBmpFileIcon.
class CUIFrameMgr : public BaseInterfaceServer
Description:
This class is available in release 3.0 and later only.
***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.
The following global functions are not part of this class but are available for use:
Function:
CUIFrameMgr *GetCUIFrameMgr();
Remarks:
Returns a pointer to the CUIFrameMgr which controls the overall operation of CUI Frames (the windows which contain toolbars, menus, the command panel, etc).
Function:
void DoCUICustomizeDialog();
Remarks:
This global function presents the Customize User Interface dialog.
Function:
BOOL AllFloatersAreHidden();
Remarks:
This global function is available in release 4.0 and later only.
Returns TRUE if all floaters are hidden; otherwise FALSE.
Methods:
public:
Prototype:
CUIFrameMgr();
Remarks:
Constructor.
Prototype:
~CUIFrameMgr();
Remarks:
Destructor.
Prototype:
CUIFrameMsgHandler *GetDefaultMsgHandler();
Remarks:
Returns a pointer to the default CUI Frame Message Handler.
Prototype:
void SetAppHWnd(HWND hApp);
Remarks:
This method is for internal use only.
Prototype:
TCHAR *GetCUIDirectory();
Remarks:
Returns the directory name of the custom user interface (CUI) file location.
Prototype:
void ProcessCUIMenu(HWND hWnd, int x, int y);
Remarks:
This brings up the CUI right click menu (wth the Add Tab, Delete Tab, etc selections). Also see the global function DoCUICustomizeDialog().
Parameters:
HWND hWnd
The handle of the window there the mouse was clicked.
int x
The x coordinate of the mouse when right clicked.
int y
The y coordinate of the cursor when right clicked.
Prototype:
void DockCUIWindow(HWND hWnd, int panel, RECT *rp = NULL, int init = FALSE);
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 hWnd
The handle of the window to dock.
int 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.
RECT *rp = NULL
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.
int init = FALSE
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).
Prototype:
void FloatCUIWindow(HWND hWnd, RECT *rp = NULL, int init = FALSE);
Remarks:
Floats (un-docks) the specified CUI Window.
Parameters:
HWND hWnd
The window to float.
RECT *rp = NULL
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.
int init = FALSE
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).
Prototype:
virtual void GetFloatingCUIFrameSize(SIZE *sz, int rows=1)=0;
Remarks:
Computes the required size of a floating CUI Frame which is linked to a toolbar. The values returned will be zero if the frame is not linked to a toolbar.
Parameters:
SIZE *sz
The computed size is returned here. sz.cx is the width, sz.cy is the height.
int rows=1
The number of rows for the toolbar used in the computation.
Prototype:
void SetReservedSize(int panel, int size);
Remarks:
This method is for internal use only.
Prototype:
int GetReservedSize(int panel);
Remarks:
This method is for internal use only.
Prototype:
int GetPanelSize(int panel, int incReserved = FALSE);
Remarks:
This method is for internal use only.
Prototype:
void RecalcLayout(int entireApp=FALSE);
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 MAX.
Parameters:
int entireApp=FALSE
TRUE to recalculate the entire application, including the viewports. This can be expensive (basically like an Interface::ForceCompleteRedraw()); FALSE will recalculate the top, botton, left and right panels but won't redraw the viewports.
Prototype:
void DrawCUIWindows(int panels=CUI_ALL_PANELS);
Remarks:
This method redraws the specified panels. Typically developers don't need to call this method.
Parameters:
int panels=CUI_ALL_PANELS
See List of CUI Docking Panel Locations.
Prototype:
void SetMacroButtonStates(BOOL force);
Remarks:
This method is available in release 4.0 and later only.
This is a very important method. It redraws all the visible CUI buttons in 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:
BOOL 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.
Prototype:
void ResetIconImages();
Remarks:
This method is available in release 4.0 and later only.
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.
Prototype:
int OverDockRegion(LPPOINT pt, DWORD posType, int override = FALSE);
Remarks:
Given a point and a position type this method returns nonzero if the point is over the specified docking region; otherwise zero.
Parameters:
LPPOINT pt
The input point to check in screen coordinates.
DWORD posType
See List of CUI Frame Position Types.
int override = FALSE
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));
Prototype:
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:
int id
The ID of the control.
Prototype:
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:
int id
The ID of the control.
Prototype:
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:
int id
The ID of the control.
Prototype:
ICUIFrame *GetICUIFrame(int i);
Remarks:
Returns a pointer to the CUI Frame as specified by the index passed.
Parameters:
int i
The zero based index in the list of frames (between 0 and GetCount()-1).
Prototype:
ICUIFrame *GetICUIFrame(TCHAR *name);
Remarks:
Returns a pointer to the CUI Frame as specified by the name passed.
Parameters:
TCHAR *name
The name of the frame.
Prototype:
ICUIFrame *GetICUIFrame(int panel, int rank, int subrank);
Remarks:
Returns a pointer to the CUI Frame as specified by the panel, rank and subrank passed.
Parameters:
int panel
One of the following values:
int rank
The zero based rank index.
int subrank
The zero based sub-rank index.
Prototype:
TCHAR *GetConfigFile();
Remarks:
This returns the path to the CUI file in use. This may be a UNC name.
Prototype:
int GetButtonHeight(int sz=0);
Remarks:
Returns the bitmap button image height for the specified size.
Parameters:
int sz=0
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
Prototype:
int GetButtonWidth(int sz=0);
Remarks:
Returns the bitmap button image width for the specified size.
Parameters:
int sz=0
The size to check. One of the following values:
CUI_SIZE_16
CUI_SIZE_24
Prototype:
void SetMode(int md);
Remarks:
This method is for internal use only.
Prototype:
int GetMode();
Remarks:
This method is for internal use only.
Prototype:
void ExpertMode(int onOff);
Remarks:
This method is for internal use only. Calling this method alone will not put 3ds max in Expert mode.
Prototype:
void HorizTextButtons(BOOL b);
Remarks:
This method is for internal use only.
Prototype:
int GetHorizTextButtons();
Remarks:
This method is for internal use only.
Prototype:
void FixedWidthTextButtons(BOOL b);
Remarks:
This method is for internal use only.
Prototype:
int GetFixedWidthTextButtons();
Remarks:
This method is for internal use only.
Prototype:
void SetTextButtonWidth(int w);
Remarks:
This method is for internal use only.
Prototype:
int GetTextButtonWidth();
Remarks:
This method is for internal use only.
Prototype:
int GetCount();
Remarks:
Returns the number of frames that exist.
Prototype:
int SetConfigFile(TCHAR *cfg);
Remarks:
This method is for internal use only.
Prototype:
int DeleteSystemWindows(int toolbarsOnly = TRUE);
Remarks:
This method is for internal use only.
Prototype:
int CreateSystemWindows(int reset = FALSE);
Remarks:
This method is for internal use only.
Prototype:
void SetImageSize(int size);
Remarks:
This method is for internal use only.
Prototype:
int GetImageSize();
Remarks:
This method is for internal use only.
Prototype:
void SetDefaultData(CUIFrameMsgHandler *msg, HIMAGELIST img16, HIMAGELIST img24=NULL);
Remarks:
This method is for internal use only.
Prototype:
int GetDefaultImageListBaseIndex(SClass_ID sid, Class_ID cid);
Remarks:
This method is available in release 4.0 and later only.
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.
Prototype:
TSTR* GetDefaultImageListFilePrefix(SClass_ID sid, Class_ID cid);
Remarks:
This method is available in release 4.0 and later only.
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.
Prototype:
int AddToRawImageList(TCHAR* pFilePrefix, int sz, HBITMAP image, HBITMAP mask);
Remarks:
This method is available in release 4.0 and later only.
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.
Prototype:
int LoadBitmapFile(TCHAR *filename);
Remarks:
This method is for internal use only.
Prototype:
int LoadBitmapImages();
Remarks:
This method is for internal use only.
Prototype:
int ReadConfig();
Remarks:
Plug-In developers should not call this method -- it is for internal use only.
Prototype:
int WriteConfig();
Remarks:
Plug-In developers should not call this method -- it is for internal use only.
Prototype:
void SetLockLayout(BOOL lock);
Remarks:
This method is for internal use only.
Prototype:
BOOL GetLockLayout();
Remarks:
Returns TRUE if the layout is locker; FALSE if unlocked.
Prototype:
void EnableAllCUIWindows(int enabled);
Remarks:
This method is for internal use only.