home *** CD-ROM | disk | FTP | other *** search
/ Informática Multimedia: Special Games / INFESPGAMES.mdf / os2 / spl / src / spl.ipf < prev    next >
Encoding:
Information Presentation Facility markup  |  1994-07-27  |  20.2 KB  |  631 lines
  1. :userdoc.
  2. :docprof toc=1234.
  3. :title.Spellbook Manager Docs
  4.  
  5. :h1 res=0.Introduction and Copyright
  6. :i1.Introduction and Copyright
  7. :p.
  8. :lines align=center.
  9. :font facename='Tms Rmn' size=36x24.
  10. :hp4.
  11. Spellbook Manager
  12. :font facename=default size=0x0.
  13. :ehp4.
  14. :hp1.spl.exe:ehp1.
  15.  
  16. :hp2.Version 1.73:ehp2.
  17.  
  18. :hp2.7/26/94:ehp2.
  19.  
  20. :hp2.Copyright (C) 1993, 1994 John-Marc Chandonia:ehp2.
  21.  
  22. :elines.
  23. :p.
  24. For suggested enhancements and bug reports, please mail
  25. :font facename=Courier size=13x8.
  26. chandoni@husc8.harvard.edu
  27. :font facename=default size=0x0.
  28. or write:
  29.  
  30. :lines align=center.
  31. John-Marc Chandonia
  32. 7 Divinity Avenue, #121
  33. Cambridge, Ma. 02138
  34. :elines.
  35. :p.
  36. This is spl, a program for handling spells and spellbooks
  37. from various fantasy role-playing (FRP) games.  It can handle
  38. both mage and priest spells for TSR's AD&.D (a trademark of TSR, Inc)
  39. game, and can easily be expanded to handle other systems as well.
  40. In addition to possibly being useful to FRP players and
  41. GM's, the source may be useful to OS/2 2.x programmers learning
  42. about containers, MLE's, and PM programming in general.
  43. :p.
  44. This program is free software; you can redistribute it and/or modify
  45. it under the terms of the GNU General Public License as published by
  46. the Free Software Foundation; either version 2 of the License, or
  47. (at your option) any later version.
  48. :p.
  49. This program is distributed in the hope that it will be useful,
  50. but WITHOUT ANY WARRANTY; without even the implied warranty of
  51. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  52. GNU General Public License for more details.
  53. :p.
  54. You should have received a copy of the GNU General Public License
  55. along with this program; if not, write to the Free Software
  56. Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  57. :p.
  58. :h1 res=1.Release Notes
  59. :i1.Release Notes
  60. :hp2.Version 1.73&colon.:ehp2.
  61. :sl.
  62. :li.Several ways of sorting books are supported.
  63. :li.You can choose which fields to show in details view.
  64. :li.Spellbooks can be loaded from the command line.
  65. :li.Multiple books can be loaded simultaneously.
  66. :esl.
  67. :p.
  68. :hp2.Version 1.5&colon.:ehp2.
  69. :sl.
  70. :li.Spell searching, sorting, loading, and saving are now multithreaded,
  71. allowing you to work on other books or adjust the window while the
  72. program is working.
  73. :li.Multiple views of the spellbook are supported.
  74. :li.Large or small icons are supported.
  75. :li.On-line help is available by pressing F1 or using the help menu/buttons.
  76. :li.Spellbook position, view, icon size, and details bar position are
  77. saved in EA's/INI files.
  78. :li.Spell descriptions are loaded in as required, using less memory.
  79. :li.Spells in the master list are saved in a "quick reference" file for
  80. faster loading.
  81. :esl.
  82. :p.
  83. :hp2.Version 1.0&colon.:ehp2.
  84. :p.
  85. This is the first initial release of the program.
  86. :p.
  87. Known bugs are listed in the file 
  88. :font facename=Courier size=13x8.
  89. bugs.txt.
  90. :font facename=default size=0x0.
  91. If you find any more, please either fix them yourself and send
  92. me the patch (sure!) or report the bug to the address given
  93. above.
  94. :p.
  95. I will put all future versions of this program on the OS/2
  96. anonymous ftp site, currently
  97. :font facename=Courier size=13x8.
  98. ftp-os2.cdrom.com.
  99. :font facename=default size=0x0.
  100. If you distribute any enhanced versions of this program, please
  101. do the same.  Also, please comment any changes in the source
  102. code, and describe them in the file 
  103. :font facename=Courier size=13x8.
  104. changes.txt.
  105. :font facename=default size=0x0.
  106.  
  107. :h1 res=2.Using the program
  108. :i1 id=using.Using the program
  109. This section describes how to install and use the program.
  110. :p.
  111. Topics include&colon.
  112. :lines.
  113.     :link reftype=hd res=3.Installation:elink.
  114.     :link reftype=hd res=4.Master spell list:elink.
  115.     :link reftype=hd res=5.Icon mapping:elink.
  116.     :link reftype=hd res=6.Spellbook window:elink.
  117.     :link reftype=hd res=38.Spell window:elink.
  118. :elines.
  119. :h2 res=3.Installation
  120. :i2 refid=using.Installation
  121. Unzip the zip file in some directory.  If you want, create a program
  122. object for the file
  123. :font facename=Courier size=13x8.
  124. spl.exe,
  125. :font facename=default size=0x0.
  126. If you don't plan to look at the source code, you can delete the
  127. src directory... this is not needed to run the program.
  128. :p.
  129. Check out the file
  130. :font facename=Courier size=13x8.
  131. splbook.all,
  132. :font facename=default size=0x0.
  133. which contains pointers to all spellbooks which will comprise the
  134. :link reftype=hd res=4.master spell list:elink..
  135. :p.
  136. Also, look at the file
  137. :font facename=Courier size=13x8.
  138. splicon.res
  139. :font facename=default size=0x0.
  140. which contains a 
  141. :link reftype=hd res=5.mapping:elink.
  142. of spell spheres and schools to icons.
  143. :p.
  144. You already know how to view the docs; to run the program, just run 
  145. :font facename=Courier size=13x8.
  146. spl.exe.
  147. :font facename=default size=0x0.
  148.  
  149. :h2 res=4.Master spell list
  150. :i2 refid=using.Master spell list
  151. :p.
  152. The file
  153. :font facename=Courier size=13x8.
  154. splbook.all
  155. :font facename=default size=0x0.
  156. contains a list of spellbooks which make up the master spell list.
  157. These spellbooks should contain full spell listings.   This is
  158. important because other spellbooks are by default saved only
  159. as lists of titles, which are then looked up in the master spell
  160. list as the spells are loaded in.
  161. :p.
  162. The format of this file is just a list of other files.  To place a
  163. comment in this list, start the line with a semicolon.
  164. :p.
  165.  
  166. :h2 res=5.Icon mapping
  167. :i2 refid=using.Icon mapping
  168. :p.
  169. The file
  170. :font facename=Courier size=13x8.
  171. splicon.def
  172. :font facename=default size=0x0.
  173. contains a mapping of spell schools and spheres to icons.
  174. :p.
  175. Spells in a book are shown with an icon which corresponds to their sphere
  176. (if given) or school (if no sphere is available).  This file contains
  177. a list of text strings to look for in the schools and spheres, and
  178. a list of icons they correspond to.  If a spell matches two or more
  179. text strings, the first one found is used.
  180. :p.
  181. The format of the file is a text string (containing no spaces), then
  182. a space, then the path name of an icon file to use.  Comments are
  183. allowed, as long as they begin with a semicolon.
  184. :p.
  185.  
  186. :h2 res=6.Spellbook window
  187. :i2 refid=using.Spellbook window
  188. :p.
  189. This is a window which represents a spellbook; it contains icons
  190. representing spells in the book.  This window has can be viewed
  191. several ways, representing spells as single icons, or more
  192. or less detailed views.
  193. :p.
  194. Several menus can be activated from this window&colon.
  195. :lines.
  196.     :link reftype=hd res=7.File Menu:elink.
  197.     :link reftype=hd res=15.Spell Menu:elink.
  198.     :link reftype=hd res=18.Book Menu:elink.
  199.     :link reftype=hd res=22.Views Menu:elink.
  200.     :link reftype=hd res=29.Help Menu:elink.
  201. :elines.
  202. :p.
  203. Also, pop-up context menus are available, either by clicking on the
  204. background of the spellbook, or on individual spells.  The default
  205. OS/2 method for bringing up these menus uses the right mouse button&colon.
  206. :lines.
  207.     :link reftype=hd res=35.Spell Context Menu:elink.
  208.     :link reftype=hd res=36.Spellbook Context Menu:elink.
  209. :elines.
  210.  
  211. :h3 res=7.File menu
  212. :p.
  213. Options on this menu include&colon.
  214. :lines.
  215.     :link reftype=hd res=8.New Spellbook:elink.
  216.     :link reftype=hd res=9.Load Spellbook:elink.
  217.     :link reftype=hd res=11.Save Spellbook:elink.
  218.     :link reftype=hd res=12.Save Full Spellbook:elink.
  219.     :link reftype=hd res=13.Close Spellbook:elink.
  220.     :link reftype=hd res=14.Quit Program:elink.
  221. :elines.
  222.  
  223. :h4 res=8.New Spellbook
  224. :p.
  225. This will create a new (empty) spellbook window that you can
  226. :link reftype=hd res=37.drag and drop:elink.
  227. spells into.
  228.  
  229. :h4 res=9.Load Spellbook
  230. :p.
  231. This will load in a spellbook from a file.  This file can contain
  232. a full spellbook, including the text of the spells, or it can
  233. be a list of spell names to be looked up in the master list.
  234. Spells listed by name in a spellbook but not found in the master
  235. list will be ignored (you will be warned if there are any).
  236.  
  237. :h4 res=11.Save Spellbook
  238. :p.
  239. This will save the names of spells in the current spellbook
  240. to disk.
  241.  
  242. :h4 res=12.Save Full Spellbook
  243. :p.
  244. This will save the complete spellbook (names and descriptions)
  245. to disk.  If the spells are in the master list, you might want
  246. to just save the names instead.
  247.  
  248. :h4 res=13.Close Spellbook
  249. :p.
  250. This will close the current spellbook.  If it has been changed
  251. but not saved, you will be asked if you want to save it first.
  252. This option is equivalent to double-clicking on the box in the
  253. upper left corner of the book, or selecting "Window -> Close"
  254. :p.
  255. Closing the last spellbook will end the program.  You can close
  256. the master spell index if you want (once another window is open),
  257. as the spells themselves are still in memory.
  258.  
  259. :h4 res=14.Quit Program
  260. :p.
  261. This will close all open spellbooks and exit the program.  If
  262. any spellbooks have been changed but not saved, a window will
  263. pop up asking if you really want to do this or not.
  264.  
  265. :h3 res=15.Spell menu
  266. :p.
  267. These options are only available if the book is writeable
  268. (i.e. not the master spell list).
  269. :p.
  270. This menu includes&colon.
  271. :lines.
  272.     :link reftype=hd res=16.Add New Spell:elink.
  273.     :link reftype=hd res=17.Delete Spell:elink.
  274. :elines.
  275.  
  276. :h4 res=16.Add New Spell
  277. :p.
  278. This will add a new spell to the book; it isn't really useful
  279. in this version.
  280.  
  281. :h4 res=17.Delete Spell
  282. :p.
  283. This will remove selected spells from the book.
  284.  
  285. :h3 res=18.Book menu
  286. :p.
  287. This menu includes&colon.
  288. :lines.
  289.     :link reftype=hd res=10.Master List:elink.
  290.     :link reftype=hd res=19.Find Subset:elink.
  291.     :link reftype=hd res=20.Sort Spellbook:elink.
  292.     :link reftype=hd res=21.Rename Spellbook:elink.
  293. :elines.
  294.  
  295. :h4 res=10.Master list
  296. :p.
  297. This will bring up a window with all spells in the
  298. master list.  You can drag and drop these into spellbooks,
  299. or look at them directly.
  300.  
  301. :h4 res=19.Find subset
  302. :p.
  303. This brings up a dialog which allows you to search through the
  304. spells in the book (window) and bring up a new book (window)
  305. which contains the results of the search.
  306. :p.
  307. Spells can be sorted on several fields, with the results
  308. OR'ed or AND'ed together depending on the buttons in the
  309. lower left corner of the dialog.  Case sensitivity is also
  310. optional.  Most of the fields just want you to enter text.
  311. :p.
  312. The "level" field allows you to enter a number for the spell
  313. level, such as "5" to select all 5th level spells.  It also
  314. allows you to enter things like ">5" or "<5" to select all
  315. spells higher or lower than a certain level.
  316. :p.
  317. The "description" field allows you to enter several lines of
  318. text instead of only one.  All lines entered are searched
  319. for in the spell descriptions, with the results OR'ed or 
  320. AND'ed together according to the button pushed on the right.
  321. :p.
  322. Searches go faster with case sensitivity enabled.  Also,
  323. searches go faster if the program doesn't have to search through
  324. entire spell descriptions... limit using the other fields if possible.
  325. :p.
  326. Searching is multithreaded, so you can work on other books
  327. while the search is in progress.
  328.  
  329. :h4 res=20.Sort spellbook
  330. :p.
  331. This sorts the spellbook by several criteria&colon.
  332. :lines.
  333.     Caster Type
  334.     Name of Spell
  335.     Spell level
  336.     School/Sphere
  337.     Components
  338.     Save
  339. :elines.
  340. :p.
  341. Sorting is multithreaded, although usually quick.
  342.  
  343. :h4 res=21.Rename spellbook
  344. :p.
  345. This renames the spellbook... it does not change the actual name of
  346. the file the spellbook is saved in, only the name which appears
  347. at the top of the window.
  348.  
  349. :h3 res=22.Views Menu
  350. :p.
  351. The Views menu includes&colon.
  352. :lines.
  353.     :link reftype=hd res=23.Icon View:elink.
  354.     :link reftype=hd res=24.Name View:elink.
  355.     :link reftype=hd res=25.Text View:elink.
  356.     :link reftype=hd res=26.Details View:elink.
  357.     :link reftype=hd res=51.Details Fields:elink.
  358.     :link reftype=hd res=27.Small Icons:elink.
  359.     :link reftype=hd res=28.Large Icons:elink.
  360. :elines.
  361. :p.
  362. Spellbooks remember which view they are in, whether to use large
  363. or small icons, and the bar position in details view.  This is
  364. stored in extended attributes for saved spellbooks, or in the
  365. INI file for the master spell window and new windows.
  366.  
  367. :h4 res=23.Icon View
  368. :p.
  369. This shows each spell as an icon with the name of the spell underneath.
  370.  
  371. :h4 res=24.Name View
  372. :p.
  373. This shows each spell on a single line with the icon to the left and
  374. the name to the right.
  375.  
  376. :h4 res=25.Text View
  377. :p.
  378. This just shows the spell names, one per line.
  379.  
  380. :h4 res=26.Details View
  381. :p.
  382. This shows the spell and some other relevant details such as spell
  383. level, and the school or sphere of the spell.
  384. :p.
  385. Which fields actually get shown are controlled by the
  386. boxes checked off in the
  387. :link reftype=hd res=51.Details Fields:elink.
  388. dialog.
  389.  
  390. :h4 res=51.Details Fields
  391. :p.
  392. This dialog allows you to display which details of the spell
  393. get shown.  Choices include&colon.
  394. :lines.
  395.     Spell Level
  396.     Casting Time
  397.     Range
  398.     Duration
  399.     Area of Effect
  400.     Sphere or School
  401.     Components
  402.     Saving Throw
  403. :elines.
  404.  
  405. :h4 res=27.Small Icons
  406. :p.
  407. This uses small icons in all views that show icons; the icons
  408. lose detail, but allow more spells on the screen.
  409.  
  410. :h4 res=28.Large Icons
  411. :p.
  412. This tells the book to use large icons to represent spells; these
  413. are as detailed as other icons in your system.
  414.  
  415. :h3 res=29.Help Menu
  416. :p.
  417. This includes&colon.
  418. :lines.
  419.     :link reftype=hd res=30.Help Index:elink.
  420.     :link reftype=hd res=31.General Help:elink.
  421.     :link reftype=hd res=33.Using Help:elink.
  422.     :link reftype=hd res=34.About:elink.
  423. :elines.
  424.  
  425. :h4 res=30.Help Index
  426. :p.
  427. This will display an index of help topics from within the program.
  428.  
  429. :h4 res=31.General Help
  430. :p.
  431. This will bring up general help on using this program, like pushing
  432. F1.
  433.  
  434. :h4 res=33.Using Help
  435. :p.
  436. This will bring up help on how OS/2's help system works.
  437.  
  438. :h4 res=34.About
  439. :p.
  440. This will briefly describe the program.
  441.  
  442. :h3 res=35.Spell Context Menu
  443. :p.
  444. This menu will pop up if you right-click on a spell in the spellbook.
  445. :p.
  446. The menu includes&colon.
  447. :lines.
  448.     :link reftype=hd res=38.Show spell:elink.
  449.     :link reftype=hd res=17.Delete spell:elink.
  450. :elines.
  451.  
  452. :h3 res=36.Spellbook Context Menu
  453. :p.
  454. This menu will pop up if you right-click in the spellbook window 
  455. somewhere in the blank (empty) part of the window.
  456. :p.
  457. The menu includes the options found in the 
  458. :link reftype=hd res=22.Views:elink.
  459. and
  460. :link reftype=hd res=18.Book:elink.
  461. menus.
  462.  
  463. :h3 res=37.Drag and Drop
  464. :p.
  465. To copy spells between windows (spellbooks), drag them with the right mouse
  466. button.  You can select several spells with the left button.  Dragging
  467. can also be used to reposition spells within a window, if the window
  468. is not read-only.
  469.  
  470. :h2 res=38.Spell Window
  471. :i2 refid=using.Spell Window
  472. :p.
  473. To bring up a spell in detail, double click on it, or
  474. select "show spell" from the context menu.  This brings
  475. up a window which is pretty self-explanatory.  Use ALT-N or ALT-P
  476. as a shortcut to go to the next or previous spell in the book.
  477. :p.
  478. You can copy text from spells onto the clipboard using the
  479. usual methods.  You can even edit and change spells, although
  480. this doesn't work very well and will probably require you to
  481. go in and fix the saved text file with an editor.
  482. :p.
  483. Any file you change and save is saved in the file
  484. :font facename=Courier size=13x8.
  485. splbook.chg.
  486. :font facename=default size=0x0.
  487.  
  488. :h1 res=39.Source information
  489. :i1 id=src.Source information
  490. :p.
  491. The source is written in C++ for the IBM C++ compiler; it will
  492. probably work with other compilers, although I haven't tested
  493. this.  You need a C++ compiler and a resource compiler to compile
  494. the dialogs and menus.
  495. :p.
  496. The makefile is compatible with GNU's make.
  497. :p.
  498. You need an IPF compiler (IPFC) to compile the documentation.
  499. :p.
  500. Click one of the following for more information&colon.
  501. :lines.
  502.     :link reftype=hd res=41.general.cpp:elink.
  503.     :link reftype=hd res=42.splbook.cpp:elink.
  504.     :link reftype=hd res=43.spl.cpp:elink.
  505.     :link reftype=hd res=44.bookwin.cpp:elink.
  506.     :link reftype=hd res=45.splobj.cpp:elink.
  507.     :link reftype=hd res=46.splwin.cpp:elink.
  508.     :link reftype=hd res=47.spldlgs.cpp:elink.
  509.     :link reftype=hd res=48.splhelp.cpp:elink.
  510.     :link reftype=hd res=49.ea.cpp:elink.
  511. :elines.
  512.  
  513. :h2 res=41.general.cpp
  514. This file contains some generally useful functions which are
  515. called from the rest of the code.  None are PM specific.
  516. :p.
  517. :hp2.fatal, error, warning:ehp2. - these are 3 error functions
  518. indicating various levels of severity.  These are pretty useless
  519. in a PM program.
  520. :p.
  521. :hp2.chkcalloc:ehp2. - this is a memory allocation function,
  522. which is pretty useless
  523. for a C++ program.  (Just use "new" instead)
  524. :p.
  525. :hp2.upstr, lowstr:ehp2. - these are 2 string functions to capitalize
  526. and uncapitalize a
  527. string... these are rarely found in C libraries, so they're
  528. included here.  These actually get used in the code.
  529. :p.
  530. :hp2.fgets_no_cr:ehp2. - this works just like fgets(), but removes
  531. the \n at the end of the string.
  532.  
  533. :h2 res=42.splbook.cpp
  534. These files contain the C++ classes for handling spells and
  535. spellbooks, and contain no OS/2-specific or PM-specific
  536. information.  Routines for reading and writing spells out
  537. of files are given.
  538. :p.
  539. Note that the classes are set up to allow later addition of
  540. psionic disciplines as a subclass of the general spell.  This
  541. is why the "magespell" class contains things like "school" and
  542. so forth that you would normally associate with all spells.
  543. :p.
  544. If you want to change this program to change the format of
  545. how spells are read in and out (for example to use this
  546. program with another FRP system) this is the file to change.
  547. It is also the most portable to other systems besides OS/2.
  548. :p.
  549.  
  550. :h2 res=43.spl.cpp
  551. :p.
  552. This file contains some initialization and general use (PM) functions
  553. which get called from classes.
  554. :p.
  555. Routines to load in the icon file, look up an icon for a given
  556. spell, load in the INI file, enable/disable or check/uncheck
  557. menu items, and printf() to a window's title bar are in here.
  558.  
  559. :h2 res=44.bookwin.cpp
  560. :p.
  561. :hp2.bookwindow:ehp2. is a class which refers to the spellbook windows which
  562. appear on the screen.  The class definition appears in
  563. bookwin.hpp.  
  564. :p.
  565. Bookwindow functions which are handled in the main thread
  566. are included in bookwin.cpp.
  567.  
  568. :h2 res=45.splobj.cpp
  569. :p.
  570. The object thread for bookwindows is handled here.  Both
  571. the object window function and the main() thread which
  572. creates it are defined here.
  573. :p.
  574. Bookwindow functions that are handled in the object thread
  575. are in this file.
  576.  
  577. :h2 res=46.splwin.cpp
  578. :p.
  579. :hp2.spellwindow:ehp2. is a class which refers to the spell windows
  580. which show the detailed descriptions of spells.  The class
  581. definition appears in splwin.hpp.
  582. :p.
  583. Spell windows are not multithreaded; all the code required to
  584. handle them is in splwin.cpp.
  585.  
  586. :h2 res=47.spldlgs.cpp
  587. :p.
  588. These files contain all the code required for processing the
  589. dialog boxes used in the program.
  590.  
  591. :h2 res=48.splhelp.cpp
  592. :p.
  593. These files contain code for on-line help.
  594.  
  595. :h2 res=49.ea.cpp
  596. :p.
  597. These files contain OS/2 specific file handling code.
  598. :p.
  599. :hp2.query_last_write:ehp2. is a function for finding out the
  600. last time a file has been written to.
  601. :p.
  602. :hp2.getEA:ehp2. is a function for reading an given EA out of a file.
  603. It may contain bugs; I have little coherent information on
  604. OS/2's EAs.
  605. :p.
  606. :hp2.putEA:ehp2. is a function for writing data to a named
  607. EA of a file.  It works, but could stand to be debugged also.
  608.  
  609. :h1 res=50.Planned enhancements
  610. :i1.Planned enhancements
  611. :p.
  612. These are things I plan to add to the program in the future, both
  613. in order to give it more functionality, and in order to learn more
  614. about PM programming myself.  If you would like to help me out
  615. with any of these, please let me know what you're working on.
  616. :p.
  617. Spellbooks within spellbooks... should make the master list
  618. much easier to view.
  619. :p.
  620. Allow users to edit/save spells in a way that actually works.
  621. :p.
  622. Allow users to change default names of things; save in .ini file.
  623. (Also find .ini file if not in same directory)
  624. :p.
  625. More drag and drop stuff... should allow you to drop a text file
  626. into a spell window and read it in.  Also, should allow you to
  627. drag a spell onto the printer and print it.  Drag and drop
  628. icon assignment would also be cool.
  629. :p.
  630. :euserdoc.
  631.