Compartilhar via


Formatação CString e exibição da caixa de mensagem

Várias funções são fornecidas para formatar e analisar objetos CString. Você pode usar essas funções sempre que precisar manipular objetos CString, mas elas são particularmente úteis para formatar cadeias de caracteres que aparecerão no texto da caixa de mensagem.

Esse grupo de funções também inclui uma rotina global para exibir uma caixa de mensagem.

CString Funções

Nome Descrição
AfxExtractSubString Extrai substrings separadas por um só caractere de uma determinada cadeia de caracteres de origem.
AfxFormatString1 Substitui uma determinada cadeia de caracteres para os caracteres de formato "%1" em uma cadeia de caracteres contida na tabela de cadeia de caracteres.
AfxFormatString2 Substitui duas cadeias de caracteres para os caracteres de formato "%1" e "%2" em uma cadeia de caracteres contida na tabela de cadeia de caracteres.
AfxMessageBox Mostra uma caixa de mensagem.

Requisitos

Cabeçalho afxwin.h

AfxExtractSubString

Essa função global pode ser usada para extrair uma substring de uma determinada cadeia de caracteres de origem.

BOOL AFXAPI AfxExtractSubString (
    CString& rString,
    LPCTSTR lpszFullString,
    int iSubString,
    TCHAR chSep  = '\n');

Parâmetros

rString
Faça referência a um objeto CString que receberá uma substring individual.

lpszFullString
Cadeia de caracteres que contém o texto completo da cadeia de caracteres a ser extraída.

iSubString
Índice baseado em zero da substring a ser extraída de lpszFullString.

chSep
Caractere separador usado para delimitar substrings.

Valor de retorno

TRUE se a função tiver extraído com êxito a substring no índice fornecido; caso contrário, FALSE.

Comentários

Essa função é útil para extrair várias substrings de uma cadeia de caracteres de origem quando um só caractere conhecido separa cada substring. Essa função pesquisa desde o início do parâmetro lpszFullString sempre que é chamada.

Essa função retornará FALSE se lpszFullString estiver definido como NULL ou a função atingir o fim de lpszFullString sem localizar iSubString+1 ocorrências do caractere separador especificado. O parâmetro rString não será modificado de seu valor original se lpszFullString for definido como NULL; caso contrário, o parâmetro rString será definido como a cadeia de caracteres vazia se a substring não puder ser extraída para o índice especificado.

Exemplo

// The following example extracts a series of name, value pairs from a
// given source string:

// Input string consisting of a number of name, value pairs
LPCTSTR lpszSource = _T("\"Name\"=\"John Smith\"\n")
_T("\"Company\"=\"Contoso, Ltd\"\n\"Salary\"=\"25,000\"");

CString strNameValue; // an individual name, value pair

int i = 0; // substring index to extract
while (AfxExtractSubString(strNameValue, lpszSource, i))
{
   // Prepare to move to the next substring
   i++;

   CString strName, strValue; // individual name and value elements

   // Attempt to extract the name element from the pair
   if (!AfxExtractSubString(strName, strNameValue, 0, _T('=')))
   {
      // Pass an error message to the debugger for display
      OutputDebugString(_T("Error extracting name\r\n"));
      continue;
   }

   // Attempt to extract the value element from the pair
   if (!AfxExtractSubString(strValue, strNameValue, 1, _T('=')))
   {
      // Pass an error message to the debugger for display
      OutputDebugString(_T("Error extracting value element\r\n"));
      continue;
   }

   // Pass the name, value pair to the debugger for display
   CString strOutput = strName + _T(" equals ") + strValue + _T("\r\n");
   OutputDebugString(strOutput);
}

Requisitos

Cabeçalho afxwin.h

AfxFormatString1

Substitui a cadeia de caracteres apontada por lpsz1 por qualquer instância dos caracteres "%1" no recurso de cadeia de caracteres de modelo identificado por nIDS.

void  AfxFormatString1(
    CString& rString,
    UINT nIDS,
    LPCTSTR lpsz1);

Parâmetros

rString
Uma referência a um objeto CString que conterá a cadeia de caracteres resultante após a substituição ser executada.

nIDS
A ID do recurso da cadeia de caracteres de modelo na qual a substituição será executada.

lpsz1
Uma cadeia de caracteres que substituirá os caracteres de formato "%1" na cadeia de caracteres de modelo.

Comentários

A cadeia de caracteres que acaba de ser formada é armazenada em rString. Por exemplo, se a cadeia de caracteres na tabela de cadeia de caracteres for "File %1 not found" e lpsz1 for igual a "C:\MYFILE.TXT", rString conterá a cadeia de caracteres "File C:\MYFILE.TXT not found". Essa função é útil para formatar cadeias de caracteres enviadas para caixas de mensagem e outras janelas.

Se os caracteres de formato "%1" aparecerem na cadeia de caracteres mais de uma vez, várias substituições serão feitas.

Exemplo

void DisplayFileNotFoundMessage(LPCTSTR pszFileName)
{
   CString strMessage;

   // The IDS_FILENOTFOUND string resource contains "Error: File %1 not found"
   AfxFormatString1(strMessage, IDS_FILENOTFOUND, pszFileName);
   // In the previous call, substitute the actual file name for the
   // %1 placeholder
   AfxMessageBox(strMessage);  // Display the error message
}

