Rogue Wave Knowledge Base
Search:    
Browse by category:
Knowledgebase | Glossary | Ask a Question |

Stingray Studio Migration Guide for the MFC 9 Feature Pack

Article ID: 1445
Last updated: 06 Nov, 2009
Revision: 1
print  Print
share  Share
Views: 15745
Posted: 26 Oct, 2009
by Rehme L.
Updated: 06 Nov, 2009
by Rehme L.

1         Introduction

1.1       What is the FoundationEx library?

The Stingray Studio FoundationEx library is a new set of application, docking, frame, and user interface classes built on the Microsoft Visual Studio 2008 SP1 MFC 9 Feature Pack. The FoundationEx library is designed to be used with all Stingray Studio products. Some existing applications previously built with Stingray Studio 10.1 and earlier will need to be migrated to use the FoundationEx library in order to take advantage of any new features in the MFC 9 Feature Pack.

For more information on the MFC 9 Feature Pack visit:

http://msdn.microsoft.com/en-us/library/bb982354.aspx

 

Note: This is not meant to be a comprehensive migration guide, there will be some custom application situations which are not covered in this migration guide and will require a more coding effort. A collection of FoundationEx samples are provided in the <StingrayInstallDir>\Samples\FoundationEx\ directory to help give a better understanding of some common types of application migrations.

1.2       Features of the FoundationEx library

The FoundationEx library adds features for migration of existing Stingray Studio applications built on Stingray Studio 10.1 and earlier to the MFC 9 Feature Pack framework. Features include categories such as Application, Dialog, Docking, Frame, and User Interface.

1.2.1       Application Features

Application level features are found in the SFLWinAppEx class which is derived from the new CWinAppEx class.

1.2.1.1     Initialization

As a convenience we’ve provided an Initialize() function which will set up your application with common defaults. It is defined and defaulted as follows:

BOOL Initialize( BOOL bInitOleLibs        = TRUE,

           BOOL bCtrlContainer      = TRUE,

           BOOL bRegistryKey        = TRUE,

           BOOL bInitKeyboardMgr    = TRUE,

           BOOL bInitMouseMgr       = TRUE,

           BOOL bInitContextMgr     = TRUE,

           BOOL bInitTooltipMgr     = TRUE,

           BOOL bInitShellMgr       = TRUE );

MyApp.cpp:

BEGIN_MESSAGE_MAP(MyApp, SFLWinAppEx), etc.

 

MyApp::InitInstance()

{

SFLWinAppEx::InitInstance();

// Set Registry variables, if needed, before Initialize().

SFLWinAppEx::Initialize(); // Using defaults

//…

}

1.2.2       Right to Left Layout Features

Right to left layout features are part of the new SFLFrameWndEx and SFLMDIFrameWndEx classes.

Frames can change layout to Right to Left by calling SetRTL(). Also, the frame the SFLFrameWndEx and SFLMDIFrameWndEx classes have command handlers for the menu command ID_SFLEX_APPSTYLE_LAYOUT_RTL.

Note: When calling SetRTL() manually, it should be called from the frame class, passing the frames this pointer and specify TRUE that the frame is the top level call.

1.2.3       Frame Features

Frame features are part of the new SFLFrameWndEx and SFLMDIFrameWndEx classes. Enhancements to the application frame include:

1.2.3.1     Look and Feel

The Look and Feel of the application frame and controls used in the MFC 9 Feature Pack can be set with the SetAppplicationStyle() function.

 

 

MainFrm.h:

class CMainFrame : public SFL[MDI]FrameWndEx {};

 

MainFrm.cpp :

BEGIN_MESSAGE_MAP(CMainFrame, SFL[MDI]FrameWndEx), etc.

 

CMainFrame::CMainFrame()

{

  // An example of setting the application

  // look and feel to Office Black.

  SFL[MDI]FrameWndEx::

     SetApplicationStyle(SFLAppStyleEx::

                         APPSTYLE_OFFICE_BLACK);

}

 

Applications that are generated with the Visual Studio 2008 SP1 application wizard can be enabled with visual styles, which will generate functions such as OnApplicationLook() in the main frame class. Optionally, these functions and message handlers can be removed and replaced with the mappings provided by SFLFrameWndEx and SFLMDIFrameWndEx.

                To handle application look and feel command messages, send the following IDs which are defined in SFLResEx.h:

ID_SFLEX_APPSTYLE_WIN_2000,

ID_SFLEX_APPSTYLE_WIN_XP,

ID_SFLEX_APPSTYLE_OFFICE_XP,

ID_SFLEX_APPSTYLE_OFFICE_2003,

ID_SFLEX_APPSTYLE_OFFICE_BLUE,

ID_SFLEX_APPSTYLE_OFFICE_BLACK,

ID_SFLEX_APPSTYLE_OFFICE_SILVER,

