Download - Stingray Studio 10.2 Toolkit

Transcript

WHITE PAPER

Rogue Wave Stingray StudioObjective ToolkitFilling the Holes in MFC to Provide Todays Modern GUI Features

www.roguewave.com

WHITE PAPER

Objective Toolkit Filling the Holes in MFC to Provide Todays Modern GUI FeaturesExecutive Summary ...................................................................................................................................... 6 The Development Challenge .................................................................................................................. 6 The Stingray Studio Solution.................................................................................................................. 6 Overview of Objective Toolkit Features ................................................................................................. 6 Introduction ................................................................................................................................................... 9 Quick Tour of Objective Toolkit ................................................................................................................. 10 Features ................................................................................................................................................. 10 Compatibility .........................................................................................................................................11 Complete Online Help System ..............................................................................................................11 Comparing MFC Extensions to Other Component Architectures ...............................................................11 MFC Extensions ....................................................................................................................................11 OLE/ActiveX Controls (OCXs) ............................................................................................................11 DLL Components.................................................................................................................................. 13 Selecting a Component Architecture .................................................................................................... 13 Technical Overview of Objective Toolkit Components .............................................................................. 13 Objective Toolkit Window/Control Components ................................................................................. 13 Button Control ............................................................................................................................... 14 Color Well Control ......................................................................................................................... 15 Masked Edit Control ...................................................................................................................... 16 Browse Edit Control ...................................................................................................................... 16 Marquee Control ............................................................................................................................ 17 Progress Control ............................................................................................................................ 17 Editable List Box Control .............................................................................................................. 17 Tab Control/Tabbed window Components .................................................................................... 18 Calculator Edit Control .................................................................................................................. 20 Calendar Control ............................................................................................................................ 21 Currency Edit Control .................................................................................................................... 21 Customizable Status Bar ................................................................................................................ 22 Customizable Toolbar .................................................................................................................... 23 Shortcut Bar Control ...................................................................................................................... 24 List Bar Control ............................................................................................................................. 25 Date/time Edit Control ................................................................................................................... 25 Extended Win32 Tree Control ....................................................................................................... 26 Objective Toolkit User Interface Extensions ........................................................................................ 28 The Workspace Manager ............................................................................................................... 28 Keyboard Shortcut Components .................................................................................................... 30

2

www.roguewave.com

WHITE PAPER

User Tools Menu Components....................................................................................................... 30 Thumbnail Components ................................................................................................................. 31 Extended Control Bar Architecture ...................................................................................................... 33 Objective Toolkit MDI Alternatives and Enhancements ...................................................................... 35 Multiple Top-level Interface (MTI) ............................................................................................... 35 Floating Document Interface (FDI) ............................................................................................... 36 Workbook Document Interface (WDI) .......................................................................................... 37 Using MTI, FDI, and WDI ............................................................................................................ 38 The Gradient Caption Extension.................................................................................................... 39 View Components ................................................................................................................................. 39 Image Components ............................................................................................................................... 40 Image Example .............................................................................................................................. 42 Objective Toolkit Utility Components .................................................................................................. 42 Non-User-Interface Utility Extensions .......................................................................................... 42 Miscellaneous User Interface Utility Extensions........................................................................... 43 Challenges of Docking a CView........................................................................................................... 45 Docking Views: Architectural Overview .............................................................................................. 46 Using the Docking Views Architecture ................................................................................................ 47 Layout Manager Framework....................................................................................................................... 47 The Problem.......................................................................................................................................... 48 The Solution.......................................................................................................................................... 48 Why use the Layout Manager? ...................................................................................................... 48 Layout ManagerArchitecture ......................................................................................................... 49 Layout managers provided by Objective Toolkit........................................................................... 53 Implementing custom layout managers ......................................................................................... 53 Adding layout management to your applications .......................................................................... 54 Advanced Docking Windows ..................................................................................................................... 54 Introduction to a new architecture ........................................................................................................ 54 Why this architecture? ................................................................................................................... 55 ActiveScript hosting engine ........................................................................................................................ 59 JavaScript .............................................................................................................................................. 60 VBScript ............................................................................................................................................... 60 Hosting an ActiveScript ........................................................................................................................ 60 ActiveScript classes ....................................................................................................................... 60 The ActiveForm scripting and editing framework................................................................................ 62 ActiveForm classes ........................................................................................................................ 62 The Model-View-Controller (MVC) Framework ....................................................................................... 64 Introduction to MVC ............................................................................................................................ 64 Considering an alternative to DVA ....................................................................................................... 64

3

www.roguewave.com

WHITE PAPER

Problems with DVA .............................................................................................................................. 65 DVAs architecture is vague ........................................................................................................... 65 DVAs approach is monolithic ....................................................................................................... 66 CViews inhibit reuse ...................................................................................................................... 66 CView/CDialog are incompatible .................................................................................................. 67 OnUpdate creates problems ........................................................................................................... 68 DVAs presentation tied to control ................................................................................................. 68 Overview of the MVC architecture ...................................................................................................... 68 MvcModel ...................................................................................................................................... 69 MvcViewport ................................................................................................................................. 70 MvcController ................................................................................................................................ 70 Connecting the model, viewport, and controller............................................................................ 71 Additional reading on MVC .......................................................................................................... 71 The MVC class hierarchy ..................................................................................................................... 72 MvcVisualComponent ................................................................................................................... 72 MvcVisualPart ............................................................................................................................... 73 MvcLogicalPart ............................................................................................................................. 73 MvcViewport ................................................................................................................................. 73 MVCWrapper_T ............................................................................................................................ 74 IComposite_T ................................................................................................................................ 75 IMvcMsgHandler ........................................................................................................................... 75 The IMvcSubject, IMvcObserver and IMvcMessage Interfaces ................................................... 75 MvcModel ...................................................................................................................................... 76 The MvcPresentationModel_T class.............................................................................................. 76 IMvcVirtualPart ............................................................................................................................. 77 MvcTransactionModel ................................................................................................................... 78 MvcController ................................................................................................................................ 78 The collection classes .................................................................................................................... 79 MVCs Undo/Redo architecture ........................................................................................................... 80 MvcCommand ............................................................................................................................... 80 The transaction model .................................................................................................................... 80 The IMvcUndoRedo interface ....................................................................................................... 81 Tying Undo/Redo into the MVC framework ................................................................................. 81 Solving real problems with MVC ......................................................................................................... 81 Clarifying the role of the model and the viewport ......................................................................... 81 Leveraging the power and flexibility of the subject/observer interfaces ....................................... 85 Using MVC and MFC together ..................................................................................................... 86 Undoing a delete command ........................................................................................................... 86 Chaining controllers together......................................................................................................... 87 Using the MVC architecture ................................................................................................................. 87

4

www.roguewave.com

WHITE PAPER

Integrating your model class .......................................................................................................... 87 Integrating your viewport class...................................................................................................... 88 Integrating your controller class .................................................................................................... 91 Using MVCs Undo/Redo architecture ................................................................................................. 92 Conclusion .................................................................................................................................................. 96

5

www.roguewave.com

WHITE PAPER

Executive SummaryThis section is for busy readers who need a quick overview of Objective Toolkit. It briefly describes major product features. For a more in-depth technical analysis of the product, begin reading at the Introduction on page 4. To help you determine which programming approach best suits your needs, we also encourage you to read the section entitled Comparing MFC Extensions to Other Component Architectures, beginning on page 7.

The Development ChallengeThe simple answer is that many need to deploy their application across all windows versions, and cant impose a particular version of a 20+ MB framework (.NET) on their users. It seems Microsoft has recognized this, based on a recent major release called MFC Feature Pack 9. MFC offers tremendous capabilities, but as at a price. It isnt as full featured or easy to use as some other methods, but that is where Stingray comes in. Stingray wraps and extends MFC so seamlessly, that you may forget that you arent using MFC directly. It is portable across many windows versions, and extends the basic capabilities with hundreds of new controls. Stingray Edition 11 supports the new MFC Feature Pack 9 features, building on a long legacy of stable releases.

