Giga Games 2/Giga_Games_2_CD-ROM_Walnut_Creek_April_1995.iso/os2/spl15.zip/spl.hlp

OS/2 Help File | 1994-04-18 | 20KB | 549 lines

ΓòÉΓòÉΓòÉ 1. Introduction and Copyright ΓòÉΓòÉΓòÉ

                            Spellbook Control Program
                                     spl.exe

                                   Version 1.5

                                     4/16/94

                  Copyright (C) 1993, 1994 John-Marc Chandonia

For suggested enhancements and bug reports, please mail
[e-mail] 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 ΓòÉΓòÉΓòÉ

Version 1.5:

Spell searching, sorting, loading, and saving are now multithreaded, allowing
you to work on other books or adjust the window while the program is working.

Multiple views of the spellbook are supported.

Large or small icons are supported.

On-line help is available by pressing F1 or using the help menu/buttons.

Spellbook position, view, icon size, and details bar position are saved in
EA's/INI files.

Spell descriptions are loaded in as required, using less memory.

Spells in the master list are saved in a "quick reference" file for faster
loading.

Version 1.0:

This is the first initial release of the program.

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.

Topics include:

  Installation
  Master spell list
  Icon mapping
  Spellbook window
  Spell window


ΓòÉΓòÉΓòÉ 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.

Also, look at the file splicon.res which contains a mapping of spell spheres
and schools to icons.

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. Spellbook window ΓòÉΓòÉΓòÉ

This is a window which represents a spellbook; it contains icons representing
spells in the book.  This window has can be viewed several ways, representing
spells as single icons, or more or less detailed views.

Several menus can be activated from this window:

  File Menu
  Spell Menu
  Book Menu
  Views Menu
  Help Menu

Also, pop-up context menus are available, either by clicking on the background
of the spellbook, or on individual spells.  The default OS/2 method for
bringing up these menus uses the right mouse button:

  Spell Context Menu
  Spellbook Context Menu


ΓòÉΓòÉΓòÉ 3.4.1. File menu ΓòÉΓòÉΓòÉ

Options on this menu include:

  New Spellbook
  Load Spellbook
  Load Full Spellbook
  Save Spellbook
  Save Full Spellbook
  Close Spellbook
  Quit Program


ΓòÉΓòÉΓòÉ 3.4.1.1. New Spellbook ΓòÉΓòÉΓòÉ

This will create a new (empty) spellbook window that you can drag and drop
spells into.


ΓòÉΓòÉΓòÉ 3.4.1.2. Load Spellbook ΓòÉΓòÉΓòÉ

This will load in a list of spells from disk, looking the spells up in the
master list to get their full descriptions.  Spells listed in the spellbook but
not found in the master list will be ignored.


ΓòÉΓòÉΓòÉ 3.4.1.3. Load Full Spellbook ΓòÉΓòÉΓòÉ

This will load in a complete spellbook (including names and descriptions) from
disk.  Spells do not have to be in the master list to be loaded successfully,
although you should add them to the master list so that the full spellbook
doesn't have to be loaded & saved.


ΓòÉΓòÉΓòÉ 3.4.1.4. Save Spellbook ΓòÉΓòÉΓòÉ

This will save the names of spells in the current spellbook to disk.


ΓòÉΓòÉΓòÉ 3.4.1.5. Save Full Spellbook ΓòÉΓòÉΓòÉ

This will save the complete spellbook (names and descriptions) to disk.  If the
spells are in the master list, you might want to just save the names instead.


ΓòÉΓòÉΓòÉ 3.4.1.6. Close Spellbook ΓòÉΓòÉΓòÉ

This will close the current spellbook.  If it has been changed but not saved,
you will be asked if you want to save it first. This option is equivalent to
double-clicking on the box in the upper left corner of the book, or selecting
"Window -> Close"

Closing the last spellbook will end the program.  You can close the master
spell index if you want (once another window is open), as the spells themselves
are still in memory.


