wxLog classes overview

wxLogクラスの概要 wxLog classes overview

Classes: wxLog,
wxLogStderr,
wxLogStream,
wxLogTextCtrl,
wxLogWindow,
wxLogGui,
wxLogNull,
wxLogChain,
wxLogPassThrough,
wxStreamToTextRedirector

これはwxWidgetsに提供されるロギングクラスの全体的な概観です。「ロギング」という言葉には、ただ「インタラクティブでないメッセージ」というだけでなく、プログラムのアウトプット全てをも含む広範な意味があります。 wxWidgetsに含まれるログ機構では、ベースとなる wxLog クラス（標準的な log target へのインターフェースを定義）を、それと一緒に使うためのいくつかの標準的な関数群の実装と同様に提供します。

This is a general overview of logging classes provided by wxWidgets. The word logging here has a broad sense, including all of the program output, not only non interactive messages. The logging facilities included in wxWidgets provide the base wxLog class which defines the standard interface for a log target as well as several standard implementations of it and a family of functions to use with them.

まず第一に、wxLog クラスを使用するのにその知識は必要とされません。このため、あなたはただ wxLogXXX() という関数について知っていればよいのです。それら全てが printf() や vprintf() と同じ文法（すなわちフォーマットstringを第１引数に、そしてそれぞれ可変数の引数か可変的な引数リストのポインタを持つ）なのです。以下がその全てです。

First of all, no knowledge of wxLog classes is needed to use them. For this, you should only know about wxLogXXX() functions. All of them have the same syntax as printf() or vprintf() , i.e. they take the format string as the first argument and respectively a variable number of arguments or a variable argument list pointer. Here are all of them:

