Static Controls

  • Article

 

Kyle Marsh
Microsoft Corporation

March 20, 1992

Abstract

Static controls are child windows used in Microsoft® Windows™-based applications to display text, to draw frames or lines separating other controls, or to display icons. Static controls do not accept user input and do not send notification messages to their parent windows. This article describes how developers can define different types of static controls and can use text styles, frame styles, and rectangle styles to modify the appearance of these controls.

Introduction

Static controls are used to display text, to draw frames and rectangles, and to display icons. Despite the name static, the information in a static control can be changed while the control exists. For example, an application can use a static control to display the amount of disk space that it is using. A static control is a good choice for this information because the user cannot change the amount of disk space used without performing some other operation. When the user performs another operation, such as deleting a file, the application updates the amount of disk space used.

The application can change the information within a static control by sending a WM_SETTEXT message to the control. If the static control displays text, a pointer to the text must be sent in the lParam of the SendMessage function (or of the SetDlgItemText function if the control is in a dialog box). In the Microsoft® Windows™ version 3.1 graphical environment, a static control that displays an icon can change it by sending an STM_SETICON message to the control with a handle to an icon resource (HICON) in the wParam of SendMessage. An application obtains the handle to the icon by calling LoadIcon. Static controls that do not display text or icons have no user-supplied information to change, so a WM_SETTEXT message sent to the static control will be ignored.

Static controls might be called "no input controls" because they accept no input from the user. If the user moves the mouse over a static control, Windows sends the control a WM_NCHITTEST message. The static control returns an HTTRANSPARENT value to Windows, which then sends the WM_NCHITTEST message to the static control's parent window. As a result of this processing, the parent window of the static control receives all mouse events. Static controls do not provide any notifications to their parent windows; in other words, they do not send any WM_COMMAND messages.

Control styles for the static class include text styles, frame styles, rectangle styles, and an icon style.

Text Styles and Modifiers

The five basic text styles for static controls are:

  • SS_RIGHT
  • SS_LEFT
  • SS_CENTER
  • SS_LEFTNOWORDWRAP
  • SS_SIMPLE

The SS_NOPREFIX style can modify a static control that has any of these text styles. Although SS_NOPREFIX is called a style, it is really a modifier to the text styles.

SS_NOPREFIX

SS_NOPREFIX instructs the static control not to interpret an ampersand (&) character in a text string as a prefix character for the keyboard access key. The static control normally removes an ampersand in a text string and underlines the following character; the control displays two ampersands (&&) as a single ampersand. When SS_NOPREFIX is used, the static control displays an ampersand as an ordinary character. To modify a text style with the SS_NOPREFIX modifier, you combine the text style with SS_NOPREFIX using the bitwise OR operator; for example, in a resource script file:

CONTROL   "Sample &Text", 104, "Static", SS_LEFT | SS_NOPREFIX, 33,
           91, 94, 13

or

LTEXT   "This is Left Text with No &Prefix", 104, 33, 91, 94, 13,
         SS_NOPREFIX

SS_RIGHT

The SS_RIGHT text-style static control defines an area that displays the given text. The application determines the size of the control. The control formats the text before it is displayed. When a word extends past the end of the control, the word automatically wraps to the next line. All displayed text is right justified. If the control is too small to display the text after it has been word wrapped, only the text within the size of the control is visible. An RTEXT statement in a dialog box resource file creates this static control:

RTEXT   "This is Right Text", 101, 33, 22, 94, 13

SS_LEFT

The SS_LEFT text-style static control defines an area that displays the given text. The application determines the size of the control. The control formats the text before it is displayed. When a word extends past the end of the control, the word automatically wraps to the next line. All displayed text is left justified. If the control is too small to display the text after it has been word wrapped, only the text within the size of the control is visible. An LTEXT statement in a dialog box resource file creates this static control:

LTEXT   "This is Left Text", 101, 33, 22, 94, 13

SS_CENTER

The SS_CENTER text-style static control defines an area that displays the given text. The application determines the size of the control. The control formats the text before it is displayed. When a word extends past the end of the control, the word automatically wraps to the next line. All displayed text is centered. If the control is too small to display the text after it has been word wrapped, only the text within the size of the control is visible. A CTEXT statement in a dialog box resource file creates this static control:

CTEXT   "This is Centered Text", 101, 33, 22, 94, 13

SS_LEFTNOWORDWRAP

The SS_LEFTNOWORDWRAP text-style static control defines an area that displays the given text. The application determines the size of the control. The control formats the text before it is displayed. Words that extend past the end of the control are clipped; no word wrapping is done, and the text is left justified. A CONTROL statement in a dialog box resource file creates this static control:

CONTROL   "This is Left Text", 104, "Static", 
           SS_LEFTNOWORDWRAP, 33, 91, 94, 13

SS_SIMPLE