ΓòÉΓòÉΓòÉ 3.4.1.7. Quit Program ΓòÉΓòÉΓòÉ

This will close all open spellbooks and exit the program.  If any spellbooks
have been changed but not saved, a window will pop up asking if you really want
to do this or not.


ΓòÉΓòÉΓòÉ 3.4.2. Spell menu ΓòÉΓòÉΓòÉ

These options are only available if the book is writeable (i.e. not the master
spell list).

This menu includes:

  Add New Spell
  Delete Spell


ΓòÉΓòÉΓòÉ 3.4.2.1. Add New Spell ΓòÉΓòÉΓòÉ

This will add a new spell to the book; it isn't really useful in this version.


ΓòÉΓòÉΓòÉ 3.4.2.2. Delete Spell ΓòÉΓòÉΓòÉ

This will remove selected spells from the book.


ΓòÉΓòÉΓòÉ 3.4.3. Book menu ΓòÉΓòÉΓòÉ

This menu includes:

  Find Subset
  Sort Spellbook
  Rename Spellbook


ΓòÉΓòÉΓòÉ 3.4.3.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.

Searching is multithreaded, so you can work on other books while the search is
in progress.


ΓòÉΓòÉΓòÉ 3.4.3.2. Sort spellbook ΓòÉΓòÉΓòÉ

This sorts the spellbook, priest spells before mage spells, then in
alphabetical order.

More sorting options are planned for later.

Sorting is multithreaded, although usually quick.


ΓòÉΓòÉΓòÉ 3.4.3.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.4.4. Views Menu ΓòÉΓòÉΓòÉ

The Views menu includes:

  Icon View
  Name View
  Text View
  Details View
  Small Icons
  Large Icons

Spellbooks remember which view they are in, whether to use large or small
icons, and the bar position in details view.  This is stored in extended
attributes for saved spellbooks, or in the INI file for the master spell window
and new windows.


ΓòÉΓòÉΓòÉ 3.4.4.1. Icon View ΓòÉΓòÉΓòÉ

This shows each spell as an icon with the name of the spell underneath.


ΓòÉΓòÉΓòÉ 3.4.4.2. Name View ΓòÉΓòÉΓòÉ

This shows each spell on a single line with the icon to the left and the name
to the right.


ΓòÉΓòÉΓòÉ 3.4.4.3. Text View ΓòÉΓòÉΓòÉ

This just shows the spell names, one per line.


ΓòÉΓòÉΓòÉ 3.4.4.4. Details View ΓòÉΓòÉΓòÉ

This shows the spell and some other relevant details such as spell level, and
the school or sphere of the spell.


ΓòÉΓòÉΓòÉ 3.4.4.5. Small Icons ΓòÉΓòÉΓòÉ

This uses small icons in all views that show icons; the icons lose detail, but
allow more spells on the screen.


ΓòÉΓòÉΓòÉ 3.4.4.6. Large Icons ΓòÉΓòÉΓòÉ

This tells the book to use large icons to represent spells; these are as
detailed as other icons in your system.


ΓòÉΓòÉΓòÉ 3.4.5. Help Menu ΓòÉΓòÉΓòÉ

This includes:

  Help Index
  General Help
  Using Help
  About


ΓòÉΓòÉΓòÉ 3.4.5.1. Help Index ΓòÉΓòÉΓòÉ

This will display an index of help topics from within the program.


ΓòÉΓòÉΓòÉ 3.4.5.2. General Help ΓòÉΓòÉΓòÉ

This will bring up general help on using this program, like pushing F1.


ΓòÉΓòÉΓòÉ 3.4.5.3. Using Help ΓòÉΓòÉΓòÉ

This will bring up help on how OS/2's help system works.


ΓòÉΓòÉΓòÉ 3.4.5.4. About ΓòÉΓòÉΓòÉ

This will briefly describe the program.