The Stingray Studio SolutionThe Objective Toolkit component found in Rogue Wave Stingray Studio provides Windows software engineers with more than 60 drop-in components that address areas not covered by the MFC library. Engineers using Objective Toolkits components can leverage their knowledge of the MFC library and save time, bypassing the tedious task of writing extensions for common user-interface tasks.

Overview of Objective Toolkit FeaturesThe components provided in Objective Toolkit can be divided into the following categories: Control components Advanced GUI components such as owner-draw buttons, bitmap buttons, menu buttons, well buttons, color well, pop-up color well, masked edit, browse edit, editable list box controls, 2D and 3D tab controls/tabbed windows, calculator control, calendar control, currency control, date/time edit control, marquee control, progress control, customizable toolbar, status bar, and an enhanced functionality tree control. User interface extensions A variety of user interface extensions, including splash window, tip of the day, bitmapped dialog, workspace manager, keyboard shortcut, run-time editing, user tools menu, and thumbnail components. Extended control bar architecture A set of MFC extensions that augment its docking window features. The extended control bar architecture and its supporting components give applications the same sizable docking window capabilitywith cool lookthat is available in the Visual C++ IDE (Integrated Development Environment).

6

www.roguewave.com

WHITE PAPER

MDI (Multiple Document Interface) alternatives and enhancements Objective Toolkit offers the following MDI alternatives and enhancements: Multiple Top-level Interface (MTI), Floating Document Interface (FDI), and Workbook Document Interface (WDI). View components CView extensions that provide features such as advanced zooming and panning. Zooming lets the user zoom in and out of a view and automatically handles all mapping mode changes. Image components A group of components that let users read, write, convert among, and manipulate popular image formats. Supported formats include DIB, GIF, JPEG, PCX, TGA, and TIFF. Utility components Utilities for data encryption and decryption in two different modes, file compression and decompression, accessing file system functions, random number generation, formula evaluation engine, and encapsulation of the Win32 Registry APIs. Data Extraction Classes Used to extract data from text streams. Docking Views is an enhancement to MDI that allows you to convert any document window (for example, MDI child) into a docking window. It allows you to dock complete MFC CViews and frame windows, providing the user with visual focus cues that automatically update the view menus and implement complete dockability. The docking views architecture allows views to float as MDI children, dock to the main frame, and also float outside the main frame. When a view is docked, you can resize the dockable views using the splitter bars positioned along the windows edge. When a view is floating as an MDI child or outside the main frame, you can resize the frames embedding the view in both directions. The Layout Manager framework manages resizing tasks through the use of a framework that implements plug-in layout algorithms and gives you the flexibility to design custom layout managers based on unique business needs. The framework includes several sample layout algorithms such as grid bag layout, relative, scaled and others. It also affords you the flexibility to design custom layout managers based on your needs (for example, for low-resolution displays). The layout manager plugs seamlessly into your existing dialog, formview, controlbar, property page, or any other window to allow for nested layouts. You can integrate the layout manager into applications in a matter of minutes. An Advanced Docking Windows (ADW) architecture, built on top of the Layout Manager framework, provides container independence, complex layout logic, and a drag-and-drop framework. It provides a powerful and flexible mechanism for docking any layout node such as any CWnd or Device Context rendered image (for example, a bitmap) to any other layout node that supports the proper docking interfaces. An ActiveScript hosting engine gives MFC applications complete access to Microsofts ActiveScript technology so they can host scripts. It also provides a mechanism for two-way interaction between MFC applications and ActiveScript so that you can quickly incorporate

7

www.roguewave.com

WHITE PAPER

VBScript and JavaScript scripting into your own MFC-based applications. A forms-editing engine works in concert with the ActiveScript hosting engine to give you the ability to edit and script MFC graphical user interfaces interactively, using a Visual Basiclike forms-editing interface. The Model-View-Controller (MVC) framework extends DVA so that you can easily separate command handling, view, and document/model information. MVC also makes it easier to create portable views that are application-independent. Build Only Components Required with Build Wizard. Reduce the size of deployed libraires by building only the required subset to reduce the overall footprint. Use the Build Wizard to generate a custom library and DLL. MFC extensions to the basic Microsoft Agent ActiveX components provide Agent-enabled Dynamic Data Validation, Tooltips, Message Boxes, and Tip of the Day support. They also provide a framework with a simple API to initialize the AgentServer, load/unload a default agent character with a default notification sink, and create Acts (critical and non-critical) associated with ActIDs. Namespace Extension Wizard-helps you quickly create a working namespace extension project. After the wizard generates the project, you can easily extend the generated skeleton namespace extension to a fully functional namespace using the classes in OT. Hyperlink Classes provide a convenient way to add point-and-click navigation to conventional non-browser-enabled applications. Web Browser Extensions provide utility functions and a COM Server handy for working with DHTML interfaces in C++. The APP (Asynchronous Pluggable Protocol) ATL Object Wizard provides a very convenient way to insert the OT APP ATL Object into any ATL project. The inserted object provides default features like parsing and validating the supplied URL, spawning a worker thread to perform asynchronous data fetch, and the ability to abort the operation gracefully. The COM object contains an implementation object to which it delegates all of the function calls. Subclassing the implementation object will provide you with virtual notifications and allow you to customize the default behavior. All Rogue Wave Stingray Studio MFC extension components include Visual C++-compatible source code. Objective Toolkit has been tested and optimized to run with Visual C++ 7.1/MFC 7.1, Visual Studio 2005/MFC 8.0, and Visual Studio 2008/MFC 9.0. Objective Toolkit provides developers with components that simulate the Visual Studio .NET/Office XP look and feel or the Microsoft Office 2003 look and feel. Objective Toolkit components provide the XP look and feel on the Windows XP platform, and when used with Visual Studio .NET, some components provide additional Visual Studio .NET look and feel features. Objective Toolkit includes full integration of the Class Reference and User Guide with

8

www.roguewave.com

WHITE PAPER

the Visual C++ MSDN help viewer, an Objective Toolkit AppWizard with automatic code generation for selected features, and full integration with the IntelliSense auto-completion utility. Its advanced docking windows architecture supports advanced features such as nested docking windows, containerindependent docking, real-time dragging, alternate docking layout logic, real-time splitter movement, fixed-size dockable windows, and more. A BuildWizard is included to minimize build time. Objective Toolkit is fully integrated with all other Stingray Studio components, including Objective Grid, Objective Chart, Objective Views, and Objective Edit.

IntroductionMany of the latest Windows applications incorporate innovative user interface features and graphical components. These featuressuch as the enhanced docking window capabilities in Microsoft Visual Studio, or the drag-and-drop customizable toolbar in Microsoft Wordhave universal appeal and benefit a myriad of Windows applications. Despite the popularity of these powerful enhancements, the Microsoft Foundation Classes (MFC) provide only the most basic user interface features and components. In addition, some of the frameworks provided by MFC are not suitable for all applications. In fact, many of these frameworks have become obsolete since they were first introduced. For example, MFCs Document/View Architecture (DVA) is designed to help separate the user interface from the data in an application. Time has shown that this architecture actually reduces code reuse. Another example is the choice of basic window management offered by MFC. MFC offers only Multiple Document Interface (MDI) and Single Document Interface (SDI) window development, despite the fact that most Windows applications no longer use this paradigm. Objective Toolkit is an MFC extension collection that extends and complements the MFC library. It provides more than sixty drop-in components that cover areas not addressed by the MFC library. Unlike other C++ components, Objective Toolkit components work seamlessly with MFC and, in most cases, inherit from existing MFC classes such as CView or CWnd. Objective Toolkit enables you to bypass the tedious task of writing extensions for common user-interface tasks. This white paper is a technical introduction to the MFC extension architecture and the major features of Objective Toolkit.

9

www.roguewave.com

WHITE PAPER

Quick Tour of Objective ToolkitThis section describes the key features of Objective Toolkit and discusses integration, compatibility, and support.

