Win32 Series - Becoming a Clipboard Viewer

http://www-user.tu-chemnitz.de/~heha/petzold/

 

 

Becoming a Clipboard Viewer

A program that is notified of changes in the clipboard contents is called a "clipboard  viewer." You get a clipboard viewer with Windows, but you can also write your own  clipboard viewer program. Clipboard viewers are notified of changes to the clipboard through  messages to the viewer's window procedure.

The Clipboard Viewer Chain

Any number of clipboard viewer applications can be running in Windows at the same  time, and they can all be notified of changes to the clipboard. From Windows'  perspective, however, there is only one clipboard viewer, which I'll call the "current clipboard  viewer." Windows maintains only one window handle to identify the current clipboard viewer,  and it sends messages only to that window when the contents of the clipboard change.

Clipboard viewer applications have the responsibility of participating in the  "clipboard viewer chain" so that all running clipboard viewer programs receive the messages  that Windows sends to the current clipboard viewer. When a program registers itself as a  clipboard viewer, that program becomes the current clipboard viewer. Windows gives  that program the window handle of the previous current clipboard viewer, and the  program saves this handle. When the program receives a clipboard viewer message, it sends  that message to the window procedure of the next program in the clipboard chain.

Clipboard Viewer Functions and Messages

A program can become part of the clipboard viewer chain by calling the  SetClipboardViewer function. If the primary purpose of the program is to serve as a clipboard viewer, the  program can call this function during processing of the WM_CREATE message. The  function returns the window handle of the previous current clipboard viewer. The program  should save that handle in a static variable:

static HWND hwndNextViewer ;[other program lines]case WM_CREATE :     [other program lines]     hwndNextViewer = SetClipboardViewer (hwnd) ;

If your program is the first program to become a clipboard viewer during the  Windows session, thenhwndNextViewer will be NULL.

