home *** CD-ROM | disk | FTP | other *** search
/ The C Users' Group Library 1994 August / wc-cdrom-cusersgrouplibrary-1994-08.iso / vol_300 / 334_02 / readme.trm < prev    next >
Text File  |  1991-02-05  |  7KB  |  166 lines
  1. DOCUMENTATION FOR GNUPLOT TERMINAL DRIVER WRITERS
  2. By Russell Lang 1/90
  3.  
  4. Information on each terminal device driver is contained in term.c and
  5. the term/*.trm files.  Each driver is contained in a .trm file and is 
  6. #include'd into term.c.  Each driver has a set of initialisers in 
  7. term.c for term_tbl[], an array of struct termentry.
  8.  
  9. Here is the definition of the struct termentry from plot.h:
  10.  
  11. struct termentry {
  12.     char *name;
  13.     char *description;
  14.     unsigned int xmax,ymax,v_char,h_char,v_tic,h_tic;
  15.     FUNC_PTR init,reset,text,scale,graphics,move,vector,linetype,
  16.         put_text,text_angle,justify_text,point,arrow;
  17. };
  18.  
  19. Here's a brief description of each variable:
  20.  
  21. The char *name is a pointer to a string containing the name
  22. of the terminal.  This name is used by the 'set terminal' and 
  23. 'show terminal' commands.  
  24. The name must be unique and must not be confused with an abbreviation 
  25. of another name.  For example if the name "postscript" exists, it is not
  26. possible to have another name "postscript2".
  27. Keep the name under 15 characters.
  28.  
  29. The char *description is a pointer to a string containing a
  30. description of the terminal, which is displayed in response
  31. to the 'set terminal' command.  
  32. Keep the description under 60 characters.
  33.  
  34. xmax is the maximum number of points in the x direction.  
  35. The range of points used by gnuplot is 0 to xmax-1.
  36.  
  37. ymax is the maximum number of points in the y direction.  
  38. The range of points used by gnuplot is 0 to ymax-1.
  39.  
  40. v_char is the height of characters, in the same units as xmax and ymax.
  41. The border for labelling at the top and bottom of the plot is 
  42. calculated using v_char.  
  43. v_char is used as the vertical line spacing for characters.
  44.  
  45. h_char is the width of characters, in the same units as xmax and ymax.
  46. The border for labelling at the left and right of the plot is 
  47. calculated using h_char.  
  48. If the _justify_text function returns FALSE, h_char is used to justify 
  49. text right or centre.  If characters are not fixed width, then the 
  50. _justify_text function must correctly justify the text.
  51.  
  52. v_tic is the vertical size of tics along the x axis, 
  53. in the same units as ymax.
  54.  
  55. h_tic is the horizontal size of tics along the y axis, 
  56. in the same units as xmax.
  57.  
  58.  
  59. Here's a brief description of what each term.c function does:
  60.  
  61. _init()  Called once, when the device is first selected.  This procedure
  62. should set up things that only need to be set once, like handshaking and
  63. character sets etc...
  64.  
  65. _reset()  Called when gnuplot is exited, the output device changed or
  66. the terminal type changed.  This procedure should reset the device, 
  67. possibly flushing a buffer somewhere or generating a form feed.
  68.  
  69. _scale(xs,ys) Called just before _graphics(). This takes the x and y
  70. scaling factors as information. If the terminal would like to do its
  71. own scaling, it returns TRUE. Otherwise, it can ignore the information
  72. and return FALSE: do_plot will do the scaling for you. null_scale is
  73. provided to do just this, so most drivers can ignore this function
  74. entirely. The Latex driver is currently the only one providing its own
  75. scaling.
  76.  
  77. _graphics()  Called just before a plot is going to be displayed.  This
  78. procedure should set the device into graphics mode.  Devices which can't
  79. be used as terminals (like plotters) will probably be in graphics mode 
  80. always and therefore won't need this.
  81.  
  82. _text()  Called immediately after a plot is displayed.  This procedure 
  83. should set the device back into text mode if it is also a terminal, so
  84. that commands can be seen as they're typed.  Again, this will probably
  85. do nothing if the device can't be used as a terminal.
  86.  
  87. _move(x,y)  Called at the start of a line.  The cursor should move to the
  88. (x,y) position without drawing.
  89.  
  90. _vector(x,y)  Called when a line is to be drawn.  This should display a line
  91. from the last (x,y) position given by _move() or _vector() to this new (x,y)
  92. position.
  93.  
  94. _linetype(lt)  Called to set the line type before text is displayed or
  95. line(s) plotted.  This procedure should select a pen color or line
  96. style if the device has these capabilities.  
  97. lt is an integer from -2 to 0 or greater.  
  98. An lt of -2 is used for the border of the plot.
  99. An lt of -1 is used for the X and Y axes.  
  100. lt 0 and upwards are used for plots 0 and upwards.
  101. If _linetype() is called with lt greater than the available line types, 
  102. it should map it to one of the available line types.
  103. Most drivers provide 9 different linetypes (lt is 0 to 8).
  104.  
  105. _put_text(x,y,str)  Called to display text at the (x,y) position, 
  106. while in graphics mode.   The text should be vertically (with respect 
  107. to the text) justified about (x,y).  The text is rotated according 
  108. to _text_angle and then horizontally (with respect to the text)
  109. justified according to _justify_text.
  110.  
  111. _text_angle(ang)  Called to rotate the text angle when placing the y label.
  112. If ang = 0 then text is horizontal.  If ang = 1 then text is vertically
  113. upwards.  Returns TRUE if text can be rotated, FALSE otherwise.
  114.  
  115. _justify_text(mode)  Called to justify text left, right or centre.
  116. If mode = LEFT then text placed by _put_text is flushed left against (x,y).
  117. If mode = CENTRE then centre of text is at (x,y).  
  118. If mode = RIGHT then text is placed flushed right against (x,y).
  119. Returns TRUE if text can be justified
  120. Returns FALSE otherwise and then _put_text assumes text is flushed left;
  121. justification of text is then performed by calculating the text width
  122. using strlen(text) * h_char.
  123.  
  124. _point(x,y,point)  Called to place a point at position (x,y).
  125. point is -1 or an integer from 0 upwards.  
  126. 6 point types (numbered 0 to 5) are normally provided.  
  127. Point type -1 is a dot.
  128. If point is more than the available point types then it should 
  129. be mapped back to one of the available points.
  130. Two _point() functions called do_point() and line_and_point() are 
  131. provided in term.c and should be suitable for most drivers.  
  132. do_point() draws the points in the current line type.
  133. If your driver uses dotted line types (generally because it is
  134. monochrome), you should use line_and_point() which changes to 
  135. line type 0 before drawing the point.  line type 0 should be solid.
  136.  
  137.  
  138. _arrow(sx,sy,ex,ey)  Called to draw an arrrow from (sx,sy) to (ex,ey).
  139. An _arrow() function called do_arrow() is provided in term.c which will
  140. draw arrows using the _move() and _vector() functions.  
  141. Drivers should use do_arrow unless it causes problems.
  142.  
  143.  
  144. The following should illustrate the order in which calls to these
  145. routines are made:
  146.  
  147.   _init()
  148.     _scale(xs,ys)
  149.     _graphics()
  150.       _linetype(lt)
  151.       _move(x,y)
  152.       _vector(x,y)
  153.       _point(x,y,point)
  154.       _text_angle(angle)
  155.       _justify(mode)
  156.       _put_text(x,y,text)
  157.       _arrow(sx,sy,ex,ey)
  158.     _text()
  159.     _graphics()
  160.       .
  161.       .
  162.     _text()
  163.   _reset()
  164.  
  165.  
  166.