ID_SFLEX_APPSTYLE_OFFICE_AQUA,

ID_SFLEX_APPSTYLE_VS_2005

 

It may be convenient to copy and paste the ‘Style’ section of the IDR_SFLEX_MAINFRAME resource into the application resource. It may also be necessary to reassign the above IDs to the cut and pasted ‘Style’ menu option, as these have a tendency to get redefined in the local applications resource.h.

 

The enumeration values that are passed to SetApplicationStyle() are the same as posted above without the “ID_”.  Ex,

SetApplicationStyle(SFLAppStyleEx::APPSTYLE_OFFICE_BLUE);

The OnApplicationStyle() handler of the SFLFrameWndEx and SFLMDIFrameWndEx classes also sends a WM_SFLEX_APPSTYLE windows message to descendant windows. If any other windows wish to handle these messages they can do so with an ON_MESSAGE() handler of the type LRESULT (WPARAM, LPARAM). The ID_SFLEX_APPSTYLE_* messages are passed in the WPARAM parameter.

                For a demonstration of the WM_APPSTYLE message look at the view class of the ExcelGrid sample located in the <StingrayInstallDir>\Samples\GridEx\ExcelGrid directory.

 

1.2.3.2     Multiple Views in Single Document Interface

The SFLFrameWndEx class supports dynamic swapping of multiple CView or CView derived classes through the class SFLMultiViewMgr. Access the SFLMultiViewMgr class through the GetMultiViewMgr() function which is a member of the SFLFrameWndEx class.

Add multiple views to the SFLMultiViewMgr class in your SFLWinAppEx derived class or in the Frames OnCreate() call:

MyView1* pView1 = new MyView1();

MyView2* pView2 = new MyView2();

GetMultiViewMgr()->AddView(pView1, ID_MYVIEW1);

GetMultiViewMgr()->AddView(pView2, ID_MYVIEW2);

 

Switch the views by calling SwitchView() with an enum index representing the associated view:

 

GetMultiViewMgr()-> SwitchView(SFLMultiViewMgr::MULTIVIEW_1);

 

Ideally, switching the views would be mapped to a menu command.

For further information on using multiple views in an SDI application refer to the MultiViewEx sample located in the <StingrayInstallDir>\Samples\FoundationEx\MultiViewEx directory.

To handle multiple sdi view command messages, send the following IDs which are defined in SFLResEx.h:

ID_SFLEX_MULTIVIEW_0, // Default view

                // associated with CSingleDocTemplate

ID_SFLEX_MULTIVIEW_1,

ID_SFLEX_MULTIVIEW_2,

ID_SFLEX_MULTIVIEW_3,

//..

ID_SFLEX_MULTIVIEW_20

 

1.2.3.3     Fullscreen

Frames support Fullscreen mode by directly calling ShowFullScreen() and verifying with IsFullScreen(), or by handling the menu command ID_SFLEX_VIEW_FULLSCREEN in the frame class.

Note: To enable menu commands, call EnableFullScreenMode(ID_SFLEX_VIEW_FULLSCREEN) in the frame class.

1.2.4       Docking Features

Several docking classes have been added to make docking controls easier.

1.2.4.1     SFLDockablePaneEx

The SFLDockablePaneEx class is a derivation from CDockablePane which will handle the docking for the new MFC9 Feature Pack framework. Objective Toolkit classes that were using CControlBar or SECControlBar should, instead, derive their classes from SFLDockablePaneEx.

1.2.4.2     SFLDockableCtrlPaneEx<T>

The SFLDockableCtrlPaneEx template class is derived from SFLDockablePaneEx and allows a control class to be passed at the template type and it will be instantiated on creation. There are some functions can we recommend overriding in a derived class in order to gain greater control of creation and layout. These are CreateControl() and AdjustLayout().

MainFrm.h:

SFLDockableCtrlPaneEx<CMFCTreeCtrl> myDockTree;

MainFrm.cpp

CMainFrame::InitInstance()

{

   //…

      if(!myDockTree.Create(this))

{

            return -1;

}

myDockTree.EnableDocking(CBRS_ALIGN_ANY);

DockPane(&myDockTree);

   //…

}

 

Note: For derived classes, you should use BEGIN_TEMPLATE_MESSAGE_MAP() instead of BEGIN_MESSAGE_MAP().

1.2.5       User Interface Features

                Several default user interface classes have been added to make creating quick default toolbar, menu, status, and ribbonbar controls easier.

1.2.5.1     SFLStandardUI

The SFLStandardUI class will create a set of default user interface elements including a menubar, toolbar, and statusbar in a SDI or MDI frame. There are several overrides for the Create() call provided for convenience but each basically gives you the ability to specify if you want all by default, or choose from the toolbar, and statusbar, as well as MDI tabs for the MDI frames.

Note: By default, a menubar will be created. See the appendix section for tips on applications without menus.

MainFrm.h :

SFLStandardUI ui;

MainFrm.cpp

CMainFrame::InitInstance()

{

   //…

EnableDocking(CBRS_ALIGN_ANY);

      If(!ui.Create(this))

{

            return -1;

}

// No need to handle docking calls.

// The base class does this.

}

 

In MDI applications, in order to get the Standard UI menu, you’ll need to change the first parameter of the CMultiDockTemplate class constructor in your application’s InitInstance() function.  It should use IDR_SFLEX_MAINFRAME. In addition, you’ll need to define any document types, etc, for resource files; otherwise, tabs will be labeled d1, d2, etc.

MyApp.cpp:

MyApp::InitInstance()

{

   //…

      CMultiDocTemplate* pDocTemplate;

    //pDocTemplate = new CMultiDocTemplate(IDR_MyAppTYPE,

      pDocTemplate = new CMultiDocTemplate(

                         IDR_SFLEX_MAINFRAME,

                         RUNTIME_CLASS(CSFLExTestDoc),

                         RUNTIME_CLASS(CChildFrame),

                         // custom MDI child frame

                         RUNTIME_CLASS(CSFLExTestView));

      if (!pDocTemplate)

            return FALSE;

      AddDocTemplate(pDocTemplate);

         //…

}

 

1.2.5.2     SFLFluentUI

The SFLFluentUI class will create a set of default user interface elements for RibbonBar based applications. Per Microsoft guidelines on creating a Fluent UI, all elements of the Fluent UI will be created by default, except for the optional CaptionBar, which can be specified for creation.

 

MainFrm.h :

SFLFluentUI ui;

MainFrm.cpp

CMainFrame::InitInstance()

 

{

//…

EnableDocking(CBRS_ALIGN_ANY);

CMDITabInfo* pTabInfo = new CMDITabInfo();

      pTabInfo->m_style     =

            CMFCTabCtrl::STYLE_3D_ONENOTE;     

pTabInfo->m_bActiveTabCloseButton = TRUE; 

      pTabInfo->m_bTabIcons             = FALSE;     

pTabInfo->m_bAutoColor            = TRUE; 

pTabInfo->m_bDocumentMenu         = TRUE; 

      if(!ui.Create(this, pTabInfo))

{

            return -1;

}

      // No need to handle docking calls.

      // The base class does this.

}

 

 

 

 

 

1.2.5.3     SFLMenuBarEx

The SFLMenuBarEx class is a derivation from CMFCMenuBar class and replaces the SECMenuBar used in Objective Toolkit. Menubars use the Create() method for creation such as:

// CMainFrame::OnCreate()

if(!m_wndMenuBar.Create(this))

{

      return -1;

}

m_wndMenuBar.SetPaneStyle(

m_wndMenuBar.GetPaneStyle()|

CBRS_SIZE_DYNAMIC|CBRS_TOOLTIPS|CBRS_FLYBY);

// Menu will not take focus on activation.

CMFCPopupMenu::SetForceMenuFocus(FALSE);

DockPane(&m_wndMenuBar);

 

Note: All applications must have a default menubar created otherwise the frames will have drawing artifacts where the menu is supposed to be located. See the appendix for applications without a menu.

1.2.5.4     SFLToolBarEx

The SFLToolBarEx class is a derivation from the CMFCToolBar class and replaces the SECToolBar and SECCustomToolBar classes in Objective Toolkit. It is no longer necessary to use the SECControlBarManager class when using the SFLToolBarEx class.

Toolbars use the Create() method for creation as such:

// CMainFrame::OnCreate()

if(!m_wndToolBar.Create(this,

                 WS_VISIBLE | CBRS_TOP |

                 CBRS_TOOLTIPS | CBRS_FLYBY |            

                 CBRS_HIDE_INPLACE |                    

                 CBRS_SIZE_DYNAMIC | CBRS_GRIPPER |

                 CBRS_BORDER_3D, ID_TOOLBAR) ||

   !m_wndToolBar.LoadToolBar(IDR_MAINFRAME))

{

return -1;

}

m_wndToolBar.EnableCustomizeButton(TRUE, ID_SFLEX_VIEW_CUSTOMIZE, _T(“Customize…”));

m_wndToolBar.EnableDocking(CBRS_ALIGN_ANY);

DockPane(&m_wndToolBar);

 

Note: DockControlBar() is not used with SFLToolBarEx, instead use DockPane() or DockPaneLeftOf().

 

Note: A unique toolbar ID should be given to each toolbar created so that layout persistence works correctly.

1.2.5.5     SFLStatusBarEx

The SFLStatusBarEx class is a derivation from the CMFCStatusBar class and replaces the SECStatusBar class in Objective Toolkit. Use the Create() method to create statusbars as such:

//CMainFrame::OnCreate()

static UINT indicators[] =

{

ID_SEPARATOR, ID_INDICATOR_CAPS, ID_INDICATOR_NUM, ID_INDICATOR_SCRL,

};

 

if(!m_wndStatusBar.Create(this) ||  

   !m_wndStatusBar.SetIndicators(indicators,

                   sizeof(indicators)/sizeof(UINT)))

{

      return -1;

}

2         Migration Essentials

Existing customers who have established applications built with a previous version of Stingray Studio 10.1 or earlier are not required to migrate. Migrating to the FoundationEx library is optional. Existing applications will continue to work as they previously did. Customers should migrate to the FoundationEx library only if they wish to use Stingray Studio in conjunction with any new features provided in the MFC 9 Feature Pack, such as the RibbonBar.

2.1       Migration Prerequisites

2.1.1       Microsoft Visual Studio 2008 with Service Pack 1 installed.

The features that the FoundationEx library is built upon are included with the Microsoft Visual Studio 2008 compiler when Service Pack 1 is installed.

2.1.2       Stingray Studio 10.2 or higher must be installed.

The FoundationEx library is included in Stingray Studio 10.2 as a preview.

2.2       Migration Requirements

2.2.1       File Pathing

The files for the FoundationEx library are located in the following structure within the Stingray Studio installation directory:

Include:

<StingrayInstallDir>\Include\FoundationEx

Resource:

<StingrayInstallDir>\Include\Res

Library:

<StingrayInstallDir>\Lib\vc9\[architecture x86 or x64]

Source:

<StingrayInstallDir>\Src

<StingrayInstallDir>\Src\FoundationEx

Samples:

<StingrayInstallDir>\Samples\FoundationEx

The solution file is FoundationEx90.sln:

 <StingrayInstallDir>\Src

The libraries, located in:

<StingrayInstallDir>\Lib\vc9\[architecture x86 or x64],

 

 

The libraries are named similar to the following where [Version] is the current version:

 

Stingray Lib MFC Lib Release

sflex[Version].lib

 

Stingray Lib MFC DLL Release

sflex[Version]a.lib

 

Stingray Lib MFC DLL Debug

sflex[Version]ad.lib

 

Stingray DLL MFC DLL Release

sflex[Version]as.dll

 

Stingray DLL MFC DLL Debug

sflex[Version]asd.dll

 

Stingray DLL MFC DLL Unicode Release

sflex[Version]asu.dll

 

Stingray DLL MFC DLL Unicode Debug

sflex[Version]asud.dll

 

Stingray Lib MFC DLL Unicode Release

sflex[Version]au.lib

 

Stingray Lib MFC DLL Unicode Debug

sflex[Version]aud.lib


Stingray Lib MFC Lib Debug

sflex[Version]d.lib

 

Stingray Lib MFC Lib Unicode Release

sflex[Version]u.lib

 

Stingray Lib MFC Lib Unicode Debug

sflex[Version]ud.lib

 

Refer to the FoundationEx.h section for information on how these static and dynamic libraries are linked to an application.

 

2.2.2       Header File Changes

2.2.2.1     SupportedPlatforms.h

Include SupportedPlatforms.h in stdafx.h.  Stingray Studio includes a file called SupportedPlatforms.h which will determine if the items you’re building are supported or not. Include SupportedPlatforms.h in the applications stdafx.h header file. The file is located in the <StingrayInstallDir>\Include directory.

Note: This should replace any targetver.h files that are generated by an application wizard.

2.2.2.2     ManifestDefs.h

Include ManifestDefs.h in stdafx.h. Stingray Studio includes a file called ManifestDefs.h which facilitates proper generation of manifest files in the application. Include ManifestDefs.h in the applications stdafx.h header file. The file is located in the <StingrayInstallDir>\Include directory. This should replace any MFC, CRT, or Windows Common Control manifest definitions.

2.2.2.3     FoundationEx.h

Include FoundationEx.h in stdafx.h. To get the functionality in the FoundationEx library, include FoundationEx.h to your application’s stdafx.h file below any necessary Windows include files. The FoundationEx.h header file is located in the <StingrayInstallDir>\Include\FoundationEx\ directory. This file includes the necessary header files for other functionality in the library, as well as the necessary defines for linking to the libraries.

#include “FoundationEx\FoundationEx.h”

Note: This assumes you have your IDE correctly pathed for Stingray Studio. Refer to the Getting Started Users Guide for more details on pathing.

Note: If you get compiler errors related to definitions of INT16, make sure you include FoundationEx.h before other Stingray product header files.

2.2.2.4     SFLResEx.h and SFLResEx.rc.

Include SFLResEx.h and SFLResEx.rc. To get the functionality of FoundationEx resources, such as menu id’s and default toolbar images, include SFLResEx.h in your application. The SFLResEx.h header file is located in the <StingrayInstallDir>\Include\Res\ directory. To add the header files to a sample or application, open the Resource View and right click on the sample or application’s .rc file and select ‘Resource Includes’.

Add SFLResEx.h to the includes section:

#include “FoundationEx\Res\SFLResEx.h”

Add SFLResEx.rc to the resource section below the include section:

#include “FoundationEx\Res\SFLResEx.rc”

2.2.2.4.1        AfxRibbon.rc

Note: For some Stingray configurations, you may need to add afxribbon.rc to your resource includes to avoid any errors when compiling. Adding afxribbon.rc to your application may cause conflicts with some LIB LIB Release configurations. To add the file, open the Resource View, right click on your project resource file (*.rc) and select ‘Resource Includes’ then add the following to the bottom section. If this is not added, the sample or application will crash on statically linked build configurations.

#include “afxribbon.rc”

 

Note: Conflicts may exist between SFLResEx.rc and afxribbon.rc. If so, try adding or removing any sections containing afxribbon.rc.

2.2.3       The _SFLEXDLL Preprocessor Macros

Include _SFLEXDLL in the preprocessor macros if you want to link FoundationEx as a Dynamic Link Library. This is included in the C++ preprocessor settings or define _SFLEXDLL in your stdafx.h header file before including any other Stingray Studio headers.

#ifndef _SFLEXDLL

#define _SFLEXDLL

#endif

3                   Migrating EXISTING Stingray Studio applications to use the FoundationEx library

3.1       Migration Description:

Migration will consist 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.

3.2       Class migration guide:

3.2.1       CWinApp/CWinAppEx à SFLWinAppEx:

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

 

3.2.1.1     Existing Registry Entries

If SFLWinAppEx::Initialize() is not called, it is important to setup registry entries to store application settings. This is accomplished by calling SetRegistryKey(_T(“Your Application’s Registry Entry”)) in InitInstance().

 

3.2.2       CFrameWnd/CFrameWndEx/SECFrameWnd à SFLFrameWndEx:

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.

3.2.3       CMDIFrameWnd/CMDIFrameWndEx/SECMDIFrameWndEx à SFLMDIFrameWndEx:

Replace all occurrences of CMDIFrameWnd, CMDIFrameWndEx, and SECMDIFrameWnd 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.

3.2.4       CMDIChildWnd/CMDIChildWndEx/SECMDIChildWnd/SECWorkbookWnd/SECWorksheet à SFLMDIChildWndEx:

Replace all occurrences of CMDIChildWnd, CMDIChildWndEx, SECMDIChildWnd, SECWorkbookWnd, 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.

3.2.4.1     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 it should use the standard CMDIChildWnd class. Ex:

CMultiDocTemplate* pDocTemplate = new CMultiDocTemplate(

IDR_1STGRITYPE,

RUNTIME_CLASS(C1stGridS1Doc),

RUNTIME_CLASS(CMDIChildWndEx), // Don’t use SFLMDIChildWndEx

RUNTIME_CLASS(C1stGridS1View));

 

3.2.5       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.

3.2.6       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.

3.2.7       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 which will need to be adjusted according to your application. The use of CBRS_EX_XXXXX styles no longer works with SFLDockablePaneEx.

3.2.7.1     Docking pane creation

The create function for docking panes is slightly different than previously used for controlbars. Parameters should be changed like the following:

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.

3.2.7.2     Showing and hiding docking windows

Docking windows are shown and hidden using the ShowPane() function. The previous ToggleVisibility() function has been replaced with ShowPane().

3.2.8       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.

3.2.8.1       Toolbar Styles

Change uses of SetBarStyle() and GetBarStyle() to SetPaneStyle() and GetPaneStyle() respectively.

3.2.8.2       SECControlBarManager and SECToolBarManager

The SECControlBarManager and the SECToolBarManager 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 9 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…

*/

 

3.2.8.3       Button Maps

Button maps are currently not implemented for use with SFLToolBarEx. These sections should be commented out.

3.2.8.4       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,

};

3.2.8.5       Toolbar Customization

The SECToolBarSheet 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();

3.2.8.6     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

SFLToolBarEx     m_wndFileToolBar;

SFLToolBarEx     m_wndEditToolBar;

SFLToolBarEx     m_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

3.2.8.7         Showing and hiding toolbars

Toolbars are shown and hidden using the function ShowPane() as such:

 

CMainFrame::OnViewToolbar()

{

      m_wndFileToolBar.ShowPane(!m_wndFileToolBar.IsVisible());

}

Note: ShowControlBar() is not used with SFLToolBarEx.

3.2.9       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 appendix for applications that do not have a menubar.

3.2.10  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.

3.2.11  SECDialogBar à SFLPaneDialogEx

Replace all occurrences of SECDialogBar with SFLPaneDialogEx. The SFLPaneDialogEx.h headerfile is located in the <StingrayInstallDir>\Include\FoundationEx\Dialog directory.

4                   Migrating a NEW Stingray Studio application to use the FoundationEx library

4.1            Migrate traditional MFC (non MFC 9) Applications to use the FoundationEx library

This section will demonstrate how to add FoundationEx classes to a skeleton MFC application that has not had any new MFC 9 features added.

4.1.1       File > New > Project

Create a new MFC Project by selecting the MFC Application option. Give it a name and location and click OK.

4.1.2       Select MFC Standard Project Type

In the ‘Application Type’ section of the MFC Application Wizard, select ‘MFC Standard’ from the ‘Project Type’ selection.

4.1.3       Select Menu and Toolbar

In the ‘User Interface Features’ section of the MFC Application Wizard, select the ‘Use MenuBar and ToolBar’ option.

4.1.4       Finish the Application Wizard

Finish selecting any other options and click ‘Finish.’ A skeleton MFC application will then be created.

4.1.5       Replace CWinApp with SFLWinAppEx

All new application framework features start with the SFLWinAppEx class. Replace all instances of CWinApp with SFLWinAppEx, this includes any global scope instances using the :: operator.

4.1.6       Replace CFrameWnd or CMDIFrameWnd with SFLFrameWndEx or SFLMDIFrameWndEx respectively

Replace Single Document Interface frame instances of CFrameWnd with SFLFrameWndEx, including any global scope instances using ::. Replace Multiple Document Interface frame instances of CMDIFrameWnd with SFLMDIFrameWndEx, including any global scope instances using ::.

4.1.7       Replace CMDIChildWnd with SFLMDIChildWndEx

For Multiple Document Interface applications, replace all instances of CMDIChildWnd classes with SFLMDIChildWndEx, including any global scope instances using ::.

4.1.8       Replace CControlBar with SFLDockablePaneEx

For docking window functionality, replace all instances of CControlBar with SFLDockablePaneEx. Also, Replace instances of DockControlBar() in your frame classes with DockPane().

4.1.9       Unicode build configurations

By default, skeleton MFC applications are set to use Unicode as the character set. If you do not wish to use a Unicode version of the FoundationEx library, you will need to change this in the applications project settings.

4.1.10  Add a MenuBar

By default, SDI and MDI, applications are expected to have at least one MenuBar associated with the application frame. For applications without a menu, refer to the appendix.

MainFrm.h

SFLMenuBarEx m_wndMenuBar;

MainFrm.cpp

int CMainFrame::OnCreate(LPCREATESTRUCT lpCreateStruct)

{

                     //..

   if(!m_wndMenuBar.Create(this))

                     {

        TRACE(“Failed to create Menu.\n”);

                          return -1;

                     }

   m_wndMenuBar.SetPaneStyle(m_wndMenuBar.GetPaneStyle() |                

                             CBRS_SIZE_DYNAMIC);

                     CMFCPopupMenu::SetForceMenuFocus(FALSE);

                     m_wndMenuBar.EnableDocking(CBRS_ALIGN_ANY);

                     DockPane(&m_wndMenuBar, AFX_IDW_DOCKBAR_TOP);

                     //..

}

 

4.2            Migrate an MFC 9 based Application to use the FoundationEx library.

This section will demonstrate how to add FoundationEx classes to an MFC application that has MFC 9 Feature Pack features already added to it.

Note: We recommend that if you are going to use the FoundationEx library you migrate from an existing Stingray application or you do so from a skeleton application. Generating an MFC 9 application with MFC 9 features will generate a tremendous amount of code which will need to be removed or reorganized, thus, it is easier to avoid this step, if possible. We do recommend, however, that you generate an MFC 9 application with MFC 9 features if you wish to study how the base MFC classes are used to handle the new RibbonBar, ToolBar, etc.

4.2.1       Replace CWinAppEx with SFLWinAppEx

All new application framework features start with the SFLWinAppEx class. Replace all instances of CWinAppEx with SFLWinAppEx, this includes any global scope instances using the :: operator.

4.2.2       Replace CFrameWndEx or CMDIFrameWndEx with SFLFrameWndEx or SFLMDIFrameWndEx respectively

Replace Single Document Interface frame instances of CFrameWndEx with SFLFrameWndEx, including any global scope instances using ::. Replace Multiple Document Interface frame instances of CMDIFrameWndEx with SFLMDIFrameWndEx, including any global scope instances using ::.

4.2.3       Replace CMDIChildWndEx with SFLMDIChildWndEx

For Multiple Document Interface applications, replace all instances of CMDIChildWndEx classes with SFLMDIChildWndEx, including any global scope instances using the :: operator.

4.2.4       Replace CDockablePane with SFLDockablePaneEx

For docking window functionality, replace all instances of CDockablePane with SFLDockablePaneEx. Also, Replace instances of DockControlBar() in your frame classes with DockPane().

4.2.5       Unicode build configurations

By default, MFC 9 applications are set to use Unicode as the character set. If you do not wish to use a Unicode version of the FoundationEx library, you will need to change this in the applications project settings.

4.2.6       Replace CMFCToolBar with SFLMenuBarEx

By default, SDI and MDI, applications are expected to have at least one MenuBar associated with the application frame. Replace CMFCToolBar with SFLToolBarEx and CMFCMenuBar with SFLMenuBarEx. For applications without a menu, refer to the appendix.

Note: Previously, some 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 appendix for applications that do not have a menubar.

4.2.7       Replacing the Application Look and Feel

The application look and feel sections that are generated by the Microsoft application wizards can be removed, since look and feel is handled in the base frame classes in conjunction with the SFLAppStyleEx class.

5         Appendix / Troubleshooting

5.1       Creating applications without a MenuBar

Creating an application without a menu can cause unwanted drawing side effects in the main frame. There is some additional work required for applications that do not use a menu. Mostly, you must destroy the menus that get created by the frame window, as well as handle them in the frame classes with several overridden functions. Please refer to the following Microsoft article work workarounds:

http://support.microsoft.com/kb/131368

5.2       RWUXTheme Compatibility

The features in the FoundationEx library do not use functionality from Stingray Studio’s RWUXTheme library. Drawing in FoundationEx is handled by the Visual and Drawing managers in the MFC 9 Feature Pack. Controls in Stingray Studio’s other products still use the RWUXTheme library for themed drawing.

There may be some drawing style conflicts when using RWUXTheme styles and those provided by the MFC 9 Feature Pack. The Stingray Studio controls have not been updated to use the new Visual and Drawing managers.

5.3       Office 2007 Theme Issues

This appears to be several bugs in the MFC 9 Feature Pack Office 2007 styles. Currently, there is no work around. Refer to:

5.3.1       Visual Manager Sleep Problem

http://social.msdn.microsoft.com/Forums/en-US/vcgeneral/thread/88b4bfe4-782a-4a0d-a042-e38be2c56544

5.3.2       Customized Popup Menus

http://connect.microsoft.com/VisualStudio/feedback/ViewFeedback.aspx?FeedbackID=325105

5.3.3       Auto-Hidden Taskbar

http://connect.microsoft.com/VisualStudio/feedback/ViewFeedback.aspx?FeedbackID=361025

5.3.4       Frame Drawing Artifacts with CMDIChildWndEx

http://social.answers.microsoft.com/Forums/pt-BR/vcgeneral/thread/33da79b7-4381-4b60-ad4e-cadece94b852

5.4       Conflicts with INT16

If you get compiler errors related to definitions of INT16, make sure you include FoundationEx.h before other Stingray product header files.  Similarly, the following errors might also be found if FoundationEx.h is included below any Stingray product header files:

c:\program files\microsoft visual studio 9.0\vc\atlmfc\include\afxbutton.h(182) : warning C4003: not enough actual parameters for macro 'SelectFont'

c:\program files\microsoft visual studio 9.0\vc\atlmfc\include\afxbutton.h(182) : error C2226: syntax error : unexpected type 'HFONT'

c:\program files\microsoft visual studio 9.0\vc\atlmfc\include\afxbutton.h(182) : error C2238: unexpected token(s) preceding ';'

c:\program files\microsoft visual studio 9.0\vc\atlmfc\include\afxfontcombobox.h(45) : warning C4003: not enough actual parameters for macro 'SelectFont'

c:\program files\microsoft visual studio 9.0\vc\atlmfc\include\afxfontcombobox.h(45) : error C2059: syntax error : '<L_TYPE_raw>'

c:\program files\microsoft visual studio 9.0\vc\atlmfc\include\afxfontcombobox.h(45) : error C2238: unexpected token(s) preceding ';'

c:\program files\microsoft visual studio 9.0\vc\atlmfc\include\afxfontcombobox.h(46) : error C2059: syntax error : '<L_TYPE_raw>'

c:\program files\microsoft visual studio 9.0\vc\atlmfc\include\afxfontcombobox.h(46) : error C2238: unexpected token(s) preceding ';'

c:\program files\microsoft visual studio 9.0\vc\atlmfc\include\afxheaderctrl.h(85) : warning C4003: not enough actual parameters for macro 'SelectFont'

c:\program files\microsoft visual studio 9.0\vc\atlmfc\include\afxheaderctrl.h(85) : error C2226: syntax error : unexpected type 'HFONT'

c:\program files\microsoft visual studio 9.0\vc\atlmfc\include\afxheaderctrl.h(85) : error C2238: unexpected token(s) preceding ';'

Make sure FoundationEx.h is included before any Stingray product header files to avoid these errors.

5.5       Multiple Toolbar Layout