FeaturesThe components provided in Objective Toolkit can be divided into the following categories: Control components: Advanced GUI components such as owner-draw buttons, bitmap buttons, menu buttons, well buttons, color well, pop-up color well, masked edit, browse edit, editable list box controls, 2D and 3D tab controls/tabbed windows, calculator control, calendar control, currency control, date/time edit control, marquee control, progress control, customizable toolbar, status bar, and an enhanced functionality tree control. User interface extensions: A variety of user interface extensions, including splash window, tip of the day, bitmapped dialog, workspace manager, keyboard shortcut, run-time editing, user tools menu, and thumbnail components. Extended control bar architecture: A set of MFC extensions that augment its docking window features. The extended control bar architecture and its supporting components give applications the same sizable docking window capabilitywith cool lookthat is available in the Visual C++ IDE (Integrated Development Environment). These docking windows also provide an autohiding feature similar to window pinning feature found in the Visual C++ .NET (2003, 2005, and 2008) IDE. MDI (Multiple Document Interface) alternatives and enhancements Objective Toolkit offers the following MDI alternatives and enhancements: Multiple Top-level Interface (MTI), Floating Document Interface (FDI), and Workbook Document Interface (WDI). View components: CView extensions that provide features such as advanced zooming and panning. Zooming lets the user zoom in and out of a view and automatically handles all mapping mode changes. Panning is a popular scrolling extension used in various Windows applications. Image components: A group of components that lets users read, write, convert among, and manipulate popular image formats. Supported formats include DIB, GIF, JPEG, PCX, TGA and TIFF. Utility components: Utilities for data encryption and decryption in two different modes, file compression and decompression, accessing file system functions, random number generation, and encapsulation of the Win32 Registry APIs. Data Extraction Classes: Data extraction classes are an object-oriented solution for scanning and extracting data from text streams.

10

www.roguewave.com

WHITE PAPER

CompatibilityObjective Toolkit is fully compatible with the latest 32-bit releases of Visual C++. Companies like Bristol and Mainsoft have ported some versions of Objective Toolkit to UNIX.

Complete Online Help SystemObjective Toolkit is supported by a complete class reference online help system to help you learn and develop with the product. In addition, you can receive context-sensitive help for methods and components while editing or browsing with the Microsoft Visual Studio code editor. The Objective Toolkit Class Reference and User Guide are now integrated into the MSDN viewer as HTML Help. The documentation is also available in CHM, HxS and PDF formats.

Comparing MFC Extensions to Other Component ArchitecturesBefore we examine the Objective Toolkit components in detail, lets compare the MFC extension approach with other available component architectures.

MFC ExtensionsMFC extensions, like MFC, are a group of C++ components that are built on and extend MFC classes. All Stingray Studio MFC extension components include complete Visual C++-compatible C++ source code and can be built as either static libraries or as AFX DLLs, which are DLLs that share a DLL copy of MFC with your application and can be shared between several applications. Since C++ includes support for object-oriented components, MFC extensions are a natural way to extend MFC. Our MFC extensions fit so seamlessly with MFC that you might not notice that you are using a different product.

OLE/ActiveX Controls (OCXs)OLE/ActiveX controls (OCXs) are the 32-bit successors to 16-bit Visual Basic eXtensions (VBX). OCXs are based on Microsofts ActiveX technologypreviously known as Object Linking and Embedding (OLE)that allows binary objects to interface with each other. Architecturally, OCXs and MFC extensions are quite different. MFC extensions are a source-level, or compile-time, interface, while OCXs are a binary-level, or run time, interface. There are benefits and drawbacks to each approach. The benefits of an OCX (run time) interface include: You can use the same OCXs in a variety of environmentssuch as Visual Basic, Visual C++, and Borland Delphiwithout having to recompile.

11

www.roguewave.com

WHITE PAPER

You can also load OCXs at run time, so you dont have to know about them at compile time.

Figure 1 - Diagram of the OCX Interface

The drawbacks of the OCX (run time) interface include: It is difficult to modify or subclass the defined behavior of the component. You can change various exported properties, but OCXs do not support C++ idioms like inheritance. Implementation inheritance is supported with MFC extensions, but not with ActiveX controls. Since a binary interface needs to be well defined, you must learn a completely new set of terminology and technology. Figure 1 diagrams the OCX interface. Attempting to simultaneously learn about both the OCX interface and a complex environment like MFC is time-consuming and difficult. Performance is an issue. Because OCXs are loaded at run-time, there is often a noticeable delay when the ActiveX COM layer loads the object and prepares it for use. There are ways to shift this delay to application startup, but this does not really solve the problem. The benefits of MFC extensions (compile-time) interface include: MFC extensions are easier to use and modify than OCXs. You can use MFC extensions the same way you use MFC classes. You can modify them with proven C++ techniques without having to learn any complex interfaces. Implementation inheritance is supported with MFC extensions.

DLL ComponentsAnother popular component architecture used primarily by C and C++ developers is a library of C

12

www.roguewave.com

WHITE PAPER

functions that are built into a Dynamic Link Library (DLL). Some of these components even include MFC class libraries that wrap the C function calls to give them a C++ interface. The benefit of DLL components is that they are easy to learn and use. Most of the DLLs written in C originated from DOS and are fairly robust libraries. The drawback of these DLL componentseven ones that provide an MFC wrapperis that they are not object-oriented and thus not easily modified or subclassed. Because the MFC wrapper classes directly call functions in the DLL, you need to determine how to override behavior through the DLL interface instead of the typical MFC methods.

Selecting a Component ArchitectureTo select a component architecture that suits your needs, consider the following questions: Q: Do I need the component to work with a variety of development environments? A: If yes, use an OCX. Q: Do I need the component to work with MFC where modifying the component is not an issue? A: If yes, consider a regular DLL-based component. Q: Do I need a component that is based on MFC and that allows me to leverage my existing knowledge of MFC architectures and classes? A: If yes, use an MFC extension. MFC extensions can be used in other development environments. Theyalsocanbemodifiedusingobject-orientedtechniques.

Q: Do I need the functionality and look and feel of the MFC 9 Feature Pack? A: If yes, link in Stingray Studios Feature Pack MFC extension. A migration guide is provided.

Technical Overview of Objective Toolkit ComponentsNow that you are familiar with various component architectures, lets take a closer look at the components provided by Objective Toolkit and examine how they fit in with existing MFC classes. Note: To ensure that Objective Toolkit components do not conflict with current or future MFC classes, most Objective Toolkit components are prefixed with SEC, which stands for Stingray Extension Classes.

Objective Toolkit Window/Control ComponentsThe Objective Toolkit window/control components provide sophisticated and attractive CWnd-based components similar to those in popular Windows applications. Objective Toolkit allows you to easily and quickly add these components to your applications.

13

www.roguewave.com

WHITE PAPER

Button Control

The Objective Toolkit button components provide versatile buttons that have more features and are easier to use than those provided by MFC. Figure 2 illustrates the bitmap, menu, and well button types associated with the Objective Toolkit button components.

Figure 2 Bitmap buttons, menu buttons, well buttons, and embedded color wells

SECOwnerDrawButton SECOwnerDrawButton simplifies the task of creating an owner-draw button. SECBitmapButton SECBitmapButton simplifies creation of buttons that include a bitmap and optional text caption on the face of the button. The top right quadrant of Figure 2 displays examples of bitmapped buttons.

Figure 3 SECBitmapButton control with text

SECMenuButton SECMenuButton provides a simple button that displays a pop-up menu to the right or below the button when a user clicks it.

14

www.roguewave.com

WHITE PAPER

Figure 4 SECMenuButton with pop-up menu

SECWellButton SECWellButton provides a color selection button. The face of the button displays the currently selected color. When the user clicks the button, a color appears below the button that allows the user to select a color.

Figure 5 SECWellButton with SECPopupColorWell control

Color Well Control

The Objective Toolkit color well components provide a sophisticated color selection control. This control displays the 20 system colors in a 4 x 5 grid. The user selects a color by clicking the cell containing that color. Each color well can have an additional button that displays a common color selection dialog when the user clicks it. This dialog allows the user to select a color other than those displayed on the face of the grid. SECColorWell SECColorWell implements an intuitive color picker window that you can embed in a dialog window or a CFormView. The color well automatically sizes to fit its content and you can apply a 3D raised border to it. SECColorWell optionally supports palette realization of its color.

Figure 6 SECColorWell control

15

www.roguewave.com

WHITE PAPER

