home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD2.iso / Misc / bgui.lzx / bgui / docs / externalclass.doc < prev    next >
Encoding:
Text File  |  1995-04-24  |  5.5 KB  |  154 lines
  1.  
  2.                File: externalclass.doc
  3.         Description: Externalclass documentation.
  4.           Copyright: (C) Copyright 1994-1995 Jaba Development.
  5.                      (C) Copyright 1994-1995 Jan van den Baard.
  6.                      All Rights Reserved.
  7.  
  8. ------------------------------------------------------------------------------
  9.  
  10. TABLE OF CONTENTS
  11.  
  12. externalclass/--background--
  13. externalclass/Methods
  14. externalclass/Attributes
  15.  
  16. externalclass/--background--                      externalclass/--background--
  17.  
  18.     NAME
  19.         Class:          externalclass
  20.         Superclass:     baseclass
  21.         Include File:   <libraries/bgui.h>
  22.  
  23.     FUNCTION
  24.         To provide an interface class which can be used to include third-party
  25.         gadget  classes  like  the colorwheel.gadget in a BGUI user interface.
  26.         Notification  is  currently only possible via the WM_ADDUPDATE method.
  27.         See  the  windowclass  documentation  for  more  information  on  this
  28.         subject.
  29.  
  30. externalclass/Methods                                    externalclass/Methods
  31.  
  32.     NEW METHODS
  33.         None.
  34.  
  35.     CHANGED METHODS
  36.         None.
  37.  
  38. externalclass/Attributes                              externalclass/Attributes
  39.  
  40.     NAME
  41.         EXT_Class -- ( Class * ), EXT_ClassID -- ( STRPTR )
  42.  
  43.     FUNCTION
  44.         Set  the  class  from  which this class needs to create an object. The
  45.         EXT_Class attribute expects a pointer to an already initialized class.
  46.         The EXT_ClassID expects the name of the public class like for instance
  47.         "colorwheel.gadget".  Please  note  that  _you_  are  responsible  for
  48.         opening and closing the class library yourself.
  49.  
  50.         Default NULL. Applicability is (I).
  51.  
  52.     NAME
  53.         EXT_MinWidth, EXT_MinHeight -- ( ULONG )
  54.  
  55.     FUNCTION
  56.         As  external  classes  normally  do  not  understand the layout engine
  57.         methods  used  by  BGUI  it  has  to  be  helped  a little. With these
  58.         attributes  you  set  the  minimum  width  and  height of the external
  59.         object.  It is very important to set reasonable values here because no
  60.         checks are made.
  61.  
  62.         Default is 0 (stupid size). Applicabilty is (I).
  63.  
  64.     NAME
  65.         EXT_TrackAttr -- ( Tag )
  66.  
  67.     FUNCTION
  68.         To  tell which attributes from the external object need to be tracked.
  69.         Because some external classes, like the colorwheel, cannot change size
  70.         once  created  it  is necessary that the externalclass  re-creates the
  71.         object  at  each  size  change. As this usually means that the current
  72.         external  object  settings are lost you can tell which attributes need
  73.         to be tracked.
  74.  
  75.         The  tracked  attributes are obtained by sending the external object a
  76.         OM_GET  method  for  each  of the attributes. This means that the only
  77.         attributes  that  can be tracked are the ones that are gettable on the
  78.         external object. There is no limit as to the number of attributes that
  79.         are trackable.
  80.  
  81.         You  can also pass attributes that are ment for the external object at
  82.         initialization time. These attributes are remembered by this class and
  83.         re-used at each re-creation of the external object.
  84.  
  85.         Example:
  86.  
  87.         Object          *wheel;
  88.         struct Screen   *screen;
  89.  
  90.         /*
  91.         **      Create a "colorwheel.gadget" external object.
  92.         **/
  93.         wheel = ExternalObject,
  94.                 EXT_MinWidth,                   30,
  95.                 EXT_MinHeight,                  30,
  96.                 EXT_ClassID,                    "colorwheel.gadget",
  97.                 WHEEL_Saturation,               0,
  98.                 WHEEL_Screen,                   screen,
  99.                 EXT_TrackAttr,                  WHEEL_Saturation,
  100.                 EXT_TrackAttr,                  WHEEL_Hue,
  101.         EndObject;
  102.  
  103.         All   tags   defined  above  are  saved  (including  the  tags  passed
  104.         automatically by the ExternalObject macro). Now a seperate copy of the
  105.         attributes to track is created.
  106.  
  107.         Once  the object needs to be re-created the  first  thing what is done
  108.         is getting the tracked attributes values from the old object.
  109.  
  110.         Now  the  old  object  is  disposed  of  and a new one is created with
  111.         exactly the same attributes that where passed at initialization time.
  112.  
  113.         Once  this  is  accomplished the tracked attributes are set to the new
  114.         object.
  115.  
  116.         Please note that tracking attributes  is only  necessary with  classes
  117.         that require a rebuild of the object when it is resized.
  118.  
  119.         Applicability is (I).
  120.  
  121.     BUGS
  122.         The  EXT_xxx  attributes from the initialization tags are not filtered
  123.         out of the saved tag list.
  124.  
  125.     SEE ALSO
  126.         EXT_NoRebuild
  127.  
  128.     NAME
  129.         EXT_Object -- ( Object * )
  130.  
  131.     FUNCTION
  132.         Get  a  pointer  to  the "real" external object. Please note that this
  133.         pointer changes at every size change.
  134.  
  135.         Applicability is (G).
  136.  
  137.     NAME
  138.         EXT_NoRebuild -- ( BOOL )
  139.  
  140.     FUNCTION
  141.         To tell the external class that the external object  does not  have to
  142.         be rebuild after a re-size. Most classes are smart enough to  handle a
  143.         re-size  of the  object  themselves  but  there are  classes  like the
  144.         colorwheel.gadget that requires a rebuild uppon a size change.
  145.  
  146.         When this   attribute   is   set  to  TRUE the class will not re-build
  147.         the external  object  and  you  do  not  need to use the EXT_TrackAttr
  148.         attributes to handle the object settings.
  149.  
  150.         Default is FALSE. Applicability is (I).
  151.  
  152.     SEE ALSO
  153.         EXT_TrackAttr
  154.