If your toolbars are not restoring correctly after setting up the layout, make sure you have created them with the Create() function and that you also have a unique ID for each toolbar created.

5.5.1       Unique Toolbar ID

Create a unique toolbar ID for each toolbar created.

#define ID_TOOLBAR1 200

#define ID_TOOLBAR2 201

 

// CMainFrame::OnCreate()

if(!m_wndToolBar1.Create(this, WS_VISIBLE|CBRS_TOP|CBRS_TOOLTIPS|CBRS_FLYBY|CBRS_HIDE_INPLACE|CBRS_SIZE_DYNAMIC|CBRS_GRIPPER|CBRS_BORDER_3D, ID_TOOLBAR1) || !m_wndToolBar1.LoadToolBar(IDR_TOOLBAR1))

{

return -1;

}

if(!m_wndToolBar2.Create(this, WS_VISIBLE|CBRS_TOP|CBRS_TOOLTIPS|CBRS_FLYBY|CBRS_HIDE_INPLACE|CBRS_SIZE_DYNAMIC|CBRS_GRIPPER|CBRS_BORDER_3D, ID_TOOLBAR2) || !m_wndToolBar2.LoadToolBar(IDR_TOOLBAR2))

{

return -1;

}

5.5.2       Layout Toolbars next to each other

If you have multiple toolbars that you are trying to layout next to each other you can do so like the following:

m_wndToolBar1.EnableDocking(CBRS_ALIGN_ANY);

m_wndToolBar2.EnableDocking(CBRS_ALIGN_ANY);

DockPane(&m_wndToolBar1);

DockPaneLeftOf(&m_wndToolBar2, &m_wndToolBar1);

Note: Also, it may be necessary to delete any previous registry entries that contain information on the application layout. See also the section on SetRegistryKey() Conflicts below.

5.6       SetRegistryKey() Conflicts

Calling SetRegistryKey() with the use of SFLWinAppEx::Initialize() may cause some registry conflicts which affect the layout of menus and toolbars because Initialize() sets the registry with a default set of registry values. Calling SetRegistryKey() before calling Initialize() like the following should resolve this:

DelRegTree(HKEY_CURRENT_USER, _T("\\Software\\StingrayEx"));

CString regkey = _T("StingrayEx");

SetAppRegKey(regkey);

SFLWinAppEx::Initialize(TRUE, TRUE, FALSE /*Registry Setup*/);

 

Likewise, it may be necessary to also call DelRegTree() prior to the SetRegistryKey() call in order to clear registry calls before setting the registry key. Ex:

DelRegTree(HKEY_CURRENT_USER, _T("\\Software\\StingrayEx"));

5.7       Crash in pMainFrame->LoadFrame(IDR_MAINFRAME)

If the sample or application you are running crashing during the Main Frame’s InitInstance() in the section loading the frame, chances are it is a static configuration and afxribbon.rc has not been added to the sample or application’s resource includes. Add the following to the project resource includes section:

#include “afxribbon.rc”

 

5.8       Runtime Crash in afxregpath.cpp

Migrating an existing application may lead to a runtime crash after migration. This can be fixed by deleting any previous existing registry values for the application. Or, adding a new registry value for the application using SetRegistryKey() before any calls to SFLWinAppEx::Initialize().

5.9       Use of DECLARE_DYNAMIC() / IMPLEMENT_DYNAMIC()

Template classes will not work with the DECLARE_DYNAMIC() AND IMPLEMENT_DYNAMIC() macros. Either, remove these calls or forward the calls to the base class of the class used in FoundationEx. Ex, forward to CSplitterWnd instead of CSplitterWndEx.

5.10  How is importing/exporting implemented?

The FoundationEx library uses the _SFLEXDLL preprocessor command to indicate Dynamic Link Library builds. If this preprocessor is not included, the build will be a static library.

Classes use the FOUNDATIONEX_API macros as defined in StingrayExportDefs.h which is located in the <StingrayInstallDir>\Include directory to define importing and exporting. The library itself has _SFLEX_EXPORT_IMPL defined during builds. This give the macros a definition of __declspec(dllexport). Since it will not be defined in samples and applications, the functions in FoundationEx will be imported, as FOUNDATIONEX_API will be defined as __declspec(dllimport).

For further information on importing and export of the Stingray libraries, consult the Getting Started User’s Guide.

5.11    Resource Corruption

The Microsoft Visual Studio 2008 SP1 compiler may truncate the end of an *.rc file, causing compile errors. Refer to the following:

http://connect.microsoft.com/VisualStudio/feedback/ViewFeedback.aspx?FeedbackID=347841

 

This article was:   Helpful | Not helpful Report an issue


Prev     Next
Stingray Studio MFC Projects Integration with .NET       Objective Edit

Others in this category
b Stingray Studio Additional Samples
b Stingray Studio MFC Projects Integration with .NET