Migrating Existing Stingray Studio Applications to Use the FoundationEx Library
Description:
Migration consists of changing some of the Microsoft or Stingray base class names, along with changing, adding, or removing some features. MFC classes to migrate include CWinApp, CFrameWnd, CMDIFrameWnd, CMDIChildWnd, CControlBar, CToolBar, CMenuBar, CStatusBar.
Stingray classes to migrate from Objective Toolkit include SECFrameWnd, SECMDIFrameWnd, SECMDIChildWnd, SECControlBar, SECToolBar, SECCustomToolBar, SECMenuBar, SECStatusBar, and SECCustomStatusBar.
Classes in the MFC Feature Pack to migrate include CWinAppEx, CFrameWndEx, CMDIFrameWndEx, CMDIChildWndEx.
Class Migration Guide:
CWinApp/CWinAppEx
Replace all occurrences of CWinApp and CWinAppEx with SFLWinAppEx. The SFLWinAppEx.h header file is located in the <StingrayInstallDir>\Include\FoundationEx\Application directory.
MyApp.h:
class MyApp : public SFLWinAppEx {};
MyApp.cpp:
BEGIN_MESSAGE_MAP(MyApp, SFLWinAppEx), etc.
Sections in the InitInstance() function of the application class can replace Ole Lib, Registry, and other common initialization sections with the following:
// MyApp::InitInstance()
SFLWinAppEx::InitInstance();
SFLWinAppEx::Initialize();
Existing Registry Entries
If SFLWinAppEx::Initialize() is not called, it is important to set up registry entries to store application settings. This is accomplished by calling SetRegistryKey(_T(“Your Application’s Registry Entry”)) in InitInstance().
CFrameWnd/CFrameWndEx
Replace all occurrences of CFrameWnd, CFrameWndEx, and SECFrameWnd with SFLFrameWndEx. The SFLFrameWndEx.h header file is located in the <StingrayInstallDir>\Include\FoundationEx\Frame directory.
MainFrm.h:
class CMainFrame : public SFLFrameWndEx {};
MainFrm.cpp:
BEGIN_MESSAGE_MAP(CMainFrame, SFLFrameWndEx), etc.
NOTE >> EnableBmpMenus() and EnableCustomCaption() are no longer used.
CMDIFrameWnd/CMDIFrameWndEx/SECMDIFrameWnd/SECWorkbookWnd
Replace all occurrences of CMDIFrameWnd, CMDIFrameWndEx, and SECMDIFrameWnd with SFLMDIFrameWndEx. Replace all occurrences of SECWorkbookWnd with SFLMDIFrameWndEx. The SFLMDIFrameWndEx.h header file is located in the <StingrayInstallDir>\Include\FoundationEx\Frame directory.
MainFrm.h
class CMainFrame : public SFLMDIFrameWndEx {};
MainFrm.cpp
BEGIN_MESSAGE_MAP(CMainFrame, SFLMDIFrameWndEx), etc.
NOTE >> EnableBmpMenus() and EnableCustomCaption() are no longer used.
CMDIChildWnd/CMDIChildWndEx/SECMDIChildWnd/SECWorksheet
Replace all occurrences of CMDIChildWnd, CMDIChildWndEx, SECMDIChildWnd, and SECWorksheet with SFLMDIChildWndEx. The SFLMDIChildWndEx.h header file is located in the <StingrayInstallDir>\Include\FoundationEx\Frame directory.
ChildFrm.h
class CChildFrame : public SFLMDIChildWndEx {};
CChildFrm.cpp
BEGIN_MESSAGE_MAP(CChildFrame, SFLMDIChildWndEx), etc.
CFormView Child View Windows
Objective Grid applications that use a CFormView-derived view class should not migrate to SFLMDIChildWndEx in the CMultiDocTemplate section of the application’s InitInstance(). Instead they should use the standard CMDIChildWnd class.
CMultiDocTemplate* pDocTemplate = new CMultiDocTemplate(
IDR_1STGRITYPE,
RUNTIME_CLASS(C1stGridS1Doc),
RUNTIME_CLASS(CMDIChildWndEx), // Don’t use SFLMDIChildWndEx
RUNTIME_CLASS(C1stGridS1View));
SECFDIFrameWnd/SECFDIChildWnd => SFLFDIFrameWndEx/SFLFDIChildWndEx
For Floating Document Interface (FDI) applications, replace all instances of SECFDIFrameWnd with SFLFDIFrameWndEx. Likewise, replace all instances of SECFDIChildWnd with SFLFDIChildWndEx. The header files for SFLFDIFrameWndEx and SFLFDIChildWndEx are located in the <StingrayInstallDir>\Include\Frame directory.
NOTE >> The function EnableCustomCaption() is no longer used.
For further information on using the SFLFDIFrameWndEx and SFLFDIChildWndEx classes, refer to the FDIEx sample located in the <StingrayInstallDir>\Samples\FoundationEx\FDIEx directory.
SECToplevelFrame => SFLTopLevelFrameEx
For Top Level Frame classes, replace all instances of SECToplevelFrame with SFLTopLevelFrameEx. The header files for SFLTopLevelFrameEx are located in the <StingrayInstallDir>\Include\Frame directory.
CControlBar/SECControlBar => SFLDockablePaneEx
Replace all occurrences of CControlBar and SECControlBar with SFLDockablePaneEx. The SFLDockablePaneEx.h header file is located in the <StingrayInstallDir>\Include\FoundationEx\Docking directory.
Also, change all instances of DockControlBar() and DockControlBarEx() to DockPane().
The Create() function call has slightly changed parameters that will need to be adjusted according to your application. The CBRS_EX_XXXXX styles no longer work with SFLDockablePaneEx.
Docking Pane Creation
The create function for docking panes is slightly different than the one previously used for ControlBars. There follows an example of the kind of changes you need to make:
m_wndDockPane.Create(this, _T("Docking Window"), CBRS_BOTTOM | WS_VISIBLE | CBRS_SIZE_DYNAMIC | CBRS_TOOLTIPS, CBRS_EX_STDCONTEXTMENU | CBRS_EX_ALLOW_MDI_FLOAT | CBRS_EX_COOL | CBRS_EX_BORDERSPACE | CBRS_EX_FLATSTYLE, ID_DOCKINGWINDOW))
change to:
m_wndDockPane.Create(_T("Docking Window"), this, CRect(0, 0, 200, 200), TRUE, ID_DOCKINGWINDOW, WS_CHILD | WS_VISIBLE | WS_CLIPSIBLINGS | WS_CLIPCHILDREN | CBRS_LEFT | CBRS_FLOAT_MULTI))
NOTE >> CBRS_EX_* styles are no longer used.
Showing and Hiding Docking Windows
Docking windows are shown and hidden using the ShowPane() function. The previous ToggleVisibility() function has been replaced by ShowPane().
CToolBar/SECToolBar/SECCustomToolBar/CMFCToolBar => SFLToolBarEx
Replace all occurrences of CToolBar, SECToolBar, SECCustomToolBar and CMFCToolBar with SFLToolBarEx. The SFLToolBarEx.h header file is located in the <StingrayInstallDir>\Include\FoundationEx\UI directory.
Toolbar Styles
Change uses of SetBarStyle() and GetBarStyle() to SetPaneStyle() and GetPaneStyle() respectively.
SECControlBarManager and SECToolBarManager
The SECControlBarManager and the SECToolBarManager classes are not used with FoundationEx. It is not necessary to use a docking manager. However, to use a docking manager, use the DockingManager class to handle management of toolbars in the MFC Feature Pack framework. A demonstration of using the DockingManager is found in:
UINT SFLDockablePaneEx::GetUniqueID(CWnd* pFrameWnd,UINT nBaseID)
When migrating applications, sections using the SECControlBarManager or SECToolBarManager should be commented out or removed.
/* COMMENT OUT…
ASSERT(m_pControlBarManager != NULL);
ASSERT_KINDOF(SECToolBarManager, m_pControlBarManager);
SECToolBarManager* pMgr = (SECToolBarManager*)m_pControlBarManager;
//VERIFY(pMgr->LoadToolBarResource(MAKEINTRESOURCE(IDR_MAINFRAME),
//MAKEINTRESOURCE(IDR_MAINFRAMELARGE)));
pMgr->AddToolBarResource(MAKEINTRESOURCE(IDR_MAINFRAME1),
MAKEINTRESOURCE(IDR_MAINFRAMELARGE1));
pMgr->AddToolBarResource(MAKEINTRESOURCE(IDR_MAINFRAME2),
MAKEINTRESOURCE(IDR_MAINFRAMELARGE2));
VERIFY(pMgr->LoadToolBarResource());
pMgr->SetButtonMap(btnMap);
pMgr->DefineDefaultToolBar(AFX_IDW_TOOLBAR, _T("File"),
NUMELEMENTS(fileButtons),
fileButtons,
CBRS_ALIGN_ANY,
AFX_IDW_DOCKBAR_TOP);
// Etc…
*/
Button Maps
Button maps are currently not implemented for use with SFLToolBarEx. These sections should be commented out.
Array of Button IDs
Arrays of button ID’s used with SFLToolBarEx should match the order of any associated bitmaps. A bitmap such as the following might have the following defined button array:
static UINT BASED_CODE fileButtons[] =
{
ID_FILE_NEW,
ID_FILE_OPEN,
ID_FILE_SAVE,
ID_SEPARATOR,
ID_EDIT_CUT,
ID_EDIT_COPY,
ID_EDIT_PASTE,
ID_FILE_PRINT,
ID_SEPARATOR,
ID_APP_ABOUT,
};
Toolbar Customization
The SECToolBarSheet class is not used with the SFLToolBarEx class. Customization of toolbars is accomplished with the following code:
CMFCToolBarsCustomizeDialog* pCustDlg = new CMFCToolBarsCustomizeDialog(this, TRUE, AFX_CUSTOMIZE_MENU_SHADOWS | AFX_CUSTOMIZE_TEXT_LABELS | AFX_CUSTOMIZE_MENU_ANIMATIONS);
pCustDlg->EnableUserDefinedToolbars();
pCustDlg->Create();
Create Individual Toolbar Resources for each Toolbar needed
Toolbars that were created using DefineDefaultToolbar() will need to be separated into individual bitmap/toolbar resources. Separate SFLToolBarEx members should be added to the application to handle the multiple separate toolbars.
// CMainFrame.h
SFLToolBarExm_wndFileToolBar;
SFLToolBarExm_wndEditToolBar;
SFLToolBarExm_wndViewToolBar;
// CMainFrame::OnCreate()
if(!m_wndFileToolBar.Create(this,
WS_VISIBLE | CBRS_TOP |
CBRS_TOOLTIPS | CBRS_FLYBY |
CBRS_HIDE_INPLACE |
CBRS_SIZE_DYNAMIC | CBRS_GRIPPER |
CBRS_BORDER_3D, ID_FILE_TOOLBAR) ||
!m_wndFileToolBar.LoadToolBar(IDR_FILE_MAINFRAME))
{
return -1;
}
if(!m_wndEditToolBar.Create(this,
WS_VISIBLE | CBRS_TOP |
CBRS_TOOLTIPS | CBRS_FLYBY |
CBRS_HIDE_INPLACE |
CBRS_SIZE_DYNAMIC | CBRS_GRIPPER |
CBRS_BORDER_3D, ID_EDIT_TOOLBAR) ||
!m_wndEditToolBar.LoadToolBar(IDR_EDIT_MAINFRAME))
{
return -1;
}
if(!m_wndViewToolBar.Create(this,
WS_VISIBLE | CBRS_TOP |
CBRS_TOOLTIPS | CBRS_FLYBY |
CBRS_HIDE_INPLACE |
CBRS_SIZE_DYNAMIC | CBRS_GRIPPER |
CBRS_BORDER_3D, ID_VIEW_TOOLBAR) ||
!m_wndViewToolBar.LoadToolBar(IDR_VIEW_MAINFRAME))
{
return -1;
}
// File Docking
m_wndFileToolBar.EnableDocking(CBRS_ALIGN_ANY);
DockPane(&m_wndFileToolBar);
// Edit Docking
m_wndEditToolBar.EnableDocking(CBRS_ALIGN_ANY);
DockPane(&m_wndEditToolBar);
// View Docking
m_wndViewToolBar.EnableDocking(CBRS_ALIGN_ANY);
DockPane(&m_wndViewToolBar);
NOTE >> Icons are easily created and edited using the free Axialis IconWorksop software from:
www.axialis.com.
Showing and Hiding toolbars
Toolbars are shown and hidden using the function ShowPane():
CMainFrame::OnViewToolbar()
{
m_wndFileToolBar.ShowPane(!m_wndFileToolBar.IsVisible());
}
NOTE >> ShowControlBar() is not used with SFLToolBarEx.
CMenuBar/SECMenuBar => SFLMenuBarEx
Replace all occurrences of CMenuBar and SECMenuBar with SFLMenuBarEx. The SFLMenuBarEx.h header file is located in the <StingrayInstallDir>\Include\FoundationEx\UI directory.
NOTE >> Previously, Objective Toolkit frame classes provided a member menubar. This is no longer the case. If a menubar is not present, one should be created. Refer to the Tips and Troubleshooting section for information on applications that do not have a menubar.
CStatusBar/CMFCStatusBar/SECStatusBar/SECCustomStatusBar => SFLStatusBarEx
Replace all occurrences of CStatusBar, CMFCStatusBar, SECStatusBar, and SECCustomStatusBar with SFLStatusBarEx. The SFLStatusBarEx.h header file is located in the <StingrayInstallDir>\Include\FoundationEx\UI directory.
SECDialogBar => SFLPaneDialogEx
Replace all occurrences of SECDialogBar with SFLPaneDialogEx. The SFLPaneDialogEx.h header file is located in the <StingrayInstallDir>\Include\FoundationEx\Dialog directory.
