Previous Next Contents Generated Index Doc Set Home


CHAPTER 11

Designing for Microsoft Windows





Introduction

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 365.
  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 366.
  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 367.
  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 369.
  5. Compliance Failure - what happens, and what to do, when an imported design fails the Windows compliance check. See page 375.
  6. Using Links - how to use Links in designs for Microsoft Windows. See page 378.
  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 365.
  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 365.
  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 365.
  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 365.
  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 365.
  8. Using Third Party Widgets - how to use third party widgets (or user widgets) in your Microsoft Windows design. See page 383.
  9. Method Declarations - how to control where methods are declared in the generated MFC code. See page 386.
  10. Application Class - how to change the generation of CWinApp in the MFC code. See page 389.
  11. File names - a note on some points you should bear in mind when naming files to be ported to Microsoft Windows. See page 390.
  12. Code Generation - a description of the code generated for Microsoft Windows, starting on page 391.
  13. Configuring Sun WorkShop Visual - a description of the resources relevant to creating designs for Microsoft Windows. See page 394.
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.


Prerequisites

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 and that you are comfortable with the idea of generating C++ code. C++ Classes 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.


Generating the Application

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.

Using Dialog Templates

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.

   To generate dialogs as resource files, set the "Generate as Resources" toggle in the Code Options dialog.
If the "Generate as Resources" toggle is not set, plain MFC is generated for your design. By default, the toggle is set.

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.


Starting in Microsoft Windows Mode

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.


The Resource File

Microsoft Windows mode can be specified by a resource in the file containing your Sun WorkShop Visual application resources:

	visu.windows:	true

The Command Line Switch

Microsoft Windows mode can also be specified by a command line switch when invoking Sun WorkShop Visual:

	visu -windows

Separate Version of Sun WorkShop Visual

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 type

	visuwin
This 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

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. The first set of differences is described here.


Microsoft Windows Compliant Toggles

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

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.

FIGURE  11-2 The Flavor Menu in the Toolbar


Visual Compliance Indicators

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.


Microsoft Windows Compliance

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.


Structure 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 for more details.


C Structures

Sun WorkShop Visual does not support the Function or Data Structure options in a compliant design.


Classes and Callbacks

Structural errors can be considerably more complicated if you have a design which is well-structured, making good use of C++ classes and with callback methods scattered among the child widgets. The following example demonstrates how this problem may occur and how to overcome it.


Example

When a widget is given a callback method, the method is declared in the enclosing class. In the following example, while using a version of Sun WorkShop Visual which was not in Microsoft Windows mode, the MenuBar, MBar_class, was declared a class and the button given a callback method:

FIGURE  11-3 Non-Compliant Hierarchy

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:

FIGURE  11-4 Error Message Showing Non-Compliance

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 by either pressing the "Declare all" button or selecting "active_button" in the list and pressing "Declare". 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.


Menubar restrictions

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

FileSelectionBox

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


Unsupported widgets

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.


Scale

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.


Frame and RadioBox

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.


MainWindow and ScrolledWindow

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.


Paned Windows

A compliant design cannot contain a Paned Window which has Separator, MainWindow, OptionMenu, or MenuBar children. Neither may the children be definitions or instances.


Definitions

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.

You cannot make the child of a shell widget the root of a definition because you cannot make the child of a shell a C++ class, as explained in Structure restrictions. To overcome this restriction, simply add a "dummy" container between the shell and the widget you wish to use as the root of your definition.

Slightly more subtly, it is not possible to have a widget with methods added to an instance which is not being sub-classed. For example, if you have an instance of a 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.


Compliance Failure

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.

.

FIGURE  11-6 The Compliance Failure Dialog

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 for a list of the possible compliance errors.

Example

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:

FIGURE  11-7 RowColumn Defined as 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:

FIGURE  11-8 Error When Pasting a Class as Child of Shell

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.


Using Links

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.


Destination Widget Not an Object on Microsoft Windows

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 for more information on which widgets are mapped to Microsoft Windows objects.


Buttons in Menus as Link Destinations

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.


File Selection Dialog as Link Destination

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.


Manager Widgets and Layout

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.

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.


Fonts and Appearance

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-1
visu*dialog.buttonFontList:\
-adobe-helvetica-medium-r-normal-*-14-*-*-*-*-77-iso8859-1
visu*dialog.textFontList:\
-adobe-helvetica-medium-r-normal-*-14-*-*-*-*-77-iso8859-1
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.


