home *** CD-ROM | disk | FTP | other *** search
/ Amiga Elysian Archive / AmigaElysianArchive.iso / bus_pers / jcgraphd.lha / JcGraphDemo / EnglishManual.txt next >
Text File  |  1992-11-06  |  41KB  |  1,043 lines
  1.                             JcGraph
  2.                     (Demo v0.903 on FredFish 671)
  3.              Copyright 1992, Jean-Christophe Clément
  4.                 Internet:clemj00@dmi.usherb.ca
  5.  
  6. Amiga, AmigaDos, WorkBench are a trademark of Commodore-Amiga Inc.
  7. PostScript is a trademark of Adobe system corp.
  8. Professionnal Page is a trademark of Gold Disk Inc.
  9. PageStream is a trademark of Soft-Logik corp.
  10. Saxon Publisher is a trademark of Saxon Industries Inc.
  11. AegisDraw2000 is a trademark of Oxxi/Aegis Inc.
  12. File requester: Copyright 1990 Khalid Aldosery.
  13. HyperText system by Dominic Giampaolo.
  14.  
  15. Note to the purists: English is my second language.
  16.  
  17. WARNING:
  18.  
  19. This software is not public-domain and thus, cannot be copied without the
  20. written permission from is author. Beeing a registered user by sending any
  21. amount of money doesn't gives any distribution right. But, a demo version
  22. which is available on request and can be freely redistributed but should
  23. keep its integrity. This demo is identified as is and all other copies are
  24. illegal.
  25.                             DISCLAIMER OF WARRANTY
  26.  
  27.     THIS SOFTWARE AND MANUAL FILE ARE OFFERED "AS IS" AND WITHOUT
  28.     WARRANTIES AS TO PERFORMANCE OR MERCHANTABILITY. ANY STATMENTS MADE
  29.     ABOUT THE USES OF THIS SOFTWARE DO NOT CONSTITUTE WARRANTIES AND SHALL
  30.     NOT BE RELIED ON BY THE BUYER IN DECIDING TO PURCHASE THIS PROGRAM.
  31.  
  32.     THIS PROGRAM IS SOLD WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES
  33.     WHATSOEVER. BECAUSE OF THE DIVERSITY OF CONDITIONS AND HARDWARE UNDER
  34.     WHICH THIS PROGRAM MAY BE USED, NO WARRANTY OF FITNESS FOR A PARTICULAR
  35.     PURPOSE IS OFFERED. THE USER IS ADVISED TO TEST THE PROGRAM THOROUGHLY
  36.     BEFORE RELYING ON IT. THE USER MUST ASSUME THE ENTIRE RISK OF USING THE
  37.     PROGRAM. ANY LIABILITY OF SELLER/MANUFACTURER WILL BE LIMITED
  38.     EXCLUSIVELY TO PRODUCT REPLACEMENT OR REFUND OF PURCHASE PRICE.
  39.  
  40.  
  41. Registration:
  42.  
  43. Send 40$ CANADIAN dollars (mail order or check is fine) to:
  44. Jean-Christophe Clement
  45. 921 rang 3 , St-Simon
  46. Quebec,CANADA
  47. J0H-1Y0
  48.  
  49. (resident of Country other than Canada and USA should add 7$ for delivery)
  50. You will receive by mail a disk containing the software (JcGraph). I would like
  51. to have some information on your working environment too.
  52. Note that your money envoice will garantee that the (1) next
  53. JcGraph upgrade will be freely sent to you (if there is such an upgrade):
  54.  
  55. 1. Wich AmigaDOS version are you using ?
  56.    a. If version < 2.0, are you planning to upgrade soon ?
  57. 2. What other major software are you using with your Amiga ?
  58.    a. If your using a spreadsheet, I would like to have it's name.
  59. 3. (To your discretion) How old are you ?
  60. 4. Are you planning to use JcGraph on a personnal or professionnal basis ?
  61. 5. Wich model of Amiga are you using ?
  62. 6. What peripheral(s) do you have ?
  63.  
  64. Table of content:
  65. -----------------
  66.  
  67. 0.Introduction.
  68. 1.Required configuration, Hardware and Software.
  69. 2.JcGraph's installation.
  70. 3.Step by step example of a graph's creation.
  71. 4.Menu options summary.
  72. 5.Control panel window.
  73. 6.File format: Input.
  74. 7.File format: Output.
  75. 8.Graph's modification.
  76. 9.Keyboard equivalent.
  77. 10.Palette requester.
  78. 11.TOOLTYPE and command line options.
  79. 12.ARexx interface.
  80. 13.Graph type file format.
  81. 14.The future of JcGraph.
  82. 15.JcGraph history.
  83.  
  84. 0.Introduction:
  85. ---------------
  86. a.What is JcGraph ?.
  87.  
  88.     Specialised in business graph generation, JcGraph will output your data
  89. as Pie, line, bar, stack charts,(etc...more) in two or three dimension. You
  90. will then be able to rotate the resulting graph in X,Y,Z axes and output
  91. them to: EPS,Geo 3D, AegisDraw2000 or IFF ILBM.
  92.  
  93. b.Why I have created JcGraph ?
  94.  
  95.     Because, after having tried some commercial software that were "supposed"
  96. to produce professionnal quality business graphs, I found that none  were up
  97. to what is available for Macintosh or IBM PC compatibles. Considering the
  98. Amiga reputation as a "Multimedia" computer, it was time for a change.
  99.  
  100. c.JcGraph's philosophy.
  101.  
  102.     The first goal of Jcgraph was to produce highest quality business
  103. graphics with the greatest visual impact with the least effort possible.
  104.     So, I asked myself: "What is the single most difficult thing to do when
  105. someone is making a business graphic without any specific tool other than a
  106. paint program ?". The answer is quite simple: "The main graphic itself!".
  107. I mean, once the main graph is designed, the process of adding title,
  108. annotation, graduated background, etc... is trivial.
  109.     JcGraph reflects this thinking; it will help you create a great looking
  110. graphic and the flexibility of it's export modules will let you add all the
  111. fancy details in other specialised software.
  112.  
  113. d. Style guide compliance.
  114.  
  115.   Well, I tried as much as possible to stick to the Style guide book, if you
  116. take into account the limited ressources I had to invest in JcGraph.
  117.  
  118. 1.Required configuration, Hardware and Software:
  119. ------------------------------------------------
  120.  
  121. Minimal:
  122.             Any Amiga (more than one is not a necessity :-).
  123.             1meg RAM.
  124.             WorkBench 1.3.
  125.             1 floppy disk.
  126.  
  127. Suggested:
  128.             Accelerated Amiga.
  129.             1.5+ meg RAM.
  130.             WorkBench 2.0+.
  131.             Hard-Disk.
  132.  
  133. JcGraph has been tested and judged fully functionnal under these system
  134. configurations:
  135. -Amiga 500, 1 floppy, 1 meg RAM, WB 1.3, 68000.
  136. -Amiga 2000HD, 52 Megs HD, 3 megs RAM, WB 2.0, 68000.
  137. -Amiga 3000/16, 50 Megs HD, 2 megs RAM, WB 2.0, 68030/16Mhz
  138.  
  139. 2.JcGraph's installation:
  140. -------------------------
  141.  
  142. A-Logical assigns:
  143. ------------------
  144.  
  145. For example: If you copy JcGraph in "Work:MyJcGraph",
  146.              add this line to the file "s:startup-sequence":
  147.              "assign JcGraph: Work:MyJcGraph".
  148.  
  149. B-Directory and files required (After having done A):
  150. -----------------------------------------------------
  151. libs:icon.library               :On WB 1.3 (in ROM under 2.0).
  152. libs:kd_freq.library            :File-requester Library. (For <2.0 user)
  153. libs:IffParse.library           ;Library used for IFF ILBM .
  154. JcGraph:Graphtype               :Contain all graph types.
  155. JcGraph:Template                :Contain all Templates.
  156. JcGraph:HelpFile                :Contain all help files.
  157. JcGraph:Rexx                    :Contain all Rexx scripts.
  158. JcGraph:HelpFile/ht             :On-line Help engine.
  159. JcGraph:JcGraph                 :Main program.
  160.  
  161. If you haven't done so yet, go to jcgraph:libs directory and type (in a
  162. shell) "copy #?.library libs:". Everything should be functionnal from now.
  163. Note that I CANNOT distribute 'IffParse.library' that comes with WB 2.0,
  164. so, you should manage to get it somewhere else.
  165.  
  166. 3.Step by step example of a graph's creation:
  167. ---------------------------------------------
  168.     We will produce a graph made of 3 rows of 3 planes each and output it as
  169. AegisDraw2000.
  170.  
  171.     The first step is data creation. To do so, use your favorite text editor.
  172. It is important that it should not produce a file containing special control
  173. characters that would not be recognized by JcGraph (stay ASCII international).
  174.     After your text editor is loaded, start by entering "1002" (without the
  175. "" delimiters). This sequence help JcGraph identify the file type, to be sure
  176. that it is really compatible. Note that all value should be comma-separated.
  177.     Next, enter the number of column that your file will contain, "3" in our
  178. example. Do the same thing for the number of line. Follows a number which
  179. will set the space between each cotation in the scale on the side of the
  180. graph; for example, if your data range from 0 to 100 and you specify 25,
  181. the cotation scale will output "0","25","50","75","100". This number use
  182. the same value unit as the data itself.
  183.     The next number (floating point), is the one by which every cotation
  184. value will be multiplied ; for example, if you enter "1.24", each cotation
  185. of the scale will be muliplied by 1.24. This permits to access floating
  186. point value without changing the data itself. Note that only 3 decimals
  187. positions will be kept for now and that a value of 0 will result in an
  188. integer form (ie no decimal point).
  189.     The next step is the value entry. As we chose to produce a 3 by 3 data
  190. file, there will be 9 consecutive values (they can be on the same line but
  191. should always be comma-separated).
  192.     The 3 next value are text strings that will identify your columns (they
  193. should always be filled). Same procedure for each line. Note that the
  194. orientation is always the same. Rows represents variation and lines are
  195. diferent products type.
  196.  
  197. Here is the resulting data file from the example:
  198. 1002,
  199. 3,3,10,0,
  200. 10,20,30,
  201. 50,60,60,
  202. 15,32,17,
  203. Jan,Fev,Mar,
  204. Gaz,Oil,Fer,
  205.  
  206. Save this result as "test3X3.asc".
  207.  
  208.     The next major step is to load this data file in JcGraph. First, run
  209. JcGraph. Note that once JcGraph is started, there can be a 3 to 5 second
  210. break (more with default ARexx script) before you see anything happen, this
  211. is normal.
  212.     Now, choose "Open..." from the project menu (Amiga+O)
  213. IMPORTANT: JcGraph accepts command from the interface window only. So, every
  214. time you want to perform an operation, you should select it (if not already
  215. selected). It is also worth to mention that when there is no data loaded in
  216. JcGraph, the interface's title bar will display "No Data".
  217.     A file requester will pop up asking "Choose an ASCII data file". It's
  218. utilisation is not described here for brievty but can get extended help by
  219. pressing HELP or SHIFT-F1 when it is active.
  220.     Find et select your file "test3X3.asc" and select "Open" from the lower
  221. left corner of the file requester's window. The mouse pointer will change
  222. for a small clock until your data file is openned. This should'nt be long.
  223.  The title bar should now display "test3X3.asc".
  224.     The window titled "Preview" gives an approximation of what the final
  225. graph will look like, in this case, data is graphed as 3D blocks. For
  226. example purpose, we will choose another type of graphic.
  227.     Choose "Load..." (Amiga+T) from the "GraphType" menu. Another file
  228. requester should appear. If JcGraph is correctly installed, a number of
  229. file ending with ".grf" extension should be listed in the window. You can
  230. now choose the type of graph that best suit your needs. For the example,
  231. choose "3D_BrokenPlanes.grf" then "Load...". After a short period of time,
  232. you should see the new graph type reflected in the Preview window. Note that
  233. the wireframe representation of the preview window is used for real-time
  234. manipulation, the final output is filled with colors.
  235.     The actual three-dimensionnal perspective doesn't do justice to the 3D
  236. effect, so we will rotate the graph using the interface window's gadgets.
  237. There is two main section that divide the interface window:
  238. 1. To the left, there is two gadget labelled "Undo" and "Render". We will
  239. discuss their respective function later.
  240. 2. To the right, there is 4 lines of gadgets. These ones control rotation
  241. values and perspective of the graph.
  242.     Line 1: Rotation around X.
  243.     Line 2: Rotation around Y.
  244.     Line 3: Rotation around Z.
  245.     Line 4: Perspective control.
  246.  
  247.     For example purpose, we will not discuss these any further  (they are
  248. described in section 5). For now, just select the first gadget from the top
  249. (the rectangular one, with a "0" in it) and replace the "0" by "-30". Press
  250. RETURN. Do the same with the next gadget, but this time, replace "0" by "30".
  251. You will immediatly see the change in the preview window. The effect is a
  252. lot more dynamic.
  253.     Now, if you want to look at the final result, select the "Render" gadget
  254. from the interface window. The mouse pointer will change for a longer period
  255. of time. After a while, the pointer should get back to normal and you should
  256. see the final result in the Output window. If it is obscured by another
  257. window, just bring it to the front (but remember to click back in the
  258. interface window in order to do any other manipulation on the graph).
  259.     From here, there could be some constatation:
  260. 1. It's nice (I hope so :-)
  261. 2. It's too small.
  262. 3. You don't like the colors.
  263.  
  264. We will solve all the problems, one at a time.
  265. 1. It's nice: That's not really a problem.
  266. 2. It's too small: Grab the sizing gadget (the one at the lower right of
  267. the Output window) and drag it to the desired size. Now, re-press "Render"
  268. and "voila!".
  269. 3. You don't like the colors: It is the next step.
  270.  
  271. Color choice:
  272. Choose the "Color..." (Amiga+k) option under the "Edit" menu. A requester
  273. named "Data color selector" should pop up. To the left, you should see all
  274. available colors... to the right, the values to be colored. You will
  275. probably recognize the texts associated with each line of value. There is
  276. also two more entries named "Background" and "Floor" which will permits
  277. respectively to change the colors of the background, behind the data and
  278. the floor, under the data (compare with the final result for better
  279. understanding). Select "Floor". A white rectangle will appear around the
  280. selected area. Then, choose a color on the left. The little box at the left
  281. of the "Floor" text should reflects the color you selected. When you are
  282. satisfied with the color you choosed, click on the close gadget to validate
  283. your entry (the one at the upper-left of the window). To see the result,
  284. selct "Render" one more time. If you don't like the color palette at all,
  285. use the "Palette..." menu option to change it.
  286.     The final step is to save the file as "AegisDraw2000". To do so, select
  287. "Draw2000" from sub-menu "Fromat..." from menu "Project" (Amiga+4). Then,
  288. choose "Save as..." from "Project" (Amiga+A) that will pop up a file
  289. requester asking for the file name of the resulting graph. Enter the name,
  290. then press RETURN. The file should now be available for use in any
  291. compatible software.
  292.     For more detail on JcGraph function, go to section 4.
  293.  
  294. 4.Menu options summary.
  295. -----------------------
  296. PROJECT
  297. About...    :Info about JcGraph.
  298. Open...     :Open a text file (Desciption in section 6).
  299. Save        :Save the graph. Format is specified in "Format".
  300. Save as...  :Same as "Save" but request a name.
  301. Format      :Select the file output format :see section 7.
  302. Print...    :Outputs to the printer.
  303.              Beware, you will be asked only once if you want to "CANCEL".
  304. Quit...     :Quit JcGraph...
  305.  
  306. EDIT
  307. Undo        :Undo the last rotation.
  308. Copy        :Not implemented yet.
  309. Color...    :Let you select color values.
  310.             The cycle gadget at the bottom of the requester has two
  311.             position, "Color" and "Grey scale". Grey scale will give you
  312.             an approximation of what the printed result will look like.
  313. Palette...  :Let you change color palette value.
  314.              See Palette section for more info.
  315. TEMPLATE
  316. Load...     :Load a template file wich contain:
  317.              -the graph type.
  318.              -rotation positions.
  319.              -perspective.
  320. Save...     :Save a template file.
  321.  
  322. GRAPHTYPE
  323. Load...     :Load a new graph type, 2D or 3D.
  324.  
  325. ENVIRONMENT
  326. Iconify           :Not implemented yet (mmmmm).
  327. Notes...          :Let you leave a note on anything you want. If you
  328.                    press the icon at left, you will always be noticed of
  329.                    your note before quitting.
  330. Arrange           :Organize windows logically on the screen.
  331. Req. Flash ON/OFF :Enable/Disable requesters Display Beep.
  332. Exec Rexx...      :Request for an ARexx script to be executed.
  333. Preview OFF/ON    :Disable/Enable the preview window.
  334. Output Back/Front :When Output window is sized, send it to back or front on
  335.                    final rendering.
  336.  
  337. HELP
  338. General...  :General help system activation.
  339. On Help...  :Activate help on using the help system.
  340. Start Help  :Context-sensitive help. You just have to select the topic
  341.              on wich you need help to get it. Select back the same              option (renamed Stop Helper) to stop.
  342.  
  343. 5.Control panel window:
  344. -----------------------
  345.     The interface window (Control panel window) is the one with lots of
  346. gadget on it.
  347.  
  348. 1. The first line of gadget contain (from the right);identifier of the
  349. rotation axis, 'X' in this case, a scroll gadget wich select the value of
  350. the 'X' rotation and a string gadget which permits to enter the value
  351. numerically. The two other line do the same thing but for the 'Y' and 'Z'
  352. axes. Modification of any of the gadget updates the Preview window
  353. automatically.
  354. 2. The slider gadget named "Perspective" will, as their name implies, will
  355. change the perspective value; the more the cursor is sled to the left, the
  356. more the graph will look "deformed" (like a camera with a fish-eye), to
  357. opposite , sliding it to the right will yield in a more orthogonal-looking
  358. graph. This effect is just for visualisation, so it, it will not be saved
  359. in the "3D Geo" format.
  360. 5.The gadget titled "Undo" will undo the last rotation operation. Menu
  361. option "Undo" (Amiga-Z) will do the same thing.
  362. 6.The "Render" gadget will gives you the final output on the screen.
  363. 7.There is also a cluster of ten button at left. These can be programmed via
  364. Arexx to execute ARexx script when pressed. See details in Rexx scripts
  365. headers given with JcGraph.
  366.  
  367. 6.File format: Input:
  368. ---------------------
  369.  
  370. Here is the text file format description:
  371.  
  372. 1002,                       1. Data identifier. Always 1002.
  373. 4,2,80,6.0,                 2. #Columns,#Lines,Cotation space, Multiplier
  374. 10,20,30,40,                3. First ligne
  375. 50,60,60,80,                4. Second line
  376. Jan,Feb,Mar,Apr,            5. Text under each column.
  377. Gaz,Oil,                    6. Text under each line.
  378.  
  379. Notes: All value may vary between -1000 and 1000.
  380.        Data file should end with a comma.
  381.        When the multiplier is 0, numbers take the
  382.        integer form (ie without floating point).
  383.        All entries should be comma separated but can be logically
  384.        organized with "returns".
  385.  
  386. 7.File format: Output:
  387. ----------------------
  388. IFF ILBM:
  389. File format compatible with most commercial an public-domain paint program.
  390.  
  391. EPSF COLOR & GRAY:
  392. Encapsulated PostScript file format. For now, it is the only format in wich
  393. the legend will be automatically created. Unless you have a PostScript
  394. interpreter, this file cannot be printed on printer other than PostScript
  395. compatible ones. By default, the font used is "Times-Roman". Si you want to
  396. output your graph to the printer and you possess a PostScript printer, just
  397. save it as EPSF. Then, type to a CLI/SHELL prompt "copy FileName to SER:"
  398. if your printer is hooked to the serial port or "copy FileName to PAR:" if
  399. it is hooked to the parrallel port. Select COLOR or GRAY EPSF format
  400. depending on your printer capability.
  401.  
  402. 3D GEO:
  403. Three-dimensionnal file format compatible with most 3D modeler and renderer
  404. on the market: 3DProfessionnal, VideoScape, LightWave, Vertex, etc...
  405. Text are saved too!
  406.  
  407. Draw2000:
  408. Structured file format compatible with the following software:
  409. PageStream 2.2, Professionnal Page 3.0, AegisDraw2000. Will produce very
  410. high quality graphs even on dot-matrix printer. Note that I had some problem
  411. with the AegisDraw import module from PageStream. It seems not to recognize
  412. JcGraph's output.I had the same problems with graphs created with Advantage
  413. and Multiplot.
  414.  
  415. 8.Graph's modification.
  416. -----------------------
  417. 8.1 Font size.
  418.     You can modify font size. You have to edit the graph type with an ASCII
  419. editor. Font size for cotation is the third from the end of the ".grf" file.
  420. Font size of the lines' text is the fourth, and the colums' the fith. There
  421. is also a way to do it inside JcGraph if you got ARexx (look in ARexx script
  422. comments for details or see chapter 12).
  423.  
  424. 9.Keyboard equivalent.
  425. ----------------------
  426. PROJECT
  427. Right Amiga+O :Open...
  428. Right Amiga+S :Save
  429. Right Amiga+A :Save as...
  430. Right Amiga+1 :Format IFF ILBM
  431. Right Amiga+2 :Format EPSF
  432. Right Amiga+3 :Format 3D Geo
  433. Right Amiga+4 :Format Draw2000
  434. Right Amiga+P :Print...
  435. Right Amiga+Q :Quit...
  436.  
  437. EDIT
  438. Right Amiga+Z :Undo
  439. Right Amiga+K :Color...
  440. Right Amiga+, :Palette...
  441.  
  442. TEMPLATE
  443. Right Amiga+L :Load...
  444. Right Amiga+U :Save...
  445.  
  446. GRAPHTYPE
  447. Right Amiga+T :Load...
  448.  
  449. ENVIRONMENT
  450. Right Amiga+. :Notes...
  451. Right Amiga+R :Arrange...
  452.  
  453. HELP
  454. Right Amiga+G :General...
  455. Right Amiga+H :On Help...
  456. Right Amiga+J :Start Helper/Stop Helper
  457.  
  458. COLOR SELECTOR:
  459. Right arrow   : Select next color.
  460. Left arrow    : Select preceding color.
  461. Up arrow      : Select next line.
  462. Down arrow    : Select preceding line.
  463.  
  464. OTHERS:
  465. F1            : Open/Close preview window.
  466. F6 to F10     : ARexx controlled.
  467.  
  468. NB: ESC will get you back from most requester.
  469.  
  470. 10. Palette requester
  471. ---------------------
  472.   This requester will help you change the default color palette of the screen
  473. JcGraph is on using both RGB and HSV color model. At the top, there is some
  474. standard intuition gadget (ie Close, Depth, etc...) that need not to be
  475. documented here (refer to your user manual). The first, leftmost gadget you
  476. will see is a recessed box that shows the color actually active. Click on any
  477. color at the bottom of the requester and you will it changed accordingly.
  478. Right of this gadget is marked vertically with letters RGB followed by three
  479. sliders. It means that you are in the RGB model an that every one of the Red,
  480. Green and Blue component of the active color can be modified with the
  481. appropriate slider at right. Note that values, ranging from 0 to 15,
  482. representing the amount of each RGB component are written at slider's right.
  483. This color palette selector also offers you the possibility to work with
  484. the HSL color model (meaning Hue, Saturation and Luminance), you just have
  485. to click on the area marked RGB to see it changed to HSL, click back on HSL
  486. to return to the RGB color model.
  487.   The big, full-color, rectangular gadget at the bottom of the requester is
  488. quite self-explanatory; it helps you choose the color you want to be activated.
  489.   Next to it, at right, is a kluster of gadget that are decribed here:
  490.  
  491. COPY:   Copy the active color on to another that you will choose after.
  492. RANGE:  Will create a range between two color that you will specify.
  493. OK:     Close the requester and keep your modification
  494. CANCEL: Cancel all the change you may have done to the color palette.
  495.  
  496. The menu:
  497.  
  498. Open...: Load a color palette previously saved. Note that because it is
  499.          IFF format, JcGraph can find color palette in almost any IFF file that
  500.          as CMAP chunk (ie Preferences palette, DR2D file, ILBM, Imagine file,
  501.          etc...), this is handy.
  502. Save As...: This will save you color palette to a file wich will then be accesible
  503.             with any IFF CMAP palette reader. (Note that some palette reader
  504.             make some false assumption about IFF and may have trouble loading
  505.             JcGraph's IFF file, notabily FreePaint and Commodore's own Palette
  506.             preferences (on 2.0)!!!)
  507. Copy:     Copy the entire color palette to the Clipboard.
  508. Paste:    Paste the entire color palette from the Clipboard. (note: that's a
  509.           shame that so few program do that :-()
  510.  
  511.   Note that pressing ESC on the keyboard or closing the window will have the
  512. same effect as clicking on CANCEL gadget.
  513.  
  514. 11.TOOLTYPE and command line options.
  515. -------------------------------------
  516. SCREEN=custom       :Start JcGraph on a custom screen.
  517. SCREEN=workbench    :Start JcGraph on the workbench.
  518. HELPENGINE=file     :Where 'file' is the Help engine used by JcGraph.
  519. TOOLPRI=-127 to 127 :Is JcGraph's task priority.
  520. PORTNAME=name       :Where 'name' is the JcGraph's ARexx port name.
  521. STARTUP=scriptname  :Where 'scriptname' is an ARexx script to be executed
  522.                      on startup.
  523.  
  524. N.B.: Most of the ToolType are commented out by default using '(' and ')'.
  525.  
  526. 12. ARexx Interface:
  527. --------------------
  528.   There is now an ARexx interface for JcGraph. Of course, if you're using
  529. 1.3 or below, you need the commercial ARexx package from William Hawes or better,
  530. spend some money on 2.0. JcGraph rely heavily on ARexx for some of it's
  531. new functions like Windows default position, Rexx Button, HotKeys etc...
  532. I think I implemented a good set of Rexx commands. The one I like the most
  533. is the 'Button' command which open a world of possibilities to the user willing
  534. to learn ARexx. Default startup script is a good example of Button command.
  535. Feel free to modify my script and to distribute them (If there is one you
  536. think that could be useful to other people, send it to me, I will include it
  537. in the registered version sent to my users)
  538.  
  539. There is 40+ ARexx commands available from JcGraph.
  540. These are (in alphabetical order):
  541.  
  542. ActivateWindow:
  543.       Function: Select a window to be the current one.
  544.       Input: INTERFACE/K,OUTPUT/K,PREVIEW/K.
  545.       Output: None.
  546.       Note: None.
  547.       See also: None.
  548.  
  549. Button:
  550.       Function: Assign a script to one of the ten screen gadget.
  551.       Input: button number (1 to 10),LABEL=,script path and name.
  552.       Output: None.
  553.       Note: ex:"button 7 label=Rend JcGraph:test/tess.rex"
  554.                Parameter's position can't be changed.
  555.       See also: Keyboard.
  556.  
  557. Close:
  558.       Function: Quit JcGraph.
  559.       Input: FORCE/S.
  560.       Output: None.
  561.       Note: Same as Quit (only there to be Style Guide complient)
  562.       See also: Quit.
  563.  
  564. Copy:
  565.       Function:
  566.       Input:
  567.       Output:
  568.       Note: Should be activated in version 1.2.
  569.       See also:
  570.  
  571. GetDataColor:
  572.       Function:
  573.       Input:
  574.       Output:
  575.       Note: Should be activated in version 1.2.
  576.       See also:
  577.  
  578. GetFormat:
  579.       Function: Return JcGraph's current output file format.
  580.       Input: None.
  581.       Output: As string:
  582.               1- IFF ILBM
  583.               2- EPSF Gray
  584.               3- EPSF Color
  585.               4- 3D Geo
  586.               5- Draw 2000
  587.       Note: None.
  588.       See also: SetFormat.
  589.  
  590. GetGraphType:
  591.       Function: Returns the path to the curent graph type file + filename.
  592.       Input: None.
  593.       Output: path + filename.
  594.       Note: If returned value is DFLT, it means that no graph type has been
  595.             loaded and the default one is used. If no string is returned,
  596.             it means that no graph type is vailable.
  597.       See also: LoadGraphType.
  598.  
  599. GetRotation:
  600.       Function: Returns X,Y and Z rotation values.
  601.       Input: None.
  602.       Output: X, Y and Z values respectivly as string, space separated.
  603.       Note: ex:"12 34 45".
  604.       See also: SetRotation,GetX,GetY,GetZ,SetX,SetY,SetZ.
  605.  
  606. GetScreenAddress:
  607.       Function: Get JcGraph's screen structure pointer.
  608.       Input: None.
  609.       Output: None.
  610.       Note: Useful to seemlessly integrate your code with JcGraph.
  611.       See also: none.
  612.  
  613. GetTypeValue:
  614.       Function: Returns graph type specific data.
  615.       Input: Data position.
  616.       Output: Value as string.
  617.       Note: The data index value is absolutly not validated, so, be careful.
  618.       See also: SetTypeValue.
  619.  
  620. GetX:
  621.       Function:  Returns X rotation value.
  622.       Input: None.
  623.       Output: X rotation value string.
  624.       Note: None.
  625.       See also: SetRotation,GetRotation,GetY,GetZ,SetX,SetY,SetZ.
  626.  
  627. GetY:
  628.       Function:  Returns Y rotation value.
  629.       Input: None.
  630.       Output: Y rotation value string.
  631.       Note: None.
  632.       See also: SetRotation,GetRotation,GetX,GetZ,SetX,SetY,SetZ.
  633.  
  634. GetZ:
  635.       Function:  Returns Z rotation value.
  636.       Input: None.
  637.       Output: Z rotation value string.
  638.       Note: None.
  639.       See also: SetRotation,GetRotation,GetY,GetX,SetX,SetY,SetZ.
  640.  
  641. Keyboard:
  642.       Function: Assign an ARexx script to key F6 to F10.
  643.       Input: KEY/K,CMD/K.
  644.       Output: None.
  645.       Note: ex:"Keyboard key=F6 cmd=rexx:test.rex"
  646.       See also: Button.
  647.  
  648. LoadGraphType:
  649.       Function: Load a new type of graphic.
  650.       Input: filename.
  651.       Output: None.
  652.       Note: ex:'LoadGraphType work:jcgraph/graphtype/gugusse3D.grf'
  653.             If no filename is given, a file requester will pops-up.
  654.       See also: GetGraphType.
  655.  
  656. MoveWindow:
  657.       Function: Set the current window's position.
  658.       Input: TOPEDGE/K,LEFTEDGE/K.
  659.       Output: Window position before moving it (LeftEdge and TopEdge).
  660.       Note: Value of -1 in TopEdge or LeftEdge fields will result in no change
  661.             in position.
  662.       See also: SizeWindow.
  663.  
  664. Nop:
  665.       Function: Does absolutly nothing.
  666.       Input: None.
  667.       Output: None.
  668.       Note: None.
  669.       See also: None.
  670.  
  671. Open:
  672.       Function: Opens a JcGraph ASCII data file.
  673.       Input: FILENAME/K.
  674.       Output: None.
  675.       Note: If no filename is given, a requester asking for one will pop-up.
  676.       See also: Close, Quit.
  677.  
  678. Print:
  679.       Function: Dumps the graph to the  printer.
  680.       Input: none.
  681.       Output: 10= no graph rendered.
  682.       Note: None.
  683.       See also: None.
  684.  
  685. Quit:
  686.       Function: Quit JcGraph.
  687.       Input: FORCE/S.
  688.       Output: None.
  689.       Note: Force suppresses the modified project requester.
  690.       See also: Close.
  691.  
  692. Render:
  693.       Function: Render a graph using current settings.
  694.       Input: None.
  695.       Output: None.
  696.       Note: If no data or graph type is loaded, a requester will pops-up
  697.             telling you so.
  698.       See also: None.
  699.  
  700. RequestFile:
  701.       Function: Pops up a file requester.
  702.       Input: TITLE/K,PATH/K,FILE/K,PATTERN/K.
  703.       Output: RC=0->OK, RC=5->CANCEL, RESULT=full path + file.
  704.       Note: None.
  705.       See also: RequestString,RequestNumber,RequestResponse,RequestNotify.
  706.  
  707. RequestNotify:
  708.       Function: Pops a requester with some text and OK gadget.
  709.       Input: message.
  710.       Output: None.
  711.       Note: This is slightly different from the Style Guide;
  712.             ex: 'RequestNotify This is the message'
  713.       See also: RequestString,RequestNumber,RequestResponse,RequestFile.
  714.  
  715. RequestNumber:
  716.       Function: Pops a requester with text, Integer, OK and CANCEL gadgets.
  717.       Input: message.
  718.       Output: if RC=0 -> OK, RC=5 -> CANCEL . Result=Number as string.
  719.       Note: This is slightly different from the Style Guide;
  720.             ex: 'RequestNumber This is the message'
  721.       See also: RequestString,RequestNotify,RequestResponse,RequestFile.
  722.  
  723. RequestResponse:
  724.       Function: Pops a requester asking for a OK/CANCEL response.
  725.       Input: message.
  726.       Output: RC=0 if OK, RC=5 if CANCEL.
  727.       Note: This is slightly different from the Style Guide;
  728.             ex: 'RequestResponse This is the message'
  729.       See also: RequestString,RequestNumber,RequestNotify,RequestFile.
  730.  
  731. RequestString:
  732.       Function: Pops a requester with text, String, OK and CANCEL gadgets.
  733.       Input: message.
  734.       Output: if RC=0 -> OK, RC=5 -> CANCEL . Result=string.
  735.       Note: This is slightly different from the Style Guide;
  736.             ex: 'RequestString This is the message'
  737.       See also: RequestNumber,RequestNotify,RequestResponse,RequestFile.
  738.  
  739. Rx:
  740.       Function: Execute a rexx script asynchronously.
  741.       Input: Rexx script name.
  742.       Output: None.
  743.       Note: This is slightly different from the Style Guide;
  744.             ex: 'Rx work:test.rex'
  745.       See also: None.
  746.  
  747. Save:
  748.       Function: Save the graph using current output format.
  749.       Input: None.
  750.       Output: None.
  751.       Note: None.
  752.       See also: SaveAs.
  753.  
  754. SaveAs:
  755.       Function: Save the graph using current output format with
  756.                 the specified name.
  757.       Input: NAME/K.
  758.       Output: None.
  759.       Note: If no name is given, a file requester will pops-up.
  760.       See also: Save.
  761.  
  762.  
  763. ScreenToBack:
  764.       Function: Brings JcGraph's screen to back.
  765.       Input: None.
  766.       Output: None.
  767.       Note: None.
  768.       See also: ScreenToFront.
  769.  
  770. ScreenToFront:
  771.       Function: Brings JcGraph's screen to front.
  772.       Input: None.
  773.       Output: None.
  774.       Note: None.
  775.       See also: ScreenToBack.
  776.  
  777. SetDataColor:
  778.       Function:
  779.       Input:
  780.       Output:
  781.       Note: Should be activated in version 1.2.
  782.       See also:
  783.  
  784. SetDisplayBeepOn:
  785.       Function: Enable screen flashes when a requester appear.
  786.       Input: None.
  787.       Output: None.
  788.       Note: None.
  789.       See also: SetDisplayBeepOff.
  790.  
  791. SetDisplayBeepOff:
  792.       Function: Disable screen flashes when a requester appear.
  793.       Input: None.
  794.       Output: None.
  795.       Note: None.
  796.       See also: SetDisplayBeepOn.
  797.  
  798. SetFormat:
  799.       Function: Set current JcGraph output file format.
  800.       Input: File format number.
  801.       Output: 0 if ok, 10 otherwise.
  802.       Note:   Format number:
  803.  
  804.               1- IFF ILBM
  805.               2- EPSF Gray
  806.               3- EPSF Color
  807.               4- 3D Geo
  808.               5- Draw 2000
  809.       See also: GetFormat.
  810.  
  811. SetRotation:
  812.       Function: Set X,Y and Z rotation value respectivly.
  813.       Input: x value, y value, z value.
  814.       Output: None.
  815.       Note: ex: "SetRotation 12 32 14"
  816.       See also: SetX, SetY, SetZ, GetX, GetY, GetZ, GetRotation.
  817.  
  818. SetTypeValue:
  819.       Function: Set graph type specific data.
  820.       Input: index of value to be changed, value.
  821.       Output: None.
  822.       Note: Value and inded aren't validated at all, so, be carefull.
  823.       See also: GetTypeValue.
  824.  
  825. SetX:
  826.       Function: Set X rotation value.
  827.       Input: value.
  828.       Output: None.
  829.       Note: ex: "SetX 10"
  830.       See also: SetY, SetZ, GetX, GetY, GetZ, GetRotation, SetRotation.
  831.  
  832. SetY:
  833.       Function: Set Y rotation value.
  834.       Input: value.
  835.       Output: None.
  836.       Note: ex: "SetY 10"
  837.       See also: SetX, SetZ, GetX, GetY, GetZ, GetRotation, SetRotation.
  838.  
  839. SetZ:
  840.       Function: Set Z rotation value.
  841.       Input: value.
  842.       Output: None.
  843.       Note: ex: "SetZ 10"
  844.       See also: SetY, SetX, GetX, GetY, GetZ, GetRotation, SetRotation.
  845.  
  846. SizeWindow:
  847.       Function: Set the current window's size.
  848.       Input: WIDTH/N,HEIGHT/N.
  849.       Output: Window size before sizing it (Width and Height).
  850.       Note: Value of -1 in width or height fields will result in no change
  851.             in size. Interface window can't be sized, so, it will only
  852.             return it's size.
  853.       See also: MoveWindow.
  854.  
  855. Version:
  856.       Function: To get JcGraph's version number.
  857.       Input: None.
  858.       Output: Version number in form 'ProgramName 9.99 (DD/MM/YY)'
  859.       Note: None.
  860.       See also: None.
  861.  
  862. WindowToFront:
  863.       Function: Brings current window to front.
  864.       Input: None.
  865.       Output: None.
  866.       Note: None.
  867.       See also: WindowToBack, ActivateWindow.
  868.  
  869. WindowToBack:
  870.       Function: Brings current window to back.
  871.       Input: None.
  872.       Output: None.
  873.       Note: None.
  874.       See also: WindowToFront, ActivateWindow.
  875.  
  876. 13.Graph type file format:
  877. --------------------------
  878.   I think this is one of the best part of JcGraph (from a programmer's point
  879. of view) it brings me back about 2 years ago: I have seen some Amiga, Mac and
  880. PC charting program and what striked me is that it seemed that there was a piece
  881. of code for each one of the graphs... what a waste! There was surely a way to
  882. draw a general rule for creating all the graphs and after some hours of
  883. refining an inital idea, I came up with this:
  884.  
  885. 1001,             : Graph type identifier.
  886.  
  887. GraphType points:
  888. -----------------
  889. Points are organized in two sets of X,Y values. First X,Y set is for
  890. the bottom of the block, second , for the top.
  891.  
  892. 4,                : Total number of points of one block.
  893.  
  894. 0,0,              : 1. X,Y of the bottom.
  895. 0,20,             : 1. X,Y of the top.
  896.  
  897. 40,0,             : 2. X,Y of the bottom.
  898. 40,20,            : 2. X,Y of the top.
  899.  
  900. 40,40,            : 3. X,Y of the bottom.
  901. 40,20,            : 3. X,Y of the top.
  902.  
  903. 0,40,             : 4. X,Y of the bottom.
  904. 0,20,             : 4. X,Y of the top.
  905.  
  906. Inter-block links:
  907. ------------------
  908. 2,3,1,4,         : If link flag is set, point 2 of the one block will be
  909.                    linked with point 1 of the following X block. 3 linked to
  910.                    4. Just two links per side are allowed.
  911. 3,4,2,1,         : If link flag is set, point 3 of the one block will be
  912.                    linked with point 2 of the following Y block. 4 linked to
  913.                    1. Just two links per side are allowed.
  914.  
  915. GraphType Flags:
  916. ----------------
  917. 2,2,              : X , Y data rows and columns of preview.
  918. 70,               : Next column spacing.
  919. 70,               : Next line spacing.
  920. 2,                : Y  data multiplier.
  921. 0,                : Joined X ? (0 or 1)
  922. 0,                : Joined Y ? (0 or 1)
  923. 0,                : Stacked ? (0 or 1)
  924. 1,                : 3-D ? (0 or 1)
  925. 0,                : Percent (pie chart) ? (0 or 1)
  926. 0,                : Block top only ? (0 or 1)
  927. 0,                : Inter-block only ? (0 or 1)
  928. 0,                : 90 degree rotation of block ? (0 or 1)
  929. 0,                : Next line shear value.
  930. 0,                : ALWAYS 0.
  931. 0,                : SIDEBYSIDE ( 0 or 1)
  932. 0,                : Y shear value.
  933. 0,                : Undefined.
  934. 40,               : Max. X block size.
  935. 40,               : Max. Y block size.
  936. 15,               : Font scale to X (scale to points value)
  937. 15,               : Font scale to Y.
  938. 15,               : Font scale to Z.
  939. 10,               : Z text offset from graph.
  940. 20,               : X text offset from graph.
  941.  
  942. I think this design is a good compromise between flexibility, simplicity and
  943. size. Experiment with it... no validation is done on graph type but anyway,
  944. you should know what you are doing when creating a new graph type.
  945. Of course, this is FAR from perfection and I now see many possible upgrades
  946. to this format that would require a severe re-write of most part of my code
  947. and unless some gigantic mega software compagny pay me to do that, I will
  948. leave this to the reader. Of course, you cannot use this in commercial code
  949. but if you want to share some ideas, write to me, I will be pleased to answer
  950. your letter.
  951.  
  952. 14.The future of JcGraph:
  953. -------------------------
  954.  
  955.     JcGraph is the first important piece of code I write for the Amiga. And
  956. even if I spent much time to it's realisation, some features could not have
  957. been implemented, because of a lack of time and funding (beeing a full time
  958. student). So I privilegied quality over quantity. But, if the effort I put
  959. in JcGraph would reflect in a high number of registration, I would probably
  960. spend some more time upgrading it. Here is a list of what could be in a
  961. future release:
  962.  
  963. -Some more ARexx scripts.
  964. -Some more ARexx commands.
  965. -LightWave file format.
  966. -DR2D.
  967.  
  968. THE BOTTOM LINE (READ IT BEFORE SENDING ANY MONEY):
  969. ---------------------------------------------------
  970. It is sad because I haven't had enough registration to be worth continuing
  971. to upgrade JcGraph. Maybe I haven't spread it enough but I guess it's not
  972. just that. Anyway, I will continue to fix bugs for my registered users and
  973. I MAY do some minor upgrades someday (really no garantee here). What bugs me
  974. the most is that every people that tried my software seemed to enjoy it a lot.
  975. Well, I will take a short Amiga programming break and will come back with
  976. other projects that are knocking to get out of my head :-0. JcGraph was many
  977. things to me:
  978. First, it was a proof that I can take a programming project of good proportion
  979. (for a single person) from the ground to a commercial quality state (I think so).
  980. Second, it was an answer to those stupid pirates who say "Ah, software are too high
  981. priced and all the money goes to a big guy in a Rolls-Royce". Well, my piece
  982. of code hasn't any equivalent on the Amiga market yet(and in some way, on any market)
  983. and it cost 40$ CDN. And I have no other mean of transportation than my own
  984. legs. Anyway, if you don't want my software, you can still mail to me, I
  985. stand for communication and I like to ear from people.
  986.  
  987. Any suggestion or comment can be send to:
  988.  
  989.             Jean-Christophe Clément
  990.             921, rang 3
  991.             St-Simon
  992.             Québec, CANADA
  993.             J0H-1Y0
  994.  
  995. If you send me suggestions, please, send them in descending order of
  996. priority (ie If you BADLY want feature A over feature B, put it first!).
  997. If you report a bug, please give an example and be precise because it may
  998. be clear in your mind but not in mine (ex: if you say "many more",
  999. I want to know how much it is !).
  1000.  
  1001. 15.JcGraph's history:
  1002. ---------------------
  1003.  
  1004. april 23 , 1992:(v0.90)
  1005.     -Beta release.
  1006.  
  1007. april 27 , 1992:(v0.901)
  1008.     -Corrected little mem alloc bug.
  1009.  
  1010. april 30 , 1992:(v0.902)
  1011.     -Added precision on 2D graphs.
  1012.     -Stack graph added.
  1013.     -Better support for floating point value.
  1014.  
  1015. may 14 , 1992:(v0.903)
  1016.     -Corrected one small problem with perspective.
  1017.  
  1018. october 10 , 1992:(v1.100)
  1019.     Major upgrade!!
  1020.     -Corrected some stupid bugs (no more problem on quit.)
  1021.     -Added an ARexx port (40+ commands) almost fully 2.0 style guide compliant.
  1022.     -Now supports the standard file requester under WB 2.0 (so that you can
  1023.      trap it with the incredible "Magic File Requester" from Stefan Stuntz.
  1024.      Boy, this requester is 1/2 as big as JcGraph (80k vs 170k) but worth every
  1025.      single bytes!). For those poor people who still use WB < 2.0... Get it (2.0)
  1026.      the soonest possible, you won't regret it. But until then, JcGraph will
  1027.      use the KD_freq for you!!
  1028.     -Well, it's been one months I've been using JcGraph about 5 hour a day
  1029.      and it has not crashed on me once. Configuration were varying from 512k
  1030.      to 3 full megs. So, I guess I can say it is quite robust now...
  1031.     -JcGraph now come with a nice disk sticker!!
  1032.     -A nice Color Palette editor has been added based on one done by
  1033.      RJ Mical with some eastethic and ergonomic enhancement.
  1034.     -Should not have problem with bigger fonts anymore.
  1035.     -Preview can now be sized and closed.
  1036.     -MANY useful Rexx scripts are included.
  1037.     -JcGraph does some more file checking on data.
  1038.     -more startup options.
  1039.     -other small stuff that you will be happy to discover yourself !!
  1040.  
  1041. Thanks to:
  1042. Richard Loubier, Pierre-Louis Constantin, Steve Davis, Dominic Giampaolo and
  1043. all those who supported my work on JcGraph.