Differences

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

--- using_20callback_20functions [2018/03/31 13:19] – external edit 127.0.0.1
+++ using_20callback_20functions [2024/01/05 00:21] (current) – external edit 127.0.0.1
@@ Line 1: / Line 1: @@
 =====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"
-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%
-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%)
-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
         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%)
-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%)
+</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:\\ \\
 ===== 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"
@@ Line 31: / Line 57: @@
         index% += 1
         IF index% <= 999 THEN = 1 ELSE = 0
+</code>
 ===== 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"
@@ Line 51: / Line 81: @@
         index% += 1
         IF index% <= 999 THEN = 1 ELSE = 0
+</code>
 ===== 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"
@@ Line 70: / Line 104: @@
         index% += 1
         IF index% <= 99 THEN = 1 ELSE = 0
+</code>