|
CFrame Class |
Description
CFrame is responsible for creating a window which includes a menu and toolbar
(usually hosted within a rebar), and a status bar, and the "view" window. The
"view" window is a separate CWnd object assigned to the
frame with the SetView function. This view
window can be any sort of window, as long as it can be a child window of the
frame. CFrame positions the view window over the part of the frame's
client client area that remains after the toolbar and statusbar have been
displayed.
To create a frame application, inherit a CMainFrame
class from CFrame. Use the Frame sample as the starting point for your
own frame applications. Refer to the Notepad and Scribble samples for examples
on how to use these classes to create a frame application.
CFrame provides support for a single "view" window. This type of frame application is called a Single Document Interface or SDI. A Multiple Document Interface (or MDI) application allows several view windows to be displayed concurrently. Refer to the CMDIFrame class if your application requires several view windows to be displayed.
CFrame Members
Construction
| CFrame | CFrame();Constructs a CFrame object. |
Attributes
| GetFrameAccel | HACCEL GetFrameAccel() const;Returns the accelerator handle for the frame. |
| GetFrameMenu | HMENU GetFrameMenu() const;Returns the menu handle for the frame. |
| GetMenuItemPos | virtual int GetMenuItemPos(HMENU hMenu, LPCTSTR szItem);Returns the position of the menu item, given it's name. |
| GetMenuBar | virtual CMenuBar* GetMenuBar() const;Returns a pointer to the MenuBar. The MenuBar's window is a child of the rebar, which in turn is a child of the frame. The MenuBar displays a menu inside the rebar. |
| GetMenuBarTheme | MenuTheme* GetMenuBarTheme() const;Returns a pointer to the MenuTheme structure used by the frame. |
| GetMRUEntry | CString GetMRUEntry(UINT nIndex);Returns a the MRU string at the specified index. |
| GetReBar | virtual CReBar* GetReBar() const;Returns a pointer to the ReBar. The ReBar's window is a child of the frame. |
| GetReBarTheme | ReBarTheme* GetReBarTheme() const;Returns a pointer to the ReBarTheme structure used by the frame. |
| GetRegistryKeyName | CString GetRegistryKeyName() const;Returns the name of the registry key used by the applications to save its setting. |
| GetStatusBar | virtual CStatusBar* GetStatusBar() const;Returns a pointer to the StatusBar. The StatusBar's window is a child of the frame. |
| GetStatusBarTheme | StatusBarTheme* GetStatusBarTheme() const;Returns a pointer to the StatusBarTheme structure used by the frame. |
| GetStatusText | CString GetStatusText() constReturns the text displayed in the status bar. |
| GetThemeName | virtual CString GetThemeName() const;Returns the name of the current XP theme name. |
| GetTitle | CString GetTitle() const;Returns the caption (window tiltle) of the frame window. |
| GetToolBar | virtual CToolBar* GetToolBar() const;Returns a pointer to the ToolBar. The ToolBar's window is a child of either the rebar or the frame. |
| GetToolBarTheme | ToolBarTheme* GetToolBarTheme() const;Returns a pointer to the ToolBarTheme structure used by the frame. |
| GetView | CWnd* GetView() const;Returns a pointer to the CWnd object positioned over the client area of the frame, commonly referred to as the View window. |
| GetViewRect | virtual CRect GetViewRect() const;Returns the coordinates of the View window. The View window is positioned over the part of the client area of the frame that remains after the toolbar and statusbar have been displayed. |
| SetFrameMenu | void SetFrameMenu(INT ID_MENU); void SetFrameMenu(HMENU hMenu);Sets the menu handle for the frame. |
| SetMenuTheme | void SetMenuTheme(MenuTheme* pMBT);Sets the theme colors used when menu items are selected. |
| SetReBarTheme | void SetReBarTheme(ReBarTheme* pRBT);Sets the theme colors used for the ReBar. |
| SetStatusBarTheme | void SetStatusBarTheme(StatusBarTheme* pSBT);Sets the theme colors used for the StatusBar. |
| SetStatusText | void SetStatusText(LPCTSTR szText);Sets the text to be displayed in the status bar. |
| SetTitle | void SetTitle(LPCTSTR szText)Sets the title (caption) of the frame window. |
| SetToolBarTheme | void SetToolBarTheme(ToolBarTheme* pTBT);Sets the theme colors used for the ToolBar. |
| SetView | void SetView(CWnd& wndView);Sets the CWnd object which will be positioned over the client area of the frame. This is CWnd object is referred to as the view window. |
State functions
| IsMenuBarUsed | BOOL IsMenuBarUsed() const;Returns TRUE if the frame is using a menubar. |
| IsMDIFrame | virtual BOOL IsMDIFrame() const;Returns TRUE if the frame is a MDI Frame. Refer to CMDIFrame. |
| IsReBarSupported | BOOL IsReBarSupported() const;Returns TRUE if the rebar can be used. |
| IsReBarUsed | BOOL IsReBarUsed() const;Returns TRUE if the frame is using a rebar control. |
Overridables
These functions should not be called directly. The framework will call these functions as required.
| CustomDrawToolBar | virtual LRESULT CustomDrawToolBar(NMHDR* pNMHDR);Draws the ToolBar. |
| DrawReBarBkgnd | virtual BOOL DrawReBarBkgnd(CDC* pDC, CReBar* pReBar);Draws the ReBar background when ReBar themes are enabled. Returns TRUE when the default background drawing is suppressed. |
| DrawStatusBarBkgnd | virtual BOOL DrawStatusBarBkgnd(CDC* pDC, CStatusBar* pStatusBar);Draws the StatusBar background when StatusBar themes are enabled. Returns TRUE when the default background drawing is suppressed. |
| LoadRegistrySettings |
virtual BOOL LoadRegistrySettings(LPCTSTR szKeyName);Loads settings for the application from the registry. By default this loads the size and position of the frame window, and the view state of the StatusBar and ToolBar. Override this function to load other settings from the registry. |
| OnActivate | virtual void OnActivate(WPARAM wParam, LPARAM lParam);Called when the frame window is activated. |
| OnClose | virtual void OnClose();Called when the frame window is closed. |
| OnCreate | virtual void OnCreate();Called when the frame window is created. This creates the toolbar and status bar. Override this function in the derived class to customise the frame's creation. |
| OnCustromDraw | virtual LRESULT OnCustomDraw(LPNMHDR pNMHDR);Called when the frame receives a Custom Draw notification. |
| OnDestroy | virtual void OnDestroy();Called when the frame window is about to be destroyed. |
| OnDrawItem | virtual LRESULT OnDrawItem(WPARAM wParam, LPARAM lParam);Called when the frame performs owner-drawing of controls or menus. |
| OnExitMenuLoop | virtual void OnExitMenuLoop();Called then a popup menu modal loop has exited. |
| OnHelp | virtual LRESULT OnHelp();Called when the F1 key is pressed. It displays the help dialog. |
| OnInitMenuPopup | virtual void OnInitMenuPopup(WPARAM wParam, LPARAM lParam);Called when a popup menu belonging to the frame is about to be displayed. |
| OnInitialUpdate | virtual void OnInitialUpdate();Override this function to specify what happens after the frame window and all child windows are created. |
| OnMeasureItem | virtual LRESULT OnMeasureItem(WPARAM wParam, LPARAM lParam);Called when when the size of an owner drawn control or menu is required. |
| OnMenuChar | virtual LRESULT OnMenuChar(WPARAM wParam, LPARAM lParam);Called when a menu mnemonic character that doesn’t match any of the predefined mnemonics in the current menu is pressed. |
| OnMenuSelect | virtual void OnMenuSelect(WPARAM wParam, LPARAM lParam);Updates the status bar when a menu item is selected. |
| OnNotify | virtual LRESULT OnNotify(WPARAM wParam, LPARAM lParam);Called when the frame receives a notification by way of a WM_NOTIFY message. |
| OnSetFocus | virtual void OnSetFocus();Called when the frame gets keyboard focus. |
| OnRBNHeightChange | virtual LRESULT OnRBNHeightChange(LPNMHDR pNMHDR);Called when the height of the ReBar has changed. |
| OnRBNLayoutChanged | virtual LRESULT OnRBNLayoutChanged(LPNMHDR pNMHDR);Called when the layout of the ReBar has changed. |
| OnRBNMinMax | virtual LRESULT OnRBNMinMax(LPNMHDR pNMHDR);Called when a ReBar band is about to be maximized or minimized. |
| OnSysColorChange | virtual void OnSysColorChange();Called when the system colours are changed, perhaps in response to changing the system's theme. |
| OnSysCommand | virtual void OnSysCommand();Called when the user chooses a command from the Window menu (formerly known as the system or control menu) or when the user chooses the maximize button, minimize button, restore button, or close button. |
| OnTimer | virtual void OnTimer(WPARAM wParam);Called at regular intervals to update the status bar. |
| OnTBNDropDown | virtual LRESULT OnTBNDropDown(LPNMTOOLBAR pNMTB);Called when the user clicks a drop down button on a ToolBar |
| OnTTNGetDispInfo | virtual LRESULT OnTTNGetDispInfo(LPNMTTDISPINFO pNMTDI);Called when a ToolTip notification is recieved. |
| OnUndocked | virtual LRESULT OnUndocked();Called when a child window has been undocked. |
| OnViewStatusBar | virtual void OnViewStatusBar();Called when the StatusBar is to be displayed or hidden. |
| OnViewToolBar | virtual void OnViewToolBar();Called when the toolbar is to be displayed or hidden. |
| PreCreate | virtual void PreCreate(CREATESTRUCT& cs);Sets the window parameters specified in CREATESTRUCT prior to window creation. |
| PreRegisterClass | virtual void PreRegisterClass(WNDCLASS &wc);Sets the window class parameters specified in WNDCLASS prior to window creation. |
| PreTranslateMessage | virtual BOOL PreTranslateMessage(MSG* pMsg);Used to translate window messages before they are dispatched to the TranslateMessage and DispatchMessage Windows functions. |
| SaveRegistrySettings | virtual BOOL SaveRegistrySettings();Saves settings for the application to the registry. By default this saves the size and position of the frame window. Override this function to save other settings to the registry. |
| SetupToolBar | virtual void SetupToolBar();Override this function to assign resource IDs to toolbar buttons using the AddToolBarButton function. All other toolbar configuration can be specified in this function as well. |
| SetTheme | virtual void SetTheme();Sets the theme used when menu items are selected. |
Operations
| AddMenuBarBand | virtual void AddMenuBarBand();Adds a menubar to the rebar. |
| AddMenuIcon | virtual BOOL AddMenuIcon(int nID_MenuItem, HICON hIcon);Adds an icon to be used on drop down menu items from the supplied icon. |
| AddMenuIcons | AddMenuIcons(const std::vector<UINT>& MenuData, COLORREF crMask, UINT ToolBarID, UINT ToolBarDisabledID);Adds a set of icons to be used on drop down menu items from the supplied bitmap IDs. |
| AddMRUEntry | virtual void AddMRUEntry(LPCTSTR szMRUEntry);Adds the specified text to the Most Recently Used list. |
| AddToolBarBand | virtual void AddToolBarBand(CToolBar* pTB, DWORD dwStyle, UINT nID);Adds a toolbar to the rebar. |
| AddToolBarButton | virtual void AddToolBarButton(UINT nID, BOOL bEnabled = TRUE, LPCTSTR szText = 0, int iImage = -1);Adds a button to the ToolBar. |
| AdjustFrameRect | virtual void AdjustFrameRect(RECT rcView) const;Adds a resource ID to the set used by the toolbar, and specifies if the button is initially disabled. |
| CreateToolBar | virtual void CreateToolBar();Create's the frame's ToolBar. |
| DrawMenuItem | virtual void DrawMenuItem(LPDRAWITEMSTRUCT pdis);Draws the icon on drop down menu items. |
| DrawMenuItemBkgnd | virtual void DrawMenuItemBkgnd(LPDRAWITEMSTRUCT pdis);Draws the icon on drop down menu items. |
| DrawMenuItemCheckmark | virtual void DrawMenuItemCheckmark(LPDRAWITEMSTRUCT pdis);Draws the check marks on drop down menu items. |
| DrawMenuItemIcon | virtual void DrawMenuItemIcon(LPDRAWITEMSTRUCT pdis);Draws the icon on drop down menu items. |
| DrawMenuItemText | DrawMenuItemText(LPDRAWITEMSTRUCT pdis);Draws the text on drop down menu items. |
| LoadRegistryMRUSettings | virtual BOOL LoadRegistryMRUSettings(UINT nMaxMRU = 0);Loads a list of Most Recently Used files from the registry. |
| MeasureMenuItem | virtual void MeasureMenuItem(MEASUREITEMSTRUCT *pmis);Calculates the required size of the menu item when performing owner drawing. |
| RecalcLayout | virtual void RecalcLayout();Repositions the child windows of the frame, such as the toolbar, status bar and view window. |
| RemoveMRUEntry | virtual void RemoveMRUEntry(LPCTSTR szMRUEntry);Removes the specified text from the Most Recently Used list. |
| SetMenuBarBandSize | virtual void SetMenuBarBandSize();Adjusts the size of the MenuBar when the frame is resized. |
| SetMenuIcons | virtual UINT SetMenuIcons(const std::vector<UINT>& MenuData, COLORREF crMask, UINT ToolBarID, UINT ToolBarDisabledID);Replaces the set of icons to be used on drop down menu icons from the supplied bitmap IDs. |
| SetStatusIndicators | virtual void SetStatusIndicators();Updates the status bar with changes to the CAPS, NUM LOCK, and SCRL indicators. |
| SetStatusText | virtual void SetStatusText();Sets the text of the status bar. |
| SetTBImageList | virtual void SetTBImageList(CToolBar* pToolBar, CImageList* pImageList, UINT nID, COLORREF crMask);Sets the image list for the specified ToolBar. |
| SetTBImageListDis | virtual void SetTBImageListDis(CToolBar* pToolBar, CImageList* pImageList, UINT nID, COLORREF crMask);Sets the disabled image list for the specified ToolBar. |
| SetTBImageListHot | virtual void SetTBImageListHot(CToolBar* pToolBar, CImageList* pImageList, UINT nID, COLORREF crMask);Sets the hot disabled image list for the specified ToolBar. |
| SetToolBarImages | virtual void SetToolBarImages(COLORREF crMask, UINT ToolBarID, UINT ToolBarHotID, UINT ToolBarDisabledID);Sets the image lists for the toolbar from the specified bitmap IDs. |
| ShowMenu | virtual void ShowMenu(BOOL bShow);Show or hide the menu. |
| ShowStatusBar | virtual void ShowStatusBar(BOOL bShow);Show or hide the statusbar. |
| ShowToolBar | virtual void ShowToolBar(BOOL bShow);Show or hide the toolbar. |
| UpdateMRUMenu | virtual void UpdateMRUMenu();Updates the menu to display the MRU entries added by the AddMRUEntry function. |
Member Variables
| m_ShowCmd | DWORD m_ShowCmd;The initial show state of the frame, loaded from the registry. It is set to either SW_MAXIMIZE or SW_SHOW. |
| m_UseIndicatorStatus | BOOL m_UseIndicatorStatus;Set to TRUE to see indicators in status bar |
| m_UseMenuStatus | BOOL m_UseMenuStatus;Set to TRUE to see menu and toolbar updates in status bar. |
| m_UseReBar | BOOL m_UseReBar;Set to TRUE if ReBars are to be used. |
| m_UseThemes | BOOL m_UseThemes;Set to TRUE if themes are to be used. |
| m_UseToolBar | BOOL m_UseToolBar;Set to TRUE if the toolbar is used |
Base class Members
For base class members, refer to the members of CDocker.
Remarks
Refer to the Frames section for information on how to use this class to create frames.
Summary Information
| Header file | frame.h |
| Win32/64 support | Yes |
| WinCE support | No |
| Library required | Comctl32.lib |