SECPopupColorWell SECPopupColorWell has been designed for use with the SECWellButton component. It builds on the functionality of the SECColorWell component to provide a pop-up color selection window. This window self-destructs when it loses focus or when a color is selected.Masked Edit Control

SECMaskEdit provides a subclassed CEdit that lets you specify the format and restrictions on the data entered. For example, if you want a user to enter a phone number, you set the mask to (###) ###-####. Then, SECMaskEdit can handle moving the cursor and restricting user input to digits where the # mask characters are located.

Figure 7 SECMaskEdit control

Browse Edit Control

A browse edit is a Windows edit control with a browse button positioned immediately to its right. The user can either type a value in the field or press the browse button and select a value from a dialog. A browse button is a push button with the label ... When you press a browse button, a dialog appears. This modal dialog contains possible values for the user to select. After the user chooses a value from the dialog, the value appears in the text field.

Figure 8 Example browse edit control

SECBrowseEditBase SECBrowseEditBase is an abstract base class that provides the interface and some of the functionality of a browse edit control. SECBrowseFileEdit SECBrowseFileEdit provides the functionality of a filename edit control. A filename edit is a browse edit that is customized for entering a filename. In a filename edit, the user can either type a filename or pick one from a dialog. SECBrowseDirEdit SECBrowseDirEdit provides the functionality of a directory edit control. A directory edit is a browse edit that allows the user to enter a directory name. The user can either type a directory name in the field or select one from a dialog.

16

www.roguewave.com

WHITE PAPER

Marquee Control

SECMarquee is derived from CWnd. Like any other control, it can be embedded in a view or dialog. The marquee can be used anywhere a CStatic can be used with scrolling enhancements.

Figure 9 SECMarquee example

Progress Control

The SECProgressCtrl includes several enhancements to the existing progress control, such as smoothfill with percentages, multidirectional progressions (left to right, right to left, bottom to top, or top to bottom), fully configurable foreground/background coloring, and custom status text with configurable fonts. The progress control also offers powerful virtual hooks for you to provide your own customizations easily.Editable List Box Control

An editable list box is a Windows list box that contains items that the user can modify interactively. The user can modify the order of list box items, create and delete items, and edit the content of items. The editable list box is similar to the Visual Studios Include and Library path editors that are accessible from Tools|Options. You can edit text in place by selecting the item and typing or you can browse for a value by clicking the browse button to the right of the item. A browse button is a push button labeled ... that is only visible after the user double-clicks on an item. When you press the browse button, a dialog directs the user to choose from a list or tree of possible values. After the user picks a value and closes the dialog, the selected item appears in the list box. The following figure illustrates the SECListBoxEditor and the SECListBoxFileEditor components in action. The four buttons above each list box permit the creation, deletion, and reordering of items.

17

www.roguewave.com

WHITE PAPER

Figure 10 SECListBoxEditor and SECListBoxFileEditor controls in a dialog

SECListBoxEditor SECListBoxEditor implements an editable list box that supports item creation, deletion, reordering, and in-place text editing. However, it does not support browsing. If browsing is required, you must derive a class from SECListBoxEditor and override its OnBrowse() method. SECListBoxFileEditor SECListBoxFileEditor is an editable list box that is customized for entering a list of filenames. An SECListBoxFileEditor object enables users to enter filenames by typing or by picking from a file selection dialog. SECListBoxDirEditor SECListBoxDirEditor is an editable list box that is customized for entering a list of directories. An SECListBoxDirEditor object enables users to enter directory names by typing or by picking from a directory selection dialog.Tab Control/Tabbed window Components

The tab control/tabbed window components work with the document/view interface to give the user a choice of either two- or three-dimensional tabs for switching between views. The following figures show tabbed windows and tab controls with two and three dimensions.

18

www.roguewave.com

WHITE PAPER

Figure 11 2D tabbed window in a view

Figure 12 3D tabbed window in a view

SECTabControlBase SECTabControlBase is an abstract base class that defines the interface API of a tab control. A tab control is a small, rectangular window that draws tabs and processes mouse events. SECTabControl SECTabControl implements a tab control with a two-dimensional look and feel. The SECTabControl inherits its interface from SECTabControlBase and adds the implementation details that define its appearance. SEC3DTabControl SEC3DTabControl implements a tab control with a three-dimensional look and feel like Visual Studios Project Workspace window. Tabs can now be positioned top, bottom, left, or right. The SEC3DTabControl inherits its interface from SECTabControlBase and adds the implementation details that define its appearance.

19

www.roguewave.com

WHITE PAPER

SECTabWndBase SECTabWndBase is an abstract base class that defines the interface of a tabbed window that contains a tab control and one or more child windows (one per tab in the tab control). A tabbed window contains and manages the layout of a tab control and one or more child windows (or pages). When a tab is selected with the mouse, the associated page is activated. SECTabWndBase supports a rich set of operations that allow new views to be added, deleted, renamed, activated, scrolled into view, and so forth. In addition, the appearance of the tabs can be customized to use different colors, fonts, tab shapes, and more. SECTabWnd SECTabWnd implements a tabbed window with a two-dimensional look and feel. The SECTabWnd inherits its interface from SECTabWndBase and adds the implementation details that define its appearance. The SECTabWnd interface is modeled after the popular MFC class, CSplitterWnd. SEC3DTabWnd SEC3DTabWnd implements a tabbed window with a three-dimensional look and feel similar to Visual Studios Project Workspace window. Tabs can be positioned top, bottom, left, or right. The SEC3DTabWnd inherits its interface from SECTabWndBase and adds the implementation details that define its appearance.Calculator Edit Control

Figure 13 demonstrates usage of the Objective Toolkit calculator and pop-up calculator edit controls.

Figure 13 SECCalculator and SECPopupCalculator in a dialog

20

www.roguewave.com

WHITE PAPER

SECCalculator SECCalculator implements a calculator edit control capable of decimal arithmetic and other standard operations. SECPopupCalculator SECPopupCalculator creates a popup window for the calculator that is destroyed whenever the = key is pressed. SECCalcBtn The base class of the buttons on the calculator is SECCalcBtn. A helper class called SECCalcBtn::Attrib defines the attributes used for drawing the calculator button.Calendar Control

SECCalendar is a CWnd-derived control class that implements a calendar control for date entry and display. Through the use of member functions, days on the calendar can be highlighted and selected. If you use the derived SECPopupCalendar component, you can view the calendar control as a drop-down window to save screen space. Figure 14 demonstrates the use of SECCalendar.

Figure 14 The calendar control

Currency Edit Control

Two components implement the currency edit control: SECCurrencyEdit and SECDropEdit.

21

www.roguewave.com

WHITE PAPER

SECCurrencyEdit is an extensible component for entering and displaying custom formatted currency data. Input data parsing and output display formatting can be customized by deriving new components from SECCurrencyEdit and SECCurrencyEdit::Format. The following figure illustrates use of the Objective Toolkit currency edit control.

Figure 15 The currency edit control in a dialog

SECDropEdit SECDropEdit adds a combo drop-down button to an edit control. This component is used with SECCurrencyEdit and SECCurrencyEdit::Format to implement the currency edit control. SECCurrencyEdit::Format is a nested helper class that provides the core currency formatting and parsing functions.Customizable Status Bar

Objective Toolkits custom Windows status bar has more features and is easier to configure than MFCs CStatusBar.

22

www.roguewave.com

WHITE PAPER

SECCustomStatusBar allows you to configure the fonts, text alignment, and foreground and background colors in status bar panes. In addition, the custom status bar incorporates a progress indicator that can be programmatically shown in place of the status bar panes. When there is no progress to illustrate, the progress indicator is hidden. You can also embed icons in status bar panes. SECCustomStatusBar also provides support for handling mouse events in status bar panes.

Figure 16 The SECCustomStatusBar

Customizable Toolbar

Objective Toolkits customizable toolbar components extend traditional toolbars by allowing the user to easily drag and drop toolbar buttons into custom toolbar configurations.

Figure 17 Customizable toolbar dialog

The preceding figure is an example of the highly dynamic dialogs you can implement with the customizable toolbar components. In variety and configurability, these toolbars are comparable to those found in Visual Studio. SECCustomToolBar SECCustomToolBar lets your users create customizable toolbars from scratch. Each toolbar can be assigned a set of buttons in a style geared toward a specialized task. From a Customize dialog, a user

23

www.roguewave.com

WHITE PAPER

can add or delete buttons and set a style from default or custom categories. For example, one set of buttons can represent common File operations and another set can represent a user-defined task. In the toolbar dialog, the user can choose between large or small buttons, enabled or disabled ToolTips, and conventional appearance or the cool look. After a user selects a button, it can be dragged to any toolbar. SECCustomToolBar objects are derived from SECControlBar, not from CToolBar/SECToolBar. The following components work in conjunction with SECCustomToolBar: SECToolBarManager manages customizable toolbars and the state of an applications main frame during customize mode, which is invoked by SECToolBarsDlg, SECToolBarsPage and SECToolBarCmdPage. SECToolBarsBase provides a common code base for SECToolBarsDlg and SECToolBarsPage, which provide a user interface for listing and manipulating toolbars. SECToolBarsDlg displays a list of toolbars to the user. This component implements the Customize dialog, which allows a user to select toolbar buttons, manipulate default toolbars, and create a toolbar from scratch. In the toolbar dialog, the user can choose between large or small buttons, disabled or enabled ToolTips, and conventional appearance or the new cool look. SECToolBarCmdPage presents all the available toolbar buttons to the user. These buttons can be dragged onto an existing toolbar or used to create a new toolbar. This component should be used in conjunction with a toolbar manager and SECToolBarSheet. It cannot be used directly in a CPropertySheet. SECToolBarSheet constructs a property sheet used in conjunction with toolbar button templates created by SECToolBarCmdPage and SECToolBarsPage. SECToolBarsPage constructs a toolbar property page for the Customize dialog implemented by SECToolBarsDlg. SECNewToolBar constructs the New Toolbar dialog, which is invoked from the Customize dialog.Shortcut Bar Control

SECShortcutBar is a new metaphor for a container class. This container class can hold any embedded CWnd-derived objects. Because the shortcut bar is a CWnd-derived class, it can also be embedded anywhere. Accordingly, you can embed shortcut bars in docking windows or the pane of a splitter window, or allow them to overtake the entire client area of the frame window.

24

www.roguewave.com

WHITE PAPER

Figure 18 The SECShortcutBar with icons you can select

List Bar Control

SECListBar is a specialized SECBar that knows how to insert and remove items from its associated CWnd. The CWnd needs to be an SECShortcutListCtrl or an SECShortcutListCtr-derived class.

Figure 19 The SECListBar with an embedded tab control

Date/time Edit Control

Figure 20 The date/time control with various default formats

SECDateTimeCtrl SECDateTimeCtrl is a date/time edit control. This component works in conjunction with SECDTGadget, which is an abstract base class for the gadget components used by SECDateTimeCtrl.

25

www.roguewave.com

WHITE PAPER

SECDTGadget SECDTGadget is an abstract base class for the gadget components used by SECDateTimeCtrl, which is a date/time editing control. There are several subclasses that are based on SECDTGadget: SECDTStaticGadget implements a non-editable text gadget. SECDTNumericGadget implements an editable numeric gadget. SECDTListGadget implements a text gadget with a defined list of possible strings. SECDTButtonGadget implements a simple push button gadget. SECDTSpinGadget implements a spin button gadget.Extended Win32 Tree Control

A tree control is a window that displays a hierarchical list of items, such as the headings in a document, the entries in an index, or the files and directories on a disk. The Win32 tree control in the Windows common controls has some limitations, the most significant being its lack of support for multiple selection. Objective Toolkit includes an extended Win32 tree control that adds support for multiple selection, plus an integrated grid with resizable header row, wordwrap, extended ToolTip functionality, alternative viewing modes (for example, current branch + parents), and various color options. Each option is controlled by a style that permits the feature to be enabled or disabled. The following diagram compares MFCs tree control with Objective Toolkits extended version.

26

www.roguewave.com

WHITE PAPER

Figure 21 An MFC control compared to Objective Toolkits extended tree control

SECTreeCtrl By deriving from SECListCtrl, the SECTreeCtrl component is capable of multiple selection, allowing a range of tree items to be selected. Each node of the SECTreeCtrl has an associated SECTreeCtrl::Node item. Each tree node consists of a text label and icons indicating selection states. Each node can have a list of items (or children) associated with it. By clicking a node, the user can expand or collapse the associated list of items. In addition, SECTreeCtrl implements a grid on a dialog template. This enables: Wordwrapping of text labels ToolTips on nodes Highlight and caret to occur simultaneously

27

www.roguewave.com

WHITE PAPER

Alternative tree view modes (normal or grey parents) SECTreeCtrl has several auxiliary components, including SECTreeCtrl::Node, SECTreeNode, SECTreeNodeX, and SECTreeCtrlToolTips. SECListCtrl SECListCtrl currently contains a subset of functionality required to implement the SECTreeCtrl derivative. For this reason, SECListCtrl is not intended for general use. By deriving from SECListCtrl, SECTreeCtrl allows a user to select multiple items from a range of items. SECTreeCtrl also allows a user to click an item to expand or collapse its associated subitems. SECListCtrl implements a list view control that holds data associated with SECTreeCtrls nodes. A list view control displays a collection of items; each item consists of an icon and a label. Additional information about each item can be displayed in columns to the right of the icon and label. SECListCtrl manages columns and their headers as well as rows of data. Individual cells in a row can contain text strings or bitmap images, or both. The control can be set with or without grid lines. The default mode is on. SECTreeCtrl::Node This component provides state and draw information for each node. Each node of an SECTreeCtrl-based hierarchical tree control nests an SECTreeCtrl::Node item. Moreover, the value of a particular nodes HTREEITEM equates to the SECTreeCtrl::Node* for that node or SECTreeCtrl::Nodes base classes, which are SECTreeNodeX and SECTreeNode. Each nodes item consists of a label and an optional bitmapped image, and each item can have a list of sub-items associated with it. By clicking an item, the user can expand and collapse the associated list of subitems. A node can appear in two view modes: normal tree view or grey parents mode. SECTreeCtrlToolTips SECTreeCtrlToolTips adds ToolTips to an SECTreeCtrl-based tree control. A ToolTip is a small pop-up window that presents a short description of an item or a prompt to the user. ToolTips are displayed when the user positions the mouse over an item in the tree for a period of time.

Objective Toolkit User Interface ExtensionsObjective Toolkit supports a variety of user interface extensions including a workspace manager (save/ restore), keyboard shortcut, user tools menu, and thumbnail.The Workspace Manager

The Objective Toolkit workspace manager provides a powerful, yet easy to implement mechanism for saving and restoring multiple window and control bar configurations. Designed with extensibility in mind, the workspace manager provides many useful virtual functions to hook in your own custom storage

28

www.roguewave.com

WHITE PAPER

protocol or media (registry, file, network, and so forth), or to customize existing functions. In addition, the workspace manager exports an effective, easy-to-use dialog for administration of these workspaces. The workspace save/restore feature is an enhancement that does not require you to change or redesign your user interface to use it. Moreover, the workspace save/restore user interface enhancement can be used with the Stingray Studio MDI, FDI, MTI, or Extended Control Bar Architecture enhancements. The workspace manager tracks the creation and destruction of all windows in the application. It can save and then later restore the position, dimensions, and content of all windows. To gather the information required to restore the content of a window, the workspace manager calls upon the document/view architecture. As long as your application is document/view-based, the workspace manager works automatically. The workspace manager consists of two components: SECWorkspaceManager and the new, more powerful SECWorkspaceManagerEx. SECWorkspaceManagerEx features the following enhancements over SECWorkspaceManager: Persistence of workspaces directly to either a file or the registry Persistence of multiple views per document Persistence of an applications current activation state Workspace versioning Full support for Objective Toolkit docking windows, toolbars, and menubars Support for Docking Views SECWorkspaceManagerEx is easier to integrate into your application than the old SECWorkspaceManager. It is easy to extend with your own custom configuration information and your own custom persistence protocol. SECWorkspaceManager is now offered solely for backward compatibility, so if you have never used Objective Toolkit, you will want to use SECWorkspaceManagerEx exclusively. All data persisted by SECWorkspaceManagerEx is stored in a tree of SECPersistentTreeNode (PTN) objects. Each object can have an arbitrary number of key-value pairs to represent one piece of data. This model is similar to the Windows system registry. By default, SECWorkspaceManagerEx stores the application state in a preset tree where settings are grouped logically according to their role (for example, controlbar settings are in one subtree and child

29

www.roguewave.com

WHITE PAPER

frame windows in another). By overriding the appropriate Open() and Save() workspace manager methods, you can easily add your own child PTN objects to be included in the workspace state.Keyboard Shortcut Components

The Objective Toolkit keyboard shortcut components provide an easy way to allow users to redefine the keyboard for your application. These components are able to update the accelerator table at run time with key bindings that the user chooses. In addition to the implementation details required to edit the key bindings at run time, Objective Toolkit also includes a shortcuts dialog that you can reuse in your application. The following figure demonstrates how to use the shortcut dialog to make a keyboard assignment for the File|Open command.

Figure 22 Shortcut dialog awaiting a new keyboard assignment for the File|Open command

SECShortcutTable SECShortcutTable contains key bindings in the form of an array of ACCELs. SECCommandList SECCommandList contains the list of all command IDs that can be assigned together with a short and a long description. Any and all parts of SECCommandList can be defaulted.User Tools Menu Components

Objective Toolkits user tools menu components implement a user-configurable tools menu like the one in

30

www.roguewave.com

WHITE PAPER

Microsoft Visual Studio. The user can add custom menu items and specify what action occurs when the menu item is selected.

Figure 23 The SECUserToolsDlg

SECUserTool SECUserTool provides an abstraction of a user tool. A user tool is an executable that can be spawned programmatically by the application. An SECUserTool object encapsulates the filename, commandline arguments, and initial directory that describes how and where to run the executable. In addition, the SECUserTool interface contains an Execute() member function that uses these attributes to launch the user-defined tool. SECUserToolsDlg SECUserToolsDlg implements a user tools dialog. A user tools dialog allows a user to edit a list of user tools, where each tool is represented by one SECUserTool object. In this dialog, the user can create new user tools, edit and delete existing user tools, and reorder the list of user tools.Thumbnail Components

Many Windows applications like Microsoft PowerPoint support thumbnailing. Thumbnailing lets the user preview files without having to open them. Objective Toolkit provides thumbnail support through the document/view architecture. The following sections describe the Objective Toolkit components that implement thumbnail support.

31

www.roguewave.com

WHITE PAPER

Figure 24 Example using the thumbnail component

SECTNBitmap SECTNBitmap is a CBitmap derivative that creates, saves and displays thumbnail images. SECTNDC SECTNDC is a CDC derivative that is passed to your SECTNViews OnDraw() method. The view draws the thumbnail image onto the SECTNDC, and Objective Toolkit then handles conversion to an SECTNBitmap and saves the image. SECTNDocument SECTNDocument is an optional CDocument derivative that stores an SECTNView thumbnail image during serialization and bypasses the thumbnail image when reading. SECTNFileDialog SECTNFileDialog uses a CFileDialog derivative to display a thumbnail. It also automatically reads and displays the thumbnail image when the user clicks a file name in the dialog. SECTNView SECTNView is a CView derivative that can automatically generate a thumbnail by drawing onto an SECTNDC. You can override this behavior so that applications can implement their own thumbnail drawing routines using an interface similar to CView printing.

32

www.roguewave.com

WHITE PAPER

SECTNWinApp SECTNWinApp automatically creates an SECTNFileDialog when the user selects Open from the File menu.

Extended Control Bar ArchitectureThe docking window support provided by MFC version 4.x is limited. Dockable windows can only be docked to the MDI parent frame or floated on the desktop. When docked, the dockable window can be repositioned but not resized. When floating, a dockable window can be resized in the horizontal or vertical directions, but not diagonally. The extended control bar architecture removes the above limitations and adds a host of new features, including those found in Microsofts Visual Studio. When docked, dockable windows can be resized via splitter bars positioned along the windows edge. When floating, a dockable window can be resized horizontally, vertically, and diagonally. Each dockable control bar can be stretched automatically when resized, or you can implement your own form of resize handling. In addition, each control bar has a default context menu accessed with a right mouse button that contains Show/Hide and Allow Docking menu items by default. Menu items can be added and subtracted from the context menu. Objective Toolkit docking windows also support control bars similar to Visual Studio 97. Extended styles allow you to customize attributes, including optional gripper, Hide button, and Expand button support. In addition, you can easily extend the gripper code with your own custom drawing code. Another feature is AutoHide, which allows the display of more information using less screen space by hiding or showing windows. This is done with a right click context menu, or by clicking the pin control. This moves the window to a border and displays a small icon. When you mouse-over a hidden window, it will again display. To keep the window visible, press the pin control again. The Stingray extended control bar architecture has been designed to extend MFCs docking control bar architecture, not alter it. Very few interface changes have been made, so your knowledge of MFCs CControlBar, CDialogBar and other classes still applies. A new feature as of Stingray Studio 2006 are auto-hide docking windows. Auto-hide docking windows are similar to the pinnable windows in Visual Studio. They are an extension to the Docking Windows architecture that deals specifically with the SECControlBar class. With this new feature, you can unpin a control bar, essentially hiding it while still keeping it docked to the corresponding dockbar. To unpin a control bar, simply click the pin button. Adding the Stingray dockable window enhancements to your application requires little more than a few base class changes.

33

www.roguewave.com

WHITE PAPER

Figure 25 Example using the extended control bar architecture

SECControlBar This component adds the internal state and implementation details required to support sizing when docked. It is a simple step to re-derive existing CControlBar-based classes from SECControlBar. SECDialogBar This component derives from SECControlBar and duplicates the CDialogBar implementation details. Re-derive your CDialogBar-based classes from SECDialogBar. SECToolBar This component adds support for sizing the toolbar when it is docked. SECToolBar derives from SECControlBar and duplicates the CToolBar implementation details. It is easy to re-derive your CToolBar-based classes from SECToolBar. SecToolBar also supports multiple toolbar bitmap resources. SECStatusBar This component serves as the base class for your applications status bar. SECStatusBar does nothing more than re-derive from SECControlBar so that all member variables and implementation details exist as the extended control bar architecture expects. Embed CWnd-derived control inside its pane.

34

www.roguewave.com

WHITE PAPER

SECMenuBar SECMenuBar replaces your menu with a dockable bar that has the look and feel of the Visual Studio and Office 2003 menus. SECMenuBar uses SECCustomToolBar as a base class. Consequently, not only does your menu bar have the cool flat look, but it is also completely customizable when used in conjunction with SECToolBarManager. SECDockState This component makes it possible to save control bar position and size, and then restore it in a later session. To add this feature, change all occurrences of CDockState in your application to SECDockState. SECFrameWnd This component adds the implementation details required to support enhanced docking window capabilities. Re-derive your CFrameWnd-based classes from SECFrameWnd. SECMDIChildWnd This component adds the implementation details necessary to support the enhanced docking window capabilities. SECMDIChildWnd derives from CMDIChildWnd. Re-derive your CMDIChildWnd-based class from SECMDIChildWnd. SECMDIFrameWnd This component derives from CMDIFrameWnd and adds the implementation details necessary to support the enhanced docking window capabilities. Most of the code introduced by the component consists of internal details. To make use of this code, you need to re-derive your CMDIFrameWnd-based class from SECMDIFrameWnd.

Objective Toolkit MDI Alternatives and EnhancementsObjective Toolkit offers the following MDI alternatives and enhancements: Multiple Top-level Interface (MTI), Floating Document Interface (FDI), and Workbook Document Interface (WDI). Before we explore how to use the components supporting these MDI alternatives and enhancements, lets consider the purpose of MTI, FDI, and WDI.Multiple Top-level Interface (MTI)

MTI can best be described as a combination of SDI and MDI. As in SDI, each top-level window manipulates one document, but as with MDI there can be multiple open documents. MTI creates a new top-level window for each new document. Each new top-level window can include its own menu bar and tool bars. With the Windows taskbar, each MTI window can be easily activated.

35

www.roguewave.com

WHITE PAPER

This approach is common in other GUI operating systems such as the OSF/Motif windowing system for UNIX. Now it is becoming commonplace in Windows as well. Figure 26 illustrates the Multiple Top-level Interface alternative.

Figure 26 The Multiple Top-level Interface (MTI) MDI alternative

SECToplevelFrame SECToplevelFrame is the basis for the MTI MDI-alternative. MTI applications derive from SECToplevelFrame. An MDI application derives from CMDIChildWnd.Floating Document Interface (FDI)

FDI is like MDI except the MDI children float freely on the desktop instead of being confined to the MDI parent window. As with MDI, you can have multiple documents open. FDI creates a new floating child window for each new document. Each FDI child window appears as a top-level window and manipulates one document. Each FDI child window can optionally include a menu bar containing menu items specific to that window. FDI-based applications have a look and feel similar to the Microsoft Visual Basic environment.

36

www.roguewave.com

WHITE PAPER

Figure 27 Example application using the Floating Document Interface (FDI)

Figure 28 Demo of the SECTabWnd Embedded in an SECControlBar

SECFDIChildWnd SECFDIChildWnd is a document window similar to an MDI child window, except that it floats freely on the desktop instead of being confined to a parent frame. FDI applications derive from SECFDIChildWnd while MDI applications derive from CMDIChildWnd. SECFDIFrameWnd SECFDIFrameWnd is a main frame window which adds support for the Window menu and the Windows dialog. FDI applications derive from SECFDIFrameWnd, while MDI applications derive from CMDIFrameWnd.Workbook Document Interface (WDI)

The Objective Toolkit WDI components enhance MDI by allowing the user to place all documents in tabbed windows. This has the benefit of reducing MDI modality. In other words, all of the documents

37

www.roguewave.com

WHITE PAPER

are visible to the user as worksheets, so the user does not have to search the Window menu to locate the document. Figure 29 illustrates the Objective Toolkit WDI interface.

Figure 29 Sample application using the Workbook Document Interface (WDI)

SECWorkbook SECWorkbook is derived from SECMDIFrameWnd and adds the workbook (WDI) interface enhancements. Derive your main frame window class from SECWorkbook if you want to add the workbook interface enhancements. SECWorksheet SECWorksheet is derived from SECMDIChildWnd and adds the WDI enhancements. Derive your MDI child windows from SECWorksheet if you want to add workbook interface enhancements.Using MTI, FDI, and WDI

These MDI alternatives may seem complex at first, but fortunately Objective Toolkit hides this complexity from the engineer. To change your MFC MDI-based application to an Objective Toolkit MTI- or FDIbased application, derive your frame window classes from one of Objective Toolkits frame window components instead of CFrameWnd or CChildFrame. For example, to convert your application from MDI to FDI, derive your CChildFrame class from SECFDIChildWnd and your CMainFrame class from SECFrameWnd.

38

www.roguewave.com

WHITE PAPER

The Gradient Caption Extension

The gradient caption extension is a frame window enhancement that provides simple emulation of the smooth gradient caption effects found in Microsoft Office. The extension also provides control over the caption text alignment. Note: The Gradient Caption Extension is not available on the Windows XP platform. The gradient caption feature is incorporated into the existing SECFrameWnd and SECMDIFrameWnd.

Figure 30 Sample application using the gradient caption frame component

SECFrameWnd This component derives from CFrameWnd and adds support for the gradient caption. SECFrameWnd also adds support for extended docking window features covered in the section entitled Extended Control Bar Architecture, beginning on page 30. SECMDIFrameWnd This component derives CMDIFrameWnd and adds support for the gradient caption and extended docking window features.

View ComponentsThe Objective Toolkit view components enhance the MFC document/view architecture by providing new features, including printing, print preview, and automatic updating. SECZoomView SECZoomView supports automatic zooming of a view. It supports two modes:zoom-to-fit and zoom normal. In zoom-to-fit mode, the view automatically zooms the view to fit the current size of the window. In zoom normal mode, the developer instructs SECZoomView when to zoom by specifying either a zoom rectangle or a zoom percentage.

39

www.roguewave.com

WHITE PAPER

SECPanView SECPanView builds on SECZoomView and adds panning support. Panning allows the user to grab the view and scroll it in any direction by moving the mouse. SECPanWnd In addition to basic panning support, SECPanView also provides an overview window named SECPanWnd that lets the user see and manipulate the entire view. Figure 31 demonstrates these panning enhancements.

Figure 31 The SECPanView and SECPanWnd (overview window) components

Image ComponentsThe Objective Toolkit image components let the developer manipulate the most popular graphic image types. SECImage SECImage is an abstract base class that defines the interface for each of the format components. This interface includes reading, writing, format conversion, and image manipulation. SECImage supports a variety of image manipulation routines, which include the following:

40

www.roguewave.com

WHITE PAPER

ContrastImage() sharpens or dulls the image. Crop() crops the image to the specified dimensions. FlipHorz() flips the image horizontally. FlipVert() flips the image vertically. Rotate90() rotates the image 90 degrees. The internal SECImage format is documented so you can easily implement your own image manipulation routines using the provided examples for reference. Since SECImage is derived from CObject, it fully supports CObject features such as run time class information, dynamic creation, and serialization. SECImage serialization is useful if you have images stored in your document that you would like to serialize along with other portions of your document. SECDib SECDib supports reading and writing of the popular Windows Device Independent Bitmap (DIB) format. Typically, a file in this format has a .bmp or .dib suffix. SECDib supports all color and compression formats for DIBs. SECGif SECGif provides reading and writing for Graphic Information File (GIF) images. The GIF format is defined by CompuServe and is one of the standard image types used by Internet browsers. Support is also included for interlaced GIF images. SECJpeg SECJpeg supports the JPEG compression scheme found in JFIF (JPEG File Interchange Format) files. This compression scheme is used in many Internet browsers and professional image applications. SECJpeg is based on the version 1.02 JFIF standard. SECPcx SECPcx supports the PC eXchange (PCX) format that many Windows graphics applications use for exchanging images. This format only supports 256 colors. SECTarga SECTarga handles the TGA (TarGA image file) format as defined by Truevision. Video Capturing Applications use TGA. In addition, it was one of the first image formats to support 24-bit color. SECTiff SECTiff can read and write Tagged Image File Format (TIFF) files. TIFF files are popular in scanning

41

www.roguewave.com

WHITE PAPER

applications. SECTiff supports version 6.0 of the TIFF standard and includes support for all image depths and compression schemes.Image Example

Now that you have seen how the Objective Toolkit image components fit together and have become familiar with the supported formats, lets look at an example. The code below shows you how to load a GIF file, display it, rotate it 90 degrees, and then convert and save the image as a PCX file.SECGif * pGif = new SECGif; pGif->LoadImage(mygif.gif); //should check for errors. //TODO display image using BitBlt/StretchBlt here. pGif->Rotate90(); //Rotate it! SECPcx * pPcx = new SECPcx; pPcx->ConvertImage(pGif); pPcx->SaveImage(mypcx.pcx);

Objective Toolkit Utility ComponentsObjective Toolkits utility components can be separated into two categories: non-user-interface components and miscellaneous user interface components.Non-User-Interface Utility Extensions

The components in this section solve non-user-interface problems and perform the following functions: Support data encryption/decryption in two different modes Compress and decompress files Access file system functions Generate random numbers Encapsulate the Win32 Registry APIs SECCryptoFile SECCryptoFile is a CFile derivative that provides encryption and decryption for data written to and read from a file. SECCryptoFile uses a triple-ranked Vigenere cipher that operates in either Electronic Codebook (ECB) or Output Feedback (OFB), which is also known as Cipher Feedback (CFB) mode. You need to supply a password, which can be entered by the user if desired, and choose an encryption method. SECCompressFile SECCompressFile is a CFile derivative that provides compression and decompression for data written to and read from a file. SECCompressFile provides a SetCompressedMode() member function to treat the file as a compressed

42

www.roguewave.com

WHITE PAPER

file type, or a normal CFile type. The user can either treat the entire file as a single compressed block of data or jump to known spots of the file to decompress a smaller portion of the file. SECFileSystem SECFileSystem is a component that allows you to access common file system functions such as retrieving general information about files and directories, reading directories, copying files, and more. You can also access parsing, GUI, and CStringList functions. SECRandom SECRandom provides a method for generating a random number based on a seed value. To skew the results of the random number generation, SECRandom also supports weighted vectors. SECRegistry Objective Toolkit provides an encapsulation of the Win32 Registry APIs. Using our registry abstraction, a developer can modify the registry through a common interface that is consistent under all versions of windows, even back as far as Windows 95. SECRegistry encapsulates the APIs used to access and modify the Windows Registry in a single component. The SECRegistry member functions pertain to the Win32 API.Miscellaneous User Interface Utility Extensions

The following components implement some other popular features for Windows applications. SECBitmapDialog SECBitmapDialog lets you create dialogs with either tiled or centered bitmaps in the background. This component supports 256 color bitmaps.

Figure 32 Example SECBitmapDialog

43

www.roguewave.com

WHITE PAPER

SECSplashWnd A splash window is a transient window that appears temporarily at application startup. Generally, the popup window displays a copyright notice while the application initializes. SECSplashWnd provides you with a ready-to-use splash window for your applications. All you need to do is insert your own splash bitmap and text. The splash window even deletes itself after a specified time or when the user clicks it, so you do not have to keep track of the splash window in your application. SECTipOfDay If you have used any Microsoft Office application, you are probably already familiar with the tip-of-theday concept. A tip of the day dialog is displayed at start up. It displays random but useful information about the application. SECTipOfDay stores tips in a plain ASCII file so you can easily create tip files (.tip) with any editor. SECTipOfDay is fully customizable. You can specify different fonts and icons, and change other attributes by deriving your own tip class from SECTipOfDay.

Figure 33 Example tip of the day using the SECTipOfDay component

SECTrayIcon SECTrayIcon helps MFC developers create applications that are invoked via the Windows tray interface. Animated icons are supported. If you look at the right edge of the Windows taskbar, there is a small tray of application icons and a system clock. This component provides your application with an easy-to-use mechanism to add your own custom icons to the system tray. It also provides UI feedback such as ToolTip text, context menu support, and animated icons.

44

www.roguewave.com

WHITE PAPER

Figure 34 Example of SECTrayIcon

Docking Views Objective Toolkit provides docking windows that enable you to designate any direct CWnd-derived window as dockable. The Docking Views in Objective Toolkit significantly extend dockability by allowing you to dock complete MFC CViews and frame windows. This metaphor provides the user with visual focus cues, updates the view menus automatically, and implements complete view dockability. Figure 35 shows Objective Toolkit Docking Views in action:

Figure 35 Objective Toolkit Docking Views

Challenges of Docking a CViewYou may be wondering why you cannot dock CViews or any arbitrary CWnd derivative with Objective Toolkits standard docking windows extended control bar architecture. There are several reasons: MFC assumes that a CView has a CFrameWnd as a parent. This assumption permits no other parents. The control bar architecture has no knowledge of DVA, of which a CView is an integral part.

45

www.roguewave.com

WHITE PAPER

You can attach a CView to a document, but the document template cannot perform the creation or initialization of the document, view, or parent window. Because the document wasnt created through standard processes, the document manager does not know of its existence, which causes problems during shutdown. A control bar cannot receive focus or become the active window. Control bars are intentionally designed to remain inactive and without focus at all times, whereas CViews are designed to be active and receive focus. This conflict of interest manifests itself in many strange ways, such as focus anomalies. A CView embedded in an SECControlBar cannot receive menu picks because the command routing is not implemented properly. Command handlers in your CView never get called because control bars are not visited when searching for a command handler. You can alter the command routing so that the control bar is visited, but you will never know which control bar to target, because the control bar never becomes active. A CView embedded in an SECControlBar cannot receive keyboard input reliably. Again, this is because the control bar can never become active. Keyboard events are routed to the windowusually the MDI child that is active. The user interface is poorly designed. The problems mentioned above are technical in nature. Even if you overcome the technical obstacles, the resulting UI will not adhere to the standard Windows UI. Lets assume you successfully embed a CView that can receive menu picks and keyboard events inside an SECControlBar. Despite your hard work, this CView still will not adhere to Windows UI standards because the control bars have no way to represent activation or, in other words, there is no caption bar to show activation. This confuses the user because a CView that is receiving menu picks and key presses doesnt have an active caption bar. Worse yet, the window that has the active caption is the most recently active MDI child, which isnt even active. However, because the MDI child has the active caption bar, most users expect menu picks and key presses to occur in that MDI child. Instead, they occur on a control bar that appears inactive. Many engineers assume that Visual Studio is embedding CViews inside its control bars. This is not the case. The Project Workspace window, for instance, is not a CTreeView, its a CTreeCtrl embedded inside the control bar. The Output Window is not a CEditView; its a CEditCtrl. If Visual Studio could dock CViews, then your header and source files would be dockable as well. They are not dockable because Microsoft hasnt solved the problems described above.

Docking Views: Architectural OverviewObjective Toolkit overcomes docking obstacles by providing an architecture that supports docking a CView. The main feature of the Docking Views architecture is the SECDockableFrame class. This class is a hybrid of a control bar and a frame window that possesses the attributes and functionality of

46

www.roguewave.com

WHITE PAPER

both. Like a frame window, an instance of SECDockableFrame can parent a CView, CSplitterWnd, SECTabWnd or any CWnd-derivative. An SECDockableFrame also has an optional title bar for showing activation and contains the logic required to change the menu bar when it is activated like a frame window. Lastly, like an SECControlBar, a dockable frame can be docked and resized when docked. The SECMultiDocTemplate class plays a key role in the Objective Toolkit Docking Views architecture. SECMultiDocTemplate is derived from CMultiDocTemplate. The role of CMultiDocTemplate is to create the document, view, and frame window, and then connect them together. It has the following features: Supplies knowledge of the SECDockable frame. Contains the logic to open a new document as a standard MDI child or docking document. Adds a ToggleDocking() member that allows you to open documents between docked and undocked states. Objective Toolkit contains changes and additions to previous Objective Toolkit classes, such as SECMDIFrameWnd and SECMDIChildWnd. These changes ensure that SECDockableFrame objects are included in the command routing class chain so that menu picks are properly routed to a docked document when it is active.

Using the Docking Views ArchitectureAdding Docking Views to your application is an easy process that entails changing several of the base classes used by your application to Objective Toolkit equivalents and using SECMultiDocTemplate instead of CDocTemplate. After you convert to Docking Views, you can customize Docking Views by turning different flags on and off.

Layout Manager FrameworkOne of the biggest problems you face as a Windows application engineer is how to manage window layout and device-independent positioning. Without Objective Toolkit you will spend a great deal of time writing thousands of lines of custom code to handle the resizing of dialogs and forms. Objective Toolkits Layout Manager addresses this challenge by providing a framework for implementing plug-in layout algorithms. The framework includes several sample layout algorithms, such as grid bag layout, relative, scaled, and more. It also provides the flexibility to design custom layout managers based on unique business needs. For example, a layout manager can be designed that supports low-resolution handling. The Layout Manager plugs seamlessly into an existing dialog, form view, control bar, property page, or any other window. It also allows you to nest layouts. Developers can integrate Layout Manager into applications in a matter of minutes.

47

www.roguewave.com

WHITE PAPER

The ProblemWhenever you create a dialog, form view, property page, or any other window with child window controls, you need to decide whether to let the user resize the window. You could forbid the resize event, but this leads to an awkward, unfriendly user interface. You could ignore the event, but this results in an ugly, under-utilized window with a disproportionate amount of extra space. Finally, you could trap the size event and code your own custom layout logic. Unfortunately, this requires a large amount of implementation-specific code that is time-consuming to create and difficult to change if you ever want to modify the windows layout. Adding support for resolution-independent positioning requires several more hours of work.

The SolutionObjective Toolkit provides a powerful layout management framework that encapsulates all the details of laying out your child window controls so you can concentrate on content rather than the mechanics of your user interface presentation. With the Layout Manager, you