Share via


CTabCtrl::GetItem

Retrieves information about a tab in a tab control.

BOOL GetItem( 
  int nItem, 
  TCITEM* pTabCtrlItem  
) const;

Parameters

  • nItem
    Zero-based index of the tab.

  • pTabCtrlItem
    Pointer to a TCITEM structure, used to specify the information to retrieve. Also used to receive information about the tab. This structure is used with the InsertItem, GetItem, and SetItem member functions.

Return Value

Returns TRUE if successful; FALSE otherwise.

Remarks

When the message is sent, the mask member specifies which attributes to return. If the mask member specifies the TCIF_TEXT value, the pszText member must contain the address of the buffer that receives the item text and the cchTextMax member must specify the size of the buffer.

  • mask
    Value specifying which TCITEM structure members to retrieve or set. This member can be zero or a combination of the following values:

    • TCIF_TEXT   The pszText member is valid.

    • TCIF_IMAGE   The iImage member is valid.

    • TCIF_PARAM   The lParam member is valid.

    • TCIF_RTLREADING   The text of pszText is displayed using right-to-left reading order on Hebrew or Arabic systems.

    • TCIF_STATE   The dwState member is valid.

  • pszText
    Pointer to a null-terminated string containing the tab text if the structure contains information about a tab. If the structure is receiving information, this member specifies the address of the buffer that receives the tab text.

  • cchTextMax
    Size of the buffer pointed to by pszText. This member is ignored if the structure is not receiving information.

  • iImage
    Index into the tab control's image list, or – 1 if there is no image for the tab.

  • lParam
    Application-defined data associated with the tab. If there are more than four bytes of application-defined data per tab, an application must define a structure and use it instead of the TCITEM structure. The first member of the application-defined structure must be a TCITEMHEADERstructure. The TCITEMHEADER structure is identical to the TCITEM structure, but without the lParam member. The difference between the size of your structure and the size of the TCITEMHEADER structure should equal the number of extra bytes per tab.

Example

// In this example a CTabCtrl data member, m_TabCtrl, changes the 
// text of the tabs in the tab control.  A call to GetItem is used 
// to get the current text, and then the text is changed.  A call  
// to SetItem is used to update the tab with the new text. 

void CTabDlg::OnChangeItem()
{
   TCITEM tcItem;
   CString pszString;

   //  Get text for the tab item.
   GetDlgItemText(IDC_ITEM_TEXT, pszString);

   //  Get the current tab item text.
   TCHAR buffer[256] = {0};
   tcItem.pszText = buffer;
   tcItem.cchTextMax = 256;
   tcItem.mask = TCIF_TEXT;
   m_TabCtrl.GetItem(0, &tcItem);
   TRACE(_T("Changing item text from %s to %s..."), tcItem.pszText, pszString);

   //  Set the new text for the item.
   tcItem.pszText = pszString.LockBuffer();

   //  Set the item in the tab control.
   m_TabCtrl.SetItem(0, &tcItem);

   pszString.UnlockBuffer();
}

Requirements

Header: afxcmn.h

See Also

Reference

CTabCtrl Class

Hierarchy Chart

CTabCtrl::InsertItem

CTabCtrl::SetItem