home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 8 / FreshFishVol8-CD2.bin / bbs / dev / cmanual-3.0.lha / CManual / Intuition / Graphics / Graphics.doc < prev    next >
Text File  |  1993-10-12  |  26KB  |  864 lines
  1. 3    GRAPHICS
  2.  
  3. 3.1  INTRODUCTION
  4.  
  5. We have now looked at how to open different types of screens,
  6. and how to open different types of windows connected to the
  7. screens etc. It is all very good, but what would Intuition be
  8. without any graphics to display in the screens/windows?
  9.  
  10. Intuition's main idea is to make the communication between
  11. the program and the user as easy as possible. Graphics enables
  12. you to display the results that the computer has calculated in
  13. an understandable way (a picture says more than...). Graphics
  14. makes it also much easier to use the program, and can warn the
  15. user if something dangerous is going to happen: It is very easy
  16. to press the wrong button if you have got a question like "OK
  17. to erase disk?", but if there also had been a picture
  18. showing a cross with the text "RIP" on, you would probably
  19. have been a bit more careful.
  20.  
  21. There exist both a low- and a high-level way of making
  22. graphics. The low-level approach (Graphics Primitives) is
  23. not described in this chapter since it is not related to
  24. Intuition. The low-level graphics routines are very fast, but
  25. if you are not careful they can trash menus etc. We will here
  26. concentrate our self on the high-level approach which is
  27. supported by Intuition, and is a safe way of drawing.
  28.  
  29.  
  30.  
  31. 3.2  LINES TEXT PICTURES
  32.  
  33. Intuition gives you three different methods of making graphics:
  34. - You can draw lines (Borders).
  35. - Print text (IntuiText).
  36. - Or you can directly print graphics images (Images).
  37.  
  38.  
  39.  
  40. 3.3  BORDERS
  41.  
  42. Border has a bit misleading name since you are not limited to
  43. only draw borders, you may draw any kind of shapes which is
  44. made out of connecting lines. A Border structure may also be
  45. connected to other Border structures, so everything which can
  46. be drawn with lines, can be drawn with Intuition's Border
  47. structure.
  48.  
  49.  
  50.  
  51. 3.3.1  THE BORDER STRUCTURE
  52.  
  53. When you want to draw lines you need to declare and initialize
  54. a Border structure which look like this:
  55.  
  56. struct Border
  57. {
  58.   SHORT LeftEdge, TopEdge;
  59.   SHORT FrontPen, BackPen, DrawMode;
  60.   SHORT Count;
  61.   SHORT *XY;
  62.   struct Border *NextBorder;
  63. };
  64.  
  65. LeftEdge, TopEdge: Start position of the lines.
  66.  
  67. FrontPen:          Colour register used to draw the lines.
  68.  
  69. BackPen:           This variable is for the moment unused.
  70.  
  71. DrawMode:          Must be either JAM1 or XOR. If the JAM1 flag
  72.                    is set, the colour specified (FrontPen) will
  73.                    be used to draw the lines regardless what
  74.                    the background colour is. The XOR flag makes
  75.                    the lines to be drawn with the binary 
  76.                    complement of the background colours.
  77.  
  78. Count:             The number of coordinates there is in the XY
  79.                    array. (See below for more information.)
  80.  
  81. XY:                A pointer to an array of coordinates used to
  82.                    draw the lines. (See below for more
  83.                    information.)
  84.  
  85. NextBorder:        A pointer to the next Border structure if
  86.                    there exist one, else NULL.
  87.  
  88.  
  89.  
  90. 3.3.2  COORDINATES
  91.  
  92. If you want to draw this:
  93.  
  94. (10,10)        (25,10)
  95.    *--------------*
  96.                   |      (35,12)
  97.                   |         *
  98.                   |         |
  99.                   *---------*
  100.                (25,14)   (35,14)
  101.  
  102. The array of coordinates would look like this:
  103.  
  104. SHORT my_points[]=
  105. {
  106.   10,10, /* Start at position (10,10) */
  107.   25,10, /* Draw a line to the right to position (25,10) */
  108.   25,14, /* Draw a line down to position (25,14) */
  109.   35,14, /* Draw a line to the right to position (35,14) */
  110.   35,12  /* Finish of by drawing a line up to position (35,12) */ 
  111. };
  112.  
  113. The array contains 5 pair of coordinates, so the variable Count
  114. should be set accordingly. The entire Border structure would
  115. therefore look something like this:
  116.  
  117. struct Border my_border=
  118. {
  119.   0, 0,        /* LeftEdge, TopEdge. */
  120.   3,           /* FrontPen, colour register 3. */
  121.   0,           /* BackPen, for the moment unused. */
  122.   JAM1,        /* DrawMode, draw the lines with colour 3. */
  123.   5,           /* Count, 5 pair of coordinates in the array. */
  124.   my_points,   /* XY, pointer to the array with the */
  125.                /* coordinates. */
  126.                /* (Remember my_points == &my_points[0]) */
  127.   NULL         /* NextBorder, no other Border structures */
  128.                /* comes after this one. */
  129. };
  130.  
  131.  
  132.  
  133. 3.4  HOW TO USE THE BORDER STRUCTURE
  134.  
  135. The Border structure is either used to draw lines in a screen
  136. or window, but can also be used to draw lines connected to a
  137. Gadget, Requester or Menu. (See chapter 4, 5 and 7 for more
  138. information about Gadgets, Requesters and Menus.)
  139.  
  140. If you want to connect a Border structure with a Gadget etc,
  141. you simply initialize the Gadget structure with a pointer to
  142. the Border structure, and Intuition will draw the lines for
  143. you. This will be explained later.
  144.  
  145. If you want to draw the lines in a screen or window you need to
  146. tell Intuition that you want it to use the structure to make
  147. some lines. You do it by calling the function DrawBorder():
  148.  
  149. Synopsis:  DrawBorder( rast_port, border, x, y );
  150.  
  151. rast_port: (struct RastPort *) Pointer to a RastPort.
  152.  
  153.            If the lines should be drawn in a window, and
  154.            my_window is a pointer to that window, you write:
  155.            my_window->RPort.
  156.           
  157.            If the lines should be drawn in a Screen, and
  158.            my_screen is a pointer to that screen, you write:
  159.            my_screen->RastPort.
  160.  
  161. border:    (struct Border *) Pointer to a Border structure
  162.            which has been initialized with your requirements.
  163.  
  164. x:         (long) Number of pixels added to the x coordinates.
  165.  
  166. y:         (long) Number of lines added to the y coordinates.
  167.  
  168.  
  169. A call to draw some lines using my_border structure would look
  170. something like this:
  171.   
  172.   DrawBorder( my_window->RPort, &my_border, 0, 0 );
  173.  
  174. If you have created a Border structure which, for example,
  175. draws a box, you can draw several boxes at different places
  176. just by changing the LeftEdge, RightEdge fields of the Border
  177. structure, or by changing the x, y fields in the function call.
  178. This shows how versatile Intuition's high-level way of drawing
  179. is.
  180.  
  181.  
  182.  
  183. 3.4  TEXT
  184.  
  185. Printing text in the Display is supported by the IntuiText
  186. structure. It is quite similar to the Border structure, and is
  187. executed in the same way. The only difference is that you need
  188. to tell Intuition what Font you want to use, and what text to
  189. print.
  190.  
  191.  
  192.  
  193. 3.4.1  THE INTUITEXT STRUCTURE
  194.  
  195. When you want to print text you need to declare and initialize
  196. a IntuiText structure which look like this:
  197.  
  198. struct IntuiText
  199. {
  200.   UBYTE FrontPen, BackPen;
  201.   UBYTE DrawMode;
  202.   SHORT LeftEdge;
  203.   SHORT TopEdge;
  204.   struct TextAttr *ITextFont;
  205.   UBYTE *IText;
  206.   struct IntuiText *NextText;
  207. };
  208.  
  209. FrontPen:          Colour register used to draw the text with.
  210.  
  211. BackPen:           Colour register used to draw the background
  212.                    of the text.
  213.  
  214. DrawMode:          There exist three different way of printing
  215.                    the text:
  216.  
  217.                    JAM1  The colour specified (FrontPen) will
  218.                          be used to draw the text with, the
  219.                          background is unchanged.
  220.  
  221.                    JAM2  The FrontPen colour will be used to
  222.                          draw the text with, the background is
  223.                          drawn with the BackPen colour.
  224.  
  225.                    XOR   The text is drawn with the the binary
  226.                          complement of the background.
  227.  
  228. LeftEdge, TopEdge: Start position of the text.
  229.  
  230. ITextFont:         A pointer to a TextAttr structure which
  231.                    tells Intuition what font, size and style
  232.                    etc to print the text with. Set to NULL if
  233.                    you want to use the default font. (See below
  234.                    for more information.)
  235.  
  236. IText:             A pointer to a NULL-terminated string that
  237.                    should be printed.
  238.  
  239. NextText:          A pointer to the next IntuiText structure if
  240.                    there exist one, else write NULL.
  241.  
  242.  
  243.  
  244. 3.4.2  FONTS
  245.  
  246. You can tell Intuition to print the text with a specific font/
  247. style. You only need to declare and initialize a TextAttr
  248. structure, and give your IntuiText structure a pointer to the
  249. TextAttr stru