CString Formatação e Exibição Message-Box

São fornecidas várias funções para formatar e analisar CString objetos. Pode usar estas funções sempre que tiver de manipular CString objetos, mas são particularmente úteis para formatar strings que aparecem no texto das caixas de mensagem.

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

CString Funções

Requerimentos

Cabeçalhoafxwin.h

AfxExtractSubString

Esta função global pode ser usada para extrair uma subcadeia de uma dada cadeia de origem.

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

Parâmetros

rString
Referência a um CString objeto que receberá uma substring individual.

lpszFullString
String contendo o texto completo da string a extrair.

iSubString
Índice baseado em zero da subcadeia para extrair de lpszFullString.

chSep
Carácter separador usado para delimitar substrings.

Valor de retorno

TRUE se a função extraiu com sucesso a subcadeia no índice fornecido; caso contrário, FALSE.

Observações

Esta função é útil para extrair múltiplas substrings de uma string de origem quando um único carácter conhecido separa cada substring. Esta função procura desde o início do lpszFullString parâmetro cada vez que é chamado.

Esta função retorna FALSE se qualquer um lpszFullString dos dois estiver definido como NULL ou se a função chegar ao fim de lpszFullString sem encontrar iSubString+1 ocorrências do carácter separador especificado. O rString parâmetro não será modificado do seu valor original se lpszFullString for definido para NULL; caso contrário, o rString parâmetro é definido para a cadeia vazia se a subcadeia não puder ser extraída para o índice especificado.

Example

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

Requerimentos

Cabeçalhoafxwin.h

AfxFormatString1

Substitui a cadeia apontada por lpsz1 por quaisquer instâncias dos caracteres "%1" no recurso da cadeia template identificada por nIDS.

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

Parâmetros

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

nIDS
O ID de recurso da cadeia template em que a substituição será realizada.

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

Observações

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

Se os caracteres "%1" de formato aparecerem na cadeia mais do que uma vez, serão feitas múltiplas substituições.

Example

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
}

Requerimentos

Cabeçalhoafxwin.h

AfxFormatString2

Substitui a cadeia apontada por lpsz1 por para quaisquer instâncias dos caracteres "%1", e a cadeia apontada por lpsz2 por para quaisquer instâncias dos caracteres "%2", no recurso de cadeia template identificado por nIDS.

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

Parâmetros

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

nIDS
O ID da tabela de cadeias da cadeia modelo em que a substituição será realizada.

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

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

Observações

A nova cadeia formada é armazenada em rString. Por exemplo, se a cadeia na tabela de cadeias for "File %1 not found in directory %2", lpsz1 aponta para "MYFILE.TXT", e lpsz2 aponta para "C:\MYDIR", então rString conterá a cadeia "File MYFILE.TXT not found in directory C:\MYDIR".

Se os caracteres "%1" de formato aparecerem "%2" na cadeia mais do que uma vez, serão feitas múltiplas substituições. Não têm de estar por ordem numérica.

Example

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
}

Requerimentos

Cabeçalhoafxwin.h

AfxMessageBox

Mostra uma caixa de mensagem no ecrã.

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 CString objeto ou cadeia terminada por null contendo 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
O ID de contexto da Ajuda para a mensagem; 0 indica que será usado o contexto de Ajuda predefinido da aplicação.

nIDPrompt
Um ID único usado para referenciar uma cadeia na tabela de cadeias.

Valor de retorno

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

• IDABORT O botão Abortar foi selecionado.

• IDCANCEL O botão Cancelar estava selecionado.

• IDIGNORE O botão Ignorar estava selecionado.

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

• IDOK O botão OK estava selecionado.

• IDRETRY O botão Retry estava selecionado.

• IDYES O botão Sim estava selecionado.

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

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

Observações

A primeira forma desta função sobrecarregada apresenta uma cadeia de texto apontada para por lpszText na caixa de mensagem e é usada nIDHelp para descrever um contexto de Ajuda. O contexto Ajuda é usado para saltar para um tópico de Ajuda associado quando o utilizador pressiona a tecla Ajuda (tipicamente F1).

A segunda forma da função usa o recurso string com o ID nIDPrompt para mostrar uma mensagem na caixa de mensagem. A página de Ajuda associada encontra-se através do valor de nIDHelp. Se o valor predefinido de nIDHelp for usado (-1), o ID do recurso da cadeia, nIDPrompt, é usado para o contexto Ajuda. Para mais informações sobre a definição de contextos de Ajuda, consulte a Nota Técnica 28.

Example

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

Consulte também

Macros e Globais
CStringT Classe