[Contents] [Index] [Help] [Browse <] [Browse >]


Included with the AMarquee distribution is a C++ "wrapper" class
that you can use if you wish, instead of invoking the amarquee.library 
calls directly.  

Amarquee.library usage maps nicely to a C++ object:

 - Using amarquee.library directly, you allocate a struct QSession,
   call functions to which you pass a pointer to your QSession struct,
   then call QFreeSession() to free the QSession struct when you
   are done.
   
 - Using the Session class, you create a new Session object, 
   call methods on the Session object, then delete the object
   when you are done.
   
Advantages of using the Session class over the straight C
API include:  

 - Const correctness.  The Session class API uses const where
   appropriate.
 - Convenient default arguments are implemented where appropriate.
   For example, the C call QGo(qsession, 0L) can be written
   in as session->go(), saving you a few keystrokes.
 - You can put Session objects on the stack, and be sure
   that they are properly allocated and freed at the correct times.
 - No performance penalty.  All Session methods are inline, so
   using a Session is really no slower than calling the C functions
   directly.
 - Since all the code needed to implement the Session class is 
   included in Session.h, it is easy to modify the Session class 
   to suit your tastes.
   
Disadvantages of the Session class:

 - It requires a C++ compiler.
 - It hasn't been run-tested.  (This is because I don't have
   a C++ compiler on my Amiga)  Nonetheless, I am fairly confident
   it is bug free, and if you look in Session.h you'll see why--
   almost all the methods are one-line pass-thrus to the C API.

Exception throwing in the Session class:

 - Exceptions are only thrown by one method in the Session class--
   the class constructor.  All other methods register failure (where
   applicable) by returning the same return codes that the C API does.
   The class constructor will throw a SessionCreationFailedException
   (also defined in Session.h) if it cannot allocate the internally
   held QSession struct. 
 - If you don't like using exceptions in C++,
   there are static methods in the Session class that you can
   use to create instead of the Session constructor to allocate
   a Session object.  These methods are named very similarly
   to their C API counterparts, and work the same way:  They
   return a pointer to a newly allocated Session object on
   success, or NULL on failure.  See Session.h for more info.
   
Note that you CANNOT cast a Session to a (struct QSession), nor
can you cast a (Session *) to a (struct QSession *).  A Session
object holds a (struct QSession *), but does not derive from it.

Note also that you must still open and close amarquee.library (v49+)
yourself--the Session class does not do it for you.


Converted on 24 Mar 2002 with RexxDoesAmigaGuide2HTML 2.1e(private) by Michael Ranner.