Writing EXE and DLL files for SuperMemo 8
Piotr Metzler, Piotr Wozniak, February 1996
To add an EXE component to an element in SuperMemo 8, do the following:
The above sequence should make sure that you can execute the EXE file by pressing the Execute button. You can change the name of the button by choosing Button text on the components pop-up menu. For example by typing &Calculator and importing CALC.EXE from Windows, you can allow the user to execute the Windows calculator by choosing the Calculator button. Note that in this, a separate copy of the EXE file will be created within the knowledge system and deleting the calculator in Windows will not affect the behavior of the system.
To add a DLL component to an element in SuperMemo 8, act as with EXE components. Note that the DLL must be written specifically for SuperMemo 8, i.e. it cannot be just any DLL. The only difference here is that DLLs cannot be executed independently. Instead, SuperMemo 8 will call specific procedures coded in the DLL such as: Repetition, Edit, or Install.
To write a DLL that will work with SuperMemo 8, you should implement one or more of the following procedures (all procedures are optional!):
All the above procedures use only one parameter: pointer to a record called RepDat. This record can be used to pass parameters to and from the DLL. The definition of RepDat is as follows:
MainWindow:HWnd; (2 bytes)
TopicWindow:HWnd; (2 bytes)
CompWindow:HWnd; (2 bytes)
TopicRect:TRect; (4 bytes)
ItemNo:integer; (4 bytes)
grade:byte; (1 bytes)
reserved:array[0..1000] of byte;
The interpretation of the fields is as follows:
The specification of TRepData is open so that new fields can be added in the future as needed. In particular all learning parameters and metrics can be obtained from TRepData (see updates to this document in the future). The open specification also means that you, DLL developer, can also postulate new fields that are needed in your implementation. Those fields can be filled out in future specifications.
Most of the fields of TRepData are set by SuperMemo upon executing relevant DLL procedures. The author of the DLL does not have to make use of those fields, nor does he have to set output fields! No errors will result.
Here are some useful procedures available from KSI.DLL that can be used in communicating with SuperMemo 8 while executing a DLL associated with a programmed component:
procedure PlayComponent(ItemNo:longint;CompNo:byte); export;
Used to play or execute the component associated with the element ItemNo and component CompNo (both can be viewed with the button displaying component number tags on the Edit tab in the element window). The component can be sound, video, script or a programmed component.
procedure GetNewFilename(filename:PChar); export;
Used to obtain new legal filename within the knowledge system (without extension!)
procedure RegisterSound(filename,itemname:PChar;var Posit:longint); export;
Used to register a wave or midi file used by the DLL. Filename is the filename obtained from GetNewFilename with a proper extension added. Itemname is any name under which the registered sound will appear in the sound registry. Posit is the newly allocated registry position for the registered sound file. Use Posit with GetSoundFilenameFromPosition if you want to make sure you use the updated sound file registered at that position (the user might wish to change the sound registered by your DLL). The var parameters indicates that Posit is an output parameter here
procedure GetSoundFilenameFromPosition(Posit:longint;filename:PChar); export;
Used to obtain the name of the file registered under a given position in the sound registry. Posit is the position. Filename is the returned filename
procedure RegisterImage(filename,itemname:PChar;var Posit:longint); export;
Analogous to RegisterSound.
procedure GetImageFilenameFromPosition(Posit:longint;filename:PChar); export;
Analogous to RegisterImage.
For example, to add a new sound file to the knowledge system do the following:
To write the simplest DLL for SuperMemo 8 that displays a Hello world dialog, do as follows: