Ernest Murphy ernie@surfree.com

October 14 2000 

Get the source code here.

Abstract:
------------------------------------------------------------------------------------------ 

  Splitter bars are a distinctive visual control element that help organize a large amount of information in a window. We now build on the techniques learned in Part I and put them in a dynamic link library. This encapsulates the code and allows it to be reused in any project.

  For simplicity, the splitter class described in the code will only support a vertical splitter bar type. This is to reduce the amount of code and checking our tutorial must explain. In the near future a fully functional control will be released for your use. Source code will be included for the curious. There are currently no plans to document this class beyond application reuse information and this source code.
 

Introduction:
------------------------------------------------------------------------------------------

  The dynamic link library can be a container for reusable code that may be shared across many applications. The drawback is a serious versoning problem if the library is ever updated, but the dll is so useful most developers will overlook this problem.

  An application using our splitter library needs to load it before it can be used. There are two basic loading methods:
 

  An application using our library must know how to use it, to this end both an include file and an object library file (.inc and .lib) should be provided.

Registering the new Window Class
------------------------------------------------------------------------------------------

  Let us first show how we build the library. Every dll contains an export to be run as it is loaded. It may be given various names, let us use DllMain.

  DllMain is passed several parameters, the important ones to us being the instance handle of the library itself, and a "reason" code. There are various events DllMain is called, and the "reason" informs us which event we are responding to.

  When the library is first loaded, the reason is set to DLL_PROCESS_ATTATCH. This is the point where we register our new splitter class. Immediately before the library is unloaded, DllMain is called with reason DLL_PROCESS_DETATCH. This is our chance to unregister the splitter class.

  The splitter window class is a very simple type just requiring a few default items. These include the class name, the cursor handle, the back color, application reuse of course our window message procedure. The class name will define for our client applications what to call our new class. The cursor handle is changed to the system standard IDC_SIZEWE ( <--> ), that is the sole visual element to indicate to the user the splitter is there. The back color is set to be COLOR_BUTTONFACE, a typical parent background color.

  Another important (and specific to controls in a dll) is the style parameter. This should be CS_GLOBALCLASS for the client application to be able to instance our class.  (thanks to Iczelion for pointing this out to me)

  Thus, our DllMain code will be as so:
 

DllMain proc hInst:DWORD, reason:DWORD, reserved1:DWORD     LOCAL wc:WNDCLASSEX     .IF reason==DLL_PROCESS_ATTACH         mov eax, hInst         mov hInstance,eax         ; register a simple window as our splitter bar child window          mov wc.cbSize, SIZEOF WNDCLASSEX         mov wc.style, CS_GLOBALCLASS        ; thanks Izcelion  :-)         mov wc.lpfnWndProc, OFFSET SplitterProc         mov wc.cbWndExtra, SIZEOF DWORD  ; we need a pointer in here         mov eax, hInstance         mov wc.hInstance, eax         mov wc.hbrBackground, COLOR_BTNFACE + 1         mov wc.lpszMenuName, NULL          mov wc.lpszClassName, OFFSET szVSplitterCtrl         xor eax, eax        ; mov eax, NULL         mov wc.hIcon, eax         mov wc.hIconSm, eax         invoke LoadCursor, NULL, IDC_SIZEWE       ; <--> cursor         mov wc.hCursor, eax         invoke RegisterClassEx, addr wc     .ELSEIF reason == DLL_PROCESS_DETACH         ; clean up is just unregistering our dll         invoke UnregisterClass, OFFSET szVSplitterCtrl, hInstance     .endif     mov eax, TRUE        ; signal SUCCESS     ret DllMain Endp

Dummy Export Function
------------------------------------------------------------------------------------------

  In order to get the linker load the dll for us, we need to export a dummy procedure. When the linker catches the reference to this export in the client code, it will provide information to the client .exe that will load the dll as the client starts.

  Note this function does not need to be executed, it just has to exist in the client. Perhaps the best place for it is immediately after the ExitProcess function.
 
 

InitSplitterCtrl PROC     ; dummy proc. Referencing this instruction anywhere in the code     ; will load the lib and register our class     xor eax, eax       ; return OK     ret InitSplitterCtrl ENDP

 

