fbdoc: wiki snapshot 2018-08-23

Author: jayrm

doc/manual/cache/CatPgMemory.wakka

@@ -28,7 +28,9 @@ Procedures that work with static and dynamic memory.
 	=={{fbdoc item="keyword" value="KeyPgSwap|SWAP"}}==
 		Exchange the contents of two variables.
 	=={{fbdoc item="keyword" value="KeyPgSadd|SADD"}}==
-		Returns the address for the data in a string variable.
+		Returns the address for the data in a zstring variable.
 >>::c::
+{{fbdoc item="see"}}
+	- [[CatPgOpMemory|Memory Operators]]
 
 {{fbdoc item="back" value="DocToc|Table of Contents"}}

doc/manual/cache/GlossaryIndex.wakka

@@ -124,7 +124,7 @@ Brief definitions and explanations for words and phrases used in the ""FreeBASIC
 	A source code statement (or statements) that allocates space for data or code.  For example, ##[[KeyPgSub|Sub]]## defines a procedure by allocating space for the program code it will contain.  Some statements can be both a declaration and a definition.  For example, ##[[KeyPgDim|Dim]]## both declares and defines a variable.
 
 **dereference**
-	The act of obtaining a value from memory at a given address. See ##[[KeyPgOpValueOf|Operator * (ValueOf)]]##, ##[[ProPgPointers|Pointers]]##.
+	The act of accessing (in read and in write) a variable stored at a given address. See ##[[KeyPgOpValueOf|Operator * (ValueOf)]]##, ##[[ProPgPointers|Pointers]]##.
 
 **descriptor**
 	Refers to the internal data structure used by the compiler and runtime library for managing variable length strings and arrays.

doc/manual/cache/KeyPgBinary.wakka

@@ -24,7 +24,7 @@ Specifies file or device to be opened for binary mode
 
 	##//filename//## must be a string expression resulting in a legal file name in the target OS, without wildcards. The file will be sought for in the present directory, unless a path is given.
 
-	##//Access_type//## By default ##**Binary**## mode allows to both read and write the file, unless an ##[[KeyPgAccess|Access]]## type is specified, it mus be one of: 
+	##//Access_type//## By default ##**Binary**## mode allows to both read and write the file, unless an ##[[KeyPgAccess|Access]]## type is specified, it must be one of: 
 		- ##**Read**## - the file is opened for input only
 		- ##**Write**## - the file is opened for output only
 		- ##**Read Write**## - the file is opened for input and output (the default)

doc/manual/cache/KeyPgByref.wakka

@@ -35,7 +35,7 @@ end
 %%
 
 {{fbdoc item="lang"}}
-	- In //[[CompilerOptlang|-lang fb]]// dialect, ##**Byval**## is the default parameter passing convention for all built-in types except ##[[KeyPgString|String]]## and user-defined ##[[KeyPgType|Type]]## which are passed ##[[KeyPgByref|Byref]]## by default.
+	- In //[[CompilerOptlang|-lang fb]]// dialect, ##[[KeyPgByval|Byval]]## is the default parameter passing convention for all built-in types except ##[[KeyPgString|String]]## and user-defined ##[[KeyPgType|Type]]## which are passed ##**Byref**## by default. The ##[[KeyPgZstring|Zstring]]## and ##[[KeyPgWstring|Wstring]]## built-in types are also passed ##**Byref**## by default, but passing ##[[KeyPgByval|Byval]]## is forbidden. Arrays are always passed ##**Byref**## and the use of the specifier ##**Byref**## or ##[[KeyPgByval|Byval]]## is forbidden.
 	- In //[[CompilerOptlang|-lang qb]]// and //[[CompilerOptlang|-lang fblite]]// dialects, ##**Byref**## is the default parameter passing convention.
 
 {{fbdoc item="diff"}}

doc/manual/cache/KeyPgByrefFunction.wakka

@@ -49,18 +49,22 @@ Function f1( ) ByRef As String
 End Function
 
 Function f2( ByRef _s As String ) ByRef As String
-   '' This variable-length string will be returned by reference, no copy will be created.
+   '' This variable-length string will transit by reference (input and output), no copy will be created.
    Function = _s
 End Function
 
 s = "abcd"
 Print s
 
-f1( ) &= "efgh"
+f1( ) = f1( ) & "efgh"
+Print s
+
+'' The enclosing parentheses are required here on the left-hand side.
+( f2( s ) ) = f2( s ) & "ijkl"
 Print s
 
-'' At time of writing, the enclosing parentheses are required here.
-( f2( s ) ) &= "ijkl"
+'' The enclosing parentheses are not required here on the left-hand side.
+f2( s ) => f2( s ) & "mnop"
 Print s
 %%
 {{fbdoc item="filename" value="examples/manual/procs/byref-result3.bas"}}%%(freebasic)

