Power GUI Programming with VisualAge C++/powergui.iso/read.me

Text File | 1996-10-31 | 22KB | 377 lines

Thank you for purchasing our newest edition of Power GUI Programming.  We
hope you find the book and its accompanying disk useful.  The disk
contains example programs, a trial copy of VisualAge for C++ for Windows,
and an extra chapter that does not appear in the text of the book.


REPORTING PROBLEMS
------------------
In the last edition, we asked you to contact us directly with any problems
that you found in the book or with the examples.  For a number of reasons
(some of us taking new jobs and changing Internet addresses), we'd like
you to report problems in one of the normal support forums provided for
VisualAge for C++.  Start your append with something like, "Could you
please forward the following remarks to one of the Power GUI authors."
For a list of the support forums, see the VisualAge for C++ publication
"Support and How to Get It" provided with the product.

In the last addition of the book we inserted a large number of spurious
commas just to see if you were on your toes.  Many of you were and
politely pointed it out to us.  In keeping with this tradition, this time
we've decided to forgo the use of the common names Windows and OS/2 for
the more correct and verbose names "the Windows operating system" and
"the OS/2 operating system."   Please don't fill up the forums with
comments on this.


THE EXAMPLE PROGRAMS
--------------------
The disk contains 150 example programs that appear in or are referenced
from the book.  We'd like to tell you that we have extensively tested the
examples and certified them ready for you to use without any work on your
part, but we won't.  We will tell you that, despite what the copyright on
this disk seems to imply, we've built these examples to help you write the
code for your product.  You can freely use parts or all of these examples
as long as you don't sell the classes as your own.

Installing the Examples
-----------------------
There is nothing fancy about the installation or use of these examples.
As the instructions below describe, you can run the examples directly from
the CD-ROM or copy them to your hard disk (this step is required if you
want to rebuild the examples).  To copy the examples from the CD-ROM drive
on m: to your hard disk on d:, use the following command:
  xcopy m:\powergui\*.* d:\powergui\*.* /s

Running the Examples
--------------------
The examples are on the CD-ROM in the "powergui" directory.  Each example
is in its own directory underneath a directory for the chapter that
describes the use of the example.  The executable code for each example is
in yet another directory under the example directory.  Executable code for
the Windows platforms is in a "win" directory and executable code for the
OS/2 platform is in an "os2" directory.  Typically, the executable program
is named the same as the directory holding the source code for the
example.

For example, in Chapter 1, "Getting Started," we've introduced a program
called "Simple Example - Version 1."
  1) The code for this program is on the CD-ROM in the directory:
     \powergui\getstart\start1.
  2) To run the OS/2 version of this program, execute the following
     commands:
     cd \powergui\getstart\start1\os2
     start1
  3) Likewise, to run the Windows version of this program, execute the
     following commands:
     cd \powergui\getstart\start1\win
     start1

Some of the examples have dependencies on other files (help and text
files) that require you to run them with the directory containing the
executable file as the current directory.

The table near the bottom of this readme identifies the location of each
example.

All of the example programs have been built by dynamically linking to both
the C/C++ runtime and the Open Class Library DLLs.  Therefore, to run
these programs, you must have installed the appropriate VisualAge for C++
product so that the C/C++ runtime and Open Class Library DLLs exist on
your system and are found via the LIBPATH (OS/2) or PATH (Windows)
environment variables.  These products are VisualAge C++ for OS/2, Version
3.0, and VisualAge for C++ for Windows, Version 3.5 (the CD-ROM includes a
trial version of the latter).  Some examples use features added to Open
Class Library in VisualAge for C++ for Windows that are not found in the
OS/2 product as shipped (we hope that these features make it into a FixPak
for VisualAge for C++ for OS/2, however).

For some of the examples to run properly, you must apply the latest FixPak
for Open Class Library.  You can find information for obtaining FixPaks on
the VisualAge for C++ home page on the World Wide Web:
  www.software.ibm.com/ad/visualage_c++

