CTabCtrl Classe

Fornece a funcionalidade do controle de guia comum do Windows.

Sintaxe

class CTabCtrl : public CWnd

Membros

Construtores públicos

Métodos públicos

Observações

Um "controle de guia" é análogo aos divisores em um caderno ou às etiquetas em um gabinete de arquivos. Usando um controle de guia, um aplicativo pode definir várias páginas para a mesma área de uma janela ou caixa de diálogo. Cada página consiste em um conjunto de informações ou um grupo de controles que o aplicativo exibe quando o usuário seleciona a guia correspondente. Um tipo especial de controle de guia exibe guias que se parecem com botões. Clicar em um botão deve executar imediatamente um comando em vez de exibir uma página.

Esse controle (e, portanto, a classe CTabCtrl) está disponível apenas para programas executados no Windows 95/98 e Windows NT versão 3.51 e posterior.

Para obter mais informações sobre CTabCtrlo , consulte Controles e uso do CTabCtrl.

Hierarquia de herança

CObject
CCmdTarget
CWnd

CTabCtrl

Requerimentos

Cabeçalho:afxcmn.h

CTabCtrl::AdjustRect

Calcula a área de exibição de um controle de tabulação dado um retângulo de janela ou calcula o retângulo de janela que corresponderia a uma determinada área de exibição.

void AdjustRect(BOOL bLarger,   LPRECT lpRect);

Parâmetros

bLarger
Indica qual operação fazer. Se esse parâmetro for TRUE, lpRect especifica um retângulo de exibição e recebe o retângulo de janela correspondente. Se este parâmetro for FALSE, lpRect especifica um retângulo de janela e recebe o retângulo de exibição correspondente.

lpRect
Ponteiro para uma RECT estrutura que especifica o retângulo dado e recebe o retângulo calculado.

Exemplo

void CTabDlg::OnSize(UINT nType, int cx, int cy)
{
   CDialog::OnSize(nType, cx, cy);

   if (m_TabCtrl.m_hWnd == NULL)
      return; // Return if window is not created yet.

   RECT rect;

   // Get size of dialog window.
   GetClientRect(&rect);

   // Adjust the rectangle to fit the tab control into the
   // dialog's client rectangle.
   m_TabCtrl.AdjustRect(FALSE, &rect);

   // Move the tab control to the new position and size.
   m_TabCtrl.MoveWindow(&rect, TRUE);
}

CTabCtrl::Create

Cria um controle tab e o anexa a uma instância de um CTabCtrl objeto.

virtual BOOL Create(
    DWORD dwStyle,
    const RECT& rect,
    CWnd* pParentWnd,
    UINT nID);

Parâmetros

dwStyle
Especifica o estilo do controle de guia. Aplique qualquer combinação de estilos de controle de guia, descrita no SDK do Windows. Consulte Comentários para obter uma lista de estilos de janela que você também pode aplicar ao controle.

rect
Especifica o tamanho e a posição do controle de guia. Pode ser um CRect objeto ou uma RECT estrutura.

pParentWnd
Especifica a janela pai do controle de guia, geralmente um CDialogarquivo . Não pode ser NULL.

nID
Especifica a ID do controle de guia.

Valor de retorno

TRUE se a inicialização do objeto foi bem-sucedida; caso contrário FALSE.

Observações

Você constrói um CTabCtrl objeto em duas etapas. Primeiro, chame o construtor e, em seguida, chame Create, que cria o controle tab e o anexa ao CTabCtrl objeto.

Além dos estilos de controle de guia, você pode aplicar os seguintes estilos de janela a um controle de guia:

• WS_CHILD: Cria uma janela filho que representa o controle de guia. Não pode ser usado com o estilo WS_POPUP.
• WS_VISIBLE: Cria um controle de guia que é inicialmente visível.
• WS_DISABLED: Cria uma janela inicialmente desativada.
• WS_GROUP: Especifica o primeiro controle de um grupo de controles no qual o usuário pode se mover de um controle para o próximo com as teclas de seta. Todos os controles definidos com o WS_GROUPestilo : após o primeiro controle pertencem ao mesmo grupo. O próximo controle com o WS_GROUPestilo : termina o grupo de estilos e inicia o próximo grupo (ou seja, um grupo termina onde o próximo começa).
• WS_TABSTOP: Especifica um de qualquer número de controles através dos quais o usuário pode se mover usando a tecla TAB. A tecla TAB move o usuário para o próximo controle especificado pelo WS_TABSTOPestilo :.

Para criar um controle de guia com estilos de janela estendidos, chame CTabCtrl::CreateEx em vez de Create.

Exemplo

// Assuming you have a member variable m_TabCtrl, that is a CTabCtrl
// object, you can use the following to create a tab control.

m_TabCtrl.Create(TCS_TABS | TCS_FIXEDWIDTH | WS_CHILD | WS_VISIBLE,
                 rect, this, IDC_MYTAB);

// This creates a tab control with the given styles, and with
// an ID of IDC_MYTAB.

CTabCtrl::CreateEx

Cria um controle (uma janela filho) e o associa ao objeto CTabCtrl.

virtual BOOL CreateEx(
    DWORD dwExStyle,
    DWORD dwStyle,
    const RECT& rect,
    CWnd* pParentWnd,
    UINT nID);

Parâmetros

dwExStyle
Especifica o estilo estendido do controle que está sendo criado. Para obter uma lista de estilos estendidos do Windows, consulte o dwExStyle parâmetro para CreateWindowEx no SDK do Windows.

dwStyle
Especifica o estilo do controle de guia. Aplique qualquer combinação de estilos de controle de guia, descrita no SDK do Windows. Consulte Comentários em Create para obter uma lista de estilos de janela que você também pode aplicar ao controle.

rect
Uma referência a uma RECT estrutura que descreve o tamanho e a posição da janela a ser criada, nas coordenadas do cliente de pParentWnd.

pParentWnd
Um ponteiro para a janela que é o pai do controle.

nID
ID da janela filho do controle.

Valor de retorno

Diferente de zero se for bem-sucedido caso contrário 0.

Observações

Use CreateEx em vez de aplicar estilos estendidos do Create Windows, especificados pelo prefácio WS_EX_de estilo estendido do Windows .

CreateEx cria o controle com os estilos estendidos do Windows especificados pelo dwExStyle. Defina estilos estendidos específicos para um controle usando SetExtendedStyle. Por exemplo, use CreateEx para definir estilos como WS_EX_CONTEXTHELP, mas use SetExtendedStyle para definir estilos como TCS_EX_FLATSEPARATORS. Para obter mais informações, consulte os estilos descritos em Estilos estendidos de controle de guia no SDK do Windows.

CTabCtrl::CTabCtrl

Constrói um objeto CTabCtrl.

CTabCtrl();

CTabCtrl::DeleteAllItems

Remove todos os itens de um controle de guia.

BOOL DeleteAllItems();

Valor de retorno

Diferente de zero se for bem-sucedido; caso contrário, 0.

CTabCtrl::DeleteItem

Remove o item especificado de um controle de guia.

BOOL DeleteItem(int nItem);

Parâmetros

nItem
Valor baseado em zero do item a ser excluído.

Valor de retorno

Diferente de zero se for bem-sucedido; caso contrário, 0.

Exemplo

// This example assumes that there is a CTabCtrl member of the
// CTabDlg class named m_TabCtrl.  On a button handler
// called OnDeleteItem of the dialog box the tab control will
// delete the 0 indexed item.

void CTabDlg::OnDeleteItem()
{
   // Delete the first item in the tab control.
   m_TabCtrl.DeleteItem(0);
}

CTabCtrl::DeselectAll

Redefine itens em um controle de guia, limpando todos os que foram pressionados.

void DeselectAll(BOOL fExcludeFocus);

Parâmetros

fExcludeFocus
Sinalizador que especifica o escopo da desseleção do item. Se esse parâmetro for definido como FALSE, todos os botões de tabulação serão redefinidos. Se estiver definido como TRUE, todos os itens de tabulação, exceto o selecionado no momento, serão redefinidos.

Observações