doc/manual/cache/KeyPgByval.wakka

@@ -39,8 +39,8 @@ End
 %%
 
 {{fbdoc item="lang"}}
-	- In the //[[CompilerOptlang|-lang fb]]// dialect, ##**Byval**## is the default parameter passing convention for all built-in types except ##[[KeyPgString|String]]## and user-defined ##[[KeyPgType|Type]]## which are passed ##[[KeyPgByref|Byref]]## by default.
-	- In //[[CompilerOptlang|-lang qb]]// and //[[CompilerOptlang|-lang fblite]]// dialects, ##**Byref**## is the default parameter passing convention.
+	- In the //[[CompilerOptlang|-lang fb]]// dialect, ##**Byval**## is the default parameter passing convention for all built-in types except ##[[KeyPgString|String]]## and user-defined ##[[KeyPgType|Type]]## which are passed ##[[KeyPgByref|Byref]]## by default. The ##[[KeyPgZstring|Zstring]]## and ##[[KeyPgWstring|Wstring]]## built-in types are also passed ##[[KeyPgByref|Byref]]## by default, but passing ##**Byval**## is forbidden. Arrays are always passed ##[[KeyPgByref|Byref]]## and the use of the specifier ##[[KeyPgByref|Byref]]## or ##**Byval**## is forbidden.
+	- In //[[CompilerOptlang|-lang qb]]// and //[[CompilerOptlang|-lang fblite]]// dialects, ##[[KeyPgByref|Byref]]## is the default parameter passing convention.
 
 {{fbdoc item="diff"}}
 	- QB only used ##**Byval**## in declarations to non-Basic subroutines

doc/manual/cache/KeyPgDraw.wakka

@@ -19,6 +19,8 @@ Statement for sequenced pixel plotting
 
 Commands to set the color, size and angle will take affect all subsequent ##**Draw**## operations.
 
+##**Draw**## respects the current clipping region as set by the ##[[KeyPgViewgraphics|View (Graphics)]]## statement, but its coordinates are not affected by the custom coordinates system.
+
 {{fbdoc item="ex"}}
 {{fbdoc item="filename" value="examples/manual/gfx/draw.bas"}}%%(freebasic)
 screen 13

doc/manual/cache/KeyPgFunctionPtr.wakka

@@ -21,6 +21,8 @@ Data type that stores a pointer to a ##[[KeyPgFunction|FUNCTION]]## procedure re
 	The procedure must match the same ##[[KeyPgFunction|Function]]## declaration as the declared ##[[KeyPgFunction|Function]]## pointer.
 
 	To call the subroutine assigned, use the ##//variable//## name as if it were a normal declared ##[[KeyPgFunction|Function]]##.
+	
+	One of the primary uses for procedure pointers is to create callback procedures. A callback procedure is a procedure created in the user program that is called by another procedure either from the user own code space or from an external library.
 
 {{fbdoc item="ex"}}
 {{fbdoc item="filename" value="examples/manual/datatype/funcptr.bas"}}%%(freebasic)
@@ -32,7 +34,64 @@ dim x as Function( x as string ) as string = procptr( ConcatSelf )
 
 print x( "Hello" )
 %%
-	 	
+{{fbdoc item="filename" value="examples/manual/datatype/funcptr2.bas"}}%%(freebasic)
+Function x2 (Byval i As Integer) As Integer
+  Return i * 2
+End Function
+
+Function x3 (Byval i As Integer) As Integer
+  Return i * 3
+End Function
+
+Function operation (Byval i As Integer, Byval op As Function (Byval As Integer) As Integer) As Integer
+  Return op(i)
+End Function
+
+Print operation(4, @x2)
+Print operation(4, @x3)
+%%
+{{fbdoc item="filename" value="examples/manual/datatype/funcptr3.bas"}}%%(freebasic)
+' Example of basic callback Function mechanism to implement a key pressed event:
+' (the user callback Function address cannot be modified while the event thread is running)
+'   - An asynchronous thread tests the keyboard in a loop, and calls a user callback Function each time a key is pressed.
+'   - The callback Function address is passed to the thread.
+'   - The callback Function prints the character of the key pressed,
+'       but if the key pressed is <escape> it orders the thread to finish by using the function return value.
+'   - As the user callback address is passed to the thread as argument, it cannot be modified while the thread is running.
+
+
+'' thread Sub definition
+  Sub threadInkey (Byval p As Any Ptr)
+	If p > 0 Then                                                '' test condition callback Function defined
+	  Dim As Function (Byref As String) As Integer callback = p  '' convert the any ptr to a callback Function pointer
+	  Do
+		Dim As String s = Inkey
+		If s <> "" Then                                          '' test condition key pressed
+		  If callback(s) Then                                    '' test condition to finish thread
+			Exit Do
+		  End If
+		End If
+		Sleep 50
+	  Loop
+	End If
+  End Sub
+
+'' user callback Function definition
+  Function printInkey (Byref s As String) As Integer
+	If Asc(s) = 27 Then                                        '' test condition key pressed = <escape>
+	  Print
+	  Return -1                                                '' order thread to finish
+	Else
+	  Print s;
+	  Return 0                                                 '' order thread to continue
+	End If
+  End Function
+
+'' user main code
+  Dim As Any Ptr p = Threadcreate(@threadInkey, @printInkey)   '' launch the thread, passing the callback Function address
+  Threadwait(p)                                                '' wait for the thread finish
+%%
+
 {{fbdoc item="diff"}}
 	- New to ""FreeBASIC""
 

