home *** CD-ROM | disk | FTP | other *** search
/ Gold Fish 3 / goldfish_volume_3.bin / files / dev / e / amigae / src / class / scrollwin / sc.doc next >
Text File  |  1994-11-08  |  4KB  |  110 lines
  1. sc.m and sctext.m: scrolling windows. [see also: textview.e]
  2.  
  3. The object `scrollwin' contained in sc.m is a general purpose window with
  4. scrollbars that will display any items of information.  `scrolltext' in the
  5. module sctext.m inherits from scrollwin and implements a scrolling window with
  6. text.  It is very easy (and encouraged) to inherit from either of these
  7. objects and implement your own scrolling windows (EDBG, for example, uses two
  8. further objects that inherit from scrolltext and display memory/registers).
  9.  
  10. members and methods of OBJECT scrollwin:
  11.  
  12.     NEW scrollwinptr.open(title,x,y,sx,sy,screen=NIL,ownidcmp=0,ownhandle=NIL)
  13.  
  14. The constructor is called with some obvious arguments.  With ownidcmp you can
  15. for example attach menus to the window.  ownhandle is a callback PROC with one
  16. arg (the intuimessage).  Will raise "scrl" if it can't get what if wants
  17. (window etc.).
  18.  
  19.     quit:=handle()
  20.  
  21. will handle messages to the window.  May call your callback or some of the
  22. extra_ methods below.  If quit=TRUE the user clicked the close gadget.
  23.  
  24.     END scrollwinptr
  25.  
  26. closes the window.
  27.  
  28.     refreshwindow()
  29.  
  30. refresh the window manually if you change something about the data
  31. represented.  normally this is done by the window automatically.
  32.  
  33. The extra_ methods are the ones you are supposed to override to implement the
  34. display of the actual data (if you just want to use scrolltext, skip these):
  35.  
  36.     extra_init(screen)
  37.  
  38. called from open(). Do any initialisations here if you wish.
  39.  
  40.     extra_exit()
  41.  
  42. same for end().
  43.  
  44.     px,py:=extra_unit()
  45.  
  46. called by the object when it wants to know how big the items being displayed
  47. are (i.e.  (1,1) for pixels, (fontwidth,fontheight) for text etc.).  The
  48. default method returns (1,1).
  49.  
  50.     ux,uy:=extra_max()
  51.  
  52. called by the object to ask the number of objects being displayed. this
  53. should be somewhere between (1,1) and (32767,32767).
  54.  
  55.     extra_refresh(x,y,xsize,ysize,xoff,yoff,win:PTR TO window)
  56.  
  57. The core.  This method is called when the area of your data denoted by
  58. (x,y,xsize,ysize) is currently visible (problably because the user scrolled it
  59. there), and needs to be rendered.  Note that these four numbers are in units
  60. of your data, not pixels!  You can use `win' to render the data, from (pixel)
  61. offsets (xoff,yoff) in the window.
  62.  
  63. As an example, say you're displaying a text with a font of 8x8 pixels, the
  64. text has 100 lines and 80 columns.  The user has resized the window such that
  65. it has space for 10 lines of text and 40 columns, and scolled to the middle of
  66. it.  The call will then look like (for example):
  67.  
  68. extra_refresh(20,45,40,10,12,4,win)
  69.  
  70. the area to be rendered is thus (320,80) in size.  Of course you can optimize
  71. refreshing by using scrolling instead of re-rendering, you should implement
  72. this yourself though (scrolltext does that).
  73.  
  74.     ux,uy:=where(px,py)
  75.  
  76. finds the element denoted by those (pixel) coordinates, as you might receive
  77. them in an intuimessage on a mouse click.  The returned 2 coordinates take
  78. care of position of the scrollers and unit size.
  79.  
  80.     settop(newtop=0,dorefresh=TRUE)
  81.  
  82. manually sets the top of the area being displayed. do not use too often
  83. as it might confuse the user.
  84.  
  85.     window:PTR TO window
  86.  
  87. the only instance variable. careful when using this.
  88.  
  89. The scrolltext object inherits from scrollwin.  You should call open / handle
  90. / end etc. on it as usual.  scrollwin redefines the extra_ methods of
  91. scrollwin to implement text-specific scrolling.  Following methods are added:
  92.  
  93.     settext(textlist,width)
  94.  
  95. The constructor for this object.  textlist should be an E list of
  96. nil-terminated strings.  width is the maximum width to display, i.e.  usually
  97. the maximum width of these strings.  Call open() as the first method after
  98. this one.
  99.  
  100.     active(cur,dorefresh=TRUE)
  101.  
  102. Will set the current active line. This will be graphically marked by inverting the
  103. line. If this method is never called there will be no active line display.
  104.  
  105.     uy:=getactive()
  106.  
  107. asks what the currently active line is.
  108.  
  109. as an example of all this, please see the extremely simple textview.e
  110.