CStatic Class

Article
06/05/2017

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at CStatic Class.

Provides the functionality of a Windows static control.

Syntax

class CStatic : public CWnd

Members

Public Constructors

Name	Description
CStatic::CStatic	Constructs a `CStatic` object.

Public Methods

Name	Description
CStatic::Create	Creates the Windows static control and attaches it to the `CStatic` object.
CStatic::DrawItem	Override to draw an owner-drawn static control.
CStatic::GetBitmap	Retrieves the handle of the bitmap previously set with SetBitmap.
CStatic::GetCursor	Retrieves the handle of the cursor image previously set with SetCursor.
CStatic::GetEnhMetaFile	Retrieves the handle of the enhanced metafile previously set with SetEnhMetaFile.
CStatic::GetIcon	Retrieves the handle of the icon previously set with SetIcon.
CStatic::SetBitmap	Specifies a bitmap to be displayed in the static control.
CStatic::SetCursor	Specifies a cursor image to be displayed in the static control.
CStatic::SetEnhMetaFile	Specifies an enhanced metafile to be displayed in the static control.
CStatic::SetIcon	Specifies an icon to be displayed in the static control.

Remarks

A static control displays a text string, box, rectangle, icon, cursor, bitmap, or enhanced metafile. It can be used to label, box, or separate other controls. A static control normally takes no input and provides no output; however, it can notify its parent of mouse clicks if it's created with SS_NOTIFY style.

Create a static control in two steps. First, call the constructor to construct the CStatic object, then call the Create member function to create the static control and attach it to the CStatic object.

If you create a CStatic object within a dialog box (through a dialog resource), the CStatic object is automatically destroyed when the user closes the dialog box.

If you create a CStatic object within a window, you may also need to destroy it. A CStatic object created on the stack within a window is automatically destroyed. If you create the CStatic object on the heap by using the new function, you must call delete on the object to destroy it when you are done with it.

Inheritance Hierarchy

CObject

CCmdTarget

CWnd

CStatic

Requirements

Header: afxwin.h

CStatic::Create

Creates the Windows static control and attaches it to the CStatic object.

virtual BOOL Create(
    LPCTSTR lpszText,  
    DWORD dwStyle,  
    const RECT& rect,  
    CWnd* pParentWnd,  
    UINT nID = 0xffff);

Parameters

lpszText
Specifies the text to place in the control. If NULL, no text will be visible.

dwStyle
Specifies the static control's window style. Apply any combination of static control styles to the control.

rect
Specifies the position and size of the static control. It can be either a RECT structure or a CRect object.

pParentWnd
Specifies the CStatic parent window, usually a CDialog object. It must not be NULL.

nID
Specifies the static control's control ID.

Return Value

Nonzero if successful; otherwise 0.

Remarks

Construct a CStatic object in two steps. First, call the constructor CStatic, and then call Create, which creates the Windows static control and attaches it to the CStatic object.

Apply the following window styles to a static control:

WS_CHILD Always
WS_VISIBLE Usually
WS_DISABLED Rarely

If you're going to display a bitmap, cursor, icon, or metafile in the static control, you'll need to apply one of the following static styles:

SS_BITMAP Use this style for bitmaps.
SS_ICON Use this style for cursors and icons.
SS_ENHMETAFILE Use this style for enhanced metafiles.

For cursors, bitmaps, or icons, you may also want to use the following style:

SS_CENTERIMAGE Use to center the image in the static control.

Example

      // This code can be placed in OnInitDialog 
      CStatic myStatic;

      // Create a child static control that centers its text horizontally.
      myStatic.Create(_T("my static"), WS_CHILD|WS_VISIBLE|SS_CENTER, 
         CRect(10,10,150,50), pParentWnd);

CStatic::CStatic

Constructs a CStatic object.

CStatic();

Example

      // Create a static object on the stack.
      CStatic myStatic;

      // Create a static object on the heap.
      CStatic* pmyStatic = new CStatic;

CStatic::DrawItem

