CString の書式指定とメッセージ ボックスの表示CString Formatting and Message-Box Display

オブジェクトを書式設定および解析するための多くの関数が用意されてい CString ます。A number of functions are provided to format and parse CString objects. これらの関数は、オブジェクトを操作する必要がある場合は常に使用でき CString ますが、メッセージボックスのテキストに表示される文字列を書式設定する場合に特に便利です。You can use these functions whenever you have to manipulate CString objects, but they are particularly useful for formatting strings that will appear in message-box text.

この一連の関数には、メッセージボックスを表示するためのグローバルルーチンも含まれています。This group of functions also includes a global routine for displaying a message box.

CString 関数CString Functions

名前Name 説明Description
AfxExtractSubStringAfxExtractSubString 指定されたソース文字列の1つの文字で区切られた部分文字列を抽出します。Extracts substrings separated by a single character from a given source string.
AfxFormatString1AfxFormatString1 文字列テーブルに含まれる文字列内の書式文字 "%1" に対して、指定された文字列を置換します。Substitutes a given string for the format characters "%1" in a string contained in the string table.
AfxFormatString2AfxFormatString2 文字列テーブルに格納されている文字列の書式文字 "%1" と "%2" の2つの文字列を置換します。Substitutes two strings for the format characters "%1" and "%2" in a string contained in the string table.
AfxMessageBoxAfxMessageBox メッセージ ボックスを表示します。Displays a message box.

要件Requirements

ヘッダー afxwin.hHeader afxwin.h

AfxExtractSubStringAfxExtractSubString

このグローバル関数は、指定されたソース文字列から部分文字列を抽出するために使用できます。This global function can be used to extract a substring from a given source string.

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

パラメーターParameters

rStringrString
個々の部分文字列を受け取る CString オブジェクトへの参照。Reference to a CString object that will receive an individual substring.

lpszFullStringlpszFullString
抽出元の文字列の完全なテキストを含む文字列。String containing the full text of the string to extract from.

iSubStringiSubString
Lpszfullstring から抽出する部分文字列の0から始まるインデックス。Zero-based index of the substring to extract from lpszFullString.

chSepchSep
部分文字列を区切るために使用する区切り記号。Separator character used to delimit substrings.

戻り値Return Value

関数が、指定されたインデックス位置にある部分文字列を正常に抽出した場合は TRUE。それ以外の場合は FALSE。TRUE if the function successfully extracted the substring at the provided index; otherwise, FALSE.

解説Remarks

この関数は、既知の1文字が各部分文字列を区切るときに、ソース文字列から複数の部分文字列を抽出する場合に便利です。This function is useful for extracting multiple substrings from a source string when a known single character separates each substring. この関数は、呼び出されるたびに、 Lpszfullstring パラメーターの先頭から検索します。This function searches from the beginning of the lpszFullString parameter each time it is called.

この関数は、 lpszfullstring が NULL に設定されているか、指定された区切り記号文字の isubstring と1回の出現を検出せずに、関数が lpszfullstring の末尾に到達した場合に FALSE を返します。This function will return FALSE if either lpszFullString is set to NULL or the function reaches the end of lpszFullString without finding iSubString+1 occurrences of the specified separator character. Lpszfullstring が NULL に設定されている場合、 rstring パラメーターは元の値から変更されません。それ以外の場合、指定されたインデックスの部分文字列を抽出できなかった場合は、 rstring パラメーターに空の文字列が設定されます。The rString parameter will not be modified from its original value if lpszFullString was set to NULL; otherwise, the rString parameter is set to the empty string if the substring could not be extracted for the specified index.

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

要件Requirements

ヘッダー afxwin.hHeader afxwin.h

AfxFormatString1AfxFormatString1

Lpsz1 が指す文字列を、 nIDS によって識別されるテンプレート文字列リソース内の文字 "%1" のすべてのインスタンスに置き換えます。Substitutes the string pointed to by lpsz1 for any instances of the characters "%1" in the template string resource identified by nIDS.

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

パラメーターParameters

rStringrString
CString置換が実行された後の結果の文字列を格納するオブジェクトへの参照。A reference to a CString object that will contain the resultant string after the substitution is performed.

nIDSnIDS
置換が実行されるテンプレート文字列のリソース ID。The resource ID of the template string on which the substitution will be performed.

lpsz1lpsz1
テンプレート文字列の書式文字 "%1" を置換する文字列。A string that will replace the format characters "%1" in the template string.

解説Remarks

新しく形成された文字列は rstring に格納されます。The newly formed string is stored in rString. たとえば、文字列テーブル内の文字列が "ファイル %1 が見つかりません" で、 lpsz1 が "C:\MYFILE.TXT" と等しい場合、 rstring には "file C:\MYFILE.TXT not found" という文字列が含まれます。For example, if the string in the string table is "File %1 not found", and lpsz1 is equal to "C:\MYFILE.TXT", then rString will contain the string "File C:\MYFILE.TXT not found". この関数は、メッセージボックスやその他のウィンドウに送信される文字列を書式設定する場合に便利です。This function is useful for formatting strings sent to message boxes and other windows.

書式文字 "%1" が文字列に複数回出現する場合は、複数の置換が行われます。If the format characters "%1" appear in the string more than once, multiple substitutions will be made.

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
}

要件Requirements

ヘッダー afxwin.hHeader afxwin.h

AfxFormatString2AfxFormatString2

Lpsz1 が指す文字列を、文字 "%1" のすべてのインスタンス、および lpsz2 が指す文字列を、 nIDS で識別されるテンプレート文字列リソースの文字 "%2" のすべてのインスタンスに置き換えます。Substitutes the string pointed to by lpsz1 for any instances of the characters "%1", and the string pointed to by lpsz2 for any instances of the characters "%2", in the template string resource identified by nIDS.

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

パラメーターParameters

rStringrString
CString置換が実行された後の結果の文字列を格納するへの参照。A reference to the CString that will contain the resultant string after the substitution is performed.

nIDSnIDS
置換が実行されるテンプレート文字列の文字列テーブル ID。The string table ID of the template string on which the substitution will be performed.

lpsz1lpsz1
テンプレート文字列の書式文字 "%1" を置換する文字列。A string that will replace the format characters "%1" in the template string.

lpsz2lpsz2
テンプレート文字列の書式文字 "%2" を置換する文字列。A string that will replace the format characters "%2" in the template string.

解説Remarks

新しく形成された文字列は rstring に格納されます。The newly formed string is stored in rString. たとえば、文字列テーブル内の文字列が "ファイル %1 がディレクトリ %2 で見つからない"、 lpsz1 が "MYFILE.TXT" を指し、 lpsz2 が "C:\MYDIR" を指している場合、 rstring には "" という MYFILE.TXT 文字列が含まれます。For example, if the string in the string table is "File %1 not found in directory %2", lpsz1 points to "MYFILE.TXT", and lpsz2 points to "C:\MYDIR", then rString will contain the string "File MYFILE.TXT not found in directory C:\MYDIR"

書式文字 "%1" または "%2" が文字列に複数回出現する場合は、複数の置換が行われます。If the format characters "%1" or "%2" appear in the string more than once, multiple substitutions will be made. 数字の順序で指定する必要はありません。They do not have to be in numerical order.

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
}

要件Requirements

ヘッダー afxwin.hHeader afxwin.h

AfxMessageBoxAfxMessageBox

画面にメッセージ ボックスを表示します。Displays a message box on the screen.

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

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

パラメーターParameters

lpszTextlpszText
CString オブジェクト、またはメッセージ ボックスに表示されるメッセージを含む null で終了する文字列をポイントします。Points to a CString object or null-terminated string containing the message to be displayed in the message box.

nTypenType
メッセージ ボックスのスタイル。The style of the message box. ボックスに任意の メッセージボックススタイル を適用します。Apply any of the message-box styles to the box.

nIDHelpnIDHelp
メッセージのヘルプ コンテキスト ID。0 は、アプリケーションの既定のヘルプ コンテキストが使用されることを示します。The Help context ID for the message; 0 indicates the application's default Help context will be used.

nIDPromptnIDPrompt
文字列テーブル内の文字列の参照に使用される一意の ID。A unique ID used to reference a string in the string table.

戻り値Return Value

メッセージ ボックスを表示する十分なメモリがない場合は 0。それ以外の場合、次のいずれかの値が返されます。Zero if there is not enough memory to display the message box; otherwise, one of the following values is returned:

  • IDABORT [中止] ボタンが選択されました。IDABORT The Abort button was selected.

  • IDCANCEL [キャンセル] ボタンが選択されました。IDCANCEL The Cancel button was selected.

  • IDIGNORE [無視] ボタンが選択されました。IDIGNORE The Ignore button was selected.

  • IDNO ボタンが選択されました。IDNO The No button was selected.

  • IDOK [OK] ボタンが選択されました。IDOK The OK button was selected.

  • IDRETRY [再試行] ボタンが選択されました。IDRETRY The Retry button was selected.

  • IDYES [はい] ボタンが選択されました。IDYES The Yes button was selected.

メッセージ ボックスに [キャンセル] ボタンがある場合、Esc キーが押されるか、または [キャンセル] ボタンが選択されると、IDCANCEL 値が返されます。If a message box has a Cancel button, the IDCANCEL value will be returned if either the ESC key is pressed or the Cancel button is selected. メッセージ ボックスに [キャンセル] ボタンがない場合、Esc キーを押しても効果はありません。If the message box has no Cancel button, pressing the ESC key has no effect.

AfxFormatString1およびAfxFormatString2関数は、メッセージボックスに表示されるテキストの書式を設定するときに役立ちます。The functions AfxFormatString1 and AfxFormatString2 can be useful in formatting text that appears in a message box.

解説Remarks

このオーバーロードされた関数の最初の形式では、メッセージボックスで lpszText が指すテキスト文字列を表示し、 nIDHelp を使用してヘルプコンテキストを記述します。The first form of this overloaded function displays a text string pointed to by lpszText in the message box and uses nIDHelp to describe a Help context. ヘルプ コンテキストは、ユーザーがヘルプ キー (通常は F1 キー) を押したときに関連するヘルプ トピックにジャンプするために使用されます。The Help context is used to jump to an associated Help topic when the user presses the Help key (typically F1).

関数の2番目の形式では、ID nIDPrompt の文字列リソースを使用して、メッセージボックスにメッセージを表示します。The second form of the function uses the string resource with the ID nIDPrompt to display a message in the message box. 関連付けられているヘルプページは、 nIDHelp の値を使用して検出されます。The associated Help page is found through the value of nIDHelp. NIDHelp の既定値 (-1) が使用されている場合は、ヘルプコンテキストに対して文字列リソース ID nIDPrompt が使用されます。If the default value of nIDHelp is used (-1), the string resource ID, nIDPrompt, is used for the Help context. ヘルプコンテキストの定義の詳細については、「 テクニカルノート 28」を参照してください。For more information about defining Help contexts, see Technical Note 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);

関連項目See also

マクロとグローバルMacros and Globals
CStringT クラスCStringT Class