HOWTO: Draw a Custom Window Caption

ID: Q99046

The information in this article applies to:

Microsoft Win32 Software Development Kit (SDK)
Microsoft Windows Software Development Kit (SDK) 3.1

SUMMARY

Microsoft Windows draws captions in the caption bar (or title bar) for all eligible windows in the system. Applications need to specify only the WS_CAPTION style to take advantage of this facility. The current version of Microsoft Windows, however, imposes three significant restrictions on the captions. An application that does not want to be tied by any of these restrictions may want to draw its own caption. This article lists the restrictions and the steps required to draw a window caption.

These restrictions also apply to Windows NT, but there are a few differences for Windows 95 and Windows 98 .

It is important to note that an application should not draw its own caption unless it has very good reasons to do so. A window caption is a user interface object, and rendering it in ways different from other windows in the system may obstruct the user's conceptual grasp of the Microsoft Windows user interface.

MORE INFORMATION

Windows and Windows NT 3.5x

The three important restrictions imposed by Microsoft Windows version 3.1 and Microsoft Windows NT on the caption for a window are:

It consists of text only; graphics are not allowed.

All text is centered and drawn with the system font.

The length of the displayed caption is limited to 78 characters even when there is space on the caption bar to accommodate extra characters.

An application can essentially render its own caption consisting of any graphic and text with the standard graphics and text primitives by painting on the nonclient area of the window. The application should draw in response to the WM_NCPAINT, WM_NCACTIVATE, WM_SETTEXT, and WM_SYSCOMMAND messages. When processing these messages, an application should first pass on the message to DefWindowProc() for default processing, then render its caption before returning from the message. This ensures that Microsoft Windows can properly draw the nonclient area. Because drawing the caption is part of DefWindowProc()'s nonclient area processing, an application should specify an empty window title to avoid any Windows-initiated drawing in the caption bar. The following steps indicate the computations needed to determine the caption drawing area:

Get the current window's rectangle using GetWindowRect(). This includes client plus nonclient areas and is in screen coordinates.

Get a device context (DC) to the window using GetWindowDC().

Compute the origin and dimensions of the caption bar. One needs to account for the window decorations (frame, border) and window bitmaps (min/max/system boxes). Remember that different window styles will result in different decorations and a different number of min/max/system boxes. Use GetSystemMetrics() to compute the dimensions of the frame, border, and the system bitmap dimensions.

Render the caption within the boundaries of the rectangle computed in step 3. Remember that the user can change the caption bar color any time by using the Control Panel. Some components of the caption, particularly text backgrounds, may need to be changed based on the current caption bar color. Use GetSysColor to determine the current color.

The following code sample draws a left-justified caption for a window (the code sample applies only to the case where the window is active):

Sample Code


   case WM_NCACTIVATE:
      if ((BOOL)wParam == FALSE)
      {
         DefWindowProc( hWnd, message, wParam, lParam );
      // Add code here to draw caption when window is inactive.

         return TRUE;
      }
      // Fall through if wParam == TRUE, i.e., window is active.

      case WM_NCPAINT:
      // Let Windows do what it usually does. Let the window caption
      // be empty to avoid any Windows-initiated caption bar drawing

         DefWindowProc( hWnd, message, wParam, lParam );
         hDC = GetWindowDC( hWnd );
         GetWindowRect( hWnd, (LPRECT)&rc2 );

      // Compute the caption bar's origin. This window has a system box
      // a minimize box, a maximize box, and has a resizeable frame

         x = GetSystemMetrics( SM_CXSIZE ) +
             GetSystemMetrics( SM_CXBORDER ) +
             GetSystemMetrics( SM_CXFRAME );
         y = GetSystemMetrics( SM_CYFRAME );
         rc1.left = x;
         rc1.top = y;

      // 2*x gives twice the bitmap+border+frame size. Since there are
      // only two bitmaps, two borders, and one frame at the end of the
      // caption bar, subtract a frame to account for this.

         rc1.right = rc2.right - rc2.left - 2*x -
                     GetSystemMetrics( SM_CXFRAME );
         rc1.bottom = GetSystemMetrics( SM_CYSIZE );

      // Render the caption. Use the active caption color as the text
      // background.

         SetBkColor( hDC, GetSysColor(COLOR_ACTIVECAPTION) );
         DrawText( hDC, (LPSTR)"Left Justified Caption", -1,
                 (LPRECT)&rc1, DT_LEFT );
        ReleaseDC( hWnd, hDC );
        break;

Windows 95, Windows 98, Windows NT 4.0, and Windows 2000

On these platforms, the text is not centered and the user can choose the Font. In addition, your application might want to monitor the WM_WININICHANGED message, because the user can change titlebar widths, and so forth, dynamically. When this happens, the application should take the new system metrics into account, and force a window redraw.

Additional query words: minimum maximum

Keywords : kbcode kbNTOS kbGrpUser kbWinOS kbWndw
Version : WINDOWS:3.1
Platform : WINDOWS
Issue type : kbhowto