Dynamic Link Library

Click on the banner to return to the user guide home page.

Dynamic Link Library

The Tools.h++ Class Library can be linked as a Microsoft Windows 3.X Dynamic Link Library (DLL). In a DLL, linking occurs at run time when the routine is actually used. This results in much smaller executables because routines are pulled in only as needed. Another advantage is that many applications can share the same code, rather than duplicating it in each application.

Because Windows and C++ technology is evolving so rapidly, be sure to check the file TOOLDLL.DOC on your distribution disk for more updates.

The DLL Example

This section discusses a sample Windows application, DEMO.CPP, that uses the Tools.h++ DLL. The code for this program can be found in the subdirectory DLLDEMO. This program falls into the familiar category of "Hello World" examples.

Figure 9. The demo program window.

Screen shot of demo program window showing the words Hello World, from RogueWave, a circle, and a square.

The program is somewhat unusual, however, in that it maintains a linked list of Drawable objects you can insert into the window at run time. You can find the list, which is implemented using class RWSlistCollectables, in the subdirectory DLLDEMO. The discussion in this section assumes that you are somewhat familiar with Windows 3.X programming, but not with its relationship to C++.

Here's the main program of DEMO.CPP, the sample Windows application that uses the Tools.h++ DLL.

/*
 * Sample Windows 3.X program, using the Tools.h++ DLL.
 */

#include "demowind.h"