Instance Data
------------------------------------------------------------------------------------------

  Naming the windows class as CLASS is a good term, as one should think of windows in object terms. Each instance of a class takes on a life of it's own, and may well need some custom information. The splitter control needs such information.

  Each splitter must keep track of the parent window it is over, and also track the windows to either side. Each side window is also allowed to set it's minimum width. This data must be somehow associated with each class instance.

  This data will be contained in a SplitterData structure like so:
 

SplitterData        STRUCT     m_hWndParent        DWORD   0     m_hWndLeft          DWORD   0     m_hWndRight         DWORD   0     m_RIGHT_MIN         DWORD   0     m_LEFT_MIN          DWORD   0 SplitterData        ENDS

  The WINCLASSEX structure has a bit of room to add data to a window class instance though the cbWndExtra parameter. MS recommends using as small a structure here as possible because it takes up very valuable GDI resources (64K max). Thus, we only allocate a single dword to use as a pointer to our SplitterData. Upon creation, each splitter creates a bit of heap for SplitterData, and saves a reference to this in the class instance.
 

The Message Loop
------------------------------------------------------------------------------------------

  The main assistance our dll gives us is providing the message loop for this control. It processes the following messages:
 

  If you cannot find the last two messages inside MSDN, that is because I just made them up. They are WM_USER messages, used to pass values to the splitter. These messages are defined as follows:
 

  Here is a portion of the message loop. Some of the code inside the WM_MOUSEMOVE handler has been omitted for clarity since it is very large. Actually, MOUSEMOVE is quite simple, but it does perform a large number of simple additions and subtractions, and the code to calculate the move for the side windows and check minimum widths was omitted here.
 

Assembling the Dynamic Link Library
------------------------------------------------------------------------------------------

  For our library, we need to define our custom window messages. These are defined inside an include file so that any code using our library will play with the same constants.  Also, the dummy exported function is prototyped. Here is the whole include file:
 

;-------------------------------------------------------------------- ; include fle for the Splitter Control Dynamic Link Library ;  ; message                  wparam              lparam ;------------------      ------------------  --------------------- ; WM_SET_PANES_HWND       hWnd of left pane   hWnd of right pane ; ; WM_SET_BORDERS_MIN      min pixle width     min pixle width ;                          of left pane        of right pane ;  ; ;  these messages must be called to set the control's properties ; ; ;-------------------------------------------------------------------- InitSplitterCtrl     proto  WM_BASE             EQU     0 WM_SET_PANES_HWND   EQU     WM_USER + WM_BASE  WM_SET_BORDERS_MIN  EQU     WM_USER + WM_BASE + 1

  The linker will bark at you if you do not a .def (definition) file of exported functions and variables. This is also quite simple for this library:
 

LIBRARY SplitterCtrl EXPORTS InitSplitterCtrl

    This defines the name of the dll, and the sole exported function. By defining the function here, we also eliminate any pesky name "decoration."

  It sure would be nice if Quick Editor had a "Build DLL" setting in it's PROJECT menu, but so far it does not (well, MY copy does) (perhaps I should nudge hutch about this for his next release.) A dll is made at the link stage out of assembled objects, either of these statements will do the trick for you:
 

; for No resources \masm32\bin\Link /DLL /SUBSYSTEM:WINDOWS /DEF:%1.def                  /LIBPATH:c:\masm32\lib %1.obj  ; with resources (an rcrs.rc file compiled to rcrs.obj) \masm32\bin\Link /DLL /SUBSYSTEM:WINDOWS /DEF:%1.def                  /LIBPATH:c:\masm32\lib %1.obj rsrc.obj

Conclusion
-----------------------------------------------------------------------------------------
  Dynamic Link Libraries provide a useful container to write reuseable functions. And when all is done, they don't take all that much more work then writing the code in the first place inside a single application. 

  In part III, we'll go thru how to use our new control.
 

Part I Splitter Bar DLL

Part III Using the Splitter Bar DLL

Part IV Ready for Prime Time
 

home