ΓòÉΓòÉΓòÉ 3.4.6. Spell Context Menu ΓòÉΓòÉΓòÉ

This menu will pop up if you right-click on a spell in the spellbook.

The menu includes:

  Show spell
  Delete spell


ΓòÉΓòÉΓòÉ 3.4.7. Spellbook Context Menu ΓòÉΓòÉΓòÉ

This menu will pop up if you right-click in the spellbook window somewhere in
the blank (empty) part of the window.

The menu includes the options found in the Views and Book menus.


ΓòÉΓòÉΓòÉ 3.4.8. 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, if the window is not read-only.


ΓòÉΓòÉΓòÉ 3.5. Spell Window ΓòÉΓòÉΓòÉ

To bring up a spell in detail, double click on it, or select "show spell" from
the context menu.  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 ΓòÉΓòÉΓòÉ

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.

Click one of the following for more information:

  general.cpp
  splbook.cpp
  spl.cpp
  bookwin.cpp
  splobj.cpp
  splwin.cpp
  spldlgs.cpp
  splhelp.cpp
  ea.cpp


ΓòÉΓòÉΓòÉ 4.1. general.cpp ΓòÉΓòÉΓòÉ

This file contains some generally useful functions which are called from the
rest of the code.  None are PM specific.

fatal, error, warning - these are 3 error functions indicating various levels
of severity.  These are pretty useless in a PM program.

chkcalloc - this is a memory allocation function, which is pretty useless for a
C++ program.  (Just use "new" instead)

upstr, lowstr - these 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.

fgets_no_cr - this works just like fgets(), but removes the \n at the end of
the string.


ΓòÉΓòÉΓòÉ 4.2. splbook.cpp ΓòÉΓòÉΓòÉ

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.3. spl.cpp ΓòÉΓòÉΓòÉ

This file contains some initialization and general use (PM) functions which get
called from classes.

Routines to load in the icon file, look up an icon for a given spell, load in
the INI file, enable/disable or check/uncheck menu items, and printf() to a
window's title bar are in here.


ΓòÉΓòÉΓòÉ 4.4. bookwin.cpp ΓòÉΓòÉΓòÉ

bookwindow is a class which refers to the spellbook windows which appear on the
screen.  The class definition appears in bookwin.hpp.

Bookwindow functions which are handled in the main thread are included in
bookwin.cpp.


ΓòÉΓòÉΓòÉ 4.5. splobj.cpp ΓòÉΓòÉΓòÉ

The object thread for bookwindows is handled here.  Both the object window
function and the main() thread which creates it are defined here.

Bookwindow functions that are handled in the object thread are in this file.


ΓòÉΓòÉΓòÉ 4.6. splwin.cpp ΓòÉΓòÉΓòÉ

spellwindow is a class which refers to the spell windows which show the
detailed descriptions of spells.  The class definition appears in splwin.hpp.

Spell windows are not multithreaded; all the code required to handle them is in
splwin.cpp.


ΓòÉΓòÉΓòÉ 4.7. spldlgs.cpp ΓòÉΓòÉΓòÉ

These files contain all the code required for processing the dialog boxes used
in the program.


ΓòÉΓòÉΓòÉ 4.8. splhelp.cpp ΓòÉΓòÉΓòÉ

These files contain code for on-line help.


ΓòÉΓòÉΓòÉ 4.9. ea.cpp ΓòÉΓòÉΓòÉ

These files contain OS/2 specific file handling code.

query_last_write is a function for finding out the last time a file has been
written to.

getEA is a function for reading an given EA out of a file. It may contain bugs;
I have little coherent information on OS/2's EAs.

putEA is a function for writing data to a named EA of a file.  It works, but
could stand to be debugged also.


ΓòÉΓòÉΓòÉ 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.

Fixing up the on-line help some more.

More ways to sort spellbooks.

More fields (user-selectable as to which ones) in details view.

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.