int PASCAL
WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance,
        LPSTR , int nCmdShow)                                // 1
{  // Create an instance of the "DemoWindow" class:
   DemoWindow ww(hInstance, hPrevInstance, nCmdShow);        // 2

   // Add some items to it:
   ww.insert( new RWRectangle(200, 50, 250, 100));           // 3
   ww.insert( new RWEllipse(50, 50, 100, 100));
   ww.insert( new RWText(20, 20, "Hello world, from Rogue 
             Wave!"));

   ww.show();      // Show the window                        // 4
   ww.update();    // Update the window

   // Enter the message loop:
   MSG msg;
   while( GetMessage( &msg, NULL, 0, 0))                     // 5
   {
     TranslateMessage( &msg );
     DispatchMessage( &msg );
   }

   return msg.wParam;                                        // 6
}

Here's the line-by-line description of the program.

//1	This is the Windows program entry point that every Windows program must have. It is equivalent to C's `main` function.
//2	This creates an instance of the class *DemoWindow*, which we will see later. It represents an abstract window into which objects can be inserted.
//3	Here we insert three different objects into the *DemoWindow*: a rectangle, an ellipse, and a text string.
//4	This tells the *DemoWindow* to show itself and to update itself.
//5	Finally, the windows main event loop is entered.
//6	The DemoWindow destructor frees all memory allocated for its window objects.

This header file declares the cla ss DemoWindow. A key feature is the singly linked list called myList, which holds the list of items that have been inserted into the window. The member function DemoWindow::insert(RWDrawable*) allows new items to be inserted. Only objects that inherit from class RWDrawable, to be defined later on, may be inserted.

The member function paint() may be called when it is time to repaint the window. The list myList will be traversed and each item in it will be repainted onto the screen.

Here's a listing of the DEMOWIND.H file

#ifndef __DEMOWIND_H__
#define __DEMOWIND_H__

/*
 * A Demonstration Window class --- allows items that
 * inherit from the base class RWDrawable to be
 * "inserted" into it.
 */

#include <windows.h>
#include <rw/slistcol.h>
#include "shapes.h"

class DemoWindow {
  HWND                  hWnd;                 // My window handle
  HINSTANCE             myInstance;       // My instance's handle
  int                   nCmdShow;
  RWSlistCollectables   myList;  // A list of items in the window

public:

  DemoWindow(HINSTANCE mom, HINSTANCE prev, int);
  ~DemoWindow();

    void   insert(RWDrawable*);   // Add a new item to the window

  HWND     handle() {return hWnd;}
  int      registerClass();            // First time registration
  void     paint();                // Called by Windows procedure
  int      show() {return ShowWindow(hWnd,nCmdShow);}
  void     update() {UpdateWindow(hWnd);}

  friend long FAR PASCAL _export
       DemoWindow_Callback(HWND, UINT, WPARAM, LPARAM);
};

DemoWindow*  RWGetWindowPtr(HWND h);
void         RWSetWindowPtr(HWND h, DemoWindow* p);

#endif

The demowind.cpp File

Now let's look at the definitions of the public functions of class DemoWindow: the DemoWindow constructor, the DemoWindow destructor, and the member functions insert(), registerClass(), and paint(). Detailed comments follow this listing.

#include <windows.h>
#include <rw/vstream.h>
#include "demowind.h"
#include "shapes.h"
#include <stdlib.h>
#include <string.h>

/*
 * Construct a new window.
 */
DemoWindow::DemoWindow( HINSTANCE mom, HINSTANCE prev,
                        int cmdShow)                          //1
{
  myInstance = mom;
  nCmdShow = cmdShow;

  // Register the class if there was no previous instance:
  if(!prev) registerClass();                                  //2

  hWnd = CreateWindow("DemoWindow",                           //3
                      "DemoWindow",
                      WS_OVERLAPPEDWINDOW,
                      CW_USEDEFAULT, 0,
                      CW_USEDEFAULT, 0,
                      NULL,
                      NULL,
                      myInstance,
                     (LPSTR)this );    // Stash away 'this'   //4

  if(!hWnd) exit( FALSE );
}

/*
 * Register self. Called once only.
 */
int
DemoWindow::registerClass(){                                 //5
   WNDCLASS wndclass;
   wndclass.style = CS_HREDRAW | CS_VREDRAW;
   wndclass.lpfnWndProc = ::DemoWindow_Callback;             //6
   wndclass.cbClsExtra = 0;
   // Request extra space to store the 'this' pointer
   wndclass.cbWndExtra = sizeof(this);                       //7
   wndclass.hInstance = myInstance;
   wndclass.hIcon = 0;
   wndclass.hCursor = LoadCursor( NULL, IDC_ARROW );
   wndclass.hbrBackground = GetStockObject( WHITE_BRUSH );
   wndclass.lpszMenuName = NULL;
   wndclass.lpszClassName = "DemoWindow";

   if( !RegisterClass(&wndclass) ) exit(FALSE);
   return TRUE;
}

DemoWindow::~DemoWindow(){
   // Delete all items in my list:
   myList.clearAndDestroy();                                 //8
}

void
DemoWindow::insert(RWDrawable* d){
   // Add a new item to the window:
   myList.insert(d);                                         //9
}

void
DemoWindow::paint(){                                        //10
   RWDrawable* shape;
   PAINTSTRUCT ps;
   BeginPaint( handle(), &ps);                              //11

   // Draw all items in the list.  Start by making an iterator:
   RWSlistCollectablesIterator next(myList);                //12

   // Now iterate through the collection, drawing each item:
   while( shape = (RWDrawable*)next() )                     //13
     shape->drawWith(ps.hdc);                               //14

   EndPaint( handle(), &ps );                               //15
}

/*
 * The callback routine for this window class.
 */
long FAR PASCAL _export
DemoWindow_Callback(HWND hWnd, unsigned iMessage,           //16
                    WPARAM wParam, LPARAM lParam)
{
   DemoWindow* pDemoWindow;

   if( iMessage==WM_CREATE ){                               //17
     // Get the "this" pointer out of the create structure 
     // and put it in the windows instance:
     LPCREATESTRUCT lpcs = (LPCREATESTRUCT)lParam;
     pDemoWindow = (DemoWindow*) lpcs->lpCreateParams;
     RWSetWindowPtr(hWnd, pDemoWindow);
     return NULL;
  }

   // Get the appropriate "this" pointer
   pDemoWindow = RWGetWindowPtr(hWnd);                      //18

   switch( iMessage ){
     case WM_PAINT:
       pDemoWindow->paint();                                //19
       break;
     case WM_DESTROY:
       PostQuitMessage( 0 );
       break;
     default:
       return DefWindowProc(hWnd, iMessage, wParam, lParam);
  };
   return NULL;
}

void RWSetWindowPtr(HWND h, DemoWindow* p){                  //20
   SetWindowLong(h, 0, (LONG)p);
}

DemoWindow* RWGetWindowPtr(HWND h){                          //21
   return (DemoWindow*)GetWindowLong(h, 0);
}

//1	This is the constructor for *DemoWindow*. It requires the handle of the application instance creating it, `mom`, the handle of any previously existing instance, `prev`, and whether to show the window in iconic form. These variables are as received from `WinMain`, the main windows procedure that we have already seen.
//2	The constructor checks to see if any previous application instance has been run and, if not, registers the class.
//3	The new window is created.
//4	A key feature is the use of the Windows extra data feature to store the `this` pointer for this *DemoWindow*. The procedure to do this is somewhat cumbersome, but very useful. The value placed here will appear in the `CREATESTRUCT` structure, which we can retrieve when processing the `WM_CREATE` message generated by the `CreateWindow` function.
//5	This member function is only called for the first instance of an application.
//6	The global function `DemoWindow_Callback` is registered as the callback procedure for this window.
//7	We ask Windows to set aside space for the `this` pointer in this Windows class. This will be used to associate a Windows handle with a particular *DemoWindow*.
//8	The destructor calls `clearAndDestroy()` to delete all items that have been inserted into `myList`.
//9	The member function `insert(RWDrawable)` inserts a new item into the window. Because RWDrawable* inherits from RWCollectable, as we shall see later on, there is no need to do a cast when calling `RWSlistCollectables::insert(RWCollectable)`. By making `myList` private and offering a restricted insert that takes arguments of type `RWDrawable` only, we ensure that only drawables will be inserted into the window.
//10	Here's the paint procedure, called when it is time to repaint the window.
//11	We start by getting the handle for this window, then calling `BeginPaint` to fill a `PAINTSTRUCT` with information about the painting.
//12	An iterator is constructed in preparation for traversing the list of items to be painted.
//13	Get the next item to be painted. If nil is returned, then there are no more items and the while loop will finish.
//14	For each item, call the virtual function `drawWith`, causing the item to paint itself onto the given device context.
//15	The `PAINTSTRUCT` is returned.
//16	Here's the callback routine to be called when it is necessary to process a message for this window. It uses the very convenient `_export` keyword of Borland C++ to indicate that this function should be exported. If you use this procedure, you don't have to list the function in an Exports section of the module definition file.
//17	If the message is a `WM_CREATE` message, it was generated by the `CreateWindow` function and this is the first time through for this procedure. Use the rather baroque procedure to fetch the `this` pointer from the `CREATESTRUCT` (recall it had been inserted at line 4), and put it into the Windows extra data. The function `RWSetWindowPtr` will be defined later.
//18	The function `RWGetWindowPtr(HWND)` is used to retrieve the pointer to the appropriate *DemoWindow*, given a Windows `HANDLE`.
//19	If a `WM_PAINT` has been retrieved, then call the `paint()` member function, which we have already seen.
//20	This function is used to put a `this` pointer into the Windows extra data. The idea is to have a one-to-one mapping of Windows handles to instances of *DemoWindow*.
//21	This function is used to fetch the `this` pointer back out.

An Excerpt from SHAPES.H

This section deals with the subclasses of RWDrawable. Class RWDrawable is an abstract base class that inherits from the Tools.h++ class RWCollectable, and adds a new member function drawWith(HDC). Subclasses specializing RWDrawable should implement this function to draw itself onto the supplied device context handle.

We have reprinted only one subclass here, RWRectangle. Class RWRectangle inherits from RWDrawable. Note that it uses the struct RECT provided by Windows as member data to hold the corners of the rectangle.

class RWDrawable : public RWCollectable{
public:
  virtual void  drawWith(HDC) const = 0;
};

class RWRectangle : public RWDrawable{
  RWDECLARE_COLLECTABLE(RWRectangle)

public:
  RWRectangle() { }
  RWRectangle(int, int, int, int);

  // Inherited from RWDrawable:
  virtual void  drawWith(HDC) const;

  // Inherited from RWCollectable:
  virtual Rwspace    binaryStoreSize() const 
                        {return 4*sizeof(int);}
  virtual unsigned   hash() const;
  virtual RWBoolean  isEqual(const RWCollectable*) const;
  virtual void       restoreGuts(RWvistream& s);
  virtual void       restoreGuts(RWFile&);
  virtual void       saveGuts(RWvostream& s) const;
  virtual void       saveGuts(RWFile&) const;

private:

  RECT  bounds;                    // The bounds of the rectangle
};

An Excerpt from SHAPES.CPP

For the purposes of this DLL demo, it really isn't necessary to provide definitions for any of the member functions inherited from RWCollectable, but let's do it anyway, for the sake of completeness.

#include "shapes.h"
#include <rw/vstream.h>
#include <rw/rwfile.h>

RWDEFINE_COLLECTABLE(RWRectangle, 0x1000)                    //1

// Constructor
RWRectangle::RWRectangle(int l, int t, int r, int b)         //2
{
   bounds.left   = l;
   bounds.top    = t;
   bounds.right  = r;
   bounds.bottom = b;
}

// Inherited from Drawable:
void
RWRectangle::drawWith(HDC hdc) const                         //3
{
   // Make the Windows call:
   Rectangle(hdc, bounds.left, bounds.top,
             bounds.right, bounds.bottom);
}

// Inherited from RWCollectable:
unsigned
RWRectangle::hash() const                                    //4
{
  return bounds.left ^ bounds.top ^ bounds.bottom ^ bounds.right;
}


RWBoolean
RWRectangle::isEqual(const RWCollectable* c) const           //5
{
   if(c->isA() != isA() ) return FALSE;

   const RWRectangle* r = (const RWRectangle*)c;

   return   bounds.left   == r->bounds.left  &&
            bounds.top    == r->bounds.top   &&
            bounds.right  == r->bounds.right &&
            bounds.bottom == r->bounds.bottom;
}

// Restore the RWRectangle from a virtual stream:
void
RWRectangle::restoreGuts(RWvistream& s)                      //6
{
   s >> bounds.left  >> bounds.top;
   s >> bounds.right >> bounds.bottom;
}

// Restore from an RWFile:
void
RWRectangle::restoreGuts(RWFile& f)                          //7
{
   f.Read(bounds.left);
   f.Read(bounds.top);
   f.Read(bounds.right);
   f.Read(bounds.bottom);
}

void
RWRectangle::saveGuts(RWvostream& s) const                   //8
{
   s << bounds.left  << bounds.top;
   s << bounds.right << bounds.bottom;
}

void
RWRectangle::saveGuts(RWFile& f) const                       //9
{
   f.Write(bounds.left);
   f.Write(bounds.top);
   f.Write(bounds.right);
   f.Write(bounds.bottom);
}

//1	This is a macro that all subclasses of RWCollectable are required to compile once, and only once. See Chapter 15 (How to Create an RWCollectable..) for more details.
//2	This is the constructor for RWRectangle that fills in the `RECT` structure.
//3	This is the definition of the virtual function `drawWith(HDC)`. It simply makes a call to the Windows function `Rectangle()` with appropriate arguments.
//4	Supplies an appropriate hashing value in case we ever want to retrieve this RWRectangle from a hash table.
//5	Supplies an appropriate `isEqual()` implementation.
//6	This function retrieves the RWRectangle from a virtual stream.
//7	This function retrieves the RWRectangle from an RWFile.
//8	This function stores the RWRectangle on a virtual stream. Note how there is no need to separate elements by white space_this will be done by the virtual stream, if necessary.
//9	This function stores the RWRectangle on an RWFile.

The other shapes, RWEllipse and RWText, are implemented in a similar manner.