wxLogFatalError は wxLogError と似ていますが、プログラムは終了コード「３（標準関数の abort() を使用）」で終了します。他のロギング関数と違って、この関数はログターゲットによるオーバライドはできません。
wxLogError はエラーメッセージ、すなわちユーザーに見せるべきメッセージ用に使用される関数です。デフォルトの処理は、ユーザーに通知するためのポップアップメッセージを表示します。
wxLogWarning は警告用です。これも通常はユーザーに見せます。ですがプログラムの処理は中断しません。
wxLogMessage は全ての正常時の、情報としてのメッセージ用です。これもデフォルトではメッセージボックスを表示します（変更して見えなくすることもできますが）。注意すべきことは、標準的な動作では後から何らかのエラーが出た場合にはインフォメーションメッセージは表示されない、つまり後から発生したエラーメッセージが先に起こっているインフォメーションメッセージを無意味なものにしてしまうということです。
wxLogVerbose はverbose（冗長）表示用です。通常は出力されませんが、ユーザーがプログラムのもっと詳細な進行状況を見たい場合には作動されるかもしれません。（一方、同じ機能で紛らわしい名前なのが wxLogInfoです。)
wxLogStatus はステータスメッセージ用です。これはアクティブなウィンドウもしくは（第１引数として）指定されたウィンドウのステータスバーに表示されます。 wxFrame が（ステータスバーを）持っているのなら。
wxLogSysError は、大抵はwxWidgets自身に使われていますが、システムコール（API関数）失敗の後にエラーをロギングするのに便利かもしれません。それは直近のシステムエラーコードや対応するメッセージと同様に、指定されたメッセージテキストをログに出力します（システムエラーコード(errno）や ::GetLastError() は、環境に依存します）。この関数の２番目の書式では、明示的にエラーコードを最初の引数とみなします。
wxLogDebug は、正真正銘のデバック出力用の関数です。これはデバックモード（プリプロセッサに「__WXDEBUG__」が定義されている場合）でのみ動作し、リリースモード（その他の場合）では展開されません。 Tip: Windows環境下で実際にデバッグ表示を見るためには、デバッガ配下でプログラムを実行するか、第３者の提供する DbgView のようなプログラムを使用しなくてはなりません。
wxLogTrace も wxLogDebug のようにデバッグビルド時にのみ動作します。これを別個の関数にした理由は、通常トレースメッセージは大量に出力されるためです。ですから、氾濫する他のデバックメッセージと分離することに意味があります。さらにこの関数の２番目のバージョンでは、生成されたメッセージの量をさらに限定するためのトレースマスクを第１引数として持っています。

wxLogFatalError which is like wxLogError, but also terminates the program with the exit code 3 (using abort() standard function). Unlike for all the other logging functions, this function can't be overridden by a log target.
wxLogError is the function to use for error messages, i.e. the messages that must be shown to the user. The default processing is to pop up a message box to inform the user about it.
wxLogWarning for warnings - they are also normally shown to the user, but don't interrupt the program work.
wxLogMessage is for all normal, informational messages. They also appear in a message box by default (but it can be changed, see below). Notice that the standard behaviour is to not show informational messages if there are any errors later - the logic being that the later error messages make the informational messages preceding them meaningless.
wxLogVerbose is for verbose output. Normally, it is suppressed, but might be activated if the user wishes to know more details about the program progress (another, but possibly confusing name for the same function is wxLogInfo).
wxLogStatus is for status messages - they will go into the status bar of the active or specified (as the first argument) wxFrame if it has one.
wxLogSysError is mostly used by wxWidgets itself, but might be handy for logging errors after system call (API function) failure. It logs the specified message text as well as the last system error code (errno or ::GetLastError() depending on the platform) and the corresponding error message. The second form of this function takes the error code explicitly as the first argument.
wxLogDebug is the right function for debug output. It only does anything at all in the debug mode (when the preprocessor symbol __WXDEBUG__ is defined) and expands to nothing in release mode (otherwise). Tip: under Windows, you must either run the program under debugger or use a 3rd party program such as DbgView to actually see the debug output.
wxLogTrace as wxLogDebug only does something in debug build. The reason for making it a separate function from it is that usually there are a lot of trace messages, so it might make sense to separate them from other debug messages which would be flooded in them. Moreover, the second version of this function takes a trace mask as the first argument which allows to further restrict the amount of messages generated.

これらの関数の使用法はかなり簡単ですが、しかし「どうして C 標準の stdio や C++ の streamsのような、他のロギング機構を使わないのか」と聞かれるかもしれません。端的な答えとしては、それらは非常に汎用的なよいメカニズムだが、ログクラスが wxWidgetsに適合されるのに対して、それらはうまく適合されないからです。 wxWidgetsのログ関数を使用する利点のいくつかは以下のとおりです。

The usage of these functions should be fairly straightforward, however it may be asked why not use the other logging facilities, such as C standard stdio functions or C++ streams. The short answer is that they're all very good generic mechanisms, but are not really adapted for wxWidgets, while the log classes are. Some of advantages in using wxWidgets log functions are:

移殖性 （デバッグやその他の）情報を出力するのに、 printf() 文や C++の cout/cerr といったストリームを使用するのはごく普通の行動です。それは Unix 環境ではちゃんと動きますが、GUI プログラムの標準出力（ｓｔｄｏｕｔ）が何にも割り当てられていない Windows 環境では、これらのメッセージは厳密にどこにも行かないのです。これであなたは、wxLogMessage() を printf() の簡単な代用品と見てくれるかもしれません。
また、下記のように書くことで、 wxLogXXX 呼び出しを cout にリダイレクトする事ができます。
```
  wxLog *logger=new wxLogStream(&cout);
  wxLog::SetActiveTarget(logger);
```
最終的には、 wxStreamToTextRedirector クラスを使うことによって cout に送った出力を wxTextCtrl にリダイレクトする可能性もあります。
柔軟性 wxLog 関数の出力は、リダイレクトするか、その重要性に基づいて隠されることができます。これは伝統的手法では、不可能であるか困難なものでした。例えば、全てのインフォメーションメッセージを除外して、「エラーメッセージのみ」あるいは「エラーメッセージと警告のみ」がログに出力されるかもしれません。
完全性 通常、ある処理が失敗したらユーザーにエラーメッセージが提示されるべきです。ファイルエラーの非常に簡単な、しかしよくある事例を取り上げてみましょう：ディスクにファイルを出力する時に十分な空き容量がない場合を思い浮かべてください。実際のエラーは wxWidgets のコードの中（例えば wxFile::Write ）で検知されているでしょうから、呼び出し側の関数ではエラーの詳細な理由は全く分からず、ただ「データファイルがディスクに書き込めなかった」ということが分かるだけなのです。しかしながら、 wxWidgets がこのような状況で wxLogError() を使えば、詳細なエラーコード（とそれに対応するエラーメッセージ）が「データファイル書き込みエラー」に関する｢高レベルな」メッセージとともにユーザーに提示されるでしょう。

Portability It is a common practice to use printf() statements or cout/cerr C++ streams for writing out some (debug or otherwise) information. Although it works just fine under Unix, these messages go strictly nowhere under Windows where the stdout of GUI programs is not assigned to anything. Thus, you might view wxLogMessage() as a simple substitute for printf().
You can also redirect the wxLogXXX calls to cout by just writing:
```
  wxLog *logger=new wxLogStream(&cout);
  wxLog::SetActiveTarget(logger);
```
Finally, there is also a possibility to redirect the output sent to cout to a wxTextCtrl by using the wxStreamToTextRedirector class.
Flexibility The output of wxLog functions can be redirected or suppressed entirely based on their importance, which is either impossible or difficult to do with traditional methods. For example, only error messages, or only error messages and warnings might be logged, filtering out all informational messages.
Completeness Usually, an error message should be presented to the user when some operation fails. Let's take a quite simple but common case of a file error: suppose that you're writing your data file on disk and there is not enough space. The actual error might have been detected inside wxWidgets code (say, in wxFile::Write), so the calling function doesn't really know the exact reason of the failure, it only knows that the data file couldn't be written to the disk. However, as wxWidgets uses wxLogError() in this situation, the exact error code (and the corresponding error message) will be given to the user together with "high level" message about data file writing error.

メッセージをログ出力する際に通常使用される全ての関数と、あなたがこれらを使用する理由について列挙しましたので、ここでこれらがどのように動作するかを記述します。

After having enumerated all the functions which are normally used to log the messages, and why would you want to use them we now describe how all this works.

wxWidgets は、ログターゲット の概念を持っています。それは wxLog の派生クラスです。そういうものとして、それはメッセージをログ出力する際に呼び出される基本クラスで仮想関数として実装しています。いかなるタイミングでも、アクティブ状態のログターゲットは１つだけで、これは wxLogXXX() 関数によって使用されます。ログ出力オブジェクト（すなわち wxLog から派生したクラスオブジェクト）の標準的な用法ですが、それは SetActiveTarget() 関数を呼び出すことでアクティブターゲットとしてインストールしておけば、それ以降は wxLogXXX() 関数を呼び出すと自動的に使用されます。

wxWidgets has the notion of a log target: it is just a class deriving from wxLog. As such, it implements the virtual functions of the base class which are called when a message is logged. Only one log target is active at any moment, this is the one used by wxLogXXX() functions. The normal usage of a log object (i.e. object of a class derived from wxLog) is to install it as the active target with a call to SetActiveTarget() and it will be used automatically by all subsequent calls to wxLogXXX() functions.

新しいログターゲットクラスを生成するためには、あなたはただ wxLog から派生させて、 DoLog() か DoLogString() のいずれか（あるいは両方）を実装する必要があるだけです。もしあなたが標準的な wxLog のメッセージフォーマット（先頭に "Error:" か "Warning:" とタイムスタンプ）で満足していて、ただメッセージを他のどこかに送りたいだけなら、２番目ので十分です。１番目のはあなたが望むものは何でもオーバーライドできるでしょうが、異なるメッセージの種類を自分で区別しなければなりません。

To create a new log target class you only need to derive it from wxLog and implement one (or both) of DoLog() and DoLogString() in it. The second one is enough if you're happy with the standard wxLog message formatting (prepending "Error:" or "Warning:", timestamping &c) but just want to send the messages somewhere else. The first one may be overridden to do whatever you want but you have to distinguish between the different message types yourself.

ここにいくつかの事前定義された wxLog から派生したクラスがあります。これらはあなたが新しいログターゲットクラスの作り方をみるのに役立つでしょうし、もちろん何の変更も加えずに使用することもできます。それは:

wxLogStderr その名前の通り、このクラスではデフォルトでメッセージを標準エラー出力からファイル（ FILE * ）に記録します。
wxLogStream このクラスは wxLogStderr と同じ機能性を持ちますが、「 FILE * 」と標準エラー出力の代わりに「 ostream 」と「 cerr 」を使います。
wxLogGui これは wxWidgets アプリケーションでの標準的なログターゲット（あなたがなにもしなければデフォルトでこれが使われます）であり、そのプラットフォームの全ての種類のメッセージについて最も合理的なハンドリングを提供します。
wxLogWindow このログターゲットは、アプリケーションが発する全てのメッセージを集める「ログコンソール」を提供して、さらに集めたメッセージをそれまでアクティブだったログターゲットに渡します。ログウィンドウフレーム（ログコンソール）には、ユーザーの「ログのクリア」「クローズ」「全メッセージをファイルに保存」を許すメニューを持っています。
wxLogNull 最後のログクラスは特別です。何もしません。このクラスのオブジェクトは多分、（一時的に） wxLogXXX() 関数のアウトプットを抑制するためにインスタンスが生成されるでしょう。例えば、存在しないファイルを開こうとすることは大抵はエラーメッセージを引き起こすでしょう。ですがもし、何らかの理由でそれを望まないのであれば、まさにこの機能を使用してください。
```
  wxFile file;

  // wxFile.Open() normally complains if file can't be opened, we don't want it
  {
    wxLogNull logNo;
    if ( !file.Open("bar") )
      ... process error ourselves ...
  } // ~wxLogNull called, old log sink restored
  
  wxLogMessage("..."); // ok
```

There are some predefined classes deriving from wxLog and which might be helpful to see how you can create a new log target class and, of course, may also be used without any change. There are:

wxLogStderr This class logs messages to a FILE *, using stderr by default as its name suggests.
wxLogStream This class has the same functionality as wxLogStderr, but uses ostream and cerr instead of FILE * and stderr.
wxLogGui This is the standard log target for wxWidgets applications (it is used by default if you don't do anything) and provides the most reasonable handling of all types of messages for given platform.
wxLogWindow This log target provides a "log console" which collects all messages generated by the application and also passes them to the previous active log target. The log window frame has a menu allowing user to clear the log, close it completely or save all messages to file.
wxLogNull The last log class is quite particular: it doesn't do anything. The objects of this class may be instantiated to (temporarily) suppress output of wxLogXXX() functions. As an example, trying to open a non-existing file will usually provoke an error message, but if for some reasons it is unwanted, just use this construction:
```
  wxFile file;

  // wxFile.Open() normally complains if file can't be opened, we don't want it
  {
    wxLogNull logNo;
    if ( !file.Open("bar") )
      ... process error ourselves ...
  } // ~wxLogNull called, old log sink restored
  
  wxLogMessage("..."); // ok
```

ログターゲットは結合することも可能です。例えばあなたは通常通りの処理はしたうえで、さらにメッセージをどこか他のところ（ログファイル等）にリダイレクトしたいと思うかもしれません。このために「 wxLogChain 」と「 wxLogPassThrough 」は使用することができます。

The log targets can also be combined: for example you may wish to redirect the messages somewhere else (for example, to a log file) but also process them as normally. For this the wxLogChain and wxLogPassThrough can be used.