manual.txt

AlertDriver c++模块化类库

Example   14,  defaultAlertDriver  is  the  first  of  four   (4)
AlertDrivers  which  are  linked together.  After  executing  the
code  in  Example  14, defaultAlertDriver will be  the  first  of
two   (2)  AlertDrivers  in  the  link.  The  three  AlertDrivers
which   were   linked   to  defaultAlertDriver   prior   to   the
ChangeLinkedAlertDriver()     call     were     detached     from
defaultAlertDriver  (and  possibly  deallocated  if   they   were
not being used by other objects).

This  concept  works  in the other direction  as  well.  You  can
link  several  AlertDrivers together, than pass  the  address  of
the   first   one   to   ChangeLinkedAlertDriver();   the   first
AlertDriver  will  be  directly  attached  to  the  object/driver
for  which  the  call was made, while all other  AlertDrivers  in
the    link   will   be   indirectly   attached   to   the   same
object/driver.

When  several  AlertDrivers are linked together,  the  first  one
processes  the  alert  from  the  AlertableObject,  then   passes
the   alert   to  the  next  linked  AlertDriver.  This   process
continues  until  there are no more AlertDrivers  in  the  chain.
Because  of  this  series of actions, it is  suggested  that  you
place    only    one   screen-oriented   AlertDriver    in    any
AlertDriver   chain.   We  also  recommend   that   the   screen-
oriented   AlertDriver  (or  any  AlertDriver   which   interacts
with  the  user)  be placed first in the chain -  this  not  only
allows  the  user  to  be  notified immediately  of  any  alerts,
but  also  ensures  that  other AlertDrivers  in  the  chain  are
informed   of   the   user's   choice.   For   example,   if   an
AlertDriver   chain  contained  both  a  StdAlertDriver   and   a
TextFileAlertDriver,   you   should  place   the   StdAlertDriver
first   because  it  interacts  with  the  user.  In  this  case,
warning  alerts  would  be  presented to  the  user  first,  then
the  user's  choice  would be recorded  in  the  text  file.  Had
the   TextFileAlertDriver  been  placed  first  in   the   chain,
recording  the  user's choice correctly in the  text  file  would
not be possible.


Modifying AlertDriver Behavior

At  times,  you  may  wish to temporarily disable  processing  of
a  certain  type of alert or affect the output of  an  alert  for
an    AlertableObject   without   changing   or   detaching   the
AlertDriver.   Such  changes  can  be  made   by   altering   the
processing   flags   which  are  stored  in   each   AlertDriver.
Through    the   use   of   AlertableObject   member    functions
GetAlertProcFlags()   and   ChangeAlertProcFlags(),    you    can
obtain  and  alter  the  settings of  the  linked  AlertDriver(s)
for   an   object.  (You  can  directly  get/set  the  processing
flags   for  an  AlertDriver  by  calling  its  member  functions
GetProcFlags()  and  ChangeProcFlags() - see  the  Class  Library
Reference chapter for details and syntax.)

The  processing  flags  for  an AlertDriver  are  represented  as
bit-mapped  constants  prefixed with the  letters  "adf"  in  the
ALERTDRV.H   header  file.  Four  of  these  constants   act   as
switches   for   processing   the  various   types   of   alerts:
adfERROR,  adfINFO,  adfMESSAGE,  and  adfWARNING.  When  one  of
these  flags  is  enabled  (on), the  AlertDriver  processes  all
alerts  of  that  type which are passed to it.  When  a  flag  is
disabled  (off),  the AlertDriver ignores alerts  of  that  type,
but  still  passes  the  alert  to the  next  linked  AlertDriver
(if any).

The  return  value  of  AlertableObject::GetAlertProcFlags()   is
an   unsigned   short  which  holds  the  value  of   all   flags
currently  enabled  for  the  first linked  AlertDriver  for  the
object.  You  can  test  to  see if a flag  is  enabled  (on)  by
performing a binary "AND" operation:

//see if the first-linked AlertDriver for MyObj is currently
processing warnings
if (MyObj.GetAlertProcFlags() & adfWARNING)
{
   //warnings are being processed for MyObj
   ...
}

Example  15  shows  how  to enable or disable  processing  for  a
specific        type       of       alert        using        the
AlertableObject::ChangeAlertProcFlags()  member   function;   the
second  parameter  determines whether  the  specified  flags  are
enabled  (cfoENABLE),  disabled  (cfoDISABLE),  or  intended   to
overwrite  all  of the current flags (cfoOVERWRITE)  as  well  as
whether   the   changes  are  made  for  the  first   AlertDriver
(cfoDRIVER)   or   for   all   linked  AlertDrivers   (cfoCHAIN).
Please see the Class Library Reference for more details.

Example  15  -  Enabling  and  disabling  AlertDriver  processing
flags  for  an  Integer  object. Notice  that  when  enabling  or
disabling   specific  flags,  other  flags  for  the  AlertDriver
are   not   altered.   In   this  example,   the   first   linked
AlertDriver   for  object  "a"  is  assumed  to  be   a   screen-
oriented interactive AlertDriver; this is normally the case.

...
Integer a;
...
/*temporarily disable information alert
   processing to the screen for a*/
a.ChangeAlertProcFlags(adfINFO, cfoDRIVER | cfoDISABLE);
/*now perform operations on a which are likely to
  generate information alerts*/
...
//enable information alert processing for a
a.ChangeAlertProcFlags(adfINFO, cfoDRIVER | cfoENABLE);
...

The   adfALLALERTS  flag  is  a  combination  of  the   adfERROR,
adfINFO, adfMESSAGE, and adfWARNING flags.

The   adfTIMESTAMP   flag   controls   whether   an   alert    is
timestamped  when  reported.  When  enabled,  this  flag   causes
the   AlertDriver  to  generate  a  string  holding  the  current
date/time  and  appends  the  alert  text  to  that  string.  The
timestamp  is  formatted  with  the  standard  ANSI  C   function
ctime()   (see   the   Class  Library   Reference   chapter   for
details.)  A  typical  timestamped error message  output  through
a TextFileAlertDriver might look like:

Tue Dec 28 15:18:36 1993
ERROR - Literal:  This is an error string.

By  this  point,  you've  no doubt realized  that  a  warning  is
the  only  type  of  alert which needs to return  information  to
the      program.      When     calling      member      function
AlertableObject::HandleWarning(),  you   not   only   specify   a
string  containing  a  question  for  the  user,  but  you   also
indicate  the  default  response  to  the  question  (please  see
the  Class  Library  Reference chapter for details).  If  warning
processing   is   enabled   for   the   object's   first   linked
AlertDriver,  the  question is presented  to  the  user  and  the
response  is  returned.  However,  this  is  one  of  only  three
possible  states  for  the AlertDriver;  warning  processing  may
be   disabled  for  the  AlertDriver,  or  the  object  may   not
currently  be  attached to an AlertDriver. In  the  latter  case,
AlertableObject::HandleWarning()     returns      a      constant
indicating  that  no  AlertDriver  is  attached  to  the  object.
But what should be returned in the former case?

By   default,   if  warning  processing  is  disabled   for   the
AlertDriver,  the  value  returned  is  the  default  value   you
specified.  Your  program  can assume that  the  user  chose  the
default   option  and  execution  continues  normally.   However,
there  may  be  times when you want to know  that  the  user  was
not  given  the  opportunity to make  a  choice.  In  this  case,
you   should  enable  processing  flag  adfDISCLOSURE   for   the
AlertDriver.  When  adfDISCLOSURE is enabled  and  adfWARNING  is
disabled,   calls   to  AlertableObject::HandleWarning()   result
in   a   special   constant   being   returned;   this   constant
indicates   that   processing   for   the   current   alert   was
disabled.

Please          see          the          discussion           of
AlertableObject::HandleWarning()    in    the    Class    Library
Reference   for   full   details  of   that   member   function's
possible  return  values  and  how your  code  should  deal  with
them.

In  most  cases,  the  default  settings  of  each  AlertDriver's
processing   flags  should  be  adequate  for  your  application.
Remember,   when   setting   the   processing   flags   for    an
AlertDriver  which  is  shared  between  objects,  you  will   be
affecting the alert processing for all of those objects.


What About Exception Handling?

Because   exception   handling  (a  fairly   new   C++   language
feature)  is  not  supported  by  all  C++  compilers  (and   not
implemented   consistently  among  those   compilers   which   do
support  it),  we  will  not attempt  to  show  sample  code  for
using  this  feature.  However,  this  does  not  mean  that  the
AlertDriver   Class  Library  is  incompatible   with   exception
handling concepts.