You can also use a program that we've supplied on the CD-ROM to run many
of the examples.  This program is further described below.  To run the
program on the examples directly from the CD-ROM, execute the following
commands:
  m:
  cd \powergui
  powergui

Building the Examples
---------------------
To rebuild the examples, you must copy them to your hard drive.  The
following examples assume that you have copied them to the "powergui"
directory of your d: drive as we have described above.

Each example contains a file, named "makefile," that you use to rebuild
the program.  You can build any example by making the directory containing
the example the current directory and executing the command "nmake."  Each
makefile is constructed to work in both the OS/2 and Windows operating
systems.  However, in the OS/2 operating system you are required to add
the definition of IC_PM to the environment.  The easiest way to do this is
by adding the following line to the bottom of your config.sys file and
rebooting your machine:
   set IC_PM=1

You can add the nmake option "/a" to force the examples to rebuild
regardless of the dependency rules contained in makefile.  For example, to
force the rebuild of the first "Getting Started" example, issue the
following commands.
   d:
   cd \powergui\getstart\start1
   nmake /a

As supplied, the make files do not build the examples with debugging
information.  If you need to debug the examples, simply add "/Ti+" to the
VisualAge for C++ compiler options environment variable, icc, and then run
nmake.  The following commands can rebuild the first "Getting Started"
example with debugging information:
   set icc=/Ti+
   d:
   cd \powergui\getstart\start1
   nmake /a

The PowerGUI Program
--------------------
In the root example directory (e.g. d:\powergui above), we have included a
simple program (actually a batch file to run the program) that we used to
build and test the examples.  We've included this program on the disk to
give you better visibility to the examples.  To start the program, change
to the root examples directory and enter "powergui."
  d:
  cd \powergui
  powergui

When loaded, the program displays a tree-view container in the top half of
a split canvas.  The bottom of the split canvas is a status window that
displays the results of your requests.

The program allows you to build and run the example programs one at a
time, by chapter, or all at once.  To run a single program, double-click
the program name.  To run all of the examples in a chapter, double-click
the chapter name.  Use the menu bar to access other build options.

To build a single program, select the program name and choose the
"Examples/Build Selected" menu item.  Similarly, to build all the programs
in a chapter, select the chapter name and again choose the
"Examples/Build Selected" menu item.

Because the program uses a work queue to process requests to build and run
programs, you can only build or run a single program at a time.  You can
add additional requests but they are queued until either the prior build
finishes or you terminate the currently running example program.

Because of differences between the OS/2 and Windows operating systems in
executing child command processes and redirecting output, the programs
build and run differently on these two platforms.  On the OS/2 platform,
builds and non-UI programs are executed in a background process and the
results are displayed in the status portion of the split canvas.  On the
Windows platform, builds and non-UI programs are executed in a foreground
process.  When you run non-UI programs on the Windows operating system,
the DOS window associated with the program remains open.  You must close
this window before the powergui program can run other programs.

If you want to use the powergui program to build the examples with
debugging information, you must set the compiler environment variable
prior to starting the powergui program.  If you always want to build the
examples with debugging information, you can edit the batch files used to
start powergui and add the SET ICC=/Ti+ command prior to the invocation of
powergui.

The output of builds from within powergui is redirected to a log file
(buildlog.os2 on the OS/2 operating system and buildlog.win on the Windows
operating system).  You can replace the status window with the contents of
this file by choosing the "Examples/Display Error Log" menu item.

Table of Example Programs
-------------------------
The following lists the examples contained on the CD-ROM.

 #  Chapter Directory              EXE           Example Name