Requisitos

Cabeçalho afxwin.h

AfxFormatString2

Substitui a cadeia de caracteres apontada por lpsz1 por todas as instâncias dos caracteres "%1", e a cadeia de caracteres apontada por lpsz2 por qualquer instância dos caracteres "%2" no recurso de cadeia de caracteres de modelo identificado por nIDS.

void AfxFormatString2(
    CString& rString,
    UINT nIDS,
    LPCTSTR lpsz1,
    LPCTSTR lpsz2);

Parâmetros

rString
Uma referência à CString que conterá a cadeia de caracteres resultante após a substituição ser executada.

nIDS
A ID da tabela de cadeia de caracteres referente à cadeia de caracteres de modelo na qual a substituição será executada.

lpsz1
Uma cadeia de caracteres que substituirá os caracteres de formato "%1" na cadeia de caracteres de modelo.

lpsz2
Uma cadeia de caracteres que substituirá os caracteres de formato "%2" na cadeia de caracteres de modelo.

Comentários

A cadeia de caracteres que acaba de ser formada é armazenada em rString. Por exemplo, se a cadeia de caracteres na tabela de cadeia de caracteres for "File %1 not found in directory %2", lpsz1 apontar para "MYFILE.TXT" e lpsz2 apontar para "C:\MYDIR", rString conterá a cadeia de caracteres "File MYFILE.TXT not found in directory C:\MYDIR".

Se os caracteres de formato "%1" ou "%2" aparecerem na cadeia de caracteres mais de uma vez, várias substituições serão feitas. Eles não precisam estar em ordem numérica.

Exemplo

void DisplayFileNotFoundMessage(LPCTSTR pszFileName, LPCTSTR pszDirectory)
{
   CString strMessage;

   // The IDS_FILENOTFOUND string resource contains "Error: File %1 not 
   // found in directory %2"
   AfxFormatString2(strMessage, IDS_FILENOTFOUND2, pszFileName, pszDirectory);
   // In the previous call, substitute the actual file and directory 
   // names into the message string
   AfxMessageBox(strMessage);  // Display the error message
}

Requisitos

Cabeçalho afxwin.h

AfxMessageBox

Exibe uma caixa de mensagem na tela.

int AfxMessageBox(
    LPCTSTR lpszText,
    UINT nType = MB_OK,
    UINT nIDHelp = 0);

int AFXAPI AfxMessageBox(
    UINT nIDPrompt,
    UINT nType = MB_OK,
    UINT nIDHelp = (UINT) -1);

Parâmetros

lpszText
Aponta para um objeto CString ou cadeia de caracteres terminada em nulo que contém a mensagem a ser exibida na caixa de mensagem.

nType
O estilo da caixa de mensagem. Aplique qualquer um dos estilos de caixa de mensagem à caixa.

nIDHelp
A ID de contexto da Ajuda para a mensagem; 0 indica que o contexto de Ajuda padrão do aplicativo será usado.

nIDPrompt
Uma ID exclusiva usada para referenciar uma cadeia de caracteres na tabela de cadeia de caracteres.

Valor de retorno

Zero se não houver memória suficiente para exibir a caixa de mensagem; caso contrário, um dos seguintes valores é retornado:

  • IDABORT O botão Anular foi selecionado.

  • IDCANCEL O botão Cancelar foi selecionado.

  • IDIGNORE O botão Ignorar foi selecionado.

  • IDNO O botão Não foi selecionado.

  • IDOK O botão OK foi selecionado.

  • IDRETRY O botão Repetir foi selecionado.

  • IDYES O botão Sim foi selecionado.

Se uma caixa de mensagem tiver um botão Cancelar, o valor IDCANCEL será retornado se a tecla ESC estiver pressionada ou o botão Cancelar estiver selecionado. Se a caixa de mensagem não tiver botão Cancelar, pressionar a tecla ESC não terá efeito.

As funções AfxFormatString1 e AfxFormatString2 podem ser úteis na formatação de texto que aparece em uma caixa de mensagem.

Comentários

A primeira forma dessa função sobrecarregada exibe uma cadeia de caracteres de texto apontada na caixa de mensagem lpszText e usa nIDHelp para descrever um contexto de Ajuda. O contexto de Ajuda é usado para ir para um tópico de Ajuda associado quando o usuário pressiona a tecla Ajuda (normalmente, F1).

A segunda forma da função usa o recurso de cadeia de caracteres com a ID nIDPrompt para exibir uma mensagem na caixa de mensagem. A página Ajuda associada é encontrada por meio do valor de nIDHelp. Se o valor padrão de nIDHelp for usado (-1), a ID do recurso de cadeia de caracteres, nIDPrompt, será usada para o contexto de Ajuda. Para mais informações sobre como definir contextos de Ajuda, confira a Nota Técnica 28.

Exemplo

// A simple message box, with only the OK button.
AfxMessageBox(_T("Simple message box."));

// A message box that uses a string from a string table
// with yes and no buttons and the stop icon.
// NOTE: nStringID is an integer that contains a valid id of
// a string in the current resource.
AfxMessageBox(nStringID, MB_YESNO | MB_ICONSTOP);

Confira também

Macros e Globais
Classe CStringT