home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 4 / DATAFILE_PDCD4.iso / utilities / utilsd / evntshell / Docs / Draw < prev    next >
Encoding:
Text File  |  1995-11-11  |  14.7 KB  |  570 lines
  1. --------------------------------------------------------
  2.  
  3. Draw units
  4. The units used by the DrawLib routines can
  5. be specified in several different units.
  6. Choosing units can be achieved with the
  7. following calls :
  8.  
  9. PROCshell_DrawSetUnitsMM millimeters
  10. PROCshell_DrawSetUnitsCM centimeters
  11. PROCshell_DrawSetUnitsIN inches
  12. PROCshell_DrawSetUnitsOS OS units
  13. PROCshell_DrawSetUnitsPT points
  14.  
  15. Drawfiles are created in millimeters by
  16. default.
  17.  
  18. --------------------------------------------------------
  19.  
  20. PROCshell_DrawCreateFile
  21. Params =>
  22.          int address of drawfile buffer
  23.              (contents ignored on entry)
  24.  
  25.        <=
  26.          address of drawfile buffer is
  27.          updated
  28.  
  29. The drawfile is created in a RAM buffer,
  30. the address of which is returned by the
  31. routine. As objects are added to the file
  32. the address of the buffer may change.
  33.  
  34. At any time the buffer contains a valid
  35. drawfile that can be displayed with
  36. PROCshell_DrawRenderFile.
  37.  
  38. Multiple drawfiles can be created at the
  39. same time, adding objects to a particular
  40. drawfile is achieved by specifying the
  41. buffer address.
  42.  
  43. --------------------------------------------------------
  44.  
  45. PROCshell_DrawRenderFile()
  46. Params =>
  47.          int  address of drawfile buffer
  48.          int  x coordinate to render drawfile
  49.               (os units)
  50.          int  y coordinate to render drawfile
  51.               (os units)
  52.          int  address of wimp redraw block
  53.          bool bounding box flag (TRUE to show object
  54.               bounds, otherwise FALSE)
  55.               
  56. This routine renders (plots) a drawfile which must
  57. be loaded into a buffer using PROCshell_DrawLoadFile,
  58. or created by the user application with
  59. PROCshell_DrawCreateFile.
  60.  
  61. The drawfile is always plotted relative to the current
  62. graphics origin. The scale of the drawfile can be set
  63. using PROCshell_DrawSetScale beforehand. Loading or
  64. creating a new file sets the scale to 1:1.
  65.  
  66. Actual rendering is performed by the DrawFile module
  67. which must be loaded by the application's !Run file.
  68.  
  69. Wimp redraw block
  70.   0  Window handle
  71.   4  Visible area minx (incl)
  72.   8               miny (incl)
  73.  12               maxx (excl)
  74.  16               maxy (excl)
  75.  20  Scrollx
  76.  24  Scrolly
  77.  28  Redraw rect  minx (incl)
  78.  32               miny (incl)
  79.  36               maxx (excl)
  80.  40               maxy (excl)
  81.  
  82. Example Code (DrawRenderFile)
  83. To render a drawfile during a call to a user redraw
  84. function, no bounding boxes shown:
  85.  
  86. DEF FN_UserRedraw_Mainw(blk%,x%,y%)
  87. PROCshell_DrawRenderFile(buffer%,x%+0,y%-1000,
  88. ,blk%,FALSE)
  89. =0
  90. --------------------------------------------------------
  91.  
  92. FNshell_DrawLoadFile()
  93. Params =>
  94.          str file name
  95.  
  96.        <=
  97.          int address of drawfile buffer
  98.  
  99. --------------------------------------------------------
  100.  
  101. PROCshell_DrawSaveFile()
  102. Params =>
  103.          int address of drawfile buffer
  104.          str file name
  105.  
  106. This routine saves the drawfile and sets
  107. the filetype to &AFF (draw).
  108.  
  109. --------------------------------------------------------
  110.  
  111. FNshell_DrawGetFileSize()
  112. Params =>
  113.          int address of drawfile buffer
  114.   
  115.        <=
  116.          int file size in bytes (excluding
  117.              EvntShell pre-header)
  118.  
  119. --------------------------------------------------------
  120.  
  121. PROCshell_DrawGetBoundingBox()
  122. Params =>
  123.          int  address of drawfile buffer
  124.          int  min x position
  125.          int  min y position
  126.          int  width  
  127.          int  height 
  128.          bool TRUE if box coords are to be
  129.               returned in OS units, ELSE
  130.               values returned in draw units
  131.  
  132.        <=
  133.          The x,y,height and width values are
  134.          returned
  135.  
  136. --------------------------------------------------------
  137.  
  138. PROCshell_DrawInitFont()
  139. Params =>
  140.          int address of drawfile buffer
  141.          str name of font to initialise
  142.              i.e. 'Trinity.Medium.Italic'
  143.  
  144.        <=
  145.           address of drawfile buffer is
  146.           updated
  147.  
  148. Before text using outline fonts can be used
  149. in a drawfile it is vital that they are
  150. initialised using this call. Once you have
  151. called this routine for the first time you
  152. must continue initialising all the fonts that
  153. will be needed before creating other objects.
  154.  
  155. It would appear (despite what the PRMs say!)
  156. that font initialisation must occur before any
  157. other objects are defined - that is you must
  158. initialise any fonts directly after creating
  159. the drawfile.
  160.  
  161. Attempting to use fonts that are not available
  162. (has !Fonts been 'seen' by the Filer?) will
  163. cause an error. You should also bear in mind
  164. that using fonts that other people may not have
  165. can cause problems as various applications
  166. react in different ways to this situation.
  167.  
  168. --------------------------------------------------------
  169.  
  170. PROCshell_DrawSetFont()
  171. Params =>
  172.          int  address of drawfile buffer
  173.          str  name of font ("" for System Font)
  174.  
  175. Before this call can be made the font specified must be
  176. initialised with a call to PROCshell_DrawInitFont,
  177. otherwise an error will be generated.
  178.  
  179. All text objects created with PROCshell_DrawOutlineFont
  180. will be in the specified font until the next call to
  181. PROCshell_DrawSetFont.
  182.  
  183. --------------------------------------------------------
  184.  
  185. PROCshell_DrawBox()
  186. Params =>
  187.          int  address of drawfile buffer
  188.          real x coordinate of bottom left
  189.               of box
  190.          real y coordinate of bottom left
  191.               of box
  192.          real width of box
  193.          real height of box
  194.  
  195.        <=
  196.          address of drawfile buffer is
  197.          updated
  198.  
  199. The coordinates and dimensions of the box
  200. are given in the currently selected units.
  201.  
  202. --------------------------------------------------------
  203.  
  204. PROCshell_DrawCircle()
  205. Params =>
  206.          int  address of drawfile buffer
  207.          real x coordinate of centre of
  208.               circle
  209.          real y coordinate of centre of
  210.               circle
  211.          real radius of circle
  212.  
  213.        <=
  214.          address of drawfile buffer is
  215.          updated
  216.  
  217. The coordinates and dimensions of the circle
  218. are given in the currently selected units.
  219.  
  220. --------------------------------------------------------
  221.  
  222. PROCshell_DrawEllipse()
  223. Params =>
  224.          int  address of drawfile buffer
  225.          real x coordinate of centre of
  226.               ellipse
  227.          real y coordinate of centre of
  228.               ellipse
  229.          real major axis of ellipse
  230.          real minor axis of ellipse
  231.           
  232.        <=
  233.          address of drawfile buffer is
  234.          updated
  235.  
  236. The coordinates and dimensions of the ellipse
  237. are given in the currently selected units.
  238.  
  239. --------------------------------------------------------
  240.  
  241. PROCshell_DrawLine()
  242. Params =>
  243.          int  address of drawfile buffer
  244.          real x coordinate of start of line
  245.          real y coordinate of start of line
  246.          real x coordinate of end of line
  247.          real y coordinate of end of line
  248.           
  249.        <=
  250.          address of drawfile buffer is
  251.          updated
  252.  
  253. The coordinates and dimensions of the line
  254. are given in the currently selected units.
  255.  
  256.  
  257. --------------------------------------------------------
  258.  
  259. PROCshell_DrawOutlineFont()
  260. Params =>
  261.          int  address of drawfile buffer
  262.          str  text to insert
  263.          real width of font  (points)
  264.          real height of font (points)
  265.          real x coordinate of bottom left
  266.               of text (current units)
  267.          real y coordinate of bottom left
  268.               of text (current units)
  269.  
  270.        <=
  271.           address of drawfile buffer is
  272.           updated
  273.  
  274. Before a text object can inserted the font
  275. used must be initialised with a call to
  276. PROCshell_DrawInitFont, otherwise an error
  277. will be generated. The font to use must also
  278. be selected with PROCshell_DrawSetFont.
  279.  
  280. --------------------------------------------------------
  281.  
  282. PROCshell_DrawSetFillColour()
  283. =>    int    address of drawfile buffer
  284.     int    red    value (0-255)
  285.     int    green    value (0-255)
  286.     int    blue    value (0-255)
  287.  
  288. The colour value is supplied as a 24 bit
  289. value, RISC OS handles the display of the
  290. colour by dithering. 'No colour' may be selected
  291. by specifying the red, green, blue values as
  292. -1, -1, -1.
  293.  
  294. --------------------------------------------------------
  295.  
  296. PROCshell_DrawSetNoFillColour
  297. =>    int    address of drawfile buffer
  298.  
  299. Sets current fill colour back to transparent.
  300.  
  301. --------------------------------------------------------
  302.  
  303. PROCshell_DrawSetPathColour()
  304. =>    int    address of drawfile buffer
  305.     int    red    value (0-255)
  306.     int    green    value (0-255)
  307.     int    blue    value (0-255)
  308.  
  309. The colour value is supplied as a 24 bit
  310. value, RISC OS handles the display of the
  311. colour by dithering. 'No colour' may be selected
  312. by specifying the red, green, blue values as
  313. -1, -1, -1.
  314.  
  315. --------------------------------------------------------
  316.  
  317. PROCshell_DrawSetNoPathColour
  318. =>    int    address of drawfile buffer
  319.  
  320. Sets current path colour back to transparent.
  321.  
  322. --------------------------------------------------------
  323. PROCshell_DrawSetPathWidth()
  324. Params =>
  325.          int  address of drawfile buffer
  326.          real path width (current units)
  327.  
  328. --------------------------------------------------------
  329.  
  330. PROCshell_DrawSetUnitsCM()
  331. Params =>
  332.          int address of drawfile buffer
  333.  
  334. Sets centimeters to be the current unit of
  335. measurement for the other library routines.
  336.  
  337. --------------------------------------------------------
  338.  
  339. PROCshell_DrawSetUnitsIN()
  340. Params =>
  341.          int address of drawfile buffer
  342.  
  343. Sets inches to be the current unit of
  344. measurement for the other library routines.
  345.  
  346. --------------------------------------------------------
  347.  
  348. PROCshell_DrawSetUnitsMM()
  349. Params =>
  350.          int address of drawfile buffer
  351.  
  352. Sets millimeters to be the current unit of
  353. measurement for the other library routines.
  354.  
  355. --------------------------------------------------------
  356.  
  357. PROCshell_DrawSetUnitsOS()
  358. Params =>
  359.          int address of drawfile buffer
  360.  
  361. Sets OS units to be the current unit of
  362. measurement for the other library routines.
  363.  
  364. --------------------------------------------------------
  365.  
  366. PROCshell_DrawSetUnitsPT()
  367. Params =>
  368.          int address of drawfile buffer
  369.  
  370. Sets points to be the current unit of
  371. measurement for the other library routines.
  372.  
  373. --------------------------------------------------------
  374.  
  375. PROCshell_DrawSetStartCapNone()
  376. Params =>
  377.          int buffer containing drawfile
  378.  
  379. Sets no cap at the start of the path.
  380.  
  381. --------------------------------------------------------
  382.  
  383. PROCshell_DrawSetStartCapRound()
  384. Params =>
  385.          int buffer containing drawfile
  386.  
  387. Sets a round cap at the start of the path.
  388.  
  389. --------------------------------------------------------
  390.  
  391. PROCshell_DrawSetStartCapSquare()
  392. Params =>
  393.          int buffer containing drawfile
  394.  
  395. Sets a square cap at the start of the path.
  396.  
  397. --------------------------------------------------------
  398.  
  399. PROCshell_DrawSetStartCapTriangle()
  400. Params =>
  401.          int buffer containing drawfile
  402.          int width  of arrowhead (current units)
  403.          int length of arrowhead (current units)
  404.  
  405. Sets a triangular cap at the start of the path.
  406.  
  407. --------------------------------------------------------
  408.  
  409. PROCshell_DrawSetEndCapNone()
  410. Params =>
  411.          int buffer containing drawfile
  412.  
  413. Sets no cap at the end of the path.
  414.  
  415. --------------------------------------------------------
  416.  
  417. PROCshell_DrawSetEndCapRound()
  418. Params =>
  419.          int buffer containing drawfile
  420.  
  421. Sets a round cap at the end of the path.
  422.  
  423. --------------------------------------------------------
  424.  
  425. PROCshell_DrawSetEndCapSquare()
  426. Params =>
  427.          int buffer containing drawfile
  428.  
  429. Sets a square cap at the end of the path.
  430.  
  431. --------------------------------------------------------
  432.  
  433. PROCshell_DrawSetEndCapTriangle()
  434. Params =>
  435.          int buffer containing drawfile
  436.          int width  of arrowhead (current units)
  437.          int length of arrowhead (current units)
  438.  
  439. Sets a triangular cap at the end of the path.
  440.  
  441. --------------------------------------------------------
  442.  
  443. PROCshell_DrawSetScale()
  444. Params =>
  445.          int  address of drawfile buffer
  446.          real x scale
  447.          real y scale
  448.  
  449. Each drawfile buffer created or loaded by
  450. the library routines has a scale which is
  451. contained in the pre-header. Loading or
  452. creating a new file sets the scale to 1:1.
  453.  
  454.  
  455. --------------------------------------------------------
  456.  
  457. PROCshell_DrawGetScale()
  458. Params =>
  459.          int  address of drawfile buffer
  460.          real x scale (value updated)
  461.          real y scale (value updated)
  462.  
  463. Each drawfile buffer created or loaded by
  464. the library routines has a scale which is
  465. contained in the pre-header. This routine
  466. allows the currently set scales to be read.
  467.  
  468. --------------------------------------------------------
  469.  
  470. PROCshell_DrawResizeWindow()
  471. Params =>
  472.          int address of drawfile buffer
  473.          int window handle
  474.          int left   margin (os units)
  475.          int bottom margin (os units)
  476.          int right  margin (os units)
  477.          int top    margin (os units)
  478.  
  479. Resizes an existing window to suit the
  480. drawfile held in the specified buffer,
  481. taking account of the current scale.
  482.  
  483. --------------------------------------------------------
  484.  
  485. PROCshell_DrawScaleToWindow()
  486. Params =>
  487.          int  address of drawfile buffer
  488.          int  window handle
  489.          int  left   margin (os units)
  490.          int  bottom margin (os units)
  491.          int  right  margin (os units)
  492.          int  top    margin (os units)
  493.          real xscl   (value returned)
  494.          real yscl   (value returned)
  495.  
  496. Returns the scale factors required to fit
  497. the drawfile held in the specified buffer
  498. within the given window.
  499.  
  500. --------------------------------------------------------
  501.  
  502. PROCshell_DrawPathStart()
  503. Params =>
  504.          int  address of drawfile buffer
  505.          real x coord
  506.          real y coord
  507.  
  508. Begins a new path object
  509.  
  510. --------------------------------------------------------
  511.  
  512. PROCshell_DrawPathDrawTo()
  513. Params =>
  514.          int  address of drawfile buffer
  515.          real x coord
  516.          real y coord
  517.  
  518. Adds a line segment to the current path object
  519.  
  520. --------------------------------------------------------
  521.  
  522. PROCshell_DrawPathCloseLine()
  523. Params =>
  524.          int address of drawfile buffer
  525.  
  526. Closes the current path with a line and fills the
  527. path with the current fill colour
  528.  
  529. --------------------------------------------------------
  530.  
  531. PROCshell_DrawPathEnd()
  532. Params =>
  533.          int address of drawfile buffer
  534.  
  535. Closes the current path with a gap and fills the
  536. path with the current fill colour
  537.  
  538. --------------------------------------------------------
  539.  
  540. PROCshell_DrawStartGroup()
  541. Params =>
  542.          int address of drawfile buffer
  543.          str name of group (less than 12 chars)
  544.          
  545. --------------------------------------------------------
  546.  
  547. PROCshell_DrawEndGroup()
  548. Params =>
  549.          int address of drawfile buffer
  550.          
  551. --------------------------------------------------------
  552.  
  553. PROCshell_DrawDestroyFile()
  554. =>    int    address of drawfile buffer
  555.  
  556. Removes the definition of a DrawFile and frees the
  557. memory used.
  558.  
  559. --------------------------------------------------------
  560.  
  561. PROCshell_DrawSetPathPattern()
  562. =>    int    address of drawfile buffer
  563.     bool    TRUE for dashed lines, otherwise FALSE
  564.     real    offset
  565.     int    number of elements
  566.     real    length (current units)
  567.  
  568. Sets the current path pattern (dashed etc).
  569.  
  570. --------------------------------------------------------