SS_SIMPLE displays text faster than the other static text-style controls because it uses TextOut rather than DrawText to display text. The text that an SS_SIMPLE static control displays is opaque and is clipped to the size of the control. The following conditions must be met for SS_SIMPLE controls to work correctly:

  1. The text must be on one line and should fit within the control. If the text does not fit within the control, it is clipped.
  2. The control must never be disabled. SS_SIMPLE static controls do not check to see whether the control is disabled. Text is never grayed.
  3. The text must never be changed to a shorter string. SS_SIMPLE static controls do not clear the control's display area when displaying text. If a shorter string is displayed, the part of the original string that is longer than the new shorter string is displayed.
  4. The parent window must not respond to a WM_CTLCOLOR message. An SS_SIMPLE control always uses the system colors Window (COLOR_WINDOW) and Window Text (COLOR_WINDOWTEXT) for its window and text regardless of what the control's parent window wants.

When SS_SIMPLE is combined with SS_NOPREFIX, the control uses ExtTextOut to display text. Because ExtTextOut clears the control and displays the new text in one fast operation, the text of an SS_SIMPLE | SS_NOPREFIX static control can be changed with minimal visible flicker, and the new text string can be shorter than the original string.

A CONTROL statement in a dialog box resource file creates this static control:

CONTROL   "Simple Text", 104, "Static", SS_SIMPLE, 33, 91, 94, 13

Frame Styles

Static controls can be used to draw frames (boxes that are not filled). Frame-style static controls do not display text. The three frame-style static controls are:

  • SS_BLACKFRAME
  • SS_WHITEFRAME
  • SS_GRAYFRAME

SS_BLACKFRAME

The SS_BLACKFRAME static control displays a frame around the control that is the same color as the Window Frame (COLOR_WINDOWFRAME). The default Windows color is black. The user can change the color by changing the window frame color in the Control Panel, or an application can call SetSysColors. A CONTROL statement in a dialog box resource file creates this static control:

CONTROL   "", 104, "Static", SS_BLACKFRAME, 33, 91, 94, 13

SS_WHITEFRAME

The SS_WHITEFRAME static control displays a frame around the control that is the same color as the Window (COLOR_WINDOW). The default Windows color is white. The user can change the color by changing the window color in the Control Panel, or an application can call SetSysColors. A CONTROL statement in a dialog box resource file creates this static control:

CONTROL   "", 104, "Static", SS_WHITEFRAME, 33, 91, 94, 13

SS_GRAYFRAME

The SS_GRAYFRAME static control displays a frame around the control that is the same color as the Desktop, the screen background (COLOR_BACKGROUND). The default Windows color is gray. The user can change the color by changing the desktop color in the Control Panel, or an application can call SetSysColors. A CONTROL statement in a dialog box resource file creates this static control:

CONTROL   "", 104, "Static", SS_GRAYFRAME, 33, 91, 94, 13

Rectangle Styles

Static controls can be used to draw rectangles (boxes that are filled). Rectangle-style static controls do not display text. The three rectangle-style static controls are:

  • SS_BLACKRECT
  • SS_WHITERECT
  • SS_GRAYRECT

SS_BLACKRECT

The SS_BLACKRECT static control displays a frame around the control and fills the control with a solid color that is the same color as the Window Frame (COLOR_WINDOWFRAME). The default Windows color is black. The user can change the color by changing the window frame color in the Control Panel, or an application can call SetSysColors. A CONTROL statement in a dialog box resource file creates this static control:

CONTROL   "", 104, "Static", SS_BLACKRECT, 33, 91, 94, 13

SS_WHITERECT

The SS_WHITERECT static control displays a frame around the control and fills the control with a solid color that is the same color as the Window (COLOR_WINDOW). The default Windows color is white. The user can change the color by changing the window color in the Control Panel, or an application can call SetSysColors. A CONTROL statement in a dialog box resource file creates this static control:

CONTROL   "", 104, "Static", SS_WHITERECT, 33, 91, 94, 13

SS_GRAYRECT

The SS_GRAYRECT static control displays a frame around the control and fills the control with a solid color that is the same color as the Desktop (COLOR_BACKGROUND). The default Windows color is gray. The user can change the color by changing the desktop color in the Control Panel, or an application can call SetSysColors. A CONTROL statement in a dialog box resource file creates this static control:

CONTROL   "", 104, "Static", SS_GRAYRECT, 33, 91, 94, 13

Icon Styles

Static controls can be used to display icons by using the SS_ICON style. Icon-style static controls are sized to fit the icon when it is displayed; the width and height that the application specifies are ignored. When defining an SS_ICON static control in a resource file, the icon must be defined elsewhere in the resource file, and the icon resource name must be specified as the text for the control. The icon name cannot be a file name. An ICON statement in a resource script file creates this static control:

SampleIcon   ICON  sample.ico
ICON   "SampleIcon", 104, 33, 91, 94, 13

In Windows version 3.1, an application can change the icon displayed by an SS_ICON static control. An application can send the STM_SETICON message to an SS_ICON control with a handle to an icon (HICON) in the wParam. SendMessage returns the handle to the previously displayed icon. The Windows version 3.1 STM_GETICON message causes SendMessage to return the handle to the currently displayed icon when sent to an SS_ICON static control.