--- ------- -----------------      --------      -----------------------------
  1    1    getstart\start1        start1        Simple Example - Version 1
  2    1    getstart\start2        start2        Simple Example - Version 2
  3    1    getstart\nonport       nonport       Using Platform-Specific Code
  4    3    latour\shopping        shopping      Shopping List
  5    5    frame1\dialog          dialog        Frame Window From Dialog Template
  6    5    frame1\modal           modal         Modal Frame Window
  7    5    frame1\minmax          minmax        Minimize/Maximize Handler
  8    5    frame1\ok2close        ok2close      Confirm Frame Window Closing
  9    5    frame1\frmextns        frmextns      Frame Extension Sampler
 10    5    frame1\dismiss         dismiss       Dismissing a Window
 11    5    frame1\infoarea        infoarea      Information Area for the System Menu
 12    5    frame1\titlebar        titlebar      Accessing the Title Bar
 13    6    menus\accel            accel         Accelerator Table Loading
 14    6    menus\addsubmn         addsubmn      Loading a Resource Submenus
 15    6    menus\cursor           cursor        Using a Menu Cursor
 16    6    menus\drawmenu         drawmenu      Drawing Menu Items
 17    6    menus\dynaccel         dynaccel      Dynamic Accelerators
 18    6    menus\dynpopup         dynpopup      Dynamically-Created Pop Up Menus
 19    6    menus\dynsubmn         dynsubmn      Dynamic Submenus
 20    6    menus\menubar          menubar       Using an IMenuBar
 21    6    menus\menures          menures       Defining a Menu Resource
 22    6    menus\sysmenu          sysmenu       Accessing the System Menu
 23    6    menus\titlebmp         titlebmp      Title Bar Bitmaps
 24    6    menus\txtpopup         txtpopup      Pop Up Menu Sample
 25    7    controls\ctors         ctors         Control Constructor and Color
 26    8    static\boxes           boxes         Group Box and Outline Box
 27    8    static\iconbmp         iconbmp       Icons and Bitmaps
 28    8    static\textclr         textclr       Static Text Colors
 29    8    static\textcv          textcv        Static Text and Canvases
 30    8    static\textstyl        textstyl      Static Text Styles
 31    9    editctls\logon         logon         Using an Edit Handler
 32    9    editctls\simple        simple        Simple Edit Control
 33   10    buttons\pushbut        pushbut       Push Buttons
 34   10    buttons\titlebut       titlebut      Title Bar Bitmaps
 35   10    buttons\radio          radio         Radio Button Select Handler
 36   11    listctls\drawlist      drawlist      List Box Custom Drawing
 37   11    listctls\spinbut       spinbut       Spin Button Date Control
 38   12    slider\progind         progind       Progress Indicator
 39   12    slider\slider          slider        Linear Slider
 40   12    slider\cslider         cslider       Circular Slider
 41   12    slider\sliddraw        sliddraw      Progress Indicator Custom Painting
 42   12    slider\slidsync        slidsync      Synchronized Slider Controls
 43   13    cnr\treetxtv           treetxtv      Container Tree Text View
 44   13    cnr\treeicov           treeicov      Container Tree Icon View
 45   13    cnr\treenamv           treenamv      Container Tree Name View
 46   13    cnr\textview           textview      Container Text View with Multiple Lines
 47   13    cnr\cdate              cdate         Dates and Times using CDATE/CTIME
 48   13    cnr\uidate             uidate        Dates and Times using IDate/ITime
 49   13    cnr\help               help          Using Help in the Container
 50   13    cnr\edithdr            edithdr       Container MLE Edit Handler
 51   13    cnr\popup              popup         Container Popup Menus
 52   13    cnr\dynobj             dynobj        Dynamic Creation of Objects
 53   13    cnr\minicnr            minicnr       Using Mini-Icons in the Container
 54   13    cnr\spreadsh           spreadsh      SpreadSheet Behavior in the Details View
 55   13    cnr\treedet            treedet       Combining the Tree and Details View
 56   13    cnr\cnralloc           cnralloc      Using ICnrAllocator
 57   14    notebook\simple        simple        Simple Client Notebook
 58   14    notebook\default       default       Default Notebook
 59   14    notebook\addpages      addpages      Adding Notebook Pages
 60   14    notebook\vportdlg      vportdlg      Using a View Port as a Notebook Page
 61   14    notebook\select        select        Delayed Addition of Pages
 62   14    notebook\smrtguid      smrtguid      Smart Guide Notebook
 63   15    canvas\lunchdlg        lunchdlg      Lunch Dialog Box
 64   15    canvas\cvsimple        cvsimple      Simple ICanvas
 65   15    canvas\cvtab           cvtab         Nested Canvas Tabbing
 66   15    canvas\setlunch        setlunch      Lunch Dialog using a Set Canvas
 67   15    canvas\setdecks        setdecks      Decks in a Set Canvas
 68   15    canvas\setpack         setpack       Deck Packing and Alignment in a Set Canvas
 69   15    canvas\mcsimple        mcsimple      Simple Multicell Canvas
 70   15    canvas\mclunch         mclunch       Lunch Dialog using a Multicell Canvas
 71   15    canvas\mcbad           mcbad         Multicell Canvas without Expandable Rows/Columns
 72   15    canvas\mccombo         mccombo       Multicell Canvas with Combination Boxes
 73   15    canvas\mcgroup         mcgroup       Multicell Canvas with Smarter Group Boxes
 74   15    canvas\splittxt        splittxt      Simple Split Canvas
 75   15    canvas\splitprb        splitprb      Split Canvas with Problem Windows
 76   15    canvas\vportbmp        vportbmp      View Port for Scrolling a Bitmap
 77   15    canvas\vportlog        vportlog      View Port with Logically-Sized Window
 78   15    canvas\complex         complex       Complex Canvas Example
 79   16    toolbar\animated       animated      Animated Buttons
 80   16    toolbar\cbutsimp       cbutsimp      Simple Custom Buttons
 81   16    toolbar\cbuthdr        cbuthdr       Custom Button Handler
 82   16    toolbar\flybasic       flybasic      Simple Fly-over Help
 83   16    toolbar\flytbar        flytbar       Tool Bar Fly-over Help
 84   16    toolbar\tbardeck       tbardeck      Using Decks in Tool Bars
 85   16    toolbar\tbarfrms       tbarfrms      Floating Tool Bars
 86   16    toolbar\tbargrps       tbargrps      Using Groups in Tool Bars
 87   16    toolbar\tbarlocs       tbarlocs      Tool Bar Locations
 88   16    toolbar\tbarmult       tbarmult      Multiple Tool Bars
 89   17    genhdrs\cmdhdrs        cmdhdrs       Simple Command Handler
 90   17    genhdrs\keybd          keybd         Keyboard Handler
 91   17    genhdrs\mouseclk       mouseclk      Mouse Click Handler
 92   17    genhdrs\enablcls       enablcls      Disable Close
 93   17    genhdrs\mousemov       mousemov      Processing Mouse Pointer Movement
 94   17    genhdrs\painthdr       painthdr      Paint Handler
 95   18    fonts\simple           simple        Simple Font Example
 96   18    fonts\genfont          genfont       Common Font Functions
 97   18    fonts\advfont          advfont       Using Advanced Font Functions
 98   18    fonts\filedlg          filedlg       Using the File Dialog
 99   18    fonts\fontdlg          fontdlg       Using the Font Dialog