Exception  handling  allows  for the separation  of  a  program's
error-generation    code    from   the   error-reporting/handling
code.   This   is   implemented  through  a  try   block   (which
contains  a  program's/routine's  "normal"  code)  and   one   or
more  catch  blocks  (which handle the  errors  occurring  within
the  try  block.)  Whenever a program exception  (an  exceptional
condition,  such  as  an  error) occurs  within  the  try  block,
the   program  executes  a  throw  (raises  the  exception)   and
control is passed to one of the catch blocks.

Once  the  exception  reaches  the catch  block,  the  exception-
handling  code  can  be  reported using an AlertDriver.  Even  if
your   objects  have  been  written  to  throw  exceptions,  they
themselves  can  catch the exceptions, report  them  using  their
linked   AlertDriver(s),   then  re-throw   the   exceptions   to
higher-level code.

If  you  plan  to  use exception handling in your  C++  programs,
we  suggest  that  you use the AlertDriver  Class  Library  as  a
environment-  and  device-independent means  of  reporting  those
exceptions.  The  concepts  of  the  AlertDriver  Class   Library
are a natural supplement to those of exception handling.


Application Design Techniques - A Summary

By  now,  you've  read  all about the power  and  flexibility  of
the  AlertDriver  Class  Library.  Compiled  below  are  what  we
have   found   to  be  the  most  important  coding  and   design
techniques   to   use   when   writing   applications   for   the
AlertDriver Class Library.
1.Always  invoke  the  appropriate  handling  for  an  alert   in
  the   member   function   in   which   the   alert   is   first
  generated;  this  helps  make your  objects  self-contained  by
  allowing them to process their own alerts.
2.Whenever   possible,  return  error  codes  from  your   member
  functions.  This  practice  allows calling  code  to  determine
  if your member functions were successful.
3.Use   the  preferred  method  of  alerting  whenever  possible.
  This  requires  that  your  class be  designed  so  that  alert
  constants   can   be   defined  early   in   development,   but
  rewards  you  with  highly  reusable code.  By  following  this
  practice,   the   text   for   each   alert   can   be   stored
  externally and/or altered by descendant classes.
4.Use   positive   or   negative  numbers  to   represent   alert
  constants,  but  never  use  zero  (0).  Zero  should  indicate
  that nothing is wrong.
5.Always   try  to  share  AlertDrivers  among  objects  whenever
  possible,   as  this  minimizes  memory  usage.  However,   you
  should  give  an  object  its own (non-shared)  AlertDriver  if
  you  will  be  altering  its processing  flags;  this  practice
  will  prevent  the  inadvertent processing  changes  of  alerts
  from other objects.
6.Use   the  AlertDriver  referenced  by  defaultAlertDriver  for
  environment-independent   alerting   for    non-object-oriented
  code.
7.Always  create  AlertDrivers on the  heap.  When  they  are  no
  longer   used,  they  will  automatically  be  deallocated   by
  the AlertableObject(s) which use them.
8.Link   AlertDrivers  whenever  you  need  to  provide  alerting
  to   multiple  output  devices.  Linking  can  take  place   at
  compile-time or at run-time.
9.Modify   an   AlertDriver's  processing  flags   whenever   you
  need  to  enable  or  disable the output of  certain  types  of
  alerts   either  temporarily  or  for  the  object's  lifetime.
  Processing  flags  can be altered at compile-time  or  at  run-
  time.



Chapter 4           Compiling & Linking
                    
IMPORTANT:       This  chapter  describes  how  to  compile   and
          link   your  programs  to  use  the  AlertDriver  Class
          Library.   You   should  read  this  section   in   its
          entirety    before   using   the   AlertDriver    Class
          Library.


Supported Compilers & Class Libraries

As  of  the  printing  of  this  manual,  the  AlertDriver  Class
Library   has   been  successfully  tested  with  the   following
compilers/class libraries:
  Borland   C++   v3.1  (text  mode,  Container  Class   Library,
  Turbo Vision, ObjectWindows)
  Microsoft C/C++ v7.0 (text mode)

Other  untested  compilers/class libraries may  be  supported  in
text   mode.   You   should   read  the   supplied   file   named
"README.1ST"   on   the  distribution  disks   for   the   latest