Introduction

This chapter shows you how to produce the simple application shown in Figure 12-1 on both Motif and Microsoft Windows. In addition, "Single Sourcing" on page 415 at the end of this chapter looks at the how you might share callback files between UNIX and Microsoft Windows.

FIGURE  12-1 Final Application

Starting Your Design

This tutorial shows you how to put together a main application window and a sub-dialog. As well as building the user interface, it uses links, callbacks and sets resources, including pixmaps. It even shows you how to pop up a menu in a drawing area. All of this will be ported to Microsoft Windows.

It is assumed that you are familiar with the basic use of Sun WorkShop Visual. For this reason, a design file containing the completed hierarchies for this tutorial is included with Sun WorkShop Visual. You can either open this file, as explained in Step 2, or follow the instructions to build the hierarchy yourself.

---

Note - You only need to do Step 3 through to Step 17 if you wish to build the hierarchy yourself.

---

FIGURE  12-2 The Initial Hierarchy

FIGURE  12-3 The Hierarchy Under the MenuBar

FIGURE  12-4 The Hierarchy Under the ScrolledWindow

Although the Form widget will not be generated into the Microsoft Windows code (we have not made it a C++ class), attachments and positions are calculated and handled by Sun WorkShop Visual in the generated code. In this way the resize behavior will be preserved. See "Manager Widgets and Layout" on page 376 for more details.

FIGURE  12-5 The Main Window Dynamic Display

FIGURE  12-6 The Sub-Dialog Hierarchy

FIGURE  12-7 The Sub-Dialog

Adding Callbacks

Here we shall add a callback method for the close button which will close the sub-dialog, and a callback method on exit_b in the file menu of the main application shell.

---

Note - For a Motif-only application you would not need to add a callback to close the application from a button - instead you could set the AutoUnmanage resource in the about_form resources to "Yes". For Microsoft Windows, however, you need to add a callback.

---

Adding a Link

You are going to add a link to display the sub-dialog from the main window. Sun WorkShop Visual is able to generate code to implement links on both Motif and Microsoft Windows. See "Using Links" on page 375 for restrictions on Microsoft Windows which should be taken into account when creating links. Read "Links" on page 189 if you are not sure how to set up links in a dialog.

Note that the Add button is pink when a menu button is selected as the destination widget. Show, Hide, Manage and Unmanage links are only effective for menu buttons on Motif; Enable and Disable links are effective on menu buttons in both Motif and Microsoft Windows. However, the menu button currently selected is not the destination widget for this exercise.

You are now going to add the same link from "subd_pixmap" in the main application shell.

Popup Menu

Adding a popup menu to a DrawingArea widget is useful whichever language you intend to generate. The next stage of the tutorial shows you how to do this. You will have to write a small amount of extra code as Sun WorkShop Visual does not automatically generate code to popup menus. Motif and Microsoft Windows have different ways of popping up a menu so your code will have to be different for each platform. The code is added much later in the tutorial, first you need to set up the callback.

The Motif XP library does not attempt to emulate the Microsoft Windows drawing or input model, hence the list of Microsoft Windows target message handlers.

FIGURE  12-8 DrawingArea Resource Panel

This will generate an appropriate Microsoft Windows message handler, which will be called in response to the corresponding Microsoft Windows message, and a matching callback stub.

"Filling in the Stubs" on page 408 of this chapter explains how to fill in the stubs to popup the menu.

Setting Resources

Sun WorkShop Visual generates resource files for Motif and Microsoft Windows. Motif, however, allows a far greater range of control over its widgets. Although there are resources in Microsoft Windows, they are limited in comparison with Motif/X resources. Microsoft Windows resources are compiled into the executable file so, unlike Motif, changing a resource on Microsoft Windows means re-compiling the application.

Setting Label Resources

In this example application, we have string, pixmap and keyboard resources. First of all, we shall set the strings of the labels, buttons and shells.

FIGURE  12-9 MenuBar Labels and Shell Title

FIGURE  12-10 Menu Item Labels

The quick brown fox

jumped over

the lazy dog

FIGURE  12-11 Completed Sub-Dialog

Generating String Resources

All of these labels are string resources. When you generate the code for the Motif version of your design you can decide whether the resources should go into the code or into the resource file. For the Microsoft Windows version all string resources are automatically generated into the source code.

Using Pixmaps

If you are using pixmaps in your design, Sun WorkShop Visual automatically converts them to Windows bitmaps when you generate code. To illustrate this, you are going to give one of the buttons a pixmap label.

