home *** CD-ROM | disk | FTP | other *** search
/ Otherware / Otherware_1_SB_Development.iso / amiga / misc / vcb10a.lha / vcb.doc < prev    next >
Text File  |  1992-10-29  |  19KB  |  463 lines
  1.  
  2.      VCB(1)                AM*GA Programmer's Manual                 VCB(1)
  3.  
  4.  
  5.  
  6.      ¢1mNAME 
  7.           ¢0mVCB 
  8.  
  9.      ¢1mVERSION 
  10.           ¢0m1.0a beta 
  11.  
  12.      ¢1mDESCRIPTION 
  13.           VCB ¢0mstands  for  Virtual  Co-ordinate  Box.    There  is  an
  14.           every-day example for its use right at hand:  the  Workbench
  15.           windows.  
  16.  
  17.           The  user  peeps  through their rectangular inner box onto a
  18.           ¢1mvirtual ¢0m(i.e. seemingly real,  but  not  there)  plane  that
  19.           infinitely extents into all directions and on which icons of
  20.           files and  drawers  lie at certain ¢1mvirtual co¢0m-¢1mordinates¢0m.  By
  21.           means of the scrollers within the window borders,  the  user
  22.           can  shift  the box around on the virtual plane, causing new
  23.           things to appear in the window.  
  24.  
  25.           Another example would be a  text  editor.    Once  you  have
  26.           entered more text that the window can hold, the text extents
  27.           beyond  the window's bounds on its ¢3mvirtual, ¢0marbitrarily long
  28.           fanfold paper.  Then  you  will  use  the  scroll  bar  that
  29.           normally  is  attached  to the right border of the window to
  30.           look at different parts of your text.  
  31.  
  32.           Almost  every  application  program  that  operates  on   an
  33.           arbitrarily  extensible project data base and that employs a
  34.           graphical user interface will use  the  virtual  co-ordinate
  35.           plane ¢3mmetaphor ¢0mto display its data.  
  36.  
  37.           Now  VCB  allows programs not only to share the concept, but
  38.           also the code!  
  39.  
  40.           VCB is a BOOPSI class implementation in shape of  a  scanned
  41.           library (for Manx/Aztec C).  
  42.  
  43.           At present this class is still `private┤ in the sense that I
  44.           do not provide code that adds it to the system's public pool
  45.           of  named  classes  and  therefore  is  not  accessible by a
  46.           symbolic name.  
  47.  
  48.           After some experiences in its use have  been  collected  and
  49.           possible  bugs  habe  been  fixed,  it  will be submitted to
  50.           Commodore Amiga for becoming a public BOOPSI  class  with  a
  51.           registered name.  This name will probably be "vcbgclass" (it
  52.           is a  descendant  of "gadgetclass").  Maybe some day it will
  53.           even be part of the OS itself (Intuition ¢3mshould ¢0mprovide such
  54.           a service).  
  55.  
  56.           You should link the library to your client code in order  to
  57.           create VCB  gadgets and attach them to your windows.  Such a
  58.           gadget consists  of  horizontal  and/or  vertical  scrollers
  59.           (that  look  almost  identical  to  those  within  Workbench
  60.           windows) and the box in which your  data  will  be  visible.
  61.           You  have  to  supply  a hook to a function of your own that
  62.           will do the actual rendering within the box according to the
  63.  
  64.  
  65.      KosmoSoft                        -1-
  66.  
  67.  
  68.      VCB(1)                AM*GA Programmer's Manual                 VCB(1)
  69.  
  70.  
  71.           `instructions┤ the gadget gives it.  The internals  of  that
  72.           function are  completely  ¢3mup  to  you!    ¢0mIt  just  makes no
  73.           difference to that gadget whether you are going  to  display
  74.           text, graphics,  a  musical  score  etc.   or all of them at
  75.           once!  
  76.  
  77.  
  78.      ¢1mUSAGE 
  79.           ¢0mUsing VCB starts with creating the BOOPSI  class.    You  do
  80.           this   by   calling  the  library  function  initVCBClass().
  81.           freeVCBClass() will free that class again.   Once  you  have
  82.           the  class,  you  can  create as many instances (gadgets) of
  83.           that class as you want by calling NewObject().  
  84.  
  85.           As each of Intuition's own classes defines certain  specific
  86.           tags  for setting up the instance as the client needs it, so
  87.           does VCB. Here are the 
  88.  
  89.      ¢1mTAGS 
  90.        ¢0mVCBGA_ExposureHook (struct Hook *) 
  91.           áááááthe hook to your rendering function (see  the  CALLBACK
  92.           section below).  
  93.  
  94.        VCBGA_Interim (BOOL) 
  95.           áááááTRUE (1) indicates that the display should update while
  96.           aáscrolleráis  moved  or a button repeats, not only when the
  97.           scrolleráorábuttonáis released.  Think twice before  setting
  98.           thisáflag!ááAlthoughátheáexposure hook only gets called when
  99.           theádisplayáactuallyáchangesá(andánotáoná¢3meveryá¢0mmouse  move),
  100.           there may be quite a lot of invocations  to  your  rendering
  101.           áááááfunction.ááIfáyourárenderingáfunction takes too long to
  102.           complete,átheásystemámayáchokeáwithápendingámouse       move
  103.           events.  
  104.  
  105.        VCBGA_HScroller (BOOL) 
  106.           áááááTRUE  (1)  indicates  that  you   want   a   horizontal
  107.           scroller.  
  108.  
  109.        VCBGA_VScroller (BOOL) 
  110.           áááááTRUE (1) indicates that you want a vertical scroller.  
  111.  
  112.           áááááWithout  the  scroller, you cannot move the display box
  113.           overátheávirtualáplaneáináthatádirectioná¢3mmanually,á¢0mbut 
  114.           besidesáthatáthereáisánoádifferenceá(you can still  move  it
  115.           via SetGadgetAttrs()).  
  116.  
  117.        VCBGA_HBorder (BOOL) 
  118.           áááááTRUE  (1)  put horizontal scroller (if any) into bottom
  119.           border of the host window.  
  120.  
  121.        VCBGA_VBorder (BOOL) 
  122.           áááááTRUE (1) put vertical  scroller  (if  any)  into  right
  123.           border of the host window 
  124.  
  125.           áááááNote:  Setting the VCBGA_H/VBorder flag will adjust the
  126.           windowábordersátoáaccommodateáthe  scroller,  it  will   not
  127.           resizeáyourágadgetáináanyáway.áá(see also example).  
  128.  
  129.  
  130.  
  131.      KosmoSoft                        -2-
  132.  
  133.  
  134.      VCB(1)                AM*GA Programmer's Manual                 VCB(1)
  135.  
  136.  
  137.        VCBGA_HUnit (ULONG) 
  138.           áááááthe  number  of pixels that make one virtual horizontal
  139.           co-ordinate unit.  
  140.  
  141.        VCBGA_VUnit (ULONG) 
  142.           áááááthe number of pixels that  make  one  virtual  vertical
  143.           co-ordinate unit.  
  144.  
  145.        VCBGA_HTotal (ULONG) 
  146.           áááááthe  horizontal extension of the virtual plane measured
  147.           in virtual units.  
  148.  
  149.        VCBGA_VTotal (ULONG) 
  150.           áááááthe vertical extension of the virtual plane measured in
  151.           virtual units.  
  152.  
  153.           áááááIn this version, VCB cannot emulate  Workbench  windows
  154.           whicháfeatureáanáinfinitely large    virtual   plane.      I
  155.           personallyádon'táneedáthisá(now),ábutáI  will  add   it   if
  156.           someone misses it.  
  157.  
  158.        VCBGA_HOffset (ULONG) 
  159.           áááááthe  current  horizontal co-ordinate of the left border
  160.           ofátheádisplayábox,ámeasured in virtual units.  
  161.  
  162.        VCBGA_VOffset (ULONG) 
  163.           áááááthe current vertical co-ordinate of the left border  of
  164.           theádisplayábox,ámeasured in virtual units.  
  165.  
  166.           In  addition  to  these,  all tags that apply to the general
  167.           ¢1mgadgetclass ¢0mremain active as well, of course.  
  168.  
  169.           To create the imagery for the scrollers, two additional tags
  170.           should be  provided.    The  tag  values  are   defined   in
  171.           <intuition/imageclass.h>.  
  172.  
  173.           These  are  SYSIA_DrawInfo (struct DrawInfo *) (you get/free
  174.           the           DrawInfo            structure            using
  175.           GetScreenDrawInfo()/FreeScreenDrawInfo,  see  AutoDocs)  and
  176.           SYSIA_Size (SYSISIZE_...).  While a missing  SYSIA_Size  tag
  177.           is   defaulted   to   SYSISIZE_MEDRES   (Workbench   default
  178.           resolution),  a  missing  SYSIA_DrawInfo  tag   will   cause
  179.           NewObject() to fail.  
  180.  
  181.           There   are  five  further  tags  that  refer  to  read-only
  182.           attributes (ignored by SetGadgetAttrs(), but retrievable  by
  183.           GetAttr()): 
  184.  
  185.        VCBGA_HSize (ULONG), VCBGA_VSize (ULONG) 
  186.           áááááthe  number of units (as defined by VCBGA_H/VUnit) that
  187.           currentlyáfitáintoáthe display box  horizontally/vertically.
  188.           ForáVCBsáwitháGFLG_RELWIDTH   /   GFLG_RELHEIGHT  set  these
  189.           valuesáchangeáeachátimeátheáwindowáis resized.  
  190.  
  191.        VCBGA_XOrigin (ULONG), VCBGA_YOrigin (ULONG) 
  192.           áááááthe current co-ordinates of the left top corner of  the
  193.           displayáboxá(whereádataáisádisplayed)áwithin  the  rastport.
  194.           NoteáthatáthisávaluesáchangeáforáVCBsáwitháGFLG_RELRIGHT   /
  195.  
  196.  
  197.      KosmoSoft                        -3-
  198.  
  199.  
  200.      VCB(1)                AM*GA Programmer's Manual                 VCB(1)
  201.  
  202.  
  203.           GFLG_RELBOTTOMásetáeachátimeátheáwindowáisáresized.ááThe 
  204.           renderingáfunctionámust  get  this  values  every time it is
  205.           invokedáandáuseáthemáináeveryárenderingáoperation as offsets
  206.           to the rastport's origin.  
  207.  
  208.        VCBGA_Semaphore (struct SignalSemaphore *) 
  209.           áááááThis returns the address of a SignalSemaphore structure
  210.           thatátheáclientácodeámust obtain if it is  going  to  modify
  211.           dataástructuresáthatátheárenderingáfunction  relies  on (see
  212.           ARBITRATION section below).  
  213.  
  214.  
  215.      ¢1mCALLBACK 
  216.  
  217.           ¢0mThe callback function will receive arguments  in  the  usual
  218.           form: the hook pointer, an `object┤ and a command message.  
  219.  
  220.           The   `object┤  is  the  usual  public  handle  to  the  VCB
  221.           instance.  You will need this to retrieve geometric data via
  222.           GetAttr() (the VCB structure is ¢3mprivate, ¢0mI'm doing this  the
  223.           clean way, despite the overhead).  See the example.  
  224.  
  225.           The  message  pointer  refers  to  an  ExposureMsg structure
  226.           (defined in vcb.h).  It contains  a  command  ID  (the  only
  227.           defined  command  ID  is  VCBCMD_RENDER, but better test for
  228.           this ID explicitly), a pointer to the  rastport  into  which
  229.           the renderings go and left, top, width and height values for
  230.           the  rectangle  that has to be (re-)drawn. An `exposure┤ has
  231.           occured if the bitmap contents do no longer reflect the data
  232.           that is located at the respective position  on  the  virtual
  233.           plane.    Possible   reasons  are  that  the  window  wasn't
  234.           previously open or was exposed by some  other  window  going
  235.           away  or  that  the display box moved to another position on
  236.           the virtual plane (either by manipulation of  the  scrollers
  237.           or by a client request via SetGadgetAttrs()).  
  238.  
  239.           The  left, top, width and height values are in virtual units
  240.           and have to be multiplied with the respective unit values to
  241.           yield pixel dimensions.  
  242.  
  243.           Be aware that callback code is hazardous area!    There  are
  244.           some things that ¢3mmust ¢0mbe avoided.  
  245.  
  246.           The execution  time  of  this  function  is  critical.   The
  247.           functionality of the whole user interface  depends  on  that
  248.           your function completes as quickly as possible.  Prepare all
  249.           information  needed  for  rendering  in advance and store it
  250.           where the function can get it (please read  the  ARBITRATION
  251.           section below,  too).    Better  to consume some more memory
  252.           than to freeze the user interface.  
  253.  
  254.           Do not call dos.library  functions  directly  or  indirectly
  255.           from the  rendering function!  This function executes in the
  256.           context of the input device's task!  
  257.  
  258.           Likewise,  do  not  directly  or  indirectly   call   Wait()
  259.           (deadlock imminent).    This  implies that you cannot employ
  260.           console.device to do text rendering!  
  261.  
  262.  
  263.      KosmoSoft                        -4-
  264.  
  265.  
  266.      VCB(1)                AM*GA Programmer's Manual                 VCB(1)
  267.  
  268.  
  269.  
  270.           If you have to debug this  part  of  your  code,  never  use
  271.           printf() or  fprintf()!    Try to kprintf() to a terminal or
  272.           record to an internal data structure and evaluate it later.  
  273.  
  274.           Nonetheless, do the things that are necessary: Please do not
  275.           make any assumptions on the state that the  rastport  is  in
  276.           when your function is called.  Setup the rastport explicitly
  277.           before you start rendering.  In particular, set the pens and
  278.           the draw mode where appropriate (text, vector drawings, area
  279.           drawings), set the line pattern for vector drawings, set the
  280.           area pattern   for   area  drawings.    Certainly  I  forgot
  281.           something,  so  please  read  through  the   docs   of   the
  282.           graphics.library  functions  that  you  use to find out what
  283.           they depend on.  Even if the OS does not make  use  of  some
  284.           rastport features  now,  it may do so in the future.  We are
  285.           all suffering the  system  font  dependency  of  pre-OS  2.0
  286.           software now.  Let this be a lesson to us!  
  287.  
  288.           If you are using the small memory model, please call geta4()
  289.           right at  the  beginning  of your exposure function!  It may
  290.           work without ¢3mnow ¢0mbut will not continue to work in the future
  291.           (it will definitely not work when VCB is a public class).  
  292.  
  293.           ¢1mNever ¢0mturn stack depth  checking  on  for  the  module  that
  294.           contains your   exposure   function!      It   would   check
  295.           input.device task's stack  and  that  seems  to  unavoidably
  296.           crash the machine.  
  297.  
  298.  
  299.      ¢1mARBITRATION 
  300.  
  301.           ¢0mThe callback function executes on another task's context and
  302.           time slice.    If  it  relies  on  data  that is going to be
  303.           changed by the client task (which is most probably the  case
  304.           if  it  is  a  project data base that is being edited by the
  305.           user), the client task has to arbitrate for the write access
  306.           to that data (read access is free for the client  since  the
  307.           callback code is not supposed to modify any static data).  
  308.  
  309.           To  that purpose, a SignalSemaphore structure is part of the
  310.           VCB instance  data.     The   semaphore   is   automatically
  311.           initialized during  the  processing  of  NewObject().    The
  312.           gadget only performs a  callback  if  an  AttemptSemaphore()
  313.           succeeds.   It  calls  ReleaseSemaphore() after the callback
  314.           completes.  
  315.  
  316.           Thus to prevent the gadget from rendering data that is being
  317.           modified, the client  must  wait  for  ObtainSemaphore()  to
  318.           return  (which  should  happen  as  soon  as  the user stops
  319.           fiddling with the VCB's  scrollers  or  moving/resizing  the
  320.           window).   As long as the client possesses the access right,
  321.           the gadget's display will not be updated, even  not  due  to
  322.           client calls to SetGadgetAttrs().  
  323.  
  324.           The  pointer  to the semaphore must be retrieved by GetAttr(
  325.           VCBGA_Semaphore, ... ) (see TAGS and example program).  
  326.  
  327.  
  328.  
  329.      KosmoSoft                        -5-
  330.  
  331.  
  332.      VCB(1)                AM*GA Programmer's Manual                 VCB(1)
  333.  
  334.  
  335.      ¢1mEXAMPLE PROGRAM 
  336.           ¢0mThere  is  a  simple   test   program   included   in   this
  337.           distribution, named test.c.  It does not do anything useful,
  338.           but it  shows  how  to  write  a  VCB client.  The rendering
  339.           function exposure() simply draws a cross into the  rectangle
  340.           that it  should  refresh,  just to visualize the idea.  test
  341.           opens a window with  scrollers  in  its  borders  that  look
  342.           almost identical to Workbench scrollers (the only difference
  343.           is  that  the  horizontal  scroller  starts  at  a  slightly
  344.           different offset from the window's left edge, respecting the
  345.           window's left  border  which  Workbench  does  not).     The
  346.           parameters  necessary  for  this  Workbench-look  can all be
  347.           found in the NewObject() taglist.  By clicking on the  close
  348.           gadget  repeatedly  you  can  run  through  a number of test
  349.           operations: Prior to that, resize the window to  be  smaller
  350.           than the  cross  that  is  initially visible.  Note that the
  351.           scrollers now indicate that there is more `data┤  than  what
  352.           is being displayed.  
  353.  
  354.           Click the close gadget.  This changes the horizontal offset,
  355.           causing  the  box contents to `scroll┤. If the offset change
  356.           conserves some old imagery, then VCB will ScrollRaster()  it
  357.           to  its  new  place  within the display box and only refresh
  358.           those areas blanked out by the scroll.  If the jump  is  too
  359.           far, it simply runs a complete redraw.  
  360.  
  361.           Click again  and  again and again and again.  The horizontal
  362.           and vertical totals (the number units that the virtual plane
  363.           extends horizontally and vertically) have changed to 3,  10,
  364.           20 and finally 30.  
  365.  
  366.           Click again.    The  program  fetches  the VCB semaphore and
  367.           obtains it.  Now moving the  scroll  bars  or  pressing  the
  368.           buttons has  no visual effect.  Note however that pressing a
  369.           button will still move  the  associated  scroll  bar  -  the
  370.           gadget is still alive!  If you do something with the window,
  371.           the display box contents will decay.  
  372.  
  373.           Click again.    The program releases the VCB semaphore again
  374.           and calls RefreshGList().  Now  the  gadget  updates  itself
  375.           according to  the  new  scroller  positions.   Releasing the
  376.           semaphore ¢3malone ¢0mdoes not trigger any display  refresh.    To
  377.           get an immediate update, you need to call RefreshGList().  
  378.  
  379.           Click again and the program terminates.  
  380.  
  381.  
  382.      ¢1mMORE EXAMPLES 
  383.           ¢0mA  real,  complex  VCB  application  is about to be publicly
  384.           released: The View-Handler which is a AmigaDOS  device  that
  385.           displays text  written to it in a window, using a VCB.  Look
  386.           for it on anonymous ftp sites (probably first in Germany).  
  387.  
  388.  
  389.      ¢1mADDITIONAL DOCUMENTATION 
  390.           ¢0mThe internally used VCX BOOPSI  class  (which  provides  the
  391.           scroll bars)  is  now  also  documented.    Please check the
  392.           README file for details.  
  393.  
  394.  
  395.      KosmoSoft                        -6-
  396.  
  397.  
  398.      VCB(1)                AM*GA Programmer's Manual                 VCB(1)
  399.  
  400.  
  401.  
  402.  
  403.      ¢1mSEE ALSO 
  404.           ¢0mRKM Libraries, BOOPSI documentation.  
  405.  
  406.  
  407.      ¢1mBUGS 
  408.           ¢0mPlease read the BUGS file being part  of  this  distribution
  409.           for details on known deficiencies of this software.  
  410.  
  411.           I  would  appreciate  reports of unknown bugs, in particular
  412.           (but not  only)  if  they  showed  up  in  a  more  uncommon
  413.           application of this stuff.  
  414.  
  415.  
  416.      ¢1mCONTACT 
  417.           ¢0mStefan  Reisner, Aachener Stra▀e 399, 5000 K÷ln 41, Germany,
  418.           internet srph-cip.uni-koeln.de 
  419.  
  420.  
  421.  
  422.  
  423.  
  424.  
  425.  
  426.  
  427.  
  428.  
  429.  
  430.  
  431.  
  432.  
  433.  
  434.  
  435.  
  436.  
  437.  
  438.  
  439.  
  440.  
  441.  
  442.  
  443.  
  444.  
  445.  
  446.  
  447.  
  448.  
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.  
  459.  
  460.  
  461.      KosmoSoft                        -7-
  462.  
  463.