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:

  1. Create a programmed component by dragging it from the edit tab at the top of the element window (a button Execute should appear on the screen)

  2. From the created component pop-up menu choose Import file

  3. In the file browser dialog, choose the EXE file to import and click OK

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 component’s 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:

TRepData=record

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;

end;

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:

  1. Call GetNewFilename from KSI.DLL to obtain a new legal filename within the knowledge system (the filename does not have an extension).

  2. Copy the sound file to the filename obtained in the previous step (do not forget to add an appropriate extension)

  3. Register the sound file by calling RegisterSound. Provide the new sound file name used in the previous step as filename. Use any name as itemname, e.g. ‘My sound’ (this name will later appear in the sound registry).

To write the simplest DLL for SuperMemo 8 that displays a ‘Hello world’ dialog, do as follows:

  1. Implement and publish an empty Repetition(RepDat:pointer) procedure in your DLL.

  2. Display ‘Hello world’ dialog within the Repetition procedure.

  3. Ignore RepDat parameters.

  4. Ignore Install and Edit procedures, i.e. do not bother writing anything.

  5. Compile your DLL and import it to any knowledge system as described earlier.

  6. Click the Execute button. ‘Hello world’ should appear on the screen