Naming the Pixmap

Remember that filenames on MS-DOS (and Microsoft Windows) must be no longer than eight characters before the extension. Sun WorkShop Visual uses the name to which you bind the pixmap in the basename of the file in Microsoft Windows mode, so make sure that you have not specified a name longer than eight characters.

You have now finished the design of your application. The rest of this tutorial shows you how to generate code for the UNIX and for Microsoft Windows and how to build the application on each platform.

Building the Application

Now that you have designed the application user interface in Sun WorkShop Visual, you can generate the Motif and Microsoft Windows code. Having generated the code, you are then ready to build the two applications. Full instructions are provided in this section, including how to fill in the callback stubs.

Controlling the Sources

For this tutorial, you need to generate two separate applications - one for Motif and one for Microsoft Windows. You should generate them into two separate directories to avoid such problems as overwriting and including the wrong header file. This tutorial does not exploit the possibilities of single sourcing, which are discussed in "Single Sourcing" on page 415.

Code Generation for Motif

The Makefile

You may have to edit the Makefile in order to access the Motif XP code, depending on how Sun WorkShop Visual has been installed and configured. Check that the XPCLASSLIBS and CCFLAGS definitions access the Motif XP library and include files. VISUROOT is the path to the root of the Sun WorkShop Visual installation directory:

XPCLASS = $(VISUROOT)/src/motifxp

XPCLASSLIBS = $(XPCLASS)/lib${ABIDIR}/libmotifxp.a

GEN_CFLAGS=-I. ${XINCLUDES} -I${XPMDIR} ${GROUP_COMPILEFLAGS}

CCFLAGS=${CFLAGS} ${ABICCFLAGS} -I${XPCLASS}/h ${GROUP_COMPILEFLAGS}

Code Generation for Microsoft Windows

The steps to generate the code for Microsoft Windows are almost the same as for Motif. Sun WorkShop Visual remembers a different set of files for each flavor so you can use the toolbar flavor menus and code generation buttons once you have specified the name of the files for the different flavors.

