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!):

• Repetition - called at the moment of executing the programmed component (e.g. by choosing the Execute button or calling PLAY in a script). If this procedure is not defined, no action is taken and no error is reported.
  
  
• Edit - called only at the moment of choosing Editing mode on the programmed component pop-up menu and used, for example, to edit parameter files associated with the DLL. If this procedure is not defined, no action is taken and no error is reported. Note that the DLL can create only one parameter file within the knowledge system without calling allocation and registration procedures. This file has the same path and name as the DLL file; only its extension is PAR. All other files created by the DLL within the knowledge system should be properly registered with the system by means of procedures available from KSI.DLL (Knowledge System Interface) described later.
  
  
• Install - called only at the moment of importing the DLL file into the knowledge system. If this procedure is not defined, no action is taken and no error is reported. This is the best procedure to place a code creating and initializing the parameters file associated with the DLL.

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:

• MainWindow - handle of the main window in SuperMemo
  
  
• TopicWindow - handle of the element window in SuperMemo
  
  
• CompWindow - handle of the component window (the one hosting the Execute button)
  
  
• TopicRect - rectangle coordinates of the element window in SuperMemo
  
  
• ItemNo - number of the element hosting the programmed component
  
  
• grade - grade given or obtained in the course of a repetition (this is an output parameter used by the Repetition procedure)

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