Called by the framework to draw an owner-drawn static control.

virtual void DrawItem(LPDRAWITEMSTRUCT lpDrawItemStruct);

Parameters

lpDrawItemStruct
A pointer to a DRAWITEMSTRUCT structure. The structure contains information about the item to be drawn and the type of drawing required.

Remarks

Override this function to implement drawing for an owner-drawn CStatic object (the control has the style SS_OWNERDRAW).

CStatic::GetBitmap

Gets the handle of the bitmap, previously set with SetBitmap, that is associated with CStatic.

HBITMAP GetBitmap() const;

Return Value

A handle to the current bitmap, or NULL if no bitmap has been set.

Example

  // Code such as this could be placed in the OnInitDialog callback.
  // It creates two bitmap static controls on the heap, using members
  // _m_pCStatic_A and _m_pCStatic_B to identify them so that they can
  // be destroyed when no longer needed.

    CBitmap CBmp;
    CImage CImg;

    // Create a child bitmap static control and load it from a CBitmap object.
    _m_pCStatic_A = new CStatic;
    _m_pCStatic_A->Create(_T("A bitmap static control (A)"), 
        WS_CHILD|WS_BORDER|WS_VISIBLE|SS_BITMAP|SS_CENTERIMAGE, CRect(16,16,64,64),
        pParentWnd);
    CBmp.LoadOEMBitmap(OBM_CLOSE);  // Loads one of the default Windows bitmaps
    _m_pCStatic_A->SetBitmap( HBITMAP(CBmp) );
    _m_pCStatic_A->ShowWindow( SW_SHOW );

    // Create a child bitmap static control and load it from a CImage object.
    _m_pCStatic_B = new CStatic;
    _m_pCStatic_B->Create(_T("A bitmap static control (B)"), 
        WS_CHILD|WS_BORDER|WS_VISIBLE|SS_BITMAP|SS_CENTERIMAGE, CRect(90,16,138,64),
        pParentWnd);
    CImg.Load( _T("test.png") );
    if( _m_pCStatic_B->GetBitmap( ) == NULL )
      _m_pCStatic_B->SetBitmap( HBITMAP(CImg) );

    /* Then, later: 
     delete( _m_pCStatic_A );
     delete( _m_pCStatic_B );
     */

CStatic::GetCursor

Gets the handle of the cursor, previously set with SetCursor, that is associated with CStatic.

HCURSOR GetCursor();

Return Value

A handle to the current cursor, or NULL if no cursor has been set.

Example

      CStatic myStatic;

      // Create a child icon static control.
      myStatic.Create(_T("my static"), 
         WS_CHILD|WS_VISIBLE|SS_ICON|SS_CENTERIMAGE, CRect(10,10,150,50), 
         pParentWnd);

      // If no image is defined for the static control, define the image 
      // to the system arrow and question mark cursor.
      if (myStatic.GetCursor() == NULL)
         myStatic.SetCursor(::LoadCursor(NULL, IDC_HELP));

CStatic::GetEnhMetaFile

Gets the handle of the enhanced metafile, previously set with SetEnhMetafile, that is associated with CStatic.

HENHMETAFILE GetEnhMetaFile() const;

Return Value

A handle to the current enhanced metafile, or NULL if no enhanced metafile has been set.

Example

      CStatic myStatic;

      // Create a child enhanced metafile static control.
      myStatic.Create(_T("my static"), 
         WS_CHILD|WS_VISIBLE|SS_ENHMETAFILE|SS_CENTERIMAGE, 
         CRect(10,10,150,50), pParentWnd);

      // If no image is defined for the static control, define the image 
      // to be "myemf.emf."
      if (myStatic.GetEnhMetaFile() == NULL)
         myStatic.SetEnhMetaFile(::GetEnhMetaFile(_T("myemf.emf")));

CStatic::GetIcon

Gets the handle of the icon, previously set with SetIcon, that is associated with CStatic.

HICON GetIcon() const;

Return Value

A handle to the current icon, or NULL if no icon has been set.

