11.1 Introduction
This chapter shows you how to produce the following application which you will also build on Microsoft Windows.
Figure 11-1 Final Application (Motif Version)
Figure 11-2 Final Application (Microsoft Windows Version)
There is also a File Selection Dialog which is part of the application.
11.2 Starting Your Design
Make sure that you are running WorkShop Visual in Microsoft Windows mode. See the Starting in Microsoft Windows Mode section on page 334.
- 1. Create the hierarchy shown in Figures 11-3 to 11-5, naming the widgets as shown.
- Names of the type [widget-class][number] (e.g. "button1") are the default names assigned by WorkShop Visual. You do not need to name those widgets explicitly.
- 2. Set the Shell to Application shell.
- This is a toggle at the top of the Shell resource panel.
Figure 11-3 The Top Level Hierarchy - Menubar and Scrolled Window Folded
Figure 11-4 The Hierarchy Under the MenuBar
Figure 11-5 The Hierarchy Under the ScrolledWindow
- 3. Specify the variable names as shown.
- 4. Use the Form layout editor to adjust your dynamic display to that shown in Figure 11-6.
- You will need to move the widgets to the right place and specify attachments. If you are not sure how to do this, read Chapter 4, "The Layout Editor", starting on page 103, first.
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 WorkShop Visual in the generated code. In this way the resize behavior will be preserved. See the Manager Widgets and Layout section on page 347 for more details.
Figure 11-6 The Dynamic Display
- 5. Save your design into a file named main.xd.
11.3 Creating a Definition
For this example, you are going to create a widget definition in a separate design and add an instance of it in the main design. You will then create a subclass by adding widgets to the instance of the definition. The definition shows the use of inherited functionality and the control of multiple source files on Microsoft Windows.
11.3.1 The Definition Design
- 1. Select New from the File menu.
- 2. Create the hierarchy shown in Figure 11-7.
Figure 11-7 The About Dialog Hierarchy
- 3. Assign widget variable names as shown above.
Note - It is important to give widgets variable names when you are going to create a C++ class definition, otherwise the definition will not contain the correct widgets.
- 4. Use the Form Layout Editor to create a layout as shown in Figure 11-8.
- You will need to move the widgets to the right place and specify attachments. If you are not sure how to do this, read Chapter 4, "The Layout Editor", starting on page 103, first.
Figure 11-8 The About Dialog
In the dialog shown in Figure 11-8, the label string resources have been set - buttons, labels etc. have been given meaningful labels. Also the text has been centered. You should wait until the Setting Label Resources section on page 373 before setting these resources.
- 5. Save your design into a file named about.xd.
11.3.2 Adding a Callback
Here we shall add a callback method for the close button which will close the about dialog.
- 1. Select the close button, close_b.
- 2. Invoke the Callbacks dialog and select the Activate callback from the list of callback types.
- 3. Check that the option menu underneath the list of defined callbacks says "Method name".
- 4. Type DoClose into the text box and press the "Add" button.
- 5. Close the Callbacks dialog.
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. This callback can be shared by the two platforms.
11.3.3 Setting Fonts
In order to make this design look the same on Microsoft Windows as it does on Motif, we shall set the label, button and text fonts to a font similar to the Microsoft Windows default font. Whether or not the font given here is suitable will depend on the configuration of Microsoft Windows you are using. You may wish to try other fonts if this one does not look good. For Microsoft Windows, font objects must be used. If you are unsure about using font objects, see the Simple Font Objects section on page 155. See the Fonts section on page 348 for more details about fonts on Microsoft Windows.
- 1. Select the Shell widget, about_shell, and display the shell resource panel.
- 2. Press the Label Font button and make a font object using the font:
-adobe-helvetica-medium-r-normal-*-14-*-*-*-*-77-iso8859-1
If this font is not available on your machine, use a similar size font.
- 3. Apply this font object to the Label font, Button font, and Text font.
You are strongly recommended to read the Fonts section on page 348 for a better understanding of the use of fonts in Microsoft Windows designs.
11.3.4 Making the Design a Definition
Create a widget definition by following these steps:
- 1. Select the Shell widget.
- 2. Select Define from the Palette menu. The hierarchy is shown within a colored box to indicate that it forms a definition.
- Notice that there is an extra widget at the bottom of your widget palette representing the about dialog definition.
- 3. Select Edit definitions from the Palette menu.
- 4. Select about_shell from the list of Definitions.
- If you do not have any other definitions, about_shell will be the only item in the list. You must still select it.
- 5. Type: about.h in the "Include file" field.
- 6. Press Update and then cancel the Edit Definitions dialog.
- 7. Save about.xd.
11.4 Creating an Instance
You can now add an instance of the definition to your main design. By adding other widgets to it, thereby creating a subclass, you have the appearance and behavior of the original definition as well as the extra features of the additional elements you are going to add. You will then add links and callbacks to complete the design.
11.4.1 Subclassing the Definition
- 1. Open the saved file main.xd.
- 2. Click on the button labelled "about_shell" at the bottom of the widget palette.
- This gives you a new dialog.
- 3. Set the variable name for the dialog shell to "about_sh".
- 4. Select the Form widget, about_form, and add a RadioBox containing two ToggleButtons.
- 5. Select about_form again and add two OptionMenus, each containing a Menu and three PushButtons.
- 6. Set the variable names of the newly added widgets as shown in Figure 11-9.
- Check that your hierarchy looks like the one shown in Figure 11-9.
- 7. Change the C++ Access to Public for the two OptionMenus, the ToggleButtons and the two Labels.
We are changing the C++ access so that we can access all of these widgets in the callbacks we'll be writing later. C++ access is changed from the Code generation page of the Core resources panel.
Figure 11-9 Hierarchy Showing New Widgets in Definition Subclass
To specify which option is shown first in the OptionMenus when the dialog is displayed, do the following:
- 8. Display the widget resources for the OptionMenu classical_c.
- 9. Select the "Display" page.
- 10. In the field labelled "Last selected" type the widget name (which, in this example, is the same as the variable name) of the widget labelled with the option you wish to be shown first.
- Our example shows the button bach_b.
- 11. Do the same for the OptionMenu jazz_c - choose any button to be shown first.
- 12. Save your design.
11.4.2 Links for the About Dialog
You are going to add a link to display the About dialog from the main window. WorkShop Visual is able to generate code to implement links on both Motif and Microsoft Windows. See the Using Links section on page 346 for restrictions on Microsoft Windows which should be taken into account when creating links. Read the Links section on page 199 if you are not sure how to set up links in a dialog.
- 1. Select about_b in the menu called help_menu of the main dialog and invoke the Edit Links dialog from the Widget menu.
- The main dialog is called "shell".
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.
- 2. Select about_sh in the window holding area.
- The text box labelled "Widget" in the Links dialog now contains the name of the about dialog shell, about_sh.
- 3. Select the "Show" link in the Links dialog and press the "Add" button to add the Show link to about_sh.
We shall now add the same link from about2_b in the RowColumn of the main shell dialog:
- 4. Go back to the main dialog.
- Select the shell from the window holding area.
- 5. Select about2_b (from the RowColumn) and select "Edit Links" from the Widget menu.
- You need to select this menu item again even though the Links dialog is still displayed on the screen - selecting the menu item makes the selected widget the "source" widget. Otherwise, it is a "destination" widget.
- 6. Select about_sh again.
- Select the shell from the window holding area.
- 7. Select the "Show" link in the Links dialog and press the "Add" button to add the Show link to about_sh.
- 8. Close the Links dialog and save the design.
11.4.3 Adding Callbacks
You have already added a callback to the about dialog (about_sh) which closes the dialog. Now add callbacks for the two ToggleButtons, classical_t and jazz_t, for all the buttons in the two OptionMenus, classical_c and jazz_c and for the exit button in the file menu.
- 1. Add a "Value changed" callback method called ClassicalChanged to the ToggleButton, classical_t, in the dialog about_sh.
- See the Callback Methods section on page 300 if you are not sure how to do this.
- 2. Add a "Value changed" callback method called JazzChanged to the ToggleButton jazz_t.
- 3. Add an "Activate" callback method called DoSetText to all of the Buttons in the two OptionMenus.
- These buttons are all going to call the same callback routine.
- 4. Change to the main shell dialog.
- 5. Select exit_b in the file_menu. Add an "Activate" callback method entitled DoExit.
- 6. Save the design - main.xd.
The Code Generation for Microsoft Windows section on page 382 of this chapter shows you how to generate the stubs for these callback methods and how to fill them in. We are going to add some more to the design before generating code.
11.5 File Selection Dialog
To complete the design, we shall add a file selection dialog. On Microsoft Windows the file selection operation is supported by a modal dialog box CFileDialog. WorkShop Visual, therefore, only allows a file selection dialog as the child of a Shell. To popup the file selection dialog, we shall use links.
- 1. Create another Shell and give it the variable name file_dialog.
- 2. Add a FileSelectionBox widget. Give the FileSelectionBox widget (the child of the Shell) the name file_select.
- 3. Add a Frame as the child of the FileSelectionBox widget and put a RadioBox with two ToggleButtons inside the Frame.
- This is just to demonstrate the sort of widgets that can be added to a FileSelectionBox. We are not going to use these widgets so we do not need to name them or set any other resources for them.
- 4. Select the Frame again and add a Label.
11.5.1 Links for the File Selection Dialog
The file selection dialog is opened by pressing one of the open buttons. We shall add a link from each of them to file_dialog.
- 1. Select the button open_b in the menu file_menu of the main shell dialog.
- 2. Select "Edit links" from the "Widget" menu.
- 3. Add a "Show" link to the file dialog shell, file_dialog.
- 4. Add the same link from open2_b in the RowColumn of the main shell dialog.
- Remember that you need to select the button open2_b and then select "Edit links" from the "Widget" menu again in order to make the button the "source" of the link.
- 5. Save the main.xd design.
11.6 Popup Menu
Another extra feature we shall add is the ability to popup a menu from the DrawingArea. WorkShop Visual cannot automatically generate code to popup menus. You will have to write a brief callback to do this. Motif and Microsoft Windows have different ways of popping up a menu and so the callback will have to be different for each platform. In this example we shall popup a menu from the DrawingArea. You have already added the menu to the design, now you need to make it work.
- 1. Select draw_area from inside the ScrolledWindow, popup_window, in the main shell dialog.
- 2. Press the callback button on the toolbar or select "Callbacks" from the "Widget" menu.
- 3. Select "Input" from the list of callback types and add a callback method called DoInput.
- The Input callback type is marked with an asterisk (*), indicating that this callback will have no effect on Microsoft Windows.
- 4. Close the Callbacks dialog.
- 5. Display the DrawingArea resource panel, shown in Figure 11-10.
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 11-10 DrawingArea Resource Panel
- 6. Set the OnRButtonDown toggle, press "Apply" and close the 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.
The Filling in the MFC Stubs section on page 385 of this chapter explains how to fill in the stubs to popup the menu.
- 7. Save the design.
11.7 Setting Resources
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.
11.7.1 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.
- 1. Go to the main shell dialog.
- 2. Display the resource panel for the Form which is the child of the Shell.
- 3. Set the dialog title to "Tutorial" by typing into the text field labelled "Title".
- You can do this by typing into the text field labelled "Title" on the "Display" page of the Shell widget resource panel.
- 4. Set the label strings of the MenuBar buttons in the main shell dialog as shown in Figure 11-11.
Figure 11-11 MenuBar Labels and Shell Title
- 5. Set the label strings of the menu item buttons as shown in Figure 11-12.
Figure 11-12 Menu Item Labels
- 6. Give the popup menu items of the popup menu in the DrawingArea the labels "Cut", "Copy" and "Paste".
- 7. Change to the sub-classed about dialog shell, about_sh.
- 8. Set the string of the label widget, label, as shown in Figure 11-16.
- The label string is also centered - to do this go to the "Settings" page of the Label resource panel and change the "Alignment" resource.
- 9. Set the OptionMenu labels as shown in Figure 11-13.
Figure 11-13 OptionMenu Labels
- 10. Set the OptionMenu item buttons as shown in Figure 11-14.
Figure 11-14 OptionMenu Items
- 11. Set the ToggleButton labels as shown in Figure 11-15.
Figure 11-15 ToggleButtons Labels.
- 12. Set the dialog title of the about dialog to "About"
- Do this by typing into the text box labelled "Title" in the resource panel of the Form which is the child of the shell.
- 13. Change to the FileSelection dialog, file_dialog.
- 14. Give the ToggleButtons in the RadioBox the labels "New" and "Append".
- 15. Use the Form layout editor to adjust your dynamic display to that shown in Figure 11-16.
- You will need to move the widgets to the right place and specify attachments. If you are not sure how to do this, read Chapter 4, "The Layout Editor", starting on page 103, first.
Note - The two OptionMenus are directly on top of one another, each attached to the Form or widgets on all sides. Later you will write a callback which will show and hide the two OptionMenus.
Figure 11-16 The Subclassed Definition
- 16. Save the design - main.xd.
11.7.2 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 where to generate these resources: into the code or into the resource file. For the Microsoft Windows version all string resources are automatically generated into the source code. We shall do this in the Code Generation for Microsoft Windows section on page 382.
11.7.3 Creating Pixmaps
We shall use pixmaps for the buttons open2_b and about2_b of the shell dialog.
- 1. Set the Type Resource of these buttons to Pixmap.
- Do this on the "Settings" page of the button resource panel.
- 2. For each button, go to the "Display" page of the button resource panel and press the button labelled "Pixmap".
- This displays the Pixmap Selector dialog.
- 3. Create a pixmap object for each button, select the pixmap object and press "Apply" so that the object name appears in the text field next to the button labelled "Pixmap" in the resource panel.
- If you are not sure about creating and using pixmap objects, see the Selecting a Pixmap section on page 160.
- 4. When you press "Apply" in the resource panel, the pixmap you have specified will be shown on the button.
- 5. Save your design.
11.7.4 Naming the Pixmap
Remember that filenames on MS-DOS (and Microsoft Windows) must be no longer than eight characters before the extension. 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.
11.7.5 Setting Fonts
For the same reasons as discussed in the Setting Fonts section on page 365 of this chapter, we must set the fonts so that they will appear the same on Microsoft Windows as on Motif.
- 1. Select the main Shell widget, shell, and display the shell resource panel.
- 2. Press the Label Font button and make a font object using the font:
-adobe-helvetica-medium-r-normal-*-14-*-*-*-*-77-iso8859-1
Again, if this font is unavailable on your machine, use a similar size font.
- 3. Apply this font object to the Label font, Button font, and Text font.
11.8 Building the Application
Now that you have designed the application user interface in WorkShop Visual, you can generate the Motif and Microsoft Windows code. You will need to generate C++ (for the main program and the callback stubs), header files and resource files. As well as code generation, this chapter also covers how to link the dialogs together by filling in the callback stubs.
11.8.1 Controlling the Sources
Some of the generated code will be Motif or Microsoft Windows specific. By using the Motif XP, however, some of the code is shared by both platforms. In particular, the callback stubs file can be shared where you are writing code which does not involve the Microsoft Windows message handler and which is not system dependent. Our example includes both types. The callback from the about dialog is an example which shows how code can be shared by both platforms. The callbacks generated for the main design contain a mixture of platform dependent and independent code and will therefore need to be separated out in order to allow single sourcing of the callbacks which can be shared.
You are strongly advised to keep the rest of the code separate - in separate directories. In this way you are less likely to overwrite one version with another and will avoid including the wrong header file - the inclusion of a header file when a definition is used in a design is generated automatically. You do not control the name of that header file so you could pick up the wrong one if all your sources are in the same directory.
11.8.2 Code Generation for Motif
You will need to reopen about.xd and generate code for that file as well as for main.xd. Follow these steps, generating the code from main.xd first. Note that the order in which the files are generated is important when you generate the makefile.
- 1. Display the Generate dialog.
- The filename fields are primed with names based on the ".xd" file name (or "untitled" if you have not saved the design yet). Instructions are given for typing in the filenames even though, if you have saved the designs as main.xd and about.xd, most of the filenames will already be correct.
- 2. Check that "C++ Motif XP" is the selected item from the "Language" option menu.
- At the top of the dialog there is a text area where you can type the name of a base directory. All filenames are then relative to this directory. You can use the "Browse" button to find a directory.
- 3. Set the base directory to the area where you wish to generate your files. Use the directory name "MXP" for these files.
- Remember that you should generate the Motif XP and the Microsoft Windows MFC code into separate directories to avoid confusion. Remember also that only a suffix of `.cxx' or `.cpp' is acceptable to both platforms.
- 4. Type: main.cxx into the text box labelled "Code" and set the "Generate" toggle.
- 5. Open the Code Options dialog.
- Press the button labelled "Options" next to the "Code" text box.
- 6. Set the "Include Header File" toggle and enter the name main.h.
- 7. Make sure that the "Include Motif Header Files" toggle is set.
- 8. Press "Ok".
- This saves your changes and closes the Code Options dialog.
- 9. Type: main.h into the text box labelled "Externs" and set the "Generate" toggle.
- 10. Type: motif_st.cxx into the text box labelled "Stubs" and set the "Generate" toggle.
- 11. Type: main.res into the text box labelled "X resources" and set the "Generate" toggle.
- For this example, you only need to generate resources for the main design as we did not set any resources in the about dialog.
- 12. Make sure that the "Generate" toggle next to the "Main Program" text box is set.
- Make sure that you have entered the filename main.cxx into the "Main program" text box so that the main procedure is generated into that file.
- 13. Open the Generate Options dialog.
- Press the button labelled "Options" at the bottom of the Generate dialog to do this.
- 14. Check that the "Links" option menu is set to "Generated to Code".
- 15. Check that the "Strings" option menu is set to "Resource file" and all other resource options are set to "Code".
- We are going to generate a resource file containing our label strings. Other resource settings will be "hard-coded".
- 16. Press "Ok".
- This saves your changes and closes the Generate Options dialog.
- 17. Type: Makefile into the "Makefile" text box and set the "Generate" toggle.
- 18. Open the Makefile Options dialog and set both the "New Makefile" and "Makefile Template" toggles.
- 19. In the Generate dialog, press "Apply" so that your settings are saved for future reference and then press "Generate".
- 20. Unset the "Generate" toggle for all files except the "Stubs" file and the "Makefile".
- 21. This time, give the stubs file the name: share_st.cxx. Keep the same name for the makefile.
- This is for the callback code which can be shared. For the moment it is identical to the file motif_st.cxx.
- 22. Open the Generate Options dialog.
- 23. Check that the "Links" option menu is set to "None".
- This prevents the links code from being duplicated in the shared file.
- 24. Open the Makefile Options dialog again, this time make sure that the "New Makefile" toggle is off and the "Makefile Template" toggle is on.
- This is to ensure that the second stubs file is included in the makefile.
- 25. Press "Generate" again in the Generate dialog.
- You have now generated the files for the main design. You also need to generate files for the about dialog.
- 26. Save the design.
- This will save the filenames that you have typed into the generate dialog.
- 27. Open the design about.xd and display the Generate dialog.
- 28. Select "C++ Motif XP" from the "Language" menu.
- 29. Set the base directory to the same as the one you used for the main design above.
- 30. Use the following filenames and set the "Generate" toggle next to each one:
- 31. Make sure that the "Generate" toggle next to "Main Program" is not set.
- For the about dialog we do not need a main procedure as this has already been generated into the code file for the main design - main.cxx.
- 32. In the Generate Options dialog, set the "Links" option menu to "None".
- 33. Use the same name as before - Makefile - for the makefile.
- We do not need another makefile - we are going to update the existing one.
- 34. In the Makefile Options dialog check that the "New Makefile" toggle is off and the "Makefile Template" toggle is on.
- This is to make sure that the about dialog sources are added to the existing makefile.
- 35. Press "Generate" to generate the files for the about dialog.
- 36. Save the design.
11.8.3 The Makefile
You may have to edit the Makefile in order to access the Motif XP code, depending on how 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 WorkShop Visual installation directory:
XPCLASS = $(VISUROOT)/src/motifxp
XPCLASSLIBS = $(XPCLASS)/lib/libmotifxp.a
CFLAGS=-I. ${XINCLUDES} -I${XPMDIR}
CCFLAGS=${CFLAGS} -I${XPCLASS}/h
11.8.4 Code Generation for Microsoft Windows
The steps to generate the code for Microsoft Windows are almost (but not quite) identical to those described above for Motif. Start by changing the Flavor menu to Microsoft Windows. WorkShop Visual remembers a different set of files for each flavor so that 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. Visual C++ will complain if it encounters a source file containing C++ code which has been given only a `.c' extension. You can specify `.cpp' or `.cxx'.
Perform the following steps first for the main.xd and repeat for the about.xd design.
- 1. Open the file.
- 2. Display the Generate dialog.
- The filename fields are primed with names based on the ".xd" file name (or "untitled" if you have not saved the design yet). Instructions are given for typing in the filenames even though, if you have saved the designs as main.xd and about.xd, most of the filenames will already be correct.
- 3. Check that "C++ Microsoft Windows MFC" is the selected item from the "Language" option menu.
- At the top of the dialog there is a text area where you can type the name of a base directory. All filenames are then relative to this directory. You can use the "Browse" button to find a directory.
- 4. Set the base directory to the area where you wish to generate your files. Use the directory name "WMFC" for these files.
- Remember that you should generate the Motif XP and the Microsoft Windows MFC code into separate directories to avoid confusion.
- 5. Type the name of the code file - main.cxx or about.cxx - into the text box labelled "Code" and check that the corresponding "Generate" toggle is set.
- 6. Open the Code Options dialog.
- Press the button labelled "Options" next to the "Code" text box.
- 7. Set the "Include Header File" toggle and enter the name of the header file you are about to generate - main.h for the main design and about.h for the about dialog.
- 8. Press "Ok".
- This saves your changes and closes the Code Options dialog.
- 9. Type: main.h for the main design and about.h for the about dialog into the field labelled "Externs" and set the "Generate" toggle.
- Make sure you have used the name you previously specified in the Code Options dialog.
- 10. For the main design only - type: wind_st.cxx into the text box labelled "Stubs" and check that the corresponding "Generate" toggle is set.
- You do not need to generate a stubs file for the about dialog as you can share the file already generated for Motif XP.
- 11. For the main design only - type: main.rc into the text box labelled "Microsoft Windows resources" and check that the corresponding "Generate" toggle is set.
- 12. Make sure that the "Generate" toggle next to the "Main Program" text box is set for the main design and not set for the about dialog.
- For the main design, make sure that you have entered the filename main.cxx into the "Main program" text box so that the main procedure is generated into that file.
- 13. Open the Generate Options dialog.
- Press the button labelled "Options" at the bottom of the Generate dialog.
- 14. Check that the "Links" option menu is set to "Generated to Code" for the main design and set to "None" for the about dialog.
- 15. Press "Ok".
- This saves your changes and closes the Generate Options dialog.
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 the Using Visual C++ section on page 395.
- 16. In the Generate dialog, press "Apply" so that your settings are saved for future reference and then press "Generate".
- A message is displayed informing you that bitmap files for each of the pixmaps you have created have been generated. The basename of each file is the name of the corresponding pixmap object.
You now have three separate stubs files for the main design. You will see why below.
11.8.5 Japanese Text
If the generated code contains Japanese text, you need to post-process the code with a filter utility, visutosj, which is provided as part of the WorkShop Visual release, before transferring it to a PC. See the Use of Japanese Font section on page 358 for more information.
11.9 Filling in the MFC Stubs
There are now four files containing callback stubs, three of them in your Motif XP directory. Assuming that your Motif XP directory is called MXP and your MFC directory is called WMFC, here is what you should have:
The Motif and Microsoft Windows stubs for the main design both contain the stubs which will be shared. The about dialog stubs file contains only one callback - DoClose. This file can be shared by both platforms. Fill it in as illustrated below.
11.9.1 about_st.cxx
/*
** Generated by WorkShop Visual
*/
/*
** WorkShop Visual generated prelude.
** Do not edit lines before "End of WorkShop Visual generated
prelude"
** Lines beginning ** WorkShop Visual Stub indicate a stub
** which will not be output on re-generation
*/
/*
**LIBS: -lXm -lXt -lX11
*/
#include <afxwin.h>
#include <afxext.h>
#include "about.h"
/* End of WorkShop Visual generated prelude */
/*
** WorkShop Visual Stub about_shell_c::DoClose
*/
void
about_shell_c::DoClose ( )
{
The code added here is Microsoft Windows code, but with the Motif XP library it will also work on Motif. This line hides the window whose shell is named about_sh.
You do not need two versions of this file - you just need to remember to copy it across to your PC with the other Microsoft Windows files.
11.9.2 The Stubs Files for the Main Design
The Motif stubs files for the main design contain, amongst other callbacks, a callback to popup the menu from the DrawingArea and another for the Exit button in the File menu. These callbacks are system dependent because, on the Microsoft Windows side, closing an application involves Microsoft Windows message handling and popping up the menu from the DrawingArea uses the Microsoft Windows drawing model. The other callbacks can be shared. Because of this, we shall need to arrange the stubs files so that we end up with the following:
- 1. motif_st.cxx. This will contain the routine to exit from the Motif application (DoExit) and the DoInput callback to popup a menu from the DrawingArea.
- 2. wind_st.cxx. This will contain the Microsoft Windows versions of the above routines except that there will be no DoInput callback, instead there is OnRButtonDown, as explained in the Popup Menu section on page 371 of this chapter.
- 3. share_st.cxx. This will contain all the other callbacks. These can be shared by both platforms.
We shall now fill in the stubs files. Leave the header information as it is in all files. Alter the files as illustrated in the following listings:
11.9.3 motif_st.cxx
/*
** Generated by WorkShop Visual
*/
/*
** WorkShop Visual generated prelude.
** Do not edit lines before "End of WorkShop Visual generated
prelude"
** Lines beginning ** WorkShop Visual Stub indicate a stub
** which will not be output on re-generation
*/
/*
**LIBS: -lXm -lXt -lX11
*/
#include <afxwin.h>
#include <afxext.h>
#include "main.h"
#include "about.h"
extern void XDmanage_link ( Widget, XtPointer client_data,
XtPointer );
extern void XDunmanage_link ( Widget, XtPointer client_data,
XtPointer );
extern void XDpopup_link ( Widget, XtPointer client_data,
XtPointer );
extern void XDpopdown_link ( Widget, XtPointer client_data,
XtPointer );
extern void XDmap_link ( Widget, XtPointer client_data, XtPointer
);
extern void XDunmap_link ( Widget, XtPointer client_data,
XtPointer );
extern void XDenable_link ( Widget, XtPointer client_data,
XtPointer );
extern void XDdisable_link ( Widget, XtPointer client_data,
XtPointer );
extern void XDshow_modal_link ( Widget, XtPointer client_data,
XtPointer );
/* End of WorkShop Visual generated prelude */
/*
** WorkShop Visual Stub shell_c::DoExit
*/
void
shell_c::DoExit ( )
{
}
/*
WorkShop Visual Stub popup_window_c::DoInput
*/
void
popup_window_c::DoInput ( )
{
}
/*
WorkShop Visual Stub radio_box_c::JazzChanged
*/
/*
WorkShop Visual Stub radio_box_c::ClassicalChanged
*/
/*
WorkShop Visual Stub about_sh_c::DoSetText
*/
Warning - The stubs code generated for the JazzChanged, DoSetText and ClassicalChanged functions must be removed from motif_st.cxx as these functions are declared in the share_st.cxx stubs file. The comments are left in to stop WorkShop Visual from regenerating the code.
This file contains code that is specific to the Motif version for the following reasons:
11.9.4 wind_st.cxx
Here you can see the Microsoft Windows version of the code to exit an application and to popup a menu. Edit the file as illustrated.
/*
** Generated by WorkShop Visual
*/
/*
** WorkShop Visual generated prelude.
** Do not edit lines before "End of WorkShop Visual generated
prelude"
** Lines beginning ** WorkShop Visual Stub indicate a stub
** which will not be output on re-generation
*/
/*
**LIBS: -lXm -lXt -lX11
*/
#include <afxwin.h>
#include <afxext.h>
#include "main.h"
#include "about.h"
/* End of WorkShop Visual generated prelude */
/*
WorkShop Visual Stub shell_c::DoExit
*/
void
shell_c::DoExit ( )
{
}
/*
WorkShop Visual Stub popup_window_c::OnRButtonDown
*/
afx_msg void
popup_window_c::OnRButtonDown( UINT nFlags, CPoint point )
{
}
/*
WorkShop Visual Stub radio_box_c::JazzChanged
*/
/*
WorkShop Visual Stub radio_box_c::ClassicalChanged
*/
/*
WorkShop Visual Stub about_sh_c::DoSetText
*/
Again the comment lines for the shared stubs are left in to stop WorkShop Visual subsequently regenerating those stubs to the file. Note that the file has "^Ms" as end of line markers for compatability with Microsoft Windows.
11.9.5 share_st.cxx
This code affects the subclassed about dialog and does the following:
Edit the file as illustrated.
/*
** Generated by WorkShop Visual
*/
/*
** WorkShop Visual generated prelude.
** Do not edit lines before "End of WorkShop Visual generated
prelude"
** Lines beginning ** WorkShop Visual Stub indicate a stub
** which will not be output on re-generation
*/
/*
**LIBS: -lXm -lXt -lX11
*/
#include <afxwin.h>
#include <afxext.h>
#include "main.h"
#include "about.h"
/* End of WorkShop Visual generated prelude */
/*
** WorkShop Visual Stub about_sh_c::DoSetText
*/
void
about_sh_c::DoSetText ( )
{
}
/*
** WorkShop Visual Stub radio_box_c::JazzChanged
*/
void
radio_box_c::JazzChanged ( )
{
}
/*
** WorkShop Visual Stub radio_box_c::ClassicalChanged
*/
void
radio_box_c::ClassicalChanged ( )
{
}
/*
WorkShop Visual Stub shell_c::DoExit
*/
...
/*
WorkShop Visual Stub popup_window_c::DoInput
*/
...
In this file the comments for the non-shared Motif stubs are left in to stop WorkShop Visual from subsequently regenerating them into the file.
11.10 Compiling the Application
Having created the design and generated code you are now ready to compile the application on both Motif and Microsoft Windows. This chapter shows you how to do this. 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.
For tutorial purposes, the stages involved in building the Microsoft Windows version of the application are illustrated below using Visual C++ v1.0 running on Microsoft Windows 3.1. However, the generated code can also be built using any C++ development environment capable of integrating the Microsoft Foundation Classes, e.g., Symantec C++. Refer to the Building the Code section on page 395 for general information about configuring Microsoft Windows-based C++ compilers to build the application.
11.10.1 Motif
All you need to do now is make the application by typing make at the command prompt in your Motif XP source directory. Your Makefile should pick up the following files:
Including the following header files:
Before running the application, be sure to arrange for the resource file to be read, as explained in the Setting up the X Resource File section on page 228.
11.11 Microsoft Windows
The code generated by WorkShop Visual is MFC code. It has not been generated for any specific Microsoft Windows application. The following section, Building the Code, lists the important points to bear in mind when building your user interface on Microsoft Windows. This section applies to all compilers.
11.11.1 Building the Code
Points to remember when building WorkShop Visual-generated applications on Microsoft Windows platforms:
- 1. You will need a C++ compiler and the Microsoft Foundation Class (MFC) include files and libraries installed on your system.
- 2. Configure the build tool to build a Microsoft Windows .EXE file.
- 3. Make sure the compiler has a valid include path to the MFC header files.
- 4. Make sure the compiler has a valid include path to the subdirectory containing the WorkShop Visual-generated source files.
- 5. Compile the code using large memory model settings.
Make sure the linker links in the MFC libraries or DLLs.
11.11.2 Using Visual C++
Visual C++ is a tool for building and debugging Microsoft Windows-based applications and libraries in an integrated Microsoft Windows environment. By using WorkShop Visual's cross-platform code generation capabilities much of the use of Visual C++ becomes unnecessary. The objects have been created by WorkShop Visual and the code has been generated for them. Without WorkShop Visual, you would normally start by designing the user interface objects (the dialogs, controls etc.) and then use various Visual C++ tools to create and manage the code to support them.
In order to maintain the sources of your application, Visual C++ uses the concept of a project. A project references all the source files and libraries that make up a program, as well as the compiler and linker commands that build the program. A project is composed of a makefile (which has the same base name as the program with a `.mak' extension), a status file (which has a `.vcw' extension), a definitions file (`.def' extension), as well as the source and resource files. A project is identified by the makefile. This means that when asked for a project (if creating a new project or opening another one), you specify the makefile. The makefile, status file and definitions file are generated by Visual C++. You will normally have no need to edit them.
Having used WorkShop Visual, all that is left for you to do is to create the project, add code for any callback functions, compile and run. Following is a description of how to do this based on Visual C++ for Microsoft Windows.
- 1. Transfer the following files to your PC:
Note - PC-NFS, available from SunSoft, is a tool designed to make sharing files between your PC and your Solaris system easy.
- 2. Start Visual C++
Three sets of instructions are given to match the following versions of Visual C++:
For Visual C++ version 2.0, turn to page 402
For Visual C++ version 4.0, turn to page 405
For Visual C++ versions 1.0 and 1.5, carry out the instructions in the following subsection.
Visual C++ Versions 1.0/1.5
To create a new Project
- 1. Choose New from the Project menu. The following dialog appears:
Figure 11-17 The New Project Dialog
- 2. Press the Browse button in order to locate the directory containing the WorkShop Visual generated source files.
- 3. At the prompt for the filename, type the name of your application with a `.mak' extension.
- This is the makefile, the file which identifies the project. It will be created for you and updated as you add and delete source files. Visual C++ creates other files for you too. If you want to know more about the files Visual C++ wishes to create, look in the Visual C++ documentation.
- 4. Alternatively, if you wish to open an existing project, select Open... from the File menu and the following dialog appears:
Figure 11-18 The Open Project Dialog
- 5. Use the directory browser on the right to find the directory containing the files generated by WorkShop Visual.
- As you are creating a new project, Visual C++ will ask you to specify the source files. The Project Edit dialog appears, as shown below.
Figure 11-19 The Project Edit Dialog
- 6. Check that the File Types list is set to request files of type `.c', `.cpp' or `.cxx'.
- 7. Press Add All to include all the sources in your project. Note that if you give a `.c' extension, Visual C++ will not be happy if the file contains c++ code.
- You will have to select individual files and press Add if you have source files from another application in the same directory.
- 8. Change the list of file types to `.rc' files. Add the resource file. Note that Visual C++ will only accept one resource file. If you have more than one, you should #include them in one file and add that file to the project.
- 9. Close the Edit dialog.
- 10. From the Options menu, choose Project. The following dialog appears:
Figure 11-20 The Project Options Dialog
- 11. Make sure that you have selected Use Microsoft Foundation Classes. Press the Compiler button. In the next dialog, shown below, select Memory Model from the category list and choose Large.
Figure 11-21 The Compiler Options Dialog
- This will ensure that the code segment will be large enough for your application. If you experience problems consult your Visual C++ documentation.
- 12. In the same dialog, select the Listing Files category, then from the subsequently displayed dialog, deselect Include Local Variables and Browser Information.
- Doing this will speed up the compilation process.
- 13. Press OK for these two dialogs.
Note - In the Project Options dialog shown in Figure 11-20, the Debug option is set. If you encounter problems with your code segment becoming too large, try deselecting this option.
- 14. Finally, check that Visual C++ has been installed with the correct list of directories to search for include files. Choose Directories from the Options menu to display the dialog shown below.
Figure 11-22 The Directories Options Dialog
- Make sure that you are including files from the current directory (this is indicated by a `.'(period)). If the system files are not being included you should refer to your Visual C++ installation manual.
- Having provided the details of your project, you may now build it.
- 15. Select "Build <projectname>.exe" in the Project menu or select the Build button on the toolbar at the top of the Workbench window.
Figure 11-23 Toolbar Buttons
- Figure 11-23 shows three buttons on the Visual Workbench toolbar which you may wish to use to build your application. The left button will only build the currently active source file. The middle button builds all files which need to be built. The right button rebuilds all the files in your project.
- 16. If this is the first time the project has been built, you will be asked if you wish Visual C++ to create a definitions file for you:
Figure 11-24 Definitions File Message
- 17. Select Yes. Visual C++ will then produce a window for you to edit the definitions file. You will not normally need to alter this file, so simply close it.
- 18. Select Build again. Visual C++ will ask you if you wish to build all affected files. Select Yes. All the files you specified as being part of the project are then built. The output from the compiler is displayed in the output window.
- If Visual C++ encounters any errors, these are displayed and the compiler stops compiling. You may now press F4 to ask Visual C++ to open the file containing the error and locate you at the relevant point in the file. Subsequent presses of F4 allow you to move through the list of errors, opening files as necessary. Double clicking on an error will also open the relevant file and move to the part of the file where the error was detected. The windows opened onto these files are full text editing windows. You can also view and edit a file in this way by selecting Open... from the File menu.
- 19. Once the application has built successfully, you can try it out. Select "Execute <projectname>.exe" from the Project menu.
Visual C++ Version 2.0
- 1. Go to File Menu and select "New".
- The following dialog is displayed:
Figure 11-25 Creating a New Item
- 2. Select "Project" from the Name list.
- The New Project dialog is then displayed, as shown below:
Figure 11-26 New Project dialog
- 3. Enter a name (such as "Tutorial") in the "Project Name" field.
- 4. Select "Application" from the Project Type option menu.
- 5. Use the "directories" search box to locate the directory in which you have stored the files which you copied to the PC.
- 6. Double-click each file to add it to your project.
- 7. Press the "Close" button.
- Visual C++ then opens the new project.
- 8. Select the "Settings" option from the Project menu.
- The Project Settings dialog is then displayed, as shown below:
Figure 11-27 Project Settings dialog
- 9. Select the "Use MFC in a Shared Dll..." option from the Microsoft Foundation Classes option menu as shown above and then Ok the dialog.
- Finally, to build your application:
- 10. Select "Build" from the Project menu.
- If Visual C++ encounters any errors, these are displayed and the compiler stops compiling. You may now press F4 to ask Visual C++ to open the file containing the error and locate you at the relevant point in the file. Subsequent presses of F4 allow you to move through the list of errors, opening files as necessary. Double clicking on an error will also open the relevant file and move to the part of the file where the error was detected. The windows opened onto these files are full text editing windows. You can also view and edit a file in this way by selecting Open... from the File menu.
- 11. Once the application has built successfully, you can try it out. Select "Execute <projectname>.exe" from the Project menu.
Visual C++ Version 4.0
- 1. Select "New" from the File menu.
- A list of new items which can be created is then displayed as shown below:
Figure 11-28 New items list
- 2. Select "Project Workspace" from the items list and Ok the dialog.
- The New Project Workspace dialog is then displayed.
Figure 11-29 New Project Workspace dialog
- 3. Select "Application" from the Type list and enter a name (such as "Tutorial") in the "Name" field.
- 4. Press the "Create" button to complete your actions.
- You are then presented with the main Visual C++ dialog. Next, you must now populate your project with the files you wish to build.
- 5. Select "Files into project" from the Insert menu.
- The following dialog is displayed:
Figure 11-30 Insert Files dialog
- 6. Locate the directory where you have placed the files you copied to the PC.
- 7. Highlight the files required by clicking on the first in the list then press shift and then click on the last of the files in the list.
- 8. Press the Ok button to add the selected files to the project.
- 9. Select the "Settings" option from the Build menu.
- The Project Settings dialog is then displayed, as shown below:
Figure 11-31 Project settings dialog
- 10. Select the "Use MFC in a Shared Dll..." option from the Microsoft Foundation Classes option menu as shown above and then Ok the dialog.
- Finally, to build your application:
- 11. Select "Build Tutorial.exe" from the Build menu.
- If Visual C++ encounters any errors, these are displayed and the compiler stops compiling. You may now press F4 to ask Visual C++ to open the file containing the error and locate you at the relevant point in the file. Subsequent presses of F4 allow you to move through the list of errors, opening files as necessary. Double clicking on an error will also open the relevant file and move to the part of the file where the error was detected. The windows opened onto these files are full text editing windows. You can also view and edit a file in this way by selecting Open... from the File menu.
- 12. Once the application has built successfully, you can try it out. Select "Execute <projectname>.exe" from the Build menu.