100   19    advframe\fstyle        fstyle        Frame Window Styles
101   19    advframe\drawextn      drawextn      Derived Frame Extensions
102   19    advframe\framesav      framesav      Frame Window Position Save Handler
103   19    advframe\tstdlg        tstdlg        Dialog Windows
104   19    advframe\winview       winview       Window Viewer Example
105   19    advframe\mdi           mdi           MDI Example
106   20    thread\simple          simple        Simple Multi-threaded Example
107   20    thread\exit            threadex      Thread Termination
108   20    thread\improved        broken        Broken Thread Example
109   20    thread\improved        fixed         Fixed Thread Example
110   20    thread\improved        easy          Simplified IThreadMemberFn
111   20    thread\picalc          picalc        Pi Calculator
112   20    thread\pithread        pithread      Calculate Pi on a Thread
113   20    thread\piserve         piserve       Service Thread
114   20    thread\starting        starting      Starting Threads Using IThread
115   20    thread\threads         threads       Ultimate IThread Demo program
116   21    dm\menudrag            menudrag      Menu Drag Example
117   21    dm\spindrag            spindrag      Spin Button Drag Example
118   21    dm\lboxdrag            lboxdrag      List Box Drag Example
119   21    dm\dragview            dragview      Drag Information Viewer
120   23    help\helpmenu          helpmenu      Help Menu Choices
121   23    help\helpid            helpid        Runtime Setting of Help Panels
122   23    help\helptbl           helptbl       Help Tables
123   23    help\helpothr          helpothr      Help for Special Cases
124   24    reslib\exetext         exetext       Using Resources in the EXE
125   24    reslib\dlltext         dlltext       Building a Resource DLL
126   24    reslib\stattxt         stattxt       Switching Resources Dynamically
127   24    reslib\procaddr        NONE          Using IProcedureAddress
128   25    profile\basicpro       basicpro      Basic Profile Example
129   25    profile\advprof        profile       GUI Profile Viewer
130   25    profile\viewprof       viewprof      Non-GUI Profile Viewer
131   26    data\cipher            cipher        Using an IString as a Buffer
132   26    data\igrep             igrep         Using IString::isLike
133   26    data\strngtst          strngtst      Using IStringTest
134   26    data\convert           convert       Using IString Conversion Functions
135   26    data\mybuffer          mybuffer      Replacing IBuffer With Your Own Class
136   26    data\str2date          str2date      Creating Dates and Times from Strings
137   26    data\stparse           stparse       String Parsing
138   27    exceptns\newexcp       newexcp       Deriving a New Exception Class
139   27    exceptns\exviewer      exviewer      An Exception Viewer
140   28    debug\trace            trace         Simple Trace Example
141   28    debug\tracebox         tracebox      Trace Browser Utility
142   28    debug\prtque           prtque        Trace Queue Browser Example
143   28    debug\zeroptr          zeroptr       Debugging a Zero Pointer
144   28    debug\excdisp          excdisp       Displaying an Exception in a Message Box
145   28    debug\invisibl         invisibl      Finding Why a Window is not Visible
146   28    debug\sigterm          sigterm       Building a Termination Signal Handler
147   29    shipapp\hello1         hello1        Changes to Hello1 for Start-Up Tuning
148   29    shipapp\appstat        appstat       Using Static Object Functions instead of Static Objects
149   29    shipapp\genprags       NONE          Command File to Generate alloc_text for Static Functions
150  n/a    extlib\valueset        testvset      Value Set Test Program


THE TRIAL COPY OF VISUALAGE FOR C++ FOR WINDOWS, VERSION 3.5
------------------------------------------------------------
The IBM Corporation was kind enough to allow us to include a trial version
of VisualAge for C++ for the Windows operating system with our book.  You
can use this trial copy for 60 days after you install it.

The trial copy is located in the "trialva" directory.  It also contains
readme.txt, license.agr, and setup.exe.  See readme.txt for installation
information and license.agr for licensing information.  To install the
trial copy from the CD-ROM drive on m:, run setup.exe while running on
either the WIndows 95 or Windows NT operating system:
  m:
  cd \trialva
  setup


THE EXTRA CHAPTER
-----------------
Due to space and time constraints, we include an extra chapter as a
PostScript file rather than as part of the text of the book itself.  This
chapter, "Custom Controls and Handlers," describes how you can create your
own window, event, and event handler classes to extend Open Class Library.
This chapter is essentially unchanged from how it appeared in the
preceding version of this book, so its dicussion and example program are
in the context of using the version of Open Class Library shipped with
C Set ++ for OS/2 (the predecesor product to VisualAge for C++).
However, the concepts that the chapter presents are still applicable to
VisualAge for C++.

The PostScript file, extlib.ps, is in the "powergui" directory.