Windows sends a WM_DRAWCLIPBOARD message to the current clipboard  viewer (the most recent window to register itself as a clipboard viewer) whenever the  contents of the clipboard change. Each program in the clipboard viewer chain should use SendMessage to pass this message to the next clipboard viewer. The last program in the clipboard  viewer chain (the first window to register itself as a clipboard viewer) will have stored a  NULLhwndNextViewer value. If hwndNextViewer is NULL, the program simply returns  without sending the message to another program. (Don't confuse the WM_DRAWCLIPBOARD  and WM_PAINTCLIPBOARD messages. The WM_PAINTCLIPBOARD message is sent by a  clipboard viewer to programs that use the CF_OWNERDISPLAY clipboard format.  The WM_ DRAWCLIPBOARD message is sent by Windows to the current clipboard viewer.)

The easiest way to process the WM_DRAWCLIPBOARD message is to send the  message to the next clipboard viewer (unless hwndNextViewer is NULL) and invalidate the  client area of your window:

case WM_DRAWCLIPBOARD :     if (hwndNextViewer)          SendMessage (hwndNextViewer, message, wParam, lParam) ;     InvalidateRect (hwnd, NULL, TRUE) ;     return 0 ;

During processing of the WM_PAINT message, you can read the contents of the  clipboard by using the normalOpenClipboard, GetClipboardData, andCloseClipboard calls.

When a program wants to remove itself from the clipboard viewer chain, it must  callChangeClipboardChain. This function requires the window handle of the program  leaving the viewer chain and the window handle of the next clipboard viewer:

ChangeClipboardChain (hwnd, hwndNextViewer) ;

When a program calls  ChangeClipboardChain, Windows sends a  WM_CHANGECBCHAIN message to the current clipboard viewer. The wParam parameter is the handle of the window removing itself from the chain (that is, the first parameter to ChangeClipboardChain), and lParam is the window handle of the next clipboard viewer after the one  removing itself from the chain (the second argument to ChangeClipboardChain).

When your program receives a WM_CHANGECBCHAIN message, you must  therefore check to see ifwParam is equal to the value of hwndNextViewer that you've saved. If it is, your program must set hwndNextViewer tolParam. This action ensures that any  future WM_DRAWCLIPBOARD messages you get won't be sent to the window removing itself  from the clipboard viewer chain. IfwParam isn't equal to hwndNextViewer andhwndNextViewer isn't NULL, send the message to the next clipboard viewer:

case WM_CHANGECBCHAIN :     if ((HWND) wParam == hwndNextViewer)          hwndNextViewer = (HWND) lParam ;     else if (hwndNextViewer)          SendMessage (hwndNextViewer, message, wParam, lParam) ;     return 0 ;

You shouldn't really need to include the else  if statement, which checks hwndNextViewer for a non-NULL value. A NULL hwndNextViewer value would indicate that the  program executing this code is the last viewer on the chain, in which case the message should  never have gotten this far.

If your program is still in the clipboard viewer chain when it is about to  terminate, you must remove it from the chain. You can do this during processing of the  WM_DESTROY message by calling ChangeClipboardChain:

case WM_DESTROY :     ChangeClipboardChain (hwnd, hwndNextViewer) ;     PostQuitMessage (0) ;     return 0 ;

Windows also has a function that allows a program to obtain the window handle  of the first clipboard viewer:

hwndViewer = GetClipboardViewer () ;

This function isn't normally needed. The return value can be NULL if there is no  current clipboard viewer.

Here's an example to illustrate how the clipboard viewer chain works. When  Windows first starts up, the current clipboard viewer is NULL:

 

Current clipboard viewer:NULL

 

A program with a window handle of hwnd1 calls  SetClipboardViewer. The function returns NULL, which becomes the hwndNextViewer value in this program:

 

Current clipboard viewer:hwnd1hwnd1's next viewer:NULL

 

A second program, with a window handle of  hwnd2, now calls SetClipboardViewer and gets back hwnd1:

 

Current clipboard viewer:hwnd2hwnd2's next viewer:hwnd1hwnd1's next viewer:NULL

 

A third program (hwnd3) and then a fourth  (hwnd4) also callSetClipboardViewer and get backhwnd2 andhwnd3:

 

Current clipboard viewer:hwnd4hwnd4's next viewer:hwnd3hwnd3's next viewer:hwnd2hwnd2's next viewer:hwnd1hwnd1's next viewer:NULL

 

When the contents of the clipboard change, Windows sends a  WM_DRAWCLIPBOARD message tohwnd4, hwnd4 sends the message tohwnd3,  hwnd3 sends it tohwnd2, hwnd2 sends it tohwnd1, and  hwnd1 returns.

Now hwnd2 decides to remove itself from the chain by calling

ChangeClipboardChain (hwnd2, hwnd1) ;

Windows sends hwnd4 a WM_CHANGECBCHAIN message with  wParam equal tohwnd2 and lParam equal tohwnd1. Because  hwnd4's next viewer ishwnd3, hwnd4 sends this message tohwnd3. Now  hwnd3 notes thatwParam is equal to its next viewer  (hwnd2), so it sets its next viewer equal to lParam (hwnd1) and returns. The mission is  accomplished. The clipboard viewer chain now looks like this:

 

Current clipboard viewer:hwnd4hwnd4's next viewer:hwnd3hwnd3's next viewer:hwnd1hwnd1's next viewer:NULL

A Simple Clipboard Viewer

Clipboard viewers don't have to be as sophisticated as the one supplied with Windows.  A clipboard viewer can, for instance, display a single clipboard format. The CLIPVIEW  program, shown in Figure 12-2, is a clipboard viewer that displays only the CF_TEXT format.

Figure 12-2. The CLIPVIEW program.

 

CLIPVIEW.C

/*-----------------------------------------   CLIPVIEW.C -- Simple Clipboard Viewer                 (c) Charles Petzold, 1998  -----------------------------------------*/#include <windows.h>LRESULT CALLBACK WndProc (HWND, UINT, WPARAM, LPARAM) ;int WINAPI WinMain (HINSTANCE hInstance, HINSTANCE hPrevInstance,                    PSTR szCmdLine, int iCmdShow){     static TCHAR szAppName[] = TEXT ("ClipView") ;     HWND         hwnd ;     MSG          msg ;     WNDCLASS     wndclass ;          wndclass.style         = CS_HREDRAW | CS_VREDRAW ;     wndclass.lpfnWndProc   = WndProc ;     wndclass.cbClsExtra    = 0 ;     wndclass.cbWndExtra    = 0 ;     wndclass.hInstance     = hInstance ;     wndclass.hIcon         = LoadIcon (NULL, IDI_APPLICATION) ;     wndclass.hCursor       = LoadCursor (NULL, IDC_ARROW) ;     wndclass.hbrBackground = (HBRUSH) GetStockObject (WHITE_BRUSH) ;     wndclass.lpszMenuName  = NULL ;     wndclass.lpszClassName = szAppName ;          if (!RegisterClass (&wndclass))     {          MessageBox (NULL, TEXT ("This program requires Windows NT!"),                      szAppName, MB_ICONERROR) ;          return 0 ;     }          hwnd = CreateWindow (szAppName,                           TEXT ("Simple Clipboard Viewer (Text Only)"),                          WS_OVERLAPPEDWINDOW,                          CW_USEDEFAULT, CW_USEDEFAULT,                          CW_USEDEFAULT, CW_USEDEFAULT,                          NULL, NULL, hInstance, NULL) ;          ShowWindow (hwnd, iCmdShow) ;     UpdateWindow (hwnd) ;          while (GetMessage (&msg, NULL, 0, 0))     {          TranslateMessage (&msg) ;          DispatchMessage (&msg) ;     }     return msg.wParam ;}LRESULT CALLBACK WndProc (HWND hwnd, UINT message, WPARAM wParam, LPARAM lParam){     static HWND hwndNextViewer ;     HGLOBAL     hGlobal ;     HDC         hdc ;     PTSTR       pGlobal ;     PAINTSTRUCT ps ;     RECT        rect ;          switch (message)     {     case WM_CREATE:          hwndNextViewer = SetClipboardViewer (hwnd) ;          return 0 ;               case WM_CHANGECBCHAIN:          if ((HWND) wParam == hwndNextViewer)               hwndNextViewer = (HWND) lParam ;                    else if (hwndNextViewer)               SendMessage (hwndNextViewer, message, wParam, lParam) ;                    return 0 ;               case WM_DRAWCLIPBOARD:          if (hwndNextViewer)               SendMessage (hwndNextViewer, message, wParam, lParam) ;                    InvalidateRect (hwnd, NULL, TRUE) ;          return 0 ;               case WM_PAINT:          hdc = BeginPaint (hwnd, &ps) ;          GetClientRect (hwnd, &rect) ;          OpenClipboard (hwnd) ;          #ifdef UNICODE          hGlobal = GetClipboardData (CF_UNICODETEXT) ;#else          hGlobal = GetClipboardData (CF_TEXT) ;#endif                    if (hGlobal != NULL)          {               pGlobal = (PTSTR) GlobalLock (hGlobal) ;               DrawText (hdc, pGlobal, -1, &rect, DT_EXPANDTABS) ;               GlobalUnlock (hGlobal) ;          }                    CloseClipboard () ;          EndPaint (hwnd, &ps) ;          return 0 ;               case WM_DESTROY:          ChangeClipboardChain (hwnd, hwndNextViewer) ;          PostQuitMessage (0) ;          return 0 ;     }     return DefWindowProc (hwnd, message, wParam, lParam) ;}

 

CLIPVIEW processes WM_CREATE, WM_CHANGECBCHAIN,  WM_DRAWCLIPBOARD, and WM_DESTROY messages as discussed above. The WM_PAINT message simply  opens the clipboard and uses GetClipboardData with a format of CF_TEXT. If the function  returns a global memory handle, CLIPVIEW locks it and uses DrawText to display the text in its client area.

A clipboard viewer that handles data formats beyond the standard formats (as the  one supplied with Windows does) has additional work to do, such as displaying the names  of all the formats currently in the clipboard. You can do this by calling EnumClipboardFormats and obtaining the names of the nonstandard formats from GetClipboardFormatName. A clipboard viewer that uses the CF_OWNERDISPLAY format must send the following  four messages to the clipboard owner to display the data:

 

WM_PAINTCLIPBOARDWM_VSCROLLCLIPBOARDWM_SIZECLIPBOARDWM_HSCROLLCLIPBOARD

 

If you want to write such a clipboard viewer, you have to obtain the window  handle of the clipboard owner using GetClipboardOwner and send that window these  messages when you need to update the clipboard viewer's client area.