Resize Behavior

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


Fonts

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.


Fontlists and Compound Strings

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.


Font Naming

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.


Pixmaps, Bitmaps and Icons

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.


Buttons with Pixmaps

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.


Colors

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.


Color Objects

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.


Using Third Party Widgets

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's Automatic Behavior

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.


Configuring Sun WorkShop Visual for Third Party Widgets

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 
Visual 
								Widget 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" Control 
						Class */
#endif /* XD_MOTIF_MFC */




/* Windows C++ Code (Real MFC) */
#ifdef    XD_WINDOWS_MFC
#define MY_BASE_CLASS   CComboBox /* Use the Real Mapping MFC 
							Control 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 for details on how to do this


Third Party Widget Resources

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 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 */


Method Declarations

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.


DrawingAreas

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 for more information.


Adding Drawing Callbacks for Microsoft Windows

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.

FIGURE  11-11 The DrawingArea Resource Panel


The Microsoft Windows Message Handler for DrawingArea

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_MSG
DECLARE_MESSAGE_MAP ()
This registers the message handler with Microsoft Windows.


Application Class

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.

FIGURE  11-12 The Application Class 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.


Event Handlers

Event Handlers explains how Sun WorkShop Visual allows you to add event handlers to widgets in your design. Most of the event masks available for Motif widgets can be mapped to Windows code. The following table shows this mapping.

TABLE  11-1   How Event Masks are Generated into Windows Code
Motif Event Mask
Windows Code

MouseMotion

Generates a generic handler for any mouse movement with or without a button press.

ButtonPress

Generate all three handlers - Left, Center and Right pressed handlers.

ButtonRelease

Generates all three handlers - Left, Center and Right release handlers.

EnterWindow

OnMouseActivate

ExposureMask

OnEraseBkgnd

KeyPressMask

WM_KEYDOWN

KeyRelease

WM_KEYUP

KeymapstateMask

WM_SYSKEYUP / WM_SYSKEYDOWN

LeaveWindowMask

WM_KILL_FOCUS

ResizeRedirect

WM_SIZE

PropertyChangeMask

ON_WM_PAINT

VisibilityChangeMask

WM_SHOWWINDOW


File names

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.


Pixmaps

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.


C++ Code

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 for details of how to change the default filters in the Generate dialog.


Makefile

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.


Code Generation

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. Project Files. The Visual C++ project files that Sun WorkShop Visual generates for you.
  3. Synchronizing Save and Code Files. How to make sure that your save file and generated code file remain in synch.
  4. Dialog Flashing. A warning that dialogs are realized (and therefore displayed) when MFC code is generated.
  5. Use of Japanese Font. What to do when generating MFC code containing Japanese text.

Generating Dialog Templates

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.

FIGURE  11-13 Generate Options Dialog

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 Application Shell

In the generated code, an Application Shell inherits from a CDialog. This means that pressing <Enter> when the dialog itself is selected closes the application. As this is the case two of the dialog's methods are generated to the stubs file to be overridden if this behavior is not desired. The methods are OnOK and OnCancel. As with all methods in the stubs file, anything added to them is retained when code is regenerated.


Project Files

When you generate any type of MFC code for Microsoft Windows, you can also generate project files for use in Microsoft Visual C++ using the base name specified in the Generate dialog. To make Sun WorkShop Visual generate project files, check that the "Generate Project Files" toggle is set in the Code Options dialog.

The files generated 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.
To use these, open the main project file (with the suffix "dsw") in Microsoft Visual C++. These project files are suitable for Visual C++ version 5 and version 6.


Synchronizing Save and Code Files

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.


Dialog Flashing

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.


Use of Japanese Font

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


Configuring Sun WorkShop Visual

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.


Adding Ctrl-M to Generated Lines

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

Setting the Color of non Microsoft Windows Resource Fields

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:	#ecc9c9eacdda
The example above shows the default file entry - i.e. the color pink. You can change this large number to a more readable color name.


Setting the Filename Filter

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:	*.c
visu.c++StubsFilter:	*.c
These 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:	*.cpp
visu.visualC++StubsFilter:	*.cpp
If 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 File names for more details about points to bear in mind when naming files intended for both platforms.



1 Pinking is only discernible on a color display.


Previous Next Contents Generated Index Doc Set Home

Copyright © 2000 Sun Microsystems, Inc. & Imperial Software Technology Ltd. All Rights Reserved.