Example

      CStatic myStatic;

      // Create a child icon static control.
      myStatic.Create(_T("my static"), 
         WS_CHILD|WS_VISIBLE|SS_ICON|SS_CENTERIMAGE, CRect(10,10,150,50), 
         pParentWnd);

      // If no icon is defined for the static control, define the icon 
      // to the system error icon.
      if (myStatic.GetIcon() == NULL)
         myStatic.SetIcon(::LoadIcon(NULL, IDI_ERROR));

CStatic::SetBitmap

Associates a new bitmap with the static control.

HBITMAP SetBitmap(HBITMAP hBitmap);

Parameters

hBitmap
Handle of the bitmap to be drawn in the static control.

Return Value

The handle of the bitmap that was previously associated with the static control, or NULL if no bitmap was associated with the static control.

Remarks

The bitmap will be automatically drawn in the static control. By default, it will be drawn in the upper-left corner and the static control will be resized to the size of the bitmap.

You can use various window and static control styles, including these:

SS_BITMAP Use this style always for bitmaps.
SS_CENTERIMAGE Use to center the image in the static control. If the image is larger than the static control, it will be clipped. If it is smaller than the static control, the empty space around the image will be filled by the color of the pixel in the upper left corner of the bitmap.
MFC provides the class CBitmap, which you can use when you have to do more with a bitmap image than just call the Win32 function LoadBitmap. CBitmap, which contains one kind of GDI object, is often used in cooperation with CStatic, which is a CWnd class that is used for displaying a graphic object as a static control.

CImage is an ATL/MFC class that lets you more easily work with device independent bitmaps (DIB). For more information, see CImage Class.

Typical usage is to give CStatic::SetBitmap a GDI object that is returned by the HBITMAP operator of a CBitmap or CImage object. The code to do this resembles the following line.

MyStaticControl.SetBitmap(HBITMAP(MyBitmap));

The following example creates two CStatic objects on the heap. It then loads one with a system bitmap using CBitmap::LoadOEMBitmap and the other from a file using CImage::Load.

Example

  // Code such as this could be placed in the OnInitDialog callback.
  // It creates two bitmap static controls on the heap, using members
  // _m_pCStatic_A and _m_pCStatic_B to identify them so that they can
  // be destroyed when no longer needed.

    CBitmap CBmp;
    CImage CImg;

    // Create a child bitmap static control and load it from a CBitmap object.
    _m_pCStatic_A = new CStatic;
    _m_pCStatic_A->Create(_T("A bitmap static control (A)"), 
        WS_CHILD|WS_BORDER|WS_VISIBLE|SS_BITMAP|SS_CENTERIMAGE, CRect(16,16,64,64),
        pParentWnd);
    CBmp.LoadOEMBitmap(OBM_CLOSE);  // Loads one of the default Windows bitmaps
    _m_pCStatic_A->SetBitmap( HBITMAP(CBmp) );
    _m_pCStatic_A->ShowWindow( SW_SHOW );

    // Create a child bitmap static control and load it from a CImage object.
    _m_pCStatic_B = new CStatic;
    _m_pCStatic_B->Create(_T("A bitmap static control (B)"), 
        WS_CHILD|WS_BORDER|WS_VISIBLE|SS_BITMAP|SS_CENTERIMAGE, CRect(90,16,138,64),
        pParentWnd);
    CImg.Load( _T("test.png") );
    if( _m_pCStatic_B->GetBitmap( ) == NULL )
      _m_pCStatic_B->SetBitmap( HBITMAP(CImg) );

    /* Then, later: 
     delete( _m_pCStatic_A );
     delete( _m_pCStatic_B );
     */

CStatic::SetCursor

Associates a new cursor image with the static control.

HCURSOR SetCursor(HCURSOR hCursor);

Parameters

hCursor
Handle of the cursor to be drawn in the static control.

Return Value

The handle of the cursor previously associated with the static control, or NULL if no cursor was associated with the static control.

Remarks

