CHAPTER 11 |
Designing for Microsoft Windows |
This chapter describes how you can use Sun WorkShop Visual to design applications to run under Microsoft Windows. Sun WorkShop Visual generates MFC (Microsoft Foundation Classes) code for your design which is then directly portable to Microsoft Windows. This chapter covers the following areas:
1. | Generating the Application - a brief description of the three flavors of C++ code generation and the option of generating dialog template files. This starts on page 363. |
2. | Starting in Microsoft Windows Mode - how to run Sun WorkShop Visual so that it checks your design for its suitability for MFC code generation. See page 364. |
3. | The Sun WorkShop Visual Window - a description of the visual differences you can see when running Sun WorkShop Visual for creating Windows designs. See page 365. |
4. | Microsoft Windows Compliance - details of the checking Sun WorkShop Visual does to make sure that your design is suitable for generating as a Windows application, starting on page 367. |
5. | Compliance Failure - what happens, and what to do, when an imported design fails the Windows compliance check. See page 373. |
6. | Using Links - how to use Links in designs for Microsoft Windows. See page 375. |
7. | Special notes for particular widgets and resource types - what to bear in mind when using the following: |
a. | Generating the Application - a brief description of the three flavors of C++ code generation and the option of generating dialog template files. This starts on page 363. |
b. | Generating the Application - a brief description of the three flavors of C++ code generation and the option of generating dialog template files. This starts on page 363. |
c. | Generating the Application - a brief description of the three flavors of C++ code generation and the option of generating dialog template files. This starts on page 363. |
d. | Generating the Application - a brief description of the three flavors of C++ code generation and the option of generating dialog template files. This starts on page 363. |
e. | Generating the Application - a brief description of the three flavors of C++ code generation and the option of generating dialog template files. This starts on page 363. |
8. | Using Third Party Widgets - how to use third party widgets (or user widgets) in your Microsoft Windows design. See page 381. |
9. | Method Declarations - how to control where methods are declared in the generated MFC code. See page 384. |
10. | Application Class - how to change the generation of CWinApp in the MFC code. See page 387. |
11. | File names - a note on some points you should bear in mind when naming files to be ported to Microsoft Windows. See page 387. |
12. | Code Generation - a description of the code generated for Microsoft Windows, starting on page 388. |
13. | Configuring Sun WorkShop Visual - a description of the resources relevant to creating designs for Microsoft Windows. See page 391. |
Chapter 12 "Creating a Microsoft Windows and Motif Application" provides step-by-step instructions for creating a Windows-compatible design and generating the MFC code for it. Following this tutorial would give you a detailed insight into the use of Sun WorkShop Visual for creating Windows applications.
This chapter makes certain assumptions about your knowledge of Sun WorkShop Visual. It is assumed that you understand structured code generation, as described in "Structured Code Generation" on page 255 and that you are comfortable with the idea of generating C++ code. "C++ Classes" on page 260 provides information on C++ in Sun WorkShop Visual.You may wish to follow the tutorial in Chapter 9 "C++ Code Tutorial" to gain experience with the generation of C++ code.
The best way to develop an application which is to be ported to different platforms is to encapsulate the platform specific parts in some way so that the body of the application is isolated from the implementation details. Sun WorkShop Visual uses its C++ code structuring capabilities to generate a set of classes for the user interface that have the same public interface, but two different implementations. In Sun WorkShop Visual these implementations are known as flavors. There are three flavors of C++ code that can be generated:
1. | Motif - The "vanilla" flavor is the same as generating C++ code when not using the Windows-aware version of Sun WorkShop Visual. The base classes are a very simple set provided, with source, with the Sun WorkShop Visual release. |
2. | Microsoft Windows MFC - The target base classes on the Microsoft Windows platform are the Microsoft Foundation Classes. These provide a fairly high level set of controls and functions which can be used to build user interfaces. |
3. | Motif XP - A set of base classes supplied with source as part of the Sun WorkShop Visual release. They are very similar to the Motif flavor base classes except that they are named to match the Microsoft Foundation Classes and provide a little of the basic functionality. They are not intended to provide the whole of the MFC interface, only enough to allow the developer some measure of shared code in the user interface. The real goal is in sharing code in the rest of the application. |
When you generate code for Microsoft Windows using MFC, you are given the choice of:
1. | Generating the dialogs in your design as dialog templates, which are Microsoft Windows resource files describing the dialog. |
2. | Generating the design in MFC code. |
For the first option above, Sun WorkShop Visual generates some MFC code to fetch widgets out of the dialog templates and to control the dialogs, thereby generating a complete application.
If the "Generate as Resources" toggle is not set, plain MFC is generated for your design. By default, the toggle is set.
To generate dialogs as resource files, set the "Generate as Resources" toggle in the Code Options dialog. The full capabilities of Sun WorkShop Visual's C++ model can still be used for MFC applications. This means that you can use sub-classing and inheritance to add additional functionality. These techniques can be used, for example, to support cross platform versions of your user-defined widgets.
There are three methods of invoking Sun WorkShop Visual so that it is running in Microsoft Windows mode. Select the method which suits you best, bearing in mind that you may have to share your copy of Sun WorkShop Visual with other users who do not want to run Sun WorkShop Visual in Microsoft Windows mode.
Microsoft Windows mode can be specified by a resource in the file containing your Sun WorkShop Visual application resources:visu.windows: true
Microsoft Windows mode can also be specified by a command line switch when invoking Sun WorkShop Visual:visu -windows
The third method of invoking Sun WorkShop Visual in Microsoft Windows mode gives the appearance of a separate application which is always in Microsoft Windows mode. This method uses the application resource, described above.
1. | Create a hard link to your Sun WorkShop Visual shell script in the $VISUROOT/bin directory. |
2. | Give this file a name such as visuwin. |
3. | Create a hard link to your Sun WorkShop Visual binary in the $VISUROOT/lib directory. Use the same file name as in Step 2. |
4. | Add the windows flag to the .Xdefaults file in your home directory, using the name of your symbolic link, as follows: |
visuwin.windows: true
In this way, you can simply typeThis will invoke Sun WorkShop Visual in Microsoft Windows mode. Other people can then continue to use Sun WorkShop Visual safe in the knowledge that the default will not be Microsoft Windows mode.
Note - This is the technique that Sun WorkShop Visual uses to bring up the version for smaller screens - such as the VGA screen. The program small_visu is nothing more than a hard link to the Sun WorkShop Visual binary which picks up an alternative set of resources from the Sun WorkShop Visual resource file.
The Sun WorkShop Visual Window looks slightly different when in Microsoft Windows mode. The main differences are the addition of two items in the toolbar at the top (and in corresponding menus) and the fact that some of the widgets are not included in the widget palette. This second point is dealt with in "Microsoft Windows Compliance" on page 367. The first set of differences is described here.
There are two Microsoft Windows Compliant toggles - one on the toolbar and one in the Module menu. They both have the same function.
FIGURE 11-1 The Compliance Buttons in the Toolbar (left)
and the Module Menu (right)
These toggles indicate whether or not the current design is Microsoft Windows compliant. If you read in a design created with a version of Sun WorkShop Visual not in Microsoft Windows mode or you cut and paste areas of a compliant hierarchy, it is possible to create structures which are not Microsoft Windows compliant.In such a case a message is displayed informing you where the problem is and the two Microsoft Windows Compliant toggles are unset. The toolbar toggle displays a red cross when it is unset. Having made the appropriate changes to your design, pressing either of these toggles will check the compliance again. If your design is now Microsoft Windows compliant, the toolbar button will be set (the red cross will disappear). If not an error message will appear indicating the problem and the toggles will remain unset.
The flavor menu in the toolbar specifies which flavor of code you wish to generate: plain Motif, Motif XP or Microsoft Windows. This only applies to C++ code generation.
In addition to the compliance issues which prevent code from being generated for Microsoft Windows, there are many attributes of a design which have no effect in the Microsoft Windows implementation (for example the alignment of a label on a button), because the Microsoft Windows toolkit does not support the concept. Sun WorkShop Visual indicates this by means of the following:
1. | Icon Cues. In the resource panels, those resources which have no effect on Microsoft Windows are indicated with a cross icon, those that do have an effect are indicated with a tick icon. |
2. | Color Cue. By default, text input fields and option menus in the resource panels use a pink color to indicate that setting the resource will have no effect in the Microsoft Windows flavor.1 |
If the variable name field of the selected widget is pink1, this indicates that the widget will not map to any equivalent Microsoft Windows object. For instance, in Microsoft Windows a menubar is simply an attribute of a Dialog, there is no menubar object. Consequently Sun WorkShop Visual will show the variable name pink for menubar widgets.Sun WorkShop Visual will also use this technique to indicate that some links will not be reproduced in the Microsoft Windows code. Links are discussed in more detail in "Using Links" on page 375.
Unfortunately for the user interface developer, the Motif and X toolkits bear little resemblance to the Microsoft Windows toolkit. Although the visual appearance is similar, the actual use of the toolkit is very different. This requires Sun WorkShop Visual to impose some restrictions on the developer before Microsoft Windows code can be generated for a design. Sun WorkShop Visual will impose these restrictions when it is in Microsoft Windows mode. When Sun WorkShop Visual is in Microsoft Windows mode it needs to permit the developer to work on designs which do not comply with these restrictions (so that an existing design can be read in for example). As a result Sun WorkShop Visual will check that a design is Microsoft Windows compliant. If a design is not Microsoft Windows compliant then C++ code can only be generated for the Motif flavor.This section details the restrictions imposed by Sun WorkShop Visual which ensure that Microsoft Windows compliant code can be generated. When in Microsoft Windows mode Sun WorkShop Visual will not allow you to create a design which violates these restrictions.
Because of the differences between Motif and Microsoft Windows in the way events are handled, some widgets cannot be made classes. In Microsoft Windows, events concerning certain widgets are always sent to the enclosing class. Other widgets must be classes in order to handle Microsoft Windows messages. Here is a list of these restrictions:
Cannot be class |
- | MenuBar |
- | PopupMenu |
- | CascadeButton |
- | OptionMenu |
- | Any widget which is the child of a Shell |
Must be class |
- | Shells |
- | ScrolledWindow (unless child of Shell) |
- | Frame |
- | RadioBox, unless the child of a Frame |
- | DrawingArea (unless child of MainWindow, ScrolledWindow or Shell) |
- | Paned Window |
- | Child of Paned Window |
The first error you are likely to encounter on reading a non-compliant design is the fact that the Shell must be structured as a C++ class. This error is easy to fix and can be done automatically from the Compliance Failure dialog. See "Compliance Failure" on page 373 for more details.
The method is declared in MBar_class. If you then read the design into a version of Sun WorkShop Visual in Microsoft Windows mode, you will be presented with the following error message because MenuBars cannot be classes:
If you remove the class definition of the MenuBar (using the Core Resources dialog), you will then see the following error message:
FIGURE 11-5 Message Informing of Method Callback Declaration Invalidation
Make sure that the method declarations are removed from the MenuBar and, in this case, added to the Shell. You cannot add them to the Form because the Form, like the MenuBar, does not map to an object on Microsoft Windows.Although Sun WorkShop Visual assists you in the above way, changing whether a widget is a class or not could have a major impact on your application. You will need to reconsider the structure of your application very carefully.
Menubars in Microsoft Windows are created by setting an attribute of the Dialog. This leads to two compliance restrictions:
Only one Menubar per shell is supported. You cannot have a design which contains more than one Menubar in a Dialog |
The Menubar parent must be the child of the Shell. A Menubar cannot be an immediate child of a Shell, nor can it be at a deeper level in the widget hierarchy than as a child of the Shell's child |
The File Selection Box must be a child of a DialogShell or TopLevelShell. In Microsoft Windows file selection is provided by a pre-defined FileSelection Dialog. This dialog can only contain a single work area child, it cannot support a Menubar, nor additional buttons (not managed by the work area).
The following widgets have no comparable control in Microsoft Windows and so cannot be used in a design that is to be portable:
SelectionBox |
Command |
MessageBox |
SelectionPrompt |
DrawnButton |
ArrowButton |
All but the last two buttons, however, can be emulated using the Dialog Template widget, which is supported as a Windows control.
The Scale widget maps to a Microsoft Windows ScrollBar control which cannot support child controls. Therefore a Scale widget with children violates the Microsoft Windows compliance restrictions.
Because of the way messages are passed to an enclosing control, both Frame and RadioBox (if not the child of a Frame) have to be classes. However, as the child of a Shell cannot be a class, it follows that neither Frame nor RadioBox can be the immediate child of a Shell.The second child of a Frame must be a Label widget - this is the title of the Frame. The Frame control in Microsoft Windows (actually a CButton in disguise) simply has a title attribute. There is no way to use another control as the title. The first child can be any widget.
Microsoft Windows does not support automatic scrolling and hence Sun WorkShop Visual in Microsoft Windows mode disables automatic scrolling options. The MainWindow widget may only include a work area and Menubar child. It does not support the command window or message window.
A compliant design cannot contain a Paned Window which has Separator, MainWindow, OptionMenu, or MenuBar children. Neither may the children be definitions or instances.
The XmNlabelType resource cannot be explicitly set for a widget which is a component of a definition when it is instantiated in another design. if a Button does not have XmNlabelType set in a definition then when that definition is used XmNlabelType cannot be set to PIXMAP. This is because Microsoft Windows uses a different class (CBitmapButton instead of CButton) to implement a button with a bitmap on it. It is obviously not possible to change the class of a variable after it has been created, hence the restriction.For the same reason it is not possible to have a CascadeButton in a definition which has no Pulldown menu and to then add the Pulldown in an instance.
Slightly more subtly, it is not possible to have a widget with methods added to an instance which is not being sub-classed. For imagine you have an instance of RowColumn definition, and the root widget (i.e. the RowColumn) does not have its structure set to class. When not in Microsoft Windows mode it is possible to add a button to the RowColumn instance and give it a method callback which is declared in an enclosing scope (say a Shell class). This is not possible in Microsoft Windows; the event has to be handled by the enclosing control (in this case the CWnd which represents the RowColumn).
The widgets in a definition must be named. This is a requirement for all C++ definitions, not just those destined for use under Microsoft Windows.
When you read in a design which was created by Sun WorkShop Visual while not in Microsoft Windows mode or you use cut and paste in such a way as to cause a design to become non-compliant, the Compliance Failure dialog appears showing you which widgets are causing the design to be non-compliant..
You can select the widgets in the scrolled list of non-compliant widgets. You may then press one of the following buttons:
Go to - This highlights the widget in your design. If the widget is part of a dialog which is not the current one, the relevant dialog is selected. If the widget is in a part of the design which is folded, the design is unfolded. Double-clicking on a widget is the same as pressing Go to. For structure problems, Sun WorkShop Visual will also open the Core resources dialog on the Code Generation page. |
Next - This moves to the next widget in the list and selects the widget in the hierarchy. |
Fix - This fixes the problem, where possible. Sun WorkShop Visual can only fix those errors connected with the structure of a widget. Other errors cannot be fixed automatically. See "Microsoft Windows Compliance" on page 367 for a list of the possible compliance errors. |
This example shows how compliance failure is detected. In the hierarchy shown in Figure 11-7, the RowColumn widget rc_is_class has been made a class:
If you were to cut rc_is_class, clear the form and then paste (i.e. pasting rc_is_class as a child of shell), Sun WorkShop Visual would mark the design as non-compliant and display the Compliance Failure Dialog shown in Figure 11-8 indicating that the child of a shell may not be a class:
Sun WorkShop Visual allows you to continue with the operation but until you change the structure of rc_is_class, you will have a design which is not Microsoft Windows compliant. The Microsoft Windows compliant toggle in the toolbar displays a red cross to remind you.
In the Motif flavors links are pre-defined callbacks. In the Microsoft Windows flavor they are implemented as simple global functions which are called by a button's message handler. There are, however, some restrictions on how links can be used on Microsoft Windows. These restrictions only affect whether code is generated for a link, they do not affect the design's compliance.
If the widget selected as the destination of a link is not mapped to an object on Microsoft Windows, the Add button in the Edit Links dialog is pink. The link can still be added and will be effective on Motif but it will not be generated into the Microsoft Windows code. To indicate this, the widget in the list of links is pink. See "Mapping Motif Widgets to Microsoft Windows" on page 786 for more information on which widgets are mapped to Microsoft Windows objects.
When adding a link where the destination widget is a PushButton in a Menu, the type of link is restricted to enable and disable. You cannot show, hide, manage or unmanage a Menu Button on Microsoft Windows.
FileSelectionBox is implemented on Microsoft Windows as a CFileDialog, a modal dialog which is shown by calling the DoModal method. This method does not return until the FileSelection is complete or cancelled. On Microsoft Windows, therefore, only the show link is supported. For both MFC and Motif XP flavors the code is structured so that the DoModal method does not return until the selection is complete or cancelled.
The Motif manager widgets have no equivalents on Microsoft Windows. Widgets such as Forms and RowColumns do not exist on Microsoft Windows. If you have one of these in your design which is not a class, it is ignored in the generated code. If it is a class, Sun WorkShop Visual generates a Canvas in its place.If you are generating dialog templates from your design, most manager widgets are ignored because dialog templates tend to be flat. They do not use the containment hierarchy that is common on Motif. Your design, therefore, is flattened out in the template files. Widgets are taken out of sub-containers and made children of the dialog. This also enables system resources to be used throughout the design. See
If you choose to generate your design into Windows resource files (or dialog templates) along with the main application code, you will be able to make adjustments to the layout using your Microsoft Windows IDE (Integrated Development Environment). These changes cannot be taken back into Sun WorkShop Visual but they do allow you to make quick, simple adjustments right where they are needed.
If you do not wish to generate dialog templates, Sun WorkShop Visual generates code containing absolute values for sizes and positions as they are at the moment of generation. So, for example, if you have a PushButton that is 100 pixels wide, 30 pixels high and is located at 10, 200 then those explicit values will be used in the Microsoft Windows code, even though you have not explicitly set the x, y, width and height resources but allowed them to be calculated by the Motif toolkit. In practice this gives very good results - generating Microsoft Windows dialogs which look very similar to their Motif counterparts.
Because Sun WorkShop Visual is generating an absolute size for a Microsoft Windows control, it is important that the size of a dialog is appropriate for any font that will be used for text displayed in it. The best way to ensure this is to make Sun WorkShop Visual use a similarly sized font to display the dialog while it is being designed. There are two ways to do this.The first way is to force the control to use a particular sized font, perhaps by setting the XmNfontList resource for the control or by setting the appropriate font resource on the shell. Consequently the dialogs will be similarly sized.
Alternatively use a resource so that Sun WorkShop Visual displays the design windows with a font that approximates to the default font used on Microsoft Windows. This will cause Sun WorkShop Visual to generate absolute sizes that are appropriate to the font. The Motif code will use a default font in the normal way. To make Sun WorkShop Visual use a specific font for the design on Microsoft Windows, use settings similar to the following in your resource file:
visu*dialog.labelFontList:\
-adobe-helvetica-medium-r-normal-*-14-*-*-*-*-77-iso8859-1visu*dialog.buttonFontList:\
-adobe-helvetica-medium-r-normal-*-14-*-*-*-*-77-iso8859-1visu*dialog.textFontList:\These values may work well for you, but it will depend on the precise font used on your Microsoft Windows system. It is the size and average width values which are important.
-adobe-helvetica-medium-r-normal-*-14-*-*-*-*-77-iso8859-1
In Microsoft Windows mode, Sun WorkShop Visual generates OnSize message handlers to provide some resize behavior when the user resizes a dialog. Sun WorkShop Visual does not attempt to reproduce exactly the Motif geometry management, rather it generates a handler which will simulate the resize behavior of certain manager widgets. In particular, these are:
ScrolledWindow |
Form |
Frame |
DialogTemplate |
These managers do not need to be classes in order to produce the resize behavior; Sun WorkShop Visual generates a handler for the enclosing class that handles all descendant widgets. You can suppress the generation of the resize handler if you want to provide your own (through a sub class for example), by unsetting the MFC OnSize handler toggle on the Code generation page of the Core resources dialog. See Figure 11-9.
FIGURE 11-9 The Core Resources Dialog - Code Generation Page
In order for a font to be generated into the Microsoft Windows code you must use font objects. This is because fonts must be persistent on Microsoft Windows. Only by using font objects can you guarantee this. Sun WorkShop Visual provides a visual cue by making the Apply button pink if you select an item from the list of fonts in the font selection dialog. If, however, you select an item from the list of font objects, the Apply button is no longer pink.
If you specify fontlists for your objects in Sun WorkShop Visual, the first font in the list will be used for the object on Microsoft Windows. Compound strings containing a mixture of tags will be translated to Microsoft Windows using only the first font specified.
Fonts in Microsoft Windows are named using a different mechanism from that used by X Windows. However, Microsoft Windows has quite a sophisticated matching algorithm. So, although Sun WorkShop Visual uses a fairly crude mapping to translate the font specification, even if you specify a font which is not available in Microsoft Windows, it will probably be substituted with something that looks reasonable.
Pixmap objects created in Sun WorkShop Visual are converted into a Microsoft Windows bitmap or icon (depending on whether the object is a button or label respectively). This is done for you automatically when you generate a Microsoft Windows resource file. X monochrome bitmaps are not supported in the translation to Microsoft Windows.When you select "Microsoft Windows Resources" from the Generate dialog, Sun WorkShop Visual informs you that it will create a resource file and a bitmap/icon file for each pixmap you have created. Bitmap files are generated with the suffix ".bmp" and icon files with the suffix ".ico". You never need to save the pixmap to a file for Microsoft Windows but you may wish to do so for the Motif version. Note that icons are always scaled to 32x32 pixels on Windows.
For a Motif Button with a pixmap type label, Sun WorkShop Visual generates a CBitmapButton for Microsoft Windows. One difference between buttons with pixmaps on Motif and CBitmapButtons on Microsoft Windows is that CBitmapButtons have no border - in fact they do not look like buttons at all. You may, therefore, wish to incorporate a border in your pixmap design.
You can set the Background and Foreground color of a widget which will be mapped to an object on Microsoft Windows. These colors will be generated into the Microsoft Windows code in terms of their RGB (Red, Green, Blue) values. Microsoft Windows does not normally have the richness of color that is commonly available on X/Motif. For this reason the colors may not look identical on the two platforms. By default, however, the colors for the Microsoft Windows 95 "look and Feel" are used.
Specify the Background and Foreground colors in the usual way in Sun WorkShop Visual. Background colors must be color objects - Foreground colors do not have to be.
Sun WorkShop Visual can be extended to support widgets from any other Xt toolkit in addition to the default Motif set. Widgets added to Sun WorkShop Visual are called user-defined widgets or third party widgets. Chapter 23 "User-Defined Widgets" provides a detailed description of this topic. The new widgets appear in the Sun WorkShop Visual widget palette and can be used in the same way as the pre-defined Motif ones.Although, in Microsoft Windows mode, Sun WorkShop Visual does not provide explicit support for third party widgets, Sun WorkShop Visual's C++ model allows you some flexibility in this area.
Sun WorkShop Visual automatically treats third party widgets as though they are an instance of the class from which they are derived. So, for example, if you have a third party widget derived from XmPushButton, Sun WorkShop Visual will add it to your design as though it is an XmPushButton. Sun WorkShop Visual will then generate Motif XP code which is based on the CButton class, since this is the way XmPushButton is implemented in the Motif XP, to create an instance of your third party widget. The Microsoft Windows code will be exactly the same as if you had used a PushButton.The example above uses the XmPushButton class which is a class supported by the Motif XP. If, however, the third party widget is derived from a class which is not supported by the Motif XP then Sun WorkShop Visual cannot handle that widget and will not generate code for it. In this case, you should use the strategy outlined in the following section.
If Sun WorkShop Visual's default behavior for a particular third party widget (described above) is not satisfactory, you can use the flexibility of the C++ model to enhance Sun WorkShop Visual's behavior. There are two steps:
1. | Decide on a sensible mapping from your third party widget to a Windows control - whether that is a builtin MFC class or another third party component. For example, many third party widget sets contain a ComboBox widget; this would clearly map through to the builtin MFC CComboBox class. |
2. | Tell Sun WorkShop Visual the name of the class it should use. On the Code Generation page of the Core Resources panel, specify the C++ class structure to be generated for the selected third party widget. Sun WorkShop Visual fills this page in with its own mappings for the Motif components, but does not always know what to do with third party widgets, simply generating a basic Canvas in its place. All you would need to do here is to override the suggested classing with the mapping you feel is appropriate, and Sun WorkShop Visual will generate code accordingly. This means you will get an object of the right type rendered into your MFC code. |
On the Unix side, you would need to include a dummy class so that the code compiles there also for either pure Motif C++ or Motif XP, depending on what you want. The following is an illustration of the code you would have to add:/* Pure Motif C++ Code */#ifdef XD_MOTIF#define MY_BASE_CLASS xd_XtWidget_c /* Use the Base Sun WorkShop VisualWidget Class */#endif /* XD_MOTIF *//* Motif XP C++ Code (Unix C++ with strict MFC API) */#ifdef XD_MOTIF_MFC#define MY_BASE_CLASS CWnd /* Use the Base Motif XP "MFC" ControlClass */#endif /* XD_MOTIF_MFC *//* Windows C++ Code (Real MFC) */#ifdef XD_WINDOWS_MFC#define MY_BASE_CLASS CComboBox /* Use the Real Mapping MFCControl Class */#endif /* XD_WINDOWS_MFC */#if defined(XD_MOTIF_MFC) || defined(XD_MOTIF)class MyMappingClass_c : public MY_BASE_CLASS{}#endif /* XD_MOTIF_MFC || XD_MOTIF */For generating Motif XP, you could also extend the Motif XP library. See "Enhancing the Motif XP" on page 839 for details on how to do this
With third party widgets which it does not understand, Sun WorkShop Visual has no way of knowing which Motif resources map to which MFC resources. For these widgets you will probably have to add the code for their resources by hand. Here are some possible strategies:
1. | Put all the third party widget resources into Loose Bindings so that they go into the X resource file and are maintained inside Sun WorkShop Visual, thus working well on the X side,. Then hand-edit the MFC resource file for similar purposes. See "Loose Bindings" on page 87 for more information on how to create and use Loose Bindings. |
2. | Generate code on Unix with resources and the code options appropriately set, then generate no resources to code for the third party widgets and again maintain the MFC resource file by hand. |
3. | Specify a code prelude to add the resources you need. This can have anything you like in it, so you could do something like the following as a pre-manage prelude (assuming my_text is a class): |
#ifdef XD_MOTIF
XtVaSetValues(my_text->xd_rootwidget(), XmNvalue, "Hello", 0) ;
#endif /* XD_MOTIF */
#if defined(XD_MOTIF_MFC) || defined(XD_WINDOWS_MFC)
my_text->SetWindowText("Hello World") ;
#endif /* XD_MOTIF_MFC || XD_WINDOWS_MFC */
The Method Declarations dialog has an extra feature when in Microsoft Windows mode. There is a toggle button labelled Microsoft Windows MFC.
FIGURE 11-10 Method Declarations Dialog with Microsoft Windows MFC Toggle
This toggle is used to denote whether the method is declared in the class structure of the enclosing class when generating Microsoft Windows code. When generating Motif code, the method is still declared in the enclosing class. The enclosing class is the nearest ancestor which has its structure set to class (either explicitly or automatically).This toggle does not indicate whether or not the method appears in the Microsoft Windows code stubs - the Callbacks dialog indicates this. If, in that dialog, the method callback has an asterisk (*) appended to it, it will not be generated into the Microsoft Windows stubs file. The Microsoft Windows MFC toggle gives you control over the method declarations, although you would usually use the default that Sun WorkShop Visual provides. Use the Method declarations dialog to declare methods in a class of your choosing or declare them in one of your own classes. They must be declared somewhere.
When you add a method callback in the Callbacks dialog, if the method has not been declared already, Sun WorkShop Visual will declare it for you in the enclosing class. If you do not wish the method to be declared there, use the Method Declarations dialog to unset the Microsoft Windows MFC toggle.
If a DrawingArea is not the child of a ScrolledWindow, MainWindow or Shell it is created as a basic CWnd class - otherwise it is ignored for Microsoft Windows code generation. See "Mapping Motif Widgets to Microsoft Windows" on page 786 for more information.
The Motif XP class library does not include any drawing support; any you require will be platform specific. However, Sun WorkShop Visual does allow you to add callback methods which by default are only declared for Motif flavors and Microsoft Windows message handlers. When in Microsoft Windows mode Sun WorkShop Visual adds a set of additional toggle buttons to the DrawingArea resource panel which can be used to add a Microsoft Windows message handler in the generated code.
If, for example, you were to select the OnRButtonDown toggle in the panel pictured above, the following stub is added to your callback stubs file:afx_msg void scrolled_win_c::OnRButtonDown( UINT nFlags, CPoint point ){}Note that afx_msg is a pseudo keyword on Microsoft Windows. The following lines are added to your C++ externs file://{{AFX_MSG(scrolled_win_c)afx_msg void OnRButtonDown( UINT nFlags, CPoint point )://}}AFX_MSGDECLARE_MESSAGE_MAP ()This registers the message handler with Microsoft Windows.
Sun WorkShop Visual generates an instance of a CWinApp class to the MFC C++ flavors to represent the application. You can configure this class by means of the Application Class dialog which is displayed from the Module Menu. Figure 11-12 shows the dialog.
Note - The declaration of the application class (whether defined by yourself or using Sun WorkShop Visual's default) is only generated when you are generating a main procedure - the "Main Program" in the Generate dialog.
Filenames on the PC are restricted to 12 characters in total (including the dot) which must be distributed as no more than eight before the dot and no more than three after. If you wish to share files between the two platforms, this restriction will have to be kept in mind when generating Microsoft Windows code. Remember, also, that MS-DOS and Microsoft Windows are not case sensitive. Do not rely on upper and lower case letters to distinguish filenames.
The above restrictions should also be remembered when naming pixmap objects. When you ask Sun WorkShop Visual to generate a Microsoft Windows resource file after you have created pixmaps, Sun WorkShop Visual automatically generates Microsoft Windows bitmaps and icons in separate files using the name you specified in the pixmap editor. If, therefore, you have specified a name with more than eight characters, you will encounter problems on Microsoft Windows.
Different compilers have varied conventions acceptable on filename extensions. The suffix `.cxx' seems to be universally supported; most compilers should support `.cpp'; some compilation systems may accept `.C' and `.c++'. Visual C++ will complain if you specify `.c' for a file which contains C++ code.See "Setting the Filename Filter" on page 392 for details of how to change the default filters in the Generate dialog.
No makefile can be generated for the Microsoft Windows code files. Since make is a UNIX utility, it is assumed that you will be using a Microsoft Windows development environment (such as Visual C++) to build your application.
Note - If you are using Make on your UNIX platform, it is best to generate different code flavors into separate directories in order to avoid confusion and name clashes.
There are a number of points connected with code generation which you should understand before generating code. These are detailed in the following subsections. Briefly, they are:
1. | Generating Dialog Templates. How you can generate your dialogs as Microsoft Windows resource files which are more easily manipulated in your Windows environment. |
2. | Enhanced MFC. How to make sure that your generated Windows application uses the MFC 4 (and above) 3D look and feel. |
3. | Project Files. The Visual C++ project files that Sun WorkShop Visual generates for you. |
4. | Synchronizing Save and Code Files. How to make sure that your save file and generated code file remain in synch. |
5. | Dialog Flashing. A warning that dialogs are realized (and therefore displayed) when MFC code is generated. |
6. | Use of Japanese Font. What to do when generating MFC code containing Japanese text. |
When you generate code for MFC, the Generate Options dialog (displayed by pressing the "Options" button at the bottom of the Generate dialog) contains a toggle labelled "Generate as Resources". This is shown in Figure 11-13. When this toggle is set, Sun WorkShop Visual generates the dialogs in your design as dialog templates, which are Microsoft Windows resource files describing the dialog. Sun WorkShop Visual generates some MFC code to fetch widgets out of the dialog templates and to control the dialogs, thereby generating a complete application. If the "Generate as Resources" toggle is not set, plain MFC is generated for your design. By default, the toggle is set.
Using dialog templates gives you the following advantages:
1. | You can use your system default resources - such as font settings. This is not possible with plain MFC. |
2. | You can use your Microsoft Windows IDE to alter the layout of dialogs easily. Note, however, that you cannot take changes back to Sun WorkShop Visual. |
Designs for which resource files (or dialog templates) are generated are dialog based. They do not have a main Frame window. This gives you a much closer correlation between what you see on Motif and what you see on Microsoft Windows.
The Generate Options dialog contains a toggle labelled "MFC 4 Enhancements". This causes Sun WorkShop Visual to generate code which uses the extended create functions in MFC to give your application the 3D look and feel.The "MFC 4 Enhancements" toggle also tells Sun WorkShop Visual to map bitmaps onto labels and icons onto buttons, giving you 3D buttons and images that do not need to be insensitive buttons.
Images handled in this way are able to find their natural size. This results in an exact representation of your Motif design.
You can have the enhanced MFC code generation with or without the "Generate as Resources" option.
The "MFC 4 Enhancements" toggle is set by default.
Code generated with "MFC 4 Enhancements" also works with MFC 5.
When you generate any type of MFC code for Microsoft Windows, project files for use in Microsoft Visual C++ are also generated using the base name specified in the Generate dialog. These files are:
<generate_filename>.dsw - This is the main project file. It uses the information in the following file. |
<generate_filename>.dsp - this contains information about the generated files. |
Open the main project file (with the suffix "dsw") in Microsoft Visual C++. These project files are suitable for Visual C++ version 5 or above.
Sun WorkShop Visual has to store the widget id numbers in the save file for definitions so that code can be correctly generated for instances which indirectly modify the layout of an unnamed component. This can cause a problem if the design is changed in a way which affects the widget ids (such as resetting) before the code is generated. Sun WorkShop Visual will detect such loss of synchronization and will prompt you to save the file.
In order for Sun WorkShop Visual to correctly generate layout information the dialogs need to be realized. Sun WorkShop Visual will automatically show and then hide any unrealized dialogs when Microsoft Windows code is generated. You may see the dialogs appear briefly on the display.
Any Microsoft Foundation Class (MFC) code generated by Sun WorkShop Visual which contains Japanese text needs to be post-processed before it is compiled under Microsoft Windows.A filter utility, xdtosj, is provided as part of the Sun WorkShop Visual release to perform this conversion. xdtosj converts the MFC code from EUC to Shift-JIS encoding and changes the DEFAULT_CHARSET value in the MFC CFont creation method to SHIFTJIS_CHARSET.
xdtosj is used in the following way:
xdtosj [-xf*] [file]The arguments are:-x Displays a brief explanation of the utility
-f filter The shift-jis filter to use (default jconv)
-* Any other `-' flags are passed to the filter
[file] An optional file. If no file is specified, stdin is used
There are a number of application resources which apply to Sun WorkShop Visual in Microsoft Windows mode. One of these is the windows flag, indicating that Sun WorkShop Visual should start up in Microsoft Windows mode. This is described in "Starting in Microsoft Windows Mode" on page 364.
By default, Sun WorkShop Visual generates code for Microsoft Windows which adds Ctrl-M as the carriage return before the linefeed character. This character is expected by MS-DOS and may, therefore, be expected by your file transfer program. If, however, you do not wish to have these characters at the end of each line, make the following change to the Sun WorkShop Visual resource file:visu.mfcCarriageReturn: false
By default, Sun WorkShop Visual indicates that a field in a resource panel, or a button or any other text field, is not applicable to Microsoft Windows by coloring it pink. This color can be changed by altering the following line in the Sun WorkShop Visual application resource file:visu.mfcTextWarningBackground: #ecc9c9eacddaThe example above shows the default file entry - i.e. the color pink. You can change this large number to a more readable color name.
In the Generate dialog, Sun WorkShop Visual provides a default filename filter in the Filter text field. You can change this in the application resource file. Search for the following:visu.c++Filter: *.cvisu.c++StubsFilter: *.cThese are the default entries for Motif code generation - both vanilla Motif and Motif XP. For Microsoft Windows code generation there are two extra filename filters:visu.visualC++Filter: *.cppvisu.visualC++StubsFilter: *.cppIf you wish to share code between the two platforms, you might consider changing the filename filters for the two different flavors so that they are the same. See the following section on file names for more details about points to bear in mind when naming files intended for both platforms.