User Tools

Site Tools


using_20callback_20functions

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

using_20callback_20functions [2018/03/31 13:19]
127.0.0.1 external edit
using_20callback_20functions [2018/04/14 17:17] (current)
richardrussell Added syntax highlighting
Line 1: Line 1:
 =====Using callback functions===== =====Using callback functions=====
  
-//by Richard Russell, December 2008//\\ \\  A few **Windows API** functions require the use of a **callback** routine, that is a function which you provide that is called by Windows during execution of the API call. The normal [[http://​www.bbcbasic.co.uk/​bbcwin/​manual/​bbcwin7.html#​sys|SYS]] statement does not provide this capability, but it is available by means of the **CALLBACK** library provided with //BBC BASIC for Windows//​.\\ \\  The library should be installed, as usual, by including this code at the beginning of your program, for example in an initialisation routine:\\ +//by Richard Russell, December 2008//\\ \\  A few **Windows API** functions require the use of a **callback** routine, that is a function which you provide that is called by Windows during execution of the API call. The normal [[http://​www.bbcbasic.co.uk/​bbcwin/​manual/​bbcwin7.html#​sys|SYS]] statement does not provide this capability, but it is available by means of the **CALLBACK** library provided with //BBC BASIC for Windows//​.\\ \\  The library should be installed, as usual, by including this code at the beginning of your program, for example in an initialisation routine: 
 + 
 +<code bb4w>
         INSTALL @lib$+"​CALLBACK"​         INSTALL @lib$+"​CALLBACK"​
-To use the library, replace the conventional method of calling a Windows API function:\\ +</​code>​ 
 + 
 +To use the library, replace the conventional method of calling a Windows API function: 
 + 
 +<code bb4w>
         SYS "​FunctionName",​ parameters TO result%         SYS "​FunctionName",​ parameters TO result%
-with the following code (requires CALLBACK.BBC version 3.4 or later):\\ +</​code>​ 
 + 
 +with the following code (requires CALLBACK.BBC version 3.4 or later): 
 + 
 +<code bb4w>
         SYS FN_syscalls("​FunctionName"​),​ parameters TO !FN_systo(result%)         SYS FN_syscalls("​FunctionName"​),​ parameters TO !FN_systo(result%)
-Note particularly the exclamation mark before **FN_systo**!\\ \\  When using the CALLBACK library you must be careful how you pass **string** parameters. In the event that one or more of the parameters needs to be a string, add a NUL-termination (requires //BBC BASIC for Windows// version 5.93a or later):\\ +</​code>​ 
 + 
 +Note particularly the exclamation mark before **FN_systo**!\\ \\  When using the CALLBACK library you must be careful how you pass **string** parameters. In the event that one or more of the parameters needs to be a string, add a NUL-termination (requires //BBC BASIC for Windows// version 5.93a or later): 
 + 
 +<code bb4w>
         parameter$ += CHR$(0) : REM Add NUL termination         parameter$ += CHR$(0) : REM Add NUL termination
         SYS FN_syscalls("​FunctionName"​),​ parameter$ TO !FN_systo(result%)         SYS FN_syscalls("​FunctionName"​),​ parameter$ TO !FN_systo(result%)
-In the event that you need to call the API function by //address// rather than by //name// use the following code:\\ +</​code>​ 
 + 
 +In the event that you need to call the API function by //address// rather than by //name// use the following code: 
 + 
 +<code bb4w>
         SYS FN_syscalln(FunctionAddress%),​ parameters TO !FN_systo(result%)         SYS FN_syscalln(FunctionAddress%),​ parameters TO !FN_systo(result%)
-You **must** include the TO clause even if you don't need the value returned by the API function. In that case simply assign the value to a dummy variable.\\ \\  The callback routine (which will sometimes be specified as one of the parameters) should be entered as:\\ +</​code>​ 
 + 
 +You **must** include the TO clause even if you don't need the value returned by the API function. In that case simply assign the value to a dummy variable.\\ \\  The callback routine (which will sometimes be specified as one of the parameters) should be entered as: 
 + 
 +<code bb4w>
         FN_callback(FNfunctionname(),​ npar%)         FN_callback(FNfunctionname(),​ npar%)
 +</​code>​
 +
 Here **FNfunctionname** is the name of the callback function in your program and **npar%** is the number of parameters it takes (this will be specified in the description of the API function).\\ \\  You should ensure that your callback function executes as quickly as possible; ideally it should not perform any input or output.\\ \\  The use of this facility is probably best illustrated by means of a few examples:\\ \\  Here **FNfunctionname** is the name of the callback function in your program and **npar%** is the number of parameters it takes (this will be specified in the description of the API function).\\ \\  You should ensure that your callback function executes as quickly as possible; ideally it should not perform any input or output.\\ \\  The use of this facility is probably best illustrated by means of a few examples:\\ \\ 
 ===== Enumerating windows ===== ===== Enumerating windows =====
-\\  The following program will count the number of windows and store their handles in an array:\\ +\\  The following program will count the number of windows and store their handles in an array: 
 + 
 +<code bb4w>
         INSTALL @lib$+"​CALLBACK"​         INSTALL @lib$+"​CALLBACK"​
  
Line 31: Line 57:
         index% += 1         index% += 1
         IF index% <= 999 THEN = 1 ELSE = 0         IF index% <= 999 THEN = 1 ELSE = 0
 +</​code>​
 +
 ===== Enumerating fonts ===== ===== Enumerating fonts =====
-\\  The following program will count the number of fonts and store their names in an array:\\ +\\  The following program will count the number of fonts and store their names in an array: 
 + 
 +<code bb4w>
         INSTALL @lib$+"​CALLBACK"​         INSTALL @lib$+"​CALLBACK"​
  
Line 51: Line 81:
         index% += 1         index% += 1
         IF index% <= 999 THEN = 1 ELSE = 0         IF index% <= 999 THEN = 1 ELSE = 0
 +</​code>​
 +
 ===== Enumerating date formats ===== ===== Enumerating date formats =====
-\\  The following program will count the number of available date formats and store them in a string array:\\ +\\  The following program will count the number of available date formats and store them in a string array: 
 + 
 +<code bb4w>
         INSTALL @lib$+"​CALLBACK"​         INSTALL @lib$+"​CALLBACK"​
  
Line 70: Line 104:
         index% += 1         index% += 1
         IF index% <= 99 THEN = 1 ELSE = 0         IF index% <= 99 THEN = 1 ELSE = 0
 +</​code>​
using_20callback_20functions.txt · Last modified: 2018/04/14 17:17 by richardrussell