═══ 1. Introduction and Copyright ═══ Spellbook Control Program spl.exe Version 1.0 8/10/93 Copyright (C) 1993 John-Marc Chandonia For suggested enhancements and bug reports, please mail chandoni@husc8.harvard.edu or write: John-Marc Chandonia 7 Divinity Avenue, #121 Cambridge, Ma. 02138 This is spl, a program for handling spells and spellbooks from various fantasy role-playing (FRP) games. It can handle both mage and priest spells for TSR's AD&D (a trademark of TSR, Inc) game, and can easily be expanded to handle other systems as well. In addition to possibly being useful to FRP players and GM's, the source may be useful to OS/2 2.x programmers learning about containers, MLE's, and PM programming in general. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. ═══ 2. Release Notes ═══ This is the first public release of the program, and therefore probably has many more bugs than I know about! Known bugs are listed in the file bugs.txt. If you find any more, please either fix them yourself and send me the patch (sure!) or report the bug to the address given above. I will put all future versions of this program on the OS/2 anonymous ftp site, currently ftp-os2.cdrom.com. If you distribute any enhanced versions of this program, please do the same. Also, please comment any changes in the source code, and describe them in the file changes.txt. ═══ 3. Using the program ═══ This section describes how to install and use the program. ═══ 3.1. Installation ═══ Unzip the zip file in some directory. If you want, create a program object for the file spl.exe, If you don't plan to look at the source code, you can delete the src directory... this is not needed to run the program. Check out the file splbook.all, which contains pointers to all spellbooks which will comprise the master spell list. Click here for more information. Also, look at the file splicon.res which contains a mapping of sphell spheres and schools to icons. Click here for more information. You already know how to view the docs; to run the program, just run spl.exe. ═══ 3.2. Master spell list ═══ The file splbook.all contains a list of spellbooks which make up the master spell list. These spellbooks should contain full spell listings. This is important because other spellbooks are by default saved only as lists of titles, which are then looked up in the master spell list as the spells are loaded in. The format of this file is just a list of other files. To place a comment in this list, start the line with a semicolon. ═══ 3.3. Icon mapping ═══ The file splicon.def contains a mapping of spell schools and spheres to icons. Spells in a book are shown with an icon which corresponds to their sphere (if given) or school (if no sphere is available). This file contains a list of text strings to look for in the schools and spheres, and a list of icons they correspond to. If a spell matches two or more text strings, the first one found is used. The format of the file is a text string (containing no spaces), then a space, then the path name of an icon file to use. Comments are allowed, as long as they begin with a semicolon. ═══ 3.4. File menu ═══ From this menu, you can load and save spellbooks, or create new spellbooks. Loading a spellbook will create a new window. Spellbooks can be loaded and saved in two ways. The menu options "Load Spellbook" and "Save Spellbook" only save lists of spells, which are looked up in the master list. The options referring to the "full" spellbook save the entire text of spells. ═══ 3.5. Spell menu ═══ These options are only available if the book is writeable (i.e. not the master spell list). These options allow you to add new spells (use Drag and Drop instead) or delete spells from a book. ═══ 3.6. Book menu ═══ These are more detailed descriptions of options under the book menu. ═══ 3.6.1. Find subset ═══ This brings up a dialog which allows you to search through the spells in the book (window) and bring up a new book (window) which contains the results of the search. Spells can be sorted on several fields, with the results OR'ed or AND'ed together depending on the buttons in the lower left corner of the dialog. Case sensitivity is also optional. Most of the fields just want you to enter text. The "level" field allows you to enter a number for the spell level, such as "5" to select all 5th level spells. It also allows you to enter things like ">5" or "<5" to select all spells higher or lower than a certain level. The "description" field allows you to enter several lines of text instead of only one. All lines entered are searched for in the spell descriptions, with the results OR'ed or AND'ed together according to the button pushed on the right. Searches go faster with case sensitivity enabled. Also, searches go faster if the program doesn't have to search through entire spell descriptions... limit using the other fields if possible. ═══ 3.6.2. Sort spellbook ═══ This sorts the spellbook, priest spells before mage spells, then in alphabetical order. ═══ 3.6.3. Rename spellbook ═══ This renames the spellbook... it does not change the actual name of the file the spellbook is saved in, only the name which appears at the top of the window. ═══ 3.7. Drag and Drop ═══ To copy spells between windows (spellbooks), drag them with the right mouse button. You can select several spells with the left button. Dragging can also be used to reposition spells within a window. ═══ 3.8. Looking at a spell ═══ To look at one spell in detail, double click on it. This brings up a window which is pretty self-explanatory. Use ALT-N or ALT-P as a shortcut to go to the next or previous spell in the book. You can copy text from spells onto the clipboard using the usual methods. You can even edit and change spells, although this doesn't work very well and will probably require you to go in and fix the saved text file with an editor. Any file you change and save is saved in the file splbook.chg. ═══ 4. Source information ═══ This is information on the source code. ═══ 4.1. Miscellaneous ═══ The source is written in C++ for the IBM C++ compiler; it will probably work with other compilers, although I haven't tested this. You need a C++ compiler and a resource compiler to compile the dialogs and menus. The makefile is compatible with GNU's make. You need an IPF compiler (IPFC) to compile the documentation. ═══ 4.2. general.cpp ═══ This file contains some generally useful functions which are called from the rest of the code. There are 3 error functions, "fatal", "error", and "warning", indicating various levels of severity. These are pretty useless in a PM program. There is a memory allocation function, which is pretty useless for a C++ program. (Just use "new" instead) There are 2 string functions to capitalize and uncapitalize a string... these are rarely found in C libraries, so they're included here. These actually get used in the code. ═══ 4.3. splbook.cpp, .hpp ═══ These files contain the C++ classes for handling spells and spellbooks, and contain no OS/2-specific or PM-specific information. Routines for reading and writing spells out of files are given. Note that the classes are set up to allow later addition of psionic disciplines as a subclass of the general spell. This is why the "magespell" class contains things like "school" and so forth that you would normally associate with all spells. If you want to change this program to change the format of how spells are read in and out (for example to use this program with another FRP system) this is the file to change. It is also the most portable to other systems besides OS/2. ═══ 4.4. spl.cpp, .hpp ═══ This is the main file that puts up menus and windows, allows direct manipulation and so forth... all functions are commented so experienced programmers should be able to find their way around. There is a class called "spellwindow" which is the window that shows a list of spells and their icons. This window uses a container to display the icons. A double-linked list of all active spellwindows is pointed to by the variable "first". There is also a class called "slwindow" (clever, huh?) which shows one individual spell when you double-click on it. This window uses a multi-line entry field (MLE) to display the spell. A linked list of these is pointed to by "firstspell". Naturally, this is really confusing and I'll try to clean things up in a later version of the program! ═══ 5. Planned enhancements ═══ These are things I plan to add to the program in the future, both in order to give it more functionality, and in order to learn more about PM programming myself. If you would like to help me out with any of these, please let me know what you're working on. Better error handling. On-line help from within the program. More views of the main container window... text view, details view, and large icon view should all be options. More ways to sort spellbooks. Allowing users to edit spells in a way that actually works. More drag and drop stuff... should allow you to drop a text file into a spell window and read it in. Also, should allow you to drag a spell onto the printer and print it. Drag and drop icon assignment would also be cool.