doc/manual/cache/KeyPgReturn.wakka

@@ -11,8 +11,11 @@ Control flow statement to return from a procedure or ##[[KeyPgGosub|Gosub]]##.
 
 	Because ##[[KeyPgReturn|Return]]## could mean return-from-gosub or return-from-procedure, ##[[KeyPgOptiongosub|Option Gosub]]## and ##[[KeyPgOptionnogosub|Option Nogosub]]## can be used to enable and disable ##[[KeyPgGosub|Gosub]]## support.  When ##[[KeyPgGosub|Gosub]]## support is disabled, ##[[KeyPgReturn|Return]]## is then recognized as return-from-procedure.  When ##[[KeyPgGosub|Gosub]]## support is enabled, ##[[KeyPgReturn|Return]]## is then recognized as return-from-gosub.
 
-	##**Return**## (from procedure) is used inside a procedure to exit the procedure possibly with a return value. A ##[[KeyPgSub|Sub]]## cannot specify a return return value.  In a ##[[KeyPgFunction|Function]]##, ##**Return**## must specify its return value.  ##**Return** //expression//## is roughly equivalent to the ##Function = //expression// : [[KeyPgExit|Exit]] Function## idiom.
-	
+	##**Return**## (from procedure) is used inside a procedure to exit the procedure possibly with a return value:
+		- A ##[[KeyPgSub|Sub]]## cannot specify a return return value. ##**Return**## is roughly equivalent to the ##[[KeyPgExit|Exit]] Sub## idiom.
+		- In a ##[[KeyPgFunction|Function]]##, ##**Return**## must specify its return value.  ##**Return** //expression//## is roughly equivalent to the ##Function = //expression// : [[KeyPgExit|Exit]] Function## idiom.
+
+		
 	##**Return**## (from gosub) is used to return control back to the statement immediately following a previous ##[[KeyPgGosub|Gosub]]## call. When used in combination with ##[[KeyPgGosub|Gosub]]##, no return value can be specified.  If the optional ##//label//## is specified, execution continues at the specified label.  If no ##[[KeyPgGosub|Gosub]]## was made, a runtime error is generated, and execution continues immediately after ##**Return**##.
 
 	A ##[[KeyPgGosub|Gosub]]## should always have a matching ##**Return**## statement.  However, if ##**Return**## (from gosub) is used where no ##[[KeyPgGosub|Gosub]]## was made, a run-time error is generated.

doc/manual/cache/KeyPgScreengraphics.wakka

@@ -59,6 +59,10 @@ __##flags## details:__
 
 __Other details__
 	While in windowed mode, clicking on the window close button will add a keypress of ##([[KeyPgChr|Chr]](255) & "k")## to the ##[[KeyPgInkey|Inkey]]## buffer.  Clicking on the Maximize window button will switch to fullscreen mode if possible.  A successful ##**Screen**## call sets currently visible and working pages both to page number ##0##, resets the palette to the specified mode one (see [[GfxDefPalettes|Default palettes]]), resets the clipping region to the size of the screen, disables custom coordinates mappings, moves the graphics cursor to the center of the screen, moves the text cursor to the top-left corner of the screen (but never visible on any graphics screen), and sets foreground and background colors to bright white and black respectively.
+	
+__Note on using ##Screen 0##__
+	##Screen 0## closes any graphics window, but also clears the console window if it exists.
+	##Screen 0, , , SCREEN_EXIT## (with ##SCREEN_EXIT=&h80000000##) also closes any graphics window, but does not clear the console window if it exists (previous text is preserved).
 
 {{fbdoc item="ex"}}
 {{fbdoc item="filename" value="examples/manual/gfx/screen.bas"}}%%(freebasic)