Remember that, on the PC, a filename must be eight characters or less before the extension. Some IDEs, including Visual C++, complain if they encounter a source file containing C++ code which has been given only a `.c' extension. You can specify ".cpp" or ".cxx".

---

Note - You do not need to generate a makefile for the Microsoft Windows code because the files will be built in a different way. This is described in "Compiling the Microsoft Windows Version" on page 411.

---

The Generated Files

When you generate MFC, you will find that extra files in addition to the code, stubs and header files are generated. These are:

Japanese Text

If the generated code contains Japanese text, you need to post-process the code with a filter utility, xdtosj, which is provided as part of the Sun WorkShop Visual release, before transferring it to a PC. See "Use of Japanese Font" on page 391 for more information.

Filling in the Stubs

You have two stubs files - one for MFC and one for Motif. Because you generated Motif XP code for your Motif application you could share some of the code. This is because Sun WorkShop Visual's XP library emulates some of the MFC for Motif. For simplicity and speed, however, this tutorial keeps the two separate. For more information on sharing the sources, see "Single Sourcing" on page 415.

The MFC Stubs

There are two callbacks - one to exit the application and one to popup the menu from the drawing area. You should fill in the stubs as shown below:

void 

shell_c::DoExit ( )

{

	
 
exit(0);

}

void 

sub_shell_c::DoClose ( )

{

	
 
this->ShowWindow(SW_HIDE);

}

afx_msg void popup_window_c::OnRButtonDown( UINT nFlags, CPoint point 
)

{

	
 
ClientToScreen(&point);

	popup->TrackPopupMenu( TPM_LEFTALIGN|TPM_RIGHTBUTTON, 

							point.x, point.y, this, NULL);

}

The Motif Stubs

There are two callbacks in the Motif stubs file to match the two in the MFC stubs file. Although the signature of the exit callback is the same for both platforms, the contents are different.

void 

shell_c::DoExit ( )

{

	
 
exit (0);

}

void 

sub_shell_c::DoClose ( )

{

	
 
this->ShowWindow(SW_HIDE);

}

void 

popup_window_c::DoInput ( )

{

	
 
popup->TrackPopupMenu(0, 0, 0, this, NULL);

}

Compiling the Application

Having created the design, generated code and filled in the callback stubs, you are now ready to compile the application on both Motif and Microsoft Windows. After the brief section on building your application on Motif, there is a description of the steps you will need to take to build your application on Microsoft Windows.

Step-by-step instructions for building the application using Visual C++ versions 4.0 and 5 on Microsoft Windows are given in "Compiling the Microsoft Windows Version" on page 411. However, you can build the generated code using any C++ development environment capable of integrating the Microsoft Foundation Classes, for example Symantec C++. Refer to "Using Other Applications" on page 414 for general information about configuring Microsoft Windows-based C++ compilers to build the application.

Compiling the Motif Version

All you need to do now is make the application by typing

make

at the command prompt in the directory where you generated the Motif code. Since you generated a Makefile, all the files in your application are automatically built.

Before running the application, be sure to arrange for the resource file to be read, as explained in "Setting up the X Resource File" on page 221.

Compiling the Microsoft Windows Version

If you are using Visual C++ Version 5, compiling your application on your PC is very simple because Sun WorkShop Visual generates full Visual C++ project files for you. If you are using earlier versions of Visual C+ you will need to create the project. Although this is not so convenient, it does not take long and only needs to be done once. Full instructions are given below for using Visual C++ Version 5 and Visual C++ Version 4.0. If you are using a version of Visual C++ earlier than 4.0 and you need help on creating a project, contact Sun WorkShop Visual support. "Using Other Applications" on page 414 gives you some tips on compiling your application if you are not using Visual C++.

Brief Notes on Visual C++

Visual C++ is an IDE (Integrated Development Environment) to help you develop applications to run on Microsoft Windows. It comprises a number of tools, including a compiler, debugger and various editors. It is a useful tool for building, debugging and controlling the sources of an application. Note, however, that any changes you make to your code in Visual C++ cannot be taken back into Sun WorkShop Visual. Visual C++ uses the concept of a project to keep track of the files in your application. You always need a project when you use Visual C++. For Version 5, Sun WorkShop Visual generates the project files for you.

---

Note - PC-NFS, available from SunSoft, is a tool designed to make sharing files between your PC and your Solaris system easy.

---

Visual C++ Version 5

Sun WorkShop Visual generates fully configured project files for Visual C++ version 5 and above. These are the files ending with a suffix of ".dsw" and ".dsp". Take both of these files to your PC along with all the MFC source files (this includes the code files, resource file, any bitmap files and header files).

Visual C++ Version 4.0

If you are using Visual C++ Version 4, you cannot use the project files generated by Sun WorkShop Visual. The following takes you through the steps required to create the project.

FIGURE  12-12 New items list

FIGURE  12-13 New Project Workspace dialog

FIGURE  12-14 Insert Files dialog

FIGURE  12-15 Project settings dialog

Using Other Applications

The code generated by Sun WorkShop Visual is MFC code. It has not been generated for any specific Microsoft Windows application. The following lists the important points to bear in mind when building your user interface on Microsoft Windows if you are not using Visual C++. This section applies to all compilers.

Make sure the linker links in the MFC libraries or DLLs.

Single Sourcing

Using Sun WorkShop Visual's Motif XP library gives you the potential to share some of your callback code between Motif and MFC. Appendix  B, "Motif XP Reference", starting on page 839 lists the classes which have been emulated for Motif. Use this appendix to find out which calls to the MFC toolkit you can use for both platforms.

To use the XP library, you should choose "Motif XP" as the language to generate for your Motif application in the Generate dialog. When generating code, you should remember that only a suffix of ".cxx" or ".cpp" is acceptable to both UNIX and Windows platforms. The following list of steps uses pre-built designs and a stubs file which has already been filled in to illustrate how you can use the Motif XP to write a callbacks file which can be used on both Motif and Windows. The files required for this are found in $VISUROOT/src/examples/tutorial where VISUROOT is the install directory of your Sun WorkShop Visual.

FIGURE  12-16 Design Hierarchy and Dynamic Display

You can look at the Stubs file in a text editor. There are three callbacks:

All of this code can be shared by the Motif XP application and the MFC application.

Other Ways to Share Source Between Platforms

There are two other options you could consider for single sourcing of callback files:

The Java programming language gives you platform independence. Sun WorkShop Visual can generate your design in Java code. In addition, you can save your design in a format ready for importing into Visaj, the Java application builder. Chapter 10, "Designing For Java", starting on page 319 explains all about creating Java applications from your design.

Get/Set Smart Code gives you a toolkit-independent "wrapper" around widgets that you are interested in. Full details, including a short tutorial, are given in Chapter 16, "Get/Set Smart Code", starting on page 487.