Esta função de membro implementa o comportamento da mensagem Win32, TCM_DESELECTALL, conforme descrito no SDK do Windows.

CTabCtrl::DrawItem

Chamado pela estrutura quando um aspeto visual de um controle de guia de desenho do proprietário muda.

virtual void DrawItem(LPDRAWITEMSTRUCT lpDrawItemStruct);

Parâmetros

lpDrawItemStruct
Um ponteiro para uma DRAWITEMSTRUCT estrutura que descreve o item a ser pintado.

Observações

O itemAction membro da estrutura define a DRAWITEMSTRUCT ação de desenho a fazer.

Por padrão, essa função de membro não faz nada. Substitua essa função de membro para implementar o desenho de um objeto owner-draw CTabCtrl .

O aplicativo deve restaurar todos os objetos de interface de dispositivo gráfico (GDI) selecionados para o contexto de exibição fornecido antes lpDrawItemStruct que essa função de membro seja encerrada.

CTabCtrl::GetCurFocus

Recupera o índice da guia com o foco atual.

int GetCurFocus() const;

Valor de retorno

O índice baseado em zero da guia com o foco atual.

CTabCtrl::GetCurSel

Recupera a guia atualmente selecionada em um controle de guia.

int GetCurSel() const;

Valor de retorno

Índice baseado em zero da guia selecionada se for bem-sucedido ou -1 se nenhuma guia for selecionada.

CTabCtrl::GetExtendedStyle

Recupera os estilos estendidos que estão atualmente em uso para o controle de guia.

DWORD GetExtendedStyle();

Valor de retorno

Representa os estilos estendidos atualmente em uso para o controle de guia. Esse valor é uma combinação de estilos estendidos de controle de guia, conforme descrito no SDK do Windows.

Observações

Esta função de membro implementa o comportamento da mensagem TCM_GETEXTENDEDSTYLEWin32 , conforme descrito no SDK do Windows.

CTabCtrl::GetImageList

Recupera a lista de imagens associada a um controle de guia.

CImageList* GetImageList() const;

Valor de retorno

Se for bem-sucedido, um ponteiro para a lista de imagens do controle de guia; caso contrário, NULL.

CTabCtrl::GetItem

Recupera informações sobre uma guia em um controle de guia.

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

Parâmetros

nItem
Índice baseado em zero da guia.

pTabCtrlItem
Ponteiro para uma TCITEM estrutura, usado para especificar as informações a serem recuperadas. Também usado para receber informações sobre a guia. Esta estrutura é usada com as InsertItemfunções , GetItem, e SetItem membro.

Valor de retorno

Devolve TRUE se for bem-sucedido; FALSE caso contrário.

Observações

Quando a mensagem é enviada, o mask membro especifica quais atributos retornar. Se o mask membro especificar o TCIF_TEXT valor, o pszText membro deverá conter o endereço do buffer que recebe o texto do item e o cchTextMax membro deverá especificar o tamanho do buffer.

• mask

  Valor especificando quais TCITEM membros da estrutura recuperar ou definir. Este membro pode ser zero ou uma combinação dos seguintes valores:

  • TCIF_TEXT: O pszText membro é válido.
  • TCIF_IMAGE: O iImage membro é válido.
  • TCIF_PARAM: O lParam membro é válido.
  • TCIF_RTLREADING: O texto do é exibido usando a ordem de leitura da pszText direita para a esquerda nos sistemas hebraico ou árabe.
  • TCIF_STATE: O dwState membro é válido.

• pszText

  Ponteiro para uma cadeia de caracteres terminada em nulo que contém o texto da guia se a estrutura contiver informações sobre uma guia. Se a estrutura estiver recebendo informações, esse membro especifica o endereço do buffer que recebe o texto da guia.

• cchTextMax

  Tamanho do buffer apontado por pszText. Este membro é ignorado se a estrutura não estiver recebendo informações.

• iImage Indexe na lista de imagens do controle de guia ou -1 se não houver nenhuma imagem para a guia.

