Class ICUIFrame
See Also: Class CUIFrameMgr, Class CUIFrameMsgHandler, Class ICustToolbar, Class ICustomControl.
class ICUIFrame : public ICustomControl
Description:
This class is available in release 3.0 and later only.
This class provides access to an individual CUI Frame (the name given to the windows that contain toolbars, menus, the command panel, etc.)
To create a floating tool palette, for example, you create a CUIFrame, create a toolbar, and then attach the two (similar to creating a custom edit field, and custom spinner, then attaching the two). This is done using the method ICustToolbar::LinkToCUIFrame().
When a Toolbar is part of a CUI frame it's called a Tool Palette. Tool Palettes can either float or dock (whereas a Toolbar must be placed by the developer in a dialog using the resource editor).
The following global functions are not part of this class but are available for use:
Function:
ICUIFrame *GetICUIFrame(HWND hCtrl);
Remarks:
Initializes the pointer to the CUI Frame control.
Parameters:
HWND hCtrl
The window handle of the control.
Function:
void ReleaseICUIFrame(ICUIFrame *icf);
Remarks:
Releases the specified control.
Parameters:
ICUIFrame *icf
Points to the frame to release.
Function:
HWND CreateCUIFrameWindow(HWND hParent, TCHAR *title, int x, int y, int cx, int cy);
Remarks:
Creates a CUI Frame Window with the specified window handle, size and title parameters. Values of 0 may be passed for x, y, cx and cy. This indicates that the initial size doesn't matter. For example, when the 3ds max CUI is created initially everything is docked. 3ds max then calls CUIFrameMgr::RecalcLayout() which computes all the sizes. Thus the values passed don’t matter since they are all going to be recalculated anyway.
Parameters:
HWND hParent
The handle of the parent window for the frame.
TCHAR *title
The title for the frame. This effectively calls SetName() below to establish a name for the frame.
int x
The x coordinate of the upper left corner.
int y
The y coordinate of the upper left corner.
int cx
The x size.
int cy
The y size.
Return Value:
If the function succeeds, the return value is the window handle to the dialog box. If the function fails, the return value is NULL.
Methods:
public:
Prototype:
virtual void SetName(TCHAR *name)=0;
Remarks:
Sets the name for the frame. This name shows up as a tooltip and also on the window border if the frame is floated. Note that the name is also used to store position information in the CUI file. Therefore developers must use a name and not simply set it to NULL.
Parameters:
TCHAR *name
The name to set.
Prototype:
virtual TCHAR *GetName()=0;
Remarks:
Returns the name of the frame.
Prototype:
virtual void SetPosType(DWORD t)=0;
Remarks:
Sets the position type. This determines the possible locations for the frame.
Parameters:
DWORD t
The position to set. See List of CUI Frame Position Types.
Prototype:
virtual DWORD GetPosType()=0;
Remarks:
Retuns a DWORD which describes the position options for this CUI Frame. See List of CUI Frame Position Types.
Prototype:
virtual void SetPosRank(int rank, int subrank=0)=0;
Remarks:
This method is for internal use only. Developers must not assign the rank and subrank as these are computed internally. Developers should create their toolbars 'floating'. Then when a user docks the toolbar it will be docked automatically when 3ds max starts up the next time.
Prototype:
virtual int GetPosRank()=0;
Remarks:
Returns the positon rank. Consider three docked toolbars, one alone on the top line, and two side by side on the line below. The top toolbar would have a rank of 0 (and a subrank of 0). The toolbar on the left in the line below would have a rank of 1 and a subrank of 0. The toolbar beside it to the right would have a rank of 1 and a subrank of 1.
Prototype:
virtual int GetPosSubrank()=0;
Remarks:
Returns the position subrank. See GetPosRank() above.
Prototype:
virtual BOOL IsFloating()=0;
Remarks:
Returns TRUE if the frame is floating (not docked); otherwise FALSE.
Prototype:
virtual void Hide(BOOL b)=0;
Remarks:
Sets the frame to hidden or not. Note that if a developer is doing something like showing their toolbars at BeginEditParams() and hiding them at EndEditParms() then this method can be used. In such a case, if the toolbar is docked then RecalcLayout() needs to be called to update the layout. If the toolbars are floating then RecalcLayout() does not need to be called.
Parameters:
BOOL b
TRUE for hidden; FALSE for not hidden.
Prototype:
virtual BOOL IsHidden()=0;
Remarks:
Returns TRUE if the frame is hidden; FALSE if visible.
Prototype:
virtual void SetCurPosition(DWORD pos)=0;
Remarks:
This method is for internal use only.
Prototype:
virtual DWORD GetCurPosition()=0;
Remarks:
Returns the current postion of the frame. 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.
CUI_FLOATING
The frame is floating (not docked).
Prototype:
virtual void SetContentType(DWORD t)=0;
Remarks:
Sets the frame contents type. This specifies if this frame holds a toolbar, menu or a floating panel.
Parameters:
DWORD t
One or more of the following flags:
CUI_TOOLBAR
Set if frame holds toolbars and / or tool palettes.
CUI_MENU
This is used internally to set if the frame holds a menu. Note: Developers should not create their own menus. 3ds max assumes that only one menu exists.
CUI_HWND
Set if frame hold a generic window handle. The command panel (which can be floated) is an example of a generic window.
Prototype:
virtual DWORD GetContentType()=0;
Remarks:
Returns a value which indicates the frame contents type. One of the following flags:
CUI_TOOLBAR
Set if frame holds toolbars and / or tool palettes.
CUI_MENU
Set if the frame holds a menu.
CUI_HWND
Set if frame hold a generic window handle.
Prototype:
virtual void SetContentHandle(HWND hContent)=0;
Remarks:
Sets the content handle. This is the window handle for the toolbar, or menu handle for a menu. Developers typically create Tool Palettes by linking a toolbar to a CUIFrame using ICustToolbar::LinkToCUIFrame() and do not need to call this method as it's done automatically.
Parameters:
HWND hContent
The handle to set.
Prototype:
virtual HWND GetContentHandle()=0;
Remarks:
Returns the content handle.
Prototype:
virtual void SetTabbedToolbar(BOOL b)=0;
Remarks:
Sets if this frame represents a tabbed toolbar. A tabbed toolbar may have individual tabs added and deleted.
Parameters:
BOOL b
TRUE for tabbed; FALSE for not tabbed.
Prototype:
virtual BOOL GetTabbedToolbar()=0;
Remarks:
Returns TRUE if this frame is a tabbed toolbar; otherwise FALSE.
Prototype:
virtual void AddToolbarTab(HWND hTBar, CUIFrameMsgHandler *msgHandler, TCHAR *name, int pos = -1)=0;
Remarks:
Adds the toolbar tab whose window handle is passed to the list of tabs maintained by this class.
Parameters:
HWND hTBar
The window handle of the toolbar tab to add.
CUIFrameMsgHandler *msgHandler
The message handler for the tab or NULL if not used.
TCHAR *name
The name for the tab.
int pos = -1
The position for the tab. This is the zero based index where 0 is at left edge of those in the frame and the max value is GetToolbarCount()-1. A value of -1 adds the tab to the end of the list of tabs. Also, for example, if you specifiy a value of 0 for an existing tabbed toolbar, the new tab is inserted at position 0 and the others are moved to the right.
Prototype:
virtual void DeleteToolbarTab(int pos)=0;
Remarks:
Deletes the specified toolbar tab.
Parameters:
int pos
Specifies the position of the tab to delete. This is the zero based index where 0 is at left edge of those in the frame and the max value is GetToolbarCount()-1.
Prototype:
virtual int GetToolbarCount()=0;
Remarks:
Returns the number of toolbar tabs in this frame.
Prototype:
virtual HWND GetToolbarHWnd(int pos)=0;
Remarks:
Returns the window handle of the toolbar tab whose position is passed.
Parameters:
int pos
Specifies the position of the tab. This is the zero based index where 0 is at left edge of those in the frame and the max value is GetToolbarCount()-1.
Prototype:
virtual TCHAR *GetTabName(int pos)=0;
Remarks:
Returns the name of the specified toolbar tab.
Parameters:
int pos
Specifies the position of the tab. This is the zero based index where 0 is at left edge of those in the frame and the max value is GetToolbarCount()-1.
Prototype:
virtual void SetCurrentTab(int pos)=0;
Remarks:
Sets the currently active tab.
Parameters:
int pos
Specifies the position of the tab. This is the zero based index where 0 is at left edge of those in the frame and the max value is GetToolbarCount()-1.
Prototype:
virtual int GetCurrentTab()=0;
Remarks:
Returns the postion of the currently active tab. This is the zero based index where 0 is at left edge of those in the frame and the max value is GetToolbarCount()-1.
Prototype:
virtual int GetSize(int sizeType, int dir, int orient)=0;
Remarks:
Returns the size of this frame for the specified size type, direction (width or height) and orientation.
Note: If this frame has a custom message handler (a CUIFrameMsgHandler object, it's ProcessMessage() method is called passing CUI_POSDATA_MSG which is used to determine the size.
Parameters:
int sizeType
The size type. See List of CUI Frame Size Types.
int dir
The direction of the frame.
CUI_HORIZ: Width.
CUI_VERT: Height.
int orient
The orientation. See List of CUI Frame Orientations.
Prototype:
virtual BOOL InstallMsgHandler(CUIFrameMsgHandler *msgHandler)=0;
Remarks:
Installs a custom message processing routine.
Parameters:
CUIFrameMsgHandler *msgHandler
Points to the handler to install. See Class CUIFrameMsgHandler for details.
Return Value:
TRUE on success; otherwise FALSE.
Prototype:
virtual BOOL SetMenuDisplay(int md)=0;
Remarks:
Sets the menu display state.
Parameters:
int md
One of the following values:
CUI_MENU_HIDE
CUI_MENU_SHOW_ENABLED
CUI_MENU_SHOW_DISABLED
Prototype:
virtual int GetMenuDisplay()=0;
Remarks:
Returns the state of the menu display. One of the following values:
CUI_MENU_HIDE
CUI_MENU_SHOW_ENABLED
CUI_MENU_SHOW_DISABLED
Prototype:
virtual void SetSystemWindow(BOOL b)=0;
Remarks:
System windows are those that come up automatically inside MAX. So command panel, the main toolbar, the tab panel and the main menu are all system windows. It is not therefore appropriate for developers to declare themselves as system windows and this method should not be called passing TRUE.
Parameters:
BOOL b
TRUE to set as a system window; otherwise FALSE.
Prototype:
virtual BOOL GetSystemWindow()=0;
Remarks:
Returns TRUE if this CUIFrame is a system window; otherwise FALSE. See SetSystemWindow() above.
Prototype:
virtual BOOL ReadConfig(TCHAR *cfg, int startup=FALSE)=0;
Remarks:
This method is for internal use only.
Prototype:
virtual void WriteConfig(TCHAR *cfg)=0;
Remarks:
This method is for internal use only.