The cursor will be automatically drawn in the static control. By default, it will be drawn in the upper-left corner and the static control will be resized to the size of the cursor.

You can use various window and static control styles, including the following:

SS_ICON Use this style always for cursors and icons.
SS_CENTERIMAGE Use to center in the static control. If the image is larger than the static control, it will be clipped. If it is smaller than the static control, the empty space around the image will be filled with the background color of the static control.

Example

      CStatic myStatic;

      // Create a child icon static control.
      myStatic.Create(_T("my static"), 
         WS_CHILD|WS_VISIBLE|SS_ICON|SS_CENTERIMAGE, CRect(10,10,150,50), 
         pParentWnd);

      // If no image is defined for the static control, define the image 
      // to the system arrow and question mark cursor.
      if (myStatic.GetCursor() == NULL)
         myStatic.SetCursor(::LoadCursor(NULL, IDC_HELP));

CStatic::SetEnhMetaFile

Associates a new enhanced metafile image with the static control.

HENHMETAFILE SetEnhMetaFile(HENHMETAFILE hMetaFile);

Parameters

hMetaFile
Handle of the enhanced metafile to be drawn in the static control.

Return Value

The handle of the enhanced metafile previously associated with the static control, or NULL if no enhanced metafile was associated with the static control.

Remarks

The enhanced metafile will be automatically drawn in the static control. The enhanced metafile is scaled to fit the size of the static control.

You can use various window and static control styles, including the following:

SS_ENHMETAFILE Use this style always for enhanced metafiles.

Example

      CStatic myStatic;

      // Create a child enhanced metafile static control.
      myStatic.Create(_T("my static"), 
         WS_CHILD|WS_VISIBLE|SS_ENHMETAFILE|SS_CENTERIMAGE, 
         CRect(10,10,150,50), pParentWnd);

      // If no image is defined for the static control, define the image 
      // to be "myemf.emf."
      if (myStatic.GetEnhMetaFile() == NULL)
         myStatic.SetEnhMetaFile(::GetEnhMetaFile(_T("myemf.emf")));

CStatic::SetIcon

Associates a new icon image with the static control.

HICON SetIcon(HICON hIcon);

Parameters

hIcon
Handle of the icon to be drawn in the static control.

Return Value

The handle of the icon previously associated with the static control, or NULL if no icon was associated with the static control.

Remarks

The icon will be automatically drawn in the static control. By default, it will be drawn in the upper-left corner and the static control will be resized to the size of the icon.

You can use various window and static control styles, including the following:

SS_ICON Use this style always for cursors and icons.
SS_CENTERIMAGE Use to center in the static control. If the image is larger than the static control, it will be clipped. If it is smaller than the static control, the empty space around the image will be filled with the background color of the static control.

Example

      CStatic myStatic;

      // Create a child icon static control.
      myStatic.Create(_T("my static"), 
         WS_CHILD|WS_VISIBLE|SS_ICON|SS_CENTERIMAGE, CRect(10,10,150,50), 
         pParentWnd);

      // If no icon is defined for the static control, define the icon 
      // to the system error icon.
      if (myStatic.GetIcon() == NULL)
         myStatic.SetIcon(::LoadIcon(NULL, IDI_ERROR));

Share via

CStatic Class

Syntax

Members

Public Constructors

Public Methods

Remarks

Inheritance Hierarchy

Requirements

CStatic::Create

Parameters

Return Value

Remarks

Example

CStatic::CStatic

Example

CStatic::DrawItem

Parameters

Remarks

CStatic::GetBitmap

Return Value

Example

CStatic::GetCursor

Return Value

Example

CStatic::GetEnhMetaFile

Return Value

Example

CStatic::GetIcon

Return Value

Example

CStatic::SetBitmap

Parameters

Return Value

Remarks

Example

CStatic::SetCursor

Parameters

Return Value

Remarks

Example

CStatic::SetEnhMetaFile

Parameters

Return Value

Remarks

Example

CStatic::SetIcon

Parameters

Return Value

Remarks

Example

See Also

Additional resources