• lParam

  Dados definidos pelo aplicativo associados à guia. Se houver mais de 4 bytes de dados definidos pelo aplicativo por guia, um aplicativo deve definir uma estrutura e usá-la em vez da TCITEM estrutura. O primeiro membro da estrutura definida pelo aplicativo deve ser uma TCITEMHEADER estrutura. A TCITEMHEADER estrutura é idêntica à TCITEM estrutura, mas sem o lParam membro. A diferença entre o tamanho da sua estrutura e o tamanho da TCITEMHEADER estrutura deve ser igual ao número de bytes extras por guia.

Exemplo

// 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();
}

CTabCtrl::GetItemCount

Recupera o número de guias no controle de guia.

int GetItemCount() const;

Valor de retorno

Número de itens no controle de guia.

Exemplo

Veja o exemplo para CPropertySheet::GetTabControl.

CTabCtrl::GetItemRect

Recupera o retângulo delimitador para a guia especificada em um controle de guia.

BOOL GetItemRect(int nItem,   LPRECT lpRect) const;

Parâmetros

nItem
Índice baseado em zero do item da guia.

lpRect
Ponteiro para uma RECT estrutura que recebe o retângulo delimitador da guia. Essas coordenadas usam o modo de mapeamento atual do visor.

Valor de retorno

Diferente de zero se for bem-sucedido; caso contrário, 0.

Exemplo

Veja o exemplo para CPropertySheet::GetTabControl.

CTabCtrl::GetItemState

Recupera o estado do item de controle de guia identificado por nItem.

DWORD GetItemState(
    int nItem,
    DWORD dwMask) const;

Parâmetros

nItem
O número de índice baseado em zero do item para o qual recuperar informações de estado.

dwMask
Máscara especificando quais sinalizadores de estado do item devem ser retornados. Para obter uma lista de valores, consulte o TCITEM membro da máscara da estrutura, conforme descrito no SDK do Windows.

Valor de retorno

Uma referência a um valor DWORD que recebe as informações de estado. Pode ser um dos seguintes valores:

Observações

O estado de um item é especificado pelo dwState membro da TCITEM estrutura.

CTabCtrl::GetRowCount

Recupera o número atual de linhas em um controle de guia.

int GetRowCount() const;

Valor de retorno

O número de linhas de guias no controle de guia.

Observações

Somente os controles de guia que têm o TCS_MULTILINE estilo podem ter várias linhas de guias.

CTabCtrl::GetToolTips

Recupera o identificador do controle de dica de ferramenta associado a um controle de guia.

CToolTipCtrl* GetToolTips() const;

Valor de retorno

Manipule o controle da ponta da ferramenta, se bem-sucedido; caso contrário NULL.

Observações

Um controle tab cria um controle de dica de ferramenta se ele tiver o TCS_TOOLTIPS estilo. Você também pode atribuir um controle de dica de ferramenta a um controle de guia usando a SetToolTips função de membro.

CTabCtrl::HighlightItem

Define o estado de realce de um item de tabulação.

BOOL HighlightItem(int idItem,  BOOL fHighlight = TRUE);

Parâmetros

idItem
Índice baseado em zero de um item de controle de tabulação.

fHighlight
Valor especificando o estado de realce a ser definido. Se esse valor for TRUE, a guia será realçada, se FALSE, a guia estiver definida para seu estado padrão.

Valor de retorno

Diferente de zero se for bem-sucedido; caso contrário, zero.

Observações

Esta função de membro implementa a mensagem TCM_HIGHLIGHTITEMWin32 , conforme descrito no SDK do Windows.

CTabCtrl::HitTest

Determina qual guia, se houver, está na posição de tela especificada.

int HitTest(TCHITTESTINFO* pHitTestInfo) const;

Parâmetros

pHitTestInfo
Ponteiro para uma TCHITTESTINFO estrutura, conforme descrito no SDK do Windows, que especifica a posição da tela a ser testada.

Valor de retorno

Retorna o índice baseado em zero da guia ou -1 se nenhuma guia estiver na posição especificada.

CTabCtrl::InsertItem

Insere uma nova guia em um controle de guia existente.

LONG InsertItem(
    int nItem,
    TCITEM* pTabCtrlItem);

LONG InsertItem(
    int nItem,
    LPCTSTR lpszItem);

LONG InsertItem(
    int nItem,
    LPCTSTR lpszItem,
    int nImage);

LONG InsertItem(
    UINT nMask,
    int nItem,
    LPCTSTR lpszItem,
    int nImage,
    LPARAM lParam);

LONG InsertItem(
    UINT nMask,
    int nItem,
    LPCTSTR lpszItem,
    int nImage,
    LPARAM lParam,
    DWORD dwState,
    DWORD dwStateMask);

Parâmetros

nItem
Índice baseado em zero da nova guia.

pTabCtrlItem
Ponteiro para uma TCITEM estrutura que especifica os atributos da guia.

lpszItem
Endereço de uma cadeia de caracteres terminada em nulo que contém o texto da guia.

nImage
O índice baseado em zero de uma imagem a ser inserida a partir de uma lista de imagens.

nMask
Especifica quais TCITEM atributos de estrutura devem ser definidos. Pode ser zero ou uma combinação dos seguintes valores:

• TCIF_TEXT: O pszText membro é válido.
• TCIF_IMAGE: O iImage membro é válido.
• TCIF_PARAM: O lParam membro é válido.
• TCIF_RTLREADING: O texto do é exibido usando a ordem de leitura da pszText direita para a esquerda nos sistemas hebraico ou árabe.
• TCIF_STATE: O dwState membro é válido.

lParam
Dados definidos pelo aplicativo associados à guia.

dwState
Especifica valores para os estados do item. Para obter mais informações, consulte TCITEM no SDK do Windows.

dwStateMask
Especifica quais estados devem ser definidos. Para obter mais informações, consulte TCITEM no SDK do Windows.

Valor de retorno

Índice baseado em zero da nova guia, se bem-sucedido; caso contrário, -1.

Exemplo

TCITEM tcItem;
tcItem.mask = TCIF_TEXT;
tcItem.pszText = _T("Tab #1");

m_TabCtrl.InsertItem(0, &tcItem);

CTabCtrl::RemoveImage

Remove a imagem especificada da lista de imagens de um controle de guia.

void RemoveImage(int nImage);

Parâmetros

nImage
Índice baseado em zero da imagem a ser removida.

Observações

O controle de guia atualiza o índice de imagem de cada guia para que cada guia permaneça associada à mesma imagem.

CTabCtrl::SetCurFocus

Define o foco para uma guia especificada em um controle de guia.

void SetCurFocus(int nItem);

Parâmetros

nItem
Especifica o índice da guia que obtém o foco.

Observações

Esta função de membro implementa o comportamento da mensagem TCM_SETCURFOCUSWin32 , conforme descrito no SDK do Windows.

CTabCtrl::SetCurSel

Seleciona uma guia em um controle de guia.

int SetCurSel(int nItem);

Parâmetros

nItem
O índice baseado em zero do item a ser selecionado.

Valor de retorno

Índice baseado em zero da guia selecionada anteriormente, se bem-sucedido, caso contrário, -1.

Observações

Um controle de guia não envia uma mensagem de TCN_SELCHANGING notificação ou TCN_SELCHANGE quando uma guia é selecionada usando essa função. Essas notificações são enviadas, usando WM_NOTIFYo , quando o usuário clica ou usa o teclado para alterar guias.

CTabCtrl::SetExtendedStyle

Define os estilos estendidos para um controle de guia.

DWORD SetExtendedStyle(DWORD dwNewStyle, DWORD dwExMask = 0);

Parâmetros

dwNewStyle
Valor especificando uma combinação de estilos estendidos de controle de tabulação.

dwExMask
Um valor DWORD que indica quais estilos devem dwNewStyle ser afetados. Apenas os estilos estendidos serão dwExMask alterados. Todos os outros estilos serão mantidos como estão. Se esse parâmetro for zero, todos os estilos serão dwNewStyle afetados.

Valor de retorno

Um valor DWORD que contém os estilos estendidos de controle de guia anteriores, conforme descrito no SDK do Windows.

Observações

Esta função de membro implementa o comportamento da mensagem TCM_SETEXTENDEDSTYLEWin32 , conforme descrito no SDK do Windows.

CTabCtrl::SetImageList

Atribui uma lista de imagens a um controle de guia.

CImageList* SetImageList(CImageList* pImageList);

Parâmetros

pImageList
Ponteiro para a lista de imagens a ser atribuída ao controle de guia.

Valor de retorno

Retorna um ponteiro para a lista de imagens anterior ou NULL se não houver nenhuma lista de imagens anterior.

CTabCtrl::SetItem

Define alguns ou todos os atributos de uma guia.

BOOL SetItem(int nItem,   TCITEM* pTabCtrlItem);

Parâmetros

nItem
Índice baseado em zero do item.

pTabCtrlItem
Ponteiro para uma TCITEM estrutura que contém os novos atributos de item. O mask membro especifica quais atributos definir. Se o mask membro especificar o TCIF_TEXT valor, o pszText membro será o endereço de uma cadeia de caracteres terminada em nulo e o cchTextMax membro será ignorado.

Valor de retorno

Diferente de zero se for bem-sucedido; caso contrário, 0.

Exemplo

Veja o exemplo para GetItem.

CTabCtrl::SetItemExtra

Define o número de bytes por guia reservados para dados definidos pelo aplicativo em um controle de guia.

BOOL SetItemExtra(int nBytes);

Parâmetros

nBytes
O número de bytes extras a serem definidos.

Valor de retorno

Diferente de zero se for bem-sucedido; caso contrário, zero.

Observações

Esta função de membro implementa o comportamento da mensagem TCM_SETITEMEXTRAWin32 , conforme descrito no SDK do Windows.

CTabCtrl::SetItemSize

Define a largura e a altura dos itens de controle de guia.

CSize SetItemSize(CSize size);

Parâmetros

size
A nova largura e altura, em pixels, dos itens de controle de guia.

Valor de retorno

Retorna a largura e a altura antigas dos itens de controle de guia.

CTabCtrl::SetItemState

Define o estado do item de controle de tabulação identificado por nItem.

BOOL SetItemState(
    int nItem,
    DWORD dwMask,
    DWORD dwState);

Parâmetros

nItem
O número de índice baseado em zero do item para o qual definir informações de estado.

dwMask
Máscara especificando quais sinalizadores de estado do item devem ser definidos. Para obter uma lista de valores, consulte o TCITEM membro da máscara da estrutura, conforme descrito no SDK do Windows.

dwState
Uma referência a um valor DWORD que contém as informações de estado. Pode ser um dos seguintes valores:

Valor de retorno

Diferente de zero se for bem-sucedido; caso contrário, 0.

CTabCtrl::SetMinTabWidth

Define a largura mínima dos itens em um controle de guia.

int SetMinTabWidth(int cx);

Parâmetros

cx
Largura mínima a ser definida para um item de controle de tabulação. Se esse parâmetro for definido como -1, o controle usará a largura de tabulação padrão.

Valor de retorno

A largura mínima de tabulação anterior.

Observações

Esta função de membro implementa o comportamento da mensagem TCM_SETMINTABWIDTHWin32 , conforme descrito no SDK do Windows.

CTabCtrl::SetPadding

Define a quantidade de espaço (preenchimento) em torno do ícone e rótulo de cada guia em um controle de guia.

void SetPadding(CSize size);

Parâmetros

size
Define a quantidade de espaço (preenchimento) em torno do ícone e rótulo de cada guia em um controle de guia.

CTabCtrl::SetToolTips

Atribui um controle de dica de ferramenta a um controle de guia.

void SetToolTips(CToolTipCtrl* pWndTip);

Parâmetros

pWndTip
Alça do controle de ponta de ferramenta.

Observações

Você pode obter o controle de dica de ferramenta associado a um controle de guia fazendo uma chamada para GetToolTips.

Exemplo

Veja o exemplo para CPropertySheet::GetTabControl.

Ver também

CWnd Classe
CHeaderCtrl Classe
CListCtrl Classe
Gráfico de Hierarquia