Autodocs/songclass.doc

   1 TABLE OF CONTENTS
   2
   3 songclass/--background--
   4 \fsongclass/--background--                             songclass/--background--
   5
   6     NAME
   7         songclass -- XModule 'boopsi'-oriented song implementation.
   8
   9     DESCRIPTION
  10         The song class is an object oriented way to handle a song.  The song
  11         class handles all data storing mechanisms for you and adds a layer
  12         of abstraction between the song internal data structures and the
  13         application.  The advantage is that the internal structures can be
  14         changed while keeping compatibility with existing software.
  15
  16         Another great advantage of being a 'boopsi' class is that the song
  17         can notify other boopsi objects whenever its attributes change.
  18         This simplifies the task of keeping the user interface updated each
  19         time the user (or an ARexx macro, or whatever) changes something.
  20
  21         For speed reasons, the song class does also allow 'white box'
  22         istance access.  This means that you can also directly access
  23         the internal data structures of the song, without using standard
  24         boopsi methods.  You are ONLY allowed to READ public fields, but not
  25         to write any of them.  The main reason to forbid direct writing is
  26         that the song class must send notifications to its targets, but it
  27         does also allow the song implementation to change in future version
  28         without breaking existing applications.
  29
  30         When you create a new istance of the song class, the object handle
  31         you get is actually a SongInfo structure.  This is only possible
  32         because the song class is a subclass of the rootclass, whose istance
  33         is placed at a negative offset in the object handle.
  34         Future song class implementations could require to be subclasses
  35         of other classes, such as the gadget class or even the datatypes
  36         class.  This problem will be probably got around by keeping the
  37         root class as the real superclass of the song and creating an
  38         istance of the other superclass which will be passed all the
  39         methods which are not recognized by the song its-self.  Call this
  40         boopsi polymorphism, if you like to :-)
  41
  42     QUOTATION
  43         Don't be a tuna head.
  44
  45 \f