Next: NameList
Up: Utility objects
Previous: Utility objects
  Contents
Subsections
Inform
Files: |
Inform.h, Inform.c |
Derived from: |
none |
Global instance (if any): |
msgInfo,
msgWarn, msgErr, msgDebug |
Used in optional component: |
Part of main VMD code |
A streams-like utility object used to format messages for display at
the console or other selectable ostream object. Messages are
given to an Inform object via insertion operators («),
and the messages are printed out to a provided ostream device,
prefixed by a certain string. A special manipulator `sendmsg' is
used to signal when a mesage should be printed.
Each Inform object has a current `message level', which is also
indicated when the messages are printed out. Routines are provided to
set the current level of the Inform object, so that only messages
with a level smaller than or equal to the current output level are
printed. Levels range from 1 (most likely to be printed) to 10 (very
unlikely to be printed). The main use of this feature in VMD is
in conjunction with debugging messages, where the level of debugging
information can be changed via text commands.
There are four global instances of Inform which are available
to the entire program (as long as they include the file Inform.h):
- Inform::Inform(char *name, int ison=1)
The name argument is the name of the instance of this object; when
messages are printed out they are profixed with the name, the
message level, and a right paren, i.e.
Info 1) Info message.
The `ison' argument determines if messages should be printed or
not at the start. Besides the message levels, each Inform object can
be on or off. When off, message are not printed, otherwise they are if
the message level is set properly.
Inform contains several manipulators used to determine how the
message is printed or to do actions. They are:
- sendmsg - used to signal that the message is complete, and
should be printed. So, this should be that last item inserted into the
Inform stream.
- level1 ... level10 - sets the output level of the current
message to , where is the digit at the end of this name (1 ... 10).
- char *name - name of the instance. Used to print message
prefix.
- ostrstream *msg - character stream used to hold the message
string to be printed.
- ostream *msgDest - destination stream, where the message will
be printed. This could be the console (cout), or also a file.
- int On - whether the object should print out its messages.
- int needNewline - before the message is actually printed,
sometimes a newline must be printed, and sometimes not. This flag tells
whether to print a newline. Once a message is printed, this flag is
cleared. The member function need_newline may be used to set
this flag.
- int outputLevel - the current output message level of the
instance. This level is compared with the level of the message currently
being requested to be printed; if the level of the message is less than
or equal to the current message level of the Inform object, then
the message is printed, otherwise it is just ignored.
- int msgLevel - the current output level of the message that
is to be printed. This may be changed anytime during the construction of
the message; the level at the time when the request to print the message
is made is the one used.
- void on(int) - set the object to be on or off.
- int on(void) - return the current on/off status.
- output_level(int) - set the current output level.
- int output_level(void) - return current output level of the
Inform object.
- msg_level(int) - set the current level of the next message
to be printed.
- int msg_level(void) - return the current message output level.
- void need_newline(int) - set the current flag for whether a
newline is needed or not.
- int need_newline(void) - return current newline print status.
- void destination(ostream *) - give the provided destination
stream to the Inform object as a place where to print messages.
- ostream *destination(void) - return destination to where
messages will be printed.
- send(void) - prints the contents of the current message buffer
to the destination stream, if necessary.
- operator«(various types) - overloaded insertion operators
which are used to put data into the current message buffer. These are
used just like regular stream insertion operators, and when the message
is complete, either the routine send should be called, or else
the sendmsg manipulator should be inserted into the stream. Newline
characters may be put in the stream, Inform will print out each
newline-separated line with the proper prefix.
As stated, there are four global instances of Inform which should be
used for printing all messages in VMD. They are used just like a stream,
except the manipulator sendmsg is used instead of endl to
signal that the string should be printed. An example:
msgWarn « level3 « "This is a level-3 warning." « sendmsg;
In this case, if msgWarn is on, and it's output level is greater than
or equal to 3, then this message will be printed, otherwise it will be
ignored.
For debugging messages (printed to msgDebug), make sure to use the
MSGDEBUG macro, so that these debugging messages can be conditionally
excluded from the executable.
Right now, only the debug Inform object takes advantage of the
message level facility, all other messages (information, warning, or error)
are all level-1 messages. More messages should be printed out by VMD,
but at different levels of verbosity and content, and text commands should
be put in to control the current output level of msgInfo, msgWarn,
and msgErr.
Text commands should be added to allow the message text to be sent to a
file, or to the console (right now, they are always sent to the console).
This would not be very difficult, a new text command would need to be
added which would open a file, and call the destination routine with
the respective ostream pointer.
Next: NameList
Up: Utility objects
Previous: Utility objects
  